@zaip-ai/cli 1.0.6 → 1.0.7

package/templates/.agents/skills/zaip-skill-refactor-existing-code/scripts/inventory-source.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { createHash, randomBytes } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, open, readdir, realpath, rename, rm } from "node:fs/promises";
+import path from "node:path";
+
+const ignoredNames = new Set([
+  ".git",
+  ".next",
+  ".turbo",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "target",
+  "vendor",
+]);
+
+function usage() {
+  console.error(
+    "Usage: node inventory-source.mjs <source-directory> [--include name[,name...]] [--output <path>]",
+  );
+  process.exit(2);
+}
+
+const input = process.argv[2];
+if (!input) usage();
+let outputPath;
+let includeArgument = "";
+for (let index = 3; index < process.argv.length; index += 2) {
+  const flag = process.argv[index];
+  const value = process.argv[index + 1];
+  if (value === undefined || (flag !== "--include" && flag !== "--output")) usage();
+  if (flag === "--include" && includeArgument !== "") usage();
+  if (flag === "--output" && outputPath !== undefined) usage();
+  if (flag === "--include") includeArgument = value;
+  else outputPath = path.resolve(value);
+}
+const includedNames = new Set(
+  includeArgument
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean),
+);
+for (const name of includedNames) {
+  if (!ignoredNames.has(name)) {
+    console.error(`inventory failed: --include only accepts default-ignored names (${name})`);
+    process.exit(2);
+  }
+}
+const sourceRoot = path.resolve(input);
+const ignored = [];
+
+async function walk(current, units) {
+  const entries = await readdir(current, { withFileTypes: true });
+  entries.sort((left, right) => left.name.localeCompare(right.name, "en"));
+  for (const entry of entries) {
+    const absolute = path.join(current, entry.name);
+    const relative = path.relative(sourceRoot, absolute).split(path.sep).join("/");
+    if (ignoredNames.has(entry.name) && !includedNames.has(entry.name)) {
+      ignored.push(relative);
+      units.push({ path: relative, kind: "ignored-directory", reason: "default-ignore" });
+      continue;
+    }
+    const stats = await lstat(absolute);
+    if (stats.isSymbolicLink()) {
+      units.push({ path: relative, kind: "symlink" });
+    } else if (stats.isDirectory()) {
+      await walk(absolute, units);
+    } else if (stats.isFile()) {
+      const inspected = await inspectFile(absolute);
+      units.push({
+        path: relative,
+        kind: "file",
+        bytes: stats.size,
+        extension: path.extname(entry.name).toLowerCase(),
+        sha256: inspected.sha256,
+        ...(inspected.binary ? { binary: true } : { lines: inspected.lines }),
+      });
+    }
+  }
+}
+
+try {
+  const stats = await lstat(sourceRoot);
+  if (!stats.isDirectory()) throw new Error("source must be a directory");
+  if (outputPath !== undefined) {
+    const canonicalSourceRoot = await realpath(sourceRoot);
+    const canonicalOutput = path.join(
+      await realpath(path.dirname(outputPath)),
+      path.basename(outputPath),
+    );
+    if (isWithin(canonicalSourceRoot, canonicalOutput)) {
+      throw new Error("--output must be outside source root");
+    }
+  }
+  const units = [];
+  await walk(sourceRoot, units);
+  const output = `${JSON.stringify(
+    {
+      schema_version: 1,
+      source_root: ".",
+      policy: {
+        default_ignored_names: [...ignoredNames].sort(),
+        included_names: [...includedNames].sort(),
+      },
+      ignored: ignored.sort((left, right) => left.localeCompare(right, "en")),
+      units,
+    },
+    null,
+    2,
+  )}\n`;
+  if (outputPath !== undefined) await writeAtomically(outputPath, output);
+  process.stdout.write(output);
+} catch (error) {
+  console.error(`inventory failed: ${error.message}`);
+  process.exit(1);
+}
+
+async function writeAtomically(destination, content) {
+  const directory = path.dirname(destination);
+  const basename = path.basename(destination);
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const temporary = path.join(directory, `.${basename}.${randomBytes(16).toString("hex")}.tmp`);
+    let handle;
+    try {
+      handle = await open(temporary, "wx");
+      await handle.writeFile(content, "utf8");
+      await handle.close();
+      await rename(temporary, destination);
+      return;
+    } catch (error) {
+      await handle?.close().catch(() => undefined);
+      await rm(temporary, { force: true }).catch(() => undefined);
+      if (error?.code === "EEXIST" && attempt < 7) continue;
+      throw error;
+    }
+  }
+  throw new Error("could not create an atomic inventory output file");
+}
+
+function isWithin(root, candidate) {
+  const normalizedRoot = normalizeForComparison(root);
+  const normalizedCandidate = normalizeForComparison(candidate);
+  const relative = path.relative(normalizedRoot, normalizedCandidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function normalizeForComparison(value) {
+  const normalized = path.normalize(value);
+  return process.platform === "win32" ? normalized.toLocaleLowerCase("en-US") : normalized;
+}
+
+async function inspectFile(absolute) {
+  const hash = createHash("sha256");
+  let binary = false;
+  let bytes = 0;
+  let newlines = 0;
+  let pendingCarriageReturn = false;
+  for await (const chunk of createReadStream(absolute)) {
+    hash.update(chunk);
+    bytes += chunk.length;
+    if (chunk.includes(0)) binary = true;
+    for (const byte of chunk) {
+      if (pendingCarriageReturn) {
+        newlines += 1;
+        pendingCarriageReturn = false;
+        if (byte === 10) continue;
+      }
+      if (byte === 13) pendingCarriageReturn = true;
+      else if (byte === 10) newlines += 1;
+    }
+  }
+  if (pendingCarriageReturn) newlines += 1;
+  return {
+    binary,
+    lines: bytes === 0 ? 0 : newlines + 1,
+    sha256: hash.digest("hex"),
+  };
+}

package/templates/.agents/skills/zaip-skill-refactor-existing-code/scripts/refactor-scripts.test.mjs

@@ -0,0 +1,293 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const skillRoot = path.resolve(import.meta.dirname, "..");
+const inventoryScript = path.join(skillRoot, "scripts", "inventory-source.mjs");
+const validateScript = path.join(skillRoot, "scripts", "validate-refactor-map.mjs");
+
+test("inventory is deterministic, hashed, and free of absolute source paths", async (context) => {
+  const fixture = await createFixture(context);
+  const first = await inventory(fixture.source);
+  const second = await inventory(fixture.source);
+
+  assert.deepEqual(first, second);
+  assert.equal(first.source_root, ".");
+  assert.deepEqual(first.ignored, ["node_modules"]);
+  assert.deepEqual(
+    first.units.map((unit) => unit.path),
+    ["node_modules", "ui/card.tsx", "ui/theme.ts"],
+  );
+  assert.ok(
+    first.units
+      .filter((unit) => unit.kind === "file")
+      .every((unit) => /^[a-f0-9]{64}$/.test(unit.sha256)),
+  );
+  assert.equal(JSON.stringify(first).includes(fixture.root), false);
+  assert.deepEqual(first.policy.included_names, []);
+});
+
+test("inventory writes the same UTF-8 JSON atomically when --output is supplied", async (context) => {
+  const fixture = await createFixture(context);
+  const output = path.join(fixture.root, "inventory.json");
+  const { stdout } = await execFileAsync(process.execPath, [
+    inventoryScript,
+    fixture.source,
+    "--output",
+    output,
+  ]);
+  assert.equal(await readFile(output, "utf8"), stdout);
+  assert.deepEqual(JSON.parse(stdout), await inventory(fixture.source));
+  assert.deepEqual(
+    (await readdir(fixture.root)).filter((name) => name.endsWith(".tmp")),
+    [],
+  );
+});
+
+test("inventory rejects output paths inside its source after supported path normalization", async (context) => {
+  const fixture = await createFixture(context);
+  const outputs = [path.join(fixture.source, "ui", "..", "inventory.json")];
+  if (process.platform === "win32") {
+    outputs.push(path.join(fixture.source.replace(/source$/i, "SOURCE"), "inventory.json"));
+  }
+  for (const output of outputs) {
+    const result = await runInventoryExpectingFailure(fixture.source, output);
+    assert.match(result.stderr, /--output must be outside source root/);
+  }
+});
+
+test("inventory rejects an output whose canonical parent resolves inside source", async (context) => {
+  const fixture = await createFixture(context);
+  const alias = path.join(fixture.root, "source-alias");
+  try {
+    await createDirectoryAlias(fixture.source, alias);
+  } catch (error) {
+    if (isTruePrivilegeError(error)) {
+      context.skip("directory links require an unavailable Windows privilege");
+      return;
+    }
+    throw error;
+  }
+
+  const result = await runInventoryExpectingFailure(
+    fixture.source,
+    path.join(alias, "inventory.json"),
+  );
+  assert.match(result.stderr, /--output must be outside source root/);
+});
+
+test("validator accepts a complete acyclic refactor map", async (context) => {
+  const fixture = await createFixture(context);
+  const sourceInventory = await inventory(fixture.source);
+  const mapPath = path.join(fixture.root, "valid-map.json");
+  await writeFile(
+    mapPath,
+    JSON.stringify({
+      schema_version: 1,
+      source_root: "legacy",
+      target_root: ".",
+      inventory: sourceInventory,
+      units: [
+        excludedDirectory("node_modules"),
+        decision("ui/theme.ts", "move", "apps/frontend/src/theme.ts"),
+        {
+          ...decision("ui/card.tsx", "adapt", "apps/frontend/src/card.tsx"),
+          ui: true,
+          visual_mode: "hybrid",
+          depends_on: ["ui/theme.ts"],
+        },
+      ],
+    }),
+  );
+
+  const { stdout } = await execFileAsync(process.execPath, [validateScript, mapPath]);
+  assert.deepEqual(JSON.parse(stdout), { valid: true, inventory_units: 3, decisions: 3 });
+});
+
+test("validator rejects traversal, dependency cycles, and Windows path collisions", async (context) => {
+  const fixture = await createFixture(context);
+  const sourceInventory = await inventory(fixture.source);
+  const mapPath = path.join(fixture.root, "invalid-map.json");
+  await writeFile(
+    mapPath,
+    JSON.stringify({
+      schema_version: 1,
+      source_root: "legacy",
+      target_root: ".",
+      inventory: sourceInventory,
+      units: [
+        excludedDirectory("node_modules"),
+        {
+          ...decision("ui/theme.ts", "move", "Apps/Frontend/src/shared.ts"),
+          depends_on: ["ui/card.tsx"],
+        },
+        {
+          ...decision("ui/card.tsx", "adapt", "apps/frontend/src/shared.ts"),
+          destinations: ["apps/frontend/src/shared.ts"],
+          depends_on: ["ui/theme.ts"],
+          rollback: "Restore the old import.",
+        },
+        {
+          ...decision("missing.ts", "move", "../escape.ts"),
+        },
+      ],
+    }),
+  );
+
+  const result = await runExpectingFailure(validateScript, mapPath);
+  assert.match(result.stderr, /dependency cycle/);
+  assert.match(result.stderr, /destination collision/);
+  assert.match(result.stderr, /cannot use destination and destinations together/);
+  assert.match(result.stderr, /invalid destination/);
+  assert.match(result.stderr, /decision source is absent from inventory/);
+
+  const unsafeRootMapPath = path.join(fixture.root, "unsafe-root-map.json");
+  await writeFile(
+    unsafeRootMapPath,
+    JSON.stringify({
+      schema_version: 1,
+      source_root: "../legacy",
+      target_root: "C:\\target",
+      inventory: {
+        ignored: [],
+        units: sourceInventory.units.filter((unit) => unit.path === "ui/theme.ts"),
+      },
+      units: [decision("ui/theme.ts", "move", "CON/file.ts")],
+    }),
+  );
+  const unsafeRootResult = await runExpectingFailure(validateScript, unsafeRootMapPath);
+  assert.match(unsafeRootResult.stderr, /source_root must be a safe relative path/);
+  assert.match(unsafeRootResult.stderr, /target_root must be a safe relative path/);
+  assert.match(unsafeRootResult.stderr, /invalid destination/);
+});
+
+test("validator rejects inventory-policy tampering and missing UI intent", async (context) => {
+  const fixture = await createFixture(context);
+  const sourceInventory = await inventory(fixture.source);
+  const tampered = structuredClone(sourceInventory);
+  tampered.ignored = [];
+  tampered.units = tampered.units.map((unit) =>
+    unit.path === "node_modules" ? { path: unit.path } : unit,
+  );
+  tampered.units.push({ path: "linked-source", kind: "symlink" });
+  const mapPath = path.join(fixture.root, "tampered-map.json");
+  await writeFile(
+    mapPath,
+    JSON.stringify({
+      schema_version: 1,
+      source_root: "legacy",
+      target_root: ".",
+      inventory: tampered,
+      units: [
+        decision("node_modules", "move", "packages/vendor"),
+        decision("linked-source", "move", "packages/linked-source"),
+        decision("ui/theme.ts", "move", "apps/frontend/src/theme.ts"),
+        {
+          ...decision("ui/card.tsx", "adapt", "apps/frontend/src/card.tsx"),
+          ui: true,
+        },
+      ],
+    }),
+  );
+
+  const result = await runExpectingFailure(validateScript, mapPath);
+  assert.match(result.stderr, /invalid kind/);
+  assert.match(result.stderr, /default-ignored path must remain an ignored-directory unit/);
+  assert.match(result.stderr, /visual_mode is required for UI units/);
+  assert.match(result.stderr, /symbolic link requires an exclude decision/);
+});
+
+test("SKILL.md map example satisfies the current validator", async (context) => {
+  const fixture = await createFixture(context);
+  const skill = await readFile(path.join(skillRoot, "SKILL.md"), "utf8");
+  const example = skill.match(/```json\r?\n([\s\S]*?)\r?\n```/);
+  assert.ok(example?.[1], "expected one JSON example in SKILL.md");
+  const mapPath = path.join(fixture.root, "skill-example.json");
+  await writeFile(mapPath, example[1]);
+  const { stdout } = await execFileAsync(process.execPath, [validateScript, mapPath]);
+  assert.equal(JSON.parse(stdout).valid, true);
+});
+
+function decision(source, action, destination) {
+  return {
+    source,
+    action,
+    destination,
+    rationale: "Preserve verified behavior in the target boundary.",
+    owner_task: "TASK-TEST-0001",
+    slice: "fixture",
+    ui: false,
+    depends_on: [],
+    gates: ["unit", "architecture"],
+    rollback: "Restore the old import.",
+  };
+}
+
+function excludedDirectory(source) {
+  return {
+    source,
+    action: "exclude",
+    rationale: "Dependency directory is outside product-code scope.",
+    owner_task: "TASK-TEST-0001",
+    slice: "inventory",
+    ui: false,
+    depends_on: [],
+    gates: ["inventory-review"],
+  };
+}
+
+async function createFixture(context) {
+  const root = await mkdtemp(path.join(os.tmpdir(), "zaip-refactor-skill-"));
+  context.after(() => rm(root, { recursive: true, force: true }));
+  const source = path.join(root, "source");
+  await mkdir(path.join(source, "ui"), { recursive: true });
+  await mkdir(path.join(source, "node_modules"), { recursive: true });
+  await writeFile(path.join(source, "ui", "card.tsx"), "export const Card = () => null;\n");
+  await writeFile(path.join(source, "ui", "theme.ts"), "export const radius = 8;\n");
+  await writeFile(path.join(source, "node_modules", "ignored.js"), "ignored\n");
+  return { root, source };
+}
+
+async function inventory(source) {
+  const { stdout } = await execFileAsync(process.execPath, [inventoryScript, source]);
+  return JSON.parse(stdout);
+}
+
+async function runExpectingFailure(script, argument) {
+  try {
+    await execFileAsync(process.execPath, [script, argument]);
+    assert.fail("expected command to fail");
+  } catch (error) {
+    assert.notEqual(error.code, 0);
+    return error;
+  }
+}
+
+async function runInventoryExpectingFailure(source, output) {
+  try {
+    await execFileAsync(process.execPath, [inventoryScript, source, "--output", output]);
+    assert.fail("expected inventory command to fail");
+  } catch (error) {
+    assert.notEqual(error.code, 0);
+    return error;
+  }
+}
+
+async function createDirectoryAlias(source, alias) {
+  if (process.platform === "win32") {
+    await symlink(source, alias, "junction");
+    return;
+  }
+  await symlink(source, alias, "dir");
+}
+
+function isTruePrivilegeError(error) {
+  if (process.platform !== "win32") return false;
+  const details = `${error?.message ?? ""}\n${error?.stderr ?? ""}`;
+  return error?.code === "EPERM" && /privilege is not held|1314/i.test(details);
+}