@rexezuge/tooling 0.0.0-stage → 1.0.0

package/dist/scripts/check-god-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-god-files.js","sourceRoot":"","sources":["../../src/scripts/check-god-files.ts"],"names":[],"mappings":"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"}

package/dist/scripts/ensure-spa-shell-stub.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=ensure-spa-shell-stub.d.ts.map

package/dist/scripts/ensure-spa-shell-stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-spa-shell-stub.d.ts","sourceRoot":"","sources":["../../src/scripts/ensure-spa-shell-stub.ts"],"names":[],"mappings":""}

package/dist/scripts/ensure-spa-shell-stub.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env tsx
+/**
+ * Write a placeholder `apps/api/src/generated/spa-shell.ts` when it is absent.
+ *
+ * Provenance: Durable-DAV's `scripts/ensure-spa-shell-stub.mjs` and Edge-Sonic's
+ * `scripts/build/ensure-spa-shell-stub.ts`. The rule lives in `spa-shell.ts`; this
+ * is the entrypoint that runs it from `postinstall`.
+ *
+ * `pnpm install` runs this before `typegen` so the API worker typechecks in a
+ * fresh clone, where the real file has not been produced by the Vite build yet.
+ * It exits having done nothing when the file already exists, so a real build
+ * output is never overwritten — overwriting would erase the last build with a
+ * stub on the next install. The file is gitignored.
+ *
+ * Usage, from the repo root (typically wired as `postinstall`):
+ *
+ * ```bash
+ * pnpm exec tsx scripts/ensure-spa-shell-stub.ts [repo-root]
+ * ```
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensureSpaShellStub } from './spa-shell';
+const REPOSITORY_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const root = process.argv[2] === undefined ? REPOSITORY_ROOT : path.resolve(process.argv[2]);
+const result = ensureSpaShellStub({ root });
+console.log(result.created
+    ? `ensure-spa-shell-stub: created stub at ${result.path}`
+    : `ensure-spa-shell-stub: ${result.path} already present, left untouched`);
+//# sourceMappingURL=ensure-spa-shell-stub.js.map

package/dist/scripts/ensure-spa-shell-stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-spa-shell-stub.js","sourceRoot":"","sources":["../../src/scripts/ensure-spa-shell-stub.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AACzF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7F,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;AAE5C,OAAO,CAAC,GAAG,CACT,MAAM,CAAC,OAAO;IACZ,CAAC,CAAC,0CAA0C,MAAM,CAAC,IAAI,EAAE;IACzD,CAAC,CAAC,0BAA0B,MAAM,CAAC,IAAI,kCAAkC,CAC5E,CAAC"}

package/dist/scripts/init-secrets.d.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env tsx
+/**
+ * Create the Secrets Store entries declared in `wrangler.jsonc`, generating a fresh
+ * value for each one that does not exist yet.
+ *
+ * Provenance: Edge-Sonic's `scripts/deploy/init-secrets.ts` and Durable-DAV's
+ * `scripts/init-secrets.ts`, converged. Both record the same two defects that hid
+ * a broken deploy for a whole release, and both fixes are carried over.
+ *
+ * ### Why this script exists at all
+ *
+ * A `secrets_store_secrets` binding fails the deploy unless the named secret
+ * already exists inside the named store. Nothing creates it: Cloudflare will not
+ * generate a value, and the template cannot carry one. So this script is the only
+ * thing standing between a fresh account and a deploy that cannot succeed.
+ *
+ * ### The two defects that hid a broken deploy
+ *
+ * **The generator list was stale.** Durable-DAV's copy carried an allowlist of
+ * exact names from the repository it was inherited from, all deleted when the repo
+ * was renamed, so the very first iteration threw `Unknown secret` and never created
+ * anything. So the rule here is the secret's **name shape**, not a list of names:
+ * `*-encryption-key` gets a generated AES-GCM key and `*-signing-secret` gets 32
+ * random bytes. Adding a secret to the template is then a one-line change needing
+ * no matching edit here, which is the property the exact-name list did not have.
+ *
+ * **The throw was swallowed.** The original ended in `main().catch(console.error)`.
+ * `console.error` returns `undefined` and never sets an exit status, so the process
+ * exited **0** and CI marked the step green — the failure only surfaced one step
+ * later, as an unexplainable `wrangler deploy` failure. Hence: the whole plan is
+ * validated **before** any Cloudflare call, and a rejection reaches the runner as
+ * a non-zero exit with a workflow annotation.
+ *
+ * ### Create-if-absent is a correctness property, not laziness
+ *
+ * An existing secret is left untouched. A replication encryption key seals every
+ * remote target's credential; regenerating it on a redeploy would strand them all
+ * as undecryptable. Rotation has to be a deliberate act with a re-encrypt path,
+ * not a side effect of deploying.
+ *
+ * Requires a materialized `wrangler.jsonc` — run
+ * `scripts/prepare-wrangler-config.ts` first. Fails rather than skipping when the
+ * config is missing, because a step reporting "Secret initialization complete"
+ * having created nothing is worse than a named error.
+ */
+import { type WranglerConfig } from './wrangler-config/types';
+/** Whether this script can produce a value for `secretName`. */
+export declare function canProvisionSecret(secretName: string): boolean;
+/** One secret to create, as the plan names it. */
+interface PlannedSecret {
+    storeId: string;
+    secretName: string;
+}
+/**
+ * Turn the config's bindings into a validated work list.
+ *
+ * Every entry is checked *before* the first Cloudflare call, so an
+ * unprovisionable secret fails the step in milliseconds instead of after some other
+ * secret has already been created.
+ */
+export declare function planSecrets(config: WranglerConfig): PlannedSecret[];
+export {};
+//# sourceMappingURL=init-secrets.d.ts.map

