pm-ops 2026.7.7 → 2026.7.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,9 +1,8 @@
1
1
  import { spawnSync } from "node:child_process";
2
2
  import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
3
- import * as fs from "node:fs";
4
- import { homedir } from "node:os";
5
- import { resolve, basename, dirname, join, relative } from "node:path";
6
3
  import { createRequire } from "node:module";
4
+ import { devNull, homedir } from "node:os";
5
+ import { resolve, basename, dirname, join, relative } from "node:path";
7
6
  const defineExtension = ((extension) => extension);
8
7
  // ---------------------------------------------------------------------------
9
8
  // Error contract — mirror pm-cli SDK EXIT_CODE so the host treats thrown
@@ -50,40 +49,81 @@ function asArray(value) {
50
49
  return [];
51
50
  return value.split(",").map((entry) => entry.trim()).filter(Boolean);
52
51
  }
53
- // Expand a leading `~` to the user's home directory so agent- or user-provided
54
- // paths like `~/container/pm-csv` resolve correctly instead of failing ENOENT
55
- // relative to the current working directory.
56
- function resolvePath(p) {
57
- if (p === "~")
52
+ function expandHome(path) {
53
+ if (path === "~")
58
54
  return homedir();
59
- if (p.startsWith("~/"))
60
- return resolve(join(homedir(), p.slice(2)));
61
- return resolve(p);
62
- }
63
- // Expand glob patterns (e.g. `~/container/pm-*`) so they work when the CLI is
64
- // invoked without a shell (agents, npx). Uses Node's fs.globSync when available
65
- // (Node 22+); falls back to the literal path on older Node or no matches.
66
- function expandGlob(pattern) {
67
- const resolved = resolvePath(pattern);
68
- if (!resolved.includes("*") && !resolved.includes("?"))
69
- return [resolved];
70
- const globSyncFn = fs.globSync;
71
- if (typeof globSyncFn === "function") {
72
- try {
73
- const matches = globSyncFn(resolved);
74
- if (matches.length > 0)
75
- return matches.map((m) => resolve(m));
55
+ return path.startsWith("~/") || path.startsWith("~\\") ? join(homedir(), path.slice(2)) : path;
56
+ }
57
+ function hasGlob(path) {
58
+ return /[*?\[]/.test(path);
59
+ }
60
+ function escapeRegexChar(char) {
61
+ return /[.+^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
62
+ }
63
+ function globSegmentToRegex(segment) {
64
+ let pattern = "";
65
+ for (let i = 0; i < segment.length; i += 1) {
66
+ const char = segment[i];
67
+ if (char === "*") {
68
+ pattern += "[^/]*";
69
+ continue;
76
70
  }
77
- catch {
78
- /* fall through to literal */
71
+ if (char === "?") {
72
+ pattern += "[^/]";
73
+ continue;
79
74
  }
75
+ if (char === "[") {
76
+ const end = segment.indexOf("]", i + 1);
77
+ const content = end > i + 1 ? segment.slice(i + 1, end) : "";
78
+ if (content && !content.includes("/")) {
79
+ pattern += `[${content.replace(/\\/g, "\\\\").replace(/\^/g, "\\^")}]`;
80
+ i = end;
81
+ continue;
82
+ }
83
+ }
84
+ pattern += escapeRegexChar(char);
80
85
  }
81
- return [resolved];
86
+ return new RegExp(`^${pattern}$`);
82
87
  }
83
- function resolveRepos(options) {
84
- const repos = asArray(options["repos"]);
88
+ function expandSimpleGlob(pattern) {
89
+ const expanded = expandHome(pattern);
90
+ const absolute = /^[A-Za-z]:[\\/]/.test(expanded) ? expanded : resolve(expanded);
91
+ if (!hasGlob(absolute))
92
+ return [absolute];
93
+ const driveRoot = /^[A-Za-z]:[\\/]/.exec(absolute)?.[0];
94
+ const root = absolute.startsWith("/") ? "/" : driveRoot ? driveRoot.slice(0, 3) : process.cwd();
95
+ let segments = absolute.split(/[\\/]+/).filter(Boolean);
96
+ if (driveRoot && segments[0]?.toLowerCase() === driveRoot.slice(0, 2).toLowerCase()) {
97
+ segments = segments.slice(1);
98
+ }
99
+ let candidates = [root];
100
+ for (const segment of segments) {
101
+ const next = [];
102
+ const segmentHasGlob = hasGlob(segment);
103
+ const matcher = segmentHasGlob ? globSegmentToRegex(segment) : null;
104
+ for (const candidate of candidates) {
105
+ if (!existsSync(candidate))
106
+ continue;
107
+ if (!segmentHasGlob) {
108
+ next.push(join(candidate, segment));
109
+ continue;
110
+ }
111
+ for (const entry of readdirSync(candidate, { withFileTypes: true })) {
112
+ if (matcher?.test(entry.name))
113
+ next.push(join(candidate, entry.name));
114
+ }
115
+ }
116
+ candidates = next;
117
+ }
118
+ // Sort matches so glob-expanded repo lists (and any fleet report built from
119
+ // them) are deterministic across filesystems whose readdir order is not
120
+ // guaranteed — important for stable, diff-friendly agent output.
121
+ return candidates.length > 0 ? [...candidates].sort() : [absolute];
122
+ }
123
+ function resolveRepos(options, args = []) {
124
+ const repos = [...asArray(options["repos"]), ...asArray(args)];
85
125
  if (repos.length > 0)
86
- return repos.flatMap((r) => expandGlob(r));
126
+ return repos.flatMap((r) => expandSimpleGlob(r));
87
127
  return [process.cwd()];
88
128
  }
89
129
  function resolveFormat(options) {
@@ -94,20 +134,64 @@ function resolveFormat(options) {
94
134
  return raw;
95
135
  return "toon";
96
136
  }
137
+ /**
138
+ * Spawn a subprocess without a shell.
139
+ *
140
+ * When the command is `npm` or `npx` we set `npm_config_userconfig=/dev/null`
141
+ * in the child environment. This prevents npm 11+ from reading the user-level
142
+ * `.npmrc` (which may contain `allow-scripts=…`) and forwarding that config to
143
+ * nested `npm` invocations as an env var. When a script like `release:check`
144
+ * itself calls `npm audit`, the nested npm sees the inherited
145
+ * `npm_config_allow_scripts` env var, treats it as a CLI-level override, and
146
+ * rejects it with EALLOWSCRIPTS ("--allow-scripts is not allowed in
147
+ * project-scoped installs"). Pointing userconfig at /dev/null breaks the
148
+ * chain: the parent npm never loads the `allow-scripts` line, so it never
149
+ * injects the env var into child scripts.
150
+ *
151
+ * The auth token that typically lives in `~/.npmrc` is NOT needed for the
152
+ * operations pm-ops runs (typecheck, build, test, audit, pack:dry-run,
153
+ * changelog:check, outdated) — all of which operate on local or public-registry
154
+ * data.
155
+ */
97
156
  function runSync(cmd, args, opts = {}) {
98
- // On Windows, npm/pm (and other globally-installed CLIs) are .cmd shims; spawning
99
- // them with shell:false fails with ENOENT. Append .cmd for those well-known
100
- // commands so the extension works cross-platform without forcing shell:true.
101
- const isWin = process.platform === "win32";
102
- const spawnCmd = isWin && (cmd === "npm" || cmd === "pm" || cmd === "npx") ? `${cmd}.cmd` : cmd;
103
- const r = spawnSync(spawnCmd, args, {
157
+ const env = { ...process.env, ...opts.env };
158
+ const command = process.platform === "win32" && ["npm", "npx", "pm"].includes(cmd) ? `${cmd}.cmd` : cmd;
159
+ if (cmd === "npm" || cmd === "npx") {
160
+ // Prevent npm from reading the user-level .npmrc (which may contain
161
+ // allow-scripts=…) so it never injects that config into child scripts.
162
+ env.npm_config_userconfig = devNull;
163
+ env.NPM_CONFIG_USERCONFIG = devNull;
164
+ // Also strip any inherited npm_config_allow_scripts env var that a parent
165
+ // `npm run` may have set — without this the child npm sees it as a
166
+ // CLI-level override and rejects it with EALLOWSCRIPTS.
167
+ for (const key of Object.keys(env)) {
168
+ if (key.toLowerCase() === "npm_config_allow_scripts")
169
+ delete env[key];
170
+ }
171
+ }
172
+ const r = spawnSync(command, args, {
104
173
  encoding: "utf-8",
105
174
  maxBuffer: 64 * 1024 * 1024,
106
175
  cwd: opts.cwd,
107
176
  timeout: opts.timeoutMs,
177
+ env,
108
178
  });
109
179
  return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", error: r.error };
110
180
  }
181
+ let pmInvocationCache = null;
182
+ function resolvePmInvocation() {
183
+ if (pmInvocationCache)
184
+ return pmInvocationCache;
185
+ const command = process.platform === "win32" ? "pm.cmd" : "pm";
186
+ const probe = spawnSync(command, ["--version"], { encoding: "utf-8", timeout: 5_000 });
187
+ if (!probe.error && probe.status === 0) {
188
+ pmInvocationCache = { cmd: "pm", args: [] };
189
+ return pmInvocationCache;
190
+ }
191
+ const script = process.argv[1];
192
+ pmInvocationCache = script ? { cmd: process.execPath, args: [script] } : { cmd: "pm", args: [] };
193
+ return pmInvocationCache;
194
+ }
111
195
  function parseJsonSafe(text) {
112
196
  try {
113
197
  return JSON.parse(text);
@@ -126,15 +210,50 @@ function readJsonFile(path) {
126
210
  return undefined;
127
211
  }
128
212
  }
129
- // Strip JSONC (// line comments and /* */ block comments) and trailing commas
130
- // so tsconfig.json files — which TypeScript permits to contain comments — parse
131
- // cleanly. Naive but sufficient for tsconfig: it does not strip comments inside
132
- // string literals, but tsconfig values do not contain "//" or "/*" literals.
133
- function stripJsonc(text) {
134
- return text
135
- .replace(/\/\*[\s\S]*?\*\//g, "")
136
- .replace(/\/\/[^\n\r]*/g, "")
137
- .replace(/,\s*([}\]])/g, "$1");
213
+ function stripJsonc(input) {
214
+ let output = "";
215
+ let inString = false;
216
+ let quote = "";
217
+ let escaped = false;
218
+ for (let i = 0; i < input.length; i += 1) {
219
+ const char = input[i];
220
+ const next = input[i + 1];
221
+ if (inString) {
222
+ output += char;
223
+ if (escaped) {
224
+ escaped = false;
225
+ }
226
+ else if (char === "\\") {
227
+ escaped = true;
228
+ }
229
+ else if (char === quote) {
230
+ inString = false;
231
+ }
232
+ continue;
233
+ }
234
+ if (char === "\"" || char === "'") {
235
+ inString = true;
236
+ quote = char;
237
+ output += char;
238
+ continue;
239
+ }
240
+ if (char === "/" && next === "/") {
241
+ while (i < input.length && input[i] !== "\n")
242
+ i += 1;
243
+ output += "\n";
244
+ continue;
245
+ }
246
+ if (char === "/" && next === "*") {
247
+ i += 2;
248
+ while (i < input.length && !(input[i] === "*" && input[i + 1] === "/"))
249
+ i += 1;
250
+ i += 1;
251
+ output += " ";
252
+ continue;
253
+ }
254
+ output += char;
255
+ }
256
+ return output.replace(/,\s*([}\]])/g, "$1");
138
257
  }
139
258
  function readJsoncFile(path) {
140
259
  if (!existsSync(path))
@@ -149,129 +268,82 @@ function readJsoncFile(path) {
149
268
  function readPackageJson(repoPath) {
150
269
  return readJsonFile(join(repoPath, "package.json"));
151
270
  }
152
- // pm-changelog is most often a devDependency, but some setups declare build
153
- // tooling under `dependencies`. Check both so we don't false-fail policy/scan.
154
271
  function hasPmChangelogDep(pkg) {
155
- return Boolean((pkg?.devDependencies && "pm-changelog" in pkg.devDependencies) ||
156
- (pkg?.dependencies && "pm-changelog" in pkg.dependencies));
157
- }
158
- // Resolve a tsconfig `extends` value to an absolute file path. The value may
159
- // be a relative path (./base.json, ../shared/tsconfig.json) or an npm package
160
- // specifier (@tsconfig/node20, @org/tsconfig/base.json). Relative values are
161
- // resolved against the current file's directory; package specifiers are
162
- // resolved via Node module resolution from the current file's directory.
163
- function resolveTsConfigExtends(fromPath, extendsValue) {
164
- // Relative/absolute path: resolve directly.
165
- if (extendsValue.startsWith("./") || extendsValue.startsWith("../") || extendsValue.startsWith("/")) {
166
- return resolve(dirname(fromPath), extendsValue);
167
- }
168
- // Package specifier (e.g. "@tsconfig/node20" or "@tsconfig/node20/tsconfig.json"):
169
- // use Node module resolution relative to the current config file. Some packages
170
- // expose the config at the package root (exportless), some via "exports"; try
171
- // the bare specifier first, then with /tsconfig.json appended.
272
+ return Boolean((pkg?.devDependencies && "pm-changelog" in pkg.devDependencies) || (pkg?.dependencies && "pm-changelog" in pkg.dependencies));
273
+ }
274
+ function resolveExtendsPath(currentFile, value) {
275
+ const withExtension = value.endsWith(".json") ? value : `${value}.json`;
276
+ if (value.startsWith(".") || value.startsWith("/") || value.startsWith("~")) {
277
+ return resolve(dirname(currentFile), expandHome(withExtension));
278
+ }
279
+ const requireFromConfig = createRequire(currentFile);
172
280
  try {
173
- const req = createRequire(fromPath);
281
+ return requireFromConfig.resolve(value);
282
+ }
283
+ catch {
174
284
  try {
175
- return req.resolve(extendsValue);
285
+ return requireFromConfig.resolve(withExtension);
176
286
  }
177
287
  catch {
178
- if (!extendsValue.endsWith(".json")) {
179
- try {
180
- return req.resolve(`${extendsValue}/tsconfig.json`);
181
- }
182
- catch {
183
- /* fall through */
184
- }
185
- }
288
+ return resolve(dirname(currentFile), "node_modules", withExtension);
186
289
  }
187
290
  }
188
- catch {
189
- /* createRequire needs a file URL; ignore on failure */
190
- }
191
- return undefined;
192
291
  }
193
- // Follow `extends` chains so a repo that inherits `strict: true` from a shared
194
- // base tsconfig (common in monorepos, or via npm packages like @tsconfig/node20)
195
- // is correctly detected as strict.
196
- function readTsConfigStrict(repoPath) {
197
- let currentPath = join(repoPath, "tsconfig.json");
198
- const visited = new Set();
199
- for (;;) {
200
- if (visited.has(currentPath))
201
- break;
202
- visited.add(currentPath);
203
- const cfg = readJsoncFile(currentPath);
204
- if (!cfg)
205
- break;
206
- if (cfg.compilerOptions?.strict === true)
207
- return true;
208
- if (cfg.compilerOptions?.strict === false)
209
- return false;
210
- if (typeof cfg.extends !== "string")
211
- break;
212
- const next = resolveTsConfigExtends(currentPath, cfg.extends);
213
- if (!next)
214
- break;
215
- currentPath = next;
216
- }
217
- return false;
218
- }
219
- // Resolve the pm CLI invocation. We prefer spawning the `pm` executable by name
220
- // (the common case), but fall back to the current Node + script path when `pm`
221
- // is not on PATH (npx, local monorepo bin, relative invocation). A quick
222
- // `spawnSync` probe avoids falling back unnecessarily and keeps the happy path
223
- // zero-config. Memoised: the probe result cannot change during a single process,
224
- // and runPm is called per-repo (2N times in report), so caching avoids 2N probes.
225
- let pmTargetCache;
226
- function pmSpawnTarget() {
227
- if (pmTargetCache)
228
- return pmTargetCache;
229
- const probe = spawnSync("pm", ["--version"], { encoding: "utf-8", shell: false, timeout: 10_000 });
230
- let target;
231
- if (!probe.error && probe.status === 0) {
232
- target = { cmd: "pm", leadArgs: [] };
233
- }
234
- else if (process.argv[0] && process.argv[1]) {
235
- // process.argv[0] = node binary, process.argv[1] = pm CLI script path.
236
- target = { cmd: process.argv[0], leadArgs: [process.argv[1]] };
237
- }
238
- else {
239
- target = { cmd: "pm", leadArgs: [] };
292
+ function readTsConfigStrictSetting(path, seen = new Set()) {
293
+ const resolved = resolve(path);
294
+ if (seen.has(resolved))
295
+ return null;
296
+ seen.add(resolved);
297
+ const cfg = readJsoncFile(resolved);
298
+ if (!cfg)
299
+ return null;
300
+ if (cfg.compilerOptions?.strict === true)
301
+ return true;
302
+ if (cfg.compilerOptions?.strict === false)
303
+ return false;
304
+ if (Array.isArray(cfg.extends)) {
305
+ for (const entry of [...cfg.extends].reverse()) {
306
+ if (typeof entry !== "string")
307
+ continue;
308
+ const inherited = readTsConfigStrictSetting(resolveExtendsPath(resolved, entry), seen);
309
+ if (inherited !== null)
310
+ return inherited;
311
+ }
312
+ return null;
240
313
  }
241
- pmTargetCache = target;
242
- return target;
314
+ if (typeof cfg.extends === "string")
315
+ return readTsConfigStrictSetting(resolveExtendsPath(resolved, cfg.extends), seen);
316
+ return null;
243
317
  }
244
- function runPm(args, opts = {}) {
245
- const target = pmSpawnTarget();
246
- return runSync(target.cmd, [...target.leadArgs, ...args], opts);
318
+ function readTsConfigStrict(repoPath) {
319
+ return readTsConfigStrictSetting(join(repoPath, "tsconfig.json")) === true;
247
320
  }
248
- // Per-process memo of readPmItems by repo path. scanRepos and runPolicy both
249
- // call this for the same repo, and ops report runs both, so without memoisation
250
- // a fleet of N repos spawns pm list 2N times. Cached for the lifetime of the
251
- // process (a single CLI invocation).
252
321
  const pmItemsCache = new Map();
253
322
  function readPmItems(repoPath) {
254
323
  if (pmItemsCache.has(repoPath))
255
- return pmItemsCache.get(repoPath);
256
- const result = readPmItemsUncached(repoPath);
257
- pmItemsCache.set(repoPath, result);
258
- return result;
259
- }
260
- function readPmItemsUncached(repoPath) {
324
+ return pmItemsCache.get(repoPath) ?? null;
261
325
  const pmRoot = join(repoPath, ".agents", "pm");
262
326
  if (!existsSync(pmRoot))
263
327
  return null;
264
- // Timeout so a single hung pm process can't block the whole fleet run.
265
- const r = runPm(["list", "--json", "--pm-path", pmRoot], { timeoutMs: 30_000 });
266
- if (r.status !== 0)
328
+ const pm = resolvePmInvocation();
329
+ const r = runSync(pm.cmd, [...pm.args, "list", "--json", "--pm-path", pmRoot], { timeoutMs: 30_000 });
330
+ if (r.status !== 0) {
331
+ pmItemsCache.set(repoPath, null);
267
332
  return null;
333
+ }
268
334
  const parsed = parseJsonSafe(r.stdout);
269
- if (!parsed)
335
+ if (!parsed) {
336
+ pmItemsCache.set(repoPath, null);
270
337
  return null;
338
+ }
271
339
  const items = Array.isArray(parsed) ? parsed : parsed.items ?? parsed.results ?? [];
272
- if (!Array.isArray(items))
340
+ if (!Array.isArray(items)) {
341
+ pmItemsCache.set(repoPath, null);
273
342
  return null;
274
- return items.filter((it) => Boolean(it) && typeof it === "object" && typeof it.id === "string");
343
+ }
344
+ const result = items.filter((it) => Boolean(it) && typeof it === "object" && typeof it.id === "string");
345
+ pmItemsCache.set(repoPath, result);
346
+ return result;
275
347
  }
276
348
  function isOffline() {
277
349
  return process.env.PM_OPS_OFFLINE === "1" || process.env.PM_OPS_OFFLINE === "true";
@@ -282,13 +354,9 @@ function countOutdated(repoPath) {
282
354
  const r = runSync("npm", ["outdated", "--json"], { cwd: repoPath, timeoutMs: 60_000 });
283
355
  if (r.error)
284
356
  return null;
285
- // `npm outdated --json` exits 0 with empty stdout when nothing is outdated.
286
- // That is the "0 outdated" case, not an error — return 0 instead of null.
287
- if (r.status === 0 && r.stdout.trim() === "")
288
- return 0;
289
357
  const parsed = parseJsonSafe(r.stdout);
290
358
  if (!parsed || typeof parsed !== "object")
291
- return null;
359
+ return r.status === 0 ? 0 : null;
292
360
  return Object.keys(parsed).length;
293
361
  }
294
362
  function readAudit(repoPath) {
@@ -328,13 +396,11 @@ function ghOpenCount(repoPath, kind) {
328
396
  }
329
397
  function scanRepo(repoPath) {
330
398
  const errors = [];
331
- // Guard against a non-existent directory so we don't spawn a flurry of
332
- // failing subprocesses (npm/gh) against it; report a clean not-ready result.
333
399
  if (!existsSync(repoPath)) {
334
400
  errors.push("repository directory does not exist");
335
401
  return {
336
402
  path: repoPath,
337
- name: null,
403
+ name: basename(repoPath),
338
404
  version: null,
339
405
  strict_ts: false,
340
406
  has_changelog: false,
@@ -416,10 +482,6 @@ function scanRepos(repos, progress) {
416
482
  const ready = results.filter((r) => r.ready).length;
417
483
  return { repos: results, summary: { total: results.length, ready, not_ready: results.length - ready } };
418
484
  }
419
- // Named defaults referenced when a policy check omits `params`. Declared before
420
- // DEFAULT_POLICY so the bundle references the same single source of truth (no
421
- // duplicated literals that could silently diverge), and used directly by
422
- // runPolicyCheck so reordering/inserting checks can never grab the wrong entry.
423
485
  const DEFAULT_REQUIRED_SCRIPTS = ["typecheck", "test", "build", "release:check", "changelog", "changelog:check"];
424
486
  const DEFAULT_REQUIRED_WORKFLOWS = ["ci.yml", "release.yml"];
425
487
  const DEFAULT_POLICY = {
@@ -434,7 +496,60 @@ const DEFAULT_POLICY = {
434
496
  };
435
497
  const NAME_PATTERN = /^pm-[a-z][a-z0-9-]*$/;
436
498
  const FORBIDDEN_PREFIXES = ["pm-ext-", "pm-preset-"];
437
- const RUNNER_PATTERN = /(github-hosted|macos-|windows-|ubuntu-)/;
499
+ const GITHUB_HOSTED_RUNNER_PATTERN = /^(?:github-hosted|macos-[A-Za-z0-9._-]+|windows-[A-Za-z0-9._-]+|ubuntu-[A-Za-z0-9._-]+)$/;
500
+ function leadingSpaces(value) {
501
+ return value.match(/^\s*/)?.[0].length ?? 0;
502
+ }
503
+ function normalizeYamlScalar(value) {
504
+ return value
505
+ .replace(/\s+#.*$/, "")
506
+ .replace(/,$/, "")
507
+ .trim()
508
+ .replace(/^['"]|['"]$/g, "");
509
+ }
510
+ function hasGithubHostedRunnerScalar(value) {
511
+ const normalized = normalizeYamlScalar(value);
512
+ if (!normalized || normalized.includes("${{"))
513
+ return false;
514
+ if (normalized.startsWith("{") && normalized.endsWith("}")) {
515
+ const labels = normalized.match(/\blabels\s*:\s*(\[[^\]]*\]|[^,}]+)/);
516
+ return labels ? hasGithubHostedRunnerScalar(labels[1]) : false;
517
+ }
518
+ if (normalized.startsWith("[") && normalized.endsWith("]")) {
519
+ return hasGithubHostedRunnerEntries(normalized.slice(1, -1).split(","));
520
+ }
521
+ return GITHUB_HOSTED_RUNNER_PATTERN.test(normalized);
522
+ }
523
+ function hasGithubHostedRunnerEntries(values) {
524
+ const entries = values.map(normalizeYamlScalar).filter(Boolean);
525
+ if (entries.includes("self-hosted"))
526
+ return false;
527
+ return entries.some((entry) => GITHUB_HOSTED_RUNNER_PATTERN.test(entry));
528
+ }
529
+ function hasGithubHostedRunsOnValue(inlineValue, blockLines) {
530
+ if (hasGithubHostedRunnerScalar(inlineValue))
531
+ return true;
532
+ const directItems = [];
533
+ const labelItems = [];
534
+ let inLabels = false;
535
+ for (const line of blockLines) {
536
+ const trimmed = line.trim();
537
+ const item = trimmed.match(/^-\s+(.+)$/);
538
+ const labels = trimmed.match(/^labels:\s*(.*)$/);
539
+ if (labels) {
540
+ if (labels[1].trim() && hasGithubHostedRunnerScalar(labels[1]))
541
+ return true;
542
+ inLabels = true;
543
+ continue;
544
+ }
545
+ if (item) {
546
+ (inLabels ? labelItems : directItems).push(item[1]);
547
+ continue;
548
+ }
549
+ inLabels = false;
550
+ }
551
+ return directItems.some(hasGithubHostedRunnerScalar) || hasGithubHostedRunnerEntries(labelItems);
552
+ }
438
553
  function checkNaming(name) {
439
554
  if (!name)
440
555
  return { id: "naming", severity: "error", pass: false, message: "package.json has no name" };
@@ -476,63 +591,35 @@ function checkPrivateNoRunners(repoPath) {
476
591
  for (const file of readdirSync(wfDir)) {
477
592
  if (!file.endsWith(".yml") && !file.endsWith(".yaml"))
478
593
  continue;
479
- // Guard the read so a broken symlink, permission error, or a file removed
480
- // between readdirSync/readFileSync records a per-file violation instead
481
- // of crashing the entire policy run.
482
594
  let content;
483
595
  try {
484
596
  content = readFileSync(join(wfDir, file), "utf-8");
485
597
  }
486
598
  catch (err) {
487
- violations.push(`${file}: could not read file (${err instanceof Error ? err.message : String(err)})`);
599
+ violations.push(`${file}: unable to read workflow (${err instanceof Error ? err.message : String(err)})`);
488
600
  continue;
489
601
  }
490
- // Detect GitHub-hosted runners across the YAML forms GitHub Actions supports:
491
- // runs-on: ubuntu-latest (single line)
492
- // runs-on: (multi-line list)
493
- // - ubuntu-latest
494
- // runs-on: (multi-line object: group/labels)
495
- // group: ...
496
- // labels:
497
- // - ubuntu-latest
498
- // Skip blank lines and #-comments when scanning the following block, and
499
- // stop at the first line indented no deeper than the runs-on key.
500
602
  const lines = content.split("\n");
501
- for (let i = 0; i < lines.length; i++) {
502
- const line = lines[i];
503
- const m = line.match(/^(\s*)runs-on:\s*(.*)$/);
603
+ for (const [index, line] of lines.entries()) {
604
+ const m = line.match(/^\s*runs-on:\s*(.*?)\s*$/);
504
605
  if (!m)
505
606
  continue;
506
- const indentLen = m[1].length;
507
- let value = m[2].trim();
508
- if (!value) {
509
- const items = [];
510
- for (let j = i + 1; j < lines.length; j++) {
511
- const nextLine = lines[j];
512
- if (nextLine.trim() === "" || nextLine.trim().startsWith("#"))
513
- continue;
514
- const indentMatch = nextLine.match(/^(\s*)(.*)$/);
515
- if (!indentMatch || indentMatch[1].length <= indentLen)
516
- break;
517
- const body = indentMatch[2];
518
- const itemMatch = body.match(/^-\s+(.*)$/);
519
- if (itemMatch) {
520
- items.push(itemMatch[1].trim());
521
- }
522
- else {
523
- // Object key form. Only `labels:` values correspond to actual
524
- // runner assignments; `group:` names are arbitrary identifiers for
525
- // runner groups and must NOT be tested against RUNNER_PATTERN
526
- // (a group named "ubuntu-pool" would otherwise false-positive).
527
- const kvMatch = body.match(/^labels:\s*(.*)$/);
528
- if (kvMatch && kvMatch[2])
529
- items.push(kvMatch[2].trim());
530
- }
531
- }
532
- value = items.join(" ");
607
+ if (hasGithubHostedRunsOnValue(m[1], [])) {
608
+ violations.push(`${file}: ${m[0].trim()}`);
609
+ continue;
610
+ }
611
+ const baseIndent = leadingSpaces(line);
612
+ const valueLines = [];
613
+ for (let nextIndex = index + 1; nextIndex < lines.length; nextIndex += 1) {
614
+ const nextLine = lines[nextIndex];
615
+ if (!nextLine.trim())
616
+ continue;
617
+ if (leadingSpaces(nextLine) <= baseIndent)
618
+ break;
619
+ valueLines.push(nextLine.trim());
533
620
  }
534
- if (RUNNER_PATTERN.test(value))
535
- violations.push(`${file}: runs-on ${value}`);
621
+ if (hasGithubHostedRunsOnValue("", valueLines))
622
+ violations.push(`${file}: runs-on uses a GitHub-hosted runner`);
536
623
  }
537
624
  }
538
625
  }
@@ -576,36 +663,30 @@ function checkPmChangelogWired(pkg) {
576
663
  };
577
664
  }
578
665
  function runPolicyCheck(def, ctx) {
579
- let res;
666
+ let result;
580
667
  switch (def.id) {
581
668
  case "naming":
582
- res = checkNaming(ctx.pkg?.name ?? null);
669
+ result = checkNaming(ctx.pkg?.name ?? null);
583
670
  break;
584
671
  case "required-scripts":
585
- res = checkRequiredScripts(ctx.pkg, def.params?.scripts ?? DEFAULT_REQUIRED_SCRIPTS);
672
+ result = checkRequiredScripts(ctx.pkg, def.params?.scripts ?? DEFAULT_REQUIRED_SCRIPTS);
586
673
  break;
587
674
  case "required-workflows":
588
- res = checkRequiredWorkflows(ctx.repoPath, def.params?.workflows ?? DEFAULT_REQUIRED_WORKFLOWS);
675
+ result = checkRequiredWorkflows(ctx.repoPath, def.params?.workflows ?? DEFAULT_REQUIRED_WORKFLOWS);
589
676
  break;
590
677
  case "private-no-runners":
591
- res = checkPrivateNoRunners(ctx.repoPath);
678
+ result = checkPrivateNoRunners(ctx.repoPath);
592
679
  break;
593
680
  case "pm-duplicate-titles":
594
- res = checkPmDuplicateTitles(ctx.items);
681
+ result = checkPmDuplicateTitles(ctx.items);
595
682
  break;
596
683
  case "pm-changelog-wired":
597
- res = checkPmChangelogWired(ctx.pkg);
684
+ result = checkPmChangelogWired(ctx.pkg);
598
685
  break;
599
686
  default:
600
- res = { id: def.id, severity: def.severity, pass: false, message: `unknown check id "${def.id}"` };
687
+ result = { id: def.id, severity: def.severity, pass: false, message: `unknown check id "${def.id}"` };
601
688
  }
602
- // Preserve any custom severity override declared in the policy bundle so
603
- // per-check output is consistent with the policy definition (a check the
604
- // user downgraded to "warning" should not be reported as "error").
605
- if (def.severity && res.severity !== def.severity) {
606
- return { ...res, severity: def.severity };
607
- }
608
- return res;
689
+ return { ...result, severity: def.severity };
609
690
  }
610
691
  function matchesFilter(repoPath, name, filter) {
611
692
  if (!filter)
@@ -641,20 +722,48 @@ function runPolicy(repos, bundle, progress) {
641
722
  return { repos: repoResults, summary: { total: repos.length, passed: totalPassed, failed: totalFailed, by_severity } };
642
723
  }
643
724
  const FALLBACK_STEPS = ["typecheck", "build", "test", "audit:prod", "pack:dry-run", "changelog:check"];
725
+ /**
726
+ * Extract a concise, human-readable error reason from npm stdout/stderr.
727
+ * npm errors typically include `npm error code XXX` and a message line;
728
+ * we surface the code + message so the user sees *why* a check failed
729
+ * without having to scroll through full build output.
730
+ */
731
+ function summarizeNpmError(stdout, stderr, args) {
732
+ const combined = `${stderr}\n${stdout}`.trim();
733
+ if (!combined)
734
+ return `npm ${args.join(" ")} exited non-zero (no output)`;
735
+ // Extract npm error code and message
736
+ const codeMatch = combined.match(/npm error code (\S+)/);
737
+ const msgMatch = combined.match(/^npm error (?!code\b|A complete log\b)(.+)$/m);
738
+ if (codeMatch && msgMatch) {
739
+ return `[${codeMatch[1]}] ${msgMatch[1].trim()}`;
740
+ }
741
+ if (codeMatch) {
742
+ return `npm error code ${codeMatch[1]}`;
743
+ }
744
+ // Fall back to last non-trivial lines of stderr
745
+ const lines = combined.split("\n").filter((l) => l.trim() && !l.startsWith(">"));
746
+ return lines.slice(-3).join(" | ").slice(-2000);
747
+ }
644
748
  function runReleaseCheck(repoPath, name, args, progress) {
645
749
  progress(`verify ${relative(process.cwd(), repoPath) || repoPath}: ${name}`);
646
750
  const start = Date.now();
647
751
  const r = runSync("npm", args, { cwd: repoPath, timeoutMs: 5 * 60_000 });
648
752
  const duration_ms = Date.now() - start;
649
- // Treat a spawn/timeout error (r.error, e.g. ETIMEDOUT/ENOENT) as a failure
650
- // and surface its message so agents get a clear reason, not just an exit code.
651
- const pass = r.status === 0 && !r.error;
652
- const error = pass
653
- ? undefined
654
- : (r.error?.message || r.stderr.trim() || r.stdout.trim() || `npm ${args.join(" ")} exited ${r.status}`).slice(-2000);
753
+ const pass = r.status === 0;
754
+ const error = pass ? undefined : r.error?.message ?? summarizeNpmError(r.stdout, r.stderr, args);
655
755
  return { name, pass, duration_ms, error };
656
756
  }
657
757
  function verifyReleaseRepo(repoPath, progress) {
758
+ if (!existsSync(repoPath)) {
759
+ return {
760
+ path: repoPath,
761
+ name: basename(repoPath),
762
+ checks: [{ name: "release:check", pass: false, duration_ms: 0, error: `repository directory does not exist: ${repoPath}` }],
763
+ passed: 0,
764
+ failed: 1,
765
+ };
766
+ }
658
767
  const pkg = readPackageJson(repoPath);
659
768
  const scripts = pkg?.scripts ?? {};
660
769
  let checks;
@@ -666,30 +775,8 @@ function verifyReleaseRepo(repoPath, progress) {
666
775
  .filter((s) => typeof scripts[s] === "string")
667
776
  .map((s) => runReleaseCheck(repoPath, s, ["run", s], progress));
668
777
  }
669
- // A missing repo directory should be reported as a path error, not mislabeled
670
- // as "no release gate found". Check existence first for accurate diagnostics.
671
- if (!existsSync(repoPath)) {
672
- checks = [
673
- {
674
- name: "release:check",
675
- pass: false,
676
- duration_ms: 0,
677
- error: `repository directory does not exist: ${repoPath}`,
678
- },
679
- ];
680
- }
681
- else if (checks.length === 0) {
682
- // A repo with no runnable release scripts would otherwise be a false green.
683
- // Surface it as a single failed check so verify-release never reports a
684
- // release-ready state for a repo that has no gate defined.
685
- checks = [
686
- {
687
- name: "release:check",
688
- pass: false,
689
- duration_ms: 0,
690
- error: "no release gate found: define a `release:check` script (or at least one of typecheck/build/test/audit:prod/pack:dry-run/changelog:check)",
691
- },
692
- ];
778
+ if (checks.length === 0) {
779
+ checks = [{ name: "release:check", pass: false, duration_ms: 0, error: "no release gate script found" }];
693
780
  }
694
781
  const passed = checks.filter((c) => c.pass).length;
695
782
  const failed = checks.filter((c) => !c.pass).length;
@@ -718,17 +805,232 @@ function renderVerifyReleaseMarkdown(result) {
718
805
  c.name,
719
806
  c.pass ? "yes" : "no",
720
807
  String(c.duration_ms),
721
- // Escape pipes AND collapse newlines so a multi-line build/test error
722
- // can't split this cell across rows and corrupt the markdown table.
723
- (c.error ?? "").replace(/\|/g, "\\|").replace(/[\r\n]+/g, " ⏎ ").slice(0, 200),
808
+ (c.error ?? "").replace(/\s+/g, " ").replace(/\|/g, "\\|").slice(0, 200),
724
809
  ]));
725
810
  }
726
811
  }
727
812
  lines.push("");
728
813
  return lines.join("\n");
729
814
  }
730
- function buildReport(repos, progress) {
731
- return { generated_at: new Date().toISOString(), scan: scanRepos(repos, progress), policy: runPolicy(repos, DEFAULT_POLICY, progress) };
815
+ function collectStatus(repoPath) {
816
+ if (!existsSync(repoPath)) {
817
+ return {
818
+ path: repoPath,
819
+ name: basename(repoPath),
820
+ version: null,
821
+ ready: false,
822
+ issues: ["repository directory does not exist"],
823
+ pm_open_items: null,
824
+ audit_critical: null,
825
+ audit_high: null,
826
+ outdated_count: null,
827
+ };
828
+ }
829
+ const pkg = readPackageJson(repoPath);
830
+ const name = pkg?.name ?? null;
831
+ const version = pkg?.version ?? null;
832
+ const issues = [];
833
+ const strict_ts = readTsConfigStrict(repoPath);
834
+ if (!strict_ts)
835
+ issues.push("strict TS not enabled");
836
+ const has_changelog = existsSync(join(repoPath, "CHANGELOG.md"));
837
+ if (!has_changelog)
838
+ issues.push("no CHANGELOG.md");
839
+ const has_release_workflow = existsSync(join(repoPath, ".github", "workflows", "release.yml"));
840
+ if (!has_release_workflow)
841
+ issues.push("no release workflow");
842
+ const has_ci = existsSync(join(repoPath, ".github", "workflows", "ci.yml"));
843
+ if (!has_ci)
844
+ issues.push("no CI workflow");
845
+ const has_pm_changelog = hasPmChangelogDep(pkg);
846
+ if (!has_pm_changelog)
847
+ issues.push("pm-changelog not wired");
848
+ let outdated_count = null;
849
+ try {
850
+ outdated_count = countOutdated(repoPath);
851
+ }
852
+ catch { /* ignore */ }
853
+ let audit_critical = null;
854
+ let audit_high = null;
855
+ try {
856
+ const a = readAudit(repoPath);
857
+ audit_critical = a.critical;
858
+ audit_high = a.high;
859
+ }
860
+ catch { /* ignore */ }
861
+ if (audit_critical !== null && audit_critical > 0)
862
+ issues.push(`${audit_critical} critical vuln(s)`);
863
+ if (audit_high !== null && audit_high > 0)
864
+ issues.push(`${audit_high} high vuln(s)`);
865
+ const items = readPmItems(repoPath);
866
+ const pm_open_items = items ? items.filter((i) => (i.status ?? "").toLowerCase() === "open").length : null;
867
+ const ready = issues.length === 0;
868
+ return { path: repoPath, name, version, ready, issues, pm_open_items, audit_critical, audit_high, outdated_count };
869
+ }
870
+ function collectStatusAll(repos, progress) {
871
+ const results = repos.map((repo) => {
872
+ progress(`status ${repo}`);
873
+ return collectStatus(repo);
874
+ });
875
+ const ready = results.filter((r) => r.ready).length;
876
+ const totalIssues = results.reduce((sum, r) => sum + r.issues.length, 0);
877
+ return { repos: results, summary: { total: results.length, ready, not_ready: results.length - ready, total_issues: totalIssues } };
878
+ }
879
+ function renderStatusMarkdown(result) {
880
+ const lines = [];
881
+ lines.push("# pm-ops status");
882
+ lines.push("");
883
+ lines.push(`Fleet: **${result.summary.total}** repo(s) — **${result.summary.ready}** ready, **${result.summary.not_ready}** not ready, **${result.summary.total_issues}** issue(s).`);
884
+ lines.push("");
885
+ lines.push(renderMarkdownRow(["repo", "version", "ready", "open items", "outdated", "critical", "high", "issues"]));
886
+ lines.push(renderMarkdownRow(["---", "---", "---", "---", "---", "---", "---", "---"]));
887
+ for (const r of result.repos) {
888
+ lines.push(renderMarkdownRow([
889
+ r.name ?? basename(r.path),
890
+ r.version ?? "-",
891
+ r.ready ? "yes" : "no",
892
+ formatCount(r.pm_open_items),
893
+ formatCount(r.outdated_count),
894
+ formatCount(r.audit_critical),
895
+ formatCount(r.audit_high),
896
+ r.issues.length === 0 ? "-" : r.issues.join("; ").replace(/\|/g, "\\|").slice(0, 200),
897
+ ]));
898
+ }
899
+ lines.push("");
900
+ return lines.join("\n");
901
+ }
902
+ function collectOutdatedRepo(repoPath) {
903
+ const pkg = readPackageJson(repoPath);
904
+ if (isOffline()) {
905
+ return { path: repoPath, name: pkg?.name ?? null, outdated: [], count: null, error: "offline mode enabled" };
906
+ }
907
+ const r = runSync("npm", ["outdated", "--json"], { cwd: repoPath, timeoutMs: 60_000 });
908
+ if (r.error) {
909
+ return { path: repoPath, name: pkg?.name ?? null, outdated: [], count: null, error: r.error.message };
910
+ }
911
+ const entries = [];
912
+ if (r.status !== 0 && r.status !== 1) {
913
+ // npm outdated exits 0 if no outdated, 1 if some outdated
914
+ return { path: repoPath, name: pkg?.name ?? null, outdated: [], count: null, error: summarizeNpmError(r.stdout, r.stderr, ["outdated", "--json"]) };
915
+ }
916
+ const parsed = parseJsonSafe(r.stdout);
917
+ if (parsed && typeof parsed === "object") {
918
+ for (const [name, info] of Object.entries(parsed)) {
919
+ if (info && typeof info === "object") {
920
+ entries.push({
921
+ name,
922
+ current: String(info.current ?? "-"),
923
+ wanted: String(info.wanted ?? "-"),
924
+ latest: String(info.latest ?? "-"),
925
+ type: String(info.type ?? "-"),
926
+ });
927
+ }
928
+ }
929
+ }
930
+ return { path: repoPath, name: pkg?.name ?? null, outdated: entries, count: entries.length };
931
+ }
932
+ function collectOutdatedAll(repos, progress) {
933
+ const results = repos.map((repo) => {
934
+ progress(`outdated ${repo}`);
935
+ return collectOutdatedRepo(repo);
936
+ });
937
+ const withOutdated = results.filter((r) => (r.count ?? 0) > 0).length;
938
+ const totalOutdated = results.reduce((sum, r) => sum + (r.count ?? 0), 0);
939
+ return { repos: results, summary: { total: results.length, repos_with_outdated: withOutdated, total_outdated: totalOutdated } };
940
+ }
941
+ function renderOutdatedMarkdown(result) {
942
+ const lines = [];
943
+ lines.push("# pm-ops outdated");
944
+ lines.push("");
945
+ lines.push(`Checked **${result.summary.total}** repo(s): **${result.summary.repos_with_outdated}** have outdated deps, **${result.summary.total_outdated}** total outdated package(s).`);
946
+ lines.push("");
947
+ for (const repo of result.repos) {
948
+ if (repo.count === null) {
949
+ lines.push(`## ${repo.name ?? basename(repo.path)}`);
950
+ lines.push("");
951
+ lines.push(repo.error ? `Unable to check outdated dependencies: ${repo.error}` : "Unable to check outdated dependencies.");
952
+ lines.push("");
953
+ continue;
954
+ }
955
+ if (repo.count === 0)
956
+ continue;
957
+ lines.push(`## ${repo.name ?? basename(repo.path)}`);
958
+ lines.push("");
959
+ lines.push(renderMarkdownRow(["package", "current", "wanted", "latest", "type"]));
960
+ lines.push(renderMarkdownRow(["---", "---", "---", "---", "---"]));
961
+ for (const e of repo.outdated) {
962
+ lines.push(renderMarkdownRow([e.name, e.current, e.wanted, e.latest, e.type]));
963
+ }
964
+ lines.push("");
965
+ }
966
+ const unknownCount = result.repos.filter((r) => r.count === null).length;
967
+ if (result.summary.total_outdated === 0 && unknownCount === 0) {
968
+ lines.push("All dependencies are up to date.");
969
+ lines.push("");
970
+ }
971
+ return lines.join("\n");
972
+ }
973
+ function collectAuditRepo(repoPath) {
974
+ const pkg = readPackageJson(repoPath);
975
+ if (isOffline()) {
976
+ return { path: repoPath, name: pkg?.name ?? null, critical: null, high: null, moderate: null, low: null, total: null, ok: false };
977
+ }
978
+ const r = runSync("npm", ["audit", "--omit=dev", "--json"], { cwd: repoPath, timeoutMs: 60_000 });
979
+ if (r.error) {
980
+ return { path: repoPath, name: pkg?.name ?? null, critical: null, high: null, moderate: null, low: null, total: null, ok: false };
981
+ }
982
+ const parsed = parseJsonSafe(r.stdout);
983
+ const v = parsed?.metadata?.vulnerabilities;
984
+ if (!v) {
985
+ return { path: repoPath, name: pkg?.name ?? null, critical: null, high: null, moderate: null, low: null, total: null, ok: false };
986
+ }
987
+ const critical = v.critical ?? 0;
988
+ const high = v.high ?? 0;
989
+ const moderate = v.moderate ?? 0;
990
+ const low = v.low ?? 0;
991
+ const total = v.total ?? 0;
992
+ return { path: repoPath, name: pkg?.name ?? null, critical, high, moderate, low, total, ok: total === 0 };
993
+ }
994
+ function collectAuditAll(repos, progress) {
995
+ const results = repos.map((repo) => {
996
+ progress(`audit ${repo}`);
997
+ return collectAuditRepo(repo);
998
+ });
999
+ const clean = results.filter((r) => r.ok).length;
1000
+ const withVulns = results.filter((r) => r.total !== null && r.total > 0).length;
1001
+ const unknown = results.filter((r) => r.total === null).length;
1002
+ const totalCritical = results.reduce((s, r) => s + (r.critical ?? 0), 0);
1003
+ const totalHigh = results.reduce((s, r) => s + (r.high ?? 0), 0);
1004
+ return { repos: results, summary: { total: results.length, clean, with_vulns: withVulns, unknown, total_critical: totalCritical, total_high: totalHigh } };
1005
+ }
1006
+ function renderAuditMarkdown(result) {
1007
+ const lines = [];
1008
+ lines.push("# pm-ops audit");
1009
+ lines.push("");
1010
+ lines.push(`Audited **${result.summary.total}** repo(s): **${result.summary.clean}** clean, **${result.summary.with_vulns}** with vulnerabilities, **${result.summary.unknown}** unknown.`);
1011
+ lines.push(`Total: **${result.summary.total_critical}** critical, **${result.summary.total_high}** high.`);
1012
+ lines.push("");
1013
+ lines.push(renderMarkdownRow(["repo", "critical", "high", "moderate", "low", "total", "status"]));
1014
+ lines.push(renderMarkdownRow(["---", "---", "---", "---", "---", "---", "---"]));
1015
+ for (const r of result.repos) {
1016
+ lines.push(renderMarkdownRow([
1017
+ r.name ?? basename(r.path),
1018
+ formatCount(r.critical),
1019
+ formatCount(r.high),
1020
+ formatCount(r.moderate),
1021
+ formatCount(r.low),
1022
+ formatCount(r.total),
1023
+ r.total === null ? "?" : r.ok ? "clean" : "vulns",
1024
+ ]));
1025
+ }
1026
+ lines.push("");
1027
+ return lines.join("\n");
1028
+ }
1029
+ function buildReport(repos, progress, includeRelease = false) {
1030
+ const scan = scanRepos(repos, progress);
1031
+ const policy = runPolicy(repos, DEFAULT_POLICY, progress);
1032
+ const release = includeRelease ? verifyRelease(repos, progress) : undefined;
1033
+ return { generated_at: new Date().toISOString(), scan, policy, release };
732
1034
  }
733
1035
  // ---------------------------------------------------------------------------
734
1036
  // Formatters
@@ -795,26 +1097,28 @@ function renderPolicyMarkdown(result) {
795
1097
  return lines.join("\n");
796
1098
  }
797
1099
  function renderReportMarkdown(result) {
798
- return [renderScanMarkdown(result.scan), "", renderPolicyMarkdown(result.policy)].join("\n");
799
- }
800
- // Serialize the structured result as JSON. Branching JSON separately from the
801
- // markdown formatter ensures `--format json` / `--json` and `--output <file>`
802
- // write real serialized JSON, not markdown.
803
- function jsonOf(structured) {
804
- return `${JSON.stringify(structured, null, 2)}\n`;
1100
+ const sections = [];
1101
+ // Header with timestamp
1102
+ sections.push(`# pm-ops Fleet Report`);
1103
+ sections.push("");
1104
+ sections.push(`_Generated: ${result.generated_at}_`);
1105
+ sections.push("");
1106
+ sections.push("");
1107
+ // Scan section
1108
+ sections.push(renderScanMarkdown(result.scan));
1109
+ sections.push("");
1110
+ // Policy section
1111
+ sections.push(renderPolicyMarkdown(result.policy));
1112
+ if (result.release) {
1113
+ sections.push("");
1114
+ sections.push(renderVerifyReleaseMarkdown(result.release));
1115
+ }
1116
+ return sections.join("\n");
805
1117
  }
806
1118
  function emitResult(structured, format, outputPath, formatter) {
807
1119
  if (outputPath) {
808
- // Create parent directories so --output ./reports/fleet.md works on a fresh
809
- // checkout instead of crashing with a raw ENOENT.
810
- const parent = dirname(resolvePath(outputPath));
811
- try {
812
- mkdirSync(parent, { recursive: true });
813
- }
814
- catch {
815
- /* ignore — writeFileSync will surface a clean error if the dir is unusable */
816
- }
817
- const body = format === "markdown" ? formatter() : jsonOf(structured);
1120
+ mkdirSync(dirname(resolve(outputPath)), { recursive: true });
1121
+ const body = format === "markdown" ? formatter() : `${JSON.stringify(structured, null, 2)}\n`;
818
1122
  writeFileSync(outputPath, body, "utf-8");
819
1123
  console.error(`pm-ops: wrote ${format} output to ${outputPath}`);
820
1124
  return { written_to: outputPath, format };
@@ -822,7 +1126,7 @@ function emitResult(structured, format, outputPath, formatter) {
822
1126
  if (format === "toon")
823
1127
  return structured;
824
1128
  if (format === "json")
825
- return renderedCommandResult(jsonOf(structured));
1129
+ return renderedCommandResult(`${JSON.stringify(structured, null, 2)}\n`);
826
1130
  return renderedCommandResult(formatter());
827
1131
  }
828
1132
  // ---------------------------------------------------------------------------
@@ -830,7 +1134,7 @@ function emitResult(structured, format, outputPath, formatter) {
830
1134
  // ---------------------------------------------------------------------------
831
1135
  export default defineExtension({
832
1136
  name: "pm-ops",
833
- version: "2026.7.7",
1137
+ version: "2026.7.10",
834
1138
  activate(api) {
835
1139
  if (typeof api.registerRenderer === "function") {
836
1140
  api.registerRenderer("toon", renderCommandResult);
@@ -858,7 +1162,7 @@ export default defineExtension({
858
1162
  ],
859
1163
  async run(ctx) {
860
1164
  const options = ctx.options;
861
- const repos = resolveRepos(options);
1165
+ const repos = resolveRepos(options, ctx.args);
862
1166
  const format = resolveFormat(options);
863
1167
  const outputPath = readString(options, "output");
864
1168
  console.error(`pm-ops scan: ${repos.length} repo(s)`);
@@ -891,14 +1195,14 @@ export default defineExtension({
891
1195
  ],
892
1196
  async run(ctx) {
893
1197
  const options = ctx.options;
894
- const repos = resolveRepos(options);
1198
+ const repos = resolveRepos(options, ctx.args);
895
1199
  const format = resolveFormat(options);
896
1200
  const strict = readBool(options, "strict");
897
1201
  const outputPath = readString(options, "output");
898
1202
  let bundle = DEFAULT_POLICY;
899
1203
  const policyFile = readString(options, "policy");
900
1204
  if (policyFile) {
901
- const loaded = readJsonFile(resolvePath(policyFile));
1205
+ const loaded = readJsonFile(resolve(policyFile));
902
1206
  if (!loaded || !Array.isArray(loaded.checks)) {
903
1207
  throw new CommandError(`--policy file "${policyFile}" is not a valid policy bundle (expected { checks: [...] })`, EXIT_CODE.USAGE);
904
1208
  }
@@ -907,21 +1211,16 @@ export default defineExtension({
907
1211
  console.error(`pm-ops policy: ${repos.length} repo(s), ${bundle.checks.length} check(s)`);
908
1212
  const result = runPolicy(repos, bundle, (m) => console.error(` ${m}`));
909
1213
  console.error(`policy: ${result.summary.passed} passed, ${result.summary.failed} failed`);
910
- const failed = result.summary.failed > 0;
911
- // In strict mode with failures, ensure the formatted result is produced
912
- // (to the --output file if set, else to stdout) BEFORE throwing so
913
- // users/agents still see which checks failed. The throw itself must
914
- // happen regardless of --output so CI exit-code gating is never bypassed.
915
- if (strict && failed) {
1214
+ if (strict && result.summary.failed > 0) {
916
1215
  if (outputPath) {
917
- // emitResult writes the file and returns a summary; discard return.
918
1216
  emitResult(result, format, outputPath, () => renderPolicyMarkdown(result));
919
1217
  }
920
1218
  else if (format === "markdown") {
921
- process.stdout.write(`${renderPolicyMarkdown(result)}\n`);
1219
+ const md = renderPolicyMarkdown(result);
1220
+ process.stdout.write(md.endsWith("\n") ? md : `${md}\n`);
922
1221
  }
923
1222
  else {
924
- process.stdout.write(jsonOf(result));
1223
+ process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
925
1224
  }
926
1225
  throw new CommandError(`policy: ${result.summary.failed} check(s) failed (strict mode)`, EXIT_CODE.GENERIC_FAILURE);
927
1226
  }
@@ -932,26 +1231,48 @@ export default defineExtension({
932
1231
  name: "ops verify-release",
933
1232
  description: "Run the release gate matrix per repo: executes `npm run release:check` (or the individual " +
934
1233
  "typecheck/build/test/audit:prod/pack:dry-run/changelog:check steps when release:check is missing) " +
935
- "and reports pass/fail with per-step timing. Does NOT publish. Exits non-zero if any repo fails.",
1234
+ "and reports pass/fail with per-step timing and concise error summaries. Does NOT publish. " +
1235
+ "Exits non-zero if any repo fails. --output writes the report to a file.",
936
1236
  intent: "run a release gate matrix across many pm repositories",
937
1237
  examples: [
938
1238
  "pm ops verify-release",
939
1239
  "pm ops verify-release --repos ./pm-csv ./pm-github",
940
1240
  "pm ops verify-release --json",
1241
+ "pm ops verify-release --format markdown --output RELEASE.md",
941
1242
  ],
942
1243
  flags: [
943
1244
  { long: "--repos", value_name: "paths", description: "Repo paths to verify (comma-separated or repeatable; default: current dir)", list: true },
944
1245
  { long: "--json", description: "Emit clean JSON to stdout (progress on stderr)" },
945
1246
  { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
1247
+ { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
946
1248
  ],
947
1249
  async run(ctx) {
948
1250
  const options = ctx.options;
949
- const repos = resolveRepos(options);
1251
+ const repos = resolveRepos(options, ctx.args);
950
1252
  const format = resolveFormat(options);
1253
+ const outputPath = readString(options, "output");
951
1254
  console.error(`pm-ops verify-release: ${repos.length} repo(s)`);
952
1255
  const result = verifyRelease(repos, (m) => console.error(` ${m}`));
953
1256
  console.error(`verify-release: ${result.summary.passed}/${result.summary.total} repos passed`);
954
1257
  const failed = result.summary.failed > 0;
1258
+ if (failed) {
1259
+ // Log a concise summary of which repos failed and why
1260
+ for (const repo of result.repos) {
1261
+ if (repo.failed > 0) {
1262
+ const failedChecks = repo.checks.filter((c) => !c.pass).map((c) => `${c.name}: ${(c.error ?? "unknown").slice(0, 120)}`);
1263
+ console.error(` FAIL ${repo.name ?? basename(repo.path)}: ${failedChecks.join("; ")}`);
1264
+ }
1265
+ }
1266
+ }
1267
+ if (outputPath) {
1268
+ mkdirSync(dirname(resolve(outputPath)), { recursive: true });
1269
+ const body = format === "markdown" ? renderVerifyReleaseMarkdown(result) : `${JSON.stringify(result, null, 2)}\n`;
1270
+ writeFileSync(outputPath, body, "utf-8");
1271
+ console.error(`pm-ops: wrote ${format} output to ${outputPath}`);
1272
+ if (failed)
1273
+ throw new CommandError(`verify-release: ${result.summary.failed} repo(s) failed`, EXIT_CODE.GENERIC_FAILURE);
1274
+ return { written_to: outputPath, format };
1275
+ }
955
1276
  if (format === "json") {
956
1277
  if (failed) {
957
1278
  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
@@ -976,13 +1297,16 @@ export default defineExtension({
976
1297
  });
977
1298
  api.registerCommand({
978
1299
  name: "ops report",
979
- description: "Emit a concise fleet report combining scan + policy results. --format markdown produces " +
980
- "a PR/issue-ready summary table. --output writes the report to a file. Default stdout TOON.",
1300
+ description: "Emit a concise fleet report combining scan + policy results (and optionally verify-release). " +
1301
+ "--format markdown produces a PR/issue-ready summary table with timestamp header. " +
1302
+ "--include-release also runs the release gate matrix and appends results. " +
1303
+ "--output writes the report to a file. Default stdout TOON.",
981
1304
  intent: "produce a concise fleet report across many pm repositories",
982
1305
  examples: [
983
1306
  "pm ops report",
984
1307
  "pm ops report --repos ./pm-csv ./pm-github --format markdown",
985
1308
  "pm ops report --format markdown --output FLEET.md",
1309
+ "pm ops report --format markdown --include-release --output FLEET.md",
986
1310
  "pm ops report --json",
987
1311
  ],
988
1312
  flags: [
@@ -990,18 +1314,106 @@ export default defineExtension({
990
1314
  { long: "--json", description: "Emit clean JSON to stdout (progress on stderr)" },
991
1315
  { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
992
1316
  { long: "--output", value_name: "file", description: "Write the rendered report to a file instead of stdout" },
1317
+ { long: "--include-release", description: "Also run verify-release and include results in the report" },
993
1318
  ],
994
1319
  async run(ctx) {
995
1320
  const options = ctx.options;
996
- const repos = resolveRepos(options);
1321
+ const repos = resolveRepos(options, ctx.args);
997
1322
  const format = resolveFormat(options);
998
1323
  const outputPath = readString(options, "output");
999
- console.error(`pm-ops report: ${repos.length} repo(s)`);
1000
- const result = buildReport(repos, (m) => console.error(` ${m}`));
1001
- console.error(`report: scan ${result.scan.summary.ready}/${result.scan.summary.total} ready; policy ${result.policy.summary.failed} failed`);
1324
+ const includeRelease = readBool(options, "include-release");
1325
+ console.error(`pm-ops report: ${repos.length} repo(s)${includeRelease ? " (+release)" : ""}`);
1326
+ const result = buildReport(repos, (m) => console.error(` ${m}`), includeRelease);
1327
+ 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` : ""}`);
1002
1328
  return emitResult(result, format, outputPath, () => renderReportMarkdown(result));
1003
1329
  },
1004
1330
  });
1331
+ // --- New fleet operations commands ---
1332
+ api.registerCommand({
1333
+ name: "ops status",
1334
+ description: "Quick fleet status overview: for each repo shows name, version, ready/not-ready, " +
1335
+ "open pm items, outdated deps, and critical/high vulnerabilities. Faster than scan " +
1336
+ "because it skips GitHub PR/issue probes and pm workspace detail. --format markdown " +
1337
+ "emits a compact table.",
1338
+ intent: "get a quick fleet health overview across many pm repositories",
1339
+ examples: [
1340
+ "pm ops status",
1341
+ "pm ops status --repos ./pm-csv ./pm-github",
1342
+ "pm ops status --format markdown",
1343
+ ],
1344
+ flags: [
1345
+ { long: "--repos", value_name: "paths", description: "Repo paths (comma-separated or repeatable; default: current dir)", list: true },
1346
+ { long: "--json", description: "Emit clean JSON to stdout (progress on stderr)" },
1347
+ { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
1348
+ { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
1349
+ ],
1350
+ async run(ctx) {
1351
+ const options = ctx.options;
1352
+ const repos = resolveRepos(options, ctx.args);
1353
+ const format = resolveFormat(options);
1354
+ const outputPath = readString(options, "output");
1355
+ console.error(`pm-ops status: ${repos.length} repo(s)`);
1356
+ const result = collectStatusAll(repos, (m) => console.error(` ${m}`));
1357
+ console.error(`status: ${result.summary.ready}/${result.summary.total} ready, ${result.summary.total_issues} issue(s)`);
1358
+ return emitResult(result, format, outputPath, () => renderStatusMarkdown(result));
1359
+ },
1360
+ });
1361
+ api.registerCommand({
1362
+ name: "ops outdated",
1363
+ description: "Check outdated dependencies across repos. Runs `npm outdated --json` per repo and " +
1364
+ "summarizes packages that have newer versions available. --format markdown groups " +
1365
+ "by repo with per-package current/wanted/latest columns.",
1366
+ intent: "check dependency freshness across many pm repositories",
1367
+ examples: [
1368
+ "pm ops outdated",
1369
+ "pm ops outdated --repos ./pm-csv ./pm-github",
1370
+ "pm ops outdated --format markdown",
1371
+ ],
1372
+ flags: [
1373
+ { long: "--repos", value_name: "paths", description: "Repo paths (comma-separated or repeatable; default: current dir)", list: true },
1374
+ { long: "--json", description: "Emit clean JSON to stdout (progress on stderr)" },
1375
+ { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
1376
+ { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
1377
+ ],
1378
+ async run(ctx) {
1379
+ const options = ctx.options;
1380
+ const repos = resolveRepos(options, ctx.args);
1381
+ const format = resolveFormat(options);
1382
+ const outputPath = readString(options, "output");
1383
+ console.error(`pm-ops outdated: ${repos.length} repo(s)`);
1384
+ const result = collectOutdatedAll(repos, (m) => console.error(` ${m}`));
1385
+ console.error(`outdated: ${result.summary.repos_with_outdated}/${result.summary.total} repos with outdated, ${result.summary.total_outdated} total`);
1386
+ return emitResult(result, format, outputPath, () => renderOutdatedMarkdown(result));
1387
+ },
1388
+ });
1389
+ api.registerCommand({
1390
+ name: "ops audit",
1391
+ description: "Security vulnerability audit across repos. Runs `npm audit --omit=dev --json` per repo " +
1392
+ "and summarizes critical/high/moderate/low counts. --format markdown emits a compact " +
1393
+ "fleet-wide vulnerability table.",
1394
+ intent: "audit security vulnerabilities across many pm repositories",
1395
+ examples: [
1396
+ "pm ops audit",
1397
+ "pm ops audit --repos ./pm-csv ./pm-github",
1398
+ "pm ops audit --format markdown",
1399
+ ],
1400
+ flags: [
1401
+ { long: "--repos", value_name: "paths", description: "Repo paths (comma-separated or repeatable; default: current dir)", list: true },
1402
+ { long: "--json", description: "Emit clean JSON to stdout (progress on stderr)" },
1403
+ { long: "--format", value_name: "toon|json|markdown", description: "Output format (default: toon)" },
1404
+ { long: "--output", value_name: "file", description: "Write the rendered output to a file instead of stdout" },
1405
+ ],
1406
+ async run(ctx) {
1407
+ const options = ctx.options;
1408
+ const repos = resolveRepos(options, ctx.args);
1409
+ const format = resolveFormat(options);
1410
+ const outputPath = readString(options, "output");
1411
+ console.error(`pm-ops audit: ${repos.length} repo(s)`);
1412
+ const result = collectAuditAll(repos, (m) => console.error(` ${m}`));
1413
+ console.error(`audit: ${result.summary.clean}/${result.summary.total} clean, ${result.summary.total_critical} critical, ${result.summary.total_high} high`);
1414
+ return emitResult(result, format, outputPath, () => renderAuditMarkdown(result));
1415
+ },
1416
+ });
1005
1417
  },
1006
1418
  });
1007
1419
  //# sourceMappingURL=index.js.map