create-ailk 0.15.0 → 0.17.0

package/dist/cli.js

@@ -7,6 +7,12 @@
  *      addModule(), print the report, exit (2 on a refusal it names)
  *      on an `add-route` subcommand: add one route surface to an existing
  *      site, print the report, exit (2 on a refusal it names) (#6947)
+ *      on an `adopt` subcommand: record an existing site's topology and
+ *      pattern version in its manifest, print the report, exit (2 on a
+ *      refusal it names) (#7875)
+ *      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 `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
@@ -40,6 +46,7 @@ import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ADD_MODULE_HELP, AddModuleRefusedError, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
 import { ADD_ROUTE_HELP, AddRouteRefusedError, addRouteToScaffold, formatAddRouteReport, parseAddRouteArgs, } from "./add-route.js";
+import { ADOPT_HELP, AdoptRefusedError, adoptSite, formatAdoptReport, parseAdoptArgs, } from "./adopt.js";
 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";
@@ -48,6 +55,7 @@ import { FREE_PREREQUISITES_NOTE, LICENSED_PREREQUISITES_NOTE, isLicensedInstall
 import { LICENSE_SET_HELP, runLicenseSet } from "./license-set.js";
 import { PLUGIN_INSTALL_LINES, helpText, parseCliArgs, parseModules, resolveCliShape, toScaffoldOptions, } from "./parse-args.js";
 import { addModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCatalogSync, syncClaudeMdSync, syncRoutesSync, } from "./programmatic.js";
+import { SEED_FLOWS_HELP, SeedFlowsRefusedError, parseSeedFlowsArgs, seedFlows, } from "./seed-flows.js";
 import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -161,6 +169,62 @@ async function main() {
         }
         process.exit(0);
     }
+    // `adopt [dir]` (#7875): record an existing site's topology and pattern
+    // version in its manifest, once. Writes that one file and nothing else. A
+    // refusal it names (a half-trimmed tree, a second run, a missing or
+    // contradicting --template / --modules, a legacy roster) exits 2.
+    if (argv[0] === "adopt") {
+        const args = parseAdoptArgs(argv.slice(1));
+        if (args.help) {
+            process.stdout.write(ADOPT_HELP);
+            process.exit(0);
+        }
+        try {
+            const result = adoptSite({
+                targetDir: args.target ?? process.cwd(),
+                templatesDir: resolve(PKG_ROOT, "templates"),
+                siteTemplatesDir: resolve(PKG_ROOT, "site-templates"),
+                template: args.template,
+                modules: args.modules,
+            });
+            process.stdout.write(formatAdoptReport(result));
+        }
+        catch (err) {
+            if (!(err instanceof AdoptRefusedError) &&
+                !(err instanceof AddModuleRefusedError)) {
+                throw err;
+            }
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+        process.exit(0);
+    }
+    // `seed-flows [dir]` (#7876): send a spoke's declared flows/*.json to its
+    // hub with the spoke key from AILK_SPOKE_KEY. Exit 1 when any flow failed;
+    // a refusal it names (a hub, a bad file, no key, no valid hub origin)
+    // exits 2 before anything is sent.
+    if (argv[0] === "seed-flows") {
+        const args = parseSeedFlowsArgs(argv.slice(1));
+        if (args.help) {
+            process.stdout.write(SEED_FLOWS_HELP);
+            process.exit(0);
+        }
+        try {
+            const result = await seedFlows({
+                targetDir: args.target ?? process.cwd(),
+                hubUrl: args.hubUrl,
+                dryRun: args.dryRun,
+                onLine: (line) => process.stdout.write(`${line}\n`),
+            });
+            process.exit(result.exitCode);
+        }
+        catch (err) {
+            if (!(err instanceof SeedFlowsRefusedError))
+                throw err;
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+    }
     // 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.
@@ -247,6 +311,10 @@ async function main() {
             "\n" +
             ADD_ROUTE_HELP +
             "\n" +
+            ADOPT_HELP +
+            "\n" +
+            SEED_FLOWS_HELP +
+            "\n" +
             APPLY_DESIGN_HELP +
             "\n" +
             LICENSE_SET_HELP);
@@ -319,7 +387,7 @@ async function main() {
     // marketing-site-free` still rides the no-key case (record D11): its
     // `requires` is all-free, so it installs from the shipped
     // `site-templates/` tree with no key and no request.
-    const { targetDir: targetAbs, surfaces, starter, modules: effectiveModules, droppedModules, hubOrigin, } = await scaffold(toScaffoldOptions(opts));
+    const { targetDir: targetAbs, surfaces, starter, modules: effectiveModules, droppedModules, hubOrigin, hubSignInOrigin, } = await scaffold(toScaffoldOptions(opts));
     const isSpoke = opts.topology === "spoke";
     // The starter scaffold() resolved — from --template, or from --shape (#6754 D4).
     const templateName = starter?.template ?? opts.template;
@@ -351,7 +419,7 @@ async function main() {
         // #7426 — a spoke says so, and names what its hosts must carry (D3).
         ...(isSpoke
             ? [
-                `Topology: spoke — no apps/api, no database, no sign-in${opts.mcp === false ? ", no apps/mcp" : "; apps/mcp is a stateless front"}.`,
+                `Topology: spoke — no apps/api, no database, ${hubSignInOrigin !== undefined ? "sign-in through the hub" : "no sign-in"}${opts.mcp === false ? ", no apps/mcp" : "; apps/mcp is a stateless front"}.`,
                 ...(droppedModules !== undefined && droppedModules.length > 0
                     ? [
                         `Not carried on a spoke: ${droppedModules.join(", ")} (your licence includes ${droppedModules.length === 1 ? "it" : "them"}; a spoke does not admit ${droppedModules.length === 1 ? "it" : "them"} yet).`,
@@ -362,6 +430,18 @@ async function main() {
                 `  AILK_API_URL=${hubOrigin ?? "<your hub origin>"}   # written to apps/web/.env.local`,
                 "  AILK_SPOKE_KEY             # issued by the hub; never written here",
                 "  AILK_VISITOR_FORWARD_KEY   # issued by the hub; never written here",
+                // #7894 D11 — the hub sign-in mode's client, issued on the hub.
+                ...(hubSignInOrigin !== undefined
+                    ? [
+                        `  AILK_HUB_SIGN_IN_URL=${hubSignInOrigin}   # written to apps/web/.env.local`,
+                        "  AILK_HUB_SESSION_SECRET    # generated into apps/web/.env.local; keep it secret",
+                        "  AILK_HUB_CLIENT_ID         # this spoke's id on the hub; never written here",
+                        "  AILK_HUB_CLIENT_SECRET     # issued by the hub; never written here",
+                        "",
+                        "On the hub, issue the client id and secret with:",
+                        "  pnpm --filter @working-theory/api spokes sign-in-client --id <spoke_id> --redirect-uri <this site's origin>/api/hub-session/callback",
+                    ]
+                    : []),
             ]
             : []),
         "",

package/dist/derive-architecture.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Derive a scaffolded site's `architecture.yaml` from its selected module set.
+ *
+ * `deriveArchitecture(modules)` composes the module-independent BASE
+ * (module-architecture.ts `ARCHITECTURE_BASE`) with the selected module slices
+ * into ONE deterministic `architecture.yaml` document string. The module set is
+ * the single source of truth for the result — same set → byte-identical output
+ * (no timestamps, stable key/array ordering), so the derivation doubles as the
+ * re-runnable sync path (add a module, re-derive, the file updates; re-deriving
+ * an unchanged set is a no-op).
+ *
+ * Zero runtime dependencies (create-ailk is a published, standalone CLI): the
+ * YAML is emitted by a small, purpose-built deterministic serializer over the
+ * fixed document shape this module produces — no `yaml`/`js-yaml` dependency.
+ */
+import { type ForbiddenPattern } from "./module-architecture.js";
 import type { Topology } from "./topology.js";
 /** The topology a document is derived for (#7426 D8). */
 export interface DeriveArchitectureOptions {
@@ -6,6 +22,12 @@ export interface DeriveArchitectureOptions {
     /** Spoke only: whether the spoke keeps `apps/mcp` (default true). */
     mcp?: boolean;
 }
+/** The only spoke files that may import @working-theory/spoke-checkout (#7873). */
+export declare const SPOKE_CHECKOUT_ROUTE_FILES: readonly string[];
+/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2). */
+export declare const SPOKE_WEB_FORBIDDEN_PATTERNS: readonly ForbiddenPattern[];
+/** The same three for a spoke's kept apps/mcp — no MCP file may import the package (#7873). */
+export declare const SPOKE_MCP_FORBIDDEN_PATTERNS: readonly ForbiddenPattern[];
 /**
  * Derive the `architecture.yaml` document for a module set.
  *

package/dist/derive-architecture.js

@@ -21,6 +21,60 @@ const SPOKE_TIERS = {
     api: "the hub at AILK_API_URL (apps/mcp is a stateless front)",
     presentation: "apps/web",
 };
+// ── The spoke checkout boundary (#7873, brief Part 2 §2) ───────────────────
+//
+// A scaffold's lint (template-overlay/tools/lint-architecture.ts) resolves an
+// import only to a workspace on disk, so the one way to ban an npm package is
+// a line-level forbidden pattern. These go under the spoke's own `apps.web`
+// and `apps.mcp` only — never top level, and never on a hub derivation.
+/** The only spoke files that may import @working-theory/spoke-checkout (#7873). */
+export const SPOKE_CHECKOUT_ROUTE_FILES = Object.freeze([
+    "apps/web/app/api/checkout/[offering]/route.ts",
+    "apps/web/app/api/webhooks/stripe/route.ts",
+]);
+/**
+ * A line-level regex for an import of `specifier` or one of its subpaths, in
+ * every form the line can take: `from "…"` (a static or re-export, including
+ * the closing line of a multi-line import), `import "…"`, `import("…")` and
+ * `require("…")`. The leading `\b` keeps `myrequire(…)` / `datafrom(…)` out;
+ * the quote set takes a backtick so `import(\`…\`)` is not a way round it.
+ * A plain string (`"stripe"`) and a lookalike name (`…-extra`) do not match.
+ */
+function specifierForm(specifier) {
+    const q = "['\"`]";
+    const literal = specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return `\\b(?:from|import|require)\\s*\\(?\\s*${q}${literal}(?:/[^'"\`]*)?${q}`;
+}
+/** P1 with no exclusions — a kept apps/mcp's form; apps/web adds the two routes. */
+const SPOKE_CHECKOUT_PATTERN = Object.freeze({
+    pattern: specifierForm("@working-theory/spoke-checkout"),
+    reason: "Spoke checkout: only the buy route and the webhook route may import @working-theory/spoke-checkout (brief Part 2 §2, #7873)",
+});
+const STRIPE_CLIENT_PATTERN = Object.freeze({
+    pattern: specifierForm("@working-theory/stripe-client"),
+    reason: "A spoke never imports stripe-client directly — it reaches Stripe only through @working-theory/spoke-checkout (#7873)",
+});
+const STRIPE_SDK_PATTERN = Object.freeze({
+    pattern: specifierForm("stripe"),
+    reason: "A spoke never imports the stripe SDK directly — it reaches Stripe only through @working-theory/spoke-checkout (#7873)",
+});
+/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2). */
+export const SPOKE_WEB_FORBIDDEN_PATTERNS = Object.freeze([
+    Object.freeze({ ...SPOKE_CHECKOUT_PATTERN, paths_excluded: [...SPOKE_CHECKOUT_ROUTE_FILES] }),
+    STRIPE_CLIENT_PATTERN,
+    STRIPE_SDK_PATTERN,
+]);
+/** The same three for a spoke's kept apps/mcp — no MCP file may import the package (#7873). */
+export const SPOKE_MCP_FORBIDDEN_PATTERNS = Object.freeze([
+    SPOKE_CHECKOUT_PATTERN,
+    STRIPE_CLIENT_PATTERN,
+    STRIPE_SDK_PATTERN,
+]);
+/** Per-app extra patterns on the spoke branch only, keyed by the app's key. */
+const SPOKE_APP_FORBIDDEN = {
+    web: SPOKE_WEB_FORBIDDEN_PATTERNS,
+    mcp: SPOKE_MCP_FORBIDDEN_PATTERNS,
+};
 function isScalar(v) {
     return typeof v === "string" || typeof v === "number";
 }
@@ -223,11 +277,14 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
         const a = declared[key];
         if (!a)
             continue;
+        // The checkout boundary is keyed on the topology the caller passed, never
+        // a module or a path glob alone, so a hub derivation is unchanged (#7873).
+        const extra = spoke ? (SPOKE_APP_FORBIDDEN[key] ?? []) : [];
         apps[key] = appToYaml({
             ...a,
             may_import_from: a.may_import_from.filter(inScaffold),
             may_not_import_from: a.may_not_import_from.filter(inScaffold),
-            forbidden_patterns: mergeForbidden([...ARCHITECTURE_BASE.appForbiddenPatterns], a.forbidden_patterns ?? []).map(scoped),
+            forbidden_patterns: mergeForbidden([...ARCHITECTURE_BASE.appForbiddenPatterns], [...(a.forbidden_patterns ?? []), ...extra]).map(scoped),
         });
     }
     // namespaces — present only if a data-tier module contributes one, and

package/dist/lib/declared-env.d.ts

@@ -0,0 +1,142 @@
+/** Names the platform sets, which need no row (D4). Fixed: a site cannot extend it. */
+export declare const PLATFORM_ENV_NAMES: readonly string[];
+/** Every name with one of these prefixes is a platform name too (D4). */
+export declare const PLATFORM_ENV_PREFIXES: readonly string[];
+/** Names a spoke may neither read nor declare (D5): its hub origin is server-only. */
+export declare const SPOKE_REFUSED_ENV: readonly string[];
+/** Whether `name` is set by the platform and so needs no row. */
+export declare function isPlatformEnvName(name: string): boolean;
+/** A site's topology. Restated from `topology.ts`: the scaffold copy cannot import it. */
+export type SiteTopology = "hub" | "spoke";
+/** One literal env read: the variable name and its 1-based line. */
+export interface EnvRead {
+    name: string;
+    line: number;
+}
+/**
+ * Every literal env read in `source` (D3): `process.env.NAME`,
+ * `process.env["NAME"]` / `['NAME']`, either with `?.` in place of a `.`,
+ * and each key of an object pattern destructured from `process.env`. A
+ * computed `process.env[expr]` is skipped. In source order.
+ */
+export declare function findEnvReads(source: string): EnvRead[];
+/**
+ * The site-relative (`/`-separated) source files under `root` whose reads
+ * the check collects, sorted. Symbolic links are not followed.
+ */
+export declare function listScannedFiles(root: string): string[];
+/** A read located in the site: the file it sits in and its line. */
+export interface SiteEnvRead extends EnvRead {
+    file: string;
+}
+/** Every read in the site at `root`, and every file that could not be read. */
+export declare function collectSiteReads(root: string): {
+    reads: SiteEnvRead[];
+    unreadable: Array<{
+        file: string;
+        reason: string;
+    }>;
+};
+/** One `env_contract` row as written. */
+export interface EnvContractRow {
+    name: string;
+    description: string;
+    secret: boolean;
+    scope?: EnvScope;
+    /** The 1-based `project.yaml` line the row's item starts on. */
+    line: number;
+}
+/** A fault in the block: the 1-based `project.yaml` line and what is wrong. */
+export interface EnvContractFault {
+    line: number;
+    message: string;
+}
+export type EnvContract = {
+    present: false;
+} | {
+    present: true;
+    rows: EnvContractRow[];
+    faults: EnvContractFault[];
+};
+export declare const ENV_SCOPES: readonly ["web", "api", "mcp"];
+export type EnvScope = (typeof ENV_SCOPES)[number];
+/**
+ * The top-level `env_contract:` block of `projectYamlText` (D2): absent, or
+ * its rows and every fault in it. A row whose name is valid is in `rows`
+ * even when another of its keys is at fault, so its name still counts as
+ * declared; the fault is reported either way.
+ */
+export declare function readEnvContract(projectYamlText: string): EnvContract;
+/**
+ * The topology `.ailk-site-manifest.json` records under `root` (D8): a
+ * missing file or key reads `"hub"`; an unknown value or a file that is not
+ * JSON is a fault. The `readSiteTopology` rule in create-ailk's `topology.ts`.
+ */
+export declare function readManifestTopology(root: string): {
+    topology: SiteTopology;
+} | {
+    fault: string;
+};
+/** The check's result: one line per finding, and the line to print on a pass. */
+export interface DeclaredEnvResult {
+    findings: string[];
+    summary: string;
+}
+/**
+ * Check the site at `root` (D5): every literal env read has an
+ * `env_contract` row, every row is well-formed, and on a spoke
+ * `NEXT_PUBLIC_AILK_API_URL` is neither read nor declared. A hub with no
+ * block has nothing to check; a spoke with no block is a finding.
+ */
+export declare function checkDeclaredEnv(root: string): DeclaredEnvResult;
+/** A block the writer cannot read, so it never appends to it (D7). */
+export declare class EnvContractError extends Error {
+    constructor(message: string);
+}
+/** What a row says about a name the writer knows (create-ailk's catalog). */
+export interface EnvCatalogEntry {
+    description: string;
+    secret: boolean;
+}
+export interface PlanEnvRowsOptions {
+    /** The site's topology — passed by the caller, never read from the manifest. */
+    topology: SiteTopology;
+    /** Described rows for known names; any other name gets a placeholder row. */
+    catalog: Readonly<Record<string, EnvCatalogEntry>>;
+    /**
+     * Names the site depends on that an installed package reads on its behalf,
+     * so the scan never sees them (#7838). Each gets a row when it has none,
+     * with no reader and so no `scope`; a platform or refused name is skipped.
+     */
+    declare?: readonly string[];
+}
+/**
+ * `projectYamlText` with a row appended for every name the site at `root`
+ * reads that has none (D7), sorted by name, after the existing rows. Platform
+ * names, and on a spoke `SPOKE_REFUSED_ENV`, get no row. Pure: it reads the
+ * tree, never writes. `added` names the rows it wrote.
+ *
+ * @throws EnvContractError when the existing block has a fault — the writer
+ *   never appends to a block it cannot read.
+ */
+export declare function planEnvRows(root: string, projectYamlText: string, opts: PlanEnvRowsOptions): {
+    text: string;
+    added: string[];
+};
+/** What `appendEnvRows` did to `<root>/project.yaml`. */
+export type AppendEnvRowsResult = {
+    state: "written";
+    added: string[];
+} | {
+    state: "unchanged";
+} | {
+    state: "no-project-yaml";
+};
+/**
+ * Plan and write `<root>/project.yaml`'s new rows (D7). Writes only when the
+ * text changed, so a second run changes nothing; never edits or removes a
+ * row. A site with no `project.yaml` is left alone.
+ *
+ * @throws EnvContractError on a block it cannot read (nothing is written).
+ */
+export declare function appendEnvRows(root: string, opts: PlanEnvRowsOptions): AppendEnvRowsResult;