create-ailk 0.28.0 → 0.29.0

package/dist/migrate-content.js

@@ -0,0 +1,215 @@
+/**
+ * `create-ailk migrate-content [<dir>] [--apply] [--api-url <origin>]
+ * [--workspace <id>]` — import an existing site's MDX pages into its
+ * workspace (#10207).
+ *
+ * The same import as `seed-workspace` — `importMdx` over `<dir>/content` with
+ * the site's own installed adapter — for the site `seed-workspace` refuses: one
+ * with no `.ailk-site-manifest.json`, or a spoke, whose workspace lives on its
+ * hub (D1). No manifest and no topology is read; the operator names the API
+ * origin and the workspace, which is all the topology would decide.
+ *
+ * A dry run is the default (D3): the importer runs over `readOnlyFetch`, which
+ * passes each `GET` through and answers a `POST` or `PATCH` locally without
+ * sending it, so the plan — create · update · unchanged · skipped · failed — is
+ * decided by the importer itself against the live workspace, and no write can
+ * leave the process. `--apply` writes; a second `--apply` reports every page
+ * `unchanged`.
+ *
+ * Credentials follow `seed-workspace` (#10204 D2): the origin from
+ * `--api-url`, else `AILK_API_URL`; the workspace id from `--workspace`, else
+ * `AILK_WORKSPACE_ID`; the agent key from `AILK_AGENT_KEY` and nowhere else.
+ * A missing or malformed credential is refused before the adapter is loaded;
+ * every refusal, the importer's included, is thrown before any request.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly. Spec:
+ * docs/specs/10207-create-ailk-migrate-content-import-spec.md.
+ */
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { formatImportMdxReport, importMdx, loadSiteMdxAdapter, } from "./lib/import-mdx.js";
+import { ParseError } from "./parse-args.js";
+import { AGENT_KEY_ENV_VAR, WORKSPACE_ID_ENV_VAR } from "./seed-workspace.js";
+import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, } from "./topology.js";
+/** The locale imported: the importer's default. */
+const LOCALE = "en";
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export class MigrateContentRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "MigrateContentRefusedError";
+    }
+}
+function refuse(message) {
+    throw new MigrateContentRefusedError(`migrate-content: ${message} Nothing was sent.`);
+}
+/** A value given, or `undefined` for an absent or empty one. */
+function given(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+// ── The dry run's transport (D3) ────────────────────────────────────────────
+/**
+ * A fetch that sends `GET`s through `inner` and never sends a write: a `POST`
+ * is answered `201` and a `PATCH` `200` locally, with the one member of a
+ * write's answer `importMdx` reads (`data.locale`). Any other method throws.
+ */
+export function readOnlyFetch(inner, locale) {
+    return (async (input, init) => {
+        const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+        if (method === "GET")
+            return inner(input, init);
+        if (method !== "POST" && method !== "PATCH") {
+            throw new Error(`a dry run sends no ${method} request`);
+        }
+        return new Response(JSON.stringify({ ok: true, data: { locale } }), {
+            status: method === "POST" ? 201 : 200,
+            headers: { "content-type": "application/json" },
+        });
+    });
+}
+// ── The plan (D4) ───────────────────────────────────────────────────────────
+/** A dry run's verb for what `--apply` would do. */
+const PLAN_VERB = {
+    created: "create",
+    updated: "update",
+    unchanged: "unchanged",
+    skipped: "skipped",
+    failed: "failed",
+};
+function planLine(outcome) {
+    const verb = PLAN_VERB[outcome.result];
+    return "reason" in outcome
+        ? `${outcome.path}: ${verb} — ${outcome.reason}`
+        : `${outcome.path}: ${verb}`;
+}
+// ── The command (D1–D4) ─────────────────────────────────────────────────────
+export async function migrateContent(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const env = opts.env ?? process.env;
+    const onLine = opts.onLine ?? (() => undefined);
+    const apply = opts.apply === true;
+    const apiKey = given(env[AGENT_KEY_ENV_VAR]);
+    if (apiKey === undefined) {
+        refuse(`set ${AGENT_KEY_ENV_VAR} to an agent key with the content-edit grant. It is read from the environment only — never a flag or a file.`);
+    }
+    const workspaceId = given(opts.workspaceId) ?? given(env[WORKSPACE_ID_ENV_VAR]);
+    if (workspaceId === undefined) {
+        refuse(`no workspace id was given. Pass --workspace <wksp_id>, or set ${WORKSPACE_ID_ENV_VAR}.`);
+    }
+    const flagOrigin = given(opts.apiUrl);
+    const source = flagOrigin !== undefined ? "--api-url" : HUB_ORIGIN_ENV_VAR;
+    const rawOrigin = flagOrigin ?? given(env[HUB_ORIGIN_ENV_VAR]);
+    if (rawOrigin === undefined) {
+        refuse(`no API origin was given. Pass --api-url <origin>, or set ${HUB_ORIGIN_ENV_VAR}.`);
+    }
+    let origin;
+    try {
+        origin = normalizeHubUrl(rawOrigin);
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        refuse(`the API origin must be an https: origin (http: only on a loopback host) with no path, query, fragment or credentials (from ${source}).`);
+    }
+    const at = `workspace ${workspaceId} at ${origin} (from ${source}).`;
+    onLine(apply
+        ? `Migrating ${opts.targetDir} into ${at}`
+        : `Planning ${opts.targetDir} against ${at} Nothing is written without --apply.`);
+    const adapters = opts.adapters ?? (await loadSiteMdxAdapter(targetDir));
+    const fetch = opts.fetch ?? globalThis.fetch;
+    const result = await importMdx({
+        contentRoot: join(targetDir, "content"),
+        adapters,
+        apiOrigin: origin,
+        workspaceId,
+        apiKey,
+        defaultLocale: LOCALE,
+        fetch: apply ? fetch : readOnlyFetch(fetch, LOCALE),
+        ...(opts.sleep !== undefined && { sleep: opts.sleep }),
+        // A dry run's importer lines say `created`/`updated`, which nothing was.
+        ...(apply && { onLine }),
+    });
+    const { failed } = result.counts;
+    if (apply) {
+        onLine(formatImportMdxReport({ pages: [], counts: result.counts }).trimEnd());
+        if (failed > 0) {
+            onLine(`${failed} page(s) were not migrated. Fix them and re-run: create-ailk migrate-content ${opts.targetDir} --apply`);
+        }
+    }
+    else {
+        const { created, updated, unchanged, skipped } = result.counts;
+        for (const outcome of result.pages)
+            onLine(planLine(outcome));
+        onLine(`create ${created} · update ${updated} · unchanged ${unchanged} · skipped ${skipped} · failed ${failed}`);
+        onLine("Dry run: nothing was written. Re-run with --apply to write these pages.");
+        if (failed > 0) {
+            onLine(`${failed} page(s) would fail. Fix them before --apply.`);
+        }
+    }
+    return { result, exitCode: failed > 0 ? 1 : 0 };
+}
+export const MIGRATE_CONTENT_HELP = `create-ailk migrate-content — import an existing site's pages into its workspace.
+
+Usage:
+  AILK_AGENT_KEY=<key> create-ailk migrate-content [<dir>] [--apply] [--api-url <origin>] [--workspace <wksp_id>]
+
+Arguments:
+  <dir>                    The site. Defaults to the current dir.
+
+Options:
+  --apply                  Write the pages. Without it the command reads the
+                           workspace, prints what it would do, and writes
+                           nothing.
+  --api-url <origin>       The API origin that holds the workspace — on a
+                           spoke, its hub's. Else AILK_API_URL. https: only
+                           (http: on localhost or 127.0.0.1).
+  --workspace <wksp_id>    The workspace the pages are written to. Else
+                           AILK_WORKSPACE_ID.
+  -h, --help               Show this help.
+
+Each content/en/<Type>/<slug>.mdx page (and each legacy
+content/<Type>/<slug>.mdx) is written to the workspace as a draft through
+the API's content routes, with the agent key, which is read from
+AILK_AGENT_KEY only and needs the content-edit grant. Nothing is published,
+so the live site does not change. The site needs no .ailk-site-manifest.json
+and may be a spoke; its dependencies must be installed.
+
+A dry run prints create, update, unchanged, skipped or failed per page. It
+cannot see a write the API would refuse at --apply (a conflict or a server
+error), and a page whose content fails its page type is planned and saved
+with errors the editor shows, not failed. --apply prints created, updated,
+unchanged, skipped or failed per page, so a re-run is safe. Exit 0 when no
+page failed, 1 when any did, 2 on a refusal (nothing is sent).
+`;
+export function parseMigrateContentArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            options: {
+                apply: { type: "boolean", default: false },
+                "api-url": { type: "string" },
+                workspace: { type: "string" },
+                help: { type: "boolean", default: false, short: "h" },
+            },
+        });
+    }
+    catch (err) {
+        throw new ParseError(`migrate-content: ${err.message}`);
+    }
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`migrate-content takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return {
+        target,
+        apply: parsed.values.apply === true,
+        apiUrl: parsed.values["api-url"],
+        workspaceId: parsed.values.workspace,
+        help: parsed.values.help === true,
+    };
+}

package/dist/seed-workspace.d.ts

@@ -0,0 +1,71 @@
+import { type ImportMdxResult, type MdxAdapterModule } from "./lib/import-mdx.js";
+import { type Topology } from "./topology.js";
+/** The environment variable the agent key is read from — and nowhere else. */
+export declare const AGENT_KEY_ENV_VAR = "AILK_AGENT_KEY";
+/** The environment variable the workspace id is read from when no flag names one. */
+export declare const WORKSPACE_ID_ENV_VAR = "AILK_WORKSPACE_ID";
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export declare class SeedWorkspaceRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export interface SeedWorkspaceOptions {
+    /** The site. */
+    targetDir: string;
+    /** `--api-url`. */
+    apiUrl?: string | undefined;
+    /** `--workspace`. */
+    workspaceId?: string | undefined;
+    /** Injectable for tests; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable for tests; defaults to the site's installed adapter. */
+    adapters?: MdxAdapterModule;
+    /** Injectable for tests; defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Injectable for tests; the wait before a rate-limited retry. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Each report line as it happens; defaults to nothing. */
+    onLine?: (line: string) => void;
+}
+export declare function seedWorkspace(opts: SeedWorkspaceOptions): Promise<{
+    result: ImportMdxResult;
+    exitCode: 0 | 1;
+}>;
+export type ScaffoldSeedPlan = {
+    kind: "not-applicable";
+} | {
+    kind: "skip";
+    reason: string;
+} | {
+    kind: "seed";
+};
+export interface ScaffoldSeedPlanInput {
+    topology: Topology | undefined;
+    /** The scaffold's effective module set. */
+    modules: readonly string[];
+    /** Whether `--install` ran. */
+    installed: boolean;
+    env: NodeJS.ProcessEnv;
+}
+/** What the scaffold does about seeding, decided in D3's order. */
+export declare function scaffoldSeedPlan(input: ScaffoldSeedPlanInput): ScaffoldSeedPlan;
+export interface RunScaffoldSeedOptions extends ScaffoldSeedPlanInput {
+    targetDir: string;
+    onLine: (line: string) => void;
+    adapters?: MdxAdapterModule;
+    fetch?: typeof globalThis.fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The whole scaffold-time step: plan, then print the skip or run the seed. A
+ * refusal is printed, never thrown, and sets no exit code (D6).
+ */
+export declare function runScaffoldSeed(opts: RunScaffoldSeedOptions): Promise<void>;
+export interface SeedWorkspaceArgs {
+    target: string | undefined;
+    apiUrl: string | undefined;
+    workspaceId: string | undefined;
+    help: boolean;
+}
+export declare const SEED_WORKSPACE_HELP = "create-ailk seed-workspace \u2014 import a starter's pages into its workspace.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --api-url <origin>       The site's API origin. Else AILK_API_URL. https:\n                           only (http: on localhost or 127.0.0.1).\n  --workspace <wksp_id>    The workspace the pages are written to. Else\n                           AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nEach content/en/<Type>/<slug>.mdx page is written to the workspace as a\ndraft through the API's content routes, with the agent key, which is read\nfrom AILK_AGENT_KEY only and needs the content-edit grant. Each page prints\ncreated, updated, unchanged, skipped or failed, so a re-run is safe. The\nsite's dependencies must be installed. Exit 0 when every page was seeded, 1\nwhen any failed, 2 on a refusal (nothing is sent).\n";
+export declare function parseSeedWorkspaceArgs(argv: string[]): SeedWorkspaceArgs;

package/dist/seed-workspace.js

@@ -0,0 +1,242 @@
+/**
+ * `create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <id>]`
+ * — import a starter scaffold's pages into its workspace (#10204), and the
+ * scaffold-time step that runs it at the end of `pnpm create ailk`.
+ *
+ * A fresh scaffold's `content/` tree is exactly its roster (spec §1), so the
+ * seed is `importMdx` over `<dir>/content` with the site's own installed
+ * adapter (D1): one `text/page` Artifact per page, and a re-run writes
+ * nothing and reports every page `unchanged`.
+ *
+ * The API origin comes from `--api-url`, else `AILK_API_URL`; the workspace
+ * id from `--workspace`, else `AILK_WORKSPACE_ID`; the agent key from
+ * `AILK_AGENT_KEY` and nowhere else — no flag and no file decides where the
+ * key goes (D2, the `seed-flows` rule, #9969 D8). Every refusal is thrown
+ * before the adapter reads a file and before any request; the origin and its
+ * source are printed before the first one. The importer owns the transport
+ * (#10203 D5): bearer header only, no redirect, the key never printed.
+ *
+ * The scaffold-time step (D3, D6) runs only on a hub with an Admin
+ * (`workspace` or `multi-tenant`), after `--install`, with all three
+ * variables set; otherwise it prints why and the command that seeds later,
+ * or nothing on a site with no Admin. It never fails the scaffold.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly. `fetch`,
+ * `sleep`, `env` and the adapter are injectable. Spec:
+ * docs/specs/10204-seed-the-starter-s-roster-spec.md.
+ */
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { AddModuleRefusedError } from "./add-module-core.js";
+import { ImportMdxRefusedError, formatImportMdxReport, importMdx, loadSiteMdxAdapter, } from "./lib/import-mdx.js";
+import { ParseError } from "./parse-args.js";
+import { readSiteRoster } from "./site-roster.js";
+import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, readSiteTopology, } from "./topology.js";
+/** The environment variable the agent key is read from — and nowhere else. */
+export const AGENT_KEY_ENV_VAR = "AILK_AGENT_KEY";
+/** The environment variable the workspace id is read from when no flag names one. */
+export const WORKSPACE_ID_ENV_VAR = "AILK_WORKSPACE_ID";
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export class SeedWorkspaceRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "SeedWorkspaceRefusedError";
+    }
+}
+function refuse(message) {
+    throw new SeedWorkspaceRefusedError(`seed-workspace: ${message} Nothing was sent.`);
+}
+/** A value given, or `undefined` for an absent or empty one (D2). */
+function given(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+// ── The command (D4) ────────────────────────────────────────────────────────
+export async function seedWorkspace(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const env = opts.env ?? process.env;
+    const onLine = opts.onLine ?? (() => undefined);
+    let roster;
+    try {
+        roster = readSiteRoster(targetDir);
+    }
+    catch (err) {
+        if (!(err instanceof AddModuleRefusedError))
+            throw err;
+        refuse(`${err.message}.`);
+    }
+    if (roster === undefined) {
+        refuse(`${opts.targetDir} has no .ailk-site-manifest.json, so it is not a starter scaffold.`);
+    }
+    let topology;
+    try {
+        topology = readSiteTopology(targetDir);
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        refuse(`${err.message}.`);
+    }
+    if (topology === "spoke") {
+        refuse(`${opts.targetDir} is a spoke: its pages are its own MDX files, and its hub owns the workspace.`);
+    }
+    const apiKey = given(env[AGENT_KEY_ENV_VAR]);
+    if (apiKey === undefined) {
+        refuse(`set ${AGENT_KEY_ENV_VAR} to an agent key with the content-edit grant. It is read from the environment only — never a flag or a file.`);
+    }
+    const workspaceId = given(opts.workspaceId) ?? given(env[WORKSPACE_ID_ENV_VAR]);
+    if (workspaceId === undefined) {
+        refuse(`no workspace id was given. Pass --workspace <wksp_id>, or set ${WORKSPACE_ID_ENV_VAR}.`);
+    }
+    const flagOrigin = given(opts.apiUrl);
+    const source = flagOrigin !== undefined ? "--api-url" : HUB_ORIGIN_ENV_VAR;
+    const rawOrigin = flagOrigin ?? given(env[HUB_ORIGIN_ENV_VAR]);
+    if (rawOrigin === undefined) {
+        refuse(`no API origin was given. Pass --api-url <origin>, or set ${HUB_ORIGIN_ENV_VAR}.`);
+    }
+    let origin;
+    try {
+        origin = normalizeHubUrl(rawOrigin);
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        refuse(`the API origin must be an https: origin (http: only on a loopback host) with no path, query, fragment or credentials (from ${source}).`);
+    }
+    onLine(`Seeding ${opts.targetDir} into workspace ${workspaceId} at ${origin} (from ${source}).`);
+    const adapters = opts.adapters ?? (await loadSiteMdxAdapter(targetDir));
+    const result = await importMdx({
+        contentRoot: join(targetDir, "content"),
+        adapters,
+        apiOrigin: origin,
+        workspaceId,
+        apiKey,
+        ...(opts.fetch !== undefined && { fetch: opts.fetch }),
+        ...(opts.sleep !== undefined && { sleep: opts.sleep }),
+        onLine,
+    });
+    // The report's count line alone: no page rows.
+    onLine(formatImportMdxReport({ pages: [], counts: result.counts }).trimEnd());
+    const { failed } = result.counts;
+    if (failed > 0) {
+        onLine(`${failed} page(s) were not seeded. Fix them and re-run: create-ailk seed-workspace ${opts.targetDir}`);
+    }
+    return { result, exitCode: failed > 0 ? 1 : 0 };
+}
+const SEED_CREDENTIALS = [
+    HUB_ORIGIN_ENV_VAR,
+    WORKSPACE_ID_ENV_VAR,
+    AGENT_KEY_ENV_VAR,
+];
+/** `A`, `A and B`, `A, B and C`. */
+function joinNames(names) {
+    return names.length <= 1
+        ? names.join("")
+        : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+}
+/** What the scaffold does about seeding, decided in D3's order. */
+export function scaffoldSeedPlan(input) {
+    if (input.topology === "spoke")
+        return { kind: "not-applicable" };
+    if (!input.modules.includes("workspace") &&
+        !input.modules.includes("multi-tenant")) {
+        return { kind: "not-applicable" };
+    }
+    const unset = SEED_CREDENTIALS.filter((name) => given(input.env[name]) === undefined);
+    if (unset.length > 0) {
+        return {
+            kind: "skip",
+            reason: `Workspace seeding skipped: ${joinNames(unset)} ${unset.length === 1 ? "is" : "are"} not set.`,
+        };
+    }
+    if (!input.installed) {
+        return {
+            kind: "skip",
+            reason: "Workspace seeding skipped: the site's dependencies are not installed (pass --install, or run pnpm install first).",
+        };
+    }
+    return { kind: "seed" };
+}
+/**
+ * The whole scaffold-time step: plan, then print the skip or run the seed. A
+ * refusal is printed, never thrown, and sets no exit code (D6).
+ */
+export async function runScaffoldSeed(opts) {
+    const plan = scaffoldSeedPlan(opts);
+    if (plan.kind === "not-applicable")
+        return;
+    if (plan.kind === "skip") {
+        opts.onLine(plan.reason);
+        opts.onLine(`  To seed it later: ${AGENT_KEY_ENV_VAR}=<key> create-ailk seed-workspace ${opts.targetDir} --api-url <origin> --workspace <wksp_id>`);
+        return;
+    }
+    opts.onLine("Seeding the workspace:");
+    try {
+        await seedWorkspace({
+            targetDir: opts.targetDir,
+            env: opts.env,
+            onLine: opts.onLine,
+            ...(opts.adapters !== undefined && { adapters: opts.adapters }),
+            ...(opts.fetch !== undefined && { fetch: opts.fetch }),
+            ...(opts.sleep !== undefined && { sleep: opts.sleep }),
+        });
+    }
+    catch (err) {
+        if (!(err instanceof SeedWorkspaceRefusedError) &&
+            !(err instanceof ImportMdxRefusedError)) {
+            throw err;
+        }
+        opts.onLine(err.message);
+    }
+}
+export const SEED_WORKSPACE_HELP = `create-ailk seed-workspace — import a starter's pages into its workspace.
+
+Usage:
+  AILK_AGENT_KEY=<key> create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <wksp_id>]
+
+Arguments:
+  <dir>                    The site. Defaults to the current dir.
+
+Options:
+  --api-url <origin>       The site's API origin. Else AILK_API_URL. https:
+                           only (http: on localhost or 127.0.0.1).
+  --workspace <wksp_id>    The workspace the pages are written to. Else
+                           AILK_WORKSPACE_ID.
+  -h, --help               Show this help.
+
+Each content/en/<Type>/<slug>.mdx page is written to the workspace as a
+draft through the API's content routes, with the agent key, which is read
+from AILK_AGENT_KEY only and needs the content-edit grant. Each page prints
+created, updated, unchanged, skipped or failed, so a re-run is safe. The
+site's dependencies must be installed. Exit 0 when every page was seeded, 1
+when any failed, 2 on a refusal (nothing is sent).
+`;
+export function parseSeedWorkspaceArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            options: {
+                "api-url": { type: "string" },
+                workspace: { type: "string" },
+                help: { type: "boolean", default: false, short: "h" },
+            },
+        });
+    }
+    catch (err) {
+        throw new ParseError(`seed-workspace: ${err.message}`);
+    }
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`seed-workspace takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return {
+        target,
+        apiUrl: parsed.values["api-url"],
+        workspaceId: parsed.values.workspace,
+        help: parsed.values.help === true,
+    };
+}

