pm-ops 2026.9.13 → 2026.9.23

package/dist/index.js

@@ -97,6 +97,16 @@ function reposFlag(description) {
         list: true,
     };
 }
+function opsExamples(command, examples) {
+    return [`pm ops ${command}`, ...examples];
+}
+/** Build the shared output-format and output-file flag definitions. */
+function formatOutputFlags(outputDescription) {
+    return [
+        { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
+        { long: "--output", value_name: "file", description: outputDescription },
+    ];
+}
 /** Extract every --repos value that follows a command path in the raw argv array. */
 function cliRepoFlagValues(commandPath, argv = process.argv.slice(2)) {
     const commandTokens = commandPath.split(" ");
@@ -154,7 +164,7 @@ function expandHome(path) {
     return path.startsWith("~/") || path.startsWith("~\\") ? join(homedir(), path.slice(2)) : path;
 }
 function hasGlob(path) {
-    return /[*?\[]/.test(path);
+    return /[*?[]/.test(path);
 }
 function escapeRegexChar(char) {
     return /[.+^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
@@ -217,6 +227,16 @@ function expandSimpleGlob(pattern) {
     // guaranteed — important for stable, diff-friendly agent output.
     return candidates.length > 0 ? [...candidates].sort() : [absolute];
 }
+/** Normalize command context into the repository paths and output routing inputs. */
+function resolveCommandInputs(ctx) {
+    const options = ctx.options;
+    return {
+        options,
+        repos: resolveRepos(options, ctx.args),
+        format: resolveFormat(options, ctx.global),
+        outputPath: readString(options, "output"),
+    };
+}
 function resolveRepos(options, args = []) {
     const repos = [...asArray(options["repos"]), ...asArray(args)];
     if (repos.length > 0)
@@ -643,6 +663,21 @@ function ghOpenCount(repoPath, kind) {
     const parsed = parseJsonSafe(r.stdout);
     return Array.isArray(parsed) ? parsed.length : null;
 }
+function readRepoPackageInfo(repoPath) {
+    const pkg = readPackageJson(repoPath);
+    return { pkg, name: pkg?.name ?? null, version: pkg?.version ?? null };
+}
+/** Read npm audit severity counts and report unavailable audits to the caller. */
+function readAuditCounts(repoPath, onError) {
+    try {
+        const audit = readAudit(repoPath);
+        return { critical: audit.critical, high: audit.high };
+    }
+    catch (error) {
+        onError(auditUnavailable(error));
+        return { critical: null, high: null };
+    }
+}
 /** Gather the full release-readiness snapshot for a single repository path. */
 function scanRepo(repoPath) {
     const errors = [];
@@ -670,9 +705,7 @@ function scanRepo(repoPath) {
             errors,
         };
     }
-    const pkg = readPackageJson(repoPath);
-    const name = pkg?.name ?? null;
-    const version = pkg?.version ?? null;
+    const { pkg, name, version } = readRepoPackageInfo(repoPath);
     const strict_ts = readTsConfigStrict(repoPath);
     const has_changelog = existsSync(join(repoPath, "CHANGELOG.md"));
     const has_release_workflow = existsSync(join(repoPath, ".github", "workflows", "release.yml"));
@@ -684,16 +717,9 @@ function scanRepo(repoPath) {
     const pm_open_items = items ? items.filter((i) => (i.status ?? "").toLowerCase() === "open").length : null;
     const pm_inprogress_items = items ? items.filter((i) => (i.status ?? "").toLowerCase() === "in_progress").length : null;
     const outdated_count = countOutdated(repoPath);
-    let audit_critical = null;
-    let audit_high = null;
-    try {
-        const a = readAudit(repoPath);
-        audit_critical = a.critical;
-        audit_high = a.high;
-    }
-    catch (err) {
-        errors.push(auditUnavailable(err));
-    }
+    const audit = readAuditCounts(repoPath, (message) => errors.push(message));
+    const audit_critical = audit.critical;
+    const audit_high = audit.high;
     const open_prs = ghOpenCount(repoPath, "pr");
     const open_issues = ghOpenCount(repoPath, "issue");
     const has_pkg = Boolean(pkg);
@@ -1065,6 +1091,10 @@ function verifyRelease(repos, progress) {
         summary: { total: results.length, passed: results.filter((r) => r.failed === 0).length, failed: results.filter((r) => r.failed > 0).length },
     };
 }
+function throwVerifyReleaseFailure(result) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    throw new CommandError(`verify-release: ${result.summary.failed} repo(s) failed`, EXIT_CODE.GENERIC_FAILURE);
+}
 /** Render the verify-release result as a markdown table of checks per repo. */
 function renderVerifyReleaseMarkdown(result) {
     const lines = [
@@ -1105,9 +1135,7 @@ async function collectStatus(repoPath) {
             pending_receipts: null,
         };
     }
-    const pkg = readPackageJson(repoPath);
-    const name = pkg?.name ?? null;
-    const version = pkg?.version ?? null;
+    const { pkg, name, version } = readRepoPackageInfo(repoPath);
     const issues = [];
     const strict_ts = readTsConfigStrict(repoPath);
     if (!strict_ts)
@@ -1126,16 +1154,9 @@ async function collectStatus(repoPath) {
     if (!has_pm_changelog && !self_hosts_pm_changelog)
         issues.push("pm-changelog not wired");
     const outdated_count = countOutdated(repoPath);
-    let audit_critical = null;
-    let audit_high = null;
-    try {
-        const a = readAudit(repoPath);
-        audit_critical = a.critical;
-        audit_high = a.high;
-    }
-    catch (err) {
-        issues.push(auditUnavailable(err));
-    }
+    const audit = readAuditCounts(repoPath, (message) => issues.push(message));
+    const audit_critical = audit.critical;
+    const audit_high = audit.high;
     // Critical vulnerabilities gate readiness (matching scanRepo's
     // audit gate). High-severity findings are still pushed to issues for
     // textual visibility but do not block ready, so fleet-health reports
@@ -2061,7 +2082,7 @@ function renderDocstringsMarkdown(result) {
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-ops",
-    version: "2026.9.13",
+    version: "2026.9.23",
     activate(api) {
         if (typeof api.registerRenderer === "function") {
             // Derived from OPS_COMMAND_PATHS rather than restated. A literal copy is
@@ -2094,23 +2115,18 @@ export default defineExtension({
                 "(comma-separated or repeatable). --json emits clean JSON; --format markdown emits a table.",
             intent: "audit release readiness across many pm repositories",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops scan",
+            examples: opsExamples("scan", [
                 "pm ops scan --repos ./pm-csv ./pm-github",
                 "pm ops scan --repos ./pm-csv,./pm-github --json",
                 "pm ops scan --format markdown",
                 "pm ops scan --repos ~/container/pm-* --format markdown --output FLEET.md",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths to scan (comma-separated or repeatable; default: current dir)"),
-                { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
-                { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
+                ...formatOutputFlags("Write the rendered output to a file instead of stdout"),
             ],
             async run(ctx) {
-                const options = ctx.options;
-                const repos = resolveRepos(options, ctx.args);
-                const format = resolveFormat(options, ctx.global);
-                const outputPath = readString(options, "output");
+                const { repos, format, outputPath } = resolveCommandInputs(ctx);
                 console.error(`pm-ops scan: ${repos.length} repo(s)`);
                 const result = scanRepos(repos, (m) => console.error(`  ${m}`));
                 console.error(`scan: ${result.summary.ready}/${result.summary.total} ready`);
@@ -2126,25 +2142,20 @@ export default defineExtension({
                 "({ checks: [{ id, severity, repo_filter?, params? }] }). --strict exits non-zero on any failure.",
             intent: "enforce naming/workflow/pm policies across many pm repositories",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops policy",
+            examples: opsExamples("policy", [
                 "pm ops policy --repos ./pm-csv ./pm-github",
                 "pm ops policy --policy ./fleet-policy.json --strict",
                 "pm ops policy --format markdown",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths to check (comma-separated or repeatable; default: current dir)"),
                 { long: "--policy", value_name: "file", description: "JSON policy bundle overriding the default checks" },
-                { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
+                ...formatOutputFlags("Write the rendered output to a file instead of stdout"),
                 { long: "--strict", description: "Exit non-zero on any failed check (any severity)" },
-                { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
             ],
             async run(ctx) {
-                const options = ctx.options;
-                const repos = resolveRepos(options, ctx.args);
-                const format = resolveFormat(options, ctx.global);
+                const { options, repos, format, outputPath } = resolveCommandInputs(ctx);
                 const strict = readBool(options, "strict");
-                const outputPath = readString(options, "output");
                 let bundle = DEFAULT_POLICY;
                 const policyFile = readString(options, "policy");
                 if (policyFile) {
@@ -2181,22 +2192,17 @@ export default defineExtension({
                 "Exits non-zero if any repo fails. --output writes the report to a file.",
             intent: "run a release gate matrix across many pm repositories",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops verify-release",
+            examples: opsExamples("verify-release", [
                 "pm ops verify-release --repos ./pm-csv ./pm-github",
                 "pm ops verify-release --json",
                 "pm ops verify-release --format markdown --output RELEASE.md",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths to verify (comma-separated or repeatable; default: current dir)"),
-                { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
-                { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
+                ...formatOutputFlags("Write the rendered output to a file instead of stdout"),
             ],
             async run(ctx) {
-                const options = ctx.options;
-                const repos = resolveRepos(options, ctx.args);
-                const format = resolveFormat(options, ctx.global);
-                const outputPath = readString(options, "output");
+                const { repos, format, outputPath } = resolveCommandInputs(ctx);
                 console.error(`pm-ops verify-release: ${repos.length} repo(s)`);
                 const result = verifyRelease(repos, (m) => console.error(`  ${m}`));
                 console.error(`verify-release: ${result.summary.passed}/${result.summary.total} repos passed`);
@@ -2220,10 +2226,8 @@ export default defineExtension({
                     return { written_to: outputPath, format };
                 }
                 if (format === "json") {
-                    if (failed) {
-                        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-                        throw new CommandError(`verify-release: ${result.summary.failed} repo(s) failed`, EXIT_CODE.GENERIC_FAILURE);
-                    }
+                    if (failed)
+                        throwVerifyReleaseFailure(result);
                     return renderedCommandResult(`${JSON.stringify(result, null, 2)}\n`);
                 }
                 if (format === "markdown") {
@@ -2234,10 +2238,8 @@ export default defineExtension({
                     }
                     return renderedCommandResult(md);
                 }
-                if (failed) {
-                    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-                    throw new CommandError(`verify-release: ${result.summary.failed} repo(s) failed`, EXIT_CODE.GENERIC_FAILURE);
-                }
+                if (failed)
+                    throwVerifyReleaseFailure(result);
                 return result;
             },
         });
@@ -2249,25 +2251,20 @@ export default defineExtension({
                 "--output writes the report to a file. Default stdout TOON.",
             intent: "produce a concise fleet report across many pm repositories",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops report",
+            examples: opsExamples("report", [
                 "pm ops report --repos ./pm-csv ./pm-github --format markdown",
                 "pm ops report --format markdown --output FLEET.md",
                 "pm ops report --format markdown --include-release --output FLEET.md",
                 "pm ops report --json",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths to report on (comma-separated or repeatable; default: current dir)"),
-                { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
-                { long: "--output", value_name: "file", description: "Write the rendered report to a file instead of stdout" },
+                ...formatOutputFlags("Write the rendered report to a file instead of stdout"),
                 { long: "--include-release", description: "Also run verify-release and include results in the report" },
             ],
             async run(ctx) {
-                const options = ctx.options;
-                const repos = resolveRepos(options, ctx.args);
-                const format = resolveFormat(options, ctx.global);
-                const outputPath = readString(options, "output");
-                const includeRelease = readBool(options, "includeRelease", "include-release");
+                const { repos, format, outputPath } = resolveCommandInputs(ctx);
+                const includeRelease = readBool(ctx.options, "includeRelease", "include-release");
                 console.error(`pm-ops report: ${repos.length} repo(s)${includeRelease ? " (+release)" : ""}`);
                 const result = buildReport(repos, (m) => console.error(`  ${m}`), includeRelease);
                 console.error(`report: scan ${result.scan.summary.ready}/${result.scan.summary.total} ready; policy ${result.policy.summary.failed} failed${result.release ? `; release ${result.release.summary.passed}/${result.release.summary.total} passed` : ""}`);
@@ -2283,21 +2280,16 @@ export default defineExtension({
                 "emits a compact table.",
             intent: "get a quick fleet health overview across many pm repositories",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops status",
+            examples: opsExamples("status", [
                 "pm ops status --repos ./pm-csv ./pm-github",
                 "pm ops status --format markdown",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths (comma-separated or repeatable; default: current dir)"),
-                { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
-                { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
+                ...formatOutputFlags("Write the rendered output to a file instead of stdout"),
             ],
             async run(ctx) {
-                const options = ctx.options;
-                const repos = resolveRepos(options, ctx.args);
-                const format = resolveFormat(options, ctx.global);
-                const outputPath = readString(options, "output");
+                const { repos, format, outputPath } = resolveCommandInputs(ctx);
                 console.error(`pm-ops status: ${repos.length} repo(s)`);
                 const result = await collectStatusAll(repos, (m) => console.error(`  ${m}`));
                 console.error(`status: ${result.summary.ready}/${result.summary.total} ready, ${result.summary.total_issues} issue(s)`);
@@ -2311,21 +2303,16 @@ export default defineExtension({
                 "by repo with per-package current/wanted/latest columns.",
             intent: "check dependency freshness across many pm repositories",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops outdated",
+            examples: opsExamples("outdated", [
                 "pm ops outdated --repos ./pm-csv ./pm-github",
                 "pm ops outdated --format markdown",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths (comma-separated or repeatable; default: current dir)"),
-                { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
-                { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
+                ...formatOutputFlags("Write the rendered output to a file instead of stdout"),
             ],
             async run(ctx) {
-                const options = ctx.options;
-                const repos = resolveRepos(options, ctx.args);
-                const format = resolveFormat(options, ctx.global);
-                const outputPath = readString(options, "output");
+                const { repos, format, outputPath } = resolveCommandInputs(ctx);
                 console.error(`pm-ops outdated: ${repos.length} repo(s)`);
                 const result = collectOutdatedAll(repos, (m) => console.error(`  ${m}`));
                 console.error(`outdated: ${result.summary.repos_with_outdated}/${result.summary.total} repos with outdated, ${result.summary.total_outdated} total`);
@@ -2339,21 +2326,16 @@ export default defineExtension({
                 "fleet-wide vulnerability table.",
             intent: "audit security vulnerabilities across many pm repositories",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops audit",
+            examples: opsExamples("audit", [
                 "pm ops audit --repos ./pm-csv ./pm-github",
                 "pm ops audit --format markdown",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths (comma-separated or repeatable; default: current dir)"),
-                { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
-                { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
+                ...formatOutputFlags("Write the rendered output to a file instead of stdout"),
             ],
             async run(ctx) {
-                const options = ctx.options;
-                const repos = resolveRepos(options, ctx.args);
-                const format = resolveFormat(options, ctx.global);
-                const outputPath = readString(options, "output");
+                const { repos, format, outputPath } = resolveCommandInputs(ctx);
                 console.error(`pm-ops audit: ${repos.length} repo(s)`);
                 const result = collectAuditAll(repos, (m) => console.error(`  ${m}`));
                 console.error(`audit: ${result.summary.clean}/${result.summary.total} clean, ${result.summary.total_critical} critical, ${result.summary.total_high} high`);
@@ -2370,12 +2352,11 @@ export default defineExtension({
                 "exposition format; --output writes a .prom file for the node_exporter textfile collector.",
             intent: "expose pm workspace metrics to Prometheus/Grafana across many pm repositories",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops metrics",
+            examples: opsExamples("metrics", [
                 "pm ops metrics --repos ./pm-csv ./pm-github",
                 "pm ops metrics --output /var/lib/node_exporter/pm.prom",
                 "pm ops metrics --stale-days 7 --format json",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths (comma-separated or repeatable; default: current dir)"),
                 { long: "--stale-days", value_name: "days", description: "Age (days) after which an active item counts as stale (default: 14)" },
@@ -2446,26 +2427,21 @@ export default defineExtension({
                 "--warn-only reports identically but always exits 0.",
             intent: "gate fleet merges on clone-local decision receipts and merge-driver safety",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops merge-receipts",
+            examples: opsExamples("merge-receipts", [
                 "pm ops merge-receipts --repos ./pm-csv ./pm-github",
                 "pm ops merge-receipts --json",
                 "pm ops merge-receipts --warn-only",
                 "pm ops merge-receipts --include-reconciled --format markdown",
                 "pm ops merge-receipts --repos ~/container/pm-* --format markdown --output MERGE.md",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths to audit (comma-separated or repeatable; default: current dir)"),
-                { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
-                { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
+                ...formatOutputFlags("Write the rendered output to a file instead of stdout"),
                 { long: "--warn-only", description: "Report identically but always exit 0 (never fail the gate)" },
                 { long: "--include-reconciled", description: "Include receipts already represented in committed history (default: pending only)" },
             ],
             async run(ctx) {
-                const options = ctx.options;
-                const repos = resolveRepos(options, ctx.args);
-                const format = resolveFormat(options, ctx.global);
-                const outputPath = readString(options, "output");
+                const { options, repos, format, outputPath } = resolveCommandInputs(ctx);
                 const warnOnly = readBool(options, "warnOnly", "warn-only");
                 const includeReconciled = readBool(options, "includeReconciled", "include-reconciled");
                 console.error(`pm-ops merge-receipts: ${repos.length} repo(s)${includeReconciled ? " (+reconciled)" : ""}${warnOnly ? " [warn-only]" : ""}`);
@@ -2520,22 +2496,17 @@ export default defineExtension({
                 "commented-out lines cannot satisfy it. Exits non-zero when any repo has violations.",
             intent: "enforce docstring coverage across many pm repositories",
             arguments: additionalRepoArguments(),
-            examples: [
-                "pm ops docstrings",
+            examples: opsExamples("docstrings", [
                 "pm ops docstrings --repos ./pm-csv ./pm-github",
                 "pm ops docstrings --format markdown",
                 "pm ops docstrings --repos ./pm-csv --json",
-            ],
+            ]),
             flags: [
                 reposFlag("Repo paths to audit (comma-separated or repeatable; default: current dir)"),
-                { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
-                { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
+                ...formatOutputFlags("Write the rendered output to a file instead of stdout"),
             ],
             async run(ctx) {
-                const options = ctx.options;
-                const repos = resolveRepos(options, ctx.args);
-                const format = resolveFormat(options, ctx.global);
-                const outputPath = readString(options, "output");
+                const { repos, format, outputPath } = resolveCommandInputs(ctx);
                 console.error(`pm-ops docstrings: ${repos.length} repo(s)`);
                 const result = collectDocstringsAll(repos, (m) => console.error(`  ${m}`));
                 console.error(`docstrings: ${result.summary.total_violations} violation(s) across ${result.summary.with_violations}/${result.summary.total} repo(s)`);