@akanjs/devkit 3.0.0-alpha.5 → 3.0.0-alpha.50

package/lint/no-return-in-store-action.grit

@@ -0,0 +1,35 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Every prototype method of a `store(...)` class is registered as an action
+// (StoreRegistry.register) and reaches callers only as `st.do.<action>`, which re-wraps it
+// (StoreInstance.#extendAccessors) and is typed void by `VoidActions` in
+// pkgs/akanjs/store/types.ts. A returned value is therefore unreachable from every call
+// site — it reads like a contract while being dead code. Write the result into state with
+// `this.set({ ... })` instead.
+//
+// Deliberately not flagged, because none of these are actions: a bare `return;` guard, a
+// `return` belonging to a nested callback, a getter, a `static` helper, and a class-property
+// arrow (an instance field, so `register` never sees it).
+`return $value;` as $return where {
+  not $value <: r"",
+  $return <: within JsClassDeclaration() as $storeClass where {
+    $storeClass <: contains JsExtendsClause() as $extends where {
+      $extends <: r"extends\s+store\([\s\S]*"
+    }
+  },
+  $return <: within JsMethodClassMember() as $action where {
+    not $action <: r"static[\s\S]*"
+  },
+  not $return <: within JsArrowFunctionExpression(),
+  not $return <: within JsFunctionExpression(),
+  not $return <: within JsFunctionDeclaration(),
+  not $return <: within JsMethodObjectMember(),
+  not $return <: within JsGetterObjectMember(),
+  not $return <: within JsSetterObjectMember(),
+  register_diagnostic(
+    span = $return,
+    message = "Store actions dispatch as void — st.do.<action>() never exposes this value. Write the result into state with this.set({ ... }) and drop the returned value; a bare 'return;' guard clause is fine.",
+    severity = "error"
+  )
+}

package/lint/no-unpublished-form-setter.grit

@@ -0,0 +1,41 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A form control publishes its own setter by reading the action off the function it was handed
+// (`actionTagOf` in pkgs/akanjs/store/actionTag.ts). A setter passed by reference names the field it
+// writes, so the control emits `data-akan-action` and `useFieldTool` publishes the field to the in-page
+// agent. An arrow that only forwards its argument is a fresh anonymous closure carrying neither, so the
+// field silently becomes unreachable to the agent, to an E2E selector, and to the accessibility tree —
+// while looking identical to a reader. Generated field setters take exactly one value
+// (`makeFormSetter` in pkgs/akanjs/store/action.ts), so the wrapper never changes what runs.
+//
+// Only a pure forwarding body is reported: the argument reaches the setter unchanged, as the sole
+// statement. Each other shape has its own home, so none of them is reported here:
+//
+//   normalize  `(v) => set(formatPhone(v))`      -> the control's own `transform` prop, which every text and
+//                                                   number `Field.*` already takes. Keep `onChange` a reference.
+//   composite  `(v) => { set(v); other(v); }`    -> a `_postSet<Field>` method on the store, with the generated
+//                                                   setter left on the control. A generated action cannot be
+//                                                   overridden: mapped types make them properties (TS2425).
+//   nested     `(v) => writeOnX('a.3.b', v)`     -> unannotatable by design. An agent reaches an embedded row
+//                                                   through `fill<Model>Form`, which waves composites through.
+//
+// A typed parameter (`(v: string) => st.do.setVOnX(v)`) is not matched: the parameter and the argument
+// bind to different text, so the metavariable cannot unify them. Under-reporting, not a false positive.
+//
+JsxAttribute() as $attr where {
+  $attr <: contains JsArrowFunctionExpression() as $arrow,
+  $arrow <: `($p) => $body`,
+  // One bare parameter. A metavariable matches a whole parameter list leniently, so `(a, b)` binds the
+  // text "a, b" and is excluded here rather than by the snippet.
+  $p <: r"[A-Za-z_$][A-Za-z0-9_$]*",
+  $body <: contains `st.do.$action($p)` as $call,
+  $action <: r"set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*",
+  // The body is that call and nothing else — `r"..."` is a full match, so an extra statement fails it.
+  $body <: r"\{?\s*(?:void\s+|await\s+)?st\.do\.[A-Za-z0-9_$]+\([A-Za-z_$][A-Za-z0-9_$]*\)\s*;?\s*\}?",
+  register_diagnostic(
+    span = $arrow,
+    message = "This arrow only forwards its argument, and an anonymous closure names no action — the control publishes no agent tool and emits no data-akan-action for the field. Pass the setter by reference: onChange={st.do.setTypeOnTicket}. A wrapper that does more is not reported: normalization belongs in the control's transform prop, a multi-write belongs in a _postSet<Field> hook on the store, and a nested path through writeOnX is reached by the agent through fill<Model>Form.",
+    severity = "error"
+  )
+}

