@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.20

package/platformTest/TestSnapshot.ts

@@ -0,0 +1,103 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export interface SnapshotDrift {
+  changed: string[];
+  added: string[];
+  removed: string[];
+}
+
+//? Per-file hashes are kept so the tree is re-checked before publishing: a run gates only if nothing changed under it.
+export class TestSnapshot {
+  static readonly #secretPatterns = [
+    /(^|\/)\.env(\.(?!(template|example|sample)$)[^/]+)?$/,
+    /(^|\/)env\/env\.(client|server)\.(?!(type|example)\.ts$)[^/]+\.ts$/,
+  ];
+
+  readonly root: string;
+  readonly tarPath: string;
+  readonly digest: string;
+  readonly #hashes: Map<string, string>;
+
+  constructor(root: string, tarPath: string, hashes: Map<string, string>) {
+    this.root = root;
+    this.tarPath = tarPath;
+    this.#hashes = hashes;
+    this.digest = TestSnapshot.#digestOf(hashes);
+  }
+
+  get fileCount() {
+    return this.#hashes.size;
+  }
+
+  static async create(root: string, outDir: string) {
+    const hashes = await TestSnapshot.#hashTree(root);
+    //? A tracked file is already in the repository; only an untracked one nobody ignored can leak by being copied.
+    const untracked = await TestSnapshot.#gitList(root, ["--others", "--exclude-standard"]);
+    const secrets = untracked.filter((file) => TestSnapshot.#secretPatterns.some((re) => re.test(file)));
+    if (secrets.length)
+      throw new Error(
+        `Refusing to snapshot env files git does not ignore — they would be copied to every test target: ${secrets.join(", ")}`,
+      );
+    await mkdir(outDir, { recursive: true });
+    const listPath = path.join(outDir, "files.txt");
+    const tarPath = path.join(outDir, "src.tar");
+    await writeFile(listPath, `${[...hashes.keys()].join("\n")}\n`);
+    const tar = Bun.spawn(
+      ["tar", ...(process.platform === "darwin" ? ["--no-xattrs"] : []), "-cf", tarPath, "-T", listPath],
+      { cwd: root, env: { ...process.env, COPYFILE_DISABLE: "1" }, stdout: "ignore", stderr: "pipe" },
+    );
+    if ((await tar.exited) !== 0) throw new Error(`tar failed: ${await new Response(tar.stderr).text()}`);
+    return new TestSnapshot(root, tarPath, hashes);
+  }
+
+  async drift(): Promise<SnapshotDrift> {
+    const current = await TestSnapshot.#hashTree(this.root);
+    const changed = [...current].filter(([file, hash]) => this.#hashes.has(file) && this.#hashes.get(file) !== hash);
+    return {
+      changed: changed.map(([file]) => file),
+      added: [...current.keys()].filter((file) => !this.#hashes.has(file)),
+      removed: [...this.#hashes.keys()].filter((file) => !current.has(file)),
+    };
+  }
+
+  static async #gitList(root: string, args: string[]) {
+    const proc = Bun.spawn(["git", "ls-files", ...args, "-z"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (exitCode !== 0) throw new Error(`git ls-files failed in ${root}: ${stderr.trim()}`);
+    return [...new Set(stdout.split("\0").filter(Boolean))].sort();
+  }
+
+  static async #listFiles(root: string) {
+    const listed = await TestSnapshot.#gitList(root, ["--cached", "--others", "--exclude-standard"]);
+    //? `--cached` still lists a tracked file deleted from the working tree, which tar would then fail on.
+    const present = await Promise.all(
+      listed.map(async (file) => ((await stat(path.join(root, file)).catch(() => null))?.isFile() ? file : null)),
+    );
+    return present.filter((file): file is string => file !== null);
+  }
+
+  static async #hashTree(root: string) {
+    const files = await TestSnapshot.#listFiles(root);
+    const hashes = new Map<string, string>();
+    for (let start = 0; start < files.length; start += 64) {
+      const batch = files.slice(start, start + 64);
+      const batchHashes = await Promise.all(
+        batch.map(async (file) => Bun.hash(await Bun.file(path.join(root, file)).bytes()).toString(16)),
+      );
+      for (const [idx, file] of batch.entries()) hashes.set(file, batchHashes[idx] ?? "");
+    }
+    return hashes;
+  }
+
+  static #digestOf(hashes: Map<string, string>) {
+    return Bun.hash([...hashes].map(([file, hash]) => `${file}:${hash}`).join("\n"))
+      .toString(16)
+      .padStart(16, "0")
+      .slice(0, 12);
+  }
+}

package/platformTest/WindowsSshTarget.ts

@@ -0,0 +1,151 @@
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { PlatformGatePolicy, WindowsTestTargetConfig } from "../cloud/constants";
+import { IdleWatchedProcess } from "./IdleWatchedProcess";
+import { type PlatformRunContext, PlatformTestTarget } from "./PlatformTestTarget";
+
+export class WindowsSshTarget extends PlatformTestTarget {
+  static readonly utmctlPath = "/Applications/UTM.app/Contents/MacOS/utmctl";
+  static readonly defaultWorkRoot = "C:\\akan-test";
+  //* arm64 has neither a sharp@0.32 prebuilt nor a Chrome for puppeteer's postinstall; x64 users get both.
+  static readonly defaultTolerateScriptFailures = ["sharp", "puppeteer"];
+  static readonly #runDirPattern = "^\\d{8}-\\d{6}$";
+  static readonly #keptRuns = 2;
+
+  readonly platform = "windows";
+  readonly policy: PlatformGatePolicy;
+  protected override readonly tolerateScriptFailures: string[];
+  readonly #config: WindowsTestTargetConfig;
+  #host: string;
+  #runDir: string | null = null;
+
+  constructor(config: WindowsTestTargetConfig) {
+    super();
+    this.#config = config;
+    this.#host = process.env.AKAN_TEST_WINDOWS_HOST ?? config.host;
+    this.policy = config.policy ?? "warn";
+    this.tolerateScriptFailures = config.tolerateScriptFailures ?? WindowsSshTarget.defaultTolerateScriptFailures;
+  }
+
+  get #workRoot() {
+    return this.#config.workRoot ?? WindowsSshTarget.defaultWorkRoot;
+  }
+
+  protected async prepare(context: PlatformRunContext) {
+    await this.#connect();
+    const bunVersion = (await this.#ssh("bun --version")).stdout.trim();
+    if (bunVersion !== Bun.version)
+      throw new Error(
+        `the Windows host runs Bun ${bunVersion || "(none)"}, this host ${Bun.version} — align them first`,
+      );
+    if ((await this.#ssh("git --version")).exitCode !== 0) throw new Error("git is not installed on the Windows host");
+    const runDir = `${this.#workRoot}\\${context.runId}`;
+    const mkdir = await this.#ssh(`New-Item -ItemType Directory -Force -Path '${runDir}\\w' | Out-Null`);
+    if (mkdir.exitCode !== 0) throw new Error(`could not create ${runDir}: ${mkdir.stderr.trim()}`);
+    this.#runDir = runDir;
+    for (const [local, remoteName] of [
+      [context.snapshot.tarPath, "src.tar"],
+      [context.envPath, "env"],
+    ] as const) {
+      const copied = await WindowsSshTarget.spawnText([
+        ...this.#scpBase(),
+        local,
+        this.#remoteScpPath(`${runDir}\\${remoteName}`),
+      ]);
+      if (copied.exitCode !== 0) throw new Error(`scp ${remoteName} failed: ${copied.stderr.trim()}`);
+    }
+    const extract = await this.exec(
+      "tar -xf ..\\src.tar && copy /Y ..\\env .env >nul && git init -q",
+      path.join(context.logDir, this.platform, "extract.log"),
+      PlatformTestTarget.installIdleMs,
+    );
+    if (extract.exitCode !== 0) throw new Error("extracting the snapshot on the Windows host failed");
+  }
+
+  protected async exec(command: string, logPath: string, idleMs: number) {
+    const runDir = this.#runDir;
+    if (!runDir) throw new Error("the Windows run directory was not prepared");
+    let remotePid: string | null = null;
+    const script = [
+      "$ProgressPreference = 'SilentlyContinue'",
+      "[Console]::OutputEncoding = [Text.Encoding]::UTF8",
+      "'PID=' + $PID",
+      ...Object.entries(PlatformTestTarget.gitIdentityEnv).map(([key, value]) => `$env:${key} = '${value}'`),
+      `Set-Location -LiteralPath '${runDir}\\w'`,
+      `cmd /c "${command} 2>&1"`,
+      "exit $LASTEXITCODE",
+    ].join("; ");
+    return await new IdleWatchedProcess([...this.#sshBase(), script], {
+      logPath,
+      idleMs,
+      onOutput: (text) => {
+        remotePid ??= /PID=(\d+)/.exec(text)?.[1] ?? null;
+      },
+      onIdle: async () => {
+        if (remotePid) await this.#ssh(`taskkill /F /T /PID ${remotePid} | Out-Null`);
+      },
+    }).run();
+  }
+
+  protected async cleanup() {
+    this.#runDir = null;
+    await this.#ssh(
+      [
+        `Get-ChildItem -LiteralPath '${this.#workRoot}' -Directory`,
+        `Where-Object { $_.Name -match '${WindowsSshTarget.#runDirPattern}' }`,
+        "Sort-Object Name -Descending",
+        `Select-Object -Skip ${WindowsSshTarget.#keptRuns}`,
+        "ForEach-Object { cmd /c rmdir /s /q $_.FullName }",
+      ].join(" | "),
+    );
+  }
+
+  async #connect() {
+    if ((await this.#ssh("exit 0")).exitCode === 0) return;
+    const vm = this.#config.utmVm;
+    if (!vm || !existsSync(WindowsSshTarget.utmctlPath))
+      throw new Error(`cannot reach ${this.#config.user}@${this.#host} over ssh`);
+    const status = (await WindowsSshTarget.spawnText([WindowsSshTarget.utmctlPath, "status", vm])).stdout.trim();
+    if (status !== "started") await WindowsSshTarget.spawnText([WindowsSshTarget.utmctlPath, "start", vm]);
+    for (let attempt = 0; attempt < 24; attempt++) {
+      const addresses = (await WindowsSshTarget.spawnText([WindowsSshTarget.utmctlPath, "ip-address", vm])).stdout;
+      const ipv4 = addresses.split(/\s+/).find((address) => /^\d+\.\d+\.\d+\.\d+$/.test(address));
+      if (ipv4) this.#host = ipv4;
+      if ((await this.#ssh("exit 0")).exitCode === 0) return;
+      await Bun.sleep(5_000);
+    }
+    throw new Error(`UTM VM "${vm}" did not answer ssh at ${this.#host}`);
+  }
+
+  #sshOptions() {
+    const expand = (file: string) => (file.startsWith("~/") ? path.join(os.homedir(), file.slice(2)) : file);
+    return [
+      "-i",
+      expand(this.#config.identityFile),
+      ...(this.#config.knownHostsFile ? ["-o", `UserKnownHostsFile=${expand(this.#config.knownHostsFile)}`] : []),
+      "-o",
+      "BatchMode=yes",
+      "-o",
+      "ConnectTimeout=8",
+      "-o",
+      "ServerAliveInterval=30",
+    ];
+  }
+
+  #sshBase() {
+    return ["ssh", ...this.#sshOptions(), `${this.#config.user}@${this.#host}`];
+  }
+
+  #scpBase() {
+    return ["scp", "-q", ...this.#sshOptions()];
+  }
+
+  #remoteScpPath(windowsPath: string) {
+    return `${this.#config.user}@${this.#host}:/${windowsPath.replaceAll("\\", "/")}`;
+  }
+
+  async #ssh(script: string) {
+    return await WindowsSshTarget.spawnText([...this.#sshBase(), script]);
+  }
+}

package/prompter.ts

@@ -1,8 +1,7 @@
 import fsPromise from "node:fs/promises";
 import { input, select } from "@inquirer/prompts";
 
-import { getDirname } from "./getDirname";
-import type { GuideGenerateJson } from "./guideline";
+import { getDirname } from "./fileSys";
 
 interface FileUpdateRequestProps {
   context: string;
@@ -34,17 +33,8 @@ export class Prompter {
     const guidelineRoot = await Prompter.#getGuidelineRoot();
     return (await fsPromise.readdir(guidelineRoot)).filter((name) => !name.startsWith("_")).sort();
   }
-  static async getGuideJson(guideName: string): Promise<GuideGenerateJson> {
-    const guidelineRoot = await Prompter.#getGuidelineRoot();
-    const filePath = `${guidelineRoot}/${guideName}/${guideName}.generate.json`;
-    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.
-   */
+  // Checked against the listing, not interpolated into a path: the name is an MCP tool argument, and an unknown one
+  // must not surface an ENOENT carrying the host's paths.
   static async getInstruction(guideName: string): Promise<string> {
     const guideNames = await Prompter.listGuidelines();
     if (!guideNames.includes(guideName))

package/qualityScanner.test.ts

@@ -1,32 +1,23 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { AbstractDoc } from "./abstractDoc";
 import { AkanQualityScanner, type QualityScanResult } from "./qualityScanner";
+import { tempDirs, writeText } from "./testHelpers";
 
-const tempRoots: string[] = [];
+const makeTempRoot = tempDirs("akan-quality-scanner-");
 
 const makeWorkspace = async (files: Record<string, string>) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-quality-scanner-"));
-  tempRoots.push(root);
-  for (const [filePath, content] of Object.entries({ ".gitignore": "node_modules\n", ...files })) {
-    const absolutePath = path.join(root, filePath);
-    await mkdir(path.dirname(absolutePath), { recursive: true });
-    await writeFile(absolutePath, content);
-  }
+  const root = await makeTempRoot();
+  for (const [filePath, content] of Object.entries({ ".gitignore": "node_modules\n", ...files }))
+    await writeText(path.join(root, filePath), content);
   return root;
 };
 
 const abstractOf = (lineNum: number) =>
   ["# post Abstract", ...Array.from({ length: lineNum - 1 }, (_, idx) => `- rule ${idx}`)].join("\n");
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 describe("AkanQualityScanner abstract rule", () => {
-  test("warns on an abstract over the line limit and points at akan compact", async () => {
+  test("warns on an abstract over the line limit and says how to trim it", async () => {
     const root = await makeWorkspace({
       "apps/demo/lib/post/post.abstract.md": abstractOf(AbstractDoc.maxLines + 1),
       "apps/demo/lib/post/post.constant.ts": "export class Post {}\n",
@@ -41,7 +32,8 @@ describe("AkanQualityScanner abstract rule", () => {
     expect(warnings).toHaveLength(1);
     expect(warnings[0]?.file).toBe("apps/demo/lib/post/post.abstract.md");
     expect(warnings[0]?.message).toContain(`${AbstractDoc.maxLines + 1} lines`);
-    expect(warnings[0]?.fix).toContain("akan compact");
+    expect(warnings[0]?.fix).toContain("## Rules");
+    expect(warnings[0]?.fix).not.toContain("akan compact");
   });
 });
 
@@ -184,15 +176,6 @@ 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({