package/dist/scripts/init-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-secrets.d.ts","sourceRoot":"","sources":["../../src/scripts/init-secrets.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAOH,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAqD3E,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAO9D;AAwCD,kDAAkD;AAClD,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,EAAE,CAkBnE"}

package/dist/scripts/init-secrets.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env tsx
+/**
+ * Create the Secrets Store entries declared in `wrangler.jsonc`, generating a fresh
+ * value for each one that does not exist yet.
+ *
+ * Provenance: Edge-Sonic's `scripts/deploy/init-secrets.ts` and Durable-DAV's
+ * `scripts/init-secrets.ts`, converged. Both record the same two defects that hid
+ * a broken deploy for a whole release, and both fixes are carried over.
+ *
+ * ### Why this script exists at all
+ *
+ * A `secrets_store_secrets` binding fails the deploy unless the named secret
+ * already exists inside the named store. Nothing creates it: Cloudflare will not
+ * generate a value, and the template cannot carry one. So this script is the only
+ * thing standing between a fresh account and a deploy that cannot succeed.
+ *
+ * ### The two defects that hid a broken deploy
+ *
+ * **The generator list was stale.** Durable-DAV's copy carried an allowlist of
+ * exact names from the repository it was inherited from, all deleted when the repo
+ * was renamed, so the very first iteration threw `Unknown secret` and never created
+ * anything. So the rule here is the secret's **name shape**, not a list of names:
+ * `*-encryption-key` gets a generated AES-GCM key and `*-signing-secret` gets 32
+ * random bytes. Adding a secret to the template is then a one-line change needing
+ * no matching edit here, which is the property the exact-name list did not have.
+ *
+ * **The throw was swallowed.** The original ended in `main().catch(console.error)`.
+ * `console.error` returns `undefined` and never sets an exit status, so the process
+ * exited **0** and CI marked the step green — the failure only surfaced one step
+ * later, as an unexplainable `wrangler deploy` failure. Hence: the whole plan is
+ * validated **before** any Cloudflare call, and a rejection reaches the runner as
+ * a non-zero exit with a workflow annotation.
+ *
+ * ### Create-if-absent is a correctness property, not laziness
+ *
+ * An existing secret is left untouched. A replication encryption key seals every
+ * remote target's credential; regenerating it on a redeploy would strand them all
+ * as undecryptable. Rotation has to be a deliberate act with a re-encrypt path,
+ * not a side effect of deploying.
+ *
+ * Requires a materialized `wrangler.jsonc` — run
+ * `scripts/prepare-wrangler-config.ts` first. Fails rather than skipping when the
+ * config is missing, because a step reporting "Secret initialization complete"
+ * having created nothing is worse than a named error.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { parse } from 'jsonc-parser';
+import { fail } from './lib/github-actions';
+import { isEmptySecretsStoreListing, parseWranglerNames } from './lib/wrangler-table';
+import { CONFIG_PATH } from './wrangler-config/types';
+/**
+ * The secret names the AES-GCM key generator produces, matched by **shape**.
+ *
+ * Keyed on the suffix because the alternative is the exact-name map that went
+ * stale. See the header: a template naming `*-encryption-key` is then a one-line
+ * change with no matching edit here, and a new secret breaks the deploy loudly
+ * instead of silently.
+ */
+const ENCRYPTION_KEY_SUFFIX = '-encryption-key';
+/** The secret names the random signing secret generator produces. */
+const SIGNING_SECRET_SUFFIX = '-signing-secret';
+/** A 256-bit AES-GCM key, base64-encoded — the shape the worker's crypto layer accepts. */
+async function generateAESGCMKey() {
+    const key = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+    const exported = await crypto.subtle.exportKey('raw', key);
+    // Chunked rather than spread: `String.fromCharCode(...bytes)` passes 32 arguments,
+    // which is fine today and is a stack overflow the day the key is longer.
+    let binary = '';
+    for (const byte of new Uint8Array(exported)) {
+        binary += String.fromCodePoint(byte);
+    }
+    return btoa(binary);
+}
+/** A 256-bit random signing secret for internal self-calls, hex-encoded. */
+function generateSigningSecret() {
+    let hex = '';
+    for (const byte of crypto.getRandomValues(new Uint8Array(32))) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return Promise.resolve(hex);
+}
+/**
+ * The generator for a secret name, chosen by the name's shape.
+ *
+ * A name matching neither is still refused rather than given a guess: the generator
+ * is not the only thing that has to be right, and an unusable value that looks
+ * provisioned is worse than a failure.
+ */
+function generatorFor(secretName) {
+    if (secretName.endsWith(ENCRYPTION_KEY_SUFFIX))
+        return generateAESGCMKey;
+    if (secretName.endsWith(SIGNING_SECRET_SUFFIX))
+        return generateSigningSecret;
+    throw new Error(`Unknown secret: ${secretName}. Name it '*-encryption-key' for a generated 32-byte AES-GCM key, ` +
+        `or '*-signing-secret' for 32 random bytes, and teach this script the shape if neither fits.`);
+}
+/** Whether this script can produce a value for `secretName`. */
+export function canProvisionSecret(secretName) {
+    try {
+        generatorFor(secretName);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Runs a wrangler subcommand, optionally feeding `input` on stdin.
+ *
+ * Arguments are passed as an argv array rather than interpolated into a shell
+ * string, so a value containing shell metacharacters cannot alter the command.
+ */
+function wrangler(args, input) {
+    try {
+        // eslint-disable-next-line sonarjs/no-os-command-from-path
+        return execFileSync('pnpm', ['exec', 'wrangler', ...args], {
+            encoding: 'utf8',
+            stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+            ...(input !== undefined && { input }),
+        });
+    }
+    catch (error) {
+        const maybeProcessError = error;
+        const stdout = maybeProcessError.stdout ? maybeProcessError.stdout.toString() : '';
+        const stderr = maybeProcessError.stderr ? maybeProcessError.stderr.toString() : '';
+        throw new Error(`Command failed: pnpm exec wrangler ${args.join(' ')}\n${stdout}${stderr || maybeProcessError.message || ''}`);
+    }
+}
+function parseWranglerConfig() {
+    if (!existsSync(CONFIG_PATH)) {
+        throw new Error(`${CONFIG_PATH} not found. Run scripts/prepare-wrangler-config.ts first — it is what creates the file this script reads.`);
+    }
+    // `parse` is error-tolerant and returns a partial object, so an empty result means
+    // malformed JSON rather than "no secrets declared". Treating that as an empty list
+    // would report success having created nothing.
+    const config = parse(readFileSync(CONFIG_PATH, 'utf8'));
+    if (config.secrets_store_secrets === undefined && Object.keys(config).length === 0) {
+        throw new Error(`${CONFIG_PATH} is empty or not valid JSONC. Run scripts/prepare-wrangler-config.ts to regenerate it.`);
+    }
+    return config;
+}
+/**
+ * Turn the config's bindings into a validated work list.
+ *
+ * Every entry is checked *before* the first Cloudflare call, so an
+ * unprovisionable secret fails the step in milliseconds instead of after some other
+ * secret has already been created.
+ */
+export function planSecrets(config) {
+    const plan = [];
+    for (const [index, secret] of (config.secrets_store_secrets ?? []).entries()) {
+        const label = secret.binding ?? `index ${index}`;
+        const storeId = secret.store_id;
+        const secretName = secret.secret_name;
+        if (storeId === undefined || storeId === '' || secretName === undefined || secretName === '') {
+            throw new Error(`secrets_store_secrets[${index}] ("${label}") needs both store_id and secret_name; ` +
+                'store_id is normally filled in by scripts/prepare-wrangler-config.ts.');
+        }
+        if (!canProvisionSecret(secretName)) {
+            throw new Error(`No generator for secret "${secretName}" (binding "${label}").`);
+        }
+        plan.push({ storeId, secretName });
+    }
+    return plan;
+}
+/**
+ * List the secret names present in a store.
+ *
+ * Returns `undefined` when the listing itself failed, which is deliberately
+ * distinct from an empty set: a transient CLI failure must not be read as "the
+ * secret is missing" and cause a duplicate insert over a live value. An empty store
+ * *is* a confirmed absence, so it maps to an empty set rather than `undefined`.
+ *
+ * The name is taken exactly. `output.includes(secretName)` is not a membership test:
+ * `my-replication-encryption-key-2` satisfies a search for
+ * `my-replication-encryption-key`, so a store holding only the suffixed entry would
+ * report the unsuffixed one as already present and it would never be created.
+ */
+function listSecretNames(storeId) {
+    let output;
+    try {
+        output = wrangler(['secrets-store', 'secret', 'list', storeId, '--remote']);
+    }
+    catch (error) {
+        if (isEmptySecretsStoreListing(error)) {
+            console.log(`Secrets Store ${storeId} is empty`);
+            return new Set();
+        }
+        console.warn(`Unable to list secrets in store ${storeId}:`, error instanceof Error ? error.message : 'unknown error');
+        return undefined;
+    }
+    return parseWranglerNames(output);
+}
+function createSecret(storeId, secretName, secretValue) {
+    console.log(`Creating secret: ${secretName}`);
+    // The value goes in on stdin, never as an argv entry: an argv is visible to every
+    // process on the runner through `ps`, and the previous
+    // `echo "${value}" | wrangler … ${name}` also broke on `"`, `$`, backticks and
+    // newlines.
+    wrangler(['secrets-store', 'secret', 'create', storeId, '--name', secretName, '--scopes', 'workers', '--remote'], secretValue);
+}
+async function main() {
+    console.log('Initializing Cloudflare secrets...');
+    const config = parseWranglerConfig();
+    const plan = planSecrets(config);
+    if (plan.length === 0) {
+        throw new Error('wrangler.jsonc declares no secrets_store_secrets entries, so there is nothing to initialize.');
+    }
+    const listedByStore = new Map();
+    for (const { storeId, secretName } of plan) {
+        if (!listedByStore.has(storeId)) {
+            listedByStore.set(storeId, listSecretNames(storeId));
+        }
+        const existing = listedByStore.get(storeId);
+        if (existing === undefined) {
+            // Refuse to guess: creating a secret we could not read back risks overwriting
+            // a live value with a freshly generated one.
+            throw new Error(`Could not list secrets in store ${storeId}; refusing to create ${secretName} without confirming it is absent.`);
+        }
+        if (existing.has(secretName)) {
+            console.log(`Secret ${secretName} already exists; leaving it untouched.`);
+            continue;
+        }
+        createSecret(storeId, secretName, await generatorFor(secretName)());
+        existing.add(secretName);
+    }
+    console.log('Secret initialization complete');
+}
+// Top-level await rather than `.catch(console.error)`, so a rejected `main` surfaces
+// as a stack trace with its cause intact and the process exits non-zero. Either way
+// the exit status has to be right: this runs in the deploy pipeline, and swallowing
+// the rejection reported a failed key bootstrap as a green step.
+try {
+    await main();
+}
+catch (error) {
+    fail(error instanceof Error ? `Secret initialization failed: ${error.message}` : String(error));
+}
+//# sourceMappingURL=init-secrets.js.map

package/dist/scripts/init-secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-secrets.js","sourceRoot":"","sources":["../../src/scripts/init-secrets.ts"],"names":[],"mappings":"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"}

package/dist/scripts/lib/cli-args.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Minimal flag parsing for the operator scripts.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/lib/cli-args.ts`, which is the
+ * only typed arg parser in the family — every other repo reads `process.argv`
+ * with `includes('--flag')` inline.
+ *
+ * The shape is generic: a declared set of value flags and boolean flags, so an
+ * unknown or valueless flag is rejected **by name** rather than silently ignored.
+ * A mistyped `--write` must not degrade into "ran with no flags" — which is what
+ * an inline `argv.includes()` does, and what turns a migration-lock invocation
+ * that misspelled the flag into a read-only run that reports success.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const flags = parseFlags(process.argv.slice(2), {
+ *   boolean: ['write', 'dry-run'],
+ *   value: ['locales-dir', 'root'],
+ * });
+ * if (isSet(flags, 'write')) { ... }
+ * const dir = valueOf(flags, 'locales-dir');
+ * ```
+ */
+/**
+ * Parsed flags: value flags map to their string, boolean flags to `true`.
+ */
+export type ParsedFlags = Map<string, string | true>;
+/**
+ * Declares which flags take a value and which are bare switches.
+ */
+export interface FlagSpec {
+    /**
+     * `--name` takes a value, e.g. `--to new@example.com`.
+     */
+    value?: readonly string[];
+    /**
+     * `--dry-run` takes no value.
+     */
+    boolean?: readonly string[];
+    /**
+     * Short form → long form, e.g. `{ h: 'help' }`.
+     */
+    alias?: Readonly<Record<string, string>>;
+}
+/**
+ * Parses `--flag value` and `--boolean` pairs out of `argv`.
+ *
+ * @throws when a value flag is missing its value, when a flag is repeated, or
+ *   when an undeclared flag is seen. Each case names the offending flag.
+ */
+export declare function parseFlags(argv: readonly string[], spec: FlagSpec): ParsedFlags;
+/**
+ * Reads a value flag, or `undefined` when it was not supplied.
+ */
+export declare function valueOf(flags: ParsedFlags, name: string): string | undefined;
+/**
+ * Reads a boolean flag, defaulting to `false`.
+ */
+export declare function isSet(flags: ParsedFlags, name: string): boolean;
+/**
+ * Split `argv` into its positional arguments and the rest, so a caller can accept
+ * `tsx script.ts <dir>` alongside `--root <dir>`.
+ *
+ * A token that follows a value flag *is* that flag's value, not a positional: the
+ * naive `argv.filter((arg) => !arg.startsWith('-'))` takes `.` out of
+ * `--root . --fail-on-hard` and then `parseFlags` reports `--root requires a value`.
+ * The value flags are passed in rather than inferred, because only the caller knows
+ * which of its declared flags take one.
+ *
+ * @throws when more than `expected` positionals are given, naming them: a second
+ *   directory is far more likely to be a mistyped flag than an intended argument.
+ */
+export declare function splitPositional(argv: readonly string[], valueFlags: readonly string[], expected?: number): {
+    positional: string[];
+    rest: string[];
+};
+//# sourceMappingURL=cli-args.d.ts.map

package/dist/scripts/lib/cli-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../../../src/scripts/lib/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B;;OAEG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;OAEG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,GAAG,WAAW,CAwC/E;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG5E;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,QAAQ,SAAI,GACX;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAwB1C"}

package/dist/scripts/lib/cli-args.js

@@ -0,0 +1,116 @@
+/**
+ * Minimal flag parsing for the operator scripts.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/lib/cli-args.ts`, which is the
+ * only typed arg parser in the family — every other repo reads `process.argv`
+ * with `includes('--flag')` inline.
+ *
+ * The shape is generic: a declared set of value flags and boolean flags, so an
+ * unknown or valueless flag is rejected **by name** rather than silently ignored.
+ * A mistyped `--write` must not degrade into "ran with no flags" — which is what
+ * an inline `argv.includes()` does, and what turns a migration-lock invocation
+ * that misspelled the flag into a read-only run that reports success.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const flags = parseFlags(process.argv.slice(2), {
+ *   boolean: ['write', 'dry-run'],
+ *   value: ['locales-dir', 'root'],
+ * });
+ * if (isSet(flags, 'write')) { ... }
+ * const dir = valueOf(flags, 'locales-dir');
+ * ```
+ */
+/**
+ * Parses `--flag value` and `--boolean` pairs out of `argv`.
+ *
+ * @throws when a value flag is missing its value, when a flag is repeated, or
+ *   when an undeclared flag is seen. Each case names the offending flag.
+ */
+export function parseFlags(argv, spec) {
+    const valueFlags = new Set(spec.value);
+    const booleanFlags = new Set(spec.boolean);
+    const aliases = spec.alias ?? {};
+    const flags = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith('-')) {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+        const raw = arg.replace(/^--?/, '');
+        const name = aliases[raw] ?? raw;
+        if (booleanFlags.has(name)) {
+            if (flags.has(name)) {
+                throw new Error(`--${name} was given more than once`);
+            }
+            flags.set(name, true);
+            continue;
+        }
+        if (!valueFlags.has(name)) {
+            throw new Error(`Unknown argument: ${arg}`);
+        }
+        if (flags.has(name)) {
+            throw new Error(`--${name} was given more than once`);
+        }
+        const value = argv[index + 1];
+        // A value that starts with `-` is treated as a missing value so that
+        // `--to --dry-run` reports the real problem instead of capturing the flag.
+        if (value === undefined || value.startsWith('-')) {
+            throw new Error(`--${name} requires a value`);
+        }
+        flags.set(name, value);
+        index += 1;
+    }
+    return flags;
+}
+/**
+ * Reads a value flag, or `undefined` when it was not supplied.
+ */
+export function valueOf(flags, name) {
+    const value = flags.get(name);
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Reads a boolean flag, defaulting to `false`.
+ */
+export function isSet(flags, name) {
+    return flags.get(name) === true;
+}
+/**
+ * Split `argv` into its positional arguments and the rest, so a caller can accept
+ * `tsx script.ts <dir>` alongside `--root <dir>`.
+ *
+ * A token that follows a value flag *is* that flag's value, not a positional: the
+ * naive `argv.filter((arg) => !arg.startsWith('-'))` takes `.` out of
+ * `--root . --fail-on-hard` and then `parseFlags` reports `--root requires a value`.
+ * The value flags are passed in rather than inferred, because only the caller knows
+ * which of its declared flags take one.
+ *
+ * @throws when more than `expected` positionals are given, naming them: a second
+ *   directory is far more likely to be a mistyped flag than an intended argument.
+ */
+export function splitPositional(argv, valueFlags, expected = 1) {
+    const takes = new Set(valueFlags);
+    const positional = [];
+    const rest = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg.startsWith('-')) {
+            rest.push(arg);
+            continue;
+        }
+        const previous = argv[index - 1];
+        const isFlagValue = previous !== undefined && previous.startsWith('-') && takes.has(previous.replace(/^--?/, ''));
+        if (isFlagValue) {
+            rest.push(arg);
+            continue;
+        }
+        positional.push(arg);
+    }
+    if (positional.length > expected) {
+        throw new Error(`Expected at most ${expected} positional argument(s), got: ${positional.join(', ')}`);
+    }
+    return { positional, rest };
+}
+//# sourceMappingURL=cli-args.js.map

