ai-delivery-workflow 0.2.2 → 0.4.0

package/bin/release-check.mjs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { normalizeNpmPackageResult } from "../lib/npm-package-result.mjs";
+
+function parseArguments(argv) {
+  const phase = argv.shift();
+  if (!new Set(["prepare", "verify"]).has(phase)) {
+    throw new Error("usage: release-check.mjs <prepare|verify> [--root path] [--version x.y.z] [--commit sha] [--scope local|full]");
+  }
+  const values = { phase, root: process.cwd(), version: null, commit: null, scope: "full" };
+  while (argv.length) {
+    const key = argv.shift();
+    if (!new Set(["--root", "--version", "--commit", "--scope"]).has(key)) {
+      throw new Error(`unknown option: ${key}`);
+    }
+    const value = argv.shift();
+    if (!value || value.startsWith("--")) throw new Error(`missing value for ${key}`);
+    values[key.slice(2)] = value;
+  }
+  if (!new Set(["local", "full"]).has(values.scope)) throw new Error("--scope must be local or full");
+  values.root = path.resolve(values.root);
+  return values;
+}
+
+function executable(name) {
+  return name;
+}
+
+function windowsNpmCli(name) {
+  const cliName = `${name}-cli.js`;
+  const candidates = [path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", cliName)];
+  const located = spawnSync("where.exe", [`${name}.cmd`], {
+    encoding: "utf8", windowsHide: true,
+  });
+  if (located.status === 0) {
+    for (const entry of located.stdout.split(/\r?\n/).filter(Boolean)) {
+      candidates.push(path.join(path.dirname(entry.trim()), "node_modules", "npm", "bin", cliName));
+    }
+  }
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
+}
+
+function command(root, program, args, options = {}) {
+  if (process.platform === "win32" && new Set(["npm", "npx"]).has(program)) {
+    const cli = windowsNpmCli(program);
+    if (!cli) return { ok: false, status: null, stdout: "", stderr: `cannot locate ${program} CLI` };
+    args = [cli, ...args];
+    program = process.execPath;
+  }
+  const result = spawnSync(program, args, {
+    cwd: root,
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: options.timeout || 10 * 60 * 1000,
+    env: options.env || process.env,
+  });
+  return {
+    ok: result.status === 0 && !result.error,
+    status: result.status,
+    stdout: result.stdout?.trim() || "",
+    stderr: result.stderr?.trim() || result.error?.message || "",
+  };
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function safeDetail(value) {
+  return String(value || "").slice(-2000);
+}
+
+function createRecorder(checks) {
+  return async (id, execute) => {
+    try {
+      const detail = await execute();
+      checks.push({ id, status: "pass", ...(detail === undefined ? {} : { detail }) });
+    } catch (error) {
+      checks.push({ id, status: "fail", detail: safeDetail(error.message) });
+    }
+  };
+}
+
+function assertCommand(result, label) {
+  if (!result.ok) throw new Error(`${label} failed: ${result.stderr || result.stdout || `exit ${result.status}`}`);
+  return result.stdout;
+}
+
+function requireVersion(value) {
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value || "")) {
+    throw new Error(`invalid release version: ${value || "<missing>"}`);
+  }
+}
+
+function validatePackageDryRun(root, result, manifest, label) {
+  assertCommand(result, label);
+  const warnings = `${result.stdout}\n${result.stderr}`;
+  if (/auto-corrected|invalid and removed/i.test(warnings)) {
+    throw new Error(`${label} reported package metadata correction warnings`);
+  }
+  const parsed = JSON.parse(result.stdout);
+  const packageResult = normalizeNpmPackageResult(parsed, manifest);
+  if (!packageResult || packageResult.error || !Array.isArray(packageResult.files)) {
+    throw new Error(`${label} returned no package file inventory`);
+  }
+  const files = new Set(packageResult.files.map((entry) => entry.path.replaceAll("\\", "/")));
+  if (packageResult.name !== manifest.name || packageResult.version !== manifest.version) {
+    throw new Error(`${label} returned an unexpected package identity`);
+  }
+  if (packageResult.id !== `${manifest.name}@${manifest.version}`) {
+    throw new Error(`${label} returned an unexpected package ID: ${packageResult.id || "missing"}`);
+  }
+  if (!files.size || packageResult.entryCount !== files.size) {
+    throw new Error(`${label} returned an inconsistent file count`);
+  }
+  if (!Number.isInteger(packageResult.size) || packageResult.size <= 0
+    || !Number.isInteger(packageResult.unpackedSize) || packageResult.unpackedSize <= 0
+    || !/^[a-f0-9]{40}$/i.test(packageResult.shasum || "")
+    || !/^sha512-[A-Za-z0-9+/]+={0,2}$/.test(packageResult.integrity || "")) {
+    throw new Error(`${label} returned incomplete package digests or sizes`);
+  }
+  for (const includedRoot of manifest.files || []) {
+    if (![...files].some((file) => file === includedRoot || file.startsWith(`${includedRoot}/`))) {
+      throw new Error(`${label} omitted declared package root: ${includedRoot}`);
+    }
+  }
+  for (const [name, binPath] of Object.entries(manifest.bin || {})) {
+    const normalized = binPath.replace(/^\.\//, "").replaceAll("\\", "/");
+    if (!files.has(normalized)) throw new Error(`${label} omitted bin.${name}: ${normalized}`);
+  }
+  if (manifest.name === "ai-delivery-workflow") {
+    if (manifest.bin?.["ai-delivery"] !== "bin/ai-delivery.mjs") {
+      throw new Error(`${label} requires bin.ai-delivery to be bin/ai-delivery.mjs`);
+    }
+    const executableContent = fs.readFileSync(path.join(root, manifest.bin["ai-delivery"]), "utf8");
+    if (!executableContent.startsWith("#!/usr/bin/env node")) {
+      throw new Error("bin.ai-delivery lacks a Node shebang: bin/ai-delivery.mjs");
+    }
+    for (const requiredRoot of ["bin", "docs", "lib", "skills"]) {
+      if (![...files].some((file) => file.startsWith(`${requiredRoot}/`))) {
+        throw new Error(`${label} omitted required release root: ${requiredRoot}`);
+      }
+    }
+    const excluded = [...files].filter((file) => /^(?:\.tmp|verification|audit)(?:\/|$)/.test(file));
+    if (excluded.length) throw new Error(`${label} included maintenance-only files: ${excluded.join(", ")}`);
+  }
+  return packageResult;
+}
+
+function runPackageDryRun(root, manifest, args, label) {
+  const cache = fs.mkdtempSync(path.join(os.tmpdir(), "ai-delivery-npm-cache-"));
+  try {
+    const result = command(root, executable("npm"), [...args, "--json"], {
+      env: { ...process.env, npm_config_cache: cache },
+    });
+    return validatePackageDryRun(root, result, manifest, label);
+  } finally {
+    fs.rmSync(cache, { recursive: true, force: true });
+  }
+}
+
+function samePackageDryRun(left, right) {
+  const summarize = (value) => ({
+    name: value.name,
+    version: value.version,
+    entryCount: value.entryCount,
+    shasum: value.shasum,
+    integrity: value.integrity,
+    files: value.files.map((entry) => entry.path.replaceAll("\\", "/")).sort(),
+  });
+  return JSON.stringify(summarize(left)) === JSON.stringify(summarize(right));
+}
+
+async function prepare(options, context) {
+  const { root, version, scope } = options;
+  const { manifest, lock, record, checks } = context;
+  await record("package-version", () => {
+    if (manifest.version !== version) throw new Error(`package.json is ${manifest.version}; expected ${version}`);
+    return version;
+  });
+  await record("package-lock-version", () => {
+    if (lock.version !== version || lock.packages?.[""]?.version !== version) {
+      throw new Error(`package-lock.json does not consistently declare ${version}`);
+    }
+    return version;
+  });
+  await record("git-main", () => {
+    const branch = assertCommand(command(root, "git", ["branch", "--show-current"]), "git branch");
+    if (branch !== "main") throw new Error(`release preparation requires main; current branch is ${branch || "detached"}`);
+    return branch;
+  });
+  await record("git-clean", () => {
+    const status = assertCommand(command(root, "git", ["status", "--porcelain=v1"]), "git status");
+    if (status) throw new Error(`worktree is not clean:\n${status}`);
+    return "clean";
+  });
+  await record("git-tag-available", () => {
+    const result = command(root, "git", ["rev-parse", "-q", "--verify", `refs/tags/v${version}`]);
+    if (result.ok) throw new Error(`tag v${version} already exists at ${result.stdout}`);
+    return `v${version}`;
+  });
+  const origin = command(root, "git", ["remote", "get-url", "origin"]);
+  await record("git-origin-main", () => {
+    if (!origin.ok) {
+      if (scope === "full") throw new Error("release preparation requires an origin remote");
+      return "not-configured-local-scope";
+    }
+    assertCommand(command(root, "git", ["fetch", "--quiet", "origin", "main"]), "git fetch origin main");
+    const counts = assertCommand(
+      command(root, "git", ["rev-list", "--left-right", "--count", "origin/main...HEAD"]),
+      "git compare origin/main",
+    ).split(/\s+/).map(Number);
+    if (counts[0] !== 0 || counts[1] !== 0) {
+      throw new Error(`main differs from origin/main: behind=${counts[0]} ahead=${counts[1]}`);
+    }
+    return "synchronized";
+  });
+  await record("git-remote-tag-available", () => {
+    if (!origin.ok) {
+      if (scope === "full") throw new Error("release preparation requires an origin remote");
+      return "not-configured-local-scope";
+    }
+    const remoteTag = command(root, "git", [
+      "ls-remote", "--exit-code", "--tags", "origin", `refs/tags/v${version}`,
+    ]);
+    if (remoteTag.ok && remoteTag.stdout) throw new Error(`remote tag v${version} already exists`);
+    if (remoteTag.status !== 2) throw new Error(`could not inspect remote tag: ${remoteTag.stderr || remoteTag.stdout}`);
+    return `v${version}`;
+  });
+  for (const [id, script] of [
+    ["tests", "test"],
+    ["skills", "skills:validate"],
+    ["audit", "audit:verify"],
+  ]) {
+    await record(id, () => {
+      if (!manifest.scripts?.[script]) throw new Error(`missing npm script: ${script}`);
+      assertCommand(command(root, executable("npm"), ["run", script]), `npm run ${script}`);
+      return script;
+    });
+  }
+  let packDryRun;
+  await record("npm-pack-dry-run", () => {
+    packDryRun = runPackageDryRun(root, manifest, ["pack", "--dry-run"], "npm pack --dry-run");
+    return `${manifest.name}@${version}; files=${packDryRun.entryCount}; integrity=${packDryRun.integrity}`;
+  });
+
+  if (scope === "full") {
+    const registry = "https://registry.npmjs.org/";
+    await record("npm-registry", () => {
+      if (manifest.publishConfig?.registry !== registry) {
+        throw new Error(`publishConfig.registry must be ${registry}`);
+      }
+      return registry;
+    });
+    await record("npm-publish-dry-run", () => {
+      const publishDryRun = runPackageDryRun(
+        root, manifest, ["publish", "--dry-run", `--registry=${registry}`], "npm publish --dry-run",
+      );
+      if (!packDryRun || !samePackageDryRun(packDryRun, publishDryRun)) {
+        throw new Error("npm publish dry-run differs from npm pack dry-run");
+      }
+      return `${manifest.name}@${version}; files=${publishDryRun.entryCount}; integrity=${publishDryRun.integrity}`;
+    });
+    await record("npm-version-available", () => {
+      const result = command(root, executable("npm"), [
+        "view", `${manifest.name}@${version}`, "version", "--json", `--registry=${registry}`,
+      ]);
+      if (result.ok && result.stdout && result.stdout !== "null") {
+        throw new Error(`${manifest.name}@${version} is already published`);
+      }
+      const missing = /E404|404 Not Found|is not in this registry/i.test(`${result.stdout}\n${result.stderr}`);
+      if (!missing) throw new Error(`could not confirm npm version availability: ${result.stderr || result.stdout}`);
+      return "available";
+    });
+    await record("npm-whoami", () => assertCommand(command(root, executable("npm"), [
+      "whoami", `--registry=${registry}`,
+    ]), "npm whoami"));
+    await record("npm-two-factor-auth", () => {
+      const output = assertCommand(command(root, executable("npm"), [
+        "profile", "get", "--json", `--registry=${registry}`,
+      ]), "npm profile get");
+      const profile = JSON.parse(output);
+      const mode = profile.tfa?.mode || profile.tfa || profile.twoFactorAuth || profile["two-factor auth"];
+      if (!/auth-and-writes/i.test(String(mode))) {
+        throw new Error(`npm 2FA must be auth-and-writes; reported ${JSON.stringify(mode ?? null)}`);
+      }
+      return "auth-and-writes";
+    });
+  }
+  return checks;
+}
+
+async function verify(options, context) {
+  const { root, version, commit: requestedCommit, scope } = options;
+  const { manifest, lock, record, checks } = context;
+  const head = assertCommand(command(root, "git", ["rev-parse", "HEAD"]), "git rev-parse HEAD");
+  const expectedCommit = requestedCommit || head;
+  await record("package-version", () => {
+    if (manifest.version !== version || lock.version !== version || lock.packages?.[""]?.version !== version) {
+      throw new Error(`package metadata does not consistently declare ${version}`);
+    }
+    return version;
+  });
+  await record("git-tag-identity", () => {
+    const tagCommit = assertCommand(
+      command(root, "git", ["rev-parse", `${`v${version}`}^{commit}`]),
+      `git tag v${version}`,
+    );
+    if (tagCommit !== expectedCommit) throw new Error(`v${version} points to ${tagCommit}; expected ${expectedCommit}`);
+    return tagCommit;
+  });
+
+  if (scope === "full") {
+    const registry = "https://registry.npmjs.org/";
+    await record("npm-metadata", () => {
+      const output = assertCommand(command(root, executable("npm"), [
+        "view", `${manifest.name}@${version}`, "version", "dist-tags", "bin", "gitHead", "--json",
+        `--registry=${registry}`,
+      ]), "npm view");
+      const metadata = JSON.parse(output);
+      if (metadata.version !== version) throw new Error(`registry returned version ${metadata.version}`);
+      if (metadata["dist-tags"]?.latest !== version) throw new Error(`npm latest is ${metadata["dist-tags"]?.latest || "missing"}`);
+      if (JSON.stringify(metadata.bin || {}) !== JSON.stringify(manifest.bin || {})) {
+        throw new Error("published bin entry differs from package.json");
+      }
+      if (metadata.gitHead && metadata.gitHead !== expectedCommit) {
+        throw new Error(`published gitHead is ${metadata.gitHead}; expected ${expectedCommit}`);
+      }
+      return `${manifest.name}@${metadata.version}`;
+    });
+    await record("external-npx-smoke", () => {
+      const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "ai-delivery-npx-smoke-"));
+      try {
+        const output = assertCommand(command(temporary, executable("npx"), [
+          "--yes", `--registry=${registry}`, `${manifest.name}@${version}`, "--version",
+        ]), "external npx smoke");
+        if (output.trim() !== version) throw new Error(`external npx reported ${output || "no version"}`);
+        return output.trim();
+      } finally {
+        fs.rmSync(temporary, { recursive: true, force: true });
+      }
+    });
+  }
+  return checks;
+}
+
+async function runReleaseCheck(options) {
+  const manifestFile = path.join(options.root, "package.json");
+  const lockFile = path.join(options.root, "package-lock.json");
+  if (!fs.existsSync(manifestFile) || !fs.existsSync(lockFile)) {
+    throw new Error("release root must contain package.json and package-lock.json");
+  }
+  const manifest = readJson(manifestFile);
+  const lock = readJson(lockFile);
+  const version = options.version || manifest.version;
+  requireVersion(version);
+  const checks = [];
+  const context = { manifest, lock, checks, record: createRecorder(checks) };
+  if (options.phase === "prepare") await prepare({ ...options, version }, context);
+  else await verify({ ...options, version }, context);
+  return {
+    schema_version: 1,
+    decision: checks.every((check) => check.status === "pass") ? "pass" : "fail",
+    phase: options.phase,
+    scope: options.scope,
+    package: { name: manifest.name, version },
+    checks,
+  };
+}
+
+try {
+  const report = await runReleaseCheck(parseArguments(process.argv.slice(2)));
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (report.decision !== "pass") process.exitCode = 1;
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 2;
+}