@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

package/src/stack/tests/run-tool.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { runTool } from "../run-tool.ts";
+import type { ToolSpec, ToolResult, ToolExecutor } from "../run-tool.ts";
+
+function recordingExecutor(
+  calls: ToolSpec[],
+  result: ToolResult = { success: true, stdout: "ok" },
+): ToolExecutor {
+  return (spec) => {
+    calls.push(spec);
+    return result;
+  };
+}
+
+describe("runTool", () => {
+  let cwd: string;
+
+  beforeEach(async () => {
+    cwd = await mkdtemp(join(tmpdir(), "run-tool-"));
+  });
+
+  afterEach(async () => {
+    await rm(cwd, { recursive: true, force: true });
+  });
+
+  it("passes the spec to the executor and returns its result", () => {
+    const calls: ToolSpec[] = [];
+    const result = runTool(
+      { bin: "npx", args: ["vite", "build"], cwd, timeoutMs: 5_000 },
+      recordingExecutor(calls),
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.stdout).toBe("ok");
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.bin).toBe("npx");
+    expect(calls[0]!.args).toEqual(["vite", "build"]);
+    expect(calls[0]!.cwd).toBe(cwd);
+    expect(calls[0]!.timeoutMs).toBe(5_000);
+  });
+
+  it("fails preflight when requireDist and dist/ is missing", () => {
+    const calls: ToolSpec[] = [];
+    const result = runTool(
+      { bin: "npx", args: ["deploy"], cwd, requireDist: true },
+      recordingExecutor(calls),
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.failedAt).toBe("preflight");
+    expect(result.errors?.[0]).toContain("dist/ directory not found");
+    expect(calls).toHaveLength(0);
+  });
+
+  it("passes preflight when requireDist and dist/ exists", async () => {
+    await mkdir(join(cwd, "dist"), { recursive: true });
+    const calls: ToolSpec[] = [];
+    const result = runTool(
+      { bin: "npx", args: ["deploy"], cwd, requireDist: true },
+      recordingExecutor(calls),
+    );
+
+    expect(result.success).toBe(true);
+    expect(calls).toHaveLength(1);
+  });
+
+  it("fails preflight when a required env var is missing", () => {
+    const calls: ToolSpec[] = [];
+    const result = runTool(
+      { bin: "npx", args: ["x"], cwd, requireEnv: ["DEFINITELY_MISSING_ENV_VAR"] },
+      recordingExecutor(calls),
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.failedAt).toBe("preflight");
+    expect(result.errors?.[0]).toContain("DEFINITELY_MISSING_ENV_VAR");
+    expect(calls).toHaveLength(0);
+  });
+
+  it("passes preflight when a required env var comes from spec.env", () => {
+    const calls: ToolSpec[] = [];
+    const result = runTool(
+      {
+        bin: "npx",
+        args: ["x"],
+        cwd,
+        env: { MY_TOKEN: "secret" },
+        requireEnv: ["MY_TOKEN"],
+      },
+      recordingExecutor(calls),
+    );
+
+    expect(result.success).toBe(true);
+    expect(calls[0]!.env?.MY_TOKEN).toBe("secret");
+  });
+
+  it("fails preflight when a required env var is empty after merge", () => {
+    const calls: ToolSpec[] = [];
+    const result = runTool(
+      {
+        bin: "npx",
+        args: ["x"],
+        cwd,
+        env: { EMPTY_TOKEN: "" },
+        requireEnv: ["EMPTY_TOKEN"],
+      },
+      recordingExecutor(calls),
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.failedAt).toBe("preflight");
+  });
+
+  it("maps an executor throw to an exec failure", () => {
+    const throwing: ToolExecutor = () => {
+      throw new Error("spawn npx ENOENT");
+    };
+    const result = runTool({ bin: "npx", args: ["x"], cwd }, throwing);
+
+    expect(result.success).toBe(false);
+    expect(result.failedAt).toBe("exec");
+    expect(result.errors?.[0]).toContain("spawn npx ENOENT");
+  });
+
+  it("propagates executor failure results unchanged", () => {
+    const calls: ToolSpec[] = [];
+    const result = runTool(
+      { bin: "npx", args: ["x"], cwd },
+      recordingExecutor(calls, { success: false, errors: ["exit 1"], failedAt: "exec" }),
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.errors).toEqual(["exit 1"]);
+  });
+});