package/dist/scripts/lib/cli-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../../../src/scripts/lib/cli-args.ts"],"names":[],"mappings":"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"}

package/dist/scripts/lib/github-actions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal GitHub Actions step helpers shared by the CI scripts.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/lib/github-actions.ts`, the only
+ * repo that factored these out. The scripts deliberately avoid `@actions/*`
+ * dependencies so they stay runnable with plain `tsx` from a local shell, which
+ * is how they are tested.
+ */
+/**
+ * Append `name=value` to the step's output file. No-op outside Actions.
+ */
+export declare function setOutput(name: string, value: string): void;
+/**
+ * Emit a workflow-command annotation so the failure is visible in the run log.
+ */
+export declare function logError(message: string): void;
+/**
+ * Report a fatal error and exit non-zero.
+ *
+ * The annotation is written *before* exiting so the reason survives in the run
+ * log. This is the whole point of the helper: the failure mode it exists to
+ * prevent is a script that ends in `.catch(console.error)`, which reports success
+ * while every side effect it was supposed to perform did not happen.
+ */
+export declare function fail(message: string): never;
+//# sourceMappingURL=github-actions.d.ts.map

package/dist/scripts/lib/github-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-actions.d.ts","sourceRoot":"","sources":["../../../src/scripts/lib/github-actions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAM3D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAG3C"}