package/linter.ts

@@ -58,19 +58,31 @@ interface LintResponse {
   warnings: LintMessage[];
 }
 
+/** Biome reads `biome.json` first and `biome.jsonc` second; only the latter may carry comments. */
+const BIOME_CONFIG_FILES = ["biome.json", "biome.jsonc"] as const;
+
 export class Linter {
   lintRoot: string;
+  configPath: string;
   #biomeBin: string;
 
   constructor(cwdPath: string) {
     this.lintRoot = this.#findBiomeRootPath(cwdPath);
+    this.configPath = Linter.#configPathIn(this.lintRoot) ?? path.join(this.lintRoot, "biome.json");
     const localBiomeBin = path.join(this.lintRoot, "node_modules/.bin/biome");
     this.#biomeBin = existsSync(localBiomeBin) ? localBiomeBin : "biome";
   }
 
+  static #configPathIn(dir: string): string | null {
+    for (const fileName of BIOME_CONFIG_FILES) {
+      const configPath = path.join(dir, fileName);
+      if (existsSync(configPath)) return configPath;
+    }
+    return null;
+  }
+
   #findBiomeRootPath(dir: string): string {
-    const configPath = path.join(dir, "biome.json");
-    if (existsSync(configPath)) return dir;
+    if (Linter.#configPathIn(dir)) return dir;
     const parentDir = path.dirname(dir);
     if (parentDir === dir) throw new Error(`biome.json not found from ${dir}`);
     return this.#findBiomeRootPath(parentDir);
@@ -193,7 +205,7 @@ export class Linter {
       "--max-diagnostics=none",
       "--no-errors-on-unmatched",
       "--config-path",
-      path.join(this.lintRoot, "biome.json"),
+      this.configPath,
       this.#toBiomePath(filePath),
     ]);
     const report = this.#parseBiomeReport(stdout || stderr);
