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

package/workflow/executor.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "bun:test";
+import { WorkflowExecutor, workflowStepKey } from "./executor";
+import type {
+  PrimitiveChangedFile,
+  WorkflowDiagnostic,
+  WorkflowPlan,
+  WorkflowStep,
+  WorkflowStepRegistry,
+  WorkflowStepResult,
+} from "./types";
+
+/**
+ * `WorkflowExecutor` takes its registry by constructor injection and its plan as data, so `apply` runs with
+ * no filesystem and no workspace — the `workspace` argument is what gates every post-apply check. These
+ * cover the ordering rules that `cli/workflow/workflow.test.ts` can only reach through a real scaffold.
+ */
+const step = (id: string, tool = `tool:${id}`): WorkflowStep => ({
+  id,
+  tool,
+  title: id,
+  description: id,
+});
+
+// Every field spelled out rather than cast through `unknown`: `apply` reads `validation` before the first
+// step runs, so a partial literal fails at runtime instead of at the type level.
+const planOf = (steps: WorkflowStep[], diagnostics: WorkflowDiagnostic[] = []): WorkflowPlan => ({
+  schemaVersion: 1,
+  workflow: "add-field",
+  mode: "plan",
+  inputs: {},
+  optionalSurfaces: {},
+  steps,
+  predictedChanges: [],
+  validation: [],
+  diagnostics,
+  recommendations: [],
+  requiresApproval: true,
+});
+
+/**
+ * A registry that records **which key** each call resolved through, not just that a step ran — the
+ * resolution order is the thing under test, and every candidate key would otherwise record the same step id.
+ */
+const changed = (path: string): PrimitiveChangedFile => ({ path, action: "modify", reason: "test" });
+
+const recordingRegistry = (results: Record<string, WorkflowStepResult | undefined> = {}) => {
+  const calls: string[] = [];
+  const registry: WorkflowStepRegistry = {};
+  const on = (key: string) => {
+    registry[key] = async () => {
+      calls.push(key);
+      return results[key];
+    };
+  };
+  return { calls, registry, on };
+};
+
+describe("WorkflowExecutor.apply", () => {
+  test("runs no step when the plan already carries an error diagnostic", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "one"));
+    const plan = planOf([step("one")], [{ severity: "error", code: "plan-invalid", message: "bad inputs" }]);
+
+    const report = await new WorkflowExecutor(registry).apply(plan);
+
+    expect(calls).toEqual([]);
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("plan-invalid");
+  });
+
+  test("a warning in the plan does not stop the steps", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "one"));
+    const plan = planOf([step("one")], [{ severity: "warning", code: "plan-note", message: "heads up" }]);
+
+    await new WorkflowExecutor(registry).apply(plan);
+
+    expect(calls).toEqual([workflowStepKey("add-field", "one")]);
+  });
+
+  test("resolves a runner by workflow-scoped key first, then tool, then bare step id", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    // All three keys are registered for the same step, so only the winner records a call.
+    on(workflowStepKey("add-field", "scoped"));
+    on("tool:scoped");
+    on("scoped");
+    await new WorkflowExecutor(registry).apply(planOf([step("scoped")]));
+    expect(calls).toEqual([workflowStepKey("add-field", "scoped")]);
+
+    const byTool = recordingRegistry();
+    byTool.on("tool:viaTool");
+    byTool.on("viaTool");
+    await new WorkflowExecutor(byTool.registry).apply(planOf([step("viaTool")]));
+    expect(byTool.calls).toEqual(["tool:viaTool"]);
+
+    const byId = recordingRegistry();
+    byId.on("viaId");
+    await new WorkflowExecutor(byId.registry).apply(planOf([step("viaId")]));
+    expect(byId.calls).toEqual(["viaId"]);
+  });
+
+  test("an unsupported step is reported and abandons the rest of the plan", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "first"));
+    on(workflowStepKey("add-field", "third"));
+
+    const report = await new WorkflowExecutor(registry).apply(planOf([step("first"), step("second"), step("third")]));
+
+    expect(calls).toEqual([workflowStepKey("add-field", "first")]);
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("workflow-step-unsupported");
+    expect(report.nextActions.map((action) => action.command)).toContain("akan workflow explain add-field");
+  });
+
+  test("accumulates changed files and diagnostics across steps, and stops at the first error", async () => {
+    const key = (id: string) => workflowStepKey("add-field", id);
+    const { calls, registry, on } = recordingRegistry({
+      [key("a")]: { changedFiles: [changed("apps/demo/lib/task/task.constant.ts")] },
+      [key("b")]: {
+        changedFiles: [changed("apps/demo/lib/task/task.dictionary.ts")],
+        diagnostics: [{ severity: "error", code: "step-failed", message: "no such module" }],
+      },
+      [key("c")]: { changedFiles: [changed("never-reached.ts")] },
+    });
+    on(key("a"));
+    on(key("b"));
+    on(key("c"));
+
+    const report = await new WorkflowExecutor(registry).apply(planOf([step("a"), step("b"), step("c")]));
+
+    expect(calls).toEqual([key("a"), key("b")]);
+    expect(report.changedFiles.map((file) => file.path)).toEqual([
+      "apps/demo/lib/task/task.constant.ts",
+      "apps/demo/lib/task/task.dictionary.ts",
+    ]);
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("step-failed");
+  });
+
+  test("a runner that answers nothing is not an error", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "silent"));
+    const report = await new WorkflowExecutor(registry).apply(planOf([step("silent")]));
+
+    expect(calls).toEqual([workflowStepKey("add-field", "silent")]);
+    expect(report.diagnostics.filter((diagnostic) => diagnostic.severity === "error")).toEqual([]);
+    expect(report.changedFiles).toEqual([]);
+  });
+});

