@warpgogol/werkstatt-shared 0.14.1 → 0.16.0

package/src/kernel/tests/drift-guard.test.ts

@@ -0,0 +1,112 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { guardTrackedOverwrite } from "../drift-guard.ts";
+
+describe("guardTrackedOverwrite (RFC-1126)", () => {
+  let dir: string;
+  const logger = { warn: vi.fn() };
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "drift-guard-"));
+    logger.warn.mockClear();
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("reports nothing to lose when the file does not exist", async () => {
+    const report = await guardTrackedOverwrite(
+      join(dir, "missing.json"),
+      "{}",
+      { format: "json" },
+      logger,
+    );
+    expect(report.wouldLose).toEqual([]);
+    expect(report.identical).toBe(false);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("reports identical when content matches", async () => {
+    const file = join(dir, "same.json");
+    writeFileSync(file, '{"a":1}\n');
+    const report = await guardTrackedOverwrite(file, '{"a":1}\n', { format: "json" }, logger);
+    expect(report.identical).toBe(true);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("warns with the lost key path for JSON drift", async () => {
+    const file = join(dir, "package.json");
+    writeFileSync(file, JSON.stringify({ dependencies: { "extra-dep": "^1.0.0" } }));
+    const report = await guardTrackedOverwrite(
+      file,
+      JSON.stringify({ dependencies: {} }),
+      { format: "json", fixHint: "edit the manifest" },
+      logger,
+    );
+    expect(report.wouldLose).toContain("dependencies.extra-dep");
+    expect(logger.warn).toHaveBeenCalledOnce();
+    expect(logger.warn.mock.calls[0]![0]).toContain("DRIFT-GUARD-01");
+    expect(logger.warn.mock.calls[0]![0]).toContain("dependencies.extra-dep");
+    expect(logger.warn.mock.calls[0]![0]).toContain("edit the manifest");
+  });
+
+  it("detects changed scalar values as lost edits", async () => {
+    const file = join(dir, "cfg.json");
+    writeFileSync(file, JSON.stringify({ version: "2.0.0" }));
+    const report = await guardTrackedOverwrite(
+      file,
+      JSON.stringify({ version: "1.0.0" }),
+      { format: "json" },
+      logger,
+    );
+    expect(report.wouldLose).toContain("version");
+  });
+
+  it("warns for YAML drift", async () => {
+    const file = join(dir, "config.yaml");
+    writeFileSync(file, "keep: yes\ndrop: gone\n");
+    const report = await guardTrackedOverwrite(file, "keep: yes\n", { format: "yaml" }, logger);
+    expect(report.wouldLose).toContain("drop");
+    expect(logger.warn).toHaveBeenCalledOnce();
+  });
+
+  it("warns for text drift listing removed lines", async () => {
+    const file = join(dir, "list.txt");
+    writeFileSync(file, "alpha\nbeta\ngamma\n");
+    const report = await guardTrackedOverwrite(file, "alpha\n", { format: "text" }, logger);
+    expect(report.wouldLose).toEqual(expect.arrayContaining(["beta", "gamma"]));
+  });
+
+  it("does not warn when new content only adds keys", async () => {
+    const file = join(dir, "grow.json");
+    writeFileSync(file, JSON.stringify({ a: 1 }));
+    const report = await guardTrackedOverwrite(
+      file,
+      JSON.stringify({ a: 1, b: 2 }),
+      { format: "json" },
+      logger,
+    );
+    expect(report.wouldLose).toEqual([]);
+    expect(report.identical).toBe(false);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("throws under strict instead of warning", async () => {
+    const file = join(dir, "strict.json");
+    writeFileSync(file, JSON.stringify({ manual: true }));
+    await expect(
+      guardTrackedOverwrite(file, "{}", { format: "json", strict: true }, logger),
+    ).rejects.toThrow("DRIFT-GUARD-01");
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("falls back to line diff when existing JSON is unparseable", async () => {
+    const file = join(dir, "broken.json");
+    writeFileSync(file, "{ not json, custom-line\n");
+    const report = await guardTrackedOverwrite(file, "{}", { format: "json" }, logger);
+    expect(report.wouldLose.length).toBeGreaterThan(0);
+  });
+});

package/src/kernel/tests/fs-atomic.test.ts

@@ -0,0 +1,150 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>
+    RFC-0258 unit tests for writeFileAtomic, written before the workspace-shared
+    writer migration per the RFC's own rollout order.
+  </purpose>
+  <responsibilities>
+    <item>Content lands intact after a single write.</item>
+    <item>A reader polling the target during many sequential writes never observes a partial file.</item>
+    <item>The temp file is removed when the write ultimately fails.</item>
+    <item>A simulated Windows EPERM on the first rename attempt is retried and succeeds.</item>
+  </responsibilities>
+  <non-goals>
+    <item>Do not cover the workspace-write-boundary lint here — see workspace-write-boundary.test.ts in site-kernel-checks.</item>
+  </non-goals>
+</MODULE_CONTRACT>
+*/
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { test, expect } from "vitest";
+import { writeFileAtomic, __setRenameImplForTests } from "../fs-atomic.ts";
+
+async function makeTmpDir(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), "fs-atomic-"));
+}
+
+test("writeFileAtomic: content lands intact", async () => {
+  const dir = await makeTmpDir();
+  try {
+    const target = path.join(dir, "out.json");
+    const content = JSON.stringify({ hello: "world", n: 42 }, null, 2);
+    await writeFileAtomic(target, content);
+    const read = await fs.readFile(target, "utf8");
+    expect(read).toBe(content);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeFileAtomic: no leftover temp files after a successful write", async () => {
+  const dir = await makeTmpDir();
+  try {
+    const target = path.join(dir, "out.json");
+    await writeFileAtomic(target, "content");
+    const entries = await fs.readdir(dir);
+    expect(entries).toEqual(["out.json"]);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeFileAtomic: a reader polling the target during 200 sequential writes never observes a partial file", async () => {
+  const dir = await makeTmpDir();
+  try {
+    const target = path.join(dir, "shared.json");
+    const totalWrites = 200;
+    let stop = false;
+    let observedPartial = false;
+    let observedCount = 0;
+
+    // Each write produces a distinct, fully-valid JSON payload of a known shape.
+    function payloadFor(i: number): string {
+      return JSON.stringify({ seq: i, marker: "X".repeat(32) }) + "\n";
+    }
+
+    const writer = (async () => {
+      for (let i = 0; i < totalWrites; i++) {
+        // A polling reader sharing the event loop can still collide with the
+        // rename often enough to exceed the production default's 5-retry
+        // budget on Windows. Widen the retry budget for this synthetic
+        // worst-case poll loop only; the production default stays 5 (RFC-0258).
+        await writeFileAtomic(target, payloadFor(i), { retries: 80 });
+      }
+      stop = true;
+    })();
+
+    const reader = (async () => {
+      while (!stop) {
+        let raw: string | undefined;
+        try {
+          raw = await fs.readFile(target, "utf8");
+        } catch {
+          // Target may not exist yet at the very start — not a partial-read failure.
+          await new Promise((resolve) => setImmediate(resolve));
+          continue;
+        }
+        observedCount += 1;
+        try {
+          const parsed = JSON.parse(raw) as { seq: number; marker: string };
+          if (parsed.marker !== "X".repeat(32)) {
+            observedPartial = true;
+          }
+        } catch {
+          observedPartial = true;
+        }
+        // Yield once per read so this is a fast, realistic poller rather than
+        // a worst-case tight spin that starves the writer's rename retries.
+        await new Promise((resolve) => setImmediate(resolve));
+      }
+    })();
+
+    await Promise.all([writer, reader]);
+
+    expect(observedPartial).toBe(false);
+    expect(observedCount > 0).toBeTruthy();
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeFileAtomic: temp file is removed when the write ultimately fails", async () => {
+  const dir = await makeTmpDir();
+  try {
+    // Target directory does not exist -> the temp-file write itself fails,
+    // and no temp file should remain in `dir`.
+    const target = path.join(dir, "missing-subdir", "out.json");
+    await expect(() => writeFileAtomic(target, "content")).rejects.toThrow();
+    const entries = await fs.readdir(dir);
+    expect(entries).toEqual([]);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("writeFileAtomic: simulated EPERM on first rename attempt is retried and succeeds", async () => {
+  const dir = await makeTmpDir();
+  try {
+    const target = path.join(dir, "out.json");
+    let calls = 0;
+    __setRenameImplForTests(async (...args: Parameters<typeof fs.rename>) => {
+      calls += 1;
+      if (calls === 1) {
+        const error = new Error("simulated EPERM") as NodeJS.ErrnoException;
+        error.code = "EPERM";
+        throw error;
+      }
+      return fs.rename(...args);
+    });
+
+    await writeFileAtomic(target, "content", { retries: 5 });
+    expect(calls >= 2).toBeTruthy();
+    const read = await fs.readFile(target, "utf8");
+    expect(read).toBe("content");
+  } finally {
+    __setRenameImplForTests(undefined);
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+});

package/src/kernel/tests/workpiece-env.test.ts

@@ -0,0 +1,44 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { EMPTY_WORKPIECE_ENV, loadWorkpieceEnv } from "../workpiece-env.ts";
+
+describe("loadWorkpieceEnv (RFC-1126)", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "workpiece-env-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("returns the shared empty map when siteDirectory is undefined", async () => {
+    expect(await loadWorkpieceEnv(undefined)).toBe(EMPTY_WORKPIECE_ENV);
+  });
+
+  it("returns an empty map when .env is missing", async () => {
+    const env = await loadWorkpieceEnv(dir);
+    expect(env.size).toBe(0);
+  });
+
+  it("parses KEY=VALUE pairs including quoted values", async () => {
+    writeFileSync(
+      join(dir, ".env"),
+      'PUBLIC_IMAGE_PROVIDER=build-portable\nQUOTED="with space"\n# comment\n\n',
+    );
+    const env = await loadWorkpieceEnv(dir);
+    expect(env.get("PUBLIC_IMAGE_PROVIDER")).toBe("build-portable");
+    expect(env.get("QUOTED")).toBe("with space");
+    expect(env.has("# comment")).toBe(false);
+  });
+
+  it("does not mutate process.env", async () => {
+    writeFileSync(join(dir, ".env"), "WORKPIECE_ONLY_KEY=from-file\n");
+    delete process.env["WORKPIECE_ONLY_KEY"];
+    await loadWorkpieceEnv(dir);
+    expect(process.env["WORKPIECE_ONLY_KEY"]).toBeUndefined();
+  });
+});

package/src/kernel/tests/workspace-io.test.ts

@@ -0,0 +1,187 @@
+import { test, expect } from "vitest";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createDefaultIO,
+  createRecordingIO,
+  createReadOnlyIO,
+  KernelMetaError,
+} from "../workspace-io.ts";
+
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0267: port + adapter tests, written before wiring into the executor.
+  Recording adapter captures intents and never touches disk (fs spy via a
+  real temp directory). Read-only adapter throws KERNEL-META-01 naming the
+  command and path on any mutation. Default adapter writes atomically
+  (delegates to writeFileAtomic, rfc-0258 — proven by "no partial content"
+  and "no leftover temp file" after a successful write).
+</purpose>
+</MODULE_CONTRACT>
+*/
+
+test("createDefaultIO: writeFile creates the file with exact content, no leftover temp file", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-default-"));
+  try {
+    const { io } = createDefaultIO();
+    const target = join(root, "nested", "file.txt");
+    await io.writeFile(target, "hello world");
+
+    const content = await readFile(target, "utf8");
+    expect(content).toBe("hello world");
+
+    const entries = await import("node:fs/promises").then((fs) => fs.readdir(join(root, "nested")));
+    expect(entries).toEqual(["file.txt"]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createDefaultIO: exists/readFile/mkdir/rm round-trip", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-default2-"));
+  try {
+    const { io } = createDefaultIO();
+    expect(await io.exists(join(root, "missing.txt"))).toBe(false);
+
+    await io.mkdir(join(root, "dir"));
+    expect(await io.exists(join(root, "dir"))).toBe(true);
+
+    await io.writeFile(join(root, "dir", "a.txt"), "a");
+    expect(await io.readFile(join(root, "dir", "a.txt"))).toBe("a");
+
+    await io.rm(join(root, "dir"), { recursive: true });
+    expect(await io.exists(join(root, "dir"))).toBe(false);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createDefaultIO: readdir returns port-neutral DirEntry[] with isFile/isDirectory booleans", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-readdir-"));
+  try {
+    const { io } = createDefaultIO();
+    await io.writeFile(join(root, "a.md"), "content");
+    await io.mkdir(join(root, "subdir"));
+
+    const entries = (await io.readdir(root)).sort((x, y) => x.name.localeCompare(y.name));
+    expect(entries).toEqual([
+      { name: "a.md", isFile: true, isDirectory: false },
+      { name: "subdir", isFile: false, isDirectory: true },
+    ]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createReadOnlyIO and createRecordingIO: readdir passes through (a read, not a mutation)", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-readdir-passthrough-"));
+  try {
+    const { io: base } = createDefaultIO();
+    await base.writeFile(join(root, "x.txt"), "x");
+
+    const readOnly = createReadOnlyIO(base, "fixture.readonly.command");
+    expect((await readOnly.readdir(root))[0]?.name).toBe("x.txt");
+
+    const { io: recording } = createRecordingIO(base);
+    expect((await recording.readdir(root))[0]?.name).toBe("x.txt");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createRecordingIO: captures write/mkdir/rm intents and never touches disk", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-recording-"));
+  try {
+    const { io: base } = createDefaultIO();
+    const { io, intents } = createRecordingIO(base);
+
+    const target = join(root, "would-write.txt");
+    await io.writeFile(target, "some content");
+    await io.mkdir(join(root, "would-mkdir"));
+    await io.rm(join(root, "would-rm"));
+
+    expect(intents.length).toBe(3);
+    expect(intents.map((i) => i.kind)).toEqual(["write", "mkdir", "rm"]);
+    expect(intents[0]?.path).toBe(target);
+    expect(intents[0]?.bytes).toBe(Buffer.byteLength("some content", "utf8"));
+
+    // Nothing was actually written.
+    await expect(() => stat(target)).rejects.toThrow();
+    const rootEntries = await import("node:fs/promises").then((fs) => fs.readdir(root));
+    expect(rootEntries).toEqual([]);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createRecordingIO: reads pass through to the base adapter", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-recording-reads-"));
+  try {
+    const { io: base } = createDefaultIO();
+    await base.writeFile(join(root, "existing.txt"), "real content");
+
+    const { io } = createRecordingIO(base);
+    expect(await io.exists(join(root, "existing.txt"))).toBe(true);
+    expect(await io.readFile(join(root, "existing.txt"))).toBe("real content");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("createReadOnlyIO: throws KERNEL-META-01 naming the command and path on writeFile", async () => {
+  const io = createReadOnlyIO(createDefaultIO().io, "fixture.readonly.command");
+  try {
+    await io.writeFile("/tmp/should-not-write.txt", "x");
+    expect.fail("should have thrown");
+  } catch (error) {
+    expect(error).toBeInstanceOf(KernelMetaError);
+    expect((error as Error).message).toMatch(/KERNEL-META-01/);
+    expect((error as Error).message).toMatch(/fixture\.readonly\.command/);
+    expect((error as Error).message).toMatch(/should-not-write\.txt/);
+  }
+});
+
+test("createReadOnlyIO: throws on mkdir, rm, and exec too", async () => {
+  const io = createReadOnlyIO(createDefaultIO().io, "fixture.readonly.command");
+  await expect(() => io.mkdir("/tmp/nope")).rejects.toThrow(KernelMetaError);
+  await expect(() => io.rm("/tmp/nope")).rejects.toThrow(KernelMetaError);
+  await expect(() => io.exec("rm", ["-rf", "/tmp/nope"])).rejects.toThrow(KernelMetaError);
+});
+
+test("createReadOnlyIO: reads still work", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-readonly-reads-"));
+  try {
+    const { io: base } = createDefaultIO();
+    await base.writeFile(join(root, "readable.txt"), "readable content");
+
+    const io = createReadOnlyIO(base, "fixture.readonly.command");
+    expect(await io.exists(join(root, "readable.txt"))).toBe(true);
+    expect(await io.readFile(join(root, "readable.txt"))).toBe("readable content");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+// RFC-0326: createDefaultIO now returns { io, intents } — the intents array
+// captures every mutation (write/mkdir/rm) for filesModified reporting.
+test("createDefaultIO: captures write/mkdir/rm intents while writing to real disk (RFC-0326)", async () => {
+  const root = await mkdtemp(join(tmpdir(), "workspace-io-default-intents-"));
+  try {
+    const { io, intents } = createDefaultIO();
+
+    await io.writeFile(join(root, "file.txt"), "content");
+    await io.mkdir(join(root, "subdir"));
+    await io.rm(join(root, "subdir"), { recursive: true });
+
+    expect(intents.length).toBe(3);
+    expect(intents.map((i) => i.kind)).toEqual(["write", "mkdir", "rm"]);
+    expect(intents[0]?.bytes).toBe(Buffer.byteLength("content", "utf8"));
+
+    // File was actually written to disk (this is the real adapter, not recording).
+    expect(await io.readFile(join(root, "file.txt"))).toBe("content");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});