package/src/stack/tests/stack-checks.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from "vitest";
+import { defineStackChecks } from "../stack-checks.ts";
+import type { StackCheckData, StackCheckSpec, StackCheckViolation } from "../stack-checks.ts";
+import type { PluginHookContext } from "../../plugin/plugin-contract.ts";
+import type {
+  KernelCommandInput,
+  KernelCommandResult,
+  KernelRuntimeContext,
+} from "@warpgogol/werkstatt-shared/kernel";
+
+const PASS_SPEC: StackCheckSpec = {
+  name: "stack.alpha.validate",
+  description: "alpha check",
+  contract: "stack",
+  rules: ["STACK-01"],
+  reads: ["src/**"],
+  check: async () => [],
+};
+
+const FAIL_VIOLATION: StackCheckViolation = {
+  ruleId: "STACK-02",
+  file: "src/bad.ts",
+  message: "bad thing",
+};
+
+const FAIL_SPEC: StackCheckSpec = {
+  name: "stack.beta.validate",
+  description: "beta check",
+  contract: "stack",
+  rules: ["STACK-02"],
+  reads: ["src/**"],
+  check: async () => [FAIL_VIOLATION],
+};
+
+function makeCtx(projectRoot: string): PluginHookContext {
+  return {
+    workspaceRoot: projectRoot,
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+  } as unknown as PluginHookContext;
+}
+
+function makeRuntimeContext(projectRoot: string): KernelRuntimeContext {
+  return { workspaceRoot: projectRoot } as unknown as KernelRuntimeContext;
+}
+
+const INPUT: KernelCommandInput = { argv: [], flags: {} };
+
+describe("defineStackChecks", () => {
+  it("emits one command per spec with metadata from the spec", () => {
+    const { commands } = defineStackChecks([PASS_SPEC, FAIL_SPEC]);
+
+    expect(commands).toHaveLength(2);
+    expect(commands[0]!.name).toBe("stack.alpha.validate");
+    expect(commands[0]!.description).toBe("alpha check");
+    expect(commands[0]!.contract).toBe("stack");
+    expect(commands[0]!.rules).toEqual(["STACK-01"]);
+    expect(commands[0]!.reads).toEqual(["src/**"]);
+    expect(commands[0]!.scope).toBe("workspace");
+    expect(commands[0]!.cacheable).toBe(false);
+  });
+
+  it("command execute returns the uniform pass envelope", async () => {
+    const { commands } = defineStackChecks([PASS_SPEC]);
+    const result = (await commands[0]!.execute(
+      INPUT,
+      makeRuntimeContext("/tmp/x"),
+    )) as KernelCommandResult<StackCheckData>;
+
+    expect(result?.exitCode).toBe(0);
+    expect(result?.data?.command).toBe("stack.alpha.validate");
+    expect(result?.data?.status).toBe("pass");
+    expect(result?.data?.violations).toEqual([]);
+    expect(result?.summary).toContain("stack.alpha.validate");
+    expect(result?.summary).toContain("pass");
+  });
+
+  it("command execute returns the uniform fail envelope with violations", async () => {
+    const { commands } = defineStackChecks([FAIL_SPEC]);
+    const result = (await commands[0]!.execute(
+      INPUT,
+      makeRuntimeContext("/tmp/x"),
+    )) as KernelCommandResult<StackCheckData>;
+
+    expect(result?.exitCode).toBe(1);
+    expect(result?.data?.status).toBe("fail");
+    expect(result?.data?.violations).toEqual([FAIL_VIOLATION]);
+    expect(result?.summary).toContain("1 violations");
+  });
+
+  it("runCheckGate succeeds when all checks pass", async () => {
+    const { runCheckGate } = defineStackChecks([PASS_SPEC]);
+    const result = await runCheckGate(makeCtx("/tmp/x"));
+
+    expect(result.success).toBe(true);
+    expect(result.errors).toBeUndefined();
+  });
+
+  it("runCheckGate aggregates failures across specs", async () => {
+    const { runCheckGate } = defineStackChecks([PASS_SPEC, FAIL_SPEC]);
+    const result = await runCheckGate(makeCtx("/tmp/x"));
+
+    expect(result.success).toBe(false);
+    expect(result.errors).toEqual(["stack.beta.validate: 1 violations"]);
+  });
+
+  it("runCheckGate prefers workpiecePath over workspaceRoot", async () => {
+    let seen = "";
+    const spec: StackCheckSpec = {
+      ...PASS_SPEC,
+      check: async (root) => {
+        seen = root;
+        return [];
+      },
+    };
+    const { runCheckGate } = defineStackChecks([spec]);
+    const ctx = {
+      ...makeCtx("/workspace"),
+      workpiecePath: "/workpiece",
+    };
+    await runCheckGate(ctx);
+
+    expect(seen).toBe("/workpiece");
+  });
+
+  it("derives invariantRows from rules[0] by default", () => {
+    const { invariantRows } = defineStackChecks([PASS_SPEC, FAIL_SPEC]);
+
+    expect(invariantRows).toEqual([
+      { id: "STACK-01", command: "stack.alpha.validate" },
+      { id: "STACK-02", command: "stack.beta.validate" },
+    ]);
+  });
+
+  it("honours explicit invariantId and skips rule-less specs", () => {
+    const custom: StackCheckSpec = { ...PASS_SPEC, invariantId: "STACK-CUSTOM" };
+    const ruleless: StackCheckSpec = { ...FAIL_SPEC, rules: [] };
+    const { invariantRows } = defineStackChecks([custom, ruleless]);
+
+    expect(invariantRows).toEqual([{ id: "STACK-CUSTOM", command: "stack.alpha.validate" }]);
+  });
+});

