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

package/agentsIndex.ts

@@ -19,6 +19,32 @@ const loadRecipeScanner = () => (recipeScannerLoad ??= import("./recipeScanner")
 export const AGENT_BLOCK_START = "<!-- akan:agent:start -->";
 export const AGENT_BLOCK_END = "<!-- akan:agent:end -->";
 
+const AGENT_VERSION_PREFIX = "<!-- akan:agent:version ";
+
+/**
+ * The generating release, stamped into the workspace block. Nothing re-runs `akan agent install` on its own, so
+ * without a stamp a workspace carrying conventions from four releases ago is indistinguishable from a current one —
+ * `akan doctor` compares this against the installed devkit and says so.
+ */
+export const stampBlockVersion = (block: string, version: string): string =>
+  `${AGENT_VERSION_PREFIX}${version} -->\n\n${block}`;
+
+/** The stamped version of a committed AGENTS.md, or null when it predates stamping or carries no block. */
+export const extractBlockVersion = (content: string): string | null =>
+  content.match(/<!-- akan:agent:version ([^\s]+) -->/)?.[1] ?? null;
+
+/** The running `@akanjs/devkit` version; null when its package.json is unreadable, which must not fail a doctor run. */
+export const readDevkitVersion = async (): Promise<string | null> => {
+  const { readFile } = await import("node:fs/promises");
+  const { getDirname } = await import("./getDirname");
+  try {
+    const raw = await readFile(`${getDirname(import.meta.url)}/package.json`, "utf-8");
+    return (JSON.parse(raw) as { version?: string }).version ?? null;
+  } catch {
+    return null;
+  }
+};
+
 export interface AgentsIndexScope {
   type: "app" | "lib";
   name: string;

package/akanContext.ts

@@ -1,6 +1,7 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { capitalize } from "akanjs/common";
+import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
 import { collectRecipeSources, findInlineRecipeDuplicates, scanRecipes } from "./recipeScanner";
@@ -14,6 +15,7 @@ import {
   workflowRunArtifactPath,
   workflowSyncDir,
 } from "./workflow";
+import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
 
 export type AkanContextFormat = "json" | "markdown";
 export type AkanModuleKind = "domain" | "service" | "scalar";
@@ -275,6 +277,8 @@ const validationCommands = [
   "akan test <app-or-lib-or-pkg>",
   "akan build <app-name>",
   "akan doctor --strict --format json",
+  "akan quality scan [--format json]",
+  "akan quality ssr [--format json]",
 ];
 
 const unknownGeneratedFilesFreshness: GeneratedFilesFreshness = {
@@ -313,36 +317,6 @@ const moduleShapeFiles = (module: AkanModuleContext) => {
 const constantFieldNames = (content: string) =>
   [...content.matchAll(/\b([A-Za-z_$][\w$]*)\s*:\s*field\(/g)].map((match) => match[1]).filter(Boolean);
 
-const appRootAllowFiles = new Set([
-  // 스코프 에이전트 가이드 — scan(write) 이 유지 (agentsIndex.ts); scanInfo.ts 의 appRootAllowedFiles 와 동기
-  "AGENTS.md",
-  "CLAUDE.md",
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json",
-]);
-
-const appRootAllowDirs = new Set([
-  ".akan",
-  "android",
-  "common",
-  "env",
-  "ios",
-  "lib",
-  "page",
-  "private",
-  "public",
-  "script",
-  "srvkit",
-  "ui",
-  "webkit",
-]);
-
 const safeReadDir = async (dirPath: string) => {
   try {
     return (await readdir(dirPath, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
@@ -647,6 +621,30 @@ export class AkanContextAnalyzer {
     };
   }
 
+  // The conventions in AGENTS.md ship with the package, but nothing re-renders them on `bun update` — a workspace
+  // keeps whichever release wrote its block until someone re-runs the install. Comparing the stamp against the
+  // running devkit is the only signal that the guide an agent is reading is older than the framework it describes.
+  static async #agentGuideDrift(workspace: WorkspaceExecutor) {
+    const installed = await readDevkitVersion();
+    if (!installed) return null;
+    const content = await safeReadText(path.join(workspace.workspaceRoot, "AGENTS.md"));
+    if (content === null) return null;
+    const stamped = extractBlockVersion(content);
+    if (stamped === installed) return null;
+    const hint = "Re-render the AGENTS.md managed block from the installed framework release.";
+    if (!stamped)
+      return {
+        code: "agent-guide-unstamped",
+        message: `AGENTS.md carries no generated-version stamp, so its conventions may predate @akanjs/devkit ${installed}`,
+        hint,
+      };
+    return {
+      code: "agent-guide-stale",
+      message: `AGENTS.md was generated by @akanjs/devkit ${stamped}, but ${installed} is installed`,
+      hint,
+    };
+  }
+
   static async doctor(
     workspace: WorkspaceExecutor,
     {
@@ -671,7 +669,8 @@ export class AkanContextAnalyzer {
     for (const app of context.apps) {
       const appPath = path.join(workspace.workspaceRoot, app.path);
       for (const entry of await safeReadDir(appPath)) {
-        const allowed = entry.isDirectory() ? appRootAllowDirs.has(entry.name) : appRootAllowFiles.has(entry.name);
+        if (!isScannedAppRootEntry(entry.name)) continue;
+        const allowed = entry.isDirectory() ? appRootAllowedDirs.has(entry.name) : appRootAllowedFiles.has(entry.name);
         if (!allowed) {
           const action = repairAction(
             "module-shape",
@@ -691,6 +690,19 @@ export class AkanContextAnalyzer {
       }
     }
 
+    const agentDrift = await AkanContextAnalyzer.#agentGuideDrift(workspace);
+    if (agentDrift) {
+      const action = repairAction("generated", "akan agent install agents-md", agentDrift.hint, true);
+      diagnostics.push({
+        severity: "warning",
+        code: agentDrift.code,
+        path: "AGENTS.md",
+        message: agentDrift.message,
+        repairActions: [action],
+      });
+      repairActions.push(action);
+    }
+
     for (const sys of [...context.apps, ...context.libs]) {
       for (const module of sys.modules) {
         if (!module.abstract.exists) {

package/applicationBuildRunner.ts

@@ -112,7 +112,7 @@ export class ApplicationBuildRunner {
       () => precompressArtifacts(this.#app),
       (result) =>
         result.files > 0
-          ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> ${ApplicationBuildRunner.formatBytes(result.outputBytes)}`
+          ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> gzip ${ApplicationBuildRunner.formatBytes(result.outputBytes)} / br ${ApplicationBuildRunner.formatBytes(result.brotliBytes)}`
           : "no files",
       phaseOptions,
     );

package/biome.base.json

@@ -0,0 +1,301 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.8/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": false
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "suspicious": {
+        "noConsole": {
+          "level": "error",
+          "options": {
+            "allow": ["assert", "error", "info", "warn"]
+          }
+        },
+        "noArrayIndexKey": "off",
+        "noShadowRestrictedNames": "off",
+        "noUnnecessaryConditions": {
+          "level": "error"
+        }
+      },
+      "correctness": {
+        "noUnusedFunctionParameters": "off",
+        "noUnusedImports": {
+          "level": "error",
+          "fix": "safe"
+        },
+        "useParseIntRadix": "off",
+        "useExhaustiveDependencies": "off",
+        "useHookAtTopLevel": "off"
+      },
+      "nursery": {
+        "useSortedClasses": {
+          "level": "error",
+          "fix": "safe",
+          "options": {
+            "attributes": ["classList"],
+            "functions": ["cn"]
+          }
+        }
+      },
+      "a11y": "off",
+      "complexity": {
+        "noStaticOnlyClass": "off"
+      },
+      "style": {
+        "useTemplate": {
+          "level": "warn",
+          "fix": "safe"
+        }
+      }
+    },
+    "domains": {
+      "project": "recommended",
+      "react": "recommended",
+      "test": "recommended",
+      "types": "all"
+    }
+  },
+  "javascript": {
+    "parser": {
+      "unsafeParameterDecoratorsEnabled": true
+    },
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "overrides": [
+    {
+      "includes": [
+        "**/env.client.local.ts",
+        "**/env.client.debug.ts",
+        "**/env.client.develop.ts",
+        "**/env.client.main.ts",
+        "**/env.client.testing.ts",
+        "**/env.server.local.ts",
+        "**/env.server.develop.ts",
+        "**/env.server.main.ts",
+        "**/env.server.testing.ts",
+        "**/env.server.type.ts",
+        "apps/*/lib/cnst.ts",
+        "apps/*/lib/dict.ts",
+        "apps/*/lib/db.ts",
+        "apps/*/lib/srv.ts",
+        "apps/*/lib/st.ts",
+        "apps/*/lib/sig.ts",
+        "apps/*/lib/useClient.ts",
+        "apps/*/lib/useServer.ts",
+        "apps/*/client.ts",
+        "apps/*/server.ts",
+        "apps/*/lib/*/index.tsx",
+        "libs/*/lib/cnst.ts",
+        "libs/*/lib/dict.ts",
+        "libs/*/lib/db.ts",
+        "libs/*/lib/srv.ts",
+        "libs/*/lib/st.ts",
+        "libs/*/lib/sig.ts",
+        "libs/*/lib/useClient.ts",
+        "libs/*/lib/useServer.ts",
+        "libs/*/client.ts",
+        "libs/*/server.ts",
+        "libs/*/index.ts",
+        "libs/*/lib/*/index.tsx"
+      ],
+      "linter": { "enabled": false },
+      "formatter": { "enabled": false },
+      "assist": { "enabled": false }
+    },
+    {
+      "includes": [
+        "apps/**/*.ts",
+        "apps/**/*.tsx",
+        "libs/**/*.ts",
+        "libs/**/*.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx",
+        "!**/*.constant.ts",
+        "!**/common/**",
+        "!**/env/**"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-throw-raw-error.grit"]
+    },
+    {
+      "includes": ["**/page/**/*.ts", "**/page/**/*.tsx", "**/*.Unit.tsx", "**/*.View.tsx"],
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-import-client-functions.grit",
+        "./node_modules/@akanjs/devkit/lint/no-use-client-in-server.grit"
+      ]
+    },
+    {
+      "includes": ["**/page/**/*.ts", "**/page/**/*.tsx"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/non-scalar-props-restricted.grit"]
+    },
+    {
+      "includes": ["**/*.constant.ts", "**/*.document.ts", "**/*.service.ts", "**/*.store.ts"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-js-private-class-method.grit"]
+    },
+    {
+      "includes": ["**/*.store.ts"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-return-in-store-action.grit"]
+    },
+    {
+      "includes": ["**/*.signal.ts"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
+    },
+    {
+      "includes": [
+        "**/ui/**/*.ts",
+        "**/ui/**/*.tsx",
+        "**/webkit/**/*.ts",
+        "**/webkit/**/*.tsx",
+        "**/common/**/*.ts",
+        "**/page/**/*.tsx",
+        "**/*.constant.ts",
+        "**/*.store.ts",
+        "**/*.Template.tsx",
+        "**/*.Unit.tsx",
+        "**/*.Util.tsx",
+        "**/*.View.tsx",
+        "**/*.Zone.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-bang-comment-in-client.grit"]
+    },
+    {
+      "includes": [
+        "**/*.constant.ts",
+        "**/*.dictionary.ts",
+        "**/*.document.ts",
+        "**/*.service.ts",
+        "**/*.signal.ts",
+        "**/*.store.ts",
+        "**/*.Template.tsx",
+        "**/*.Unit.tsx",
+        "**/*.Util.tsx",
+        "**/*.View.tsx",
+        "**/*.Zone.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-deep-internal-import.grit"]
+    },
+    {
+      "includes": [
+        "**/page/**/*.ts",
+        "**/page/**/*.tsx",
+        "**/index.ts",
+        "**/index.tsx",
+        "**/cnst.ts",
+        "**/db.ts",
+        "**/dict.ts",
+        "**/option.ts",
+        "**/sig.ts",
+        "**/srv.ts",
+        "**/st.ts",
+        "**/*.constant.ts",
+        "**/*.dictionary.ts",
+        "**/*.document.ts",
+        "**/*.service.ts",
+        "**/*.signal.ts",
+        "**/*.signal.test.ts",
+        "**/*.service.test.ts",
+        "**/*.store.ts",
+        "**/*.Template.tsx",
+        "**/*.Unit.tsx",
+        "**/*.Util.tsx",
+        "**/*.View.tsx",
+        "**/*.Zone.tsx"
+      ],
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-import-external-library.grit",
+        "./node_modules/@akanjs/devkit/lint/no-deep-internal-import.grit"
+      ]
+    },
+    {
+      "includes": [
+        "apps/**/*.tsx",
+        "libs/**/*.tsx",
+        "apps/**/ui/**/*.ts",
+        "libs/**/ui/**/*.ts",
+        "apps/**/webkit/**/*.ts",
+        "libs/**/webkit/**/*.ts",
+        "apps/**/page/**/*.ts",
+        "libs/**/page/**/*.ts",
+        "apps/**/common/**/*.ts",
+        "libs/**/common/**/*.ts",
+        "apps/**/*.store.ts",
+        "libs/**/*.store.ts",
+        "apps/**/*.constant.ts",
+        "libs/**/*.constant.ts",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-import-server-in-client.grit"]
+    },
+    {
+      "includes": [
+        "apps/**/*.document.ts",
+        "libs/**/*.document.ts",
+        "apps/**/*.dictionary.ts",
+        "libs/**/*.dictionary.ts",
+        "apps/**/*.service.ts",
+        "libs/**/*.service.ts",
+        "apps/**/*.signal.ts",
+        "libs/**/*.signal.ts",
+        "apps/**/srvkit/**/*.ts",
+        "libs/**/srvkit/**/*.ts",
+        "apps/**/common/**/*.ts",
+        "libs/**/common/**/*.ts",
+        "apps/**/*.constant.ts",
+        "libs/**/*.constant.ts",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-import-client-in-server.grit"]
+    },
+    {
+      "includes": [
+        "apps/**/*.ts",
+        "apps/**/*.tsx",
+        "libs/**/*.ts",
+        "libs/**/*.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-raw-palette-class.grit",
+        "./node_modules/@akanjs/devkit/lint/no-arbitrary-color.grit",
+        "./node_modules/@akanjs/devkit/lint/no-daisyui-legacy-class.grit",
+        "./node_modules/@akanjs/devkit/lint/no-inline-color.grit",
+        "./node_modules/@akanjs/devkit/lint/no-interpolated-arbitrary-class.grit"
+      ]
+    }
+  ]
+}

package/biomeBase.ts

@@ -0,0 +1,9 @@
+/** `extends` target for a workspace `biome.json`; Biome resolves it through node_modules. */
+export const biomeBaseConfig = "@akanjs/devkit/biome.base.json";
+
+// Biome moves rules between groups across minors — `noUnnecessaryConditions` sat in `nursery` at 2.4 and moved to
+// `suspicious` at 2.5 — and the stale position is a hard "unknown key" error, not a warning. A workspace whose
+// Biome disagrees with the shipped base config therefore fails to load it at all, which is why the version is
+// pinned here instead of resolved to latest at create time. Bump this and `biome.base.json` in one commit, and run
+// `biome migrate --write` in the workspace root and in `pkgs/@akanjs/devkit` so both configs move together.
+export const biomeVersion = "2.5.8";

package/capacitorApp.test.ts

@@ -11,6 +11,7 @@ import {
   clearRootCapacitorConfigs,
   formatAndroidReleaseSigningError,
   getAdbDeviceStateIssues,
+  getAndroidLocalServerHost,
   getMissingAndroidReleaseSigningKeys,
   isPlaceholderAppId,
   materializeCapacitorConfig,
@@ -339,6 +340,13 @@ describe("Android signing diagnostics", () => {
       "Android device abc123 is unauthorized. Confirm USB debugging authorization on the device.",
       "Android device xyz is offline. Reconnect the device or restart adb.",
     ]);
+    expect(getAndroidLocalServerHost("List of devices attached\nemulator-5554 device\n", "192.168.0.5")).toBe(
+      "10.0.2.2",
+    );
+    expect(getAndroidLocalServerHost("List of devices attached\nabc123 device\n", "192.168.0.5")).toBe("192.168.0.5");
+    expect(
+      getAndroidLocalServerHost("List of devices attached\nemulator-5554 device\nabc123 device\n", "192.168.0.5"),
+    ).toBe("192.168.0.5");
   });
 });