@akanjs/devkit 3.0.0-alpha.0 → 3.0.0-alpha.10

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.0",
+  "version": "3.0.0-alpha.10",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -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.0",
+    "akanjs": "3.0.0-alpha.10",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/qualityScanner.test.ts

@@ -3,7 +3,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AbstractDoc } from "./abstractDoc";
-import { AkanQualityScanner } from "./qualityScanner";
+import { AkanQualityScanner, type QualityScanResult } from "./qualityScanner";
 
 const tempRoots: string[] = [];
 
@@ -44,3 +44,156 @@ describe("AkanQualityScanner abstract rule", () => {
     expect(warnings[0]?.fix).toContain("akan compact");
   });
 });
+
+const staticMarkup = (elementNum: number) =>
+  Array.from({ length: elementNum }, (_, idx) => `      <p className="text-sm">row ${idx}</p>`).join("\n");
+
+const rulesOf = (result: QualityScanResult, rule: string) => result.warnings.filter((warning) => warning.rule === rule);
+
+describe("AkanQualityScanner ssr rules", () => {
+  test("flags a client file that uses no client-only capability", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Plain.tsx": `"use client";\nexport const Plain = () => <div>plain</div>;\n`,
+      "apps/demo/ui/Interactive.tsx": `"use client";\nexport const Interactive = () => <button onClick={() => null}>go</button>;\n`,
+      "apps/demo/ui/Hooked.tsx": `"use client";\nimport { useState } from "react";\nexport const Hooked = () => {\n  const [open] = useState(false);\n  return <div>{open ? "y" : "n"}</div>;\n};\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.unnecessary-use-client");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("apps/demo/ui/Plain.tsx");
+  });
+
+  test("keeps the directive on a third-party wrapper and on an index_ boundary", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Chart.tsx": `"use client";\nimport { Bar } from "react-chartjs-2";\nexport const Chart = () => <Bar data={{}} />;\n`,
+      "apps/demo/ui/Lazy/index_.tsx": `"use client";\nexport { Inner } from "./Inner";\n`,
+    });
+
+    expect(rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.unnecessary-use-client")).toHaveLength(0);
+  });
+
+  test("flags a static component and a mostly-static component inside a client file", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Panels.tsx": [
+        `"use client";`,
+        `import { useState } from "react";`,
+        `export const StaticPanel = () => (`,
+        `  <section>`,
+        staticMarkup(5),
+        `  </section>`,
+        `);`,
+        `export const MixedPanel = () => {`,
+        `  const [open, setOpen] = useState(false);`,
+        `  return (`,
+        `    <section>`,
+        staticMarkup(12),
+        `      <span>{open ? "open" : "shut"}</span>`,
+        `    </section>`,
+        `  );`,
+        `};`,
+        "",
+      ].join("\n"),
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+    const staticWarnings = rulesOf(result, "akan.ssr.client-static-component");
+    const mixedWarnings = rulesOf(result, "akan.ssr.client-static-markup");
+
+    expect(staticWarnings).toHaveLength(1);
+    expect(staticWarnings[0]?.message).toContain("StaticPanel");
+    expect(staticWarnings[0]?.fix).toContain("server file");
+    expect(mixedWarnings).toHaveLength(1);
+    expect(mixedWarnings[0]?.message).toContain("MixedPanel");
+  });
+
+  test("flags a mount-only load but not a reactive one", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Zone.tsx": [
+        `"use client";`,
+        `import { useEffect } from "react";`,
+        `export const List = ({ tag }: { tag: string }) => {`,
+        `  useEffect(() => {`,
+        `    void st.do.initPostInPublic();`,
+        `  }, []);`,
+        `  useEffect(() => {`,
+        `    void st.do.getPostListInTag(tag);`,
+        `  }, [tag]);`,
+        `  return <div>{tag}</div>;`,
+        `};`,
+        "",
+      ].join("\n"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.client-mount-load");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("st.do.initPostInPublic");
+    expect(warnings[0]?.fix).toContain("init/view");
+  });
+
+  test("flags useState in a Template", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Template.tsx": `"use client";\nimport { useState } from "react";\nexport const General = () => {\n  const [draft, setDraft] = useState("");\n  return <input value={draft} onChange={(e) => setDraft(e.target.value)} />;\n};\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.template-client-state");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.fix).toContain("st.do.setFieldOnX");
+  });
+
+  test("flags a module that renders only from client files", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Zone.tsx": [
+        `"use client";`,
+        `import { useState } from "react";`,
+        `export const Card = () => {`,
+        `  const [open] = useState(false);`,
+        `  return (`,
+        `    <section>`,
+        staticMarkup(14),
+        `      <span>{open ? "open" : "shut"}</span>`,
+        `    </section>`,
+        `  );`,
+        `};`,
+        "",
+      ].join("\n"),
+      "libs/shared/lib/user/User.Zone.tsx": `"use client";\nimport { st } from "@libs/shared/client";\nexport const Self = () => <User.View.General user={st.use.self()} />;\n`,
+      "libs/shared/lib/user/User.View.tsx": `export const General = ({ name }: { name: string }) => <div>{name}</div>;\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.module-missing-server-view");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("apps/demo/lib/post");
+  });
+
+  test("measures the server render share per scope and for the workspace", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Server.tsx": `export const Server = () => (\n  <section>\n    <p>a</p>\n    <p>b</p>\n  </section>\n);\n`,
+      "libs/shared/ui/Client.tsx": `"use client";\nexport const Client = () => <button onClick={() => null}>go</button>;\n`,
+    });
+
+    const { ssrBalance } = await new AkanQualityScanner().scan(root);
+
+    expect(ssrBalance.map((entry) => entry.scope)).toEqual(["apps/demo", "libs/shared", "workspace"]);
+    expect(ssrBalance[0]).toMatchObject({ serverMass: 3, clientMass: 0, serverShare: 1 });
+    expect(ssrBalance[1]).toMatchObject({ serverMass: 0, clientMass: 1 });
+    expect(ssrBalance[2]).toMatchObject({ scope: "workspace", serverMass: 3, clientMass: 1 });
+  });
+});
+
+describe("AkanQualityScanner layout rules", () => {
+  test("flags an unknown app root file but not a facet entrypoint", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/client.ts": "export const client = 1;\n",
+      "apps/demo/helper.ts": "export const helper = 1;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.app-root-file");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("apps/demo/helper.ts");
+  });
+});

package/qualityScanner.ts

@@ -1,12 +1,15 @@
 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 { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
+import { appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
-type QualityScope = "global" | "file" | "convention" | "layout";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
 
 export interface QualityWarning {
   rule: string;
@@ -23,10 +26,11 @@ export interface QualityScanResult {
   workspaceRoot: string;
   scannedFiles: number;
   warnings: QualityWarning[];
+  ssrBalance: SsrBalanceEntry[];
   suggestedRules: string[];
 }
 
-interface SourceFileInfo {
+export interface SourceFileInfo {
   file: string;
   absolutePath: string;
   content: string;
@@ -88,29 +92,6 @@ const SUGGESTED_RULES = [
   "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline.",
 ];
 
-const APP_ROOT_FILES = new Set([
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json",
-]);
-
-const LIB_ROOT_FILES = new Set([
-  "cnst.ts",
-  "db.ts",
-  "dict.ts",
-  "option.ts",
-  "sig.ts",
-  "srv.ts",
-  "st.ts",
-  "useClient.ts",
-  "useServer.ts",
-]);
-
 const CONVENTION_SUFFIXES = [
   ".constant.ts",
   ".dictionary.ts",
@@ -120,24 +101,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> = {
@@ -169,6 +132,18 @@ const RULE_FIXES: Record<string, string> = {
     "Move the file into a domain module folder under lib/; keep lib 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":
+    'Delete the "use client" directive so the file renders on the server. If it exists only to wrap one client child, drop the wrapper and use the child directly.',
+  "akan.ssr.client-static-component":
+    "Move the component to a server file — a <Model>.Unit.tsx / <Model>.View.tsx for a module, or a ui/ file with no directive — and reference it from the client file.",
+  "akan.ssr.client-static-markup":
+    "Keep the interactive element in the client component and hoist the static subtree into a server component, then accept it as `children` or render it through a Unit/View reference.",
+  "akan.ssr.client-mount-load":
+    "Load the data in the route with `fetch.initX(...)` / `fetch.viewX(...)` and pass the init/view object down as a prop; the client store hydrates from it and the effect goes away.",
+  "akan.ssr.module-missing-server-view":
+    "Add a <Model>.Unit.tsx for list/card rendering and a <Model>.View.tsx for the detail surface, then have the Zone delegate to them.",
+  "akan.ssr.template-client-state":
+    "Bind the field to the store instead: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`.",
 };
 
 function getRuleFix(rule: string): string | undefined {
@@ -190,6 +165,7 @@ export class AkanQualityScanner {
         .filter((file) => AbstractDoc.isAbstractPath(file))
         .map((file) => this.#readTextFile(workspaceRoot, file)),
     );
+    const ssr = new SsrScanner().scan(sourceFiles);
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile) => this.#scanSingleFileQuality(sourceFile)),
@@ -197,6 +173,7 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
+      ...ssr.warnings,
     ];
 
     return {
@@ -205,6 +182,7 @@ export class AkanQualityScanner {
       warnings: warnings
         .map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) }))
         .sort(compareWarnings),
