@akanjs/devkit 3.0.0-alpha.1 → 3.0.0-alpha.11

package/qualityScanner.test.ts

@@ -183,3 +183,195 @@ describe("AkanQualityScanner ssr rules", () => {
     expect(ssrBalance[2]).toMatchObject({ scope: "workspace", serverMass: 3, clientMass: 1 });
   });
 });
+
+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 mcp rules", () => {
+  test("flags an exposed endpoint whose dictionary entry carries no desc", async () => {
+    const root = await makeWorkspace({
+      "libs/shared/lib/post/post.signal.ts": [
+        `import { endpoint } from "akanjs/signal";`,
+        `export class PostEndpoint extends endpoint(srv.post, ({ query }) => ({`,
+        `  publishPost: query(Boolean, { guards: [Admin], mcp: { expose: true } }).exec(() => true),`,
+        `  archivePost: query(Boolean, { guards: [Admin], mcp: { expose: true } }).exec(() => true),`,
+        `  quietPost: query(Boolean, { guards: [Admin] }).exec(() => true),`,
+        `})) {}`,
+        "",
+      ].join("\n"),
+      "libs/shared/lib/post/post.dictionary.ts": [
+        `export const dictionary = modelDictionary(["en", "ko"]).endpoint((fn) => ({`,
+        `  publishPost: fn(["Publish", "게시"]).desc(["Publishes a post", "글을 게시합니다"]),`,
+        `  archivePost: fn(["Archive", "보관"]).arg((t) => ({`,
+        `    postId: t(["Post", "글"]).desc(["Post to archive", "보관할 글"]),`,
+        `  })),`,
+        `}));`,
+        "",
+      ].join("\n"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.missing-description");
+
+    // `archivePost` describes only its argument, which says nothing about when to reach for the tool.
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("archivePost");
+    expect(warnings[0]?.line).toBe(4);
+    expect(warnings[0]?.fix).toContain(".desc(");
+  });
+
+  test("accepts a slice described on its own entry or on the endpoint it generates", async () => {
+    const root = await makeWorkspace({
+      "libs/shared/lib/post/post.signal.ts": signalOf(
+        [
+          `  inPublic: init({ mcp: { expose: true } }).exec(function () { return this.postService.queryInPublic(); }),`,
+          `  inTag: init({ mcp: { expose: true } }).exec(function () { return this.postService.queryInTag(); }),`,
+          `  inDraft: init({ mcp: { expose: true } }).exec(function () { return this.postService.queryInDraft(); }),`,
+        ].join("\n"),
+      ),
+      "libs/shared/lib/post/post.dictionary.ts": [
+        `export const dictionary = modelDictionary(["en", "ko"])`,
+        `  .slice((fn) => ({`,
+        `    inPublic: fn(["In Public", "공개"]).desc(["Public posts", "공개된 글"]),`,
+        `    inTag: fn(["In Tag", "태그"]),`,
+        `    inDraft: fn(["In Draft", "초안"]),`,
+        `  }))`,
+        `  .endpoint((fn) => ({`,
+        `    postListInTag: fn(["Post List In Tag", "태그별 글"]).desc(["Posts under a tag", "태그에 속한 글"]),`,
+        `  }));`,
+        "",
+      ].join("\n"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.missing-description");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("inDraft");
+  });
+
+  test("flags an exposure that declares no guards, whatever the slice call declared", async () => {
+    const root = await makeWorkspace({
+      "libs/shared/lib/post/post.signal.ts": signalOf(
+        [
+          `  inPublic: init({ guards: [Public], mcp: { expose: true } }).exec(function () { return this.postService.queryInPublic(); }),`,
+          `  inTag: init({ mcp: { expose: true } }).exec(function () { return this.postService.queryInTag(); }),`,
+          `  inDraft: init({ ...sharedOption, mcp: { expose: true } }).exec(function () { return this.postService.queryInDraft(); }),`,
+        ].join("\n"),
+      ),
+      "libs/shared/lib/post/post.dictionary.ts": `export const dictionary = modelDictionary(["en", "ko"]);\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.unguarded-exposure");
+
+    // `inPublic` decided; `inDraft` may have inherited a `guards` from the spread, so it is unreadable, not missing.
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("inTag");
+    expect(warnings[0]?.fix).toContain("guards: [Public]");
+  });
+
+  test("stays silent on a module that exposes nothing to MCP", async () => {
+    const root = await makeWorkspace({
+      "libs/shared/lib/post/post.signal.ts": signalOf(
+        `  inPublic: init().exec(function () { return this.postService.queryInPublic(); }),`,
+      ),
+      "libs/shared/lib/post/post.dictionary.ts": `export const dictionary = modelDictionary(["en", "ko"]);\n`,
+    });
+
+    expect(rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.missing-description")).toHaveLength(0);
+  });
+});
+
+describe("AkanQualityScanner agent rules", () => {
+  const storeOf = (body: string) =>
+    [
+      `import { store } from "akanjs/store";`,
+      `export class PostStore extends store(sig.post, () => ({})) {`,
+      body,
+      `}`,
+      "",
+    ].join("\n");
+
+  test("flags only the actions whose endpoint description would be the wrong one", async () => {
+    const root = await makeWorkspace({
+      "libs/shared/lib/post/post.store.ts": storeOf(
+        [
+          // Named after the endpoint it calls, so it already reads as that endpoint's `.desc()`.
+          `  async publishPost(id: string) { await fetch.publishPost(id); }`,
+          // Renamed: the store name is the verb a user would say, the endpoint name is the verb the API has.
+          `  async archive(id: string) { await fetch.archivePost(id); }`,
+          // Two endpoints behind one action, so neither one's description covers it.
+          `  async publishAndTag(id: string) { await fetch.publishPost(id); await fetch.tagPost(id); }`,
+          // Never leaves the client, so it is not published and its description would be read by nobody.
+          `  toggleDraft() { this.set({ draft: !this.get().draft }); }`,
+        ].join("\n"),
+      ),
+      "libs/shared/lib/post/post.dictionary.ts": `export const dictionary = modelDictionary(["en", "ko"]);\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.agent.missing-store-description");
+
+    expect(warnings.map((warning) => warning.message)).toHaveLength(2);
+    expect(warnings[0]?.message).toContain("archive");
+    expect(warnings[0]?.message).toContain("archivePost()");
+    expect(warnings[1]?.message).toContain("publishAndTag");
+    expect(warnings[0]?.fix).toContain(".store()");
+  });
+
+  test("accepts an action described on its own store entry or on a same-named endpoint", async () => {
+    const root = await makeWorkspace({
+      "libs/shared/lib/post/post.store.ts": storeOf(
+        [
+          `  async archive(id: string) { await fetch.archivePost(id); }`,
+          `  async logout() { await fetch.signoutUser(); }`,
+          `  async retire(id: string) { await fetch.archivePost(id); }`,
+        ].join("\n"),
+      ),
+      "libs/shared/lib/post/post.dictionary.ts": [
+        `export const dictionary = modelDictionary(["en", "ko"])`,
+        `  .endpoint((fn) => ({`,
+        // Not the endpoint it calls — an entry under the action's own name describes the action.
+        `    logout: fn(["Log Out", "로그아웃"]).desc(["Ends the session", "세션을 종료합니다"]),`,
+        `  }))`,
+        `  .store((t) => ({`,
+        `    archive: t(["Archive", "보관"]).desc(["Files the post away", "글을 보관합니다"]),`,
+        `    retire: t(["Retire", "폐기"]),`,
+        `  }));`,
+        "",
+      ].join("\n"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.agent.missing-store-description");
+
+    // `retire` has an entry but no `.desc()`, which is a label and not a sentence an agent can act on.
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("retire");
+  });
+
+  test("stays quiet on a store with no custom actions, which is most of them", async () => {
+    const root = await makeWorkspace({
+      "libs/shared/lib/post/post.store.ts": storeOf(`  // action`),
+      "libs/shared/lib/post/post.dictionary.ts": `export const dictionary = modelDictionary(["en", "ko"]);\n`,
+    });
+
+    expect(rulesOf(await new AkanQualityScanner().scan(root), "akan.agent.missing-store-description")).toHaveLength(0);
+  });
+});
+
+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,13 +1,17 @@
 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 { McpScanner } from "./mcpScanner";
 import { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
+import { StoreScanner } from "./storeScanner";
+import { appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
-type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "mcp" | "agent";
 
 export interface QualityWarning {
   rule: string;
@@ -90,29 +94,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",
@@ -122,24 +103,6 @@ const CONVENTION_SUFFIXES = [
   ".store.ts",
 ] as const;
 
-// Non-PascalCase exports the framework recognizes on page/layout route modules (see PageModule/LayoutModule
-// in pkgs/akanjs/client/csrTypes.ts). PascalCase route exports (Loading, NotFound, Error) pass the component
-// check, and the `default` export is handled separately.
-const PAGE_RESERVED_EXPORTS = new Set([
-  "pageConfig",
-  "head",
-  "metadata",
-  "generateHead",
-  "generateMetadata",
-  "fonts",
-  "manifest",
-  "theme",
-  "reconnect",
-  "wsConnect",
-  "layoutStyle",
-  "gaTrackingId",
-]);
-
 // How to remediate each rule, keyed by rule id. Surfaced as a `fix:` line per warning (text + JSON output)
 // so the scan result tells the reader what to do, not just what is wrong.
 const RULE_FIXES: Record<string, string> = {
@@ -183,6 +146,12 @@ const RULE_FIXES: Record<string, string> = {
     "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 — 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 — 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 — 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.",
 };
 
 function getRuleFix(rule: string): string | undefined {
@@ -213,6 +182,8 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
       ...ssr.warnings,
+      ...new McpScanner().scan(sourceFiles),
+      ...new StoreScanner().scan(sourceFiles),
     ];
 
     return {
@@ -449,7 +420,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",
@@ -460,7 +431,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",
@@ -691,7 +662,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) {