@zaip-ai/cli 2.2.0 → 2.6.0

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/,
+  );
+});

package/templates/.agents/skills/zaip-skill-github-deploy/scripts/github-deploy-contract.test.mjs

@@ -17,7 +17,7 @@ test("explicit Git publication verbs select the guarded deploy skill", async ()
   assert.doesNotMatch(skill, /standing automatic deployment|activate it automatically/);
   assert.match(openai, /\$zaip-skill-github-deploy/);
   assert.match(openai, /fa.a deploy/);
-  assert.match(core, /deploy.*seleciona/);
+  assert.match(core, /seleciona/);
 });
 
 test("deploy guidance preserves the canonical Task subject and Git-only boundary", async () => {
@@ -28,7 +28,7 @@ test("deploy guidance preserves the canonical Task subject and Git-only boundary
   assert.ok(skill.includes("[CODEX|CLAUDE] [P:XXXX] [S:XXXX] [T:XXXX] <Task title>"));
   assert.match(skill, /exclusively `CODEX` or `CLAUDE`; `AUTO` is not part/);
   assert.match(skill, /Git-only publication/);
-  assert.match(workflow, /formar commits funcionais apenas do diff pretendido\/evidenciado/);
+  assert.match(workflow, /commitar o diff evidenciado com pathspecs explícitos/);
 });
 
 test("faça deploy authorizes the complete selected worktree with safety gates", async () => {
@@ -51,3 +51,26 @@ test("deploy permission and reconciliation remain explicit and recoverable", asy
   assert.match(skill, /Restore with `git stash apply`/);
   assert.match(openai, /worktree selecionado inteiro como escopo autorizado/);
 });
+
+test("workflow retains the explicit publication routing contract", async () => {
+  const workflow = await readFile(resolve(root, "rules", "workflow.md"), "utf8");
+  assert.match(workflow, /deploy\|push\|publicar.*autoriza.*\$zaip-skill-github-deploy/);
+});
+
+test("release guidance requires reviewed categorized notes and published-body readback", async () => {
+  const [skill, identity, notes, validator] = await Promise.all([
+    readFile(resolve(skillRoot, "SKILL.md"), "utf8"),
+    readFile(resolve(skillRoot, "references", "release-identity.md"), "utf8"),
+    readFile(resolve(skillRoot, "references", "release-notes.md"), "utf8"),
+    readFile(resolve(skillRoot, "scripts", "validate-release-notes.mjs"), "utf8"),
+  ]);
+  assert.match(skill, /Never use `--generate-notes`/);
+  assert.match(identity, /--notes-file <reviewed-notes\.md>/);
+  assert.match(identity, /--notes-file <reviewed-notes\.md>.*Never use `--generate-notes`/);
+  assert.match(notes, /exact previous Release tag/);
+  assert.match(notes, /Novidades \(feat\)/);
+  assert.match(notes, /Read the release back after creation/);
+  assert.match(validator, /compare-only/);
+  assert.match(validator, /exactly cover the changed Git range/);
+  assert.match(validator, /immutable 40-character candidate SHA/);
+});