create-ailk 0.28.0 → 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/chrome-readers.d.ts

@@ -5,17 +5,33 @@ export interface UnreadChromeKnob {
     /** Overlay-relative path of the reader file, with `/` separators. */
     file: string;
 }
+/** One overlay file that reads a knob. */
+export interface ChromeReader {
+    /** Overlay-relative path, with `/` separators. */
+    file: string;
+    /** Present when `file` reads the knob only through its imports: the files it reaches that read it directly. */
+    via?: string[];
+}
 /** The pattern that means "this text reads `knob`". */
 export declare function chromeReadPattern(knob: string): RegExp;
 /**
- * knob → the overlay files that read it, sorted. Scans `<templatesDir>/apps/web`;
- * fails closed (throws, naming the directory) when it is absent or unreadable,
- * so a broken overlay can never read as "nothing reads any knob".
+ * knob → the overlay files that read it, sorted by file; one that reads it
+ * only through relative imports carries `via`. Scans `<templatesDir>/apps/web`; fails closed (throws, naming the directory)
+ * when it is absent or unreadable, so a broken overlay can never read as
+ * "nothing reads any knob".
  */
-export declare function chromeKnobReaders(templatesDir: string): Map<string, string[]>;
+export declare function chromeKnobReaders(templatesDir: string): Map<string, ChromeReader[]>;
 /**
  * The `(knob, file)` pairs where the resolved chrome sets a non-default `knob`,
  * the shipped overlay's `file` reads it, the site has its own `file`, and the
  * site's `file` does not read it. A reader file the site lacks is skipped.
+ *
+ * A pair the overlay credits only through an import is also satisfied when
+ * some site file outside its `via` reads the knob directly: a site from before
+ * the read moved into the helper renders it in its own place (#10156). So the
+ * import credit adds a pair only for a knob the site reads nowhere but its
+ * helpers. It is per file, not per export: a site whose home page drops the
+ * helper import is named for every knob that helper reads — a refusal the
+ * operator passes with `--allow-unread-chrome`, never a silent miss.
  */
-export declare function unreadChromeKnobs(resolved: ResolvedSiteChrome, readers: ReadonlyMap<string, readonly string[]>, siteDir: string): UnreadChromeKnob[];
+export declare function unreadChromeKnobs(resolved: ResolvedSiteChrome, readers: ReadonlyMap<string, readonly ChromeReader[]>, siteDir: string): UnreadChromeKnob[];

package/dist/lib/chrome-readers.js

@@ -11,12 +11,16 @@
  *   each knob — nothing is hard-coded, so a new reader file is picked up.
  * - `unreadChromeKnobs` compares the site's own copy of each reader file.
  *
- * "Reads `knob`" means the file's text matches `(?:siteChrome|chrome)\.<knob>\b`.
- * A file that reads a knob under another name (a destructured alias) is not
- * recognised — accepted (spec § Clarifications, detection).
+ * A file "reads `knob` directly" when its text matches
+ * `(?:siteChrome|chrome)\.<knob>\b`, and "reads" it when it or a file it
+ * imports by a relative path, at any depth, reads it directly — so the layout
+ * stays a reader of `innerPages` after #10106 moved that read into
+ * `lib/page-chrome.ts` (#10156). A file that reads a knob under another name
+ * (a destructured alias) is not recognised — accepted (spec § Clarifications,
+ * detection).
  */
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, posix } from "node:path";
 import { DEFAULT_SITE_CHROME, } from "../site-chrome.js";
 /** The overlay tree the generated app files live under. */
 const OVERLAY_WEB_DIR = ["apps", "web"];
@@ -31,41 +35,126 @@ function listSources(root, dir, out) {
     for (const entry of readdirSync(join(root, dir), { withFileTypes: true })) {
         const rel = `${dir}/${entry.name}`;
         if (entry.isDirectory()) {
-            if (entry.name !== "__tests__")
+            if (entry.name !== "__tests__" &&
+                entry.name !== "node_modules" &&
+                !entry.name.startsWith(".")) {
                 listSources(root, rel, out);
+            }
         }
         else if (/\.tsx?$/.test(entry.name)) {
             out.push(rel);
         }
     }
 }
