@zaip-ai/cli 2.2.0 → 3.0.0

package/templates/.agents/skills/zaip-skill-cybersecurity/scripts/score-audit.mjs

@@ -0,0 +1,185 @@
+import { readFile } from "node:fs/promises";
+
+const weights = [10, 12, 14, 12, 8, 12, 10, 10, 6, 6];
+const confidenceLevels = new Set(["low", "medium", "high"]);
+const statuses = new Set(["scored", "unknown", "not_applicable"]);
+
+export function scorePillar({
+  pass = 0,
+  partial = 0,
+  fail = 0,
+  notTested = 0,
+  confidence = "medium",
+}) {
+  if (!confidenceLevels.has(confidence))
+    throw new Error("Pillar confidence must be low, medium, or high");
+  for (const value of [pass, partial, fail, notTested]) {
+    if (!Number.isInteger(value) || value < 0)
+      throw new Error("Control counts must be non-negative integers");
+  }
+  const planned = pass + partial + fail + notTested;
+  if (planned === 0)
+    return {
+      pass,
+      partial,
+      fail,
+      notTested,
+      confidence,
+      grade: null,
+      coverage: null,
+      perfect: false,
+      status: "unknown",
+    };
+  const tested = pass + partial + fail;
+  const coverage = (tested / planned) * 100;
+  if (coverage < 60 || tested === 0)
+    return {
+      pass,
+      partial,
+      fail,
+      notTested,
+      confidence,
+      grade: null,
+      coverage,
+      perfect: false,
+      status: "unknown",
+    };
+  const controlsGrade = (10 * (pass + 0.5 * partial)) / tested;
+  if (confidence === "low")
+    return {
+      pass,
+      partial,
+      fail,
+      notTested,
+      confidence,
+      grade: null,
+      coverage,
+      perfect: false,
+      status: "unknown",
+    };
+  const grade = Math.min(controlsGrade, coverage / 10, confidence === "high" ? 10 : 9.9);
+  return {
+    pass,
+    partial,
+    fail,
+    notTested,
+    confidence,
+    grade,
+    coverage,
+    perfect: confidence === "high" && pass === planned,
+    status: "scored",
+  };
+}
+
+export function capsFromFindings(findings = []) {
+  if (!Array.isArray(findings)) throw new Error("findings must be an array");
+  return findings.flatMap((finding) => {
+    const status =
+      { confirmado: "confirmed", suspeito: "suspected", "não-testado": "not-tested" }[
+        finding?.status
+      ] ?? finding?.status;
+    const severity = finding?.severity;
+    if (!["confirmed", "suspected", "not-tested"].includes(status))
+      throw new Error("Finding status is invalid");
+    if (!["critical", "high", "medium", "low", "info"].includes(severity))
+      throw new Error("Finding severity is invalid");
+    const retested =
+      typeof finding?.positiveRetest?.evidence === "string" &&
+      finding.positiveRetest.evidence.trim() !== "" &&
+      typeof finding?.negativeRetest?.evidence === "string" &&
+      finding.negativeRetest.evidence.trim() !== "";
+    if (finding?.closed === true && retested) return [];
+    if (status !== "confirmed") return [9.9];
+    if (severity === "critical") return [3];
+    if (severity === "high") return [5];
+    if (severity === "medium") return [finding.materialBoundary ? 7 : 9.9];
+    return [9.9];
+  });
+}
+
+export function scoreOverall(pillars, { confidence = "medium", caps = [], findings = [] } = {}) {
+  if (!Array.isArray(pillars) || pillars.length !== 10)
+    throw new Error("Exactly ten pillars are required");
+  if (!confidenceLevels.has(confidence)) throw new Error("confidence must be low, medium, or high");
+  const ids = pillars.map((pillar) => pillar?.id);
+  if (new Set(ids).size !== 10 || ids.some((id) => !Number.isInteger(id) || id < 1 || id > 10))
+    throw new Error("Pillar ids must be unique integers from 1 through 10");
+  for (const cap of caps)
+    if (!Number.isFinite(cap) || cap < 0 || cap > 10)
+      throw new Error("caps must be finite scores from 0 through 10");
+  const normalized = pillars.map((pillar) => {
+    if (!statuses.has(pillar?.status)) throw new Error("Pillar status is invalid");
+    if (pillar.status === "not_applicable") {
+      const evidenceValid =
+        (typeof pillar.evidence === "string" && pillar.evidence.trim() !== "") ||
+        (typeof pillar.evidence?.locator === "string" && pillar.evidence.locator.trim() !== "");
+      if (typeof pillar.reason !== "string" || pillar.reason.trim() === "" || !evidenceValid)
+        throw new Error("N/A pillars require reason and evidence");
+      return pillar;
+    }
+    if (
+      !["pass", "partial", "fail", "notTested"].every(
+        (key) => Number.isInteger(pillar[key]) && pillar[key] >= 0,
+      )
+    )
+      throw new Error("Scored pillars require non-negative integer control evidence counts");
+    if (!confidenceLevels.has(pillar.confidence))
+      throw new Error("Each scored pillar requires confidence");
+    const derived = scorePillar(pillar);
+    if (pillar.status !== derived.status)
+      throw new Error("Pillar status must derive from control evidence");
+    if (
+      (pillar.grade !== undefined && pillar.grade !== derived.grade) ||
+      (pillar.coverage !== undefined && pillar.coverage !== derived.coverage)
+    )
+      throw new Error("Pillar grade and coverage must derive from control evidence");
+    if (
+      pillar.grade !== null &&
+      (!Number.isFinite(pillar.grade) || pillar.grade < 0 || pillar.grade > 10)
+    )
+      throw new Error("Pillar grade must be null or a finite score from 0 through 10");
+    if (
+      pillar.coverage !== null &&
+      (!Number.isFinite(pillar.coverage) || pillar.coverage < 0 || pillar.coverage > 100)
+    )
+      throw new Error("Pillar coverage must be null or a percentage from 0 through 100");
+    return { ...pillar, ...derived };
+  });
+  const applicable = normalized.filter((pillar) => pillar.status !== "not_applicable");
+  if (
+    applicable.length === 0 ||
+    confidence === "low" ||
+    applicable.some((pillar) => pillar.confidence === "low")
+  )
+    return null;
+  const weightedCoverage =
+    applicable.reduce((sum, pillar) => sum + (pillar.coverage ?? 0) * weights[pillar.id - 1], 0) /
+    applicable.reduce((sum, pillar) => sum + weights[pillar.id - 1], 0);
+  const highCoverage = new Set([1, 2, 3, 4, 6, 8, 9]);
+  if (
+    applicable.some(
+      (pillar) => pillar.status === "unknown" || pillar.grade === null || pillar.coverage < 60,
+    ) ||
+    weightedCoverage < 80 ||
+    applicable.some((pillar) => highCoverage.has(pillar.id) && pillar.coverage < 80)
+  )
+    return null;
+  const raw =
+    applicable.reduce((sum, pillar) => sum + pillar.grade * weights[pillar.id - 1], 0) /
+    applicable.reduce((sum, pillar) => sum + weights[pillar.id - 1], 0);
+  const cap = Math.min(10, ...caps, ...capsFromFindings(findings));
+  const score = Math.min(raw, cap);
+  const perfect =
+    confidence === "high" &&
+    applicable.every(
+      (pillar) => pillar.confidence === "high" && pillar.grade === 10 && pillar.coverage === 100,
+    );
+  return Math.floor((score === 10 && !perfect ? 9.9 : score) * 10) / 10;
+}
+
+if (process.argv[1]?.replaceAll("\\", "/").endsWith("/score-audit.mjs") && process.argv[2]) {
+  const input = JSON.parse(await readFile(process.argv[2], "utf8"));
+  process.stdout.write(
+    `${JSON.stringify({ overall: scoreOverall(input.pillars, input), pillars: input.pillars }, null, 2)}\n`,
+  );
+}

