@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/platformTest/PlatformTestRun.ts

@@ -0,0 +1,141 @@
+import path from "node:path";
+import chalk from "chalk";
+import type { TestTargetsConfig } from "../cloud/constants";
+import { GlobalConfig } from "../cloud/globalConfig";
+import { LinuxDockerTarget } from "./LinuxDockerTarget";
+import { type PlatformTestResult, PlatformTestTarget, type RemoteTestPlatform } from "./PlatformTestTarget";
+import { TestSnapshot } from "./TestSnapshot";
+import { WindowsSshTarget } from "./WindowsSshTarget";
+
+interface PlatformTestRunOptions {
+  workspaceRoot: string;
+  platforms: RemoteTestPlatform[];
+  pkgs: string[];
+  targets: TestTargetsConfig;
+  onProgress: (message: string) => void;
+}
+
+export interface PlatformVerdict {
+  blocking: PlatformTestResult[];
+  warning: PlatformTestResult[];
+}
+
+export class PlatformTestRun {
+  //? The CLI refuses a root without these, and the cli suite builds temp workspaces from them; none is a secret.
+  static readonly envKeys = [
+    "USE_AKANJS_PKGS",
+    "AKAN_PUBLIC_REPO_NAME",
+    "AKAN_PUBLIC_SERVE_DOMAIN",
+    "AKAN_PUBLIC_ENV",
+    "AKAN_PUBLIC_OPERATION_MODE",
+    "APP_OPERATION_MODE",
+    "SERVER_MODE",
+  ] as const;
+  static readonly promoteAfterGreenRuns = 3;
+
+  readonly runId: string;
+  readonly logDir: string;
+  readonly snapshot: TestSnapshot;
+  readonly #results: Promise<PlatformTestResult[]>;
+
+  constructor(runId: string, logDir: string, snapshot: TestSnapshot, results: Promise<PlatformTestResult[]>) {
+    this.runId = runId;
+    this.logDir = logDir;
+    this.snapshot = snapshot;
+    this.#results = results;
+  }
+
+  static async start({ workspaceRoot, platforms, pkgs, targets, onProgress }: PlatformTestRunOptions) {
+    const runId = PlatformTestRun.newRunId();
+    const logDir = path.join(workspaceRoot, "local", "deploy-test", runId);
+    const snapshot = await TestSnapshot.create(workspaceRoot, logDir);
+    const envPath = path.join(logDir, "env");
+    await Bun.write(envPath, await PlatformTestRun.allowlistedEnv(workspaceRoot));
+    const instances = platforms.map((platform) => {
+      if (platform === "linux") return new LinuxDockerTarget(targets.linux);
+      if (!targets.windows) throw new Error("the windows test target is not configured");
+      return new WindowsSshTarget(targets.windows);
+    });
+    const results = Promise.all(
+      instances.map((target) => target.run({ snapshot, envPath, runId, logDir, pkgs, onProgress })),
+    );
+    return new PlatformTestRun(runId, logDir, snapshot, results);
+  }
+
+  async results() {
+    return await this.#results;
+  }
+
+  static parsePlatforms(value: string): RemoteTestPlatform[] {
+    const names = value
+      .split(",")
+      .map((name) => name.trim().toLowerCase())
+      .filter((name) => name && name !== "none");
+    const unknown = names.filter((name) => name !== "linux" && name !== "windows");
+    if (unknown.length)
+      throw new Error(`Unknown test platform: ${unknown.join(", ")} (expected linux, windows, or none)`);
+    return [...new Set(names as RemoteTestPlatform[])];
+  }
+
+  static newRunId(now = new Date()) {
+    const pad = (value: number) => String(value).padStart(2, "0");
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  }
+
+  static async allowlistedEnv(workspaceRoot: string) {
+    const envFile = Bun.file(path.join(workspaceRoot, ".env"));
+    const lines = (await envFile.exists()) ? (await envFile.text()).split(/\r?\n/) : [];
+    const allowed = new Set<string>(PlatformTestRun.envKeys);
+    const kept = lines.filter((line) => allowed.has(line.split("=", 1)[0]?.trim() ?? ""));
+    return `${kept.join("\n")}\n`;
+  }
+
+  static failed(result: PlatformTestResult) {
+    return !!result.infraError || result.packages.some((pkg) => pkg.status !== "pass");
+  }
+
+  static verdict(results: PlatformTestResult[]): PlatformVerdict {
+    const failed = results.filter((result) => PlatformTestRun.failed(result));
+    return {
+      blocking: failed.filter((result) => result.policy === "gate"),
+      warning: failed.filter((result) => result.policy === "warn"),
+    };
+  }
+
+  format(results: PlatformTestResult[], { maxFailures = 15 }: { maxFailures?: number } = {}) {
+    const lines = [
+      chalk.bold(
+        `Platform tests · snapshot ${this.snapshot.digest} (${this.snapshot.fileCount} files) · ${path.relative(this.snapshot.root, this.logDir)}`,
+      ),
+    ];
+    for (const result of results) {
+      const mark = PlatformTestRun.failed(result) ? chalk.red("✖") : chalk.green("✔");
+      lines.push(`${mark} ${result.platform} (${result.policy}, ${Math.round(result.ms / 1000)}s)`);
+      if (result.infraError) lines.push(chalk.red(`    setup: ${result.infraError}`));
+      for (const warning of result.envWarnings) lines.push(chalk.yellow(`    env: ${warning}`));
+      for (const pkg of result.packages) {
+        const line = `    ${PlatformTestTarget.describe(pkg)}`;
+        lines.push(pkg.status === "pass" ? line : chalk.red(line));
+        for (const failure of pkg.report.failures.slice(0, maxFailures))
+          lines.push(chalk.dim(`      ${failure.file ? `${failure.file} › ` : ""}${failure.name}`));
+        if (pkg.report.failures.length > maxFailures)
+          lines.push(chalk.dim(`      … ${pkg.report.failures.length - maxFailures} more in ${pkg.logPath}`));
+      }
+    }
+    return lines.join("\n");
+  }
+
+  /** A `warn` platform becomes a gate once it has been green for enough deploys in a row. */
+  static async recordStreaks(results: PlatformTestResult[]) {
+    const targets = await GlobalConfig.getTestTargets();
+    const windows = targets.windows;
+    const result = results.find((one) => one.platform === "windows");
+    if (!windows || !result || (windows.policy ?? "warn") !== "warn") return null;
+    const greenStreak = PlatformTestRun.failed(result) ? 0 : (windows.greenStreak ?? 0) + 1;
+    const promoted = greenStreak >= PlatformTestRun.promoteAfterGreenRuns;
+    await GlobalConfig.setTestTargets({
+      windows: { ...windows, greenStreak, ...(promoted ? { policy: "gate" } : {}) },
+    });
+    return { platform: "windows" as const, greenStreak, promoted };
+  }
+}

