@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/skills/zaip-skill-github-deploy/references/release-notes.md

@@ -0,0 +1,134 @@
+# Release notes contract
+
+Every GitHub Release needs an agent-reviewed UTF-8 Markdown body that explains the delivered product
+changes. GitHub's generated notes and a `Full Changelog` comparison are useful navigation aids only;
+neither is an acceptable body on its own. The body opens with a Resumo section containing a short
+plain-language paragraph or bullets before the categorized sections. Write in the project's language;
+the validator's headings below use Brazilian Portuguese. A configured human-only review policy remains
+mandatory where it applies.
+
+## Build the reviewed source
+
+1. Resolve the exact previous Release tag for the same product and channel, then resolve the exact
+   candidate commit SHA. Prove the tag is an ancestor of that candidate with git merge-base
+   --is-ancestor. Do not substitute the previous Git commit, a moving branch head, or a guessed
+   version. For a first release, record that there is no previous tag and inventory the initial
+   candidate explicitly with the initial mode.
+2. Inventory the exact range before writing prose: `git diff --name-status <previous-tag>..<candidate-sha>`
+   and the corresponding commit messages. Read the meaningful diffs. This covers direct commits,
+   merge commits, and squashed pull requests without relying on PR titles. The file inventory is an
+   internal coverage aid, not a release-note dump.
+3. Group files that implement one outcome into one topic. Deduplicate generated, template, lock, and
+   projection files behind their canonical user-facing improvement, but retain every changed file in
+   that topic's internal mapping. Do not omit a meaningful change because it is spread across files.
+4. Write the body in UTF-8 Markdown. After Resumo, use only sections with content: Novidades (feat),
+   Correções (fix), Desempenho (perf), Alterações internas (refactor, build, ci, test, chore),
+   Segurança, Alterações incompatíveis e migrações, and Documentação. Each topic gets one concrete
+   bullet that states the outcome and affected capability, rather than a commit subject or a list of
+   paths. Conventional commits are useful input, never a substitute for reviewing the diff.
+5. Keep an adjacent uncommitted-or-local release inventory JSON while publishing. It must state the
+   exact `from` tag, `to` SHA, every changed file, and one or more topics. Each topic has a category,
+   a unique bullet copied verbatim into the Markdown body, and the source files it covers. This makes
+   coverage mechanically checkable while keeping the published body readable.
+
+Illustrative body (replace every example with observed facts):
+
+```md
+## Resumo
+
+- A publicação agora entrega uma descrição revisada e verificável das melhorias.
+
+## Novidades
+
+- **Feature:** Releases now include grouped, reviewed summaries of every delivered capability.
+
+## Documentação
+
+- **Documentation:** The deploy guide now records the prior release range and validates the published body.
+
+Full Changelog: [v2.4...v2.5](https://github.com/owner/repository/compare/v2.4...v2.5)
+```
+
+The optional comparison link belongs after the explanatory bullets. Do not use empty category headings,
+placeholders, `TBD`, `N/A`, a single generic bullet, or a raw file/commit list as a substitute for the
+summary.
+
+Example inventory shape:
+
+```json
+{
+  "from": "v2.4",
+  "to": "0123456789abcdef0123456789abcdef01234567",
+  "files": ["src/release-notes.ts", "docs/releases.md"],
+  "topics": [
+    {
+      "category": "feat",
+      "bullet": "- **Feature:** Releases now include grouped, reviewed summaries of every delivered capability.",
+      "files": ["src/release-notes.ts"]
+    },
+    {
+      "category": "docs",
+      "bullet": "- **Documentation:** The deploy guide now records the prior release range and validates the published body.",
+      "files": ["docs/releases.md"]
+    }
+  ]
+}
+```
+
+## Validate, publish, and read back
+
+Use a local working path such as `.local/release-notes-<tag>.md` and
+`.local/release-notes-<tag>.inventory.json`; never commit temporary release-note working files unless the
+repository explicitly owns them. Before creating the Release, validate the actual Git range, inventory,
+and reviewed body:
+
+```powershell
+node .agents/skills/zaip-skill-github-deploy/scripts/validate-release-notes.mjs --repository . --from <previous-tag> --to <candidate-sha> --notes-file .local/release-notes-<tag>.md --inventory-file .local/release-notes-<tag>.inventory.json
+gh release create <tag> --repo <owner/repo> --target <candidate-sha> --title <title> --notes-file .local/release-notes-<tag>.md --prerelease --latest=false
+```
+
+Read the release back after creation. Save the returned `body` as UTF-8 and run the same validator with
+the same range and inventory. Also inspect the returned title, tag, target commit, prerelease state, and
+URL. A mismatch, missing bullet, compare-only body, or incomplete inventory is a release failure that
+must be corrected by editing the authorized Release body and reading it back again.
+
+```powershell
+gh release view <tag> --repo <owner/repo> --json body,name,tagName,targetCommitish,isPrerelease,url
+```
+
+For an initial release, invoke the validator with `--initial` instead of `--from`, and use null as
+the inventory from value.
+
+The validator proves UTF-8, a non-empty categorized structure, the exact immutable candidate range, and
+one visible bullet plus an internal file mapping for every topic. It cannot prove that a bullet explains
+a change well, that the grouping is useful, or that a sensitive detail is appropriate to disclose; the
+agent must review those semantic judgments, with human review where a configured policy requires it.
+Never include credentials, personal data, exploit instructions, or unapproved vulnerability details in a
+public release body. Use the approved private security process when disclosure must be delayed or limited.
+
+Record the prior tag, candidate SHA, reviewed notes path, inventory result, and published-body readback
+in the delivery evidence. This contract changes the release description only; it does not authorize a
+GitHub Release, a push, or npm publication.
+
+## Completeness and reader impact
+
+- Explain every meaningful created, edited, removed or deprecated topic, including documentation,
+  dependencies, CI and maintenance. Map `added` to Novidades, `changed` to Alterações internas,
+  and `removed` or `deprecated` to Alterações incompatíveis e migrações in the inventory. Put
+  incompatibilities first after Resumo when present. Distinguish observable behavior changes from
+  internal refactors in the bullet text.
+- For each breaking change, removal or deprecation, describe who is affected, the migration or
+  replacement, and any confirmed deadline. Add Atualização and Limitações sections only when useful.
+  Do not invent compatibility, performance gains or successful tests.
+- Reconcile reverted changes and intermediate fixes against the final diff; do not claim work that
+  was undone. Rebuild the inventory and notes if the candidate changes. Generated copies belong to
+  their canonical topic; mechanical noise may be grouped, without hiding a distinct improvement.
+- Review the wording for both open-source users and private company audiences. Keep private links
+  accessible to their intended audience and remove sensitive internal details from public notes.
+- Read back the published `body` and compare it with the reviewed UTF-8 file, in addition to running
+  the validator. The transport must preserve the prose, not just its structural validity. Verify the
+  tag's resolved SHA separately; `targetCommitish` may be a branch name.
+
+Sources: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), and
+[GitHub release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes).