package/templates/.agents/skills/zaip-skill-cybersecurity/scripts/score-audit.test.mjs

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { capsFromFindings, scoreOverall, scorePillar } from "./score-audit.mjs";
+
+test("scores controls reproducibly and keeps untested coverage visible", () => {
+  assert.deepEqual(scorePillar({ pass: 3, partial: 1, fail: 0, notTested: 1 }), {
+    pass: 3,
+    partial: 1,
+    fail: 0,
+    notTested: 1,
+    confidence: "medium",
+    grade: 8,
+    coverage: 80,
+    perfect: false,
+    status: "scored",
+  });
+  assert.deepEqual(scorePillar({ notTested: 3 }), {
+    pass: 0,
+    partial: 0,
+    fail: 0,
+    notTested: 3,
+    confidence: "medium",
+    grade: null,
+    coverage: 0,
+    perfect: false,
+    status: "unknown",
+  });
+});
+
+test("requires high confidence before a pillar can publish ten", () => {
+  assert.equal(scorePillar({ pass: 10, confidence: "medium" }).grade, 9.9);
+  assert.equal(scorePillar({ pass: 10, confidence: "medium" }).perfect, false);
+  assert.equal(scorePillar({ pass: 10, confidence: "low" }).status, "unknown");
+  assert.equal(scorePillar({ pass: 10, confidence: "high" }).grade, 10);
+});
+
+test("requires all ten pillars and applies impact caps without rounding to ten", () => {
+  const pillars = Array.from({ length: 10 }, (_, index) => ({
+    id: index + 1,
+    status: "scored",
+    ...scorePillar(index === 0 ? { pass: 8, notTested: 2 } : { pass: 2 }),
+  }));
+  assert.equal(scoreOverall(pillars, { confidence: "high" }), 9.7);
+  assert.equal(
+    scoreOverall(pillars, {
+      confidence: "high",
+      findings: [{ status: "confirmed", severity: "critical" }],
+    }),
+    3,
+  );
+  assert.deepEqual(capsFromFindings([{ status: "suspected", severity: "high" }]), [9.9]);
+  pillars[4].status = "unknown";
+  assert.throws(() => scoreOverall(pillars), /status must derive/);
+  assert.throws(
+    () =>
+      scoreOverall([{ ...pillars[0], id: 1 }, ...pillars.slice(1, 9), { ...pillars[9], id: 1 }]),
+    /unique/,
+  );
+});
+
+test("requires observed retests to clear a finding cap", () => {
+  const open = {
+    status: "confirmed",
+    severity: "critical",
+    closed: true,
+    positiveRetest: true,
+    negativeRetest: true,
+  };
+  assert.deepEqual(capsFromFindings([open]), [3]);
+  open.positiveRetest = { evidence: "tests/security.test.ts:20" };
+  open.negativeRetest = { evidence: "tests/security.test.ts:31" };
+  assert.deepEqual(capsFromFindings([open]), []);
+  assert.deepEqual(capsFromFindings([{ status: "confirmed", severity: "info" }]), [9.9]);
+});
+
+test("excludes only evidenced N/A pillars before evaluating numeric grades", () => {
+  const pillars = Array.from({ length: 10 }, (_, index) => ({
+    id: index + 1,
+    ...scorePillar({ pass: 2, confidence: "high" }),
+  }));
+  pillars[9] = {
+    id: 10,
+    status: "not_applicable",
+    grade: null,
+    coverage: null,
+    reason: "No deployed recovery component",
+    evidence: "architecture.md:9",
+  };
+  assert.equal(scoreOverall(pillars, { confidence: "high" }), 10);
+  pillars[9] = { id: 10, status: "not_applicable", grade: null, coverage: null };
+  assert.throws(() => scoreOverall(pillars), /reason and evidence/);
+  pillars[9] = {
+    id: 10,
+    status: "not_applicable",
+    grade: null,
+    coverage: null,
+    reason: "No deployed recovery component",
+    evidence: true,
+  };
+  assert.throws(() => scoreOverall(pillars), /reason and evidence/);
+});