+/** A relative module specifier in an import, export-from or dynamic import. */
+const RELATIVE_IMPORT = /(?:\bfrom|\bimport)\s*\(?\s*["'](\.{1,2}\/[^"']+)["']/g;
+function sourceTree(root) {
+    const texts = new Map();
+    const closures = new Map();
+    const importLists = new Map();
+    const text = (file) => {
+        if (!texts.has(file)) {
+            const abs = join(root, file);
+            texts.set(file, existsSync(abs) ? readFileSync(abs, "utf8") : null);
+        }
+        return texts.get(file);
+    };
+    /** The files `file` imports by a relative path that exist under the root; `./x.js` may name `x.ts`. */
+    const imports = (file) => {
+        const cached = importLists.get(file);
+        if (cached !== undefined)
+            return cached;
+        const out = [];
+        for (const match of (text(file) ?? "").matchAll(RELATIVE_IMPORT)) {
+            const base = posix
+                .normalize(posix.join(posix.dirname(file), match[1]))
+                .replace(/\/$/, "");
+            if (base.startsWith(".."))
+                continue;
+            const stem = base.replace(/\.(?:js|jsx)$/, "");
+            const hit = [
+                base,
+                `${stem}.ts`,
+                `${stem}.tsx`,
+                `${stem}/index.ts`,
+                `${stem}/index.tsx`,
+            ].find((candidate) => /\.tsx?$/.test(candidate) && text(candidate) !== null);
+            if (hit !== undefined)
+                out.push(hit);
+        }
+        importLists.set(file, out);
+        return out;
+    };
+    const reached = (file) => {
+        let closure = closures.get(file);
+        if (closure === undefined) {
+            closure = new Set();
+            const stack = [...imports(file)];
+            while (stack.length > 0) {
+                const next = stack.pop();
+                if (next === file || closure.has(next))
+                    continue;
+                closure.add(next);
+                stack.push(...imports(next));
+            }
+            closures.set(file, closure);
+        }
+        return closure;
+    };
+    const readsDirectly = (file, pattern) => pattern.test(text(file) ?? "");
+    return {
+        text,
+        reached,
+        readsDirectly,
+        reads: (file, pattern) => readsDirectly(file, pattern) ||
+            [...reached(file)].some((dep) => readsDirectly(dep, pattern)),
+    };
+}
 /**
- * knob → the overlay files that read it, sorted. Scans `<templatesDir>/apps/web`;
- * fails closed (throws, naming the directory) when it is absent or unreadable,
- * so a broken overlay can never read as "nothing reads any knob".
+ * knob → the overlay files that read it, sorted by file; one that reads it
+ * only through relative imports carries `via`. Scans `<templatesDir>/apps/web`; fails closed (throws, naming the directory)
+ * when it is absent or unreadable, so a broken overlay can never read as
+ * "nothing reads any knob".
  */
 export function chromeKnobReaders(templatesDir) {
     const webDir = join(templatesDir, ...OVERLAY_WEB_DIR);
-    const readers = new Map();
+    const direct = new Map();
+    const files = [];
+    const tree = sourceTree(templatesDir);
     try {
         if (!existsSync(webDir))
             throw new Error("missing");
-        const files = [];
         listSources(templatesDir, OVERLAY_WEB_DIR.join("/"), files);
-        for (const file of files.sort()) {
-            const text = readFileSync(join(templatesDir, file), "utf8");
-            for (const match of text.matchAll(new RegExp(`${READ_HEAD}([A-Za-z_$][\\w$]*)\\b`, "g"))) {
+        files.sort();
+        for (const file of files) {
+            for (const match of tree
+                .text(file)
+                .matchAll(new RegExp(`${READ_HEAD}([A-Za-z_$][\\w$]*)\\b`, "g"))) {
                 const knob = match[1];
-                const list = readers.get(knob) ?? [];
+                const list = direct.get(knob) ?? [];
                 if (!list.includes(file))
                     list.push(file);
-                readers.set(knob, list);
+                direct.set(knob, list);
             }
         }
     }
     catch {
         throw new Error(`cannot check chrome knobs: the overlay has no readable apps/web at ${webDir}. Reinstall create-ailk.`);
     }
+    const readers = new Map();
+    for (const [knob, directFiles] of direct) {
+        const list = [];
+        for (const file of files) {
+            if (directFiles.includes(file)) {
+                list.push({ file });
+                continue;
+            }
+            const via = directFiles.filter((reader) => tree.reached(file).has(reader));
+            if (via.length > 0)
+                list.push({ file, via });
+        }
+        readers.set(knob, list);
+    }
     return readers;
 }
 /** A knob is set when it differs from its default; an optional knob (no default) when present. */
@@ -81,19 +170,38 @@ function isSet(resolved, knob) {
  * The `(knob, file)` pairs where the resolved chrome sets a non-default `knob`,
  * the shipped overlay's `file` reads it, the site has its own `file`, and the
  * site's `file` does not read it. A reader file the site lacks is skipped.
+ *
+ * A pair the overlay credits only through an import is also satisfied when
+ * some site file outside its `via` reads the knob directly: a site from before
+ * the read moved into the helper renders it in its own place (#10156). So the
+ * import credit adds a pair only for a knob the site reads nowhere but its
+ * helpers. It is per file, not per export: a site whose home page drops the
+ * helper import is named for every knob that helper reads — a refusal the
+ * operator passes with `--allow-unread-chrome`, never a silent miss.
  */
 export function unreadChromeKnobs(resolved, readers, siteDir) {
     const out = [];
+    const site = sourceTree(siteDir);
+    let siteFiles;
     for (const knob of Object.keys(resolved).sort()) {
         if (!isSet(resolved, knob))
             continue;
         const pattern = chromeReadPattern(knob);
-        for (const file of readers.get(knob) ?? []) {
-            const abs = join(siteDir, file);
-            if (!existsSync(abs))
+        for (const { file, via } of readers.get(knob) ?? []) {
+            if (site.text(file) === null || site.reads(file, pattern))
                 continue;
-            if (!pattern.test(readFileSync(abs, "utf8")))
-                out.push({ knob, file });
+            if (via !== undefined) {
+                if (siteFiles === undefined) {
+                    siteFiles = [];
+                    if (existsSync(join(siteDir, ...OVERLAY_WEB_DIR))) {
+                        listSources(siteDir, OVERLAY_WEB_DIR.join("/"), siteFiles);
+                    }
+                }
+                const elsewhere = siteFiles.some((other) => !via.includes(other) && site.readsDirectly(other, pattern));
+                if (elsewhere)
+                    continue;
+            }
+            out.push({ knob, file });
         }
     }
     return out;

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

@@ -109,6 +109,12 @@ export interface PlanEnvRowsOptions {
      * with no reader and so no `scope`; a platform or refused name is skipped.
      */
     declare?: readonly string[];
+    /**
+     * When set, only reads in these site-relative files get a row (#10173):
+     * `update` declares what the files it wrote read, never a name only the
+     * site's own code reads.
+     */
+    onlyFiles?: ReadonlySet<string>;
 }
 /**
  * `projectYamlText` with a row appended for every name the site at `root`

package/dist/lib/declared-env.js

@@ -904,6 +904,8 @@ export function planEnvRows(root, projectYamlText, opts) {
     const refused = new Set(opts.topology === "spoke" ? SPOKE_REFUSED_ENV : []);
     const files = new Map();
     for (const read of collectSiteReads(root).reads) {
+        if (opts.onlyFiles !== undefined && !opts.onlyFiles.has(read.file))
+            continue;
         if (isPlatformEnvName(read.name) || refused.has(read.name))
             continue;
         if (declared.has(read.name))

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

@@ -27,3 +27,19 @@ export declare function resolveRelativeImport(fromFile: string, spec: string, ca
  * @param seeds repo-relative, "/"-separated files the closure starts from.
  */
 export declare function importClosure(repoRoot: string, roots: readonly string[], seeds: Iterable<string>): Set<string>;
+/**
+ * The names a module imports from each specifier, textually (#10173): the
+ * members of a `{ … }` list (an `a as b` member names `a`, a `type a` member
+ * `a`) and `default` for a default import. A namespace import (`* as x`) and
+ * a side-effect import name nothing.
+ */
+export declare function namedImportsOf(text: string): Array<{
+    specifier: string;
+    names: string[];
+}>;
+/**
+ * Whether module `text` exports `name`, textually. Fails toward `true` — an
+ * `export *`, or a destructuring export, could export anything — so a caller
+ * that holds a file back on `false` never holds one that does export it.
+ */
+export declare function exportsName(text: string, name: string): boolean;

package/dist/lib/import-graph.js

@@ -138,3 +138,56 @@ export function importClosure(repoRoot, roots, seeds) {
     }
     return closed;
 }
+const IDENT = "[A-Za-z_$][\\w$]*";
+/** `import { a, b as c }` / `export { a } from` / `import X from` — the bound names per specifier. */
+const NAMED_IMPORT = new RegExp(`\\b(?:import|export)\\s+(?:type\\s+)?(?:(${IDENT})\\s*,\\s*)?\\{([^}]*)\\}\\s*from\\s*["']([^"']+)["']` +
+    `|\\bimport\\s+(?:type\\s+)?(${IDENT})\\s+from\\s*["']([^"']+)["']`, "g");
+/**
+ * The names a module imports from each specifier, textually (#10173): the
+ * members of a `{ … }` list (an `a as b` member names `a`, a `type a` member
+ * `a`) and `default` for a default import. A namespace import (`* as x`) and
+ * a side-effect import name nothing.
+ */
+export function namedImportsOf(text) {
+    const out = [];
+    for (const m of text.matchAll(NAMED_IMPORT)) {
+        if (m[3] !== undefined) {
+            const names = (m[2] ?? "")
+                .split(",")
+                .map((member) => member.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim())
+                .filter((name) => new RegExp(`^${IDENT}$`).test(name));
+            if (m[1] !== undefined)
+                names.push("default");
+            out.push({ specifier: m[3], names });
+        }
+        else if (m[5] !== undefined) {
+            out.push({ specifier: m[5], names: ["default"] });
+        }
+    }
+    return out;
+}
+/**
+ * Whether module `text` exports `name`, textually. Fails toward `true` — an
+ * `export *`, or a destructuring export, could export anything — so a caller
+ * that holds a file back on `false` never holds one that does export it.
+ */
+export function exportsName(text, name) {
+    if (/\bexport\s*\*/.test(text))
+        return true;
+    if (/\bexport\s+(?:const|let|var)\s*[{[]/.test(text))
+        return true;
+    if (name === "default" && /\bexport\s+default\b/.test(text))
+        return true;
+    const declared = new RegExp(`\\bexport\\s+(?:declare\\s+)?(?:async\\s+)?(?:abstract\\s+)?` +
+        `(?:const\\s+enum|const|let|var|function\\s*\\*?|class|type|interface|enum|namespace)\\s*${name.replace(/\$/g, "\\$")}\\b`);
+    if (declared.test(text))
+        return true;
+    for (const m of text.matchAll(/\bexport\s*(?:type\s*)?\{([^}]*)\}/g)) {
+        for (const member of (m[1] ?? "").split(",")) {
+            const parts = member.trim().replace(/^type\s+/, "").split(/\s+as\s+/);
+            if ((parts[1] ?? parts[0])?.trim() === name)
+                return true;
+        }
+    }
+    return false;
+}