package/templates/.agents/skills/zaip-skill-github-deploy/scripts/consumer-release-preparation.mjs

@@ -0,0 +1,389 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign,
+  verify,
+} from "node:crypto";
+import { existsSync } from "node:fs";
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { parseDocument } from "./yaml-parser.mjs";
+
+const fail = (m) => {
+    throw new Error(m);
+  },
+  sha40 = /^[a-f0-9]{40}$/i,
+  tag = /^v\d+\.\d+$/;
+const hash = async (p) =>
+    createHash("sha256")
+      .update(await readFile(p))
+      .digest("hex"),
+  json = async (p) => JSON.parse(await readFile(p, "utf8"));
+const git = (cwd, args) =>
+  execFileSync("git", args, { cwd, encoding: "utf8", windowsHide: true }).trim();
+const unsigned = (r) => {
+  const { signature, ...body } = r;
+  return Buffer.from(JSON.stringify(body));
+};
+const key = (x, label) => {
+  if (x.asymmetricKeyType !== "ed25519") fail(`${label} must be Ed25519`);
+};
+export function identity(repository, expected) {
+  const sha = git(repository, ["rev-parse", "HEAD"]).toLowerCase();
+  if (!sha40.test(sha) || sha !== expected.toLowerCase())
+    fail("repository SHA does not match requested SHA");
+  if (git(repository, ["status", "--porcelain"]) !== "") fail("repository must be clean");
+  return {
+    sha,
+    tree: git(repository, ["rev-parse", "HEAD^{tree}"]).toLowerCase(),
+    tree_sha256: createHash("sha256")
+      .update(execFileSync("git", ["ls-tree", "-r", "-z", sha], { cwd: repository }))
+      .digest("hex"),
+  };
+}
+export async function configuredBranch(repository, scope = "frontend") {
+  if (!["frontend", "backend"].includes(scope))
+    fail("consumer release scope must be frontend or backend");
+  const configPath = join(repository, ".agents", "config", "project.yaml");
+  if (!existsSync(configPath)) return "beta";
+  let document;
+  try {
+    document = parseDocument(await readFile(configPath, "utf8"), {
+      strict: true,
+      uniqueKeys: true,
+    });
+  } catch {
+    fail("project.yaml must contain a mapping");
+  }
+  if (document.errors.length) fail("project.yaml is invalid");
+  const config = document.toJS();
+  if (config === null || typeof config !== "object" || Array.isArray(config))
+    fail("project.yaml must contain a mapping");
+  const deploy = config.deploy;
+  if (deploy === undefined) return "beta";
+  if (deploy === null || typeof deploy !== "object" || Array.isArray(deploy))
+    fail("project.yaml deploy must be a mapping");
+  if (
+    !Object.keys(deploy).every((key) =>
+      [
+        "branch",
+        "production_branch",
+        "allow_production",
+        "frontend",
+        "backend",
+        "database",
+      ].includes(key),
+    )
+  )
+    fail("project.yaml deploy has unsupported keys");
+  for (const key of ["frontend", "backend", "database"])
+    if (
+      deploy[key] !== undefined &&
+      (deploy[key] === null ||
+        typeof deploy[key] !== "object" ||
+        Array.isArray(deploy[key]) ||
+        !Object.keys(deploy[key]).every((nested) => nested === "branch"))
+    )
+      fail(`project.yaml deploy.${key} must be a branch mapping`);
+  const branch = deploy[scope]?.branch ?? deploy.branch ?? "beta";
+  if (typeof branch !== "string" || branch.trim() === "" || branch.trim() !== branch)
+    fail("project.yaml deploy branch must be a non-empty Git branch name");
+  if (branch.length > 255 || !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(branch))
+    fail(`project.yaml deploy branch is invalid: ${branch}`);
+  return branch;
+}
+export function commands(value) {
+  if (
+    !Array.isArray(value) ||
+    !value.length ||
+    !value.every(
+      (x) =>
+        x &&
+        ["node", "corepack", "npm", "pnpm"].includes(x.command) &&
+        Array.isArray(x.args) &&
+        x.args.every((a) => typeof a === "string") &&
+        (x.command === "node" || x.args.every((a) => /^[-A-Za-z0-9_./:@=*]+$/.test(a))),
+    )
+  )
+    fail("required_commands must use node or a supported package manager with safe string args");
+  return value;
+}
+export function commandInvocation(item, platform = process.platform) {
+  if (item.command === "node") return { command: process.execPath, args: item.args };
+  if (platform === "win32")
+    return {
+      command: process.env.ComSpec ?? "cmd.exe",
+      args: ["/d", "/s", "/c", `${item.command}.cmd`, ...item.args],
+    };
+  return { command: item.command, args: item.args };
+}
+export function run(list, cwd, label = "preparation") {
+  for (const item of commands(list)) {
+    const invocation = commandInvocation(item);
+    const result = spawnSync(invocation.command, invocation.args, {
+      cwd,
+      encoding: "utf8",
+      windowsHide: true,
+      shell: false,
+    });
+    if (result.error || result.status !== 0) fail(`${label} command failed: ${item.command}`);
+  }
+}
+export function policyFor(policy, caller) {
+  if (
+    policy?.schema_version !== 1 ||
+    policy.repository !== caller.repository ||
+    policy.configured_branch !== caller.branch ||
+    !tag.test(policy.github_version ?? "") ||
+    policy.github_version !== caller.githubVersion
+  )
+    fail("policy is not authorized for this GitHub caller");
+  const required = commands(policy.required_commands);
+  if (JSON.stringify(required) !== JSON.stringify(caller.commands))
+    fail("caller commands differ from policy required_commands");
+  return required;
+}
+export async function bootstrap({ trustStore, publicKey, keyId }) {
+  const parsedKey = createPublicKey(await readFile(publicKey));
+  key(parsedKey, "public key");
+  if (!/^[A-Za-z0-9._-]{1,64}$/.test(keyId)) fail("invalid key id");
+  const store = resolve(trustStore),
+    file = `${keyId}.pub.pem`;
+  await mkdir(store, { recursive: true });
+  await cp(resolve(publicKey), join(store, file));
+  await writeFile(
+    join(store, "trusted-github-release-keys.json"),
+    `${JSON.stringify({ schema_version: 1, keys: [{ key_id: keyId, file, sha256: await hash(join(store, file)) }] }, null, 2)}\n`,
+  );
+}
+export async function keygen({ privateKey, publicKey }) {
+  const privatePath = resolve(privateKey);
+  const publicPath = resolve(publicKey);
+  if (privatePath === publicPath) fail("private and public key paths must differ");
+  const pair = generateKeyPairSync("ed25519");
+  await mkdir(dirname(privatePath), { recursive: true });
+  await mkdir(dirname(publicPath), { recursive: true });
+  await writeFile(privatePath, pair.privateKey.export({ type: "pkcs8", format: "pem" }), {
+    encoding: "utf8",
+    flag: "wx",
+    mode: 0o600,
+  });
+  await writeFile(publicPath, pair.publicKey.export({ type: "spki", format: "pem" }), {
+    encoding: "utf8",
+    flag: "wx",
+    mode: 0o644,
+  });
+  return { privateKey: privatePath, publicKey: publicPath };
+}
+export async function prepare(input) {
+  if (!sha40.test(input.sha) || !tag.test(input.githubVersion))
+    fail("SHA and GitHub version vN.N are required");
+  const repository = resolve(input.repository),
+    branch = await configuredBranch(repository, input.scope ?? "frontend");
+  if (branch !== input.branch || git(repository, ["branch", "--show-current"]) !== branch)
+    fail("checked out branch does not match configured branch");
+  const policyDigest = await hash(input.policy),
+    before = identity(repository, input.sha),
+    required = policyFor(await json(input.policy), input);
+  run(required, repository);
+  const after = identity(repository, input.sha);
+  if (policyDigest !== (await hash(input.policy))) fail("policy changed during preparation");
+  if (JSON.stringify(before) !== JSON.stringify(after))
+    fail("repository identity changed during preparation");
+  const privateKey = createPrivateKey(await readFile(input.privateKey));
+  key(privateKey, "private key");
+  const clock = Date.now(),
+    issued_at = new Date(clock).toISOString(),
+    expires_at = new Date(clock + 7 * 86400000).toISOString(),
+    receipt = {
+      schema_version: 1,
+      algorithm: "ed25519",
+      key_id: input.keyId,
+      issued_at,
+      expires_at,
+      repository: input.repository,
+      configured_branch: branch,
+      github_version: input.githubVersion,
+      candidate: after,
+      policy_sha256: policyDigest,
+      required_commands: required,
+    };
+  const signed = {
+    ...receipt,
+    signature: sign(null, unsigned(receipt), privateKey).toString("base64"),
+  };
+  await mkdir(resolve(input.outputDir), { recursive: true });
+  const receiptPath = join(resolve(input.outputDir), "consumer-github-release-receipt.json");
+  await writeFile(receiptPath, `${JSON.stringify(signed, null, 2)}\n`);
+  return { receiptPath, receipt: signed };
+}
+export async function verifyPreparation(input) {
+  const receipt = await json(input.receipt),
+    repository = resolve(input.repository),
+    branch = await configuredBranch(repository, input.scope ?? "frontend"),
+    current = identity(repository, input.sha),
+    required = policyFor(await json(input.policy), input),
+    now = Date.now(),
+    issued = Date.parse(receipt.issued_at),
+    expires = Date.parse(receipt.expires_at);
+  if (
+    !Number.isFinite(issued) ||
+    !Number.isFinite(expires) ||
+    issued > now + 300000 ||
+    now - issued > 7 * 86400000 ||
+    expires <= now ||
+    expires > issued + 7 * 86400000 ||
+    !tag.test(input.githubVersion) ||
+    branch !== input.branch ||
+    receipt.schema_version !== 1 ||
+    receipt.algorithm !== "ed25519" ||
+    receipt.repository !== input.repository ||
+    receipt.configured_branch !== branch ||
+    receipt.github_version !== input.githubVersion ||
+    JSON.stringify(receipt.candidate) !== JSON.stringify(current) ||
+    JSON.stringify(receipt.required_commands) !== JSON.stringify(required) ||
+    receipt.policy_sha256 !== (await hash(input.policy))
+  )
+    fail("receipt GitHub identity, expiry or policy mismatch");
+  const trust = await json(join(resolve(input.trustStore), "trusted-github-release-keys.json")),
+    entry = trust.keys?.find((x) => x.key_id === receipt.key_id);
+  if (!entry) fail("receipt key is not trusted");
+  const keyPath = join(resolve(input.trustStore), entry.file);
+  if (entry.sha256 !== (await hash(keyPath))) fail("trusted key digest mismatch");
+  const publicKey = createPublicKey(await readFile(keyPath));
+  key(publicKey, "trusted public key");
+  if (!verify(null, unsigned(receipt), publicKey, Buffer.from(receipt.signature, "base64")))
+    fail("receipt signature is invalid");
+  return receipt;
+}
+export async function guardedPush(input, runner = null) {
+  const prepared = await prepare(input);
+  await verifyPreparation({ ...input, receipt: prepared.receiptPath });
+  const remote = input.remote ?? "origin";
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(remote)) fail("invalid Git remote name");
+  const repository = resolve(input.repository),
+    source = git(repository, ["remote", "get-url", "--push", remote]),
+    refspec = `${input.sha}:refs/heads/${input.branch}`;
+  if (
+    source !== input.remoteUrl ||
+    git(repository, ["rev-parse", "HEAD"]).toLowerCase() !== input.sha.toLowerCase()
+  )
+    fail("push remote or HEAD changed after verification");
+  const preflight = {
+    phase: "preflight",
+    repository,
+    remote,
+    branch: input.branch,
+    scope: input.scope ?? "frontend",
+  };
+  if (runner) runner(preflight);
+  else
+    execFileSync(
+      process.execPath,
+      [
+        join(dirname(fileURLToPath(import.meta.url)), "preflight.mjs"),
+        "--repository",
+        repository,
+        "--remote",
+        remote,
+        "--branch",
+        input.branch,
+        "--scope",
+        preflight.scope,
+      ],
+      { cwd: repository, stdio: "inherit", windowsHide: true },
+    );
+  if (git(repository, ["rev-parse", "HEAD"]).toLowerCase() !== input.sha.toLowerCase())
+    fail("HEAD changed after preflight");
+  if (runner) runner({ phase: "push", repository, remote, refspec });
+  else
+    execFileSync("git", ["push", remote, refspec], {
+      cwd: repository,
+      stdio: "inherit",
+      windowsHide: true,
+    });
+  return { ...prepared, refspec };
+}
+const opts = {
+  repository: { type: "string" },
+  sha: { type: "string" },
+  branch: { type: "string" },
+  scope: { type: "string", default: "frontend" },
+  remote: { type: "string", default: "origin" },
+  "remote-url": { type: "string" },
+  "github-version": { type: "string" },
+  policy: { type: "string" },
+  "trust-store": { type: "string" },
+  "private-key": { type: "string" },
+  "public-key": { type: "string" },
+  "key-id": { type: "string" },
+  "output-dir": { type: "string" },
+  receipt: { type: "string" },
+  "commands-json": { type: "string" },
+};
+async function main() {
+  const [action] = process.argv.slice(2),
+    { values } = parseArgs({ options: opts, strict: true, allowPositionals: true }),
+    need = (n) => values[n] ?? fail(`--${n} is required`);
+  if (action === "bootstrap")
+    return bootstrap({
+      trustStore: need("trust-store"),
+      publicKey: need("public-key"),
+      keyId: need("key-id"),
+    });
+  if (action === "keygen")
+    return keygen({
+      privateKey: need("private-key"),
+      publicKey: need("public-key"),
+    });
+  const common = {
+    repository: need("repository"),
+    sha: need("sha"),
+    branch: need("branch"),
+    scope: values.scope,
+    githubVersion: need("github-version"),
+    policy: need("policy"),
+    trustStore: values["trust-store"],
+    commands: JSON.parse(need("commands-json")),
+  };
+  if (action === "prepare") {
+    const r = await prepare({
+      ...common,
+      outputDir: need("output-dir"),
+      privateKey: need("private-key"),
+      keyId: need("key-id"),
+    });
+    process.stdout.write(`${JSON.stringify({ valid: true, receipt: r.receiptPath })}\n`);
+    return;
+  }
+  if (action === "verify") {
+    await verifyPreparation({ ...common, receipt: need("receipt") });
+    process.stdout.write('{"valid":true}\n');
+    return;
+  }
+  if (action === "guarded-push") {
+    const r = await guardedPush({
+      ...common,
+      outputDir: need("output-dir"),
+      privateKey: need("private-key"),
+      keyId: need("key-id"),
+      remote: values.remote,
+      remoteUrl: need("remote-url"),
+    });
+    process.stdout.write(
+      `${JSON.stringify({ valid: true, pushed: true, receipt: r.receiptPath, refspec: r.refspec })}\n`,
+    );
+    return;
+  }
+  fail("Usage: consumer-release-preparation.mjs bootstrap|keygen|prepare|verify|guarded-push");
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url))
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });

package/templates/.agents/skills/zaip-skill-github-deploy/scripts/consumer-release-preparation.test.mjs

@@ -0,0 +1,134 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import {
+  bootstrap,
+  commandInvocation,
+  configuredBranch,
+  guardedPush,
+  keygen,
+  prepare,
+  run,
+  verifyPreparation,
+} from "./consumer-release-preparation.mjs";
+
+const git = (cwd, ...args) => execFileSync("git", args, { cwd, encoding: "utf8" }).trim();
+
+test("resolves only the selected application scope from nested deploy configuration", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-consumer-config-"));
+  try {
+    const repo = join(root, "repo");
+    await mkdir(join(repo, ".agents", "config"), { recursive: true });
+    await writeFile(
+      join(repo, ".agents", "config", "project.yaml"),
+      [
+        "deploy:",
+        "  branch: beta",
+        "  frontend:",
+        "    branch: main",
+        "  backend:",
+        "    branch: beta",
+        "  database:",
+        "    branch: beta",
+        "",
+      ].join("\n"),
+    );
+    assert.equal(await configuredBranch(repo), "main");
+    assert.equal(await configuredBranch(repo, "backend"), "beta");
+    await assert.rejects(() => configuredBranch(repo, "database"), /frontend or backend/);
+    await writeFile(join(repo, ".agents", "config", "project.yaml"), "project: consumer\n");
+    assert.equal(await configuredBranch(repo), "beta");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("GitHub-only guard binds parsed config, policy, receipt expiry and fixed refspec", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-consumer-"));
+  try {
+    const repo = join(root, "repo");
+    await mkdir(join(repo, ".agents", "config"), { recursive: true });
+    git(repo, "init", "--quiet");
+    git(repo, "checkout", "-qb", "main");
+    git(repo, "config", "user.email", "x@y.invalid");
+    git(repo, "config", "user.name", "x");
+    git(repo, "remote", "add", "origin", "ssh://git@example.invalid/consumer.git");
+    await writeFile(
+      join(repo, ".agents", "config", "project.yaml"),
+      "deploy:\n  branch: beta\n  frontend:\n    branch: main\n  backend:\n    branch: beta\n  database:\n    branch: beta\n",
+    );
+    await writeFile(join(repo, "README.md"), "x");
+    git(repo, "add", ".");
+    git(repo, "commit", "--quiet", "-m", "x");
+    const priv = join(root, "k.pem");
+    const pub = join(root, "k.pub");
+    const policy = join(root, "policy.json");
+    const trust = join(root, "trust");
+    const out = join(root, "out");
+    const sha = git(repo, "rev-parse", "HEAD");
+    const required = [{ command: "node", args: ["-e", "process.exit(0)"] }];
+    const input = {
+      repository: repo,
+      sha,
+      branch: "main",
+      scope: "frontend",
+      githubVersion: "v1.2",
+      policy,
+      trustStore: trust,
+      commands: required,
+      outputDir: out,
+      privateKey: priv,
+      keyId: "consumer",
+      remoteUrl: "ssh://git@example.invalid/consumer.git",
+    };
+    await keygen({ privateKey: priv, publicKey: pub });
+    await writeFile(
+      policy,
+      JSON.stringify({
+        schema_version: 1,
+        repository: repo,
+        configured_branch: "main",
+        github_version: "v1.2",
+        required_commands: required,
+      }),
+    );
+    await bootstrap({ trustStore: trust, publicKey: pub, keyId: "consumer" });
+    const prepared = await prepare(input);
+    await verifyPreparation({ ...input, receipt: prepared.receiptPath });
+    const calls = [];
+    await guardedPush(input, (value) => calls.push(value));
+    assert.deepEqual(
+      calls.map((value) => value.phase),
+      ["preflight", "push"],
+    );
+    assert.equal(calls[1].refspec, sha + ":refs/heads/main");
+    await assert.rejects(
+      () => prepare({ ...input, commands: [{ command: "node", args: ["-e", "process.exit(2)"] }] }),
+      /differ/,
+    );
+    await writeFile(join(repo, "dirty"), "x");
+    await assert.rejects(
+      () => verifyPreparation({ ...input, receipt: prepared.receiptPath }),
+      /clean/,
+    );
+    await rm(join(repo, "dirty"));
+    await writeFile(policy, "{}");
+    await assert.rejects(() => verifyPreparation({ ...input, receipt: prepared.receiptPath }));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("runs corepack through the Windows command wrapper without arbitrary shell input", () => {
+  const invocation = commandInvocation({ command: "corepack", args: ["--version"] }, "win32");
+  assert.match(invocation.command, /cmd\.exe$/i);
+  assert.deepEqual(invocation.args, ["/d", "/s", "/c", "corepack.cmd", "--version"]);
+  run([{ command: "corepack", args: ["--version"] }], process.cwd(), "corepack");
+  assert.throws(
+    () => run([{ command: "corepack", args: ["--version;whoami"] }], process.cwd()),
+    /supported package manager/,
+  );
+});