primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/block-selector.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Resolve the identifier the `prompts tests` and `workflows tests` verbs take
+ * (issue #3249).
+ *
+ * The block-testing endpoints key on the composite `<type>#<blockId>` and
+ * never check that the block exists, so an identifier that names no prompt or
+ * workflow came back as an empty page rather than a 404: `tests list <key>`
+ * printed "No test cases found." and exited 0, and a checked-in
+ * `prompts/<key>.tests/` sidecar looked unregistered until the id was tried.
+ * The key is what an author has to hand — `prompts list` prints it beside the
+ * id, and the config tree, `config push` and the test sidecars are all
+ * key-addressed — so a wrong identifier was indistinguishable from a block
+ * with no cases.
+ *
+ * Resolving here — against the app's own list — is what makes an empty
+ * listing mean "this block exists and has no cases", the same answer #3000
+ * gave the integration verbs (`integration-selector.ts`). The list is the one
+ * call that can answer both halves: it maps a key to its id and it proves the
+ * identifier belongs to THIS app. It is drained across every page, because
+ * the server pages prompts at 50 and workflows at 25 by default. Archived
+ * blocks are included, because their cases stay inspectable.
+ *
+ * Keys are matched exactly first. The server does not lowercase prompt or
+ * workflow keys on write, so a case-insensitive match is a fallback that
+ * resolves only when it is unambiguous — two keys differing only in case are
+ * refused by name rather than picked between (the `resolveScript` rule in
+ * `scripts.ts`).
+ */
+export interface ResolvedBlock {
+    blockId: string;
+    /** The block's key, when the summary carries one. */
+    blockKey?: string;
+}
+type ListPage = {
+    items: any[];
+    nextCursor?: string | null;
+};
+type ListParams = {
+    cursor?: string;
+    limit?: number;
+};
+/** The one method each resolver needs from `ApiClient`. */
+export interface PromptLister {
+    listPrompts(appId: string, params?: ListParams): Promise<ListPage>;
+}
+export interface WorkflowLister {
+    listWorkflows(appId: string, params?: ListParams): Promise<ListPage>;
+}
+/**
+ * Map a prompt ID or key to its prompt ID.
+ *
+ * Throws — naming the identifier — when nothing in the app matches, so the
+ * caller's existing catch prints the message and exits non-zero.
+ */
+export declare function resolvePromptSelector(client: PromptLister, appId: string, selector: string): Promise<ResolvedBlock>;
+/** The same resolution for a workflow ID or key. */
+export declare function resolveWorkflowSelector(client: WorkflowLister, appId: string, selector: string): Promise<ResolvedBlock>;
+export {};

package/dist/src/lib/block-selector.js

@@ -0,0 +1,92 @@
+/**
+ * Resolve the identifier the `prompts tests` and `workflows tests` verbs take
+ * (issue #3249).
+ *
+ * The block-testing endpoints key on the composite `<type>#<blockId>` and
+ * never check that the block exists, so an identifier that names no prompt or
+ * workflow came back as an empty page rather than a 404: `tests list <key>`
+ * printed "No test cases found." and exited 0, and a checked-in
+ * `prompts/<key>.tests/` sidecar looked unregistered until the id was tried.
+ * The key is what an author has to hand — `prompts list` prints it beside the
+ * id, and the config tree, `config push` and the test sidecars are all
+ * key-addressed — so a wrong identifier was indistinguishable from a block
+ * with no cases.
+ *
+ * Resolving here — against the app's own list — is what makes an empty
+ * listing mean "this block exists and has no cases", the same answer #3000
+ * gave the integration verbs (`integration-selector.ts`). The list is the one
+ * call that can answer both halves: it maps a key to its id and it proves the
+ * identifier belongs to THIS app. It is drained across every page, because
+ * the server pages prompts at 50 and workflows at 25 by default. Archived
+ * blocks are included, because their cases stay inspectable.
+ *
+ * Keys are matched exactly first. The server does not lowercase prompt or
+ * workflow keys on write, so a case-insensitive match is a fallback that
+ * resolves only when it is unambiguous — two keys differing only in case are
+ * refused by name rather than picked between (the `resolveScript` rule in
+ * `scripts.ts`).
+ */
+import { paginateAll } from "./paginate.js";
+const PROMPT_KIND = {
+    noun: "prompt",
+    idField: "promptId",
+    keyField: "promptKey",
+    listCommand: "primitive prompts list",
+};
+const WORKFLOW_KIND = {
+    noun: "workflow",
+    idField: "workflowId",
+    keyField: "workflowKey",
+    listCommand: "primitive workflows list",
+};
+/** The largest page the list endpoints accept (#1316), so a drain is few calls. */
+const PAGE_LIMIT = 100;
+/**
+ * Map a prompt ID or key to its prompt ID.
+ *
+ * Throws — naming the identifier — when nothing in the app matches, so the
+ * caller's existing catch prints the message and exits non-zero.
+ */
+export function resolvePromptSelector(client, appId, selector) {
+    return resolveBlockSelector(PROMPT_KIND, (params) => client.listPrompts(appId, params), appId, selector);
+}
+/** The same resolution for a workflow ID or key. */
+export function resolveWorkflowSelector(client, appId, selector) {
+    return resolveBlockSelector(WORKFLOW_KIND, (params) => client.listWorkflows(appId, params), appId, selector);
+}
+async function resolveBlockSelector(kind, list, appId, selector) {
+    const identifier = (selector ?? "").trim();
+    if (!identifier) {
+        throw new Error(`A ${kind.noun} ID or key is required.`);
+    }
+    const items = await paginateAll((cursor) => list(cursor ? { cursor, limit: PAGE_LIMIT } : { limit: PAGE_LIMIT }));
+    const keyOf = (item) => typeof item?.[kind.keyField] === "string" ? item[kind.keyField] : undefined;
+    let match = items.find((item) => item?.[kind.idField] === identifier) ??
+        items.find((item) => keyOf(item) === identifier);
+    if (!match) {
+        const lowered = identifier.toLowerCase();
+        const ci = items.filter((item) => keyOf(item)?.toLowerCase() === lowered);
+        if (ci.length > 1) {
+            const candidates = ci
+                .map((item) => keyOf(item))
+                .sort()
+                .join(", ");
+            throw new Error(`${capitalize(kind.noun)} key is ambiguous: ${identifier}. Did you mean: ${candidates}? ` +
+                `Keys differing only in case must be given exactly, or by ID.`);
+        }
+        match = ci[0];
+    }
+    if (!match) {
+        throw new Error(`No ${kind.noun} '${identifier}' in app ${appId}. ` +
+            `Pass a ${kind.noun} key or ID from '${kind.listCommand}'.`);
+    }
+    const blockKey = keyOf(match);
+    return {
+        blockId: match[kind.idField] ?? identifier,
+        ...(blockKey ? { blockKey } : {}),
+    };
+}
+function capitalize(word) {
+    return word.charAt(0).toUpperCase() + word.slice(1);
+}
+//# sourceMappingURL=block-selector.js.map

package/dist/src/lib/block-selector.js.map

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

package/dist/src/lib/canonical-json.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function canonicalJsonStringify(value: any): string;

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>;