primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

package/dist/src/lib/canonical-json.js

@@ -0,0 +1,35 @@
+/**
+ * Canonical JSON serialization used for content comparison and hashing.
+ *
+ * Key order is normalized (sorted) so two structurally identical objects
+ * always produce the same string, while array order is preserved (step order
+ * matters in workflows).
+ *
+ * Lives in `lib/` rather than inside `commands/sync.ts` so both the sync
+ * command and the workflow-include reconciliation helper can compare values
+ * the same way without a circular import.
+ */
+export function canonicalJsonStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map((v) => canonicalJsonStringify(v)).join(",") + "]";
+    }
+    // Honor `toJSON` before the key walk. A `Date` — or smol-toml's `TomlDate`,
+    // what a TOML datetime literal parses to — has no enumerable own keys, so
+    // the `Object.keys()` walk below would collapse it to "{}" and every
+    // datetime would hash identically (issue #1919). Both implement `toJSON`,
+    // returning the ISO string; recursing on it makes date-like values (nested
+    // ones too) participate in the hash. Matches JSON.stringify's own semantics.
+    if (typeof value.toJSON === "function") {
+        return canonicalJsonStringify(value.toJSON());
+    }
+    const keys = Object.keys(value).sort();
+    return ("{" +
+        keys
+            .map((k) => JSON.stringify(k) + ":" + canonicalJsonStringify(value[k]))
+            .join(",") +
+        "}");
+}
+//# sourceMappingURL=canonical-json.js.map

package/dist/src/lib/canonical-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.js","sourceRoot":"","sources":["../../../src/lib/canonical-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAU;IAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAC3E,CAAC;IACD,4EAA4E;IAC5E,0EAA0E;IAC1E,qEAAqE;IACrE,0EAA0E;IAC1E,2EAA2E;IAC3E,6EAA6E;IAC7E,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACvC,OAAO,sBAAsB,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,OAAO,CACL,GAAG;QACH,IAAI;aACD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;aACtE,IAAI,CAAC,GAAG,CAAC;QACZ,GAAG,CACJ,CAAC;AACJ,CAAC"}

package/dist/src/lib/channel.d.ts

@@ -0,0 +1,30 @@
+export declare const DEFAULT_CHANNEL_BRANCH = "main";
+/**
+ * Normalize a server URL for comparison: keep the scheme/host/port, strip all
+ * trailing slashes from the pathname. Returns null for an unparseable value.
+ * `http` vs `https` intentionally does NOT normalize to the same string
+ * (scheme is significant).
+ */
+export declare function normalizeServerUrl(raw: string): string | null;
+/**
+ * Is `value` a plausible git branch ref that is safe to interpolate into a
+ * GitHub URL path? Deliberately strict — only ASCII letters/digits and
+ * `._/-`, no leading dash, no `..`, capped length. This guards the branch
+ * override env vars so no arbitrary string reaches a URL.
+ */
+export declare function isValidBranchName(value: string): boolean;
+/**
+ * Resolve which channel branch to fetch from. Precedence:
+ *   1. `override` (an undocumented, internal env var — `overrideName` is
+ *      only used in the error message). An empty value is ignored; a value
+ *      that is not a plausible git ref is rejected (throws).
+ *   2. Alpha detection: a normalized-URL match of the resolved server URL
+ *      against `ALPHA_SERVER_URL` → `alpha`.
+ *   3. Otherwise `main` (production / local / any non-alpha target, or no
+ *      target at all when the CLI is logged out).
+ *
+ * Pure and side-effect free: the caller passes the resolved server URL (or
+ * `undefined` when `getServerUrl()` threw) and the override, so this is
+ * fully unit-testable without config/credentials.
+ */
+export declare function resolveChannelBranch(serverUrl: string | undefined, override: string | undefined, overrideName: string): string;

package/dist/src/lib/channel.js

