create-ailk 0.14.0 → 0.16.0

package/dist/surfaces.js

@@ -626,6 +626,10 @@ export const ROUTE_SINCE = {
     "(authed)/account/inbox/[kind]/[id]": "0.30.0",
     "(authed)/account/settings": "0.30.0",
     "(authed)/account/support": "0.30.0",
+    // #7920 — the member file read a message's file action opens. Genuinely
+    // new, so it attaches at today's fixed-group version, the same rule #7430
+    // applied above.
+    "(authed)/account/inbox/message/[id]/file": "0.37.0",
     // The leads inbox (#5678). The ROUTE ships in every scaffold, Free
     // included — lead capture is a never-gate surface, so reading a lead back
     // is one too. Whether it shows a ROW is a separate question with two
@@ -756,6 +760,9 @@ export const ROUTE_DEPENDENCIES = {
         `${ROUTE_ROOT}/(authed)/account/error-row.tsx`,
         `${ROUTE_ROOT}/(authed)/account/retry-button.tsx`,
     ],
+    // #7920 — the member file read re-serves the hub's bytes with the
+    // credential `forwardedCookieInit` returns.
+    "(authed)/account/inbox/message/[id]/file": ["apps/web/lib/server-api.ts"],
     "(authed)/account/settings": [
         "apps/web/lib/account-config.ts",
         "apps/web/lib/auth-env.ts",

package/dist/sync-routes.js

@@ -31,8 +31,11 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { copyTemplate } from "./copy.js";
+import { appendEnvRows } from "./lib/declared-env.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, NON_ROUTE_DIRS, ROUTE_DEPENDENCIES, ROUTE_MESSAGE_NAMESPACES, ROUTE_SINCE, surfaceForRouteDir, } from "./surfaces.js";
+import { SPOKE_SEAM_FILES, isSpokeExcluded, readSpokeShape, } from "./topology.js";
 /** Template-relative prefix every `apps/web` route directory sits under. */
 const ROUTE_ROOT = "apps/web/app/[locale]";
 /**
@@ -98,9 +101,9 @@ function reportFor(route) {
  * byte-for-byte in, the target's copy. Non-recursive: nested directories are
  * route dirs of their own, or `__tests__`.
  */
-function isModified(expectedDir, targetDir) {
+function isModified(expectedDir, targetDir, skip = () => false) {
     for (const entry of readdirSync(expectedDir, { withFileTypes: true })) {
-        if (!entry.isFile())
+        if (!entry.isFile() || skip(entry.name))
             continue;
         const targetFile = join(targetDir, entry.name);
         if (!existsSync(targetFile))
@@ -163,12 +166,27 @@ export function syncRoutes(opts) {
             skippedSurfaces.push(surface.id);
     }
     skippedSurfaces.sort();
+    // #7426 D13 — on a spoke, a route dir the spoke does not carry (the
+    // `(auth)` and `(authed)` groups) is out of scope: neither reported nor
+    // copied. This is the one filter point for add-module, add-route and the
+    // sync-routes subcommand alike; a hub's scope is unchanged. The spoke's
+    // sign-in mode rides along (#7894 D1): a hub sign-in spoke keeps its
+    // `(authed)` account area in scope and its operator surfaces out.
+    const spoke = readSpokeShape(targetAbs);
+    // A spoke's own render of a seam, and a file it does not carry, are not
+    // "modified" (#7894 D8): the template holds the hub's.
+    const spokeSkip = (route) => (name) => {
+        const path = `${ROUTE_ROOT}/${route}/${name}`;
+        return (spoke !== undefined &&
+            (SPOKE_SEAM_FILES.includes(path) || isSpokeExcluded(path, spoke)));
+    };
     const inScope = listTemplateRouteDirs(opts.templatesDir)
         .map(reportFor)
         // "authed" (#5014): the `(authed)` route group ships unconditionally in
-        // every scaffold today, the same as "core" — it is checked regardless of
+        // every hub scaffold, the same as "core" — it is checked regardless of
         // `carried`, which only tracks GATEABLE_SURFACES opt-in.
-        .filter((r) => r.surface === "core" || r.surface === "authed" || carried.has(r.surface));
+        .filter((r) => r.surface === "core" || r.surface === "authed" || carried.has(r.surface))
+        .filter((r) => spoke === undefined || !isSpokeExcluded(`${ROUTE_ROOT}/${r.route}`, spoke));
     // Identical to scaffoldSync's defaults, so a synced route matches a fresh
     // scaffold of the same target byte-for-byte.
     const markers = {
@@ -193,7 +211,7 @@ export function syncRoutes(opts) {
             if (!existsSync(targetRoute)) {
                 missing.push(report);
             }
-            else if (isModified(join(scratch, report.route), targetRoute)) {
+            else if (isModified(join(scratch, report.route), targetRoute, spokeSkip(report.route))) {
                 modified.push(report);
             }
         }
@@ -241,6 +259,12 @@ export function syncRoutes(opts) {
             copyDependencyFile(join(opts.templatesDir, dep), dst, markers);
             appliedDependencies.push(dep);
         }
+        // #7874 D9 — a spoke declares what the copied routes read, as the last
+        // write. A malformed env_contract block throws EnvContractError naming
+        // its line; the files copied above stay.
+        if (spoke !== undefined) {
+            appendEnvRows(targetAbs, { topology: "spoke", catalog: ENV_CATALOG });
+        }
     }
     return {
         targetDir: targetAbs,

package/dist/topology.d.ts

@@ -0,0 +1,246 @@
+import { type ModuleName } from "./parse-args.js";
+/** The two topologies. `hub` is the default and the only one before #7426. */
+export declare const TOPOLOGIES: readonly ["hub", "spoke"];
+export type Topology = (typeof TOPOLOGIES)[number];
+/** A refusal or a malformed input this module names. */
+export declare class TopologyError extends Error {
+    constructor(message: string);
+}
+/** Roots no spoke carries. `apps/mcp` joins them with `--without-mcp`. */
+export declare const SPOKE_REMOVED_ROOTS: readonly string[];
+/** The root `--without-mcp` removes. */
+export declare const SPOKE_MCP_ROOT = "apps/mcp";
+/** Commerce's apps/web files that reach the hub's own checkout (spoke-intake Rule 3, #7838). */
+export declare const SPOKE_HUB_CHECKOUT_SEEDS: readonly string[];
+/**
+ * The files a spoke does not carry — files and directories, scaffold-relative:
+ * the sign-in and database seeds, then the commerce files that call the hub's
+ * own checkout (`SPOKE_HUB_CHECKOUT_SEEDS`; a spoke keeps its own, #7838).
+ * Every other file that imports one of them goes with it (`spokeExclusions`).
+ */
+export declare const SPOKE_REMOVAL_SEEDS: readonly string[];
+/**
+ * Module paths a spoke drops even when it carries the module (#7876 D8,
+ * clarified 2026-10-09). `signal-collectors`' report reader links a
+ * grant-gated report's bytes on the hub from `NEXT_PUBLIC_AILK_API_URL`,
+ * which a spoke refuses (#7874: its hub origin is server-only), and a
+ * deliverable is hub-side anyway — so a spoke carries neither the
+ * `/reports` routes nor the report seeds that would have no route.
+ */
+export declare const SPOKE_EXCLUDED_MODULE_PATHS: readonly string[];
+/**
+ * The `(authed)` seeds of the sign-in-through-the-hub mode (#7894 D9): the
+ * whole `(authed)` group goes in the default mode; in the hub mode its account
+ * area, layout and gate seam stay, and only these go — the operator surfaces,
+ * the Better Auth gate and the suites that mock `auth.ts` by path.
+ */
+export declare const HUB_MODE_AUTHED_SEEDS: readonly string[];
+/** The generated seam files (D5; #7874 D12). A seam is rewritten, never removed. */
+export declare const WEB_SEAM_PATH = "apps/web/lib/topology.generated.ts";
+export declare const MCP_SEAM_PATH = "apps/mcp/src/lib/topology.generated.ts";
+/** The browser API origin seam (#7874 D12): a spoke's render reads no env. */
+export declare const API_ORIGIN_SEAM_PATH = "apps/web/lib/api-origin.generated.ts";
+/**
+ * The `(authed)` layout's signed-out gate (#7894 D8). Under the `(authed)`
+ * seed, so a default-mode spoke drops it with its group and never renders it.
+ */
+export declare const AUTHED_GATE_SEAM_PATH = "apps/web/app/[locale]/(authed)/signed-out-gate.generated.tsx";
+export declare const SPOKE_SEAM_FILES: readonly string[];
+/**
+ * Template files only a spoke carries (#7874 D11): the declared-env check.
+ * `scaffoldSync` excludes them from a hub's copy (`copyTemplate`'s
+ * `excludePaths` matches an exact file path).
+ */
+export declare const SPOKE_ONLY_FILES: readonly string[];
+/**
+ * The closure's allow-list: a file `spokeExclusions` removes must sit under
+ * one of these prefixes, or under a `__tests__/` directory. A member outside
+ * both is a defect — a shared file started importing a sign-in or database
+ * file — and `spokeExclusions` throws naming it rather than cut it silently.
+ */
+export declare const SPOKE_REMOVABLE_PREFIXES: readonly string[];
+/**
+ * A spoke's sign-in modes (#7894 D1): `off` — the default, no sign-in — and
+ * `hub`, signing a visitor in through the hub (`--hub-sign-in <origin>`).
+ */
+export type SignInMode = "off" | "hub";
+export interface SpokeShapeOptions {
+    /** Whether the spoke keeps `apps/mcp` (the default; `--without-mcp` drops it). */
+    mcp: boolean;
+    /** The sign-in mode (#7894 D1). Absent means `"off"`, so every existing caller is the default mode. */
+    signIn?: SignInMode;
+}
+/** The removed roots for these options. */
+export declare function spokeRemovedRoots(opts: SpokeShapeOptions): string[];
+/**
+ * Whether a closure member is one the registry allows a spoke to drop: under
+ * a seed of THAT sign-in mode, or a test. In the hub mode a surviving account
+ * file that imports `auth.ts` is therefore not removable, and
+ * `spokeExclusions` throws naming it (#7894 D9).
+ */
+export declare function isRemovableClosureMember(path: string, opts?: Pick<SpokeShapeOptions, "signIn">): boolean;
+/**
+ * Every path a spoke does not carry, computed over the built `templates/`
+ * tree: the removed roots, the seeds that apply, and every source file under
+ * the kept apps that reaches a seed through relative imports, to a fixed
+ * point. Sorted; directories and files alike, matched at a directory
+ * boundary by `isSpokeExcluded` and `copyTemplate`'s `excludePaths`.
+ *
+ * The walk is the relative-import resolution `importClosure` uses
+ * (`lib/import-graph.ts`), with ONE difference: a seam file is never a
+ * candidate, so the walk never crosses it. The hub render of a seam imports
+ * a seed by design (D5); its importers keep their place on a spoke because
+ * the spoke render of the same file imports none.
+ *
+ * @throws TopologyError naming every closure member outside
+ *   `SPOKE_REMOVABLE_PREFIXES` and not a test — a new shared file importing
+ *   a sign-in or database file, which removing would silently break the
+ *   spoke (spec § 5.3: escalate, never widen).
+ */
+export declare function spokeExclusions(templatesDir: string, opts: SpokeShapeOptions): string[];
+export interface IsSpokeExcludedOptions extends SpokeShapeOptions {
+    /**
+     * The full `spokeExclusions(...)` list, when the caller computed it. Absent,
+     * only the removed roots and the seeds are checked — exact for any path
+     * that is not a file of the built `templates/` tree (a module bundle's
+     * file, a route directory), since only a template file can be a closure
+     * member.
+     */
+    exclusions?: readonly string[];
+}
+/**
+ * The one predicate for "a spoke does not carry this path" (the Phase 2
+ * generator contract). Scaffold-relative, `/`- or `\`-separated.
+ */
+export declare function isSpokeExcluded(path: string, opts: IsSpokeExcludedOptions): boolean;
+/**
+ * Where a module bundle's `installMap` destination lands on a spoke (#7876
+ * D10): `database/flows/<name>.flow.json` becomes `flows/<name>.json` — a
+ * declared flow `create-ailk seed-flows` sends to the hub — and every other
+ * destination is returned unchanged. Applied before the spoke filter, so a
+ * remapped flow survives it while the rest of `database/` is dropped. A hub
+ * install passes no remap.
+ */
+export declare function spokeDestination(destination: string): string;
+/**
+ * `apps/web/lib/topology.generated.ts` for `topology` (D5) and, on a spoke,
+ * its sign-in mode (#7894 D8). The hub render loads `auth.ts` only when a
+ * session is read, so a module that imports this seam for a constant never
+ * loads Better Auth.
+ */
+export declare function renderWebSeam(topology: Topology, signIn?: SignInMode): string;
+/**
+ * `apps/web/app/[locale]/(authed)/signed-out-gate.generated.tsx` (#7894 D8).
+ * The hub render is the `(authed)` layout's no-session branch, moved; the
+ * `signIn: "hub"` render imports only the hub-session gate. A default-mode
+ * spoke carries no `(authed)` group, so it has no render.
+ * @throws TopologyError for a spoke in the default mode.
+ */
+export declare function renderAuthedGateSeam(topology: Topology, signIn?: SignInMode): string;
+/** `apps/mcp/src/lib/topology.generated.ts` for `topology` (D5). */
+export declare function renderMcpSeam(topology: Topology): string;
+/** `apps/web/lib/api-origin.generated.ts` for `topology` (#7874 D12). */
+export declare function renderApiOriginSeam(topology: Topology): string;
+/** `pnpm-workspace.yaml` without its `database` package entry. */
+export declare function transformWorkspaceYaml(text: string): string;
+/** The root `package.json` without its `db:*` scripts. */
+export declare function transformRootPackageJson(text: string): string;
+/** The spoke's declared-env script (#7874 D11) — named apart from the monorepo's `env:check`. */
+export declare const ENV_DECLARED_SCRIPT = "env:declared";
+/**
+ * The spoke's root `package.json` with the declared-env check (#7874 D11):
+ * an `env:declared` script after `claude-md:check`, and `preflight` running
+ * it right after `claude-md:check`. Applied after `transformRootPackageJson`.
+ * @throws TopologyError when either anchor is missing.
+ */
+export declare function addEnvCheckScripts(text: string): string;
+/**
+ * The spoke's `.github/workflows/ci.yml` (#7874 D11): a `pnpm env:declared`
+ * step after `pnpm claude-md:check`, and no `pnpm db:generate` step — a
+ * spoke has no `database/` and no `db:*` script, so that step would fail
+ * first (#7962). The comment block directly above the dropped step goes with
+ * it.
+ * @throws TopologyError when either anchor is missing.
+ */
+export declare function transformCiWorkflow(text: string): string;
+/** The root `tsconfig.json` without a reference under a removed root. */
+export declare function transformRootTsconfig(text: string, opts: SpokeShapeOptions): string;
+/**
+ * An app's `package.json` without its `@working-theory/database` dependency.
+ * @throws TopologyError when `required` and the dependency is absent.
+ */
+export declare function transformAppPackageJson(text: string, label: string, required: boolean): string;
+/**
+ * Apply every D6 root-file transform to the spoke at `targetDir` (after the
+ * base copy, before any module or template layer), and write the spoke
+ * render of each seam it carries (D5). Also the declared-env check's root
+ * script and CI step (#7874 D11), and the browser API origin seam (D12).
+ * @throws TopologyError naming the file whose anchor is missing.
+ */
+export declare function applySpokeTransforms(targetDir: string, opts: SpokeShapeOptions): void;
+/** The env var a spoke reaches its hub through. */
+export declare const HUB_ORIGIN_ENV_VAR = "AILK_API_URL";
+/**
+ * Write `AILK_API_URL=<origin>` to the spoke's `apps/web/.env.local` (D2) —
+ * the `auth-secret-file.ts` never-clobber rule: an assignment already in any
+ * env file Next loads for `apps/web` is kept, and `.env.local` stays
+ * gitignored. Never writes `AILK_SPOKE_KEY` or `AILK_VISITOR_FORWARD_KEY`:
+ * the hub issues those.
+ */
+export declare function writeHubOriginEnv(targetDir: string, origin: string): void;
+/** The env var naming the hub's web origin a hub-mode spoke signs in at (#7894 D11). */
+export declare const HUB_SIGN_IN_URL_ENV_VAR = "AILK_HUB_SIGN_IN_URL";
+/** The env var holding a hub-mode spoke's own cookie key material (#7894 D7, D11). */
+export declare const HUB_SESSION_SECRET_ENV_VAR = "AILK_HUB_SESSION_SECRET";
+/**
+ * Write a hub-mode spoke's sign-in env (#7894 D11) to `apps/web/.env.local`,
+ * under `writeHubOriginEnv`'s never-clobber rule: the hub's web origin, and a
+ * fresh session secret (32 random bytes, 43 base64url characters). Never the
+ * client id or client secret — the hub issues those (`spokes sign-in-client`)
+ * — and never `BETTER_AUTH_SECRET` or a database URL.
+ */
+export declare function writeHubSignInEnv(targetDir: string, origin: string): void;
+/** The `hard_floors:` block a spoke's `project.yaml` carries (D9). */
+export declare function renderSpokeHardFloors(opts: SpokeShapeOptions): string;
+/** `project.yaml` with its `hard_floors:` block replaced by the spoke's (D9). */
+export declare function transformProjectYaml(text: string, opts: SpokeShapeOptions): string;
+/** Why a module is not admitted on a spoke, and where its admission lives. */
+export declare const SPOKE_REFUSAL_REASONS: Partial<Record<ModuleName, string>>;
+/** The modules a spoke may carry — every slice declaring `spoke: true`. */
+export declare function spokeModules(): ModuleName[];
+/** The refusal for a module a spoke cannot carry, or undefined when admitted. */
+export declare function spokeModuleRefusal(name: ModuleName): string | undefined;
+/**
+ * The topology `<targetDir>` records. A missing manifest, or one without a
+ * `topology` key, reads as `"hub"` — every site scaffolded before #7426.
+ * @throws TopologyError on an unreadable manifest or an unknown value.
+ */
+export declare function readSiteTopology(targetDir: string): Topology;
+/**
+ * The spoke options `<targetDir>` records (#7894 D1), for the later commands
+ * (`sync-routes`, `add-module`): `undefined` on a hub; on a spoke, `mcp` from
+ * whether it still carries `apps/mcp` and `signIn` from the manifest's
+ * `signIn` key — absent reads as `"off"`, every spoke before #7894.
+ * @throws TopologyError on an unreadable manifest or an unknown value.
+ */
+export declare function readSpokeShape(targetDir: string): SpokeShapeOptions | undefined;
+/**
+ * Hosts a spoke may reach over plain `http:` — the set
+ * `packages/api-client/src/http.ts` sends the spoke key under. Named here
+ * rather than imported: create-ailk carries no runtime dependency.
+ */
+export declare const LOOPBACK_HOSTS: readonly string[];
+/**
+ * The hub origin for a spoke: `--hub-url`, else `AILK_API_URL`. An `https:`
+ * URL, or `http:` on a loopback host, with no path but `/`, no query and no
+ * fragment — normalized to its origin with no trailing slash.
+ * @throws TopologyError naming both inputs when neither is set or the value
+ *   is not such an origin. Never echoes a query or fragment.
+ */
+export declare function normalizeHubUrl(raw: string | undefined): string;
+/**
+ * The hub's WEB origin a hub-mode spoke signs in at (`--hub-sign-in`, #7894
+ * D1) — `normalizeHubUrl`'s rules, each refusal naming the flag.
+ * @throws TopologyError when `raw` is not such an origin.
+ */
+export declare function normalizeHubSignInUrl(raw: string): string;