package/templates/.agents/skills/zaip-skill-data-modeling/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: zaip-skill-data-modeling
+description: Model persistent data, ownership, constraints, tenancy, and query needs before database implementation.
+---
+
+# Model data
+
+Use before new tables, meaningful relationships, or persistent state changes.
+
+1. Define entities, lifecycle, owner module, tenant boundary, invariants, retention, and read paths from concrete use cases.
+2. Choose keys, constraints, indexes, and deletion semantics from query and integrity needs; do not copy a generic schema.
+3. Identify sensitive attributes and authorization paths. Account-scoped data must carry an explicit tenant context through every access path.
+4. Record backward compatibility and data backfill needs. Delegate schema rollout to `$zaip-skill-database-migrations`.
+5. Validate the model against invalid state, cross-tenant access, and the expected query volume.

package/templates/.agents/skills/zaip-skill-data-modeling/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Data Modeling"
+  short_description: "Model owned data and query constraints"
+  default_prompt: "Use $zaip-skill-data-modeling to model data ownership and constraints for this feature."

package/templates/.agents/skills/zaip-skill-database-migrations/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: zaip-skill-database-migrations
+description: Plan and verify compatible database schema migrations, backfills, typed access, and recovery paths.
+---
+
+# Evolve database schemas
+
+Use when PostgreSQL or Supabase schema changes affect an existing application.
+
+1. Establish the current schema, deployed application versions, data volume, compatibility window, and the single authoritative migrator before writing a migration. Read `references/promotion-example.md` for an expand/contract change.
+2. For Supabase, create a request with the verified source `owner/repository`, source SHA, stable request ID, SQL path, tests and risk. The database PR title is `[owner/repository] description` and its only automatic target is `beta` in the configured database repository. An authorized configured workflow must publish its proposal head before the CLI opens the PR; no generic agent push permission or migration to `main` is granted.
+3. Do not create a Supabase branch, preview project, hosted integration, or paid resource implicitly. Explain the recurring beta cost and obtain informed human confirmation before any hosted provisioning. If beta integration is absent, prepare locally and stop before remote submission; never fall back to `main`. If the user explicitly refuses beta, use [manual mode](references/manual-mode.md) for the next migration.
+4. Supabase GitHub Integration is the only automated hosted migration applicator. In manual mode, a human may run the exported SQL in the Supabase SQL Editor; agents use READ-ONLY-BETA/READ-ONLY-PROD only for diagnosis and must never use remote SQL, `db push`, `apply_migration`, or startup migration execution.
+5. Serialize beta merges. Destructive, incompatible, RLS, permission, function or trigger changes require human review before beta and again for `beta -> main`.
+6. Prefer expand, deploy compatible readers and writers, backfill, verify, then contract. State transaction and lock expectations explicitly.
+7. Update typed Kysely access only after the migration contract is clear; keep migration execution separate from application deployment authority.
+8. Test a clean database and an upgrade from representative prior data, including retry and rollback or forward-repair behavior.
+9. Do not claim data safety without an observed backup or reversible recovery path.
+
+If beta was explicitly refused, do not use `prepare` or `submit` for that migration. Follow [manual mode](references/manual-mode.md); dependent work waits for the recorded human SQL Editor result.