package/platformTest/PlatformTestTarget.ts

@@ -0,0 +1,142 @@
+import path from "node:path";
+import type { PlatformGatePolicy } from "../cloud/constants";
+import { BunTestReport } from "./BunTestReport";
+import type { IdleWatchedResult } from "./IdleWatchedProcess";
+import type { TestSnapshot } from "./TestSnapshot";
+
+export type RemoteTestPlatform = "linux" | "windows";
+export type PackageTestStatus = "pass" | "fail" | "hung";
+
+export interface PackageTestResult {
+  pkg: string;
+  status: PackageTestStatus;
+  report: BunTestReport;
+  ms: number;
+  logPath: string;
+}
+
+export interface PlatformTestResult {
+  platform: RemoteTestPlatform;
+  policy: PlatformGatePolicy;
+  packages: PackageTestResult[];
+  envWarnings: string[];
+  infraError: string | null;
+  ms: number;
+}
+
+export interface PlatformRunContext {
+  snapshot: TestSnapshot;
+  envPath: string;
+  runId: string;
+  logDir: string;
+  pkgs: string[];
+  onProgress: (message: string) => void;
+}
+
+export abstract class PlatformTestTarget {
+  static readonly installIdleMs = 5 * 60_000;
+  static readonly testIdleMs = 2 * 60_000;
+  protected static readonly gitIdentityEnv = {
+    GIT_AUTHOR_NAME: "akan-test",
+    GIT_AUTHOR_EMAIL: "akan-test@localhost",
+    GIT_COMMITTER_NAME: "akan-test",
+    GIT_COMMITTER_EMAIL: "akan-test@localhost",
+    GIT_CONFIG_COUNT: "1",
+    GIT_CONFIG_KEY_0: "init.defaultBranch",
+    GIT_CONFIG_VALUE_0: "main",
+  };
+
+  abstract readonly platform: RemoteTestPlatform;
+  abstract readonly policy: PlatformGatePolicy;
+  protected readonly tolerateScriptFailures: string[] = [];
+
+  protected abstract prepare(context: PlatformRunContext): Promise<void>;
+  protected abstract exec(command: string, logPath: string, idleMs: number): Promise<IdleWatchedResult>;
+  protected abstract cleanup(context: PlatformRunContext): Promise<void>;
+
+  async run(context: PlatformRunContext): Promise<PlatformTestResult> {
+    const startedAt = performance.now();
+    const envWarnings: string[] = [];
+    const packages: PackageTestResult[] = [];
+    const result = (infraError: string | null): PlatformTestResult => ({
+      platform: this.platform,
+      policy: this.policy,
+      packages,
+      envWarnings,
+      infraError,
+      ms: performance.now() - startedAt,
+    });
+    try {
+      await this.prepare(context);
+      await this.#install(context, envWarnings);
+      const build = await this.exec(
+        "bun run buildAkan",
+        this.#logPath(context, "build"),
+        PlatformTestTarget.installIdleMs,
+      );
+      if (build.exitCode !== 0) throw new Error(`buildAkan failed — see ${this.#logPath(context, "build")}`);
+      for (const pkg of context.pkgs) {
+        const logPath = this.#logPath(context, `test-${pkg.replaceAll("/", "__")}`);
+        const run = await this.exec(
+          `bun dist/pkgs/@akanjs/cli/index.js test ${pkg}`,
+          logPath,
+          PlatformTestTarget.testIdleMs,
+        );
+        const report = new BunTestReport(run.output);
+        const status: PackageTestStatus =
+          run.hung || run.timedOut ? "hung" : report.passed && run.exitCode === 0 ? "pass" : "fail";
+        packages.push({ pkg, status, report, ms: run.ms, logPath });
+        context.onProgress(`[${this.platform}] ${PlatformTestTarget.describe(packages.at(-1) as PackageTestResult)}`);
+      }
+      return result(null);
+    } catch (error) {
+      return result(error instanceof Error ? error.message : String(error));
+    } finally {
+      await this.cleanup(context).catch(() => undefined);
+    }
+  }
+
+  static describe({ pkg, status, report, ms }: PackageTestResult) {
+    const seconds = `${Math.round(ms / 1000)}s`;
+    if (status === "hung") return `${pkg}: hung${report.lastFile ? ` in ${report.lastFile}` : ""} (${seconds})`;
+    return `${pkg}: ${report.pass} pass / ${report.fail} fail${report.errors ? ` / ${report.errors} errors` : ""} (${seconds})`;
+  }
+
+  async #install(context: PlatformRunContext, envWarnings: string[]) {
+    const logPath = this.#logPath(context, "install");
+    const install = await this.exec("bun install --frozen-lockfile", logPath, PlatformTestTarget.installIdleMs);
+    if (install.exitCode === 0) return;
+    const failedScripts = [...install.output.matchAll(/(?:pre|post)?install script from "([^"]+)" exited/g)].map(
+      (match) => match[1] ?? "",
+    );
+    const tolerable =
+      failedScripts.length > 0 && failedScripts.every((pkg) => this.tolerateScriptFailures.includes(pkg));
+    if (!tolerable) throw new Error(`bun install failed — see ${logPath}`);
+    //* A failed lifecycle script makes bun skip linking the root `.bin`; a second pass without scripts links it.
+    envWarnings.push(`install script failed for ${failedScripts.join(", ")} — tolerated on ${this.platform}`);
+    const relink = await this.exec(
+      "bun install --frozen-lockfile --ignore-scripts",
+      this.#logPath(context, "install-relink"),
+      PlatformTestTarget.installIdleMs,
+    );
+    if (relink.exitCode !== 0) throw new Error(`bun install --ignore-scripts failed — see ${logPath}`);
+  }
+
+  #logPath(context: PlatformRunContext, name: string) {
+    return path.join(context.logDir, this.platform, `${name}.log`);
+  }
+
+  protected static async spawnText(command: string[], stdin?: string) {
+    const proc = Bun.spawn(command, {
+      stdin: stdin === undefined ? "ignore" : new Response(stdin),
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { stdout, stderr, exitCode };
+  }
+}

package/platformTest/TestSnapshot.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+import { TestSnapshot } from "./TestSnapshot";
+
+const makeRoot = tempDirs("akan-snapshot-");
+const git = async (cwd: string, ...args: string[]) => {
+  const proc = Bun.spawn(["git", ...args], {
+    cwd,
+    stdout: "ignore",
+    stderr: "ignore",
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: "t",
+      GIT_AUTHOR_EMAIL: "t@t",
+      GIT_COMMITTER_NAME: "t",
+      GIT_COMMITTER_EMAIL: "t@t",
+    },
+  });
+  expect(await proc.exited).toBe(0);
+};
+const write = async (root: string, file: string, content: string) => await writeText(path.join(root, file), content);
+const makeRepo = async () => {
+  const root = await makeRoot();
+  await git(root, "init", "-q");
+  await write(root, ".gitignore", "ignored/\nlocal/\n.env\n");
+  await write(root, "tracked.ts", "export {};\n");
+  await write(root, "gone.ts", "export {};\n");
+  await git(root, "add", ".");
+  await git(root, "commit", "-q", "-m", "init");
+  await unlink(path.join(root, "gone.ts"));
+  await write(root, "untracked.ts", "export const a = 1;\n");
+  await write(root, "ignored/secret.ts", "export {};\n");
+  await write(root, ".env", "OPENAI_API_KEY=nope\n");
+  return root;
+};
+const tarEntries = async (tarPath: string) => {
+  const proc = Bun.spawn(["tar", "-tf", tarPath], { stdout: "pipe" });
+  return (await new Response(proc.stdout).text()).split(/\r?\n/).filter(Boolean).sort();
+};
+
+describe("TestSnapshot", () => {
+  test("packs what git would show — tracked and untracked, never ignored or deleted", async () => {
+    const root = await makeRepo();
+    const snapshot = await TestSnapshot.create(root, path.join(root, "local", "run"));
+
+    expect(await tarEntries(snapshot.tarPath)).toEqual([".gitignore", "tracked.ts", "untracked.ts"]);
+    expect(snapshot.fileCount).toBe(3);
+  });
+
+  test("reports what changed underneath it", async () => {
+    const root = await makeRepo();
+    const snapshot = await TestSnapshot.create(root, path.join(root, "local", "run"));
+    await write(root, "tracked.ts", "export const changed = true;\n");
+    await write(root, "added.ts", "export {};\n");
+    await unlink(path.join(root, "untracked.ts"));
+
+    expect(await snapshot.drift()).toEqual({ changed: ["tracked.ts"], added: ["added.ts"], removed: ["untracked.ts"] });
+  });
+
+  test("refuses an env file git does not ignore instead of shipping it to a test host", async () => {
+    const root = await makeRepo();
+    await write(root, "apps/demo/env/env.server.local.ts", "export default {};\n");
+    await write(root, "apps/demo/env/env.server.example.ts", "export default {};\n");
+    await write(root, "templates/.env.template", "KEY=\n");
+
+    await expect(TestSnapshot.create(root, path.join(root, "local", "run"))).rejects.toThrow(
+      "apps/demo/env/env.server.local.ts",
+    );
+  });
+});

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))