@@ -390,14 +402,7 @@ export class Linter {
 
     const source = readFileSync(resolvedFilePath, "utf8");
     const { stdout } = await this.#runBiome(
-      [
-        "check",
-        "--write",
-        "--config-path",
-        path.join(this.lintRoot, "biome.json"),
-        "--stdin-file-path",
-        this.#toBiomePath(resolvedFilePath),
-      ],
+      ["check", "--write", "--config-path", this.configPath, "--stdin-file-path", this.#toBiomePath(resolvedFilePath)],
       source,
     );
     const lintResult = await this.lintFile(resolvedFilePath);
@@ -412,7 +417,7 @@ export class Linter {
   async getConfigForFile(filePath: string): Promise<unknown> {
     const resolvedFilePath = this.#resolveFilePath(filePath);
     if (!existsSync(resolvedFilePath)) throw new Error(`File not found: ${filePath}`);
-    return JSON.parse(readFileSync(path.join(this.lintRoot, "biome.json"), "utf8")) as unknown;
+    return JSON.parse(readFileSync(this.configPath, "utf8")) as unknown;
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.5",
+  "version": "3.0.0-alpha.50",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -14,7 +14,7 @@
     "directory": "pkgs/@akanjs/devkit"
   },
   "engines": {
-    "bun": ">=1.3.13"
+    "bun": ">=1.4.0"
   },
   "exports": {
     ".": {
@@ -23,6 +23,7 @@
       "default": "./index.ts"
     },
     "./package.json": "./package.json",
+    "./biome.base.json": "./biome.base.json",
     "./akanApp": "./akanApp/index.ts",
     "./akanConfig": "./akanConfig/index.ts",
     "./artifact": "./artifact/index.ts",
@@ -44,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.5",
+    "akanjs": "3.0.0-alpha.50",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",
@@ -52,7 +53,6 @@
     "fonteditor-core": "^2.6.3",
     "ignore": "^7.0.5",
     "ink": "^6.8.0",
-    "js-yaml": "^4.1.1",
     "ora": "^9.4.0",
     "ssh2": "^1.17.0",
     "subset-font": "^2.5.0",

package/qualityScanner.test.ts

@@ -184,6 +184,15 @@ describe("AkanQualityScanner ssr rules", () => {
   });
 });
 
+const signalOf = (entries: string) =>
+  [
+    `import { endpoint, slice } from "akanjs/signal";`,
+    `export class PostSlice extends slice(srv.post, { guards: {}, mcp: { get: true } }, (init) => ({`,
+    entries,
+    `})) {}`,
+    "",
+  ].join("\n");
+
 describe("AkanQualityScanner layout rules", () => {
   test("flags an unknown app root file but not a facet entrypoint", async () => {
     const root = await makeWorkspace({
@@ -196,4 +205,47 @@ describe("AkanQualityScanner layout rules", () => {
     expect(warnings).toHaveLength(1);
     expect(warnings[0]?.file).toBe("apps/demo/helper.ts");
   });
+
+  test("flags an unknown lib root file but not a facet entrypoint", async () => {
+    const root = await makeWorkspace({
+      "libs/demo/client.ts": "export const client = 1;\n",
+      "libs/demo/helper.ts": "export const helper = 1;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.lib-root-file");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("libs/demo/helper.ts");
+  });
+
+  test("flags a root folder no facet owns, on both sides", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/base/helper.ts": "export const helper = 1;\n",
+      "apps/demo/common/helper.ts": "export const helper = 1;\n",
+      "libs/demo/base/helper.ts": "export const helper = 1;\n",
+      "libs/demo/common/helper.ts": "export const helper = 1;\n",
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+
+    expect(rulesOf(result, "akan.layout.app-root-folder").map((warning) => warning.file)).toEqual([
+      "apps/demo/base/helper.ts",
+    ]);
+    expect(rulesOf(result, "akan.layout.lib-root-folder").map((warning) => warning.file)).toEqual([
+      "libs/demo/base/helper.ts",
+    ]);
+  });
+
+  test("keeps a root signal test out of the lib facet rule", async () => {
+    const root = await makeWorkspace({
+      "libs/demo/lib/cnst.ts": "export const cnst = 1;\n",
+      "libs/demo/lib/user.signal.test.ts": "export const test = 1;\n",
+      "libs/demo/lib/helper.ts": "export const helper = 1;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.lib-facet-file");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("libs/demo/lib/helper.ts");
+  });
 });

package/qualityScanner.ts

@@ -1,14 +1,16 @@
 import { createHash } from "node:crypto";
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
 import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
+import { FormSetterScanner } from "./formSetterScanner";
 import { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
-import { appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
+import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
-type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "agent";
 
 export interface QualityWarning {
   rule: string;
@@ -87,7 +89,8 @@ const SUGGESTED_RULES = [
   "Keep apps/*/lib and libs/*/lib root files limited to generated support facets such as cnst.ts, db.ts, dict.ts, sig.ts, srv.ts, st.ts, useClient.ts, and useServer.ts.",
   "Use domain module folders consistently: lib/<model> for database modules, lib/_<service> for service modules, and lib/__scalar/<scalar> for scalar modules.",
   "Keep module UI filenames predictable: database modules use <Model>.Template/Unit/Util/View/Zone.tsx, service modules use <Service>.Util/Zone.tsx, and scalar modules use <Scalar>.Template/Unit.tsx.",
-  "Move shared app utilities to apps/*/common instead of creating apps/*/base.",
+  "Hand a form control its store setter by reference so the field publishes an agent tool; put normalization in the control's transform prop and a multi-write in a _postSet<Field> hook on the store.",
+  "Move shared app and lib utilities to common/ instead of creating apps/*/base or libs/*/base.",
   "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline.",
 ];
 
@@ -100,24 +103,6 @@ const CONVENTION_SUFFIXES = [
   ".store.ts",
 ] as const;
 
-// Non-PascalCase exports the framework recognizes on page/layout route modules (see PageModule/LayoutModule
-// in pkgs/akanjs/client/csrTypes.ts). PascalCase route exports (Loading, NotFound, Error) pass the component
-// check, and the `default` export is handled separately.
-const PAGE_RESERVED_EXPORTS = new Set([
-  "pageConfig",
-  "head",
-  "metadata",
-  "generateHead",
-  "generateMetadata",
-  "fonts",
-  "manifest",
-  "theme",
-  "reconnect",
-  "wsConnect",
-  "layoutStyle",
-  "gaTrackingId",
-]);
-
 // How to remediate each rule, keyed by rule id. Surfaced as a `fix:` line per warning (text + JSON output)
 // so the scan result tells the reader what to do, not just what is wrong.
 const RULE_FIXES: Record<string, string> = {
@@ -139,14 +124,22 @@ const RULE_FIXES: Record<string, string> = {
     "Move the Window augmentation into an approved browser integration file and keep it isolated.",
   "akan.file.prototype-mutation": "Avoid prototype mutation, or isolate it in an approved low-level integration file.",
   "akan.file.class-export-global-declaration": "Move the helper to a sibling file and import it into the class module.",
+  "akan.agent.unpublished-form-setter":
+    "Pass the setter by reference where the wrapper only forwards (onChange={st.do.setTitleOnTask}); move normalization into the control's own transform prop; move a multi-write into a _postSet<Field> hook on the store, keeping the generated setter on the control.",
   "akan.file.component-internal-declaration":
     "Move the type or helper to a type/util file in ui/, webkit/, or common/ by purpose. If it is the component's props, declare it as `interface <Component>Props`.",
   "akan.file.component-export":
     "Move the value or type to a util/constant/type file in ui/, webkit/, or common/ and import it. Adding `export` is not a valid fix — only PascalCase components and their `<Component>Props` interface belong here.",
   "akan.layout.app-root-file":
     "Move the file into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit).",
+  "akan.layout.app-root-folder":
+    "Move the folder's contents into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit) and delete it.",
   "akan.layout.lib-root-file":
-    "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
+    "Move the file into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit).",
+  "akan.layout.lib-root-folder":
+    "Move the folder's contents into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit) and delete it.",
+  "akan.layout.lib-facet-file":
+    "Move the file into a domain module folder under lib/; keep the lib facet root limited to generated support facets.",
   "akan.layout.module-ui-file":
     "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component.",
   "akan.ssr.unnecessary-use-client":
@@ -190,6 +183,7 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
+      ...new FormSetterScanner().scan(sourceFiles),
       ...ssr.warnings,
     ];
 
@@ -425,26 +419,31 @@ export class AkanQualityScanner {
   }
 
   #scanLayoutQuality(sourceFile: SourceFileInfo): QualityWarning[] {
-    const segments = sourceFile.file.split("/");
     const warnings: QualityWarning[] = [];
-    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.has(segments[2])) {
-      warnings.push({
-        rule: "akan.layout.app-root-file",
-        scope: "layout",
-        severity: "warning",
-        file: sourceFile.file,
-        message: `Unexpected app root file "${segments[2]}". Keep application code in conventional app folders.`,
-      });
+    const rootEntry = getSysRootEntry(sourceFile.file);
+    if (rootEntry) {
+      const { type, name, isDir } = rootEntry;
+      const allowed = isDir ? rootAllowedDirs[type].has(name) : rootAllowedFiles[type].has(name);
+      const kind = isDir ? "folder" : "file";
+      if (!allowed) {
+        warnings.push({
+          rule: `akan.layout.${type}-root-${kind}`,
+          scope: "layout",
+          severity: "warning",
+          file: sourceFile.file,
+          message: `Unexpected ${type} root ${kind} "${name}". Keep ${type} code in conventional ${type} folders.`,
+        });
+      }
     }
 
-    const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
+    const libFacetFile = getLibFacetRootFile(sourceFile.file);
+    if (libFacetFile && !isAllowedLibFacetRootFile(libFacetFile)) {
       warnings.push({
-        rule: "akan.layout.lib-root-file",
+        rule: "akan.layout.lib-facet-file",
         scope: "layout",
         severity: "warning",
         file: sourceFile.file,
-        message: `Unexpected lib root file "${libRootFile}". Keep direct lib root files limited to generated support facets.`,
+        message: `Unexpected lib facet root file "${libFacetFile}". Keep direct lib/ root files limited to generated support facets.`,
       });
     }
 
@@ -669,7 +668,7 @@ function isRestrictedInternalKind(kind: ComponentFileDeclaration["kind"]) {
 
 function isAllowedComponentExport(declaration: ComponentFileDeclaration, isPage: boolean) {
   if (isComponentValueKind(declaration.kind) && isPascalCaseName(declaration.name)) return true;
-  return isPage && PAGE_RESERVED_EXPORTS.has(declaration.name);
+  return isPage && RESERVED_ROUTE_CONFIG_EXPORTS.has(declaration.name);
 }
 
 function isPascalCaseName(name: string) {
@@ -838,7 +837,19 @@ function getConventionDescription(suffix: (typeof CONVENTION_SUFFIXES)[number],
   return `${modelName}Store`;
 }
 
-function getLibRootFile(file: string) {
+const sysRootTypes = { apps: "app", libs: "lib" } as const;
+
+function getSysRootEntry(file: string) {
+  const segments = file.split("/");
+  const root = segments[0];
+  const name = segments[2];
+  if (!root || !name || segments.length < 3) return null;
+  const type = sysRootTypes[root as keyof typeof sysRootTypes];
+  if (!type) return null;
+  return { type, name, isDir: segments.length > 3 };
+}
+
+function getLibFacetRootFile(file: string) {
   const segments = file.split("/");
   if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
     return segments[3];

package/repoIdentity.ts

@@ -0,0 +1,42 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+// Resolved once per root: every CLI command builds a WorkspaceExecutor, and this would otherwise fork git on each.
+const resolved = new Map<string, string>();
+
+const readRemoteName = (workspaceRoot: string): string | null => {
+  try {
+    const url = execFileSync("git", ["config", "--get", "remote.origin.url"], {
+      cwd: workspaceRoot,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    // Both remote spellings end in the repository: git@host:owner/name.git and https://host/owner/name.git.
+    return (
+      url
+        .replace(/\.git$/, "")
+        .split(/[/:]/)
+        .pop() || null
+    );
+  } catch {
+    // No git, no origin, or no git binary — a fresh `akan workspace` before its first commit lands here.
+    return null;
+  }
+};
+
+/**
+ * The repository's own name.
+ *
+ * Deriving it from the working directory made every generated file that names the repo — the AGENTS.md title, its
+ * `- Repo:` line — depend on what each person happened to call the folder they cloned into, so one commit rendered
+ * a different guide per developer and the diff never settled. The origin remote is the one identity every clone
+ * shares. `AKAN_PUBLIC_REPO_NAME` is deliberately not consulted: that is a deployment namespace (queue prefixes,
+ * cache keys, secret paths) which a monorepo hosting several products legitimately points somewhere else.
+ */
+export const resolveRepoName = (workspaceRoot: string): string => {
+  const cached = resolved.get(workspaceRoot);
+  if (cached) return cached;
+  const repoName = readRemoteName(workspaceRoot) ?? path.basename(workspaceRoot);
+  resolved.set(workspaceRoot, repoName);
+  return repoName;
+};

package/routeSourceValidator.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+
+import { RouteSourceValidator } from "./routeSourceValidator";
+
+const validate = (source: string, kind: "page" | "layout", rootLayout = false) =>
+  RouteSourceValidator.validateRouteSourceExports(source, `page/_${kind}.tsx`, kind, { rootLayout });
+
+describe("RouteSourceValidator", () => {
+  test("accepts every root-layout config export the route tree honors", () => {
+    const source = [
+      "export default function Layout() { return null; }",
+      "export const fonts = [];",
+      "export const manifest = {};",
+      'export const theme = "dark";',
+      "export const reconnect = true;",
+      "export const wsConnect = true;",
+      "export const layoutStyle = {};",
+      'export const gaTrackingId = "G-1";',
+    ].join("\n");
+
+    expect(() => validate(source, "layout", true)).not.toThrow();
+  });
+
+  test("rejects root-layout-only exports on a nested layout and on a page", () => {
+    const source = ["export default function Layout() { return null; }", "export const wsConnect = true;"].join("\n");
+
+    expect(() => validate(source, "layout")).toThrow('unsupported export "wsConnect"');
+    expect(() => validate(source, "page")).toThrow('unsupported export "wsConnect"');
+  });
+
+  test("reads devOnly off pageConfig without evaluating the module", () => {
+    const source = [
+      "export default function Page() { return null; }",
+      "export const pageConfig = { devOnly: true };",
+    ].join("\n");
+
+    expect(RouteSourceValidator.validateRouteSourceExports(source, "page/_index.tsx", "page")).toEqual({
+      devOnly: true,
+    });
+  });
+});

package/routeSourceValidator.ts

@@ -1,3 +1,4 @@
+import { getRouteExports } from "akanjs/common";
 import ts from "typescript";
 
 /** What the build needs out of a route module without evaluating it. */
@@ -16,44 +17,6 @@ export interface RouteSourceInfo {
  * validate a route source stay lean.
  */
 export class RouteSourceValidator {
-  static readonly #pageExports = new Set([
-    "default",
-    "pageConfig",
-    "head",
-    "metadata",
-    "generateHead",
-    "generateMetadata",
-    "Loading",
-  ]);
-  static readonly #rootLayoutExports = new Set([
-    "default",
-    "pageConfig",
-    "head",
-    "metadata",
-    "generateHead",
-    "generateMetadata",
-    "fonts",
-    "manifest",
-    "theme",
-    "reconnect",
-    "layoutStyle",
-    "gaTrackingId",
-    "Loading",
-    "NotFound",
-    "Error",
-  ]);
-  static readonly #layoutExports = new Set([
-    "default",
-    "pageConfig",
-    "head",
-    "metadata",
-    "generateHead",
-    "generateMetadata",
-    "Loading",
-    "NotFound",
-    "Error",
-  ]);
-
   static validateRouteSourceExports(
     source: string,
     filePath: string,
@@ -61,12 +24,7 @@ export class RouteSourceValidator {
     options: { rootLayout?: boolean } = {},
   ): RouteSourceInfo {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-    const allowed =
-      kind === "page"
-        ? RouteSourceValidator.#pageExports
-        : options.rootLayout
-          ? RouteSourceValidator.#rootLayoutExports
-          : RouteSourceValidator.#layoutExports;
+    const allowed = getRouteExports(kind, { rootLayout: options.rootLayout });
     const exported = new Set<string>();
     const assertExport = (name: string) => {
       if (!allowed.has(name)) {

package/scanInfo.ts

@@ -9,9 +9,8 @@ import type {
   PkgScanResult,
   ScanResult,
 } from "./akanConfig";
-
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
-import { appRootAllowedDirs, appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
+import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 const scalarFileTypes = ["constant", "dictionary", "document", "template", "unit", "util", "view", "zone"] as const;
 type ScalarFileType = (typeof scalarFileTypes)[number];
@@ -57,7 +56,6 @@ const moduleUiFileTypes = {
   scalar: new Set(["Template", "Unit"]),
 } satisfies Record<ModuleKind, Set<string>>;
 const testFilePattern = /\.(test|spec)\.(ts|tsx)$/;
-const rootSignalTestFilePattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(ts|tsx)$/;
 
 // The dependency scanner needs `typescript` (~65MB resident). Only the scan/sync commands run it, so
 // load it on demand rather than through the module graph of every process that imports scan info.
@@ -65,8 +63,6 @@ const createDependencyScanner = async (exec: AppExecutor | LibExecutor | PkgExec
   (await import("./dependencyScanner")).TypeScriptDependencyScanner.from(exec);
 
 const isAllowedTestFile = (filename: string) => testFilePattern.test(filename);
-const isAllowedLibRootFile = (filename: string) =>
-  libFacetRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
 const getScanPath = (exec: AppExecutor | LibExecutor, relativePath: string) =>
   path.posix.join(`${exec.type}s`, exec.name, relativePath.split(path.sep).join("/"));
 async function clearGeneratedRootCapacitorConfigs(exec: AppExecutor | LibExecutor) {
@@ -85,24 +81,29 @@ async function assertScanConvention(exec: AppExecutor | LibExecutor, libRoot: {
     violations.push(`${getScanPath(exec, relativePath)}: ${reason}`);
   };
 
-  if (exec.type === "app") {
-    const { files, dirs } = await exec.getFilesAndDirs(".");
-    files
-      .filter((filename) => !appRootAllowedFiles.has(filename))
-      .forEach((filename) => {
-        addViolation(filename, "unsupported app root file");
-      });
-    dirs
-      .filter((dirname) => !appRootAllowedDirs.has(dirname))
-      .forEach((dirname) => {
-        addViolation(dirname, "unsupported app root folder");
-      });
-  }
+  const allowedRootFiles: ReadonlySet<string> = rootAllowedFiles[exec.type];
+  const allowedRootDirs: ReadonlySet<string> = rootAllowedDirs[exec.type];
+  const { files, dirs } = await exec.getFilesAndDirs(".");
+  files
+    .filter((filename) => !allowedRootFiles.has(filename))
+    .forEach((filename) => {
+      addViolation(filename, `unsupported ${exec.type} root file`);
+    });
+  dirs
+    .filter((dirname) => !allowedRootDirs.has(dirname))
+    .forEach((dirname) => {
+      addViolation(dirname, `unsupported ${exec.type} root folder`);
+    });
+
+  //* An app validates its page tree in `getPageKeys`, which a lib has no equivalent of — so a lib's own
+  //* routes went unchecked until whichever app opted into them with `syncPageLibs` blew up on the sync.
+  if (exec.type === "lib")
+    for (const { relativePath, reason } of await exec.getPageConventionViolations()) addViolation(relativePath, reason);
 
   libRoot.files
-    .filter((filename) => !isAllowedLibRootFile(filename))
+    .filter((filename) => !isAllowedLibFacetRootFile(filename))
     .forEach((filename) => {
-      addViolation(path.join("lib", filename), "unsupported lib root file");
+      addViolation(path.join("lib", filename), "unsupported lib facet root file");
     });
 
   libRoot.dirs

package/transforms/externalizeFrameworkPlugin.ts

@@ -65,7 +65,6 @@ const DEFAULT_EXCLUDE_PREFIX = ["@akanjs/cli/", "@akanjs/devkit/"];
 const OPTIONAL_BACKEND_EXTERNAL_EXACT = new Set<string>([
   "@libsql/client",
   "bullmq",
-  "croner",
   "ioredis",
   "postgres",
   "protobufjs",