@akanjs/devkit 3.0.0-alpha.4 → 3.0.0-alpha.40

package/qualityScanner.ts

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

package/spinner.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { Spinner } from "./spinner";
+
+interface TtyStub {
+  restore: () => void;
+  rawModeCalls: boolean[];
+}
+
+/**
+ * ora only reaches for stdin when both streams look interactive, so the stub has to fake a tty on
+ * stderr (which decides `isEnabled`) as well as on stdin.
+ */
+const stubTty = (): TtyStub => {
+  const rawModeCalls: boolean[] = [];
+  const stdin = process.stdin as NodeJS.ReadStream & { setRawMode?: (mode: boolean) => unknown };
+  const previous = {
+    stdinIsTTY: stdin.isTTY,
+    stderrIsTTY: process.stderr.isTTY,
+    stderrColumns: process.stderr.columns,
+    setRawMode: stdin.setRawMode,
+    isPaused: stdin.isPaused,
+  };
+  stdin.isTTY = true;
+  process.stderr.isTTY = true;
+  process.stderr.columns = 120;
+  stdin.setRawMode = (mode: boolean) => {
+    rawModeCalls.push(mode);
+    return stdin;
+  };
+  stdin.isPaused = () => true;
+  return {
+    rawModeCalls,
+    restore: () => {
+      stdin.isTTY = previous.stdinIsTTY;
+      process.stderr.isTTY = previous.stderrIsTTY;
+      process.stderr.columns = previous.stderrColumns;
+      stdin.setRawMode = previous.setRawMode;
+      stdin.isPaused = previous.isPaused;
+    },
+  };
+};
+
+describe("Spinner", () => {
+  // A raw terminal at spawn time is what a Bun child snapshots and writes back when it exits, which is
+  // how `akan start` used to leave a terminal that no longer turns Ctrl+C into SIGINT.
+  test("never puts the terminal into raw mode while it spins", () => {
+    const tty = stubTty();
+    try {
+      const spinner = new Spinner("Preparing backend...").start();
+      expect(tty.rawModeCalls).toEqual([]);
+      spinner.succeed("prepared");
+      expect(tty.rawModeCalls).toEqual([]);
+    } finally {
+      tty.restore();
+    }
+  });
+
+  test("keeps ora's stdin discarder disabled", () => {
+    expect(Spinner.oraOptions.discardStdin).toBe(false);
+  });
+
+  // An unsized pty reports `isTTY: true` with `columns: 0`, which turns ora's clear loop into an
+  // infinite one — the process then writes cursor moves until it is SIGKILLed.
+  test("refuses to animate against a tty that reports no width", () => {
+    expect(Spinner.canAnimate({ isTTY: true, columns: 0 } as NodeJS.WriteStream)).toBe(false);
+    expect(Spinner.canAnimate({ isTTY: true, columns: 120 } as NodeJS.WriteStream)).toBe(true);
+    expect(Spinner.canAnimate({ isTTY: false, columns: 0 } as NodeJS.WriteStream)).toBe(true);
+  });
+
+  test("falls back to plain lines when the terminal has no width", () => {
+    const previous = { isTTY: process.stderr.isTTY, columns: process.stderr.columns };
+    process.stderr.isTTY = true;
+    process.stderr.columns = 0;
+    try {
+      expect(new Spinner("Preparing backend...").enableSpin).toBe(false);
+    } finally {
+      process.stderr.isTTY = previous.isTTY;
+      process.stderr.columns = previous.columns;
+    }
+  });
+});

package/spinner.ts

@@ -2,6 +2,26 @@ import ora, { type Ora } from "ora";
 
 export class Spinner {
   static padding = 12;
+  /**
+   * XXX: `discardStdin` must stay off. It makes ora put the terminal into raw mode for as long as the
+   * spinner runs, and a Bun child spawned in that window snapshots the raw termios and writes it back
+   * when it exits — long after the spinner restored the terminal. `akan start` spawns the builder and
+   * the backend under the "Preparing backend..." spinner, so the first builder recycle (a config or
+   * runtime-metadata change) SIGTERMs that child and silently turns the developer's terminal raw:
+   * `isig` goes off, Ctrl+C stops producing SIGINT at all, and the dev server looks unkillable.
+   */
+  static oraOptions = { discardStdin: false } as const;
+  /**
+   * ora sizes its clear loop as `ceil(lineWidth / stream.columns)`, so a tty that reports **0** columns
+   * makes it `Infinity` and `clear()` never returns. An unsized pty does exactly that (`isTTY: true`,
+   * `columns: 0`) — CI runners, `expect`/`script` harnesses, some detached panes. Measured: 750MB of
+   * cursor moves and 8.7GB RSS inside a minute, in a loop that no longer reaches the point where SIGINT
+   * or SIGTERM could be handled, so only SIGKILL ends it. A terminal with no width has nothing to
+   * animate anyway; fall back to plain lines.
+   */
+  static canAnimate(stream: NodeJS.WriteStream = process.stderr): boolean {
+    return !stream.isTTY || stream.columns > 0;
+  }
   spinner: Ora;
   stopWatch: NodeJS.Timeout | null = null;
   startAt: Date = new Date();
@@ -12,10 +32,10 @@ export class Spinner {
     Spinner.padding = Math.max(Spinner.padding, prefix.length);
     this.prefix = prefix;
     this.message = message;
-    this.spinner = ora(message);
+    this.spinner = ora({ ...Spinner.oraOptions, text: message });
     this.spinner.prefixText = prefix.padStart(Spinner.padding, " ");
     this.spinner.indent = indent;
-    this.enableSpin = enableSpin;
+    this.enableSpin = enableSpin && Spinner.canAnimate();
   }
   start() {
     this.startAt = new Date();