@pareto4/pp-core 1.5.0

package/scripts/verify-npm-publish.cjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * verify-npm-publish.cjs — verifies a freshly-published npm version is
+ * retrievable, tolerating registry/CDN propagation lag via bounded retry.
+ * Fixes #623. Used by both Verify-publish steps in .github/workflows/release.yml.
+ */
+
+const cp = require('node:child_process');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+// ---- Constants ---------------------------------------------------------------
+
+const REASON = Object.freeze({
+  OK_VERSION_LIVE: 'ok_version_live',
+  FAIL_VERSION_NOT_FOUND: 'fail_version_not_found',
+});
+
+// ---- Sleep -------------------------------------------------------------------
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// ---- npm fetchers ------------------------------------------------------------
+
+function defaultFetchVersion(pkg, version) {
+  try {
+    const out = cp.execFileSync('npm', ['view', `${pkg}@${version}`, 'version'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return out || null;
+  } catch { return null; }
+}
+
+function defaultFetchDistTag(pkg, distTag) {
+  try {
+    const out = cp.execFileSync('npm', ['view', pkg, 'dist-tags', '--json'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const tags = JSON.parse(out);
+    return (tags && typeof tags === 'object' && tags[distTag]) || null;
+  } catch { return null; }
+}
+
+// ---- Core async function (unit-tested seam) ----------------------------------
+
+async function verifyPublish({
+  pkg,
+  version,
+  distTag = null,
+  fetchVersion = defaultFetchVersion,
+  fetchDistTag = defaultFetchDistTag,
+  maxAttempts = 20,
+  intervalMs = 5000,
+  sleep = defaultSleep,
+}) {
+  let attempts = 0;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const found = fetchVersion(pkg, version);
+    attempts++;
+
+    if (found === version) {
+      // Version confirmed live — optionally resolve dist-tag informally
+      let distTagResult = null;
+
+      if (distTag && typeof distTag === 'string' && distTag.length > 0) {
+        let pointsTo = null;
+
+        for (let dt = 1; dt <= maxAttempts; dt++) {
+          const tagVal = fetchDistTag(pkg, distTag);
+          if (tagVal !== null) {
+            pointsTo = tagVal;
+            break;
+          }
+          if (dt < maxAttempts) {
+            await sleep(intervalMs);
+          }
+        }
+
+        distTagResult = {
+          name: distTag,
+          points_to: pointsTo,
+          matches: pointsTo === version,
+        };
+      }
+
+      return {
+        ok: true,
+        reason: REASON.OK_VERSION_LIVE,
+        pkg,
+        version,
+        attempts,
+        distTag: distTagResult,
+      };
+    }
+
+    // Not found yet — sleep before retry (but not after the final attempt)
+    if (attempt < maxAttempts) {
+      await sleep(intervalMs);
+    }
+  }
+
+  return {
+    ok: false,
+    reason: REASON.FAIL_VERSION_NOT_FOUND,
+    pkg,
+    version,
+    attempts,
+    distTag: null,
+  };
+}
+
+// ---- Argument parsing --------------------------------------------------------
+
+function parseArgs(argv) {
+  const opts = {
+    pkg: null,
+    version: null,
+    distTag: null,
+    maxAttempts: 20,
+    intervalMs: 5000,
+    json: false,
+  };
+
+  const args = argv.slice();
+  while (args.length > 0) {
+    const arg = args.shift();
+
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write(
+        'Usage: node scripts/verify-npm-publish.cjs --package <pkg> --version <ver> [options]\n' +
+        '\n' +
+        'Options:\n' +
+        '  --package <s>       npm package name (required)\n' +
+        '  --version <s>       version to verify (required)\n' +
+        '  --dist-tag <s>      dist-tag to report (optional, informational only)\n' +
+        '  --max-attempts <n>  max retry attempts (default: 20)\n' +
+        '  --interval-ms <n>   ms between retries (default: 5000)\n' +
+        '  --json              emit structured JSON output\n' +
+        '  --help, -h          show this help\n'
+      );
+      throw new ExitError(0);
+    } else if (arg === '--package') {
+      const val = args.shift();
+      if (!val || val.startsWith('-')) {
+        throw new ExitError(2, 'error: --package requires a value');
+      }
+      opts.pkg = val;
+    } else if (arg === '--version') {
+      const val = args.shift();
+      if (!val || val.startsWith('-')) {
+        throw new ExitError(2, 'error: --version requires a value');
+      }
+      opts.version = val;
+    } else if (arg === '--dist-tag') {
+      const val = args.shift();
+      if (!val || val.startsWith('-')) {
+        throw new ExitError(2, 'error: --dist-tag requires a value');
+      }
+      opts.distTag = val;
+    } else if (arg === '--max-attempts') {
+      const val = args.shift();
+      if (!val || val.startsWith('-')) {
+        throw new ExitError(2, 'error: --max-attempts requires a value');
+      }
+      const n = parseInt(val, 10);
+      if (isNaN(n) || n < 1) {
+        throw new ExitError(2, 'error: --max-attempts must be a positive integer');
+      }
+      opts.maxAttempts = n;
+    } else if (arg === '--interval-ms') {
+      const val = args.shift();
+      if (!val || val.startsWith('-')) {
+        throw new ExitError(2, 'error: --interval-ms requires a value');
+      }
+      const n = parseInt(val, 10);
+      if (isNaN(n) || n < 0) {
+        throw new ExitError(2, 'error: --interval-ms must be a non-negative integer');
+      }
+      opts.intervalMs = n;
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else {
+      throw new ExitError(2, `unknown argument: ${arg}`);
+    }
+  }
+
+  if (!opts.pkg) {
+    throw new ExitError(2, 'error: --package is required');
+  }
+  if (!opts.version) {
+    throw new ExitError(2, 'error: --version is required');
+  }
+
+  return opts;
+}
+
+// ---- Main entry point --------------------------------------------------------
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = await verifyPublish({
+    pkg: opts.pkg,
+    version: opts.version,
+    distTag: opts.distTag,
+    maxAttempts: opts.maxAttempts,
+    intervalMs: opts.intervalMs,
+  });
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    if (result.ok) {
+      process.stdout.write(
+        `✓ Verified: ${result.pkg}@${result.version} is live on npm (after ${result.attempts} attempt(s))\n`
+      );
+      if (result.distTag) {
+        process.stdout.write(`✓ ${result.distTag.name} tag points to: ${result.distTag.points_to}\n`);
+        if (!result.distTag.matches) {
+          process.stdout.write(
+            `::warning::${result.distTag.name} dist-tag points to ${result.distTag.points_to}, expected ${result.version}\n`
+          );
+        }
+      }
+    } else {
+      process.stdout.write(
+        `::error::Published version verification failed. ${result.pkg}@${result.version} not found after ${result.attempts} attempt(s)\n`
+      );
+    }
+  }
+
+  return result.ok ? 0 : 1;
+}
+
+// ---- Guard -------------------------------------------------------------------
+
+if (require.main === module) {
+  runMain(main);
+}
+
+module.exports = { verifyPublish, parseArgs, REASON, defaultFetchVersion, defaultFetchDistTag };

package/scripts/verify-opengsd-sweep.cjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * verify-opengsd-sweep.cjs — Combined OpenGSD audit gate (D-11, SC3 cross-cut).
+ *
+ * Sweeps two surfaces for residual OpenGSD spellings:
+ *   (a) Code surface: pp-core/bin/** (all text files)
+ *   (b) Docs surface: README.md, CONTRIBUTING.md, docs/** (live user-facing docs)
+ *
+ * Explicit carve-outs (allowlist — intentional OpenGSD references):
+ *   D-07 provenance files: LICENSE, NOTICE, UPSTREAM_SYNC.md
+ *   D-06 historical corpus: docs/adr/, docs/proposals/, docs/discussions/,
+ *                            docs/issueevidence/, docs/prd/, docs/research/
+ *   D-06 notice file:       docs/adr/README.md  (contains the history-notice header)
+ *   Migration provenance:   pp-core/bin/lib/installer-migrations/005-*.cjs
+ *                            (comment accurately names the upstream source package)
+ *
+ * Exit codes:
+ *   0 — live surface is OpenGSD-free (all hits are inside the carve-outs)
+ *   1 — one or more stray hits found outside the carve-outs
+ *
+ * Usage:
+ *   node scripts/verify-opengsd-sweep.cjs
+ *
+ * Exports:
+ *   runSweep(opts?) → { hits: Array<{file, line, text}>, clean: boolean }
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+// ── Root ────────────────────────────────────────────────────────────────────
+
+const ROOT = path.resolve(__dirname, '..');
+
+// ── OpenGSD pattern ─────────────────────────────────────────────────────────
+
+/** Matches any recognised OpenGSD spelling in a line of text. */
+const OPENGSD_RE = /opengsd|open-gsd/i;
+
+// ── Carve-out allowlists (all paths are absolute) ───────────────────────────
+
+/**
+ * D-07 provenance files: MIT-required OpenGSD attribution must remain intact.
+ * These are absolute paths.
+ */
+const PROVENANCE_FILES = new Set([
+  path.join(ROOT, 'LICENSE'),
+  path.join(ROOT, 'NOTICE'),
+  path.join(ROOT, 'UPSTREAM_SYNC.md'),
+]);
+
+/**
+ * D-06 historical corpus directories: upstream OpenGSD decision records,
+ * retained for historical integrity. Do NOT modify these.
+ */
+const HISTORICAL_CORPUS_DIRS = [
+  path.join(ROOT, 'docs', 'adr'),
+  path.join(ROOT, 'docs', 'proposals'),
+  path.join(ROOT, 'docs', 'discussions'),
+  path.join(ROOT, 'docs', 'issueevidence'),
+  path.join(ROOT, 'docs', 'prd'),
+  path.join(ROOT, 'docs', 'research'),
+];
+
+/**
+ * docs/adr/README.md — the inherited-history notice header.
+ * This file intentionally references the upstream project to explain provenance.
+ */
+const ADR_README = path.join(ROOT, 'docs', 'adr', 'README.md');
+
+/**
+ * Migration-005 provenance comment: legitimately names the upstream source
+ * package (@opengsd/gsd-core) in the migration description.
+ * Matched as a path prefix glob (any 005-*.cjs under installer-migrations/).
+ */
+const MIGRATION_005_DIR = path.join(ROOT, 'pp-core', 'bin', 'lib', 'installer-migrations');
+const MIGRATION_005_PREFIX = '005-';
+
+// ── Carve-out predicate ──────────────────────────────────────────────────────
+
+/**
+ * Returns true if the file is in a carve-out and should be skipped entirely.
+ * @param {string} abs  absolute path to the file
+ */
+function isCarvedOut(abs) {
+  // D-07 provenance files
+  if (PROVENANCE_FILES.has(abs)) return true;
+
+  // D-06 historical corpus dirs
+  for (const dir of HISTORICAL_CORPUS_DIRS) {
+    if (abs.startsWith(dir + path.sep) || abs === dir) return true;
+  }
+
+  // docs/adr/README.md — the history notice
+  if (abs === ADR_README) return true;
+
+  // Migration-005 provenance comment
+  if (
+    abs.startsWith(MIGRATION_005_DIR + path.sep) &&
+    path.basename(abs).startsWith(MIGRATION_005_PREFIX)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+// ── File walker ─────────────────────────────────────────────────────────────
+
+/**
+ * Walk a directory recursively, collecting all text files.
+ * Skips: node_modules, .git, and directories that are entirely carved out.
+ *
+ * @param {string}   dir     absolute path to walk
+ * @param {string[]} result  accumulator
+ * @returns {string[]}
+ */
+function walkDir(dir, result) {
+  result = result || [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      // Skip common non-source dirs
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+
+      // Skip carved-out directories at directory level (avoids walking them)
+      let skipDir = false;
+      for (const carved of HISTORICAL_CORPUS_DIRS) {
+        if (abs === carved) { skipDir = true; break; }
+      }
+      if (skipDir) continue;
+
+      walkDir(abs, result);
+    } else if (entry.isFile()) {
+      result.push(abs);
+    }
+  }
+
+  return result;
+}
+
+// ── Surface scanners ─────────────────────────────────────────────────────────
+
+/**
+ * Scan a list of absolute file paths for OpenGSD hits.
+ * @param {string[]} files
+ * @returns {Array<{file: string, line: number, text: string}>}
+ */
+function scanFiles(files) {
+  const hits = [];
+
+  for (const abs of files) {
+    if (isCarvedOut(abs)) continue;
+
+    let content;
+    try {
+      content = fs.readFileSync(abs, 'utf8');
+    } catch {
+      // Binary or unreadable file — skip
+      continue;
+    }
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (OPENGSD_RE.test(lines[i])) {
+        hits.push({
+          file: path.relative(ROOT, abs),
+          line: i + 1,
+          text: lines[i].trimEnd(),
+        });
+      }
+    }
+  }
+
+  return hits;
+}
+
+// ── Code surface ─────────────────────────────────────────────────────────────
+
+const CODE_ROOT = path.join(ROOT, 'pp-core', 'bin');
+
+/** Collect all text files under pp-core/bin/, skipping node_modules. */
+function collectCodeFiles() {
+  if (!fs.existsSync(CODE_ROOT)) return [];
+  return walkDir(CODE_ROOT, []);
+}
+
+// ── Docs surface ─────────────────────────────────────────────────────────────
+
+const DOCS_DIR = path.join(ROOT, 'docs');
+
+/** Root-level live-doc files (README.md, CONTRIBUTING.md). */
+const ROOT_DOC_FILES = [
+  path.join(ROOT, 'README.md'),
+  path.join(ROOT, 'CONTRIBUTING.md'),
+];
+
+/** Collect all files in the live docs surface. */
+function collectDocsFiles() {
+  const files = [];
+
+  // Root-level live docs
+  for (const f of ROOT_DOC_FILES) {
+    if (fs.existsSync(f)) files.push(f);
+  }
+
+  // docs/ tree (historical corpus dirs skipped by walkDir)
+  if (fs.existsSync(DOCS_DIR)) {
+    walkDir(DOCS_DIR, files);
+  }
+
+  return files;
+}
+
+// ── Main sweep logic ─────────────────────────────────────────────────────────
+
+/**
+ * Run the combined OpenGSD sweep across the code + docs surfaces.
+ *
+ * @param {object}  [opts]
+ * @param {boolean} [opts.quiet]  suppress stdout progress output
+ * @returns {{ hits: Array<{file, line, text}>, clean: boolean }}
+ */
+function runSweep(opts) {
+  const quiet = (opts && opts.quiet) || false;
+
+  const codeFiles = collectCodeFiles();
+  const docsFiles = collectDocsFiles();
+
+  if (!quiet) {
+    process.stdout.write(
+      `[verify-opengsd-sweep] Scanning ${codeFiles.length} code file(s) and ${docsFiles.length} doc file(s)...\n`
+    );
+  }
+
+  const codeHits = scanFiles(codeFiles);
+  const docsHits = scanFiles(docsFiles);
+  const hits = [...codeHits, ...docsHits];
+
+  return { hits, clean: hits.length === 0 };
+}
+
+// ── CLI entry ────────────────────────────────────────────────────────────────
+
+function cliMain() {
+  const { hits, clean } = runSweep({ quiet: false });
+
+  if (clean) {
+    process.stdout.write(
+      '[verify-opengsd-sweep] PASS — live code+docs surface is OpenGSD-free (carve-outs intact).\n'
+    );
+    return 0;
+  }
+
+  process.stderr.write(
+    `[verify-opengsd-sweep] FAIL — ${hits.length} stray OpenGSD reference(s) found outside the allowlist:\n\n`
+  );
+  for (const h of hits) {
+    process.stderr.write(`  ${h.file}:${h.line}: ${h.text}\n`);
+  }
+  process.stderr.write('\n');
+  process.stderr.write(
+    'Fix each hit in the offending file (see 06-PATTERNS.md substitution table),\n' +
+    'then re-run this script.\n'
+  );
+
+  throw new ExitError(1);
+}
+
+// ── Exports + guard ──────────────────────────────────────────────────────────
+
+module.exports = { runSweep, OPENGSD_RE, isCarvedOut };
+
+if (require.main === module) {
+  runMain(cliMain);
+}