@akanjs/devkit 3.1.0-rc.9 → 3.1.0

package/lint/__fixtures__/no-conditional-st-hook/good.tsx

@@ -0,0 +1,33 @@
+export const A = () => {
+  const uploading = st.use.xUploading(); // @ok
+  const formUploading = st.use.xFormUploading(); // @ok
+  const busy = uploading || !!formUploading.voice; // @ok
+  const first = st.use.a() || fallback; // @ok
+  const picked = st.use.b() ? one : two; // @ok
+  if (st.use.c()) run(); // @ok
+  switch (st.use.mode()) { case "a": run(); } // @ok
+  for (const item of st.use.items()) run(item); // @ok
+  const selected = st.sel((s) => s.d); // @ok
+  const latest = st.ref((s) => s.e); // @ok
+  const save = st.tool("save").desc("d").exec(async () => { await st.do.saveX(); }); // @ok
+  const [f, setF] = st.useState("f", String).desc("d").init(""); // @ok
+  st.expose("g", String).desc("d").value(f); // @ok
+  useEffect(() => st.sub((s) => s.h, run), []); // @ok
+  return <div onClick={() => st.do.setNameOnX(st.get().name)}>{open ? <Child /> : null}</div>; // @ok
+};
+export const B = memo(() => { const a = st.use.a(); return null; }); // @ok
+export const C = forwardRef((props, ref) => { const b = st.sel((s) => s.b); return null; }); // @ok
+export const useTools = () => { const tool = (name) => st.tool(name).desc("d").exec(() => run()); tool("a"); }; // @ok
+export const D = () => <Load.Units renderItem={(item) => <Row key={item.id} id={item.id} />} />; // @ok
+export const E = () => { const busy = open && other.use.x(); return busy; }; // @ok
+export const F = () => { const Submit = useMemo(() => () => { const v = st.use.x(); return v; }, []); return <Submit />; }; // @ok
+export const G = () => { const Submit = useMemo(() => (open ? () => null : () => { const save = st.tool("s").desc("d").exec(run); return <Button onClick={save} />; }), [open]); return <Submit />; }; // @ok
+export const H = () => { for (let i = st.use.start(); i < 3; i++) run(i); return null; }; // @ok
+export const I = isNative ? () => { const a = st.use.a(); return a; } : () => null; // @ok
+export const J = () => { const a = (() => st.use.x())(); return a; }; // @ok
+export const K = () => { const Row = () => { const a = st.use.a(); return a; }; return <List row={Row} />; }; // @ok
+const renderPage = () => { const a = st.use.a(); return a; }; // @ok
+export const L = page().render(renderPage); // @ok
+export const M = () => { const v = st.use.x(); props.onPick?.(v); return v; }; // @ok
+export const N = () => { const a = st["use"].a(); const b = st.use["b"](); return a ?? b; }; // @ok
+export const O = () => { let v = cached; v = st.use.a(); return v; }; // @ok

package/lint/no-conditional-st-hook.grit