package/workspaceLayout.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
+import {
+  appRootAllowedDirs,
+  appRootAllowedFiles,
+  isAllowedLibFacetRootFile,
+  isScannedRootEntry,
+  libRootAllowedDirs,
+  libRootAllowedFiles,
+} from "./workspaceLayout";
 
 describe("app root layout allowlist", () => {
   test("admits the scoped agent guides sync writes into every app", () => {
@@ -19,8 +26,53 @@ describe("app root layout allowlist", () => {
   });
 
   test("skips dotfile artifacts the sync glob never sees, but keeps .akan", () => {
-    expect(isScannedAppRootEntry(".DS_Store")).toBe(false);
-    expect(isScannedAppRootEntry(".akan")).toBe(true);
-    expect(isScannedAppRootEntry("lib")).toBe(true);
+    expect(isScannedRootEntry("app", ".DS_Store")).toBe(false);
+    expect(isScannedRootEntry("app", ".akan")).toBe(true);
+    expect(isScannedRootEntry("app", "lib")).toBe(true);
+  });
+});
+
+describe("lib root layout allowlist", () => {
+  test("admits what the libRoot template and scan write", () => {
+    for (const filename of ["AGENTS.md", "akan.config.ts", "akan.lib.json", "client.ts", "index.ts", "server.ts"]) {
+      expect(libRootAllowedFiles.has(filename)).toBe(true);
+    }
+    for (const dirname of ["common", "env", "lib", "page", "plugin", "private", "public", "srvkit", "ui", "webkit"]) {
+      expect(libRootAllowedDirs.has(dirname)).toBe(true);
+    }
+  });
+
+  test("rejects a lib root entry no facet owns", () => {
+    expect(libRootAllowedFiles.has("helper.ts")).toBe(false);
+    expect(libRootAllowedDirs.has("base")).toBe(false);
+  });
+
+  test("rejects the app-only run and mobile entries", () => {
+    for (const filename of ["main.ts", "capacitor.config.ts", "akan.app.json"]) {
+      expect(libRootAllowedFiles.has(filename)).toBe(false);
+    }
+    for (const dirname of [".akan", "android", "ios", "mobile", "script", "secrets"]) {
+      expect(libRootAllowedDirs.has(dirname)).toBe(false);
+    }
+  });
+
+  test("skips dotfile artifacts in a lib root too", () => {
+    expect(isScannedRootEntry("lib", ".gitignore")).toBe(false);
+    expect(isScannedRootEntry("lib", ".akan")).toBe(false);
+    expect(isScannedRootEntry("lib", "ui")).toBe(true);
+  });
+});
+
+describe("lib facet root allowlist", () => {
+  test("admits the generated support facets and a root signal test", () => {
+    expect(isAllowedLibFacetRootFile("cnst.ts")).toBe(true);
+    expect(isAllowedLibFacetRootFile("option.ts")).toBe(true);
+    expect(isAllowedLibFacetRootFile("user.signal.test.ts")).toBe(true);
+    expect(isAllowedLibFacetRootFile("user.signal.spec.ts")).toBe(true);
+  });
+
+  test("rejects a hand-written file beside the barrels", () => {
+    expect(isAllowedLibFacetRootFile("helper.ts")).toBe(false);
+    expect(isAllowedLibFacetRootFile("user.test.ts")).toBe(false);
   });
 });

package/workspaceLayout.ts

@@ -4,10 +4,11 @@
  * 같은 규칙을 scanInfo(`akan sync`, hard error) · akanContext(`akan doctor`, diagnostic) ·
  * qualityScanner(`akan quality scan`, warning) 세 곳이 각자 복사해 두면서 실제로 어긋났다
  * (스코프 AGENTS.md/CLAUDE.md 는 sync 만 허용, `plugin` 은 문서에만, `secrets` 는 doctor 만 거부).
- * 규칙을 추가할 때는 이 파일만 고치고, 루트 AGENTS.md 와 `.cursor/rules/akan-scan-conventions.mdc`
- * 의 목록도 같이 갱신한다.
+ * 규칙을 추가할 때는 이 파일만 고치고, 루트 AGENTS.md 의 목록도 같이 갱신한다.
  */
 
+export type SysType = "app" | "lib";
+
 export const appRootAllowedFiles = new Set([
   // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
   "AGENTS.md",
@@ -42,6 +43,43 @@ export const appRootAllowedDirs = new Set([
   "webkit",
 ]);
 
+/**
+ * 라이브러리 루트는 앱 루트에서 실행/모바일 전용 항목(`main.ts`, `capacitor.config.ts`, `.akan`,
+ * `android`, `ios`, `mobile`, `script`, `secrets`)을 뺀 집합이다 — 라이브러리는 부팅되지도, 패키징되지도
+ * 않는다. `index.ts` 는 lib 에만 생성되고, `README.md` / `tsconfig.spec.json` 은 라이브러리가 패키지로
+ * 배포되기 때문에 남는다. `public` / `private` 은 syncAssets 가 앱으로 심링크하므로 라이브러리도 가진다.
+ */
+export const libRootAllowedFiles = new Set([
+  "AGENTS.md",
+  "CLAUDE.md",
+  "README.md",
+  "akan.config.ts",
+  "akan.lib.json",
+  "client.ts",
+  "index.ts",
+  "package.json",
+  "server.ts",
+  "tsconfig.json",
+  "tsconfig.spec.json",
+  "tsconfig.tsbuildinfo",
+]);
+
+export const libRootAllowedDirs = new Set([
+  "common",
+  "env",
+  "lib",
+  "page",
+  "plugin",
+  "private",
+  "public",
+  "srvkit",
+  "ui",
+  "webkit",
+]);
+
+export const rootAllowedFiles = { app: appRootAllowedFiles, lib: libRootAllowedFiles } as const;
+export const rootAllowedDirs = { app: appRootAllowedDirs, lib: libRootAllowedDirs } as const;
+
 export const libFacetRootAllowedFiles = new Set([
   "cnst.ts",
   "db.ts",
@@ -54,8 +92,15 @@ export const libFacetRootAllowedFiles = new Set([
   "useServer.ts",
 ]);
 
+/** `<model>.signal.test.ts` — lib 파싯 루트에 놓이는 유일한 비생성 파일 (테스트가 배럴 전체를 부팅한다). */
+const libFacetRootTestPattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(ts|tsx)$/;
+
+export const isAllowedLibFacetRootFile = (filename: string) =>
+  libFacetRootAllowedFiles.has(filename) || libFacetRootTestPattern.test(filename);
+
 /**
- * scanSync 는 앱 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
+ * scanSync 는 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
  * doctor 가 그 차이만큼 `.DS_Store` 같은 툴 산출물을 에러로 올리므로 같은 기준으로 걸러낸다.
  */
-export const isScannedAppRootEntry = (name: string) => !name.startsWith(".") || appRootAllowedDirs.has(name);
+export const isScannedRootEntry = (type: SysType, name: string) =>
+  !name.startsWith(".") || rootAllowedDirs[type].has(name);

package/builder.ts

@@ -1,164 +0,0 @@
-import { existsSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
-import path from "node:path";
-import type { Loader } from "bun";
-import type { Executor } from "./executors";
-import { FileSys } from "./fileSys";
-import type { PackageJson } from "./types";
-
-/** Relative paths under these directories are not used as Bun.build entrypoints (Bun does not expand `**` in entrypoint strings; we scan with {@link Bun.Glob}). */
-const SKIP_ENTRY_DIR_SET = new Set(["node_modules", "dist", "build", ".git", ".next"]);
-
-const assetExtensions = [".css", ".md", ".js", ".png", ".ico", ".svg", ".json", ".template"];
-const assetLoader = Object.fromEntries(assetExtensions.map((ext) => [ext, "file" as const])) satisfies Record<
-  string,
-  Loader
->;
-
-type BunBuildConfig = Parameters<typeof Bun.build>[0] & { bundle?: boolean };
-type ExportValue = string | string[] | { [condition: string]: ExportValue };
-
-interface BuildOptions {
-  bundle?: boolean;
-  additionalEntryPoints?: string[];
-}
-
-interface BuilderOptions {
-  executor: Executor;
-  distExecutor: Executor;
-  pkgJson: PackageJson;
-  rootPackageJson: PackageJson;
-}
-export class Builder {
-  #executor: Executor;
-  #distExecutor: Executor;
-  #pkgJson: PackageJson;
-
-  constructor({ executor, distExecutor, pkgJson }: BuilderOptions) {
-    this.#executor = executor;
-    this.#distExecutor = distExecutor;
-    this.#pkgJson = pkgJson;
-  }
-  #globEntrypoints(cwd: string, pattern: string): string[] {
-    const glob = new Bun.Glob(pattern);
-    return Array.from(glob.scanSync({ cwd, onlyFiles: true }))
-      .filter((relativePath) => {
-        const segments = relativePath.split(path.sep);
-        return !segments.some((segment) => SKIP_ENTRY_DIR_SET.has(segment));
-      })
-      .map((rel) => path.join(cwd, rel));
-  }
-  #globFiles(cwd: string, pattern = "**/*.*"): string[] {
-    const glob = new Bun.Glob(pattern);
-    return Array.from(glob.scanSync({ cwd, onlyFiles: true })).filter((relativePath) => {
-      const segments = relativePath.split(path.sep);
-      return !segments.some((segment) => SKIP_ENTRY_DIR_SET.has(segment));
-    });
-  }
-
-  #resolveAdditionalEntrypoints(cwd: string, additionalEntryPoints: string[]): string[] {
-    const out: string[] = [];
-    for (const p of additionalEntryPoints) {
-      if (p.includes("*")) {
-        const rel = p.startsWith(`${cwd}/`) || p.startsWith(`${cwd}${path.sep}`) ? p.slice(cwd.length + 1) : p;
-        out.push(...this.#globEntrypoints(cwd, rel));
-      } else out.push(path.isAbsolute(p) ? p : path.join(cwd, p));
-    }
-    return out;
-  }
-  #getBuildOptions({ bundle = false, additionalEntryPoints = [] }: BuildOptions = {}): BunBuildConfig {
-    const cwd = this.#executor.cwdPath;
-    const entrypoints = [
-      ...(bundle ? [path.join(cwd, "index.ts")] : this.#globEntrypoints(cwd, "**/*.{ts,tsx}")),
-      ...this.#resolveAdditionalEntrypoints(cwd, additionalEntryPoints),
-    ];
-    return {
-      root: cwd,
-      entrypoints,
-      bundle,
-      packages: "external",
-      splitting: false,
-      target: this.#pkgJson.bun?.platform,
-      format: "esm",
-      outdir: this.#distExecutor.cwdPath,
-      external: ["react", "react-dom"],
-      loader: assetLoader,
-    };
-  }
-  async #copySourceFiles() {
-    const cwd = this.#executor.cwdPath;
-    for (const relativePath of this.#globFiles(cwd)) {
-      if (relativePath === "package.json") continue;
-      const sourcePath = path.join(cwd, relativePath);
-      const targetPath = path.join(this.#distExecutor.cwdPath, relativePath);
-      await mkdir(path.dirname(targetPath), { recursive: true });
-      await Bun.write(targetPath, Bun.file(sourcePath));
-    }
-  }
-  #toPublishedPath(publishedPath: string, { useSource }: { useSource: boolean }) {
-    const hasDotSlash = publishedPath.startsWith("./");
-    const withoutFormatDir = publishedPath.replace(/^(?:\.\/)?(?:esm|cjs)\//, hasDotSlash ? "./" : "");
-    if (!useSource) return withoutFormatDir;
-    if (!hasDotSlash && withoutFormatDir === publishedPath) return publishedPath;
-    const parsed = path.posix.parse(withoutFormatDir);
-    if (![".js", ".mjs", ".cjs"].includes(parsed.ext)) return withoutFormatDir;
-    const withoutExt = path.posix.join(parsed.dir, parsed.name);
-    const sourcePath = withoutExt.startsWith("./") ? withoutExt.slice(2) : withoutExt;
-    const sourceCandidates = [`${sourcePath}.ts`, `${sourcePath}.tsx`];
-    const matchedSource = sourceCandidates.find((candidate) =>
-      existsSync(path.join(this.#executor.cwdPath, candidate)),
-    );
-    if (!matchedSource) return withoutFormatDir;
-    return hasDotSlash ? `./${matchedSource}` : matchedSource;
-  }
-  #normalizeExports(
-    exportsValue: ExportValue | undefined,
-    { useSource }: { useSource: boolean },
-  ): ExportValue | undefined {
-    if (!exportsValue) return exportsValue;
-    if (typeof exportsValue === "string") return this.#toPublishedPath(exportsValue, { useSource });
-    if (Array.isArray(exportsValue))
-      return exportsValue.map((value) => this.#normalizeExports(value, { useSource }) as string);
-    if (typeof exportsValue !== "object") return exportsValue;
-
-    return Object.fromEntries(
-      Object.entries(exportsValue)
-        .filter(([condition]) => condition !== "require")
-        .map(([condition, value]) => [condition, this.#normalizeExports(value, { useSource })])
-        .filter((entry): entry is [string, ExportValue] => entry[1] !== undefined),
-    );
-  }
-  #getPackageJson({ bundle = false }: BuildOptions = {}): PackageJson {
-    const rootEntry = bundle ? "./index.js" : "./index.ts";
-    const normalizedExports = this.#normalizeExports(this.#pkgJson.exports as ExportValue | undefined, {
-      useSource: !bundle,
-    });
-    return {
-      ...this.#pkgJson,
-      type: "module",
-      main: rootEntry,
-      bin: this.#normalizeExports(this.#pkgJson.bin as ExportValue | undefined, { useSource: !bundle }),
-      exports: {
-        ...((typeof normalizedExports === "object" && !Array.isArray(normalizedExports)
-          ? normalizedExports
-          : {}) as Record<string, ExportValue>),
-        ".": {
-          import: rootEntry,
-          types: bundle ? "./index.d.ts" : "./index.ts",
-        },
-      },
-    };
-  }
-  async build(options: BuildOptions = {}) {
-    if (await FileSys.dirExists(this.#distExecutor.cwdPath))
-      await this.#distExecutor.exec(`rm -rf ${this.#distExecutor.cwdPath}`);
-
-    if (options.bundle) {
-      const buildResult = await Bun.build({ ...this.#getBuildOptions(options) });
-      if (!buildResult.success) throw new AggregateError(buildResult.logs, "Bundle failed");
-    } else await this.#copySourceFiles();
-
-    const pkgPackageJson = this.#getPackageJson(options);
-    await this.#distExecutor.setPackageJson(pkgPackageJson);
-  }
-}

package/extractDeps.ts

@@ -1,86 +0,0 @@
-import type { PackageJson } from "./types";
-
-const NODE_NATIVE_MODULE_SET = new Set([
-  "assert",
-  "async_hooks",
-  "buffer",
-  "child_process",
-  "cluster",
-  "console",
-  "constants",
-  "crypto",
-  "dgram",
-  "dns",
-  "domain",
-  "events",
-  "fs",
-  "http",
-  "http2",
-  "https",
-  "inspector",
-  "module",
-  "net",
-  "os",
-  "path",
-  "perf_hooks",
-  "process",
-  "punycode",
-  "querystring",
-  "readline",
-  "repl",
-  "stream",
-  "string_decoder",
-  "timers",
-  "tls",
-  "trace_events",
-  "tty",
-  "url",
-  "util",
-  "v8",
-  "vm",
-  "wasi",
-  "worker_threads",
-  "zlib",
-]);
-
-export const extractDependencies = (
-  filepaths: { path: string; text: string }[],
-  pacakgeJson: PackageJson,
-  defaultDependencies: string[] = [],
-) => {
-  if (!pacakgeJson.dependencies) throw new Error("No dependencies found in package.json");
-  const dependencies = new Set<string>(defaultDependencies);
-
-  const existingDependencies = new Set<string>([
-    ...Object.keys(pacakgeJson.dependencies ?? {}),
-    ...Object.keys(pacakgeJson.devDependencies ?? {}),
-  ]);
-  const versionObj = {
-    ...(pacakgeJson.dependencies ?? {}),
-    ...(pacakgeJson.devDependencies ?? {}),
-  };
-
-  // Look for require statements: require('package-name') or import 'package-name'
-  const requireRegex = /(?:require\s*\(|import\s*(?:[\w\s{},*]*\s+from\s*)?|import\s*\()\s*['"`]([^'"`]+)['"`]/g;
-  for (const { text } of filepaths.filter(({ path }) => path.endsWith(".js") || path.endsWith(".ts"))) {
-    let requireMatch = requireRegex.exec(text);
-    while (requireMatch !== null) {
-      const moduleName = requireMatch[1];
-      if (!moduleName) throw new Error(`No module name found in ${text}`);
-      const moduleNameParts = moduleName.split("/");
-      const subModuleLength = moduleNameParts.length;
-      for (let i = 0; i < subModuleLength; i++) {
-        const libName = moduleNameParts.slice(0, i + 1).join("/");
-        if (!NODE_NATIVE_MODULE_SET.has(libName) && existingDependencies.has(libName)) dependencies.add(libName);
-      }
-      requireMatch = requireRegex.exec(text);
-    }
-  }
-  return Object.fromEntries(
-    [...dependencies].sort().map((dep) => {
-      const version = versionObj[dep];
-      if (!version) throw new Error(`No version found for ${dep}`);
-      return [dep, version];
-    }),
-  );
-};