package/src/stack/tests/walk-files.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  walkFiles,
+  readTextFile,
+  readTextFiles,
+  readBinaryFiles,
+} from "../walk-files.ts";
+
+describe("walkFiles", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "walk-files-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("returns relative paths with forward slashes, recursively by default", async () => {
+    await mkdir(join(root, "a", "b"), { recursive: true });
+    await writeFile(join(root, "top.ts"), "");
+    await writeFile(join(root, "a", "mid.ts"), "");
+    await writeFile(join(root, "a", "b", "deep.ts"), "");
+
+    const files = await walkFiles(root);
+
+    expect(files.sort()).toEqual(["a/b/deep.ts", "a/mid.ts", "top.ts"]);
+  });
+
+  it("returns only top-level files when recursive is false", async () => {
+    await mkdir(join(root, "sub"), { recursive: true });
+    await writeFile(join(root, "top.ts"), "");
+    await writeFile(join(root, "sub", "nested.ts"), "");
+
+    const files = await walkFiles(root, { recursive: false });
+
+    expect(files).toEqual(["top.ts"]);
+  });
+
+  it("applies the filter to relative paths", async () => {
+    await mkdir(join(root, "sub"), { recursive: true });
+    await writeFile(join(root, "keep.ts"), "");
+    await writeFile(join(root, "skip.js"), "");
+    await writeFile(join(root, "sub", "keep.ts"), "");
+
+    const files = await walkFiles(root, { filter: (rel) => rel.endsWith(".ts") });
+
+    expect(files.sort()).toEqual(["keep.ts", "sub/keep.ts"]);
+  });
+
+  it("returns an empty array for a missing directory", async () => {
+    expect(await walkFiles(join(root, "nope"))).toEqual([]);
+  });
+
+  it("skips non-file entries", async () => {
+    await mkdir(join(root, "dir-only"), { recursive: true });
+    await writeFile(join(root, "file.ts"), "");
+
+    const files = await walkFiles(root);
+
+    expect(files).toEqual(["file.ts"]);
+  });
+});
+
+describe("readTextFile", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "walk-read-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("reads utf-8 content", async () => {
+    await writeFile(join(root, "a.txt"), "hello ünïcode");
+
+    expect(await readTextFile(join(root, "a.txt"))).toBe("hello ünïcode");
+  });
+
+  it("returns null for a missing file", async () => {
+    expect(await readTextFile(join(root, "missing.txt"))).toBeNull();
+  });
+});
+
+describe("readTextFiles / readBinaryFiles", () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "walk-reads-"));
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("reads multiple files keyed by relative path", async () => {
+    await mkdir(join(root, "sub"), { recursive: true });
+    await writeFile(join(root, "a.ts"), "aaa");
+    await writeFile(join(root, "sub", "b.ts"), "bbb");
+
+    const contents = await readTextFiles(root, ["a.ts", "sub/b.ts"]);
+
+    expect(contents.get("a.ts")).toBe("aaa");
+    expect(contents.get("sub/b.ts")).toBe("bbb");
+    expect(contents.size).toBe(2);
+  });
+
+  it("omits unreadable entries", async () => {
+    await writeFile(join(root, "a.ts"), "aaa");
+
+    const contents = await readTextFiles(root, ["a.ts", "missing.ts"]);
+
+    expect(contents.size).toBe(1);
+    expect(contents.has("missing.ts")).toBe(false);
+  });
+
+  it("reads binary content without utf-8 corruption", async () => {
+    const bytes = Buffer.from([0x00, 0xff, 0xfe, 0x42]);
+    await writeFile(join(root, "bin.dat"), bytes);
+
+    const contents = await readBinaryFiles(root, ["bin.dat"]);
+
+    expect(contents.get("bin.dat")).toEqual(bytes);
+  });
+});