@@ -0,0 +1,146 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `st.use.<key>()`, `st.slice.<name>.use.<key>()`, `st.sel()`, `st.ref()` and the builders' last step
+// (`st.tool(…)….exec()` / `.card()`, `st.useState(…)….init()`, `st.expose(…)….value()`) are React hooks that Biome's
+// `useHookAtTopLevel` cannot see: it recognises a hook by a `use` prefix on the called name. A hook a render skips
+// shifts every later hook by one slot, and production React does not check the order — a later `useRef` then
+// receives a frozen store value and the screen dies far from the cause ("Cannot add property current, object is not
+// extensible").
+//
+// Reported: the right operand of `||` / `&&` / `??` and of `||=` / `&&=` / `??=`, a ternary branch, an `if` / `else`
+// body, a `switch` case, a loop (a `for` initializer runs once and is not one), a `catch` block, a default value,
+// the arguments of an optional call, and a callback handed to a call or a JSX prop inside a component, inline or by
+// a camelCase name (`.map`, `useEffect`, an event handler, a render prop — `Load.Units` calls `renderList` only while
+// the list is non-empty). A test position is not reported: `if (st.use.x())` always runs. Each position counts up to
+// the nearest function only, so a component defined in `useMemo` or picked by a module-level ternary is its own
+// render; a PascalCase name is a component, which React renders rather than calls.
+//
+// Not reported: a hook after an early `return` (GritQL sees no statement order), a local helper the component
+// calls (`const tool = (name) => st.tool(name)…exec(…)` runs a fixed number of times when called at top level),
+// and a hook reached through anything but the `st` identifier.
+//
+pattern st_hook_call() {
+  or {
+    `st.use.$key($args)`,
+    `st.slice.$slice.use.$key($args)`,
+    `st.sel($args)`,
+    `st.ref($args)`,
+    `$chain.exec($args)` where { $chain <: r"st\s*\.\s*tool\s*\([\s\S]*" },
+    `$chain.card($args)` where { $chain <: r"st\s*\.\s*tool\s*\([\s\S]*" },
+    `$chain.init($args)` where { $chain <: r"st\s*\.\s*useState\s*\([\s\S]*" },
+    `$chain.value($args)` where { $chain <: r"st\s*\.\s*expose\s*\([\s\S]*" },
+    // Computed access (`st["use"].x()`, `st.use[key]()`) at any step, which would take a snippet per combination.
+    JsCallExpression(callee = $callee) where {
+      $callee <: or {
+        r"st\s*(?:\.\s*use|\[\s*[\x27\x22`]use[\x27\x22`]\s*\])\s*(?:\.\s*[\w$]+|\[[^\]]*\])",
+        r"st\s*(?:\.\s*slice|\[\s*[\x27\x22`]slice[\x27\x22`]\s*\])\s*(?:\.\s*[\w$]+|\[[^\]]*\])\s*(?:\.\s*use|\[\s*[\x27\x22`]use[\x27\x22`]\s*\])\s*(?:\.\s*[\w$]+|\[[^\]]*\])",
+        r"st\s*\[\s*[\x27\x22`](?:sel|ref)[\x27\x22`]\s*\]"
+      }
+    }
+  }
+}
+
+pattern function_like() {
+  or {
+    JsArrowFunctionExpression(),
+    JsFunctionExpression(),
+    JsFunctionDeclaration(),
+    JsFunctionExportDefaultDeclaration(),
+    JsMethodObjectMember(),
+    JsGetterObjectMember(),
+    JsSetterObjectMember(),
+    JsMethodClassMember(),
+    JsGetterClassMember(),
+    JsSetterClassMember(),
+    JsConstructorClassMember()
+  }
+}
+
+// An IIFE runs where it stands, so the position around it still decides whether its hooks run.
+pattern function_boundary() {
+  function_like() as $boundary where {
+    not $boundary <: within JsCallExpression(callee = $iifeCallee) where {
+      $iifeCallee <: or { $boundary, JsParenthesizedExpression(expression = $boundary) }
+    }
+  }
+}
+
+pattern callback_slot() {
+  or { JsCallArguments(), JsxExpressionAttributeValue(), JsxExpressionChild() }
+}
+
+pattern passed_by_name($name) {
+  or {
+    JsCallArguments(args = [..., $arg where { $arg <: $name }, ...]),
+    JsxExpressionAttributeValue(expression = $arg) where { $arg <: $name },
+    JsxExpressionChild(expression = $arg) where { $arg <: $name }
+  }
+}
+
+JsCallExpression() as $call where {
+  $call <: st_hook_call(),
+  or {
+    $call <: within JsLogicalExpression(right = $right) where { $right <: contains $call } until function_boundary(),
+    // The operator token is not a field GritQL can read; `[^=]*` makes the first `=` in the text the operator's.
+    $call <: within JsAssignmentExpression(right = $right) as $assignment where {
+      $assignment <: r"[^=]*(?:\|\||&&|\?\?)=[\s\S]*",
+      $right <: contains $call
+    } until function_boundary(),
+    $call <: within JsConditionalExpression(consequent = $then, alternate = $else) where {
+      or { $then <: contains $call, $else <: contains $call }
+    } until function_boundary(),
+    $call <: within JsIfStatement(consequent = $then, else_clause = $else) where {
+      or { $then <: contains $call, $else <: contains $call }
+    } until function_boundary(),
+    $call <: within JsForStatement(initializer = $init) where { not $init <: contains $call } until function_boundary(),
+    $call <: within JsForOfStatement(body = $body) where { $body <: contains $call } until function_boundary(),
+    $call <: within JsForInStatement(body = $body) where { $body <: contains $call } until function_boundary(),
+    $call <: within or {
+      JsCaseClause(),
+      JsDefaultClause(),
+      JsWhileStatement(),
+      JsDoWhileStatement(),
+      JsCatchClause()
+    } until function_boundary(),
+    $call <: within or {
+      JsFormalParameter(initializer = $default),
+      JsObjectBindingPatternShorthandProperty(init = $default),
+      JsObjectBindingPatternProperty(init = $default),
+      JsArrayBindingPatternElement(init = $default),
+      JsObjectAssignmentPatternShorthandProperty(init = $default),
+      JsObjectAssignmentPatternProperty(init = $default),
+      JsArrayAssignmentPatternElement(init = $default)
+    } where { $default <: contains $call } until function_boundary(),
+    // A `?.` ahead of the callee's first `(` or `[` sits on its own chain, so a nullish link skips the arguments.
+    $call <: within JsCallExpression(callee = $callee, arguments = $arguments) as $outerCall where {
+      $arguments <: contains $call,
+      or { $outerCall <: `$optionalCallee?.($optionalArgs)`, $callee <: r"[^\[\(]*\?\.[\s\S]*" }
+    } until function_boundary(),
+    and {
+      $call <: within function_boundary() as $nearest until function_boundary(),
+      or {
+        // The callback must be handed over inside another function: a component passed to `memo()` /
+        // `forwardRef()` at module level is not one.
+        $nearest <: within callback_slot() as $slot where { $slot <: within function_boundary() } until function_boundary(),
+        and {
+          or {
+            $nearest <: JsFunctionDeclaration(id = $name),
+            $nearest <: within JsVariableDeclarator(id = $name, initializer = JsInitializerClause(expression = $value)) where {
+              $value <: $nearest
+            } until function_boundary()
+          },
+          $name <: r"[a-z_$][\w$]*",
+          $nearest <: within or { JsFunctionBody(), JsModule() } as $scope where {
+            $scope <: contains passed_by_name($name) as $handover where { $handover <: within function_boundary() }
+          } until or { JsFunctionBody(), JsModule() }
+        }
+      }
+    }
+  },
+  register_diagnostic(
+    span = $call,
+    message = "This st hook does not run on every render — it sits behind a condition, in a loop, or in a nested function. React matches hooks by call order, so the hooks after it shift by one slot and a later one reads another hook's state; production React does not check, and the screen crashes somewhere else. Read each st.use.* into its own const at the top of the component, then combine the values: const uploading = st.use.xUploading(); const formUploading = st.use.xFormUploading(); const busy = uploading || !!formUploading.voice. For a list, move the hook into a child component rendered per item.",
+    severity = "error"
+  )
+}

