@akanjs/cli 3.0.0-alpha.11 → 3.0.0-alpha.110

package/{quality.command-ec8r1dn3.js → quality.command-gmbs7nws.js}

@@ -1,177 +1,95 @@
 // @bun
-import {
-  AbstractDoc
-} from "./index-0wae5ebk.js";
 import {
   Workspace,
-  command,
   runner,
-  script
-} from "./index-etwh7sd3.js";
+  script,
+  command
+} from "./index-mak3cd28.js";
+import"./index-q0y2jq9j.js";
 import {
-  appRootAllowedFiles,
-  libFacetRootAllowedFiles
-} from "./index-yzsxc30b.js";
-import"./index-mxvakhsm.js";
-import"./index-1577bej2.js";
-import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+  rootAllowedFiles,
+  rootAllowedDirs,
+  isAllowedLibFacetRootFile
+} from "./index-2tv3fdx4.js";
+import"./index-6wwzs1bc.js";
+import {
+  AbstractDoc
+} from "./index-meh558jy.js";
 
 // pkgs/@akanjs/devkit/qualityScanner.ts
 import { createHash } from "crypto";
 import { readdir, readFile, stat } from "fs/promises";
-import path3 from "path";
+import path from "path";
 import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
-import ts4 from "typescript";
+import ts3 from "typescript";
 
-// pkgs/@akanjs/devkit/mcpScanner.ts
-import path from "path";
+// pkgs/@akanjs/devkit/formSetterScanner.ts
 import ts from "typescript";
 
-class McpScanner {
+class FormSetterScanner {
+  static #fieldSetter = /^set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*$/;
   scan(sourceFiles) {
-    const dictionaries = new Map(sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".dictionary.ts")).map((sourceFile) => [path.dirname(sourceFile.file), sourceFile]));
-    return sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".signal.ts")).flatMap((sourceFile) => this.#scanSignal(sourceFile, dictionaries.get(path.dirname(sourceFile.file))));
-  }
-  #scanSignal(signal, dictionary) {
-    const exposed = McpScanner.#exposedDeclarations(signal);
-    if (!exposed.length)
-      return [];
-    const refName = path.basename(signal.file, ".signal.ts").replace(/^_+/, "");
-    const described = dictionary ? McpScanner.#describedEntries(dictionary) : new Map;
-    return [
-      ...exposed.filter(({ name, kind }) => !McpScanner.#isDescribed(described, refName, name, kind)).map(({ name, kind, line }) => ({
-        rule: "akan.mcp.missing-description",
-        scope: "mcp",
-        severity: "warning",
-        file: signal.file,
-        line,
-        message: `MCP-exposed ${kind} "${name}" has no dictionary .desc(); an agent sees its name and nothing else.`
-      })),
-      ...exposed.filter(({ guards }) => guards === "missing").map(({ name, kind, line }) => ({
-        rule: "akan.mcp.unguarded-exposure",
-        scope: "mcp",
-        severity: "warning",
-        file: signal.file,
-        line,
-        message: `MCP-exposed ${kind} "${name}" declares no guards; a slice's guards map never reaches a named slice.`
-      }))
-    ];
-  }
-  static #isDescribed(described, refName, name, kind) {
-    if (described.get(kind)?.has(name))
-      return true;
-    return kind === "slice" && !!described.get("endpoint")?.has(`${refName}List${McpScanner.#capitalize(name)}`);
+    return sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".tsx")).flatMap((f) => this.#scanFile(f));
   }
