avorelo 0.1.0

package/scripts/lib/publish-provenance-readiness.js

@@ -0,0 +1,283 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+const {
+  readPackageJson,
+  getPublishConfig,
+  getBinEntries,
+  runNpm,
+} = require("./package-runtime");
+
+const CONTRACT = "avorelo.publishProvenanceReadiness.v1";
+const SCHEMA_VERSION = 1;
+const ARTIFACT_DIR_REL = ".claude/cco/orchestration/public-distribution";
+const ARTIFACT_REL = ARTIFACT_DIR_REL + "/latest-publish-provenance-readiness.json";
+
+function safeReadText(absPath, maxChars) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return fs.readFileSync(absPath, "utf8").slice(0, maxChars || 4096);
+  } catch {
+    return null;
+  }
+}
+
+function pass(id, label, evidence, detail) {
+  return { id, label, status: "pass", evidence: evidence || null, detail: detail || null, safeNextAction: null };
+}
+
+function warn(id, label, safeNextAction, evidence, detail) {
+  return { id, label, status: "warn", evidence: evidence || null, detail: detail || null, safeNextAction: safeNextAction || "Review warning." };
+}
+
+function blocked(id, label, safeNextAction, evidence, detail) {
+  return { id, label, status: "blocked", evidence: evidence || null, detail: detail || null, safeNextAction: safeNextAction || "Fix blocker." };
+}
+
+function inspectPublishWorkflow(cwd) {
+  const checks = [];
+  const workflowDir = path.join(cwd, ".github", "workflows");
+  if (!fs.existsSync(workflowDir)) {
+    checks.push(warn("release_workflow_presence", "No release workflow found", "Add a gated release workflow when you are ready to automate publish."));
+    return { checks, workflowFiles: [] };
+  }
+
+  const workflowFiles = fs.readdirSync(workflowDir).filter((file) => /\.ya?ml$/i.test(file));
+  const releaseFiles = workflowFiles.filter((file) => /release|publish/i.test(file));
+  if (releaseFiles.length > 0) {
+    checks.push(pass("release_workflow_presence", "Release workflow(s) found", { files: releaseFiles }));
+  } else {
+    checks.push(warn("release_workflow_presence", "No release workflow found", "Add a gated release workflow when you are ready to automate publish.", { workflowFiles }));
+  }
+
+  let autoPublish = false;
+  for (const workflow of workflowFiles) {
+    const content = safeReadText(path.join(workflowDir, workflow), 8000) || "";
+    if (/npm publish/i.test(content) && !/workflow_dispatch|environment:|manual/i.test(content)) {
+      autoPublish = true;
+      break;
+    }
+  }
+
+  checks.push(
+    autoPublish
+      ? warn("no_auto_publish_in_ci", "Workflow may publish without an approval gate", "Add a manual or environment approval gate to npm publish steps.")
+      : pass("no_auto_publish_in_ci", "No ungated auto-publish detected", { workflowFilesChecked: workflowFiles.length })
+  );
+
+  return { checks, workflowFiles, autoPublish };
+}
+
+function inspectTrustedPublishingReadiness(cwd) {
+  const pkg = readPackageJson(cwd);
+  const publishConfig = getPublishConfig(pkg) || {};
+  const checks = [];
+  if (publishConfig.provenance === true) {
+    checks.push(pass("provenance_config_readiness", "publishConfig.provenance is enabled", { publishConfig }));
+  } else {
+    checks.push(warn("provenance_config_readiness", "publishConfig.provenance is not enabled", "Add publishConfig.provenance: true when you are ready for trusted publishing."));
+  }
+
+  const docsDir = path.join(cwd, "docs");
+  let documented = false;
+  if (fs.existsSync(docsDir)) {
+    const docFiles = fs.readdirSync(docsDir).filter((file) => file.endsWith(".md"));
+    documented = docFiles.some((file) => /trusted.?publishing|oidc|provenance/i.test(safeReadText(path.join(docsDir, file), 4000) || ""));
+  }
+
+  checks.push(
+    documented
+      ? pass("trusted_publishing_documented", "Trusted publishing is documented", { documented: true })
+      : warn("trusted_publishing_documented", "Trusted publishing is not documented", "Document the chosen publish path when you are ready to automate it.")
+  );
+
+  return {
+    checks,
+    provenanceConfigStatus: publishConfig.provenance === true ? "configured" : "not_configured",
+    trustedPublishingStatus: documented ? "documented" : "preferred_not_configured",
+  };
+}
+
+function inspectNpmTokenRisk(cwd) {
+  const checks = [pass("npm_publish_not_run", "npm publish is not run by this command", { safe: true })];
+  const npmrcPath = path.join(cwd, ".npmrc");
+  const npmrcText = safeReadText(npmrcPath, 2000) || "";
+  if (/_authToken|token|password|secret/i.test(npmrcText)) {
+    checks.push(blocked("no_long_lived_token_required", "Hardcoded npm token detected", "Remove npm tokens from .npmrc and use npm login or trusted publishing instead."));
+    checks.push(blocked("no_npm_token_in_repo", "npm token detected in tracked config", "Remove the tracked npm token immediately."));
+  } else {
+    checks.push(pass("no_long_lived_token_required", "No hardcoded npm token detected", { npmrcExists: fs.existsSync(npmrcPath) }));
+    checks.push(pass("no_npm_token_in_repo", "No npm token detected in tracked config", { checked: [".npmrc", "package.json"] }));
+  }
+  return { checks };
+}
+
+function inspectPackagePublishStatus(cwd) {
+  const pkg = readPackageJson(cwd);
+  const checks = [];
+  if (!pkg || typeof pkg.private !== "boolean") {
+    checks.push(warn("package_publish_status_known", "package.json private field is missing or invalid", "Set private explicitly in package.json."));
+    return { checks, isPrivate: null };
+  }
+  checks.push(pass("package_publish_status_known", "package.json private field is explicit", { private: pkg.private }));
+  checks.push(pass("private_or_public_status_known", "Private/public status is known", { private: pkg.private }));
+  return { checks, isPrivate: pkg.private === true };
+}
+
+function inspectNpmAuth(cwd, options = {}) {
+  if (options.npmWhoamiResult) return options.npmWhoamiResult;
+  return runNpm(["whoami"], {
+    cwd,
+    timeoutMs: 60000,
+    cacheLabel: "npm-whoami",
+  });
+}
+
+function buildPublishProvenanceReadiness(cwd, options = {}) {
+  const pkg = readPackageJson(cwd);
+  const publishConfig = getPublishConfig(pkg) || {};
+  const binEntries = getBinEntries(pkg);
+  const packageAudit = options.packageAudit || require("./package-content-audit").buildPackageContentAudit(cwd, options);
+  const installClaims = options.installClaims || require("./public-install-claim-checker").validateInstallClaims(cwd, options);
+  const packageSmoke = options.packageSmoke || require("./local-package-smoke").runLocalPackageSmoke(cwd, options);
+  const statusResult = inspectPackagePublishStatus(cwd, options);
+  const workflowResult = inspectPublishWorkflow(cwd, options);
+  const trustedResult = inspectTrustedPublishingReadiness(cwd, options);
+  const tokenResult = inspectNpmTokenRisk(cwd, options);
+  const npmWhoami = inspectNpmAuth(cwd, options);
+  const publishApproved = (options.env || process.env).AVORELO_ALLOW_NPM_PUBLISH === "1";
+
+  const auth = npmWhoami.success
+    ? { status: "authenticated", username: (npmWhoami.stdout || "").trim() || null }
+    : /ENEEDAUTH|not logged in|login/i.test((npmWhoami.errorSummary || "") + " " + (npmWhoami.stderr || ""))
+      ? { status: "auth_required", username: null }
+      : { status: "unknown", username: null };
+
+  const readyToPublish = !!(
+    pkg &&
+    pkg.private === false &&
+    publishConfig.access === "public" &&
+    binEntries.avorelo === "bin/avorelo" &&
+    packageAudit &&
+    packageAudit.ok === true &&
+    packageSmoke &&
+    packageSmoke.passed === true &&
+    installClaims &&
+    installClaims.ok === true
+  );
+
+  const publishedVerified = !!(options.publicSmoke && options.publicSmoke.passed && auth.status === "authenticated" && publishApproved);
+  const checks = [
+    ...statusResult.checks,
+    ...workflowResult.checks,
+    ...trustedResult.checks,
+    ...tokenResult.checks,
+    pkg && pkg.private === true
+      ? pass("local_distribution_ready", "Private package is not publish-ready by design", { private: true }, "Private package can stay local-only until publish closure is complete.")
+      : readyToPublish
+        ? pass("local_distribution_ready", "Package audit, smoke, and claims all passed", {
+          packageAudit: packageAudit ? packageAudit.status : null,
+          packageSmoke: packageSmoke ? packageSmoke.status : null,
+          installClaims: installClaims ? installClaims.status : null,
+        })
+        : blocked("local_distribution_ready", "Local distribution checks are incomplete", "Run package-audit, package-smoke, and install-claims until they all pass."),
+    auth.status === "authenticated"
+      ? pass("npm_auth_status", "npm auth is available", { username: auth.username })
+      : auth.status === "auth_required"
+        ? warn("npm_auth_status", "npm auth is required", "Run npm adduser before publishing.")
+        : warn("npm_auth_status", "npm auth status is unknown", "Retry npm whoami in a network-enabled shell."),
+    publishApproved
+      ? pass("publish_approval_status", "Publish approval environment flag is present", { publishApproved: true })
+      : warn("publish_approval_status", "Publish approval environment flag is missing", "Set AVORELO_ALLOW_NPM_PUBLISH=1 before running npm publish."),
+  ];
+
+  const blockers = checks.filter((check) => check.status === "blocked").map((check) => check.id);
+  const warnings = checks.filter((check) => check.status === "warn").map((check) => check.id);
+  const status = blockers.length > 0
+    ? "blocked"
+    : pkg && pkg.private === true
+      ? "not_applicable"
+      : (auth.status === "authenticated" && publishApproved ? "pass" : "warn");
+  const packagePublishStatus = pkg && pkg.private === false ? "public_ready" : (pkg && pkg.private === true ? "private" : "unknown");
+  const publishCommand = "AVORELO_ALLOW_NPM_PUBLISH=1 npm publish --access public";
+  const safeNextAction = blockers.length > 0
+    ? "Fix the blocked local distribution checks before publish."
+    : pkg && pkg.private === true
+      ? "Package is still private. Finish public package closure before publish."
+      : auth.status !== "authenticated"
+      ? "Run npm adduser, then " + publishCommand
+      : !publishApproved
+        ? publishCommand
+        : publishedVerified
+          ? "Public npm distribution is already verified."
+          : publishCommand;
+
+  const readiness = {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: nowIso(),
+    status,
+    readyToPublish,
+    publishedVerified,
+    publishApproved,
+    auth,
+    packagePublishStatus,
+    trustedPublishingStatus: trustedResult.trustedPublishingStatus,
+    provenanceConfigStatus: trustedResult.provenanceConfigStatus,
+    releaseWorkflowStatus: workflowResult.workflowFiles.length > 0 ? "present" : "absent",
+    checks,
+    blockers,
+    warnings,
+    npmWhoamiResult: npmWhoami.success ? (npmWhoami.stdout || "").trim() : (npmWhoami.errorSummary || ""),
+    packageAuditStatus: packageAudit ? packageAudit.status : "missing",
+    packageSmokeStatus: packageSmoke ? packageSmoke.status : "missing",
+    installClaimsStatus: installClaims ? installClaims.status : "missing",
+    publishCommand,
+    safeNextAction,
+    noPublicLaunchClaim: true,
+    redacted: true,
+  };
+
+  try {
+    appendProductLearningEvent(cwd, {
+      event: "publish_provenance_readiness_built",
+      contract: CONTRACT,
+      status,
+      readyToPublish,
+      authStatus: auth.status,
+      publishApproved,
+    });
+  } catch {}
+
+  return readiness;
+}
+
+function writePublishProvenanceReadiness(cwd, readiness) {
+  const dir = path.join(cwd, ARTIFACT_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(cwd, ARTIFACT_REL), JSON.stringify(readiness, null, 2));
+}
+
+function formatPublishProvenanceText(readiness) {
+  return [
+    "Publish Provenance Readiness [" + String(readiness.status || "unknown").toUpperCase() + "]",
+    "  readyToPublish: " + readiness.readyToPublish,
+    "  npm auth: " + readiness.auth.status + (readiness.auth.username ? " (" + readiness.auth.username + ")" : ""),
+    "  publishApproved: " + readiness.publishApproved,
+    "  Blockers: " + readiness.blockers.length,
+    "  Warnings: " + readiness.warnings.length,
+    "  Next: " + readiness.safeNextAction,
+  ].join("\n");
+}
+
+module.exports = {
+  buildPublishProvenanceReadiness,
+  inspectPublishWorkflow,
+  inspectTrustedPublishingReadiness,
+  inspectNpmTokenRisk,
+  writePublishProvenanceReadiness,
+  formatPublishProvenanceText,
+};