@@ -0,0 +1,68 @@
+import { ALPHA_SERVER_URL } from "./constants.js";
+// Channel resolution shared by every surface that fetches from a
+// branch-as-channel repo (issue #1934): `primitive guides` (the
+// primitive-docs-site repo) and `primitive init` (the template mirrors).
+// Branches are named after the deploy environment they describe: `main` =
+// production, `alpha` = the alpha environment.
+export const DEFAULT_CHANNEL_BRANCH = "main";
+/**
+ * Normalize a server URL for comparison: keep the scheme/host/port, strip all
+ * trailing slashes from the pathname. Returns null for an unparseable value.
+ * `http` vs `https` intentionally does NOT normalize to the same string
+ * (scheme is significant).
+ */
+export function normalizeServerUrl(raw) {
+    try {
+        const u = new URL(raw);
+        const path = u.pathname.replace(/\/+$/, "");
+        return `${u.protocol}//${u.host}${path}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is `value` a plausible git branch ref that is safe to interpolate into a
+ * GitHub URL path? Deliberately strict — only ASCII letters/digits and
+ * `._/-`, no leading dash, no `..`, capped length. This guards the branch
+ * override env vars so no arbitrary string reaches a URL.
+ */
+export function isValidBranchName(value) {
+    if (value.length === 0 || value.length > 100)
+        return false;
+    if (value.includes(".."))
+        return false;
+    return /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value);
+}
+/**
+ * Resolve which channel branch to fetch from. Precedence:
+ *   1. `override` (an undocumented, internal env var — `overrideName` is
+ *      only used in the error message). An empty value is ignored; a value
+ *      that is not a plausible git ref is rejected (throws).
+ *   2. Alpha detection: a normalized-URL match of the resolved server URL
+ *      against `ALPHA_SERVER_URL` → `alpha`.
+ *   3. Otherwise `main` (production / local / any non-alpha target, or no
+ *      target at all when the CLI is logged out).
+ *
+ * Pure and side-effect free: the caller passes the resolved server URL (or
+ * `undefined` when `getServerUrl()` threw) and the override, so this is
+ * fully unit-testable without config/credentials.
+ */
+export function resolveChannelBranch(serverUrl, override, overrideName) {
+    const trimmedOverride = override?.trim();
+    if (trimmedOverride) {
+        if (!isValidBranchName(trimmedOverride)) {
+            throw new Error(`Invalid ${overrideName} "${override}": must be a plausible git branch name.`);
+        }
+        return trimmedOverride;
+    }
+    if (serverUrl) {
+        const target = normalizeServerUrl(serverUrl);
+        const alpha = normalizeServerUrl(ALPHA_SERVER_URL);
+        if (target !== null && alpha !== null && target === alpha) {
+            return "alpha";
+        }
+    }
+    return DEFAULT_CHANNEL_BRANCH;
+}
+//# sourceMappingURL=channel.js.map

package/dist/src/lib/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../../src/lib/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,iEAAiE;AACjE,gEAAgE;AAChE,yEAAyE;AACzE,0EAA0E;AAC1E,+CAA+C;AAE/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC5C,OAAO,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,EAAE,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IAC3D,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,+BAA+B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAA6B,EAC7B,QAA4B,EAC5B,YAAoB;IAEpB,MAAM,eAAe,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzC,IAAI,eAAe,EAAE,CAAC;QACpB,IAAI,CAAC,iBAAiB,CAAC,eAAe,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CACb,WAAW,YAAY,KAAK,QAAQ,yCAAyC,CAC9E,CAAC;QACJ,CAAC;QACD,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;QAC7C,MAAM,KAAK,GAAG,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;QACnD,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YAC1D,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC;AAChC,CAAC"}

package/dist/src/lib/cli-manifest.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Machine-readable CLI command manifest (issue #983).
+ *
+ * Serializes the full commander command tree (commands, subcommands, args,
+ * options, aliases, global options, version) into a stable JSON shape so that
+ * external tooling — e.g. `primitive-docs` CI — can drift-gate documented CLI
+ * invocations against the *published* CLI rather than scraping `--help` text.
+ *
+ * The walker uses only commander v12 public accessors, so it is decoupled from
+ * commander internals:
+ *   - `cmd.name()`, `cmd.description()`, `cmd.aliases()`
+ *   - `cmd.commands` (recurse into subcommands)
+ *   - `cmd.registeredArguments` (positional args)
+ *   - `cmd.options` (per-command options)
+ *
+ * `globalOptions` is the top-level program's own options (e.g. `-e, --env`),
+ * reported once at the root rather than repeated on every command.
+ *
+ * `schemaVersion` is the contract knob: consumers assert they understand the
+ * shape and fail loud if a future CLI bumps it. Bumping it is a breaking change
+ * for downstream tooling.
+ */
+import type { Command } from "commander";
+/** Current manifest schema version. Bump on any breaking shape change. */
+export declare const CLI_MANIFEST_SCHEMA_VERSION = 1;
+export interface ManifestArg {
+    name: string;
+    required: boolean;
+    variadic: boolean;
+    description: string;
+}
+export interface ManifestOption {
+    flags: string;
+    description: string;
+    required: boolean;
+    defaultValue: unknown;
+    /**
+     * True for options registered with commander's `hideHelp()` — deprecated
+     * aliases kept working for one window but not part of the supported surface
+     * (#2357). Consumers that treat the manifest as the flag allowlist (the
+     * docs CLI gate) should exclude these so new documentation cannot be
+     * written against a flag that is on its way out.
+     */
+    hidden: boolean;
+}
+export interface ManifestCommand {
+    name: string;
+    description: string;
+    aliases: string[];
+    args: ManifestArg[];
+    options: ManifestOption[];
+    commands: ManifestCommand[];
+}
+export interface CliManifest {
+    schemaVersion: number;
+    name: string;
+    version: string;
+    globalOptions: ManifestOption[];
+    commands: ManifestCommand[];
+}
+/**
+ * Build the JSON manifest for a fully-built commander program.
+ *
+ * @param program The root commander `Command` after all subcommands are
+ *   registered.
+ * @param version The CLI version (typically `pkg.version`).
+ */
+export declare function buildCliManifest(program: Command, version: string): CliManifest;

package/dist/src/lib/cli-manifest.js

@@ -0,0 +1,71 @@
+/**
+ * Machine-readable CLI command manifest (issue #983).
+ *
+ * Serializes the full commander command tree (commands, subcommands, args,
+ * options, aliases, global options, version) into a stable JSON shape so that
+ * external tooling — e.g. `primitive-docs` CI — can drift-gate documented CLI
+ * invocations against the *published* CLI rather than scraping `--help` text.
+ *
+ * The walker uses only commander v12 public accessors, so it is decoupled from
+ * commander internals:
+ *   - `cmd.name()`, `cmd.description()`, `cmd.aliases()`
+ *   - `cmd.commands` (recurse into subcommands)
+ *   - `cmd.registeredArguments` (positional args)
+ *   - `cmd.options` (per-command options)
+ *
+ * `globalOptions` is the top-level program's own options (e.g. `-e, --env`),
+ * reported once at the root rather than repeated on every command.
+ *
+ * `schemaVersion` is the contract knob: consumers assert they understand the
+ * shape and fail loud if a future CLI bumps it. Bumping it is a breaking change
+ * for downstream tooling.
+ */
+/** Current manifest schema version. Bump on any breaking shape change. */
+export const CLI_MANIFEST_SCHEMA_VERSION = 1;
+function serializeArg(arg) {
+    return {
+        name: arg.name(),
+        required: !!arg.required,
+        variadic: !!arg.variadic,
+        description: arg.description || "",
+    };
+}
+function serializeOption(opt) {
+    return {
+        flags: opt.flags,
+        description: opt.description || "",
+        required: !!opt.required,
+        defaultValue: opt.defaultValue ?? null,
+        hidden: !!opt.hidden,
+    };
+}
+function serializeCommand(cmd) {
+    return {
+        name: cmd.name(),
+        description: cmd.description() || "",
+        aliases: cmd.aliases() || [],
+        args: (cmd.registeredArguments || []).map(serializeArg),
+        options: (cmd.options || []).map(serializeOption),
+        commands: (cmd.commands || []).map(serializeCommand),
+    };
+}
+/**
+ * Build the JSON manifest for a fully-built commander program.
+ *
+ * @param program The root commander `Command` after all subcommands are
+ *   registered.
+ * @param version The CLI version (typically `pkg.version`).
+ */
+export function buildCliManifest(program, version) {
+    const root = program;
+    return {
+        schemaVersion: CLI_MANIFEST_SCHEMA_VERSION,
+        name: root.name(),
+        version,
+        // Top-level program options are the "global" options (e.g. -e, --env);
+        // per-command options live under each command in `commands[]`.
+        globalOptions: (root.options || []).map(serializeOption),
+        commands: (root.commands || []).map(serializeCommand),
+    };
+}
+//# sourceMappingURL=cli-manifest.js.map

package/dist/src/lib/cli-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-manifest.js","sourceRoot":"","sources":["../../../src/lib/cli-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAyC7C,SAAS,YAAY,CAAC,GAAQ;IAC5B,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE;QAChB,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ;QACxB,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ;QACxB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE;KACnC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,GAAQ;IAC/B,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE;QAClC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ;QACxB,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,IAAI;QACtC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM;KACrB,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAQ;IAChC,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE;QACpC,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE;QAC5B,IAAI,EAAE,CAAC,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC;QACvD,OAAO,EAAE,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC;QACjD,QAAQ,EAAE,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC;KACrD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,OAAe;IAChE,MAAM,IAAI,GAAG,OAAc,CAAC;IAC5B,OAAO;QACL,aAAa,EAAE,2BAA2B;QAC1C,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;QACjB,OAAO;QACP,uEAAuE;QACvE,+DAA+D;QAC/D,aAAa,EAAE,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC;QACxD,QAAQ,EAAE,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC;KACtD,CAAC;AACJ,CAAC"}

package/dist/src/lib/codegen-shared/generatedFiles.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared write / `--check` / stale-cleanup machinery for the CLI codegen
+ * commands (issue #1442, sponsor decision #6).
+ *
+ * Both `databases codegen` (#814) and `workflows codegen` (#1442) render a set
+ * of `*.generated.ts` files and then either write them to disk or, under
+ * `--check`, compare the would-be output byte-for-byte against what's on disk.
+ * The write/compare/cleanup half is identical between them, so it lives here
+ * rather than being cloned into each generator.
+ *
+ * The RENDERING (schema → TS) stays in each generator — only the on-disk
+ * lifecycle is shared: `mkdir`, write, orphan cleanup, and the `--check`
+ * missing/differs/stale comparison.
+ */
+export type GeneratedFileMismatchReason = "missing" | "differs" | "stale";
+export interface GeneratedFileMismatch {
+    filePath: string;
+    reason: GeneratedFileMismatchReason;
+}
+export interface WriteOrCheckResult {
+    /** Files written (or that would be written under `--check`). */
+    writtenFiles: string[];
+    /** Stale `*.generated.ts` files deleted (empty under `--check`). */
+    deletedFiles: string[];
+    /** Only populated under `--check`: files whose on-disk content is out of date. */
+    mismatches: GeneratedFileMismatch[];
+}
+export interface WriteOrCheckOptions {
+    /** Directory the generated files live in. */
+    outputDir: string;
+    /** Absolute file path → rendered content. */
+    filesToWrite: Map<string, string>;
+    /**
+     * If true, do not write. Compare each would-be file to disk and return a
+     * non-empty `mismatches` list if anything would change.
+     */
+    check?: boolean;
+    /**
+     * When true, `filesToWrite` is the COMPLETE set of generated files this
+     * output dir owns, so orphaned `*.generated.ts` files are cleaned up (write
+     * mode) or flagged `stale` (check mode). When false — a run filtered to a
+     * subset — sibling generated files are left intact and not flagged, because
+     * `filesToWrite` is only a partial view.
+     */
+    fullOwnership: boolean;
+    /**
+     * Suffix identifying generator-owned files (for orphan cleanup / stale
+     * detection). Defaults to `.generated.ts`. Both `databases codegen` and
+     * `workflows codegen` write one `<name>.generated.ts` file per entity into
+     * their OWN default output dir (`database-type-configs/generated/` and
+     * `workflows/generated/` respectively), so suffix-based ownership never
+     * reaches the other generator's files.
+     */
+    generatedSuffix?: string;
+    /**
+     * Optional banner prefix that further narrows ownership by file CONTENT.
+     * When set, a `<suffix>` file is only considered owned (for orphan cleanup /
+     * stale detection) if its contents also start with this prefix.
+     *
+     * The Swift path needs this: both `workflows codegen --lang swift` and the
+     * Swift model codegen (`swift-bao-codegen`) emit `.generated.swift` files and
+     * may share one output dir (a Sources dir in the consuming app). Suffix alone
+     * cannot tell them apart, so a suffix-only sweep would delete the other
+     * generator's files. Scoping by the emitted header banner keeps each
+     * generator's cleanup to its own files. The TS callers leave this unset —
+     * their default `generated/` dirs are single-generator, so suffix ownership
+     * is already unambiguous.
+     *
+     * Several banners may be given: a generator whose banner has been RENAMED
+     * still owns the files it stamped with the old one (issue #2760), and
+     * dropping them from the set would orphan every pre-rename output.
+     */
+    ownershipBanner?: string | readonly string[];
+    /**
+     * Banners belonging to OTHER generators that must never be overwritten by
+     * this run (issue #1653, class 3b). When two generators share one `--output`
+     * dir and a name coincides (e.g. a workflow key equals a database type name),
+     * both resolve to the identical `<name>.generated.swift` path. Without this
+     * guard the second run silently clobbers the first (cleanup skips the foreign
+     * file because it carries the other banner, then the write loop overwrites
+     * it). Before writing OR checking, if a target path already holds a file whose
+     * content starts with one of these foreign banners, the run fails.
+     */
+    foreignOwnershipBanners?: string[];
+    /**
+     * Builds the error thrown when a `foreignOwnershipBanners` collision is
+     * detected. Lets the caller throw its own named error (e.g. the Swift path's
+     * `SwiftCodegenError`) without this shared module depending on it. When unset,
+     * a generic `Error` is thrown.
+     */
+    onForeignBannerCollision?: (info: {
+        filePath: string;
+        foreignBanner: string;
+    }) => Error;
+}
+/**
+ * Write (or `--check`) a set of rendered generated files, handling orphan
+ * cleanup / stale detection. Pure lifecycle: the caller renders content, this
+ * owns the disk side.
+ */
+export declare function writeOrCheckGeneratedFiles(options: WriteOrCheckOptions): Promise<WriteOrCheckResult>;

package/dist/src/lib/codegen-shared/generatedFiles.js

@@ -0,0 +1,191 @@
+/**
+ * Shared write / `--check` / stale-cleanup machinery for the CLI codegen
+ * commands (issue #1442, sponsor decision #6).
+ *
+ * Both `databases codegen` (#814) and `workflows codegen` (#1442) render a set
+ * of `*.generated.ts` files and then either write them to disk or, under
+ * `--check`, compare the would-be output byte-for-byte against what's on disk.
+ * The write/compare/cleanup half is identical between them, so it lives here
+ * rather than being cloned into each generator.
+ *
+ * The RENDERING (schema → TS) stays in each generator — only the on-disk
+ * lifecycle is shared: `mkdir`, write, orphan cleanup, and the `--check`
+ * missing/differs/stale comparison.
+ */
+import * as path from "path";
+import { promises as fsp } from "fs";
+const DEFAULT_GENERATED_SUFFIX = ".generated.ts";
+/** Normalize the one-or-many ownership banner into a list. */
+function bannerList(banner) {
+    if (banner === undefined)
+        return [];
+    return typeof banner === "string" ? [banner] : banner;
+}
+/**
+ * Write (or `--check`) a set of rendered generated files, handling orphan
+ * cleanup / stale detection. Pure lifecycle: the caller renders content, this
+ * owns the disk side.
+ */
+export async function writeOrCheckGeneratedFiles(options) {
+    const outAbs = path.resolve(options.outputDir);
+    const suffix = options.generatedSuffix ?? DEFAULT_GENERATED_SUFFIX;
+    // Cross-generator collision guard (issue #1653, class 3b). Runs BEFORE the
+    // check/write branch so `--check` reports the named collision too, rather than
+    // a generic `differs`.
+    await assertNoForeignBannerCollision(options.filesToWrite, options.foreignOwnershipBanners, options.onForeignBannerCollision);
+    if (options.check === true) {
+        return await runCheck(outAbs, options.filesToWrite, options.fullOwnership, suffix, options.ownershipBanner);
+    }
+    await fsp.mkdir(outAbs, { recursive: true });
+    const deletedFiles = await cleanupGeneratedOutputs(outAbs, options.filesToWrite, options.fullOwnership, suffix, options.ownershipBanner);
+    const writtenFiles = [];
+    for (const [filePath, content] of options.filesToWrite) {
+        await fsp.writeFile(filePath, content, "utf-8");
+        writtenFiles.push(filePath);
+    }
+    writtenFiles.sort();
+    deletedFiles.sort();
+    return { writtenFiles, deletedFiles, mismatches: [] };
+}
+/**
+ * Fail if any target path already holds a file owned by a DIFFERENT generator
+ * (its content starts with a foreign ownership banner). A genuinely absent file
+ * (ENOENT) is not a collision and is skipped; any other read error is
+ * propagated (abort) so the write path never truncates a file whose banner
+ * could not be verified. Runs in both the write and `--check` paths.
+ */
+async function assertNoForeignBannerCollision(filesToWrite, foreignBanners, onCollision) {
+    if (!foreignBanners || foreignBanners.length === 0)
+        return;
+    for (const filePath of filesToWrite.keys()) {
+        let contents;
+        try {
+            contents = await fsp.readFile(filePath, "utf-8");
+        }
+        catch (err) {
+            if (err && err.code === "ENOENT") {
+                continue; // genuinely absent → not a collision
+            }
+            // Any other read error (e.g. EACCES on an owner-write-only file) means
+            // the banner could NOT be verified. Treating it as absent is fail-open:
+            // the write path would then truncate a foreign file whose banner was
+            // never checked. Rethrow so the run aborts, matching the sibling
+            // `runCheck`.
+            throw err;
+        }
+        const foreignBanner = foreignBanners.find((b) => contents.startsWith(b));
+        if (foreignBanner !== undefined) {
+            throw onCollision
+                ? onCollision({ filePath, foreignBanner })
+                : new Error(`codegen: output collision — "${filePath}" is already owned by a ` +
+                    `different generator (banner "${foreignBanner.trim()}"). Give ` +
+                    `one generator a separate --output directory.`);
+        }
+    }
+}
+async function runCheck(outAbs, filesToWrite, fullOwnership, suffix, ownershipBanner) {
+    const mismatches = [];
+    for (const [filePath, expected] of filesToWrite) {
+        let actual;
+        try {
+            actual = await fsp.readFile(filePath, "utf-8");
+        }
+        catch (err) {
+            if (err && err.code === "ENOENT") {
+                actual = null;
+            }
+            else {
+                throw err;
+            }
+        }
+        if (actual === null) {
+            mismatches.push({ filePath, reason: "missing" });
+        }
+        else if (actual !== expected) {
+            mismatches.push({ filePath, reason: "differs" });
+        }
+    }
+    // Stale on-disk generated files the generator wouldn't produce also count as
+    // a mismatch (so CI catches dropped types/workflows). Skip when this run only
+    // owns a subset: `filesToWrite` is then partial, so sibling files aren't
+    // "stale" — they just weren't in scope.
+    if (fullOwnership && (await dirExists(outAbs))) {
+        const onDisk = await listOwnedGeneratedFiles(outAbs, suffix, ownershipBanner);
+        const expectedPaths = new Set(filesToWrite.keys());
+        for (const filePath of onDisk) {
+            if (!expectedPaths.has(filePath)) {
+                mismatches.push({ filePath, reason: "stale" });
+            }
+        }
+    }
+    return {
+        writtenFiles: [...filesToWrite.keys()].sort(),
+        deletedFiles: [],
+        mismatches,
+    };
+}
+async function cleanupGeneratedOutputs(outDir, filesToWrite, fullOwnership, suffix, ownershipBanner) {
+    // A filtered run only owns a subset; `filesToWrite` does not represent the
+    // full set of generated files, so skip orphan cleanup to avoid destroying
+    // sibling files. Full cleanup only happens on the unfiltered run.
+    if (!fullOwnership)
+        return [];
+    const onDisk = await listOwnedGeneratedFiles(outDir, suffix, ownershipBanner);
+    const expectedPaths = new Set(filesToWrite.keys());
+    const deleted = [];
+    for (const filePath of onDisk) {
+        if (!expectedPaths.has(filePath)) {
+            await fsp.unlink(filePath);
+            deleted.push(filePath);
+        }
+    }
+    return deleted;
+}
+/**
+ * List only the generator-owned files in `outDir`, decided by the `suffix`
+ * (`.generated.ts`) and, when given, an `ownershipBanner` prefix on the file's
+ * content. Hand-written files — and files owned by a DIFFERENT generator that
+ * happen to share the suffix — are never touched.
+ */
+async function listOwnedGeneratedFiles(outDir, suffix, ownershipBanner) {
+    if (!(await dirExists(outDir)))
+        return [];
+    const entries = await fsp.readdir(outDir, { withFileTypes: true });
+    const owned = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith(suffix))
+            continue;
+        const filePath = path.join(outDir, entry.name);
+        const banners = bannerList(ownershipBanner);
+        if (banners.length > 0) {
+            // Content-scoped ownership: only sweep files carrying THIS generator's
+            // banner, so a shared output dir keeps each generator's cleanup to its
+            // own files. A read failure means "not confidently ours" → skip it.
+            let contents;
+            try {
+                contents = await fsp.readFile(filePath, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            if (!banners.some((banner) => contents.startsWith(banner)))
+                continue;
+        }
+        owned.push(filePath);
+    }
+    return owned;
+}
+async function dirExists(dir) {
+    try {
+        const stat = await fsp.stat(dir);
+        return stat.isDirectory();
+    }
+    catch (err) {
+        if (err && err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+//# sourceMappingURL=generatedFiles.js.map

package/dist/src/lib/codegen-shared/generatedFiles.js.map

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