-  static #exposedDeclarations(signal) {
-    const found = [];
+  #scanFile({ file, sourceFile }) {
+    const wrapped = [];
     const visit = (node) => {
-      if (McpScanner.#isExposeOption(node)) {
-        const declaration = McpScanner.#enclosingDeclaration(node, signal.sourceFile);
-        if (declaration)
-          found.push(declaration);
+      if (ts.isJsxAttribute(node)) {
+        const setter = FormSetterScanner.#wrappedSetterOf(node);
+        if (setter)
+          wrapped.push({ setter, line: FormSetterScanner.#lineOf(sourceFile, node) });
       }
       ts.forEachChild(node, visit);
     };
-    visit(signal.sourceFile);
-    return found;
-  }
-  static #isExposeOption(node) {
-    if (!ts.isPropertyAssignment(node) || McpScanner.#propertyName(node) !== "mcp")
-      return false;
-    if (!ts.isObjectLiteralExpression(node.initializer))
-      return false;
-    return node.initializer.properties.some((property) => ts.isPropertyAssignment(property) && McpScanner.#propertyName(property) === "expose" && property.initializer.kind === ts.SyntaxKind.TrueKeyword);
-  }
-  static #enclosingDeclaration(option, sourceFile) {
-    let declaration = null;
-    for (let node = option.parent;node; node = node.parent) {
-      if (!declaration && ts.isPropertyAssignment(node)) {
-        declaration = node;
-        continue;
+    visit(sourceFile);
+    if (!wrapped.length)
+      return [];
+    const setters = [...new Set(wrapped.map((entry) => entry.setter))].sort();
+    return [
+      {
+        rule: "akan.agent.unpublished-form-setter",
+        scope: "agent",
+        severity: "warning",
+        message: setters.length === 1 ? `${setters[0]} is reached through a wrapper, so that field publishes no agent tool and carries no data-akan-action.` : `${setters.length} field setters are reached through a wrapper, so those fields publish no agent tool and carry no data-akan-action: ${setters.join(", ")}.`,
+        file,
+        line: wrapped[0]?.line,
+        locations: wrapped.map(({ line }) => ({ file, line }))
       }
-      const kind = McpScanner.#factoryKind(node);
-      if (!kind || !declaration)
-        continue;
-      const name = McpScanner.#propertyName(declaration);
-      if (!name)
-        return null;
-      const line = sourceFile.getLineAndCharacterOfPosition(declaration.getStart(sourceFile)).line + 1;
-      return { name, kind, line, guards: McpScanner.#guardState(option) };
-    }
-    return null;
-  }
-  static #guardState(option) {
-    const options = option.parent;
-    if (!ts.isObjectLiteralExpression(options))
-      return "unknown";
-    if (options.properties.some((property) => ts.isSpreadAssignment(property)))
-      return "unknown";
-    return options.properties.some((property) => ts.isPropertyAssignment(property) && McpScanner.#propertyName(property) === "guards") ? "declared" : "missing";
+    ];
   }
-  static #factoryKind(node) {
-    if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression))
+  static #wrappedSetterOf(attribute) {
+    if (!ts.isIdentifier(attribute.name) || !/^on[A-Z]/.test(attribute.name.text))
       return null;
-    const factory = node.expression.text;
-    return factory === "slice" || factory === "endpoint" ? factory : null;
-  }
-  static #describedEntries(dictionary) {
-    const described = new Map;
-    const visit = (node) => {
-      const stage = McpScanner.#dictionaryStage(node);
-      if (stage) {
-        for (const [name, chain] of McpScanner.#stageEntries(node)) {
-          if (!chain.has("desc"))
-            continue;
-          const names = described.get(stage) ?? new Set;
-          names.add(name);
-          described.set(stage, names);
+    const initializer = attribute.initializer;
+    if (!initializer || !ts.isJsxExpression(initializer) || !initializer.expression)
+      return null;
+    const handler = initializer.expression;
+    if (!ts.isArrowFunction(handler) && !ts.isFunctionExpression(handler))
+      return null;
+    if (!handler.parameters.length)
+      return null;
+    return FormSetterScanner.#setterCallIn(handler.body);
+  }
+  static #setterCallIn(node) {
+    let found = null;
+    const visit = (current) => {
+      if (found)
+        return;
+      if (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+        const { expression, name } = current.expression;
+        if (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression) && expression.expression.text === "st" && expression.name.text === "do" && FormSetterScanner.#fieldSetter.test(name.text)) {
+          found = name.text;
+          return;
         }
       }
-      ts.forEachChild(node, visit);
+      ts.forEachChild(current, visit);
     };
-    visit(dictionary.sourceFile);
-    return described;
-  }
-  static #dictionaryStage(node) {
-    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression))
-      return null;
-    const stage = node.expression.name.text;
-    return stage === "endpoint" || stage === "slice" ? stage : null;
-  }
-  static #stageEntries(stage) {
-    const callback = stage.arguments[0];
-    if (!callback || !ts.isArrowFunction(callback))
-      return [];
-    const body = ts.isParenthesizedExpression(callback.body) ? callback.body.expression : callback.body;
-    if (!ts.isObjectLiteralExpression(body))
-      return [];
-    return body.properties.flatMap((property) => {
-      if (!ts.isPropertyAssignment(property))
-        return [];
-      const name = McpScanner.#propertyName(property);
-      return name ? [[name, McpScanner.#chainCalls(property.initializer)]] : [];
-    });
-  }
-  static #chainCalls(expression) {
-    const calls = new Set;
-    let current = expression;
-    while (ts.isCallExpression(current) || ts.isPropertyAccessExpression(current)) {
-      if (ts.isPropertyAccessExpression(current))
-        calls.add(current.name.text);
-      current = current.expression;
-    }
-    return calls;
-  }
-  static #propertyName(property) {
-    const { name } = property;
-    if (ts.isIdentifier(name) || ts.isStringLiteral(name))
-      return name.text;
-    return null;
+    visit(node);
+    return found;
   }