package/dist/scripts/lib/github-actions.js

@@ -0,0 +1,38 @@
+/**
+ * Minimal GitHub Actions step helpers shared by the CI scripts.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/lib/github-actions.ts`, the only
+ * repo that factored these out. The scripts deliberately avoid `@actions/*`
+ * dependencies so they stay runnable with plain `tsx` from a local shell, which
+ * is how they are tested.
+ */
+import { appendFileSync } from 'node:fs';
+/**
+ * Append `name=value` to the step's output file. No-op outside Actions.
+ */
+export function setOutput(name, value) {
+    const outputFile = process.env.GITHUB_OUTPUT;
+    if (!outputFile) {
+        return;
+    }
+    appendFileSync(outputFile, `${name}=${value}\n`);
+}
+/**
+ * Emit a workflow-command annotation so the failure is visible in the run log.
+ */
+export function logError(message) {
+    process.stderr.write(`::error::${message}\n`);
+}
+/**
+ * Report a fatal error and exit non-zero.
+ *
+ * The annotation is written *before* exiting so the reason survives in the run
+ * log. This is the whole point of the helper: the failure mode it exists to
+ * prevent is a script that ends in `.catch(console.error)`, which reports success
+ * while every side effect it was supposed to perform did not happen.
+ */
+export function fail(message) {
+    logError(message);
+    process.exit(1);
+}
+//# sourceMappingURL=github-actions.js.map