create-ailk 0.28.1 → 0.29.0

package/README.md

@@ -552,6 +552,128 @@ deliverables, pricing, registers, listings — so a flow that needs one is
 authored in the hub's Admin; once it carries one, the hub refuses a seed of
 that flow (`409 slug_owned`) rather than delete the block.
 
+### Seeding the workspace
+
+On a site with an Admin (the `workspace` or `multi-tenant` module), the
+starter's pages are also rows in the site's workspace, so the Admin's Docs
+lists Home, About, Contact and every other roster page on first open.
+`seed-workspace` writes them there: each `content/en/<Type>/<slug>.mdx` page
+becomes one draft `text/page` Artifact.
+
+```bash
+AILK_AGENT_KEY=<agent key> create-ailk seed-workspace ./my-site --api-url <api origin> --workspace <wksp_id>
+```
+
+- The API origin is `--api-url`, else `AILK_API_URL`; it must be `https:` (or
+  `http:` on a loopback host). The workspace id is `--workspace`, else
+  `AILK_WORKSPACE_ID`. The first line printed names the workspace, the origin
+  and the origin's source, before any request.
+- The agent key is read from `AILK_AGENT_KEY` only — never a flag or a file —
+  and never printed. An owner issues it in the Admin with the `content-edit`
+  grant.
+- Each page prints `created`, `updated`, `unchanged`, `skipped` or `failed`,
+  then a count line. A re-run creates nothing and reports every page
+  `unchanged`. An agent writes ten times a minute, so a first seed of about
+  thirty pages waits out the rate limit a few times.
+- The site's dependencies must be installed (`pnpm install`): the pages are
+  read through the site's own `@working-theory/content-adapters`.
+- The API must run with `content-write` and a tenancy module (`workspace` or
+  `multi-tenant`) in `AILK_ENABLED_MODULES`. Without them the content routes
+  are not served and every page fails `404`.
+- Exit 0 when every page was seeded, 1 when any failed, 2 on a refusal (no
+  `.ailk-site-manifest.json`, a spoke, a missing key, workspace id or origin,
+  the adapter not installed), which sends nothing.
+
+`pnpm create ailk` runs the same seed as its last step, after `--install`,
+when the site has an Admin and `AILK_API_URL`, `AILK_WORKSPACE_ID` and
+`AILK_AGENT_KEY` are all set. When the site has an Admin but one is missing,
+or `--install` was not passed, it prints that seeding was skipped and the
+command above. A site with no Admin, or a spoke, prints nothing about it. A
+seed that fails or is refused at scaffold time prints why and never fails the
+scaffold; `seed-workspace` is where a seed's result is an exit code.
+
+On a site carrying `signal-collectors`, the two `ThankYouPage` seeds
+`contact` and `newsletter` share an address (locale and slug) with the
+`ContactPage` and `NewsletterSignup` pages, so those two are reported
+`failed` and the seed exits 1 until one side's slug changes.
+
+To check a seed:
+
+```bash
+cd my-site
+# 1. Re-run the seed: nothing may be created, updated or fail.
+AILK_AGENT_KEY=<agent key> create-ailk seed-workspace . --api-url <api origin> --workspace <wksp_id>
+#    expect the count line: created 0 · updated 0 · unchanged <N> · skipped <S> · failed 0
+# 2. Read the workspace's pages back: at least <N> rows.
+curl -sS -H "authorization: Bearer $AILK_AGENT_KEY" "<api origin>/v1/workspaces/<wksp_id>/content?locale=en" | jq '.data | length'
+```
+
+### Migrating an existing site's content
+
+`migrate-content` imports the pages of a site that was not seeded at
+scaffold time — a site with no `.ailk-site-manifest.json`, or a spoke — into
+a workspace: each `content/en/<Type>/<slug>.mdx` page, and each legacy
+`content/<Type>/<slug>.mdx` page, becomes one draft `text/page` Artifact.
+
+```bash
+AILK_AGENT_KEY=<agent key> create-ailk migrate-content ./my-site --api-url <api origin> --workspace <wksp_id>
+AILK_AGENT_KEY=<agent key> create-ailk migrate-content ./my-site --apply --api-url <api origin> --workspace <wksp_id>
+```
+
+- It is a dry run by default and writes nothing: it reads the workspace,
+  prints what `--apply` would do to each page — `create`, `update`,
+  `unchanged`, `skipped` or `failed` — then a count line. A dry run never sends
+  a write: its transport answers a create or an update itself.
+- `--apply` writes. Each page prints `created`, `updated`, `unchanged`,
+  `skipped` or `failed`, then a count line; a re-run creates nothing and
+  reports every page `unchanged`.
+- The API origin is `--api-url`, else `AILK_API_URL`; it must be `https:` (or
+  `http:` on a loopback host). The workspace id is `--workspace`, else
+  `AILK_WORKSPACE_ID`. The agent key is read from `AILK_AGENT_KEY` only —
+  never a flag or a file — and never printed; it needs the `content-edit`
+  grant. The first line printed names the workspace, the origin and the
+  origin's source, before any request.
+- On a spoke, the workspace is its hub's: pass the hub's API origin and the
+  spoke's workspace on the hub.
+- Pages land as drafts and nothing is published, so the live site keeps
+  serving its MDX files and does not change.
+- The plan cannot see a write the API would refuse at `--apply` (a conflict
+  with an edit made in between, or a server error): such a page is planned
+  `create` or `update`. A page whose content fails its page type is planned
+  and then saved with the errors the editor shows, not `failed`.
+- The site's dependencies must be installed (`pnpm install`): the pages are
+  read through the site's own `@working-theory/content-adapters`.
+- Exit 0 when no page failed, 1 when any did (in a dry run, when any would), 2
+  on a refusal (a missing key, workspace id or origin, no `content/`, the
+  adapter not installed), which sends nothing.
+
+To migrate a live site and prove a visitor sees no change (samhenry.org's
+sequence; the placeholders are yours to fill):
+
+```bash
+cd <the samhenry repo>                 # dependencies installed (pnpm install)
+export AILK_AGENT_KEY=<agent key>      # content-edit, issued in the hub's Admin for the Sam Henry workspace
+API=<hub api origin>; WS=<wksp_id>
+# 0. Snapshot the live site before anything is written.
+curl -sS https://samhenry.org/sitemap.xml | grep -o '<loc>[^<]*</loc>' | sed -e 's/<loc>//' -e 's/<\/loc>//' | sort -u > urls.txt
+mkdir -p before after
+n=0; while read -r u; do n=$((n+1)); curl -sS -o "before/$n.html" -w '%{http_code} %{url_effective}\n' "$u"; done < urls.txt > before/status.txt
+# 1. Dry run: the plan; nothing is written. Expect failed 0 and exit 0.
+npx create-ailk@<version> migrate-content . --api-url "$API" --workspace "$WS"
+# 2. Apply. Expect: created <N> · updated 0 · unchanged 0 · skipped <S> · failed 0
+npx create-ailk@<version> migrate-content . --apply --api-url "$API" --workspace "$WS"
+# 3. Re-run: nothing changes. Expect: created 0 · updated 0 · unchanged <N> · skipped <S> · failed 0
+npx create-ailk@<version> migrate-content . --apply --api-url "$API" --workspace "$WS"
+# 4. Docs lists them: at least <N> rows (exactly <N> on a workspace that had no pages).
+printf 'authorization: Bearer %s\n' "$AILK_AGENT_KEY" | curl -sS -H @- "$API/v1/workspaces/$WS/content?locale=en" | jq '.data | length'
+# 5. The live diff: re-fetch the same URLs and compare. Expect no output from diff.
+n=0; while read -r u; do n=$((n+1)); curl -sS -o "after/$n.html" -w '%{http_code} %{url_effective}\n' "$u"; done < urls.txt > after/status.txt
+diff -r before after && echo "live site unchanged"
+```
+
+A non-empty diff is a finding: stop and report it before migrating another
+site.
+
 ### A spoke's declared environment
 
 A spoke scaffold's `pnpm preflight` and CI run `pnpm env:declared`: every
