@decohere/ci-tools 0.0.1-dev.20 → 0.0.1-dev.20261105.103

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 Typesmiths
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/ci-tools",
-  "version": "0.0.1-dev.20",
+  "version": "0.0.1-dev.20261105.103",
   "description": "CI utility scripts for badge generation, coverage reporting, pages artifact assembly, and GitHub API tooling",
   "keywords": [
     "typescript",
@@ -10,18 +10,28 @@
     "github-actions",
     "decohere"
   ],
+  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/ci-tools#readme",
+  "bugs": {
+    "url": "https://github.com/typesmiths/decohere/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/typesmiths/decohere.git",
+    "directory": "projects/ci-tools"
+  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
   "exports": {
     "./lib/svg": "./src/lib/svg.mjs",
     "./lib/lcov": "./src/lib/lcov.mjs",
+    "./lib/github-issue": "./src/lib/github-issue.mjs",
     "./coverage/badge": "./src/coverage/badge.mjs",
     "./coverage/report": "./src/coverage/report.mjs",
-    "./coverage/enforce-thresholds": "./src/coverage/enforce-thresholds.mjs",
     "./badges/ci-status": "./src/badges/ci-status.mjs",
     "./pages/artifact": "./src/pages/artifact.mjs",
     "./pages/smoke": "./src/pages/smoke.mjs",
+    "./audit/format": "./src/audit/format.mjs",
     "./audit/summarize": "./src/audit/summarize.mjs",
     "./audit/enforce": "./src/audit/enforce.mjs",
     "./audit/upsert-issue": "./src/audit/upsert-issue.mjs",
@@ -31,7 +41,11 @@
     "./changeset/check-status": "./src/changeset/check-status.mjs",
     "./github/create-issue": "./src/github/create-issue.mjs",
     "./github/ensure-metadata": "./src/github/ensure-metadata.mjs",
-    "./github/create-or-update-pr": "./src/github/create-or-update-pr.mjs"
+    "./github/create-or-update-pr": "./src/github/create-or-update-pr.mjs",
+    "./github/publish-verify": "./src/github/publish-verify.mjs",
+    "./github/first-publish-check": "./src/github/first-publish-check.mjs",
+    "./github/npm-bootstrap": "./src/github/npm-bootstrap.mjs",
+    "./github/smoke-create-launcher": "./src/github/smoke-create-launcher.mjs"
   },
   "scripts": {
     "test": "vitest run"

package/src/audit/enforce.mjs

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { formatLog, highCritical, parseAudit } from "./format.mjs";
 
 const auditFilePath = process.argv[2] ?? "npm-audit.json";
 
@@ -10,12 +11,13 @@ try {
 	process.exit(1);
 }
 
-const vulnerabilities = data.metadata?.vulnerabilities ?? {};
-const high = vulnerabilities.high ?? 0;
-const critical = vulnerabilities.critical ?? 0;
+const parsed = parseAudit(data);
+const blocking = highCritical(parsed);
 
-if (high > 0 || critical > 0) {
-	console.error(`Security gate failed: high=${high}, critical=${critical}`);
+if (blocking.length > 0) {
+	console.error(
+		`Security gate failed: high=${parsed.high}, critical=${parsed.critical}\n${formatLog({ ...parsed, advisories: blocking })}`,
+	);
 	process.exit(1);
 }
 

package/src/audit/format.mjs

@@ -0,0 +1,133 @@
+/**
+ * Shared npm/pnpm audit JSON helpers.
+ *
+ * Supports pnpm's classic `{ advisories }` report and npm audit v2
+ * `{ auditReportVersion: 2, vulnerabilities }` (pnpm 9+/10).
+ */
+
+const SEVERITY_ORDER = ["critical", "high", "moderate", "low", "info"];
+
+function ghsaFromUrl(url) {
+	return typeof url === "string" ? (url.match(/GHSA-[a-z0-9-]+/i)?.[0] ?? "") : "";
+}
+
+function fromClassicAdvisories(data) {
+	return Object.values(data?.advisories ?? {}).map((raw) => {
+		const paths = (raw.findings ?? []).flatMap((f) => f.paths ?? []);
+		const url = raw.url ?? "";
+		return {
+			id: raw.id,
+			module: raw.module_name ?? "(unknown)",
+			severity: String(raw.severity ?? "info").toLowerCase(),
+			title: raw.title ?? "",
+			url,
+			vulnerable: raw.vulnerable_versions ?? "",
+			patched: raw.patched_versions ?? "",
+			cves: raw.cves ?? [],
+			ghsa: ghsaFromUrl(url),
+			paths: paths.slice(0, 3),
+		};
+	});
+}
+
+function fromNpmV2(data) {
+	const byKey = new Map();
+	for (const vuln of Object.values(data?.vulnerabilities ?? {})) {
+		const vias = Array.isArray(vuln.via) ? vuln.via : [];
+		for (const via of vias) {
+			if (via == null || typeof via !== "object") continue;
+			const url = via.url ?? "";
+			const key = url || `${via.name ?? vuln.name}:${via.title ?? ""}`;
+			const existing = byKey.get(key);
+			const node = Array.isArray(vuln.nodes) ? vuln.nodes[0] : undefined;
+			if (existing) {
+				if (node && existing.paths.length < 3 && !existing.paths.includes(node)) {
+					existing.paths.push(node);
+				}
+				continue;
+			}
+			byKey.set(key, {
+				id: via.source,
+				module: via.name ?? vuln.name ?? "(unknown)",
+				severity: String(via.severity ?? vuln.severity ?? "info").toLowerCase(),
+				title: via.title ?? "",
+				url,
+				vulnerable: via.range ?? vuln.range ?? "",
+				patched: "",
+				cves: [],
+				ghsa: ghsaFromUrl(url),
+				paths: node ? [node] : [],
+			});
+		}
+	}
+	return [...byKey.values()];
+}
+
+export function parseAudit(data) {
+	const counts = data?.metadata?.vulnerabilities ?? {};
+	const info = counts.info ?? 0;
+	const low = counts.low ?? 0;
+	const moderate = counts.moderate ?? 0;
+	const high = counts.high ?? 0;
+	const critical = counts.critical ?? 0;
+	const total = counts.total ?? info + low + moderate + high + critical;
+
+	const classic = data?.advisories != null && Object.keys(data.advisories).length > 0;
+	const advisories = classic ? fromClassicAdvisories(data) : fromNpmV2(data);
+
+	advisories.sort((a, b) => {
+		const d = SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity);
+		if (d !== 0) return d;
+		return String(a.module).localeCompare(String(b.module));
+	});
+
+	return { total, critical, high, moderate, low, info, advisories };
+}
+
+export function formatLog(parsed) {
+	const lines = [
+		`npm audit: total=${parsed.total} critical=${parsed.critical} high=${parsed.high} moderate=${parsed.moderate} low=${parsed.low} info=${parsed.info}`,
+	];
+	for (const a of parsed.advisories) {
+		const id = a.ghsa || a.cves[0] || a.id;
+		lines.push(
+			`  [${a.severity}] ${a.module} ${id}: ${a.title} (vulnerable ${a.vulnerable}; patched ${a.patched})`,
+		);
+		if (a.url) lines.push(`    ${a.url}`);
+		if (a.paths[0]) lines.push(`    ${a.paths[0]}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+export function formatMarkdown(parsed) {
+	const lines = [
+		"## npm audit",
+		"",
+		"| Severity | Count |",
+		"|---|---|",
+		`| Critical | ${parsed.critical} |`,
+		`| High | ${parsed.high} |`,
+		`| Moderate | ${parsed.moderate} |`,
+		`| Low | ${parsed.low} |`,
+		`| Info | ${parsed.info} |`,
+		`| **Total** | **${parsed.total}** |`,
+		"",
+	];
+	if (parsed.advisories.length === 0) {
+		lines.push("No advisories.");
+		return `${lines.join("\n")}\n`;
+	}
+	lines.push("### Advisories", "");
+	for (const a of parsed.advisories) {
+		const id = a.ghsa || a.cves.join(", ") || a.id;
+		const link = a.url ? `[${id}](${a.url})` : id;
+		lines.push(`- **${a.severity}** \`${a.module}\` ${link} — ${a.title}`);
+		lines.push(`  - vulnerable: \`${a.vulnerable}\`; patched: \`${a.patched}\``);
+		if (a.paths[0]) lines.push(`  - ${a.paths[0]}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+export function highCritical(parsed) {
+	return parsed.advisories.filter((a) => a.severity === "high" || a.severity === "critical");
+}

package/src/audit/summarize.mjs

@@ -1,46 +1,24 @@
 import { appendFileSync, readFileSync } from "node:fs";
+import { formatLog, formatMarkdown, parseAudit } from "./format.mjs";
 
 const auditFilePath = process.argv[2] ?? "npm-audit.json";
 
-function writeSummary(lines) {
-	const summaryText = `${lines.join("\n")}\n`;
+function writeSummary(text) {
 	if (process.env.GITHUB_STEP_SUMMARY) {
-		appendFileSync(process.env.GITHUB_STEP_SUMMARY, summaryText);
-		return;
+		appendFileSync(process.env.GITHUB_STEP_SUMMARY, text);
 	}
-	process.stdout.write(summaryText);
 }
 
 let data = null;
 try {
 	data = JSON.parse(readFileSync(auditFilePath, "utf8"));
 } catch {
-	writeSummary([
-		"## Security Audit",
-		"",
-		"- npm audit output could not be parsed.",
-		`- See uploaded \`${auditFilePath}\` artifact for raw output.`,
-	]);
-	process.exit(0);
+	const msg = `npm audit output could not be parsed (${auditFilePath}).\n`;
+	process.stderr.write(msg);
+	writeSummary(`## Security Audit\n\n- ${msg}`);
+	process.exit(1);
 }
 
-const vulnerabilities = data.metadata?.vulnerabilities ?? {};
-const info = vulnerabilities.info ?? 0;
-const low = vulnerabilities.low ?? 0;
-const moderate = vulnerabilities.moderate ?? 0;
-const high = vulnerabilities.high ?? 0;
-const critical = vulnerabilities.critical ?? 0;
-const total = vulnerabilities.total ?? info + low + moderate + high + critical;
-
-writeSummary([
-	"## Security Audit",
-	"",
-	`| Severity  | Count |`,
-	`|-----------|-------|`,
-	`| Critical  | ${critical} |`,
-	`| High      | ${high} |`,
-	`| Moderate  | ${moderate} |`,
-	`| Low       | ${low} |`,
-	`| Info      | ${info} |`,
-	`| **Total** | **${total}** |`,
-]);
+const parsed = parseAudit(data);
+process.stdout.write(formatLog(parsed));
+writeSummary(formatMarkdown(parsed));

package/src/audit/upsert-issue.mjs

@@ -1,68 +1,19 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import os from "node:os";
-import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { upsertIssue } from "../lib/github-issue.mjs";
+import { formatMarkdown, parseAudit } from "./format.mjs";
 
 const auditFilePath = process.argv[2] ?? "npm-audit.json";
 const ISSUE_TITLE = "security(ci): npm audit vulnerabilities detected";
 
-function runGh(args) {
-	const result = spawnSync("gh", args, { encoding: "utf8", env: process.env });
-	if (result.status !== 0) {
-		throw new Error(result.stderr || result.stdout || `gh command failed: ${args.join(" ")}`);
+function runUrl() {
+	if (
+		process.env.GITHUB_SERVER_URL &&
+		process.env.GITHUB_REPOSITORY &&
+		process.env.GITHUB_RUN_ID
+	) {
+		return `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
 	}
-	return result.stdout;
-}
-
-function readAuditSummary(filePath) {
-	const data = JSON.parse(readFileSync(filePath, "utf8"));
-	const vulnerabilities = data.metadata?.vulnerabilities ?? {};
-	const info = vulnerabilities.info ?? 0;
-	const low = vulnerabilities.low ?? 0;
-	const moderate = vulnerabilities.moderate ?? 0;
-	const high = vulnerabilities.high ?? 0;
-	const critical = vulnerabilities.critical ?? 0;
-	const total = vulnerabilities.total ?? info + low + moderate + high + critical;
-	return { total, critical, high, moderate, low, info };
-}
-
-function buildBody(summary) {
-	const runUrl =
-		process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID
-			? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
-			: "(run URL unavailable)";
-	const sha = process.env.GITHUB_SHA ? process.env.GITHUB_SHA.slice(0, 12) : "unknown";
-
-	return [
-		"## npm audit detected vulnerabilities",
-		"",
-		`- Total: ${summary.total}`,
-		`- Critical: ${summary.critical}`,
-		`- High: ${summary.high}`,
-		`- Moderate: ${summary.moderate}`,
-		`- Low: ${summary.low}`,
-		`- Info: ${summary.info}`,
-		"",
-		`- Commit: ${sha}`,
-		`- Workflow run: ${runUrl}`,
-		"",
-		"This issue is managed by CI and will be updated on subsequent main-branch runs while vulnerabilities remain.",
-	].join("\n");
-}
-
-function findExistingIssueNumber() {
-	const output = runGh([
-		"issue",
-		"list",
-		"--state",
-		"open",
-		"--limit",
-		"200",
-		"--json",
-		"number,title",
-	]);
-	const issues = JSON.parse(output);
-	return issues.find((issue) => issue.title === ISSUE_TITLE)?.number ?? null;
+	return "(run URL unavailable)";
 }
 
 if (!existsSync(auditFilePath)) {
@@ -70,21 +21,21 @@ if (!existsSync(auditFilePath)) {
 	process.exit(0);
 }
 
-const summary = readAuditSummary(auditFilePath);
-if (summary.total === 0) {
+const parsed = parseAudit(JSON.parse(readFileSync(auditFilePath, "utf8")));
+if (parsed.total === 0) {
 	console.log("No vulnerabilities found; skipping issue create/update.");
 	process.exit(0);
 }
 
-const body = buildBody(summary);
-const tempFile = path.join(os.tmpdir(), `npm-audit-issue-${Date.now()}.md`);
-writeFileSync(tempFile, body, "utf8");
-
-const existingIssueNumber = findExistingIssueNumber();
-if (existingIssueNumber) {
-	runGh(["issue", "comment", String(existingIssueNumber), "--body-file", tempFile]);
-	console.log(`Updated existing issue #${existingIssueNumber}.`);
-} else {
-	runGh(["issue", "create", "--title", ISSUE_TITLE, "--body-file", tempFile]);
-	console.log("Created new npm audit tracking issue.");
-}
+const sha = process.env.GITHUB_SHA ? process.env.GITHUB_SHA.slice(0, 12) : "unknown";
+const body = [
+	formatMarkdown(parsed).trim(),
+	"",
+	`- Commit: \`${sha}\``,
+	`- Workflow run: ${runUrl()}`,
+	"",
+	"This issue is managed by CI: main-branch runs and the nightly audit update it in place while vulnerabilities remain.",
+].join("\n");
+
+const result = upsertIssue({ title: ISSUE_TITLE, body });
+console.log(`${result.created ? "Opened" : "Updated"} issue #${result.number} ${result.url}`);