package/mobile/desktopServerStage.ts

@@ -33,6 +33,7 @@ export class DesktopServerStage {
     "console.js",
     "console-runtime.js",
     "csr",
+    "mcp-apps",
     "public",
     ".akan",
   ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0-rc.9",
+  "version": "3.1.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -14,7 +14,7 @@
     "directory": "pkgs/@akanjs/devkit"
   },
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.4"
   },
   "exports": {
     ".": {
@@ -46,25 +46,25 @@
     "@earendil-works/pi-coding-agent": "1.3.0",
     "@earendil-works/pi-mcp": "1.3.0",
     "@earendil-works/pi-tui": "1.3.0",
-    "@inquirer/prompts": "^8.4.3",
-    "@tailwindcss/node": "^4.3.0",
-    "akanjs": "3.1.0-rc.9",
-    "chalk": "^5.6.2",
-    "commander": "^14.0.3",
-    "dayjs": "^1.11.20",
-    "fontaine": "^0.8.0",
+    "@inquirer/prompts": "^8.7.3",
+    "@tailwindcss/node": "^4.3.3",
+    "akanjs": "3.1.0",
+    "chalk": "^6.0.1",
+    "commander": "^15.0.0",
+    "dayjs": "^1.11.23",
+    "fontaine": "^1.0.1",
     "fonteditor-core": "^2.6.3",
-    "ignore": "^7.0.5",
-    "ora": "^9.4.0",
+    "ignore": "^7.0.12",
+    "ora": "^9.4.1",
     "ssh2": "^1.17.0",
-    "subset-font": "^2.5.0",
+    "subset-font": "^2.9.0",
     "tailwind-scrollbar": "^4.0.2",
-    "tailwindcss": "^4.3.0",
-    "typebox": "1.1.38",
+    "tailwindcss": "^4.3.3",
+    "typebox": "1.3.37",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "react": "19.3.0"
+    "react": "19.3.1"
   },
   "peerDependenciesMeta": {
     "react": {

package/routeSourceValidator.test.ts

@@ -43,7 +43,7 @@ describe("RouteSourceValidator route chains", () => {
   const chain = (source: string, kind: "page" | "layout", pattern: string) =>
     RouteSourceValidator.validateRouteSourceExports(source, `page/${kind}.tsx`, kind, { pattern });
 
-  test("reads params, prompt and devOnly off a page() chain without evaluating it", () => {
+  test("reads params, prompt, apps and devOnly off a page() chain without evaluating it", () => {
     const source = [
       'import { page } from "akanjs/client";',
       "export default page()",
@@ -51,11 +51,13 @@ describe("RouteSourceValidator route chains", () => {
       '  .search("status", String)',
       "  .config({ transition: 'stack', devOnly: true })",
       '  .prompt("briefProject", "Brief one project.")',
-      "  .render(async ({ projectId }) => null);",
+      '  .app("showProject", "Show one project.", ({ projectId }) => null)',
+      '  .app("showBoard", "Show its board.", ({ projectId }) => null)',
+      "  .render(async ({ projectId, showProject }) => showProject);",
     ].join("\n");
     expect(chain(source, "page", "/:lang/project/:projectId")).toEqual({
       devOnly: true,
-      chain: { kind: "page", params: ["projectId"], prompt: "briefProject" },
+      chain: { kind: "page", params: ["projectId"], prompt: "briefProject", apps: ["showProject", "showBoard"] },
     });
   });
 
@@ -88,16 +90,29 @@ describe("RouteSourceValidator route chains", () => {
     expect(() => chain("export default page().param(name, ID).render(() => null);", "page", "/:lang/:x")).toThrow(
       ".param() takes a string literal first",
     );
+    expect(() => chain('export default page().app(name, "x", () => null).render(() => null);', "page", "/")).toThrow(
+      ".app() takes a string literal first",
+    );
     expect(() => chain("export default page().config({ devOnly: flag }).render(() => null);", "page", "/")).toThrow(
       "devOnly must be a literal true or false",
     );
+    const indirect = [
+      'const memo = page().app("showMemo", "x", () => null).render(() => null);',
+      "export default memo;",
+    ];
+    expect(() => chain(indirect.join("\n"), "page", "/")).toThrow('exports its chain through "memo"');
+    const renamed = [indirect[0], "export { memo as default };"];
+    expect(() => chain(renamed.join("\n"), "page", "/")).toThrow('exports its chain through "memo"');
   });
 
-  test("still reads the legacy shape as before", () => {
+  test("still reads the legacy shape as before, which never takes a guard", () => {
     const source = [
       "export default function Page() { return null; }",
       "export const pageConfig = { devOnly: false };",
     ].join("\n");
     expect(chain(source, "page", "/")).toEqual({ devOnly: false });
+    expect(() => chain(`${source}\nexport const guard = async () => undefined;`, "page", "/")).toThrow(
+      "exports guard beside a legacy default",
+    );
   });
 });

package/routeSourceValidator.ts

@@ -15,6 +15,8 @@ export interface RouteSourceChain {
   params: string[];
   /** The `.prompt()` name, when the page publishes itself as an MCP prompt. */
   prompt?: string;
+  /** The `.app()` names, each one MCP App the build gives a view of its own. */
+  apps: string[];
 }
 
 interface ChainStage {
@@ -80,6 +82,10 @@ export class RouteSourceValidator {
       throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
     }
     const chain = RouteSourceValidator.#readChain(sourceFile, filePath);
+    if (!chain && exported.has("guard"))
+      throw new Error(
+        `[route-convention] ${filePath} exports guard beside a legacy default; declare it with .guard() on its chain`,
+      );
     if (!chain) return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
     const named = [...exported].filter((name) => name !== "default");
     if (named.length)
@@ -93,34 +99,75 @@ export class RouteSourceValidator {
     if (options.pattern) RouteSourceValidator.#assertChainParams(chain, options.pattern, filePath);
     return {
       devOnly: chain.devOnly,
-      chain: { kind: chain.kind, params: chain.params, ...(chain.prompt ? { prompt: chain.prompt } : {}) },
+      chain: {
+        kind: chain.kind,
+        params: chain.params,
+        ...(chain.prompt ? { prompt: chain.prompt } : {}),
+        apps: chain.apps,
+      },
     };
   }
 
   // Null for the legacy shape. Read off the source because the build enumerates routes without importing them.
   static #readChain(sourceFile: ts.SourceFile, filePath: string) {
     for (const statement of sourceFile.statements) {
+      const local = RouteSourceValidator.#defaultLocalOf(statement);
+      if (local && RouteSourceValidator.#bindsChain(sourceFile, local))
+        throw new Error(
+          `[route-convention] ${filePath} exports its chain through "${local}"; write \`export default page()…\` — the build reads the chain without evaluating the module`,
+        );
       if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
-      let node = RouteSourceValidator.#unwrapExpression(statement.expression);
-      const stages: ChainStage[] = [];
-      while (node && ts.isCallExpression(node)) {
-        const callee = node.expression;
-        if (ts.isPropertyAccessExpression(callee)) {
-          stages.unshift({ name: callee.name.text, args: node.arguments });
-          node = callee.expression;
-          continue;
-        }
-        if (ts.isIdentifier(callee) && chainRoots.has(callee.text))
-          return RouteSourceValidator.#chainOf(callee.text as RouteSourceChain["kind"], stages, filePath);
-        return null;
+      const walked = RouteSourceValidator.#walkChain(RouteSourceValidator.#unwrapExpression(statement.expression));
+      return walked ? RouteSourceValidator.#chainOf(walked.kind, walked.stages, filePath) : null;
+    }
+    return null;
+  }
+
+  static #defaultLocalOf(statement: ts.Statement): string | undefined {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      const node = RouteSourceValidator.#unwrapExpression(statement.expression);
+      return node && ts.isIdentifier(node) ? node.text : undefined;
+    }
+    if (!ts.isExportDeclaration(statement) || statement.moduleSpecifier || statement.isTypeOnly) return undefined;
+    const clause = statement.exportClause;
+    if (!clause || !ts.isNamedExports(clause)) return undefined;
+    const element = clause.elements.find((element) => !element.isTypeOnly && element.name.text === "default");
+    return element?.propertyName && ts.isIdentifier(element.propertyName) ? element.propertyName.text : undefined;
+  }
+
+  static #walkChain(start: ts.Expression | undefined) {
+    let node = start;
+    const stages: ChainStage[] = [];
+    while (node && ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (ts.isPropertyAccessExpression(callee)) {
+        stages.unshift({ name: callee.name.text, args: node.arguments });
+        node = callee.expression;
+        continue;
       }
+      if (ts.isIdentifier(callee) && chainRoots.has(callee.text))
+        return { kind: callee.text as RouteSourceChain["kind"], stages };
       return null;
     }
     return null;
   }
 
+  static #bindsChain(sourceFile: ts.SourceFile, name: string) {
+    return sourceFile.statements.some(
+      (statement) =>
+        ts.isVariableStatement(statement) &&
+        statement.declarationList.declarations.some(
+          (declaration) =>
+            ts.isIdentifier(declaration.name) &&
+            declaration.name.text === name &&
+            !!RouteSourceValidator.#walkChain(RouteSourceValidator.#unwrapExpression(declaration.initializer)),
+        ),
+    );
+  }
+
   static #chainOf(kind: RouteSourceChain["kind"], stages: ChainStage[], filePath: string) {
     const params: string[] = [];
+    const apps: string[] = [];
     let prompt: string | undefined;
     let devOnly = false;
     const literal = (stage: ChainStage) => {
@@ -134,10 +181,11 @@ export class RouteSourceValidator {
     for (const stage of stages) {
       if (stage.name === "param") params.push(literal(stage));
       else if (stage.name === "prompt") prompt = literal(stage);
+      else if (stage.name === "app") apps.push(literal(stage));
       else if (stage.name === "config")
         devOnly = RouteSourceValidator.#devOnlyOf(RouteSourceValidator.#unwrapExpression(stage.args[0]), filePath);
     }
-    return { kind, params, prompt, devOnly };
+    return { kind, params, prompt, apps, devOnly };
   }
 
   /** The same rule the loader applies: a page names every `[x]` it sits under, a layout may name a subset. */

package/scanInfo.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import path from "node:path";
 import type {
   AppConfigResult,
@@ -295,11 +296,19 @@ class ScanInfo {
 }
 
 export const isAkanFrameworkDependency = (dep: string) => dep === "akanjs" || dep.startsWith("akanjs/");
+export interface MigrationScanEntry {
+  id: string;
+  checksum: string;
+}
+
 export class AppInfo extends ScanInfo {
+  static readonly migrationDir = "script/migration";
+  static readonly #migrationIdRe = /^\d{12}_[A-Za-z][A-Za-z0-9]*$/;
   readonly type = "app";
   readonly exec: AppExecutor;
   readonly akanConfig: AppConfigResult;
   readonly libDeps: string[];
+  readonly migrations: MigrationScanEntry[];
 
   static appInfos = new Map<string, AppInfo>();
   static async fromExecutor(exec: AppExecutor, options: { refresh?: boolean } = {}) {
@@ -314,17 +323,21 @@ export class AppInfo extends ScanInfo {
         LibInfo.libInfos.set(libName, await LibInfo.fromExecutor(libExecutor));
       }),
     );
-    const libDeps = await AppInfo.#getAllLibDeps(exec, scanResult.libDeps);
-    const appInfo = new AppInfo(exec, scanResult as AppScanResult, libDeps);
+    const [libDeps, migrations] = await Promise.all([
+      AppInfo.#getAllLibDeps(exec, scanResult.libDeps),
+      AppInfo.scanMigrations(exec),
+    ]);
+    const appInfo = new AppInfo(exec, scanResult as AppScanResult, libDeps, migrations);
     AppInfo.appInfos.set(exec.name, appInfo);
     return appInfo;
   }
 
-  constructor(exec: AppExecutor, scanResult: AppScanResult, libDeps: string[]) {
+  constructor(exec: AppExecutor, scanResult: AppScanResult, libDeps: string[], migrations: MigrationScanEntry[] = []) {
     super(scanResult);
     this.exec = exec;
     this.akanConfig = scanResult.akanConfig;
     this.libDeps = libDeps;
+    this.migrations = migrations;
   }
   override getScanResult(): AppScanResult {
     return this.scanResult as AppScanResult;
@@ -334,6 +347,26 @@ export class AppInfo extends ScanInfo {
     (this.scanResult as AppScanResult).routes = routes;
   }
 
+  //* Line endings and a BOM dropped: an editor or autocrlf would otherwise record another checksum for the same script.
+  static async scanMigrations(exec: AppExecutor) {
+    const files = (await exec.readdir(AppInfo.migrationDir)).filter(
+      (file) => file.endsWith(".ts") && !/\.(test|spec|d)\.ts$/.test(file),
+    );
+    return await Promise.all(
+      files.map(async (file) => {
+        const id = file.slice(0, -".ts".length);
+        if (!AppInfo.#migrationIdRe.test(id))
+          throw new Error(
+            `${AppInfo.migrationDir}/${file}: a migration is named <yyyyMMddHHmm>_<camelName>.ts; create one with \`akan create-migration\``,
+          );
+        const source = (await exec.readFile(`${AppInfo.migrationDir}/${file}`))
+          .replace(/^\uFEFF/, "")
+          .replaceAll("\r\n", "\n");
+        return { id, checksum: createHash("sha256").update(source).digest("hex") };
+      }),
+    );
+  }
+
   static async #getAllLibDeps(exec: AppExecutor, libDeps: string[], libSet = new Set<string>()) {
     await Promise.all(
       libDeps.map(async (libName) => {

package/subspace.test.ts

@@ -245,7 +245,7 @@ describe("Subspace push", () => {
     expect(second.sha).not.toBe(first.sha);
   });
 
-  test("keeps the subspace's own root config and drops a Jenkinsfile an earlier push left there", async () => {
+  test("keeps the subspace's own root config and a Jenkinsfile an earlier push left there, never the workspace's", async () => {
     const { workRoot, bareRoot, subspace } = await makeMirror("own-served", "own-private", "own-kit");
     const customer = await cloneSubspace(workRoot, bareRoot, "own-customer");
     await write(path.join(customer, "akan.config.ts"), "export default { pipeline: {} };\n");
@@ -261,7 +261,8 @@ describe("Subspace push", () => {
     expect(await FileSys.readText(path.join(subspaceRoot, "akan.config.ts"))).toContain(
       "export default { pipeline: {} };",
     );
-    expect(await FileSys.fileExists(path.join(subspaceRoot, "Jenkinsfile"))).toBe(false);
+    expect(await FileSys.fileExists(path.join(subspaceRoot, "Jenkinsfile"))).toBe(true);
+    expect(await FileSys.readText(path.join(subspaceRoot, "Jenkinsfile"))).toContain("pipeline { agent none }");
   });
 
   test("refuses a lock that resolves from a registry only this machine reaches, before it clones", async () => {

package/subspaceClone.ts

@@ -47,10 +47,6 @@ export class SubspaceClone {
     this.#clone = new Executor(`subspace-${declaration.name}`, this.#clonePath);
   }
 
-  async #cloneGit(args: string[]) {
-    return await this.#workspace.spawn("git", ["-C", this.#clonePath, ...args]);
-  }
-
   async #ensure(branch: string) {
     if (!(await FileSys.dirExists(path.join(this.#clonePath, ".git")))) {
       await rm(this.#clonePath, { recursive: true, force: true });
@@ -160,15 +156,13 @@ export class SubspaceClone {
     await rm(path.join(this.#clonePath, SubspaceClone.holdDir), { recursive: true, force: true });
   }
 
-  //* A root entry last written by a sync commit is a copy an earlier push left there, the parent's Jenkinsfile among them:
-  //* it goes. Any other is the subspace's own and is held through the extraction.
+  //* Held even when an earlier push left it, the workspace's Jenkinsfile among them: it is the subspace's only copy.
   async #holdRootEntries() {
     const holdRoot = path.join(this.#clonePath, SubspaceClone.holdDir, "root");
     const held: string[] = [];
     for (const entry of SubspaceClone.subspaceOwnedRootEntries) {
       const from = path.join(this.#clonePath, entry);
       if (!(await FileSys.entryExists(from))) continue;
-      if (await this.#isPushedCopy(entry)) continue;
       await mkdir(holdRoot, { recursive: true });
       await rename(from, path.join(holdRoot, entry));
       held.push(entry);
@@ -185,11 +179,6 @@ export class SubspaceClone {
     }
   }
 
-  async #isPushedCopy(entry: string) {
-    const subject = await this.#cloneGit(["log", "-1", "--format=%s", "--", entry]).catch(() => "");
-    return subject.trim().startsWith(SubspaceClone.syncSubjectPrefix);
-  }
-
   static async #copyMissing(from: string, to: string) {
     await mkdir(to, { recursive: true });
     for (const entry of await readdir(from, { withFileTypes: true })) {

package/transforms/mcpAppPageTrimmer.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { symlink } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+import { McpAppPageTrimmer } from "./mcpAppPageTrimmer";
+
+const makeTempRoot = tempDirs("akan-mcp-app-trim-");
+
+describe("McpAppPageTrimmer", () => {
+  test("hands every stage but the apps a function that draws nothing, and keeps the rest of the chain as written", () => {
+    const source = [
+      'import { fetch, Memo } from "@apps/minimal/client";',
+      'import { Screen } from "@apps/minimal/ui";',
+      "export default page()",
+      '  .param("memoId", ID)',
+      "  .config({ topInset: 48 })",
+      "  .guard(async ({ memoId }) => { await fetch.memo(memoId); })",
+      "  .head(<title>Memo</title>)",
+      "  .loading(() => <Screen>loading</Screen>)",
+      '  .app("showMemo", "Show one memo.", ({ memoId }) => <Memo.Zone.View view={fetch.viewMemo(memoId).memoView} />)',
+      "  .render(({ memoId, showMemo }) => (",
+      '    <Screen className="pb-10">{showMemo}</Screen>',
+      "  ));",
+    ].join("\n");
+    expect(McpAppPageTrimmer.trim(source, "memo.tsx")).toBe(
+      [
+        'import { fetch, Memo } from "@apps/minimal/client";',
+        'import { Screen } from "@apps/minimal/ui";',
+        "export default page()",
+        '  .param("memoId", ID)',
+        "  .config({ topInset: 48 })",
+        "  .guard(() => null)",
+        "  .head(() => null)",
+        "  .loading(() => null)",
+        '  .app("showMemo", "Show one memo.", ({ memoId }) => <Memo.Zone.View view={fetch.viewMemo(memoId).memoView} />)',
+        "  .render(() => null);",
+      ].join("\n"),
+    );
+  });
+
+  test("trims a page reached through a link, as a synced lib page is", async () => {
+    const root = await makeTempRoot();
+    await writeText(
+      path.join(root, "libs/shared/page/login.tsx"),
+      [
+        "const page = () => ({ render: (draw: () => string) => draw });",
+        'export default page().render(() => "drawn by the render");',
+      ].join("\n"),
+    );
+    await symlink(path.join(root, "libs/shared/page"), path.join(root, "linked"));
+    await writeText(path.join(root, "entry.ts"), 'import login from "./linked/login.tsx";\nexport { login };\n');
+    const result = await Bun.build({
+      entrypoints: [path.join(root, "entry.ts")],
+      plugins: [McpAppPageTrimmer.plugin([path.join(root, "linked/login.tsx")])],
+    });
+    const [output] = result.outputs;
+    expect(result.success).toBe(true);
+    expect(await output?.text()).not.toContain("drawn by the render");
+  });
+
+  test("drops a lazy component only the page's render drew, with what it imports", async () => {
+    const root = await makeTempRoot();
+    await writeText(path.join(root, "Globe.ts"), 'export default "a heavy globe";\n');
+    await writeText(
+      path.join(root, "trip.tsx"),
+      [
+        "const lazy = (load: () => Promise<unknown>) => ({ load });",
+        'const Globe = lazy(() => import("./Globe"));',
+        "const page = () => ({ app: (name: string, draw: () => unknown) => ({ render: (render: () => unknown) => [name, draw, render] }) });",
+        'export default page().app("showTrip", () => "a trip card").render(() => Globe);',
+      ].join("\n"),
+    );
+    await writeText(path.join(root, "entry.ts"), 'import trip from "./trip.tsx";\nconsole.info(trip);\n');
+    const result = await Bun.build({
+      entrypoints: [path.join(root, "entry.ts")],
+      plugins: [McpAppPageTrimmer.plugin([path.join(root, "trip.tsx")])],
+      splitting: false,
+    });
+    const text = (await result.outputs[0]?.text()) ?? "";
+    expect(result.success).toBe(true);
+    expect(text).toContain("a trip card");
+    expect(text).not.toContain("a heavy globe");
+  });
+
+  test("leaves a module with no chain as it is", () => {
+    const legacy = "export default function Page() { return <main />; }\nexport const pageConfig = {};";
+    expect(McpAppPageTrimmer.trim(legacy, "legacy.tsx")).toBe(legacy);
+  });
+});