@akanjs/devkit 3.0.0-alpha.8 → 3.0.0-alpha.81

package/linter.ts

@@ -3,14 +3,14 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import chalk from "chalk";
 
-type BiomeSeverity = "error" | "warning" | "information" | "hint";
+export type BiomeSeverity = "error" | "warning" | "information" | "hint";
 
-interface BiomePosition {
+export interface BiomePosition {
   line: number;
   column: number;
 }
 
-interface BiomeDiagnostic {
+export interface BiomeDiagnostic {
   severity: BiomeSeverity;
   message: string;
   category?: string;
@@ -21,7 +21,7 @@ interface BiomeDiagnostic {
   };
 }
 
-interface BiomeReport {
+export interface BiomeReport {
   summary?: {
     changed?: number;
     errors?: number;
@@ -58,19 +58,81 @@ interface LintResponse {
   warnings: LintMessage[];
 }
 
+/**
+ * Extracts the `--reporter=json` report from Biome's output.
+ *
+ * Biome mixes configuration and IO diagnostics into the same stream as the report, so the output is not
+ * always JSON alone. Slicing from the first `{` to the last `}` mis-parses as soon as that leading text
+ * carries a brace of its own, which is not hypothetical: a config error printed ahead of the report made
+ * one unchanged command alternate between 2 and 10 diagnostics. So every `{` is tried as a start, its
+ * match is found by depth while string literals are skipped, and the first candidate that both parses and
+ * carries a report field wins — a brace in prose parses as nothing, and `{"a":1}` in prose is not a report.
+ */
+export const parseBiomeReport = (output: string): BiomeReport => {
+  for (let start = output.indexOf("{"); start !== -1; start = output.indexOf("{", start + 1)) {
+    const end = objectEndAt(output, start);
+    if (end === -1) break;
+    const report = asBiomeReport(output.slice(start, end + 1));
+    if (report) return report;
+  }
+  throw new Error(output.trim() || "No Biome JSON output");
+};
+
+const objectEndAt = (output: string, start: number): number => {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let idx = start; idx < output.length; idx += 1) {
+    const char = output[idx];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+      continue;
+    }
+    if (char === '"') inString = true;
+    else if (char === "{") depth += 1;
+    else if (char === "}" && --depth === 0) return idx;
+  }
+  return -1;
+};
+
+const asBiomeReport = (candidate: string): BiomeReport | null => {
+  try {
+    const parsed = JSON.parse(candidate) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    if (!("diagnostics" in parsed) && !("summary" in parsed)) return null;
+    return parsed as BiomeReport;
+  } catch {
+    return null;
+  }
+};
+
+/** 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);
@@ -111,14 +173,6 @@ export class Linter {
     });
   }
 
-  #parseBiomeReport(output: string): BiomeReport {
-    const jsonStart = output.indexOf("{");
-    const jsonEnd = output.lastIndexOf("}");
-    if (jsonStart === -1 || jsonEnd === -1 || jsonEnd < jsonStart)
-      throw new Error(output.trim() || "No Biome JSON output");
-    return JSON.parse(output.slice(jsonStart, jsonEnd + 1)) as BiomeReport;
-  }
-
   #diagnosticFilePath(diagnostic: BiomeDiagnostic, fallbackFilePath: string) {
     const diagnosticPath = diagnostic.location?.path;
     if (!diagnosticPath) return fallbackFilePath;
@@ -193,10 +247,10 @@ 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);
+    const report = parseBiomeReport(stdout || stderr);
     const results = this.#toLintResults(report, filePath);
     const { errors, warnings } = this.#splitMessages(results);
     const output = write && existsSync(filePath) ? readFileSync(filePath, "utf8") : undefined;
@@ -390,14 +444,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);
@@ -409,10 +456,37 @@ export class Linter {
    * @param filePath - Path to the file
    * @returns Biome configuration object
    */
+  /**
+   * Applies Biome's safe fixes to many files in one process.
+   *
+   * One spawn, not one per file: Biome's startup dominates a small file, so the per-file path turns a
+   * fifteen-file scaffold into three seconds of process launches. Paths that do not exist are dropped
+   * rather than thrown on, because the caller is usually reporting what a template just wrote and a
+   * template is allowed to decline a file.
+   */
+  async fixFiles(filePaths: string[]): Promise<{ fixed: string[] }> {
+    const resolved = filePaths.map((filePath) => this.#resolveFilePath(filePath)).filter(existsSync);
+    if (resolved.length === 0) return { fixed: [] };
+    const before = new Map(resolved.map((filePath) => [filePath, readFileSync(filePath, "utf8")]));
+    await this.#runBiome([
+      "check",
+      "--write",
+      "--reporter=json",
+      "--max-diagnostics=none",
+      "--no-errors-on-unmatched",
+      "--config-path",
+      this.configPath,
+      ...resolved.map((filePath) => this.#toBiomePath(filePath)),
+    ]);
+    return {
+      fixed: resolved.filter((filePath) => readFileSync(filePath, "utf8") !== before.get(filePath)),
+    };
+  }
+
   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.8",
+  "version": "3.0.0-alpha.81",
   "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.8",
+    "akanjs": "3.0.0-alpha.81",
     "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",
@@ -62,7 +62,7 @@
   },
   "peerDependencies": {
     "@capacitor/cli": "^8.3.4",
-    "react": "19.2.6"
+    "react": "19.2.7"
   },
   "peerDependenciesMeta": {
     "@capacitor/cli": {
@@ -76,4 +76,4 @@
   "bun": {
     "platform": "bun"
   }
-}
+}

package/prompter.ts

@@ -24,7 +24,6 @@ export class Prompter {
   }
 
   static async selectGuideline() {
-    const guidelineRoot = await Prompter.#getGuidelineRoot();
     const guideNames = await Prompter.listGuidelines();
     return await select({
       message: "Select a guideline",
@@ -41,11 +40,17 @@ export class Prompter {
     const guideJson = await fsPromise.readFile(filePath, "utf-8");
     return JSON.parse(guideJson) as GuideGenerateJson;
   }
+  /**
+   * The name is checked against the directory listing rather than interpolated straight into a path:
+   * it arrives from an MCP tool argument, and an unknown one has to name the valid set instead of
+   * surfacing an ENOENT that carries the host's own paths.
+   */
   static async getInstruction(guideName: string): Promise<string> {
+    const guideNames = await Prompter.listGuidelines();
+    if (!guideNames.includes(guideName))
+      throw new Error(`Unknown guideline "${guideName}". Available: ${guideNames.join(", ")}`);
     const guidelineRoot = await Prompter.#getGuidelineRoot();
-    const filePath = `${guidelineRoot}/${guideName}/${guideName}.instruction.md`;
-    const content = await fsPromise.readFile(filePath, "utf-8");
-    return content;
+    return await fsPromise.readFile(`${guidelineRoot}/${guideName}/${guideName}.instruction.md`, "utf-8");
   }
   static async getUpdateRequest(guideName: string) {
     return await input({

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,111 @@ 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");
+  });
+});
+
+describe("bang comments in browser-reachable files", () => {
+  const bangWarningsIn = async (files: Record<string, string>) => {
+    const result = await new AkanQualityScanner().scan(await makeWorkspace(files));
+    return rulesOf(result, "akan.file.bang-comment-in-client");
+  };
+
+  test("flags the first and last line, which the grit rule cannot reach", async () => {
+    const warnings = await bangWarningsIn({
+      "apps/demo/ui/First.tsx": "//! FIXME: broken\nexport const First = () => null;\n",
+      "apps/demo/ui/Last.tsx": "export const Last = () => null;\n//! left behind\n",
+    });
+
+    expect(warnings.map((warning) => `${warning.file}:${warning.line}`).sort()).toEqual([
+      "apps/demo/ui/First.tsx:1",
+      "apps/demo/ui/Last.tsx:2",
+    ]);
+    expect(warnings[0]?.fix).toContain("// FIXME:");
+  });
+
+  test("flags the block form and a marker trailing code", async () => {
+    const warnings = await bangWarningsIn({
+      "apps/demo/lib/task/Task.Zone.tsx": ["/*! keep me */", "export const Zone = () => null; //! and me", ""].join(
+        "\n",
+      ),
+    });
+
+    expect(warnings.map((warning) => warning.line)).toEqual([1, 2]);
+  });
+
+  test("ignores a double slash inside a string literal", async () => {
+    expect(
+      await bangWarningsIn({ "apps/demo/ui/Url.tsx": 'export const url = "https://host//!path";\n' }),
+    ).toHaveLength(0);
+  });
+
+  test("stays out of server files and tests", async () => {
+    const body = "//! server-only marker\nexport const value = 1;\n";
+    expect(
+      await bangWarningsIn({
+        "apps/demo/srvkit/storage.ts": body,
+        "apps/demo/lib/task/task.service.ts": body,
+        "apps/demo/ui/Card.test.tsx": body,
+        "apps/demo/lib/task/task.signal.spec.ts": body,
+      }),
+    ).toHaveLength(0);
+  });
+
+  test("covers every path role the grit rule is scoped to", async () => {
+    const body = "//! marker\nexport const value = 1;\n";
+    const files = [
+      "apps/demo/ui/Card.tsx",
+      "apps/demo/webkit/useThing.tsx",
+      "apps/demo/common/format.ts",
+      "apps/demo/page/task/_index.tsx",
+      "apps/demo/lib/task/task.constant.ts",
+      "apps/demo/lib/task/task.store.ts",
+      "apps/demo/lib/task/Task.Unit.tsx",
+    ];
+    const warnings = await bangWarningsIn(Object.fromEntries(files.map((file) => [file, body])));
+
+    expect(warnings.map((warning) => warning.file).sort()).toEqual([...files].sort());
+  });
 });

package/qualityScanner.ts

@@ -5,11 +5,12 @@ 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;
@@ -88,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.",
 ];
 
@@ -115,6 +117,8 @@ const RULE_FIXES: Record<string, string> = {
     "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.",
@@ -122,14 +126,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":
@@ -173,6 +185,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,
     ];
 
@@ -303,6 +316,7 @@ export class AkanQualityScanner {
       });
     }
 
+    warnings.push(...getBangCommentWarnings(sourceFile));
     warnings.push(...getPlaceholderExportWarnings(sourceFile));
     warnings.push(...getDictionaryTextWarnings(sourceFile));
     warnings.push(...getGlobalMutationWarnings(sourceFile));
@@ -408,26 +422,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.`,
       });
     }
 
@@ -580,9 +599,10 @@ function isEnumClassStatement(sourceFile: ts.SourceFile, statement: ts.Statement
 
 function getExportedClassNames(sourceFile: ts.SourceFile) {
   return sourceFile.statements
-    .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement) && !!statement.name)
+    .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement))
     .filter((statement) => isExported(statement))
-    .map((statement) => statement.name!.text);
+    .map((statement) => statement.name?.text)
+    .filter((name): name is string => !!name);
 }
 
 function isComponentDeclarationFile(file: string) {
@@ -662,7 +682,43 @@ function isPascalCaseName(name: string) {
 
 function isDefaultExportStatement(statement: ts.Statement) {
   if (ts.isExportAssignment(statement)) return !statement.isExportEquals;
-  return !!(ts.getCombinedModifierFlags(statement as ts.Declaration) & ts.ModifierFlags.Default);
+  if (!ts.canHaveModifiers(statement)) return false;
+  return !!ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+}
+
+/**
+ * Bun's bundler keeps `//!` and `/*!` through minification (it reads them as the `@license` class), so a
+ * bang marker in browser-reachable code ships verbatim to every visitor. `no-bang-comment-in-client.grit`
+ * is the build gate; this exists because that rule cannot see the whole file.
+ *
+ * A comment is trivia, which Biome's GritQL exposes to no node pattern, so the rule matches through
+ * `file($name, $body)` — and `$body` is the module's *token* span. A marker above the first statement or
+ * below the last one sits in leading or trailing trivia and is unreachable from GritQL at all. Reading the
+ * raw text here covers both, and re-reporting the markers grit already catches costs nothing: the two run
+ * from different commands, and a file with one is failing lint either way.
+ */
+function getBangCommentWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
+  if (!isClientReachableFile(sourceFile.file)) return [];
+  // Anchored to line start or to whitespace after code, so a literal like `"https://host//!path"` is not a hit.
+  return findPatternLines(sourceFile.content, /(?:^|[^\s/][ \t]+)\/[*/]!/).map((line) => ({
+    rule: "akan.file.bang-comment-in-client",
+    scope: "file" as const,
+    severity: "warning" as const,
+    file: sourceFile.file,
+    line,
+    message: "A `//!` or `/*!` marker survives minification and ships to the browser.",
+  }));
+}
+
+/** Mirrors the path scope of `no-bang-comment-in-client.grit` in `biome.base.json`. */
+function isClientReachableFile(file: string) {
+  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: SourceFileInfo): QualityWarning[] {
@@ -821,7 +877,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/recipeScanner.ts

@@ -118,7 +118,10 @@ const extractVariants = (config: ts.ObjectLiteralExpression) => {
         if (!ts.isPropertyAssignment(variant) || !isNamed(variant.name)) continue;
         if (!ts.isObjectLiteralExpression(variant.initializer)) continue;
         variants[propName(variant.name)] = variant.initializer.properties
-          .filter((option): option is ts.PropertyAssignment => ts.isPropertyAssignment(option) && isNamed(option.name))
+          .filter(
+            (option): option is ts.PropertyAssignment & { name: ts.Identifier | ts.StringLiteral } =>
+              ts.isPropertyAssignment(option) && isNamed(option.name),
+          )
           .map((option) => propName(option.name));
       }
     } else if (key === "defaultVariants" && ts.isObjectLiteralExpression(property.initializer)) {

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;
+};