@@ -638,7 +760,8 @@ The network invariant (#6759 D6), in full:
 3. Substitutes `workspace:*` references in every `package.json` with the matching `@working-theory/*` semver from npm — versions are pinned at npm-publish time.
 4. Substitutes `{{PROJECT_NAME}}`, `{{COMPANY_NAME}}`, `{{COMPANY_DOMAIN}}` markers in `templates/README.md` from the target directory name (and CLI flags / interactive prompts in future versions).
 5. Derives and writes `architecture.yaml` (the site's code-boundary config) from the selected module set — see below.
-6. Prints next steps: `cd <dir> && pnpm install && pnpm dev`.
+6. On a site with an Admin, seeds the starter's pages into its workspace when `--install` ran and `AILK_API_URL`, `AILK_WORKSPACE_ID` and `AILK_AGENT_KEY` are set, else prints why not and the `seed-workspace` command — see [Seeding the workspace](#seeding-the-workspace).
+7. Prints next steps: `cd <dir> && pnpm install && pnpm dev`.
 
 ## `architecture.yaml` is derived from the module set
 

package/dist/cli.js

@@ -14,6 +14,15 @@
  *      on a `seed-flows` subcommand: send a spoke's declared flows/*.json to
  *      its hub with the key from AILK_SPOKE_KEY, print one line per flow,
  *      exit 1 if any failed (2 on a refusal it names, nothing sent) (#7876)
+ *      on a `seed-workspace` subcommand: import a starter's content/ pages
+ *      into its workspace with the agent key from AILK_AGENT_KEY, print one
+ *      line per page and the count line, exit 1 if any failed (2 on a
+ *      refusal it names, nothing sent) (#10204)
+ *      on a `migrate-content` subcommand: plan an existing site's content/
+ *      pages against its workspace — or, with --apply, write them — with the
+ *      agent key from AILK_AGENT_KEY, print one line per page and the count
+ *      line, exit 1 if any failed (2 on a refusal it names, nothing sent)
+ *      (#10207)
  *      on a `sync-routes` subcommand: parse its own argv, run syncRoutesSync(),
  *      print the report, exit (1 iff routes are missing in check mode)
  *      on a `license set` subcommand: write the key into the scaffold, push it
@@ -31,7 +40,11 @@
  *      template's own bundle (#5481), then validates + copies the local
  *      template, then merges each fetched bundle in, the site template last
  *   5. when --install: spawn `pnpm install` (cwd = target, hard-coded argv)
- *   6. print next-steps message
+ *   6. on a hub with an Admin: seed the starter's pages into the workspace
+ *      when --install ran and AILK_API_URL, AILK_WORKSPACE_ID and
+ *      AILK_AGENT_KEY are set, else print why not and the command that seeds
+ *      it later; never fails the scaffold (#10204)
+ *   7. print next-steps message
  *
  * Any thrown error (parse failure, validation failure, copy failure,
  * `LicenseRequiredError`) is caught at the top level: stderr
@@ -55,14 +68,17 @@ import { ADOPT_HELP, AdoptRefusedError, adoptSite, formatAdoptReport, parseAdopt
 import { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
 import { CLAUDE_MD_CHECK_PATH } from "./claude-md.js";
 import { buildScaffoldMarkers } from "./copy.js";
+import { ImportMdxRefusedError } from "./lib/import-mdx.js";
 import { assertKeyedOrFreeReleased, assertReleased } from "./lib/module-license-gate.js";
 import { withNpmTokenUserConfig } from "./lib/npm-auth.js";
 import { FREE_PREREQUISITES_NOTE, LICENSED_PREREQUISITES_NOTE, isLicensedInstall, proCallout, } from "./lib/pro-callout.js";
 import { LICENSE_SET_HELP, runLicenseSet } from "./license-set.js";
-import { PLUGIN_INSTALL_LINES, helpText, parseCliArgs, parseModules, resolveCliShape, toScaffoldOptions, } from "./parse-args.js";
+import { MIGRATE_CONTENT_HELP, MigrateContentRefusedError, migrateContent, parseMigrateContentArgs, } from "./migrate-content.js";
+import { PLUGIN_INSTALL_LINES, ParseError, helpText, parseCliArgs, parseModules, resolveCliShape, toScaffoldOptions, } from "./parse-args.js";
 import { addModule, removeModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, } from "./programmatic.js";
 import { REMOVE_MODULE_HELP, RemoveModuleRefusedError, formatRemoveModuleReport, parseRemoveModuleArgs, } from "./remove-module.js";
 import { SEED_FLOWS_HELP, SeedFlowsRefusedError, parseSeedFlowsArgs, seedFlows, } from "./seed-flows.js";
+import { SEED_WORKSPACE_HELP, SeedWorkspaceRefusedError, parseSeedWorkspaceArgs, runScaffoldSeed, seedWorkspace, } from "./seed-workspace.js";
 import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
 import { UPDATE_HELP, UpdateRefusedError, formatUpdateReport, parseUpdateArgs, updateSite, } from "./update.js";
@@ -271,6 +287,67 @@ async function main() {
             process.exit(err.exitCode);
         }
     }
+    // `seed-workspace [dir]` (#10204): import a starter's content/ pages into
+    // its workspace with the agent key from AILK_AGENT_KEY. Exit 1 when any
+    // page failed; a refusal it names (a bad argv, no roster of record, a
+    // spoke, a missing credential, no installed adapter) exits 2 before
+    // anything is sent.
+    if (argv[0] === "seed-workspace") {
+        try {
+            const args = parseSeedWorkspaceArgs(argv.slice(1));
+            if (args.help) {
+                process.stdout.write(SEED_WORKSPACE_HELP);
+                process.exit(0);
+            }
+            const { exitCode } = await seedWorkspace({
+                targetDir: args.target ?? process.cwd(),
+                apiUrl: args.apiUrl,
+                workspaceId: args.workspaceId,
+                onLine: (line) => process.stdout.write(`${line}\n`),
+            });
+            process.exit(exitCode);
+        }
+        catch (err) {
+            if (!(err instanceof ParseError) &&
+                !(err instanceof SeedWorkspaceRefusedError) &&
+                !(err instanceof ImportMdxRefusedError)) {
+                throw err;
+            }
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(2);
+        }
+    }
+    // `migrate-content [dir]` (#10207): import an existing site's content/
+    // pages into its workspace — a dry run that writes nothing unless --apply.
+    // Takes a site with no manifest and a spoke. Exit 1 when any page failed; a
+    // refusal it names (a bad argv, a missing credential, no installed adapter)
+    // exits 2 before anything is sent.
+    if (argv[0] === "migrate-content") {
+        try {
+            const args = parseMigrateContentArgs(argv.slice(1));
+            if (args.help) {
+                process.stdout.write(MIGRATE_CONTENT_HELP);
+                process.exit(0);
+            }
+            const { exitCode } = await migrateContent({
+                targetDir: args.target ?? process.cwd(),
+                apply: args.apply,
+                apiUrl: args.apiUrl,
+                workspaceId: args.workspaceId,
+                onLine: (line) => process.stdout.write(`${line}\n`),
+            });
+            process.exit(exitCode);
+        }
+        catch (err) {
+            if (!(err instanceof ParseError) &&
+                !(err instanceof MigrateContentRefusedError) &&
+                !(err instanceof ImportMdxRefusedError)) {
+                throw err;
+            }
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(2);
+        }
+    }
     // Subcommand dispatch, ahead of the flag parser: `sync-routes` has its own
     // argv shape (#4986). Check mode exits 1 iff a template route is missing;
     // locally modified routes are reported but do not fail; --apply exits 0.
@@ -393,6 +470,8 @@ async function main() {
             "\n" +
             SEED_FLOWS_HELP +
             "\n" +
+            SEED_WORKSPACE_HELP +
+            "\n" +
             APPLY_DESIGN_HELP +
             "\n" +
             UPDATE_HELP +
@@ -486,6 +565,17 @@ async function main() {
             throw new Error(`pnpm install failed in ${targetAbs} (exit ${result.status}). Run it manually after fixing the issue.`);
         }
     }
+    // #10204 — on a hub with an Admin, seed the starter's pages into the
+    // workspace, or say why not and how to later. A refusal is printed, never
+    // thrown: the site was written and is valid either way (D6).
+    await runScaffoldSeed({
+        targetDir: targetAbs,
+        topology: opts.topology,
+        modules: effectiveModules,
+        installed: opts.install === true,
+        env: process.env,
+        onLine: (line) => process.stdout.write(`${line}\n`),
+    });
     // Next-steps message. A licensed install (#6480) is not told it needs no
     // licence key, and is not pitched the Pro tier it already owns. Reads the
     // EFFECTIVE module set (#6759 D6) — result.modules already carries any

package/dist/lib/import-mdx.d.ts

@@ -0,0 +1,59 @@
+/** A refusal the CLI exits 2 on, thrown before any file is read or request sent. */
+export declare class ImportMdxRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+/** The adapter package's two members the importer needs, typed structurally. */
+export interface MdxAdapterModule {
+    createMdxAdapter(o: {
+        contentRoot: string;
+        defaultLocale?: string;
+    }): {
+        getPageSource(type: string, slug: string, locale?: string): Promise<{
+            frontmatter: Record<string, unknown>;
+            body: string;
+        } | null>;
+    };
+    SCHEMA_ORG_TYPES: readonly string[];
+}
+export interface ImportMdxOptions {
+    /** The site's content root (`content/`). */
+    contentRoot: string;
+    adapters: MdxAdapterModule;
+    /** The API's origin: https, or http on a loopback host. */
+    apiOrigin: string;
+    workspaceId: string;
+    /** An agent key; sent only as a bearer token. */
+    apiKey: string;
+    /** The locale tree imported; defaults to `en`. */
+    defaultLocale?: string;
+    /** 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 is decided, and each wait; defaults to nothing. */
+    onLine?: (line: string) => void;
+}
+export type ImportMdxOutcome = {
+    path: string;
+    result: "created" | "updated" | "unchanged";
+    type: string;
+    slug: string;
+} | {
+    path: string;
+    result: "skipped" | "failed";
+    reason: string;
+};
+export type ImportMdxResultKind = ImportMdxOutcome["result"];
+export interface ImportMdxResult {
+    pages: ImportMdxOutcome[];
+    counts: Record<ImportMdxResultKind, number>;
+}
+/** The whole report, one line per page and a final count line. */
+export declare function formatImportMdxReport(result: ImportMdxResult): string;
+export declare function importMdx(opts: ImportMdxOptions): Promise<ImportMdxResult>;
+/**
+ * The site's installed adapter package, resolved from its `apps/web` — never
+ * create-ailk's own `node_modules`.
+ */
+export declare function loadSiteMdxAdapter(siteRoot: string): Promise<MdxAdapterModule>;