package/templates/.agents/skills/zaip-skill-database-migrations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Database Migrations"
+  short_description: "Plan compatible schema migrations safely"
+  default_prompt: "Use $zaip-skill-database-migrations to plan and validate this schema change."

package/templates/.agents/skills/zaip-skill-database-migrations/references/manual-mode.md

@@ -0,0 +1,15 @@
+# Modo manual sem beta hospedada
+
+Use somente depois de o usuário recusar explicitamente a beta hospedada. A ausência de beta, a instalação e a configuração local não são uma recusa inferida.
+
+Para uma mudança futura, execute no Git root do repositório solicitante:
+
+```powershell
+node .agents/skills/zaip-skill-database-migrations/scripts/export-manual-sql.mjs --repository . --beta-declined --name criar-tabela-funcionalidade-meta-diagnosis --sql-file <arquivo-sql-preparado>
+```
+
+O helper usa o timezone do projeto ou UTC explicitamente, cria `/db-migrations/YYYY-MM-DD-HH-mm-slug.sql` apenas se concluir e usa `-2` em colisão sem sobrescrever. Sua saída declara `pending_human_execution`, caminho, hash e origem.
+
+O agente não faz deploy SQL, `db push`, `apply_migration`, pipeline de migration ou startup migration. Uma pessoa executa o arquivo no [Supabase SQL Editor](https://supabase.com/docs/guides/database/overview), seguindo a ordem, backup e revisão aplicáveis, e informa sucesso ou erro. Em caso de erro, não marque como concluído nem presuma rollback: uma pessoa verifica possível aplicação parcial antes de qualquer migration corretiva. Após sucesso humano, registre a evidência e retome somente as dependências dessa migration. O relato humano não é comprovação independente; registre sua fonte e qualquer observação verificável disponível. Se uma beta for adotada depois, reconcilie o histórico de migrations antes de retomar o fluxo protegido.
+
+Este modo não cria branch hospedada, preview, integração GitHub, secret, workflow ou custo Supabase.

package/templates/.agents/skills/zaip-skill-database-migrations/references/promotion-example.md

@@ -0,0 +1,5 @@
+# Compatible promotion example
+
+For a `display_name` rename, the authoritative migrator first adds nullable `public_name` and its index. A compatible application release writes both fields and reads `public_name ?? display_name`. A bounded backfill records progress and can safely resume. After verified completion and the compatibility window, a later migration makes `public_name` required and removes the old column.
+
+Only one migrator owns the migrations table and ordering. A failed backfill is recovered by rerunning an idempotent batch or forwarding a corrective migration; never hand-edit production schema state to make a migrator believe work succeeded.

package/templates/.agents/skills/zaip-skill-database-migrations/scripts/export-manual-sql.mjs

@@ -0,0 +1,145 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseDocument } from "../../zaip-skill-github-deploy/scripts/yaml-parser.mjs";
+
+// Local export only. The calling agent must have observed the user's actual refusal.
+export function exportManualSql({
+  repository = ".",
+  betaDeclined,
+  name,
+  sqlFile,
+  now = new Date(),
+}) {
+  if (betaDeclined !== true)
+    throw new Error("Explicit human beta refusal is required; no folder created.");
+  if (typeof name !== "string" || /[\\/]/.test(name))
+    throw new Error("Provide a descriptive name without path separators.");
+  const slug = name
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 100)
+    .replace(/-$/, "");
+  if (!slug) throw new Error("Provide a non-empty descriptive name.");
+  const root = realpathSync(git(resolve(repository), ["rev-parse", "--show-toplevel"]));
+  if (typeof sqlFile !== "string" || !sqlFile)
+    throw new Error("Provide --sql-file containing the prepared SQL.");
+  const sql = readFileSync(resolve(root, sqlFile), "utf8").replace(/^\uFEFF/, "");
+  if (!sql.trim() || sql.includes("\0"))
+    throw new Error("The prepared SQL must be non-empty UTF-8 text.");
+  const configPath = join(root, ".agents/config/project.yaml");
+  let timezone = "UTC";
+  if (existsSync(configPath)) {
+    const document = parseDocument(readFileSync(configPath, "utf8"), { uniqueKeys: true });
+    if (document.errors.length)
+      throw new Error("Invalid project configuration; no folder created.");
+    timezone = document.toJS()?.project?.timezone ?? "UTC";
+  }
+  if (typeof timezone !== "string" || !timezone) throw new Error("Invalid project timezone.");
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat("en-CA", {
+      timeZone: timezone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      hourCycle: "h23",
+    })
+      .formatToParts(now)
+      .map(({ type, value }) => [type, value]),
+  );
+  const timestamp = [parts.year, parts.month, parts.day, parts.hour, parts.minute].join("-");
+  const origin = git(root, ["remote", "get-url", "origin"], true);
+  const sourceRepository =
+    /^(?:git@github\.com:|https:\/\/github\.com\/|ssh:\/\/git@github\.com\/)([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(
+      origin,
+    )?.[1] ?? null;
+  const sourceSha = git(root, ["rev-parse", "--verify", "HEAD"], true) || null;
+  const body = [
+    "-- Manual SQL: pending human execution in the Supabase SQL Editor.",
+    "-- User declined hosted beta. No agent or pipeline may execute this file.",
+    `-- Source repository: ${sourceRepository ?? "unavailable"}; source SHA: ${sourceSha ?? "unavailable"}`,
+    `-- Prepared: ${now.toISOString()}; filename timezone: ${timezone}`,
+    "-- Review the target project, impact and recovery plan before running.",
+    "",
+    sql,
+    "",
+  ].join("\n");
+  const directory = join(root, "db-migrations");
+  // Validate everything before creating the optional directory; reject existing links/junctions.
+  try {
+    mkdirSync(directory);
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+  }
+  const stat = lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || realpathSync(directory) !== directory)
+    throw new Error("db-migrations must be a real directory directly inside the repository.");
+  for (let suffix = 1; suffix <= 1000; suffix++) {
+    const file = join(directory, `${timestamp}-${slug}${suffix === 1 ? "" : `-${suffix}`}.sql`);
+    try {
+      writeFileSync(file, body, { encoding: "utf8", flag: "wx" });
+    } catch (error) {
+      if (error.code === "EEXIST") continue;
+      throw error;
+    }
+    return {
+      status: "pending_human_execution",
+      file,
+      timezone,
+      sha256: createHash("sha256").update(body).digest("hex"),
+      source_repository: sourceRepository,
+      source_sha: sourceSha,
+      next_action:
+        "Human reviews and runs the SQL in the correct Supabase project's SQL Editor, then reports the result. Agent does not execute it.",
+    };
+  }
+  throw new Error("Too many filename collisions; choose another descriptive name.");
+}
+
+function git(repository, args, optional = false) {
+  const result = spawnSync("git", ["-C", repository, ...args], {
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+    timeout: 10000,
+  });
+  if (result.error || result.status !== 0) {
+    if (optional) return "";
+    throw new Error("Cannot resolve the local Git repository root.");
+  }
+  return result.stdout.trim();
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const args = process.argv.slice(2);
+    const options = {};
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i];
+      if (flag === "--beta-declined") options.betaDeclined = true;
+      else if (["--repository", "--name", "--sql-file"].includes(flag)) {
+        const value = args[++i];
+        if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value.`);
+        options[flag === "--sql-file" ? "sqlFile" : flag.slice(2)] = value;
+      } else throw new Error(`Unknown option: ${flag}`);
+    }
+    process.stdout.write(`${JSON.stringify(exportManualSql(options), null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}