+      ssrBalance: ssr.balance,
       suggestedRules: SUGGESTED_RULES,
     };
   }
@@ -432,7 +410,7 @@ export class AkanQualityScanner {
   #scanLayoutQuality(sourceFile: SourceFileInfo): QualityWarning[] {
     const segments = sourceFile.file.split("/");
     const warnings: QualityWarning[] = [];
-    if (segments[0] === "apps" && segments.length === 3 && !APP_ROOT_FILES.has(segments[2])) {
+    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.has(segments[2])) {
       warnings.push({
         rule: "akan.layout.app-root-file",
         scope: "layout",
@@ -443,7 +421,7 @@ export class AkanQualityScanner {
     }
 
     const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !LIB_ROOT_FILES.has(libRootFile)) {
+    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
       warnings.push({
         rule: "akan.layout.lib-root-file",
         scope: "layout",
@@ -470,6 +448,10 @@ export function formatQualityScanResult(result: QualityScanResult) {
     "",
     ...formatQualityWarnings(result.warnings),
     "",
+    "SSR balance (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
     "Suggested quality rules:",
     "",
     ...result.suggestedRules.map((rule) => `  - ${rule}`),
@@ -477,6 +459,24 @@ export function formatQualityScanResult(result: QualityScanResult) {
   return sections.join("\n");
 }
 
+export function formatSsrScanResult(result: QualityScanResult) {
+  const sections = [
+    "Akan SSR Balance Scan",
+    `workspace: ${result.workspaceRoot}`,
+    `scanned files: ${result.scannedFiles}`,
+    `ssr warnings: ${result.warnings.length}`,
+    "",
+    "Server render share (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
+    "Warnings:",
+    "",
+    ...formatQualityWarnings(result.warnings),
+  ];
+  return sections.join("\n");
+}
+
 export function formatQualityWarnings(warnings: QualityWarning[]) {
   if (warnings.length === 0) return ["No warnings found."];
   return warnings.flatMap((warning) => {
@@ -652,7 +652,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) {

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

@@ -11,6 +11,7 @@ import type {
 } from "./akanConfig";
 
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
+import { appRootAllowedDirs, appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
 
 const scalarFileTypes = ["constant", "dictionary", "document", "template", "unit", "util", "view", "zone"] as const;
 type ScalarFileType = (typeof scalarFileTypes)[number];
@@ -43,49 +44,7 @@ type DatabaseFileType = (typeof databaseFileTypes)[number];
 
 type ModuleKind = "database" | "service" | "scalar";
 
-const appRootAllowedFiles = new Set([
-  // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
-  "AGENTS.md",
-  "CLAUDE.md",
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json",
-  "tsconfig.tsbuildinfo",
-]);
 const generatedRootCapacitorConfigFiles = ["capacitor.config.js", "capacitor.config.json"] as const;
-const appRootAllowedDirs = new Set([
-  ".akan",
-  "android",
-  "env",
-  "ios",
-  "lib",
-  "mobile",
-  "page",
-  "private",
-  "public",
-  "script",
-  "ui",
-  "srvkit",
-  "webkit",
-  "common",
-  "secrets",
-]);
-const libRootAllowedFiles = new Set([
-  "cnst.ts",
-  "db.ts",
-  "dict.ts",
-  "option.ts",
-  "sig.ts",
-  "srv.ts",
-  "st.ts",
-  "useClient.ts",
-  "useServer.ts",
-]);
 const internalLibDirs = new Set(["__lib", "__scalar"]);
 const moduleNonUiFileTypes = {
   database: new Set(["constant", "dictionary", "document", "service", "signal", "store"]),
@@ -107,7 +66,7 @@ const createDependencyScanner = async (exec: AppExecutor | LibExecutor | PkgExec
 
 const isAllowedTestFile = (filename: string) => testFilePattern.test(filename);
 const isAllowedLibRootFile = (filename: string) =>
-  libRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
+  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) {