package/src/stack/walk-files.ts

@@ -0,0 +1,114 @@
+/*
+<MODULE_CONTRACT>
+<purpose>walkFiles — the single file-discovery and file-reading seam for stack plugins
+(RFC-1100). Returns workspace-relative paths with forward slashes and reads file
+contents in bulk, so validators never import node:fs directly.</purpose>
+
+<non-goals>
+  <item>Does not write files — writes flow through writeFileIfChanged / WorkspaceIO.</item>
+  <item>Does not apply implicit ignore rules (no dotfile or prefix skipping) — callers scope by directory and filter.</item>
+  <item>Does not run in the browser — server-only (Node fs/promises).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1100: initial shared walker — walkFiles plus readTextFile/readTextFiles/readBinaryFiles companions; replaces per-validator private readdir walkers in stack plugins.</item>
+  <item>RFC-1100: step 1 — shared tool/fs/check seams (walkFiles, runTool, defineStackChecks)</item>
+</CHANGE_SUMMARY>
+*/
+
+// Server-only. Do not import from browser/client scripts.
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface WalkFilesOptions {
+  /** Recurse into subdirectories. Default true. */
+  recursive?: boolean;
+  /** Return true to include a file by its directory-relative path (forward slashes). */
+  filter?: (relPath: string) => boolean;
+}
+
+/**
+ * Lists files under `dir` as relative paths with forward slashes.
+ * Missing or unreadable directories yield an empty array.
+ */
+export async function walkFiles(
+  dir: string,
+  options: WalkFilesOptions = {},
+): Promise<string[]> {
+  const { recursive = true, filter } = options;
+  const results: string[] = [];
+
+  async function walk(current: string, relPrefix: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (recursive) {
+          await walk(join(current, entry.name), relPath);
+        }
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (filter && !filter(relPath)) continue;
+      results.push(relPath);
+    }
+  }
+
+  await walk(dir, "");
+  return results;
+}
+
+/**
+ * Reads a single file as utf-8. Returns null when the file is missing or unreadable.
+ */
+export async function readTextFile(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads multiple files under `dir` as utf-8, keyed by their walkFiles-relative path.
+ * Unreadable entries are omitted from the result.
+ */
+export async function readTextFiles(
+  dir: string,
+  relPaths: string[],
+): Promise<Map<string, string>> {
+  const contents = new Map<string, string>();
+  for (const relPath of relPaths) {
+    const content = await readTextFile(join(dir, relPath));
+    if (content !== null) {
+      contents.set(relPath, content);
+    }
+  }
+  return contents;
+}
+
+/**
+ * Reads multiple files under `dir` as raw buffers, keyed by their walkFiles-relative
+ * path. Use for byte-accurate work (hashing, gzip measurement) where utf-8 decoding
+ * would corrupt binary content. Unreadable entries are omitted from the result.
+ */
+export async function readBinaryFiles(
+  dir: string,
+  relPaths: string[],
+): Promise<Map<string, Buffer>> {
+  const contents = new Map<string, Buffer>();
+  for (const relPath of relPaths) {
+    try {
+      contents.set(relPath, await readFile(join(dir, relPath)));
+    } catch {
+      // Skip unreadable files — same tolerance as the walkers this replaces.
+    }
+  }
+  return contents;
+}