avorelo 0.1.0

package/scripts/lib/package-content-audit.js

@@ -0,0 +1,368 @@
+"use strict";
+
+// ── Package Content Audit ─────────────────────────────────────────────────────
+// Contract: avorelo.packageContentAudit.v1
+// Answers: "What files would npm publish include, and are any forbidden/suspicious?"
+// Uses npm pack --dry-run. Never runs npm publish.
+
+const fs = require("fs");
+const path = require("path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+const {
+  readPackageJson,
+  getBinEntries,
+  getPublishConfig,
+  runNpm,
+  normalizeRelativePath,
+  collectRuntimeDependencyGraph,
+  findMissingRuntimeDependencies,
+  getPublicRuntimeEntryFiles,
+} = require("./package-runtime");
+
+const CONTRACT = "avorelo.packageContentAudit.v1";
+const SCHEMA_VERSION = 1;
+const ARTIFACT_DIR_REL = ".claude/cco/orchestration/public-distribution";
+const ARTIFACT_REL = ARTIFACT_DIR_REL + "/latest-package-content-audit.json";
+
+const FORBIDDEN_PATTERNS = [
+  // .env files — but NOT .example files (those are safe templates)
+  { pattern: /^\.env($|\.[^e]|\.[e][^x]|\.[ex][^a])/i, reason: "env file (not example)" },
+  // Actual secret stores — NOT source files that merely mention secrets
+  { pattern: /\.env\.local$/i, reason: ".env.local file" },
+  { pattern: /\.env\.production$/i, reason: ".env.production file" },
+  { pattern: /\.env\.development$/i, reason: ".env.development file" },
+  { pattern: /npm-token/i, reason: "npm token file" },
+  { pattern: /\.npmtoken$/i, reason: "npm token file" },
+  { pattern: /\.npmrc$/, reason: ".npmrc (may contain tokens)" },
+  { pattern: /^\.claude\//i, reason: "claude runtime state" },
+  { pattern: /^\.avorelo\//i, reason: "avorelo runtime state" },
+  { pattern: /^\.wuz\//i, reason: "wuz runtime state (internal)" },
+  { pattern: /^artifacts\//i, reason: "runtime artifacts" },
+  { pattern: /^apps\/public-web\//i, reason: "public website source" },
+  { pattern: /^tests?\//i, reason: "test files" },
+  { pattern: /^docs\//i, reason: "docs not required at runtime" },
+  { pattern: /^deferred\//i, reason: "deferred sources" },
+  { pattern: /^dist\//i, reason: "build output" },
+  { pattern: /^screenshots?\//i, reason: "screenshots" },
+  { pattern: /^reports?\//i, reason: "generated reports" },
+  { pattern: /^\.git\//i, reason: "git internals" },
+  /^node_modules\//i,
+  /\.tgz$/i,
+];
+
+const SUSPICIOUS_PATTERNS = [
+  /^tests?\//i,
+  /^spec\//i,
+  /^e2e-tests?\//i,
+  /^\.github\//i,
+  /\.log$/i,
+  /^screenshots?\//i,
+  /^videos?\//i,
+  /\.backup$/i,
+  /^docs\/dogfood\//i,
+  /^docs\/feedback\//i,
+];
+
+const REQUIRED_FILES = [
+  "package.json",
+  "bin/avorelo",
+  "scripts/lib/public-cli.js",
+];
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch { return null; }
+}
+
+// ── npm pack --dry-run ────────────────────────────────────────────────────────
+
+function runNpmPackDryRun(cwd, options) {
+  const result = runNpm(["pack", "--dry-run", "--json"], {
+    cwd,
+    timeoutMs: 30000,
+    cacheLabel: "package-audit",
+  });
+  return {
+    success: result.success,
+    output: result.stdout || "",
+    stderr: result.stderr || "",
+    combinedOutput: result.combinedOutput || "",
+    errorSummary: result.errorSummary || "",
+  };
+}
+
+// ── Parse npm pack output ─────────────────────────────────────────────────────
+
+function parseNpmPackOutput(output, options) {
+  const trimmedOutput = (output || "").trim();
+  if (trimmedOutput.startsWith("[")) {
+    try {
+      const parsedJson = JSON.parse(trimmedOutput);
+      const firstEntry = Array.isArray(parsedJson) ? parsedJson[0] : parsedJson;
+      const files = Array.isArray(firstEntry && firstEntry.files)
+        ? firstEntry.files.map(function(entry) { return entry.path; })
+        : [];
+      return {
+        files,
+        totalFiles: firstEntry && typeof firstEntry.entryCount === "number" ? firstEntry.entryCount : files.length,
+        totalSizeEstimate: firstEntry && typeof firstEntry.size === "number" ? String(firstEntry.size) + " bytes" : "unknown",
+      };
+    } catch {
+      // Fall through to legacy npm notice parsing below.
+    }
+  }
+
+  // npm pack --dry-run format (npm v7+):
+  // npm notice === Tarball Contents ===
+  // npm notice  1.2kB  package.json
+  // npm notice 12.3kB  bin/avorelo
+  // ...
+  // npm notice === Tarball Details ===
+  // npm notice total files: N
+  // npm notice bundled size: X bytes
+  const files = [];
+  let totalSizeEstimate = null;
+  let totalFiles = null;
+
+  const lines = output.split("\n");
+  let inContents = false;
+
+  for (const line of lines) {
+    // Detect section header
+    if (/tarball contents/i.test(line)) { inContents = true; continue; }
+    if (/tarball details/i.test(line)) { inContents = false; continue; }
+
+    if (inContents) {
+      // Match: "npm notice  1.2kB  some/path/file.js"
+      const m = line.match(/npm\s+notice\s+[\d.]+\s*[kKmMbB]+\s+(.+)/);
+      if (m) {
+        files.push(m[1].trim());
+      }
+    }
+
+    // Also look for "total files:" line
+    const totalM = line.match(/total files:\s*(\d+)/i);
+    if (totalM) totalFiles = parseInt(totalM[1], 10);
+
+    const sizeM = line.match(/package size:\s*(.+)/i);
+    if (sizeM) totalSizeEstimate = sizeM[1].trim();
+  }
+
+  // Fallback: if npm pack outputs lines without "npm notice" prefix
+  if (files.length === 0) {
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("npm") && !trimmed.startsWith("{") && trimmed.includes("/")) {
+        files.push(trimmed);
+      }
+    }
+  }
+
+  // Deduplicate (combined stderr+stdout can have dupes)
+  const uniqueFiles = Array.from(new Set(files));
+  return { files: uniqueFiles, totalFiles: totalFiles || uniqueFiles.length, totalSizeEstimate: totalSizeEstimate || "unknown" };
+}
+
+// ── Audit the file list ───────────────────────────────────────────────────────
+
+function auditPackFileList(fileList, options) {
+  const forbiddenFiles = [];
+  const suspiciousFiles = [];
+  const requiredPresent = [];
+  const requiredMissing = [];
+
+  for (const f of fileList) {
+    const normalized = normalizeRelativePath(f);
+
+    // .example files are safe templates, never forbidden
+    if (/\.example$/i.test(normalized)) { /* skip forbidden check */ }
+    else {
+      for (const entry of FORBIDDEN_PATTERNS) {
+        const pat = entry.pattern || entry;
+        if (pat.test(normalized)) {
+          forbiddenFiles.push(f);
+          break;
+        }
+      }
+    }
+
+    for (const pat of SUSPICIOUS_PATTERNS) {
+      if (pat.test(normalized)) {
+        suspiciousFiles.push(f);
+        break;
+      }
+    }
+  }
+
+  for (const req of REQUIRED_FILES) {
+    const found = fileList.some(function(f) {
+      return f.replace(/\\/g, "/") === req || f.replace(/\\/g, "/").endsWith("/" + req);
+    });
+    if (found) {
+      requiredPresent.push(req);
+    } else {
+      requiredMissing.push(req);
+    }
+  }
+
+  return { forbiddenFiles, suspiciousFiles, requiredPresent, requiredMissing };
+}
+
+// ── Build audit ───────────────────────────────────────────────────────────────
+
+function buildPackageContentAudit(cwd, options) {
+  const pkg = readPackageJson(cwd);
+  const binEntries = getBinEntries(pkg);
+  const publishConfig = getPublishConfig(pkg);
+  const filesAllowlist = Array.isArray(pkg && pkg.files) ? pkg.files.slice() : [];
+  const runtimeGraph = collectRuntimeDependencyGraph(cwd, {
+    entryFiles: getPublicRuntimeEntryFiles(cwd),
+  });
+  const missingRuntimeDependencies = findMissingRuntimeDependencies(pkg, runtimeGraph);
+  const runResult = options && options.npmPackResult ? options.npmPackResult : runNpmPackDryRun(cwd, options);
+  const metadataProblems = [];
+
+  if (!pkg) metadataProblems.push("package.json missing or invalid");
+  if (pkg && pkg.name !== "avorelo") metadataProblems.push("package name must be avorelo");
+  if (pkg && !pkg.version) metadataProblems.push("package version missing");
+  if (pkg && pkg.private !== false) metadataProblems.push("package private flag must be false for ready_to_publish");
+  if (!publishConfig || publishConfig.access !== "public") metadataProblems.push("publishConfig.access must be public");
+  if (!binEntries.avorelo || binEntries.avorelo !== "bin/avorelo") metadataProblems.push("bin.avorelo must point to bin/avorelo");
+  if (filesAllowlist.length === 0) metadataProblems.push("package files allowlist missing");
+  if (missingRuntimeDependencies.length > 0) metadataProblems.push("runtime dependencies must be present in dependencies: " + missingRuntimeDependencies.join(", "));
+  if (runtimeGraph.missingLocalFiles.length > 0) metadataProblems.push("runtime graph references missing local files: " + runtimeGraph.missingLocalFiles.join(", "));
+
+  if (!runResult.success) {
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      generatedAt: nowIso(),
+      status: "not_available",
+      ok: false,
+      packageName: pkg && pkg.name ? pkg.name : null,
+      version: pkg && pkg.version ? pkg.version : null,
+      private: pkg ? pkg.private : null,
+      publishConfig,
+      binEntries,
+      filesAllowlist,
+      runtimeExternalDependencies: runtimeGraph.externalPackages,
+      runtimeDependenciesOk: missingRuntimeDependencies.length === 0 && runtimeGraph.missingLocalFiles.length === 0,
+      missingRuntimeDependencies,
+      missingLocalRuntimeFiles: runtimeGraph.missingLocalFiles,
+      runtimeFilesMissingFromPack: runtimeGraph.localFiles,
+      distributionState: "publish_blocked",
+      npmPackDryRunAvailable: false,
+      packageFiles: [],
+      fileCount: 0,
+      totalSizeEstimate: "unknown",
+      forbiddenFiles: [],
+      suspiciousFiles: [],
+      requiredFiles: { present: [], missing: REQUIRED_FILES },
+      missingRequiredFiles: REQUIRED_FILES,
+      metadataProblems,
+      safeNextAction: "npm pack --dry-run failed. Verify npm is available and package.json is valid.",
+      noPublicLaunchClaim: true,
+      redacted: true,
+    };
+  }
+
+  const combined = runResult.combinedOutput || [runResult.output, runResult.stderr].filter(Boolean).join("\n");
+  const parsed = parseNpmPackOutput(combined, options);
+  const { forbiddenFiles, suspiciousFiles, requiredPresent, requiredMissing } = auditPackFileList(parsed.files, options);
+  const packedFiles = new Set(parsed.files.map((entry) => normalizeRelativePath(entry)));
+  const runtimeFilesMissingFromPack = runtimeGraph.localFiles.filter((filePath) => !packedFiles.has(filePath));
+
+  let status;
+  if (metadataProblems.length > 0 || forbiddenFiles.length > 0 || runtimeFilesMissingFromPack.length > 0) {
+    status = "fail";
+  } else if (suspiciousFiles.length > 0 || requiredMissing.length > 0) {
+    status = "warn";
+  } else {
+    status = "pass";
+  }
+
+  const safeNextAction = metadataProblems.length > 0
+    ? "Fix package metadata before publish. Name/bin/private/publishConfig/files must all be explicit."
+    : forbiddenFiles.length > 0
+    ? "Add forbidden files to .npmignore immediately. Do not publish until resolved."
+    : runtimeFilesMissingFromPack.length > 0
+    ? "Ensure all runtime files required by the packed public CLI are included in the publish surface."
+    : requiredMissing.length > 0
+    ? "Verify required files (" + requiredMissing.join(", ") + ") will be included in the published package."
+    : suspiciousFiles.length > 0
+    ? "Review suspicious files and add to .npmignore if not needed in published package."
+    : "Package content audit passed. Proceed to local package smoke test.";
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: nowIso(),
+    status,
+    ok: status === "pass",
+    packageName: pkg && pkg.name ? pkg.name : null,
+    version: pkg && pkg.version ? pkg.version : null,
+    private: pkg ? pkg.private : null,
+    publishConfig,
+    binEntries,
+    filesAllowlist,
+    runtimeExternalDependencies: runtimeGraph.externalPackages,
+    runtimeDependenciesOk: missingRuntimeDependencies.length === 0 && runtimeGraph.missingLocalFiles.length === 0,
+    missingRuntimeDependencies,
+    missingLocalRuntimeFiles: runtimeGraph.missingLocalFiles,
+    runtimeFilesMissingFromPack,
+    distributionState: status === "pass" ? "ready_to_publish" : "publish_blocked",
+    npmPackDryRunAvailable: true,
+    packageFiles: parsed.files,
+    fileCount: parsed.totalFiles,
+    totalSizeEstimate: parsed.totalSizeEstimate,
+    forbiddenFiles,
+    suspiciousFiles,
+    requiredFiles: { present: requiredPresent, missing: requiredMissing },
+    missingRequiredFiles: requiredMissing,
+    metadataProblems,
+    safeNextAction,
+    noPublicLaunchClaim: true,
+    redacted: true,
+  };
+}
+
+// ── Write ─────────────────────────────────────────────────────────────────────
+
+function writePackageContentAudit(cwd, audit) {
+  const dir = path.join(cwd, ARTIFACT_DIR_REL);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(cwd, ARTIFACT_REL), JSON.stringify(audit, null, 2));
+}
+
+// ── Format ────────────────────────────────────────────────────────────────────
+
+function formatPackageContentAuditText(audit, options) {
+  if (!audit.npmPackDryRunAvailable) {
+    return "Package Content Audit [NOT_AVAILABLE]\n  npm pack --dry-run failed. Cannot audit file list.";
+  }
+  const lines = [
+    "Package Content Audit [" + audit.status.toUpperCase() + "]",
+    "  Package: " + (audit.packageName || "?") + "@" + (audit.version || "?"),
+    "  Private: " + audit.private,
+    "  publishConfig: " + JSON.stringify(audit.publishConfig || null),
+    "  Files: " + audit.fileCount + " (" + audit.totalSizeEstimate + ")",
+    "  Forbidden: " + audit.forbiddenFiles.length,
+    "  Suspicious: " + audit.suspiciousFiles.length,
+    "  Required present: " + audit.requiredFiles.present.length + "/" + REQUIRED_FILES.length,
+    "  Missing required: " + (audit.missingRequiredFiles.join(", ") || "none"),
+    "  Next: " + audit.safeNextAction,
+  ];
+  return lines.join("\n");
+}
+
+module.exports = {
+  runNpmPackDryRun,
+  parseNpmPackOutput,
+  auditPackFileList,
+  buildPackageContentAudit,
+  writePackageContentAudit,
+  formatPackageContentAuditText,
+};

package/scripts/lib/package-runtime.js

@@ -0,0 +1,278 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { builtinModules } = require("module");
+
+const BUILTIN_MODULES = new Set([
+  ...builtinModules,
+  ...builtinModules.map((name) => name.replace(/^node:/, "")),
+  ...builtinModules.map((name) => (name.startsWith("node:") ? name : `node:${name}`)),
+]);
+const REQUIRE_PATTERN = /require\((["'])([^"']+)\1\)/g;
+const OPTIONAL_REQUIRE_LOOKAROUND = 240;
+
+function ensureDir(dirPath) {
+  if (!dirPath) return dirPath;
+  fs.mkdirSync(dirPath, { recursive: true });
+  return dirPath;
+}
+
+function readJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^\uFEFF/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function readPackageJson(cwd) {
+  return readJson(path.join(cwd, "package.json"));
+}
+
+function getBinEntries(pkg) {
+  if (!pkg || !pkg.bin) return {};
+  return typeof pkg.bin === "string" ? { [pkg.name || "avorelo"]: pkg.bin } : { ...pkg.bin };
+}
+
+function getPublishConfig(pkg) {
+  return pkg && pkg.publishConfig && typeof pkg.publishConfig === "object"
+    ? { ...pkg.publishConfig }
+    : null;
+}
+
+function createCacheDir(label = "default") {
+  const safeLabel = String(label).replace(/[^a-z0-9_-]+/gi, "-").toLowerCase();
+  return ensureDir(path.join(os.tmpdir(), "avorelo-npm-cache", safeLabel));
+}
+
+function createTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix || "avorelo-"));
+}
+
+function buildPackageManagerEnv(options = {}) {
+  const env = {
+    ...process.env,
+    ...(options.env || {}),
+  };
+  env.npm_config_cache = options.cacheDir || createCacheDir(options.cacheLabel || "default");
+  env.npm_config_update_notifier = "false";
+  env.npm_config_fund = "false";
+  env.npm_config_audit = "false";
+  env.npm_config_loglevel = env.npm_config_loglevel || "warn";
+  return env;
+}
+
+function runPackageManagerCommand(tool, args, options = {}) {
+  const commandArgs = Array.isArray(args) ? args.slice() : [];
+  const env = buildPackageManagerEnv(options);
+  const spawnCommand = process.platform === "win32" ? "cmd" : tool;
+  const spawnArgs = process.platform === "win32" ? ["/c", tool, ...commandArgs] : commandArgs;
+  const result = spawnSync(spawnCommand, spawnArgs, {
+    cwd: options.cwd || process.cwd(),
+    env,
+    encoding: "utf8",
+    timeout: options.timeoutMs || 120000,
+    stdio: "pipe",
+  });
+
+  const stdout = result.stdout || "";
+  const stderr = result.stderr || "";
+  return {
+    success: result.status === 0,
+    status: result.status,
+    signal: result.signal || null,
+    stdout,
+    stderr,
+    combinedOutput: [stdout, stderr].filter(Boolean).join("\n").trim(),
+    errorSummary: [stderr, stdout].find(Boolean) || (result.error ? String(result.error) : ""),
+    cacheDir: env.npm_config_cache,
+  };
+}
+
+function runNpm(args, options = {}) {
+  return runPackageManagerCommand("npm", args, options);
+}
+
+function runNpx(args, options = {}) {
+  return runPackageManagerCommand("npx", args, options);
+}
+
+function normalizeRelativePath(filePath) {
+  return String(filePath || "").replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function packageNameFromSpecifier(specifier) {
+  const normalized = String(specifier || "").replace(/^node:/, "");
+  if (!normalized || normalized.startsWith(".") || normalized.startsWith("/")) return null;
+  if (normalized.startsWith("@")) {
+    const parts = normalized.split("/");
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : normalized;
+  }
+  return normalized.split("/")[0];
+}
+
+function isFile(candidate) {
+  try {
+    return fs.existsSync(candidate) && fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function resolveLocalModule(fromFile, specifier) {
+  const absoluteBase = path.resolve(path.dirname(fromFile), specifier);
+  const candidates = [
+    `${absoluteBase}.js`,
+    `${absoluteBase}.json`,
+    path.join(absoluteBase, "index.js"),
+    path.join(absoluteBase, "index.json"),
+    absoluteBase,
+  ];
+  return candidates.find((candidate) => isFile(candidate)) || null;
+}
+
+function isLikelyOptionalRequire(source, matchIndex) {
+  const start = Math.max(0, matchIndex - OPTIONAL_REQUIRE_LOOKAROUND);
+  const end = Math.min(source.length, matchIndex + OPTIONAL_REQUIRE_LOOKAROUND);
+  const before = source.slice(start, matchIndex);
+  const after = source.slice(matchIndex, end);
+  return /\btry\s*\{[^{}]*$/s.test(before) && /\}\s*catch\b/s.test(after);
+}
+
+function getPublicRuntimeEntryFiles(cwd) {
+  const root = path.resolve(cwd);
+  return [
+    path.join(root, "scripts", "lib", "alpha-activation.js"),
+    path.join(root, "scripts", "cco-status.js"),
+    path.join(root, "scripts", "cco-dashboard.js"),
+  ].filter((filePath) => fs.existsSync(filePath));
+}
+
+function collectRuntimeDependencyGraph(cwd, options = {}) {
+  const root = path.resolve(cwd);
+  const entryFiles = (options.entryFiles || [path.join(root, "bin", "avorelo")]).map((filePath) => path.resolve(filePath));
+  const visited = new Set();
+  const externalPackages = new Set();
+  const localFiles = new Set();
+  const missingLocalFiles = new Set();
+  const queue = entryFiles.slice();
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || visited.has(current) || !fs.existsSync(current)) continue;
+    visited.add(current);
+    localFiles.add(normalizeRelativePath(path.relative(root, current)));
+
+    let source = "";
+    try {
+      source = fs.readFileSync(current, "utf8");
+    } catch {
+      continue;
+    }
+
+    REQUIRE_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = REQUIRE_PATTERN.exec(source)) !== null) {
+      const specifier = match[2];
+      const optionalRequire = isLikelyOptionalRequire(source, match.index);
+      if (!specifier) continue;
+      if (specifier.startsWith(".")) {
+        const resolved = resolveLocalModule(current, specifier);
+        if (resolved) {
+          queue.push(resolved);
+        } else if (!optionalRequire) {
+          missingLocalFiles.add(normalizeRelativePath(path.relative(root, path.resolve(path.dirname(current), specifier))));
+        }
+        continue;
+      }
+
+      const packageName = packageNameFromSpecifier(specifier);
+      if (!packageName || BUILTIN_MODULES.has(packageName) || BUILTIN_MODULES.has(specifier) || optionalRequire) continue;
+      externalPackages.add(packageName);
+    }
+  }
+
+  return {
+    entryFiles: entryFiles.map((filePath) => normalizeRelativePath(path.relative(root, filePath))),
+    localFiles: Array.from(localFiles).sort(),
+    externalPackages: Array.from(externalPackages).sort(),
+    missingLocalFiles: Array.from(missingLocalFiles).sort(),
+  };
+}
+
+function findMissingRuntimeDependencies(pkg, runtimeGraph) {
+  const dependencies = pkg && pkg.dependencies && typeof pkg.dependencies === "object" ? pkg.dependencies : {};
+  return (runtimeGraph && Array.isArray(runtimeGraph.externalPackages) ? runtimeGraph.externalPackages : [])
+    .filter((packageName) => !Object.prototype.hasOwnProperty.call(dependencies, packageName))
+    .sort();
+}
+
+function buildPathRedactions(paths = []) {
+  const redactions = [];
+  for (const value of paths) {
+    if (!value) continue;
+    const normalized = String(value);
+    redactions.push([normalized, "<redacted-temp-path>"]);
+    redactions.push([normalized.replace(/\\/g, "/"), "<redacted-temp-path>"]);
+    redactions.push([normalized.replace(/\\/g, "\\\\"), "<redacted-temp-path>"]);
+  }
+  return redactions.sort((left, right) => right[0].length - left[0].length);
+}
+
+function redactPathsInText(text, paths = []) {
+  if (typeof text !== "string" || !text) return text;
+  let redacted = text;
+  for (const [target, replacement] of buildPathRedactions(paths)) {
+    redacted = redacted.split(target).join(replacement);
+  }
+  return redacted;
+}
+
+function redactPathsInValue(value, paths = []) {
+  if (typeof value === "string") return redactPathsInText(value, paths);
+  if (Array.isArray(value)) return value.map((entry) => redactPathsInValue(entry, paths));
+  if (!value || typeof value !== "object") return value;
+  const next = {};
+  for (const [key, entry] of Object.entries(value)) {
+    next[key] = redactPathsInValue(entry, paths);
+  }
+  return next;
+}
+
+function mapDistributionStateToStatus(distributionState) {
+  switch (distributionState) {
+    case "publish_blocked":
+      return "blocked";
+    case "private_local_only":
+    case "local_verified":
+      return "local_only";
+    case "ready_to_publish":
+    case "published_verified":
+      return "pass";
+    default:
+      return "warn";
+  }
+}
+
+module.exports = {
+  ensureDir,
+  readJson,
+  readPackageJson,
+  getBinEntries,
+  getPublishConfig,
+  createCacheDir,
+  createTempDir,
+  runNpm,
+  runNpx,
+  normalizeRelativePath,
+  collectRuntimeDependencyGraph,
+  findMissingRuntimeDependencies,
+  getPublicRuntimeEntryFiles,
+  redactPathsInText,
+  redactPathsInValue,
+  mapDistributionStateToStatus,
+};

package/scripts/lib/plan-surface.js

@@ -0,0 +1,53 @@
+"use strict";
+
+const { PLAN_ENV, getCurrentPlan, getHistoryRetention, canExportReports } = require("./entitlements");
+const { getPlan, listBucketsForPlan, comparePlans } = require("./plans");
+const { buildVisualQaSurface } = require("./visual-qa");
+const { buildPlanSecuritySurface } = require("./agent-enforcement");
+
+function buildIncludedLine(planName, visualQaSurface) {
+  if (planName === "pro") {
+    return "Included: Better AI Coding Tasks, Advanced Context Optimization, more Visual QA, and advanced Agent Security.";
+  }
+  const quota = visualQaSurface?.quota;
+  const visualQaLabel = quota?.tracked ? `${quota.limit} Visual QA/${quota.period}` : "Visual QA";
+  return `Included: Better AI Coding Tasks, Basic Context Optimization, ${visualQaLabel}, and Basic Agent Security.`;
+}
+
+function buildUpgradeLine() {
+  return "Pro unlocks advanced task compilation, deeper context optimization, more Visual QA, least-privilege protection, and evidence history/export.";
+}
+
+function buildPlanSurface(cwd) {
+  const planName = getCurrentPlan({ cwd });
+  const plan = getPlan(planName) || getPlan("free");
+  const buckets = listBucketsForPlan(planName);
+  const visualQa = buildVisualQaSurface(cwd, { plan: planName });
+  const security = buildPlanSecuritySurface(cwd, { plan: planName });
+  const comparison = comparePlans();
+  const overrideValue = String(process.env[PLAN_ENV] || "").trim().toLowerCase();
+  const overrideNote = overrideValue === planName
+    ? `${PLAN_ENV}=${overrideValue} override active for local development/testing.`
+    : null;
+  return {
+    plan: planName,
+    planLabel: plan.name,
+    planSource: overrideNote ? "env_override" : "default_resolution",
+    overrideNote,
+    subtitle: plan.subtitle,
+    promise: plan.promise,
+    buckets: buckets.map((bucket) => bucket.label),
+    bucketDetails: buckets,
+    includedLine: buildIncludedLine(planName, visualQa),
+    upgradeLine: buildUpgradeLine(),
+    historyRetention: getHistoryRetention(planName),
+    canExportReports: canExportReports(planName),
+    visualQa,
+    security,
+    upgradeUnlocks: comparison.upgradeUnlocks,
+  };
+}
+
+module.exports = {
+  buildPlanSurface,
+};