package/dist/template-record.d.ts

@@ -49,14 +49,23 @@ export interface TemplateRecord {
 export declare class TemplateRecordError extends Error {
     constructor(message: string);
 }
+export interface ParseTemplateRecordOptions {
+    /**
+     * Called with each traversal-safe `files` key that is not a recordable path
+     * — a path a later create-ailk stopped recording, such as a generated file
+     * (#10173) — instead of refusing the record. The row is left out of the
+     * result. An unsafe key still refuses.
+     */
+    onUnrecordable?: (key: string) => void;
+}
 /**
  * Parse `.ailk-template-files.json` text, refusing — naming the field — on:
  * JSON that does not parse; `schema !== 1`; an unknown top-level key; an
- * empty `projectName`; a `files` key that is not a recordable path; a
- * `sha256` that is not 64 lowercase hex; a `version` that is not a semver
- * string (#8522 D1).
+ * empty `projectName`; a `files` key that is not a recordable path (unless
+ * `onUnrecordable` takes it); a `sha256` that is not 64 lowercase hex; a
+ * `version` that is not a semver string (#8522 D1).
  */
-export declare function parseTemplateRecord(text: string): TemplateRecord;
+export declare function parseTemplateRecord(text: string, opts?: ParseTemplateRecordOptions): TemplateRecord;
 /** `record` as `scaffold()` and `update` write it: sorted keys, trailing newline. */
 export declare function serializeTemplateRecord(record: TemplateRecord): string;
 export interface PlanTemplateRecordOptions {

package/dist/template-record.js

@@ -128,11 +128,11 @@ function isSafeRecordKey(key) {
 /**
  * Parse `.ailk-template-files.json` text, refusing — naming the field — on:
  * JSON that does not parse; `schema !== 1`; an unknown top-level key; an
- * empty `projectName`; a `files` key that is not a recordable path; a
- * `sha256` that is not 64 lowercase hex; a `version` that is not a semver
- * string (#8522 D1).
+ * empty `projectName`; a `files` key that is not a recordable path (unless
+ * `onUnrecordable` takes it); a `sha256` that is not 64 lowercase hex; a
+ * `version` that is not a semver string (#8522 D1).
  */
-export function parseTemplateRecord(text) {
+export function parseTemplateRecord(text, opts = {}) {
     let doc;
     try {
         doc = JSON.parse(text);
@@ -167,6 +167,10 @@ export function parseTemplateRecord(text) {
             throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files" has an unsafe key "${key}"`);
         }
         if (!isRecordable(key)) {
+            if (opts.onUnrecordable !== undefined) {
+                opts.onUnrecordable(key);
+                continue;
+            }
             throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files" has a key "${key}" that is not a recordable path`);
         }
         if (typeof value !== "object" || value === null) {

package/dist/update.d.ts

@@ -40,11 +40,24 @@ export interface UpdateResult {
         path: string;
         reason: string;
     }>;
-    /** Per file left under review or skipped, the template tests importing it that stay at the site's version (#8704). */
+    /**
+     * Per file left under review or skipped — or a relative import the written
+     * code names that the site will not have (`missing`) — the template tests
+     * (#8704) and the other template files (`importers`, #10173) held with it
+     * — the files that import it, or, when it is a file staying at the site's
+     * version, the written files it imports — which keep the site's version so
+     * the tree never imports what it lacks.
+     */
     heldBack: Array<{
         file: string;
         tests: string[];
+        importers?: string[];
+        missing?: true;
     }>;
+    /** The `project.yaml` `env_contract` rows added for env vars the written files read (#10172). */
+    envRowsAdded?: string[];
+    /** Record rows dropped because the path is no longer recordable (#10173). */
+    droppedRows?: string[];
     /** The mdx-body pages under `content/` given a `# ` heading this run (#7495). */
     headingsAdded: string[];
     backfilled?: {
@@ -52,6 +65,23 @@ export interface UpdateResult {
         files: number;
     };
 }
+/**
+ * The site's messages catalog with every key the template's copy has and it
+ * lacks (#10173): the site's values always win, nothing is removed, and the
+ * keys it gains follow its own. A key that is an object on one side and a
+ * value on the other is a conflict, and nothing is merged.
+ */
+export declare function mergeMessagesAdditively(ours: string, theirs: string): {
+    status: "merged";
+    text: string;
+    added: number;
+} | {
+    status: "conflict";
+    keys: string[];
+} | {
+    status: "invalid";
+    reason: string;
+};
 export declare function updateSite(opts: UpdateSiteOptions): Promise<UpdateResult>;
 /** The printed report (D9): one section per non-empty list, in order. */
 export declare function formatUpdateReport(result: UpdateResult): string;
@@ -59,6 +89,6 @@ export interface UpdateArgs {
     target: string | undefined;
     help: boolean;
 }
-export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the\napp jest configs require, whose template copy changed is overwritten. An\nedited file whose template copy also changed is three-way merged with\n`git` (git must be on PATH); a conflict leaves the file alone and is\nlisted under \"Needs review\". Every template test that imports a file\nleft under \"Needs review\" or \"Skipped\" (by a relative import) is held at the\nsite's version with it, its record entry is not advanced, and it is listed\nunder \"Held back with <file>\" \u2014 reconcile the file, then run update again to\nbring its tests forward. Every other file in the run still updates.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. A site scaffolded before\n@working-theory/mcp-server has its copied apps/mcp moved to the boot set:\nthe server and each module's paid MCP pack join apps/mcp/package.json, the\ncopied server files go, and apps/mcp/src/lib/paid-tools.generated.ts is\nrewritten on every run. A site scaffolded before @working-theory/api has its\ncopied apps/api moved to the boot file: the app becomes @working-theory/app-api,\nthe package and the six @working-theory/api-<module> packages join\napps/api/package.json, its bins and build:vercel delegate to the package, and\nthe copied server files go. Run `pnpm install` after either move, since the\napp's package.json gained dependencies. Each mdx-body page in content/ with no\n'# ' heading gets its title and description written into its body as its\nheading and intro, listed under \"Page heading added\"; a page with one heading\nis left as it is, and one with several, or one whose frontmatter it cannot\nread, is listed under \"Needs review\". Commit before running, and review the\ndiff after.\n";
+export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the\napp jest configs require, whose template copy changed is overwritten. An\nedited file whose template copy also changed is three-way merged with\n`git` (git must be on PATH); a conflict leaves the file alone and is\nlisted under \"Needs review\"; an apps/web/messages catalog instead gains the\ntemplate's new keys and keeps every value it has, and is reviewed only when a\nkey is an object on one side and a value on the other. Every template file,\ntest or not, that imports a file left under \"Needs review\" or \"Skipped\" (by a\nrelative or @/ import, transitively) is held at the site's version with it,\nits record entry is not advanced, and it is listed under \"Held back with\n<file>\" \u2014 reconcile the file, then run update again to bring it forward. A\nwritten file whose import names a file the site will not have is held the\nsame way, under \"Held back with <file> (not in this site)\". Every other file\nin the run still updates. When project.yaml has an env_contract block, each\nenv var the written files read that has no row gains one; no row is edited.\nA record row at a path create-ailk no longer records is dropped and listed.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. A site scaffolded before\n@working-theory/mcp-server has its copied apps/mcp moved to the boot set:\nthe server and each module's paid MCP pack join apps/mcp/package.json, the\ncopied server files go, and apps/mcp/src/lib/paid-tools.generated.ts is\nrewritten on every run. A site scaffolded before @working-theory/api has its\ncopied apps/api moved to the boot file: the app becomes @working-theory/app-api,\nthe package and the six @working-theory/api-<module> packages join\napps/api/package.json, its bins and build:vercel delegate to the package, and\nthe copied server files go. Run `pnpm install` after either move, since the\napp's package.json gained dependencies. Each mdx-body page in content/ with no\n'# ' heading gets its title and description written into its body as its\nheading and intro, listed under \"Page heading added\"; a page with one heading\nis left as it is, and one with several, or one whose frontmatter it cannot\nread, is listed under \"Needs review\". Commit before running, and review the\ndiff after.\n";
 /** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */
 export declare function parseUpdateArgs(argv: string[]): UpdateArgs;