-  static #capitalize(value) {
-    return value.charAt(0).toUpperCase() + value.slice(1);
+  static #lineOf(sourceFile, node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
   }
 }
 
@@ -535,122 +453,6 @@ function getAccessRoot(node) {
   return ts2.isIdentifier(current) ? current.text : "";
 }
 
-// pkgs/@akanjs/devkit/storeScanner.ts
-import path2 from "path";
-import ts3 from "typescript";
-
-class StoreScanner {
-  scan(sourceFiles) {
-    const dictionaries = new Map(sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".dictionary.ts")).map((sourceFile) => [path2.dirname(sourceFile.file), sourceFile]));
-    return sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".store.ts")).flatMap((sourceFile) => this.#scanStore(sourceFile, dictionaries.get(path2.dirname(sourceFile.file))));
-  }
-  #scanStore(store, dictionary) {
-    const actions = StoreScanner.#customActions(store);
-    if (!actions.length)
-      return [];
-    const described = dictionary ? StoreScanner.#describedEntries(dictionary) : new Map;
-    return actions.filter(({ name, fetched }) => fetched.length && !fetched.includes(name)).filter(({ name }) => !described.get("store")?.has(name) && !described.get("endpoint")?.has(name)).map(({ name, line, fetched }) => ({
-      rule: "akan.agent.missing-store-description",
-      scope: "agent",
-      severity: "warning",
-      file: store.file,
-      line,
-      message: `Store action "${name}" calls ${fetched.map((key) => `${key}()`).join(", ")} under a different name and has no dictionary .store() entry, so an agent reading it has the name and nothing else.`
-    }));
-  }
-  static #customActions(store) {
-    const actions = [];
-    const visit = (node) => {
-      if (ts3.isClassDeclaration(node) && StoreScanner.#extendsStore(node)) {
-        for (const member of node.members) {
-          if (!ts3.isMethodDeclaration(member))
-            continue;
-          if (member.modifiers?.some((modifier) => modifier.kind === ts3.SyntaxKind.StaticKeyword))
-            continue;
-          const name = StoreScanner.#memberName(member);
-          if (!name)
-            continue;
-          const line = store.sourceFile.getLineAndCharacterOfPosition(member.getStart(store.sourceFile)).line + 1;
-          actions.push({ name, line, fetched: StoreScanner.#fetchedEndpoints(member) });
-        }
-      }
-      ts3.forEachChild(node, visit);
-    };
-    visit(store.sourceFile);
-    return actions;
-  }
-  static #extendsStore(node) {
-    return !!node.heritageClauses?.some((clause) => clause.types.some((type) => ts3.isCallExpression(type.expression) && StoreScanner.#isStoreCall(type.expression)));
-  }
-  static #isStoreCall(expression) {
-    return ts3.isIdentifier(expression.expression) && expression.expression.text === "store";
-  }
-  static #fetchedEndpoints(member) {
-    const fetched = new Set;
-    const visit = (node) => {
-      if (ts3.isCallExpression(node) && ts3.isPropertyAccessExpression(node.expression) && ts3.isIdentifier(node.expression.expression) && node.expression.expression.text === "fetch")
-        fetched.add(node.expression.name.text);
-      ts3.forEachChild(node, visit);
-    };
-    visit(member);
-    return [...fetched];
-  }
-  static #describedEntries(dictionary) {
-    const described = new Map;
-    const visit = (node) => {
-      const stage = StoreScanner.#dictionaryStage(node);
-      if (stage) {
-        for (const [name, chain] of StoreScanner.#stageEntries(node)) {
-          if (!chain.has("desc"))
-            continue;
-          const names = described.get(stage) ?? new Set;
-          names.add(name);
-          described.set(stage, names);
-        }
-      }
-      ts3.forEachChild(node, visit);
-    };
-    visit(dictionary.sourceFile);
-    return described;
-  }
-  static #dictionaryStage(node) {
-    if (!ts3.isCallExpression(node) || !ts3.isPropertyAccessExpression(node.expression))
-      return null;
-    const stage = node.expression.name.text;
-    return stage === "store" || stage === "endpoint" ? stage : null;
-  }
-  static #stageEntries(stage) {
-    const callback = stage.arguments[0];
-    if (!callback || !ts3.isArrowFunction(callback))
-      return [];
-    const body = ts3.isParenthesizedExpression(callback.body) ? callback.body.expression : callback.body;
-    if (!ts3.isObjectLiteralExpression(body))
-      return [];
-    return body.properties.flatMap((property) => {
-      if (!ts3.isPropertyAssignment(property))
-        return [];
-      const name = StoreScanner.#memberName(property);
-      return name ? [[name, StoreScanner.#chainCalls(property.initializer)]] : [];
-    });
-  }
-  static #chainCalls(expression) {
-    const calls = new Set;
-    let current = expression;
-    while (ts3.isCallExpression(current) || ts3.isPropertyAccessExpression(current)) {
-      if (ts3.isPropertyAccessExpression(current))
-        calls.add(current.name.text);
-      current = current.expression;
-    }
-    return calls;
-  }
-  static #memberName(member) {
-    const { name } = member;
-    if (!name || !ts3.isIdentifier(name) && !ts3.isStringLiteral(name))
-      return null;
-    return name.text;
-  }
-}
-
 // pkgs/@akanjs/devkit/qualityScanner.ts
 var MAX_FILE_LINES = 2000;
 var PLACEHOLDER_EXPORT_NAMES = new Set([
@@ -672,7 +474,8 @@ var 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."
 ];
 var CONVENTION_SUFFIXES = [
@@ -690,25 +493,27 @@ var RULE_FIXES = {
   "akan.file.max-lines": "Break the file into smaller focused modules; keep one primary responsibility per file.",
   "akan.file.abstract-max-lines": "Run `akan compact <app-or-lib>` to rewrite the abstract with the AI editor, keeping only the invariants and workflows the source files cannot show.",
   "akan.file.placeholder-export": "Remove the placeholder export; generated indexes should only re-export real modules.",
+  "akan.file.bang-comment-in-client": "Rewrite the marker as `// FIXME:` or `// TODO:`. Keep the bang form for server, srvkit, and CLI files.",
   "akan.file.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
   "akan.file.global-declaration": "Move the global declaration into an approved low-level integration file (e.g. webkit) and keep it isolated.",
   "akan.file.window-augmentation": "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 \u2014 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.lib-root-file": "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
+  "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 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": '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 \u2014 a <Model>.Unit.tsx / <Model>.View.tsx for a module, or a ui/ file with no directive \u2014 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}`.",
-  "akan.mcp.missing-description": "Add `.desc([en, ko])` to this entry in the module's dictionary \u2014 for a slice, either on the slice entry or on the `<model>List<Slice>` endpoint it generates. Describe when to reach for it, not what it is named.",
-  "akan.agent.missing-store-description": "Add the action to the module dictionary's `.store()` stage with a `.desc([en, ko])` saying what it does for the user \u2014 not what the endpoint it calls does. That stage is optional everywhere else: an action named after its endpoint already reads as that endpoint's description.",
-  "akan.mcp.unguarded-exposure": "Name the guards in the same option object as `mcp`: `init({ guards: [SignedIn], mcp: { expose: true } })`. Write `guards: [Public]` if anonymous reads are the intent \u2014 the access is the same, but only one of the two is a decision. The `slice()` call's guards map reaches the root slice and base CRUD, never a named slice."
+  "akan.ssr.template-client-state": "Bind the field to the store instead: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`."
 };
 function getRuleFix(rule) {
   if (rule.startsWith("akan.convention"))
@@ -729,9 +534,8 @@ class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
-      ...ssr.warnings,
-      ...new McpScanner().scan(sourceFiles),
-      ...new StoreScanner().scan(sourceFiles)
+      ...new FormSetterScanner().scan(sourceFiles),
+      ...ssr.warnings
     ];
     return {
       workspaceRoot,
@@ -745,7 +549,7 @@ class AkanQualityScanner {
     const ignoreFilter = ignore().add(await this.#readGitIgnore(workspaceRoot));
     const files = [];
     for (const targetRoot of ["apps", "libs"]) {
-      const absoluteTargetRoot = path3.join(workspaceRoot, targetRoot);
+      const absoluteTargetRoot = path.join(workspaceRoot, targetRoot);
       if (!await isDirectory(absoluteTargetRoot))
         continue;
       await this.#walkTargetFiles(workspaceRoot, absoluteTargetRoot, ignoreFilter, files);
@@ -753,7 +557,7 @@ class AkanQualityScanner {
     return files.sort();
   }
   async#readGitIgnore(workspaceRoot) {
-    const gitIgnorePath = path3.join(workspaceRoot, ".gitignore");
+    const gitIgnorePath = path.join(workspaceRoot, ".gitignore");
     if (!await Bun.file(gitIgnorePath).exists())
       return [];
     return (await readFile(gitIgnorePath, "utf8")).split(/\r?\n/);
@@ -761,8 +565,8 @@ class AkanQualityScanner {
   async#walkTargetFiles(workspaceRoot, currentPath, ignoreFilter, files) {
     const entries = await readdir(currentPath, { withFileTypes: true });
     for (const entry of entries) {
-      const absolutePath = path3.join(currentPath, entry.name);
-      const relativePath = toPosix(path3.relative(workspaceRoot, absolutePath));
+      const absolutePath = path.join(currentPath, entry.name);
+      const relativePath = toPosix(path.relative(workspaceRoot, absolutePath));
       if (shouldSkipPath(relativePath, entry.isDirectory(), ignoreFilter))
         continue;
       if (entry.isDirectory()) {
@@ -777,17 +581,17 @@ class AkanQualityScanner {
     }
   }
   async#readSourceFile(workspaceRoot, file) {
-    const absolutePath = path3.join(workspaceRoot, file);
+    const absolutePath = path.join(workspaceRoot, file);
     const content = await readFile(absolutePath, "utf8");
     return {
       file,
       absolutePath,
       content,
-      sourceFile: ts4.createSourceFile(file, content, ts4.ScriptTarget.Latest, true, getScriptKind(file))
+      sourceFile: ts3.createSourceFile(file, content, ts3.ScriptTarget.Latest, true, getScriptKind(file))
     };
   }
   async#readTextFile(workspaceRoot, file) {
-    return { file, content: await readFile(path3.join(workspaceRoot, file), "utf8") };
+    return { file, content: await readFile(path.join(workspaceRoot, file), "utf8") };
   }
   #scanGlobalQuality(sourceFiles) {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile) => getExportedFunctionLikes(sourceFile));
@@ -841,6 +645,7 @@ class AkanQualityScanner {
         message: `File has ${lineCount} lines. Keep single files under ${MAX_FILE_LINES} lines.`
       });
     }
+    warnings.push(...getBangCommentWarnings(sourceFile));
     warnings.push(...getPlaceholderExportWarnings(sourceFile));
     warnings.push(...getDictionaryTextWarnings(sourceFile));
     warnings.push(...getGlobalMutationWarnings(sourceFile));
@@ -911,7 +716,7 @@ class AkanQualityScanner {
     const suffix = CONVENTION_SUFFIXES.find((candidate) => sourceFile.file.endsWith(candidate));
     if (!suffix)
       return [];
-    const modelName = toPascalCase(path3.basename(sourceFile.file, suffix));
+    const modelName = toPascalCase(path.basename(sourceFile.file, suffix));
     const warnings = [];
     for (const declaration of getTopLevelDeclarations(sourceFile)) {
       if (isAllowedConventionDeclaration(suffix, modelName, declaration))
@@ -922,7 +727,7 @@ class AkanQualityScanner {
         severity: "warning",
         file: sourceFile.file,
         line: declaration.line,
-        message: `${path3.basename(sourceFile.file)} should not declare top-level ${declaration.kind} "${declaration.name}". Allowed declarations: ${getConventionDescription(suffix, modelName)}.`
+        message: `${path.basename(sourceFile.file)} should not declare top-level ${declaration.kind} "${declaration.name}". Allowed declarations: ${getConventionDescription(suffix, modelName)}.`
       });
     }
     return warnings;
@@ -942,25 +747,30 @@ class AkanQualityScanner {
     ];
   }
   #scanLayoutQuality(sourceFile) {
-    const segments = sourceFile.file.split("/");
     const warnings = [];
-    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.`
       });
     }
     const moduleUiWarning = getModuleUiWarning(sourceFile.file);
@@ -1030,7 +840,7 @@ function getExportedFunctionLikes(sourceFile) {
   const declarations = [];
   const nameExempt = isPageRouteFile(sourceFile.file) || isUiComponentFile(sourceFile.file);
   for (const statement of sourceFile.sourceFile.statements) {
-    if (ts4.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
+    if (ts3.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
         name: statement.name.text,
         kind: "function",
@@ -1040,7 +850,7 @@ function getExportedFunctionLikes(sourceFile) {
         duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, false)
       });
     }
-    if (ts4.isClassDeclaration(statement) && statement.name && isExported(statement)) {
+    if (ts3.isClassDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
         name: statement.name.text,
         kind: "class",
@@ -1050,9 +860,9 @@ function getExportedFunctionLikes(sourceFile) {
         duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, isEnumClassStatement(sourceFile.sourceFile, statement))
       });
     }
-    if (ts4.isVariableStatement(statement) && isExported(statement)) {
+    if (ts3.isVariableStatement(statement) && isExported(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts4.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
+        if (!ts3.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
           continue;
         declarations.push({
           name: declaration.name.text,
@@ -1091,14 +901,14 @@ function isInLibModule(file) {
   return (segments[0] === "apps" || segments[0] === "libs") && segments.includes("lib");
 }
 function isEnumClassStatement(sourceFile, statement) {
-  if (!ts4.isClassDeclaration(statement))
+  if (!ts3.isClassDeclaration(statement))
     return false;
-  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts4.SyntaxKind.ExtendsKeyword);
+  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts3.SyntaxKind.ExtendsKeyword);
   const expression = heritageClause?.types[0]?.expression;
   return !!expression && expression.getText(sourceFile).startsWith("enumOf(");
 }
 function getExportedClassNames(sourceFile) {
-  return sourceFile.statements.filter((statement) => ts4.isClassDeclaration(statement) && !!statement.name).filter((statement) => isExported(statement)).map((statement) => statement.name.text);
+  return sourceFile.statements.filter((statement) => ts3.isClassDeclaration(statement)).filter((statement) => isExported(statement)).map((statement) => statement.name?.text).filter((name) => !!name);
 }
 function isComponentDeclarationFile(file) {
   if (!file.endsWith(".tsx"))
@@ -1114,7 +924,7 @@ function isComponentDeclarationFile(file) {
 function getComponentFileDeclarations(sourceFile) {
   const reExportedNames = new Set;
   for (const statement of sourceFile.statements) {
-    if (ts4.isExportDeclaration(statement) && statement.exportClause && ts4.isNamedExports(statement.exportClause)) {
+    if (ts3.isExportDeclaration(statement) && statement.exportClause && ts3.isNamedExports(statement.exportClause)) {
       for (const element of statement.exportClause.elements)
         reExportedNames.add((element.propertyName ?? element.name).text);
     }
@@ -1124,19 +934,19 @@ function getComponentFileDeclarations(sourceFile) {
     const isDefaultExport = isDefaultExportStatement(statement);
     const inlineExported = isExported(statement);
     const add = (name, kind, line) => declarations.push({ name, kind, line, exported: inlineExported || reExportedNames.has(name), isDefaultExport });
-    if (ts4.isInterfaceDeclaration(statement))
+    if (ts3.isInterfaceDeclaration(statement))
       add(statement.name.text, "interface", getLine(sourceFile, statement));
-    else if (ts4.isTypeAliasDeclaration(statement))
+    else if (ts3.isTypeAliasDeclaration(statement))
       add(statement.name.text, "type", getLine(sourceFile, statement));
-    else if (ts4.isEnumDeclaration(statement))
+    else if (ts3.isEnumDeclaration(statement))
       add(statement.name.text, "enum", getLine(sourceFile, statement));
-    else if (ts4.isFunctionDeclaration(statement) && statement.name)
+    else if (ts3.isFunctionDeclaration(statement) && statement.name)
       add(statement.name.text, "function", getLine(sourceFile, statement));
-    else if (ts4.isClassDeclaration(statement) && statement.name)
+    else if (ts3.isClassDeclaration(statement) && statement.name)
       add(statement.name.text, "class", getLine(sourceFile, statement));
-    else if (ts4.isVariableStatement(statement)) {
+    else if (ts3.isVariableStatement(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts4.isIdentifier(declaration.name))
+        if (!ts3.isIdentifier(declaration.name))
           continue;
         const kind = isFunctionLikeInitializer(declaration.initializer) ? "function" : "variable";
         add(declaration.name.text, kind, getLine(sourceFile, declaration));
@@ -1148,15 +958,15 @@ function getComponentFileDeclarations(sourceFile) {
 function getCompoundComponentNames(sourceFile) {
   const names = new Set;
   for (const statement of sourceFile.statements) {
-    if (!ts4.isExpressionStatement(statement))
+    if (!ts3.isExpressionStatement(statement))
       continue;
     const { expression } = statement;
-    if (!ts4.isBinaryExpression(expression) || expression.operatorToken.kind !== ts4.SyntaxKind.EqualsToken)
+    if (!ts3.isBinaryExpression(expression) || expression.operatorToken.kind !== ts3.SyntaxKind.EqualsToken)
       continue;
-    if (!ts4.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
+    if (!ts3.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
       continue;
     names.add(expression.left.name.text);
-    if (ts4.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
+    if (ts3.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
       names.add(expression.right.text);
   }
   return names;
@@ -1176,9 +986,37 @@ function isPascalCaseName(name) {
   return /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
 }
 function isDefaultExportStatement(statement) {
-  if (ts4.isExportAssignment(statement))
+  if (ts3.isExportAssignment(statement))
     return !statement.isExportEquals;
-  return !!(ts4.getCombinedModifierFlags(statement) & ts4.ModifierFlags.Default);
+  if (!ts3.canHaveModifiers(statement))
+    return false;
+  return !!ts3.getModifiers(statement)?.some((modifier) => modifier.kind === ts3.SyntaxKind.DefaultKeyword);
+}
+function getBangCommentWarnings(sourceFile) {
+  if (!isClientReachableFile(sourceFile.file))
+    return [];
+  return findPatternLines(sourceFile.content, /(?:^|[^\s/][ \t]+)\/[*/]!/).map((line) => ({
+    rule: "akan.file.bang-comment-in-client",
+    scope: "file",
+    severity: "warning",
+    file: sourceFile.file,
+    line,
+    message: "A `//!` or `/*!` marker survives minification and ships to the browser."
+  }));
+}
+function isClientReachableFile(file) {
+  if (/\.(test|spec)\.tsx?$/.test(file))
+    return false;
+  if (/\.(constant|store)\.ts$/.test(file))
+    return true;
+  if (/\.(Template|Unit|Util|View|Zone)\.tsx$/.test(file))
+    return true;
+  const segments = file.split("/");
+  if (segments.includes("ui") || segments.includes("webkit"))
+    return /\.tsx?$/.test(file);
+  if (segments.includes("common"))
+    return file.endsWith(".ts");
+  return segments.includes("page") && file.endsWith(".tsx");
 }
 function getPlaceholderExportWarnings(sourceFile) {
   if (!sourceFile.file.endsWith("/index.ts") && !sourceFile.file.endsWith("/index.tsx"))
@@ -1208,7 +1046,7 @@ function getDictionaryTextWarnings(sourceFile) {
 function getGlobalMutationWarnings(sourceFile) {
   const warnings = [];
   for (const statement of sourceFile.sourceFile.statements) {
-    if (ts4.isModuleDeclaration(statement) && statement.name.getText(sourceFile.sourceFile) === "global") {
+    if (ts3.isModuleDeclaration(statement) && statement.name.getText(sourceFile.sourceFile) === "global") {
       warnings.push({
         rule: "akan.file.global-declaration",
         scope: "file",
@@ -1218,7 +1056,7 @@ function getGlobalMutationWarnings(sourceFile) {
         message: "Global declarations require an explicit low-level integration allowlist."
       });
     }
-    if (ts4.isInterfaceDeclaration(statement) && statement.name.text === "Window") {
+    if (ts3.isInterfaceDeclaration(statement) && statement.name.text === "Window") {
       warnings.push({
         rule: "akan.file.window-augmentation",
         scope: "file",
@@ -1228,7 +1066,7 @@ function getGlobalMutationWarnings(sourceFile) {
         message: "Window augmentation should be isolated to approved browser integration files."
       });
     }
-    if (ts4.isExpressionStatement(statement) && statement.expression.getText(sourceFile.sourceFile).includes(".prototype.")) {
+    if (ts3.isExpressionStatement(statement) && statement.expression.getText(sourceFile.sourceFile).includes(".prototype.")) {
       warnings.push({
         rule: "akan.file.prototype-mutation",
         scope: "file",
@@ -1246,23 +1084,23 @@ function getTopLevelDeclarations(sourceFile) {
 }
 function getTopLevelDeclaration(sourceFile, statement) {
   const line = getLine(sourceFile, statement);
-  if (ts4.isClassDeclaration(statement) && statement.name) {
+  if (ts3.isClassDeclaration(statement) && statement.name) {
     return [{ name: statement.name.text, kind: "class", line, exported: isExported(statement), node: statement }];
   }
-  if (ts4.isFunctionDeclaration(statement) && statement.name) {
+  if (ts3.isFunctionDeclaration(statement) && statement.name) {
     return [{ name: statement.name.text, kind: "function", line, exported: isExported(statement), node: statement }];
   }
-  if (ts4.isInterfaceDeclaration(statement)) {
+  if (ts3.isInterfaceDeclaration(statement)) {
     return [{ name: statement.name.text, kind: "interface", line, exported: isExported(statement), node: statement }];
   }
-  if (ts4.isTypeAliasDeclaration(statement)) {
+  if (ts3.isTypeAliasDeclaration(statement)) {
     return [{ name: statement.name.text, kind: "type", line, exported: isExported(statement), node: statement }];
   }
-  if (ts4.isEnumDeclaration(statement)) {
+  if (ts3.isEnumDeclaration(statement)) {
     return [{ name: statement.name.text, kind: "enum", line, exported: isExported(statement), node: statement }];
   }
-  if (ts4.isVariableStatement(statement)) {
-    return statement.declarationList.declarations.filter((declaration) => ts4.isIdentifier(declaration.name)).map((declaration) => ({
+  if (ts3.isVariableStatement(statement)) {
+    return statement.declarationList.declarations.filter((declaration) => ts3.isIdentifier(declaration.name)).map((declaration) => ({
       name: declaration.name.text,
       kind: "variable",
       line: getLine(sourceFile, declaration),
@@ -1270,7 +1108,7 @@ function getTopLevelDeclaration(sourceFile, statement) {
       node: statement
     }));
   }
-  if (ts4.isExportDeclaration(statement)) {
+  if (ts3.isExportDeclaration(statement)) {
     return [{ name: "export declaration", kind: "export", line, exported: true, node: statement }];
   }
   return [];
@@ -1295,9 +1133,9 @@ function isAllowedConstantDeclaration(modelName, declaration) {
     return false;
   if ([`${modelName}Input`, `${modelName}Object`, modelName, `Light${modelName}`, `${modelName}Insight`].includes(declaration.name))
     return true;
-  if (!ts4.isClassDeclaration(declaration.node))
+  if (!ts3.isClassDeclaration(declaration.node))
     return false;
-  const heritageClause = declaration.node.heritageClauses?.find((clause) => clause.token === ts4.SyntaxKind.ExtendsKeyword);
+  const heritageClause = declaration.node.heritageClauses?.find((clause) => clause.token === ts3.SyntaxKind.ExtendsKeyword);
   const expression = heritageClause?.types[0]?.expression;
   return !!expression && expression.getText().startsWith("enumOf(");
 }
@@ -1314,7 +1152,19 @@ function getConventionDescription(suffix, modelName) {
     return `${modelName}Internal, ${modelName}Slice, or ${modelName}Endpoint`;
   return `${modelName}Store`;
 }
-function getLibRootFile(file) {
+var sysRootTypes = { apps: "app", libs: "lib" };
+function getSysRootEntry(file) {
+  const segments = file.split("/");
+  const root = segments[0];
+  const name = segments[2];
+  if (!root || !name || segments.length < 3)
+    return null;
+  const type = sysRootTypes[root];
+  if (!type)
+    return null;
+  return { type, name, isDir: segments.length > 3 };
+}
+function getLibFacetRootFile(file) {
   const segments = file.split("/");
   if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
     return segments[3];
@@ -1363,13 +1213,13 @@ function getModuleInfo(file) {
   return { moduleName, fileName, kind: "database" };
 }
 function isExportedConst(declaration) {
-  return declaration.exported && ts4.isVariableStatement(declaration.node) && (declaration.node.declarationList.flags & ts4.NodeFlags.Const) !== 0;
+  return declaration.exported && ts3.isVariableStatement(declaration.node) && (declaration.node.declarationList.flags & ts3.NodeFlags.Const) !== 0;
 }
 function isExported(node) {
-  return !!ts4.getCombinedModifierFlags(node) && !!(ts4.getCombinedModifierFlags(node) & ts4.ModifierFlags.Export);
+  return !!ts3.getCombinedModifierFlags(node) && !!(ts3.getCombinedModifierFlags(node) & ts3.ModifierFlags.Export);
 }
 function isFunctionLikeInitializer(node) {
-  return !!node && (ts4.isArrowFunction(node) || ts4.isFunctionExpression(node));
+  return !!node && (ts3.isArrowFunction(node) || ts3.isFunctionExpression(node));
 }
 function getBodyFingerprint(sourceFile, node) {
   if (!node)
@@ -1391,7 +1241,7 @@ async function isDirectory(absolutePath) {
   }
 }
 function getScriptKind(file) {
-  return file.endsWith(".tsx") ? ts4.ScriptKind.TSX : ts4.ScriptKind.TS;
+  return file.endsWith(".tsx") ? ts3.ScriptKind.TSX : ts3.ScriptKind.TS;
 }
 function getLine(sourceFile, node) {
   return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
@@ -1412,7 +1262,7 @@ function toPascalCase(value) {
   return value.replace(/(^|[-_./])([a-zA-Z0-9])/g, (_, __, char) => char.toUpperCase()).replace(/[-_./]/g, "");
 }
 function toPosix(value) {
-  return value.split(path3.sep).join("/");
+  return value.split(path.sep).join("/");
 }
 function groupBy(items, getKey) {
   const grouped = new Map;