package/scripts/lib/readiness-delta.js

@@ -0,0 +1,218 @@
+"use strict";
+
+// ── Readiness Delta ───────────────────────────────────────────────────────────
+// Contract: avorelo.readinessDelta.v1
+//
+// Compares two full-readiness gate snapshots and surfaces what changed
+// between them: score movement, new passes/warnings/blockers, evidence gaps closed.
+// Read-only, deterministic, no network, no external calls.
+// Honest insufficient_data when snapshots are missing or incomparable.
+
+const fs = require("fs");
+const path = require("path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.readinessDelta.v1";
+const SCHEMA_VERSION = 1;
+const DELTA_DIR_REL = ".claude/cco/orchestration/readiness-delta";
+const ARTIFACT_REL = DELTA_DIR_REL + "/latest-readiness-delta.json";
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch { return null; }
+}
+
+function listKeyed(items) {
+  if (!Array.isArray(items)) return {};
+  var out = {};
+  items.forEach(function(item) {
+    if (item && item.checkId) out[item.checkId] = item;
+  });
+  return out;
+}
+
+// ── Core delta logic ──────────────────────────────────────────────────────────
+
+function computeReadinessDelta(snapshotA, snapshotB) {
+  if (!snapshotA || !snapshotB) {
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "insufficient_data",
+      reason: !snapshotA ? "snapshot_a_missing" : "snapshot_b_missing",
+      scoreDelta: null,
+      statusChanged: false,
+      newPasses: [],
+      newWarnings: [],
+      newBlockers: [],
+      resolvedWarnings: [],
+      resolvedBlockers: [],
+      evidenceGapsClosed: [],
+      noPublicLaunchClaim: true,
+      redacted: true,
+    };
+  }
+
+  var scoreA = typeof snapshotA.score === "number" ? snapshotA.score : null;
+  var scoreB = typeof snapshotB.score === "number" ? snapshotB.score : null;
+  var scoreDelta = (scoreA !== null && scoreB !== null) ? (scoreB - scoreA) : null;
+
+  var passesA = listKeyed(snapshotA.passes);
+  var passesB = listKeyed(snapshotB.passes);
+  var warningsA = listKeyed(snapshotA.warnings);
+  var warningsB = listKeyed(snapshotB.warnings);
+  var blockersA = listKeyed(snapshotA.blockers);
+  var blockersB = listKeyed(snapshotB.blockers);
+
+  // New passes: in B passes but not in A passes
+  var newPasses = Object.keys(passesB).filter(function(k) { return !passesA[k]; }).map(function(k) { return passesB[k]; });
+  // New warnings: in B warnings but not in A warnings
+  var newWarnings = Object.keys(warningsB).filter(function(k) { return !warningsA[k]; }).map(function(k) { return warningsB[k]; });
+  // New blockers: in B blockers but not in A blockers
+  var newBlockers = Object.keys(blockersB).filter(function(k) { return !blockersA[k]; }).map(function(k) { return blockersB[k]; });
+  // Resolved warnings: in A warnings but now in B passes
+  var resolvedWarnings = Object.keys(warningsA).filter(function(k) { return passesB[k]; }).map(function(k) { return warningsA[k]; });
+  // Resolved blockers: in A blockers but now in B passes or warnings
+  var resolvedBlockers = Object.keys(blockersA).filter(function(k) { return passesB[k] || warningsB[k]; }).map(function(k) { return blockersA[k]; });
+
+  // Evidence gaps closed: items missing in A but present in B (check evidence closure if available)
+  var evidenceGapsClosed = [];
+  if (snapshotA.evidenceGaps && snapshotB.evidenceGaps) {
+    var gapsA = new Set(Array.isArray(snapshotA.evidenceGaps) ? snapshotA.evidenceGaps : []);
+    var gapsB = new Set(Array.isArray(snapshotB.evidenceGaps) ? snapshotB.evidenceGaps : []);
+    gapsA.forEach(function(g) { if (!gapsB.has(g)) evidenceGapsClosed.push(g); });
+  }
+
+  var statusChanged = snapshotA.status !== snapshotB.status || snapshotA.releaseCandidateStatus !== snapshotB.releaseCandidateStatus;
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status: "ready",
+    fromScore: scoreA,
+    toScore: scoreB,
+    scoreDelta: scoreDelta,
+    fromStatus: snapshotA.status || null,
+    toStatus: snapshotB.status || null,
+    fromRcStatus: snapshotA.releaseCandidateStatus || null,
+    toRcStatus: snapshotB.releaseCandidateStatus || null,
+    statusChanged: statusChanged,
+    newPasses: newPasses,
+    newWarnings: newWarnings,
+    newBlockers: newBlockers,
+    resolvedWarnings: resolvedWarnings,
+    resolvedBlockers: resolvedBlockers,
+    evidenceGapsClosed: evidenceGapsClosed,
+    noPublicLaunchClaim: true,
+    redacted: true,
+  };
+}
+
+// ── Convenience: load gate snapshots from disk ────────────────────────────────
+
+function loadGateSnapshots(cwd, opts) {
+  opts = opts || {};
+  var gateArtifactRel = ".claude/cco/orchestration/full-readiness/latest-gate.json";
+  var historyDir = path.join(cwd, ".claude/cco/orchestration/full-readiness/history");
+  var current = safeReadJson(path.join(cwd, gateArtifactRel));
+  var previous = null;
+
+  if (fs.existsSync(historyDir)) {
+    var files = fs.readdirSync(historyDir)
+      .filter(function(f) { return f.endsWith(".json"); })
+      .sort()
+      .reverse();
+    if (files.length > 0) {
+      previous = safeReadJson(path.join(historyDir, files[0]));
+    }
+  }
+
+  // Also allow explicit snapshot paths
+  if (opts.snapshotAPath) previous = safeReadJson(opts.snapshotAPath) || previous;
+  if (opts.snapshotBPath) current = safeReadJson(opts.snapshotBPath) || current;
+
+  return { snapshotA: previous, snapshotB: current };
+}
+
+function buildReadinessDelta(cwd, opts) {
+  opts = opts || {};
+  var snapshots = loadGateSnapshots(cwd, opts);
+  return computeReadinessDelta(snapshots.snapshotA, snapshots.snapshotB);
+}
+
+function writeReadinessDelta(cwd, delta) {
+  var dir = path.join(cwd, DELTA_DIR_REL);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(cwd, ARTIFACT_REL), JSON.stringify(delta, null, 2));
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName: "readiness_delta_built",
+      category: "full_readiness",
+      status: delta.status,
+      scoreDelta: delta.scoreDelta,
+      statusChanged: delta.statusChanged,
+    });
+  } catch (e) {}
+  return delta;
+}
+
+function formatReadinessDeltaText(delta, opts) {
+  opts = opts || {};
+  var lines = [];
+  if (delta.status === "insufficient_data") {
+    lines.push("Readiness delta: insufficient_data (" + (delta.reason || "unknown") + ")");
+    lines.push("Run the full-readiness gate at least once to see a delta.");
+    return lines.join("\n");
+  }
+  lines.push("Readiness delta");
+  if (delta.fromScore !== null && delta.toScore !== null) {
+    var sign = delta.scoreDelta >= 0 ? "+" : "";
+    lines.push("Score: " + delta.fromScore + " → " + delta.toScore + " (" + sign + delta.scoreDelta + ")");
+  }
+  if (delta.statusChanged) {
+    lines.push("Status: " + delta.fromStatus + " → " + delta.toStatus);
+    if (delta.fromRcStatus !== delta.toRcStatus) {
+      lines.push("RC status: " + delta.fromRcStatus + " → " + delta.toRcStatus);
+    }
+  }
+  if (delta.resolvedBlockers && delta.resolvedBlockers.length > 0) {
+    lines.push("Resolved blockers (" + delta.resolvedBlockers.length + "):");
+    delta.resolvedBlockers.forEach(function(b) { lines.push("  ✓ " + (b.checkId || b)); });
+  }
+  if (delta.resolvedWarnings && delta.resolvedWarnings.length > 0) {
+    lines.push("Resolved warnings (" + delta.resolvedWarnings.length + "):");
+    delta.resolvedWarnings.forEach(function(w) { lines.push("  ✓ " + (w.checkId || w)); });
+  }
+  if (delta.newBlockers && delta.newBlockers.length > 0) {
+    lines.push("New blockers (" + delta.newBlockers.length + "):");
+    delta.newBlockers.forEach(function(b) { lines.push("  ✗ " + (b.checkId || b)); });
+  }
+  if (delta.newWarnings && delta.newWarnings.length > 0) {
+    lines.push("New warnings (" + delta.newWarnings.length + "):");
+    delta.newWarnings.forEach(function(w) { lines.push("  ⚠ " + (w.checkId || w)); });
+  }
+  if (delta.newPasses && delta.newPasses.length > 0) {
+    lines.push("New passes (" + delta.newPasses.length + "):");
+    delta.newPasses.forEach(function(p) { lines.push("  ✓ " + (p.checkId || p)); });
+  }
+  if (delta.evidenceGapsClosed && delta.evidenceGapsClosed.length > 0) {
+    lines.push("Evidence gaps closed: " + delta.evidenceGapsClosed.join(", "));
+  }
+  lines.push("No public launch claim.");
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  ARTIFACT_REL,
+  computeReadinessDelta,
+  buildReadinessDelta,
+  writeReadinessDelta,
+  formatReadinessDeltaText,
+};