@sdods/cli 0.7.2 → 0.9.0

package/dist/commands/baselines.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function register(program: Command): void;
+//# sourceMappingURL=baselines.d.ts.map

package/dist/commands/baselines.js

@@ -0,0 +1,111 @@
+import { relative, resolve as resolvePath } from 'node:path';
+import pc from 'picocolors';
+import { DEFAULT_ARTIFACTS_DIR, SdodsError, acceptVisualFailures, listVisualFailures, selectVisualFailures, } from '@sdods/core';
+import { createContext } from '../context.js';
+import { heading, json, ok, out, table } from '../ui.js';
+import { listRuns } from './trace.js';
+function artifactsDirOf(ctx, flag) {
+    return resolvePath(ctx.rootDir, flag ?? process.env.SDODS_ARTIFACTS_DIR ?? DEFAULT_ARTIFACTS_DIR);
+}
+function findRun(ctx, opts) {
+    const artifactsDir = artifactsDirOf(ctx, opts.artifactsDir);
+    const runs = listRuns(artifactsDir);
+    const run = opts.run ? runs.find((r) => r.runId === opts.run) : runs[0];
+    if (!run)
+        throw new SdodsError('CONFIG_NOT_FOUND', opts.run
+            ? `Run ${opts.run} not found under ${artifactsDir}.`
+            : `No runs under ${artifactsDir}.`, {
+            hint: 'Run `sdods run -t @visual …` first, or download the CI run into .sdods/runs/<id>.',
+            exitCode: 2,
+        });
+    return run;
+}
+const pct = (r) => (r === undefined ? '' : `${(r * 100).toFixed(2)}%`);
+export function register(program) {
+    const baselines = program
+        .command('baselines')
+        .description('Review failed visual baseline checks of a run and accept the new screenshots');
+    baselines
+        .command('diff')
+        .description('List the visual checks that failed in a run: expected, actual and diff images')
+        .option('--run <id>', 'run id (default: the most recent run)')
+        .option('--artifacts-dir <dir>', `artifacts directory (default: ${DEFAULT_ARTIFACTS_DIR})`)
+        .action(async (opts, cmd) => {
+        const ctx = createContext(cmd);
+        const run = findRun(ctx, opts);
+        const failures = listVisualFailures(run.dir);
+        const abs = (p) => (p ? resolvePath(run.dir, p) : undefined);
+        if (ctx.opts.json)
+            return json({
+                runId: run.runId,
+                failures: failures.map((f) => ({
+                    ...f,
+                    actual: abs(f.actual),
+                    expected: abs(f.expected),
+                    diff: abs(f.diff),
+                })),
+            });
+        if (!failures.length) {
+            ok(`No failed visual checks in run ${run.runId}.`);
+            return;
+        }
+        heading(`${failures.length} failed visual check(s) in run ${run.runId}`);
+        const rel = (p) => (p ? relative(ctx.rootDir, p) : '—');
+        for (const f of failures) {
+            out('');
+            out(`${pc.bold(`${f.runnerProject}/${f.name}`)}  ${pc.dim(f.platform)}  ${reasonLabel(f)}`);
+            out(`  scenario  ${f.scenarioName} ${pc.dim(`(${f.featureUri})`)}`);
+            out(`  baseline  ${f.baseline}`);
+            table([
+                { image: 'expected', path: rel(abs(f.expected)) },
+                { image: 'actual', path: rel(abs(f.actual)) },
+                { image: 'diff', path: rel(abs(f.diff)) },
+            ]);
+        }
+        out('');
+        out(pc.dim(`Accept after reviewing the diff: sdods baselines accept <name…> --run ${run.runId}  (or --all)`));
+    });
+    baselines
+        .command('accept [names...]')
+        .description('Copy the actual screenshot of failed visual checks over their baselines (writes to the project tree)')
+        .requiredOption('--run <id>', 'run id the screenshots come from (required)')
+        .option('--all', 'accept every failed visual check of the run')
+        .option('--artifacts-dir <dir>', `artifacts directory (default: ${DEFAULT_ARTIFACTS_DIR})`)
+        .action(async (names, opts, cmd) => {
+        const ctx = createContext(cmd);
+        if (opts.all && names.length)
+            throw new SdodsError('CONFIG_INVALID', 'Pass baseline names or --all, not both.', {
+                exitCode: 2,
+            });
+        const run = findRun(ctx, opts);
+        const failures = listVisualFailures(run.dir);
+        if (!failures.length)
+            throw new SdodsError('CONFIG_NOT_FOUND', `No failed visual checks in run ${run.runId}.`, {
+                hint: 'Nothing to accept. `sdods baselines diff --run <id>` lists what failed.',
+                exitCode: 2,
+            });
+        const picked = selectVisualFailures(failures, { names, all: opts.all });
+        const accepted = acceptVisualFailures({
+            runDir: run.dir,
+            failures: picked,
+            projectRoot: (slug) => ctx.registry.rootOf(slug),
+        });
+        if (ctx.opts.json)
+            return json({ runId: run.runId, accepted });
+        for (const a of accepted) {
+            ok(`${a.created ? 'created' : 'updated'} ${relative(ctx.rootDir, a.to)}  ${pc.dim(`${a.runnerProject}/${a.name} · ${a.platform} · ${reasonLabel(a)}`)}`);
+            out(pc.dim(`  from ${relative(ctx.rootDir, a.from)}`));
+            if (a.diff)
+                out(pc.dim(`  diff ${relative(ctx.rootDir, a.diff)}`));
+        }
+        out(pc.dim('Review the PNGs with `git diff --stat` and commit them with the change that moved the pixels.'));
+    });
+}
+function reasonLabel(f) {
+    if (f.reason === 'missing')
+        return pc.cyan('new baseline');
+    if (f.reason === 'size')
+        return pc.yellow('size changed');
+    return pc.yellow(`changed ${pct(f.diffRatio)}`.trim());
+}
+//# sourceMappingURL=baselines.js.map

package/dist/commands/doctor.js

@@ -2,17 +2,18 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { execa } from 'execa';
 import pc from 'picocolors';
-import { collectVarRefs, loadDotEnvLayer, loadEnvFile } from '@sdods/core';
+import { collectVarRefs, describeWorkers, effectiveWorkers, loadDotEnvLayer, loadEnvFile, poolAccountsByEnv, } from '@sdods/core';
 import { createContext } from '../context.js';
 import { browserStatuses } from './browsers.js';
 import { MIN_PLAYWRIGHT_FOR_STEP_RESULTS, installedPlaywrightVersion, stepResultsWarning, } from '../runner-compat.js';
-import { json, out } from '../ui.js';
+import { json, out, parseIntFlag } from '../ui.js';
 export function registerDoctorCommand(program) {
     program
         .command('doctor')
         .description('Check Node, Bun, browsers, projects, env vars and database reachability')
         .option('-p, --project <slug>', 'limit env-var checks to one project')
         .option('--fix', 'install missing browsers')
+        .option('-w, --workers <n>', 'worker count to check user pools against (default: SDODS_WORKERS, else Playwright default)', parseIntFlag('workers'))
         .action(async (opts, cmd) => {
         const ctx = createContext(cmd);
         const checks = [];
@@ -45,6 +46,8 @@ export function registerDoctorCommand(program) {
                 cwd: ctx.rootDir,
             }).catch(() => undefined);
         }
+        const envWorkers = Number(process.env.SDODS_WORKERS);
+        const workers = opts.workers ?? (Number.isInteger(envWorkers) && envWorkers > 0 ? envWorkers : undefined);
         const entries = opts.project
             ? [ctx.registry.entry(opts.project)]
             : ctx.registry.entriesList();
@@ -80,6 +83,9 @@ export function registerDoctorCommand(program) {
                         ? `Add ${missing.join(', ')} to ${join(e.root, `.env.${envName}`)}`
                         : undefined,
                 });
+                const pool = poolCheck(e.slug, envName, { ...e.config, root: e.root }, envCfg.users.poolSize, workers);
+                if (pool)
+                    checks.push(pool);
             }
         }
         const driver = process.env.DB_DRIVER ?? 'sqlite';
@@ -121,6 +127,42 @@ export function registerDoctorCommand(program) {
             process.exitCode = 1;
     });
 }
+/**
+ * #153: accounts per role in an exclusive, worker-held pool against the worker count. Advisory —
+ * doctor does not know which roles a run will select; `sdods run` makes the real decision and
+ * fails with USER_POOL_TOO_SMALL. Undefined when there is nothing to compare.
+ */
+function poolCheck(slug, envName, project, poolSize, workers) {
+    const pool = project.data.userPool;
+    if (!pool)
+        return undefined;
+    const name = `${slug}/${envName} user pool`;
+    if (pool.mode === 'shared' || pool.leaseScope === 'scenario') {
+        return {
+            name,
+            ok: true,
+            detail: pool.mode === 'shared' ? 'mode: shared (no leases)' : 'leaseScope: scenario (queues)',
+        };
+    }
+    const accounts = poolAccountsByEnv(project, {
+        envs: [envName],
+        poolSize: () => poolSize,
+    })?.get(envName);
+    if (!accounts)
+        return undefined; // not file-backed
+    const n = effectiveWorkers(workers);
+    const short = [...accounts].filter(([, count]) => count < n);
+    return {
+        name,
+        ok: short.length === 0,
+        optional: true,
+        detail: `${[...accounts].map(([role, count]) => `${role} ${count}`).join(', ') || 'no accounts'} ` +
+            `vs ${describeWorkers(workers)}`,
+        fix: short.length
+            ? `fewer accounts than workers for ${short.map(([r]) => r).join(', ')}: sdods run stops with USER_POOL_TOO_SMALL when more of their @user: scenarios could run at once than there are accounts. Set data.userPool.leaseScope: scenario, add accounts, or lower --workers.`
+            : undefined,
+    };
+}
 /**
  * The token matrix. "one-of" rows form a group: agents need ANY one of them.
  * Platform features never need an external token.

package/dist/commands/integrations.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import pc from 'picocolors';
-import { DEFAULT_ARTIFACTS_DIR } from '@sdods/core';
+import { DEFAULT_ARTIFACTS_DIR, SdodsError } from '@sdods/core';
 import { createContext } from '../context.js';
 import { LINKS_FILE, notifyRun } from '../notify.js';
 import { json, ok, out, table, warn } from '../ui.js';
@@ -54,6 +54,7 @@ export function register(program) {
                 detail: res.detail,
                 secrets: fmtSecrets(p.secrets),
                 ...(ctx.opts.json && res.labels ? { labels: res.labels } : {}),
+                ...(ctx.opts.json && res.evidence ? { evidence: res.evidence } : {}),
             });
         }
         if (ctx.opts.json)
@@ -190,6 +191,51 @@ export function register(program) {
             return ok('Nothing to sync (no enabled providers or no links).');
         table(rows);
     });
+    const evidence = cmd
+        .command('evidence')
+        .description('The GitHub evidence branch (integrations.github.evidence.host: branch)');
+    evidence
+        .command('prune')
+        .description('Rewrite the evidence branch without runs uploaded before the cutoff (a new orphan commit, force-pushed)')
+        .requiredOption('-p, --project <slug>', 'project slug')
+        .option('--older-than <age>', '90min, 36h, 14d or 2w; a bare number is days (default: evidence.retainDays)')
+        .option('--dry-run', 'list the runs that would be removed without rewriting the branch')
+        .action(async (opts, c) => {
+        const ctx = createContext(c);
+        const entry = ctx.registry.entry(opts.project);
+        const { getProviders, GitHubProvider, parseAge } = await import('@sdods/integrations');
+        if (opts.olderThan) {
+            try {
+                parseAge(opts.olderThan);
+            }
+            catch (e) {
+                throw new SdodsError('CONFIG_INVALID', e.message);
+            }
+        }
+        const [gh] = await getProviders(entry.config, { only: ['github'], projectRoot: entry.root });
+        const docsPath = '/docs/guides/github-and-jira#evidence-that-renders-in-private-repositories';
+        if (!gh?.enabled || !(gh.provider instanceof GitHubProvider))
+            throw new SdodsError('CONFIG_INVALID', `integrations.github is not enabled for project ${entry.slug}.`, { docsPath });
+        if (gh.initError)
+            throw new SdodsError('CONFIG_INVALID', `github: ${gh.initError}`, { docsPath });
+        if (entry.config.integrations.github?.evidence?.host !== 'branch')
+            throw new SdodsError('CONFIG_INVALID', `integrations.github.evidence.host is not "branch" for project ${entry.slug}.`, { docsPath });
+        const res = await gh.provider.pruneEvidence({
+            olderThan: opts.olderThan,
+            dryRun: Boolean(opts.dryRun),
+        });
+        if (ctx.opts.json)
+            return json(res);
+        const verb = res.dryRun ? 'would remove' : 'removed';
+        if (!res.removed.length)
+            ok(`${res.branch}: nothing to prune (${res.kept.length} run(s) kept)`);
+        else {
+            table(res.removed.map((r) => ({ run: r.runId, uploaded: r.uploadedAt })));
+            ok(`${res.branch}: ${verb} ${res.removed.length} run(s), kept ${res.kept.length}${res.commitSha ? ` (new root ${res.commitSha.slice(0, 10)})` : ''}`);
+        }
+        if (res.unknown.length)
+            warn(`kept ${res.unknown.length} run(s) missing from runs/index.json (age unknown): ${res.unknown.join(', ')}`);
+    });
     cmd
         .command('links')
         .description('List known issue links for a project')

package/dist/commands/load.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function register(program: Command): void;
+//# sourceMappingURL=load.d.ts.map

package/dist/commands/load.js

@@ -0,0 +1,95 @@
+import { relative } from 'node:path';
+import pc from 'picocolors';
+import { SdodsError } from '@sdods/core';
+import { createContext } from '../context.js';
+import { heading, json, ok, out, table, warn } from '../ui.js';
+export function register(program) {
+    program
+        .command('load')
+        .description('Load test an API with k6: generate a script from load/<profile>.yaml and run it (opt-in per environment)')
+        .argument('[profile]', 'profile name: projects/<slug>/load/<profile>.yaml')
+        .option('-p, --project <slug>', 'project slug')
+        .option('-e, --env <name>', 'environment (must set load.allowed: true)')
+        .option('--dry-run', 'write the k6 script and stop; k6 is not needed')
+        .option('--out <dir>', 'output directory (default .sdods/runs/<id>/load/<profile>)')
+        .option('--runner <runner>', 'auto | k6 | docker (auto uses k6 on PATH)', 'auto')
+        .option('--image <image>', 'k6 image for --runner docker', 'grafana/k6:latest')
+        .option('--list', 'list the load profiles of the project')
+        .action(async (profile, opts, cmd) => {
+        const ctx = createContext(cmd);
+        const entry = ctx.registry.pick(opts.project);
+        const load = await import('@sdods/core/load');
+        if (opts.list) {
+            const rows = load.listLoadProfiles(entry.root).map((name) => ({ profile: name }));
+            if (ctx.opts.json)
+                return json(rows);
+            if (!rows.length)
+                return out(pc.dim(`no profiles in ${relative(ctx.rootDir, entry.root)}/load`));
+            return table(rows, ['profile']);
+        }
+        if (!profile) {
+            throw new SdodsError('CONFIG_INVALID', 'Name a load profile, or pass --list.', {
+                hint: `sdods load -p ${entry.slug} -e <env> <profile> --dry-run`,
+                exitCode: 2,
+            });
+        }
+        if (!['auto', 'k6', 'docker'].includes(opts.runner)) {
+            throw new SdodsError('CONFIG_INVALID', `--runner must be auto, k6 or docker.`, {
+                exitCode: 2,
+            });
+        }
+        const quiet = Boolean(ctx.opts.json || ctx.opts.quiet);
+        if (!quiet)
+            heading(`load · ${entry.slug} · ${profile}${opts.dryRun ? ' · dry run' : ''}`);
+        const res = await load.runLoad({
+            rootDir: ctx.rootDir,
+            projectRoot: entry.root,
+            profile,
+            env: opts.env,
+            outDir: opts.out,
+            dryRun: Boolean(opts.dryRun),
+            runner: opts.runner,
+            image: opts.image,
+            // --json keeps stdout for the result; k6's own output goes to stderr.
+            stdio: ctx.opts.json ? 'stderr' : 'inherit',
+            log: (line) => {
+                if (quiet)
+                    return;
+                if (line.startsWith('warning: '))
+                    warn(line.slice('warning: '.length));
+                else
+                    out(line);
+            },
+        });
+        process.exitCode = res.exitCode;
+        if (ctx.opts.json)
+            return json(res);
+        const script = relative(ctx.rootDir, res.scriptFile);
+        if (res.dryRun) {
+            ok(`script written: ${script}`);
+            if (res.requiredEnv.length)
+                out(pc.dim(`reads from the environment: ${res.requiredEnv.join(', ')}`));
+            return;
+        }
+        const s = res.summary;
+        if (s) {
+            table([
+                {
+                    requests: s.requests ?? '',
+                    'p95 ms': s.p95Ms === undefined ? '' : Math.round(s.p95Ms),
+                    failed: s.failedRate === undefined ? '' : `${(s.failedRate * 100).toFixed(2)}%`,
+                    checks: s.checksRate === undefined ? '' : `${(s.checksRate * 100).toFixed(2)}%`,
+                },
+            ], ['requests', 'p95 ms', 'failed', 'checks']);
+        }
+        if (res.summaryFile)
+            out(pc.dim(`summary: ${relative(ctx.rootDir, res.summaryFile)}`));
+        if (res.exitCode === 0)
+            ok('thresholds passed');
+        else if (res.thresholdsFailed)
+            warn('thresholds failed (k6 exit 99)');
+        else
+            warn(`k6 exited with ${res.k6ExitCode}`);
+    });
+}
+//# sourceMappingURL=load.js.map

package/dist/commands/matrix.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+/**
+ * `sdods matrix expand` — write the `Examples:` blocks of every `@matrix:<name>` Scenario Outline
+ * from `roles.matrix.yaml` (#118). `--check` writes nothing and fails when a feature is out of date,
+ * for CI; `--dry-run` writes nothing and, with `--json`, returns the expanded text (the MCP
+ * `matrix_expand` tool turns that into a proposal instead of touching the working tree).
+ */
+export declare function register(program: Command): void;
+//# sourceMappingURL=matrix.d.ts.map

package/dist/commands/matrix.js

@@ -0,0 +1,90 @@
+import { writeFileSync } from 'node:fs';
+import { resolve as resolvePath, sep } from 'node:path';
+import pc from 'picocolors';
+import { ROLES_MATRIX_FILE, listFeatureFiles, planMatrixExpansion } from '@sdods/core';
+import { createContext } from '../context.js';
+import { collect, json, ok, out } from '../ui.js';
+/**
+ * `sdods matrix expand` — write the `Examples:` blocks of every `@matrix:<name>` Scenario Outline
+ * from `roles.matrix.yaml` (#118). `--check` writes nothing and fails when a feature is out of date,
+ * for CI; `--dry-run` writes nothing and, with `--json`, returns the expanded text (the MCP
+ * `matrix_expand` tool turns that into a proposal instead of touching the working tree).
+ */
+export function register(program) {
+    const matrix = program
+        .command('matrix')
+        .description('Role × surface matrices from roles.matrix.yaml');
+    matrix
+        .command('expand')
+        .description('Write the generated Examples of every @matrix:<name> outline')
+        .option('-p, --project <slug>', 'project slug (default: all projects)')
+        .option('--check', 'write nothing; exit 3 if any feature is out of date or invalid')
+        .option('--dry-run', 'write nothing; report what would change (with --json, the new text)')
+        .option('--file <path>', 'only this feature file (repeatable)', collect, [])
+        .action((opts, cmd) => {
+        const ctx = createContext(cmd);
+        const entries = opts.project
+            ? [ctx.registry.entry(opts.project)]
+            : ctx.registry.entriesList();
+        const only = opts.file.map((f) => resolvePath(f));
+        const write = !opts.check && !opts.dryRun;
+        const files = [];
+        const problems = [];
+        let configInvalid = false;
+        for (const e of entries) {
+            // The matrix needs the project file, not an environment: no env is resolved (or required).
+            const project = { ...e.config, root: e.root };
+            const featureFiles = only.length
+                ? only.filter((f) => f.startsWith(resolvePath(project.root) + sep))
+                : listFeatureFiles(project.root);
+            const plan = planMatrixExpansion(project, featureFiles);
+            if (plan.loaded?.problems.length)
+                configInvalid = true;
+            for (const p of [...plan.problems, ...plan.files.flatMap((f) => f.problems)])
+                problems.push({ project: e.slug, ...p });
+            for (const f of plan.files) {
+                // A template with errors is reported, not rewritten: fix the outline, then expand.
+                const blocked = f.problems.some((p) => p.severity === 'error');
+                if (write && f.changed && !blocked)
+                    writeFileSync(f.file, f.after);
+                files.push({
+                    project: e.slug,
+                    path: f.path,
+                    status: !f.changed ? 'unchanged' : write && !blocked ? 'updated' : 'stale',
+                    examples: f.examples,
+                    ...(opts.dryRun && ctx.opts.json ? { content: f.after } : {}),
+                });
+            }
+        }
+        const errors = problems.filter((p) => p.severity === 'error');
+        const stale = files.filter((f) => f.status === 'stale');
+        const failed = opts.check ? stale.length > 0 || errors.length > 0 : errors.length > 0;
+        if (ctx.opts.json)
+            json({ ok: !failed, files, problems });
+        else {
+            for (const p of problems)
+                out(`${p.severity === 'error' ? pc.red('✖') : pc.yellow('⚠')} ${p.project}/${p.file}${p.line ? `:${p.line}` : ''}  ${p.rule}  ${p.message}`);
+            for (const f of files) {
+                const label = f.status === 'updated'
+                    ? pc.green('updated')
+                    : f.status === 'stale'
+                        ? pc.yellow('out of date')
+                        : pc.dim('up to date');
+                out(`${label}  ${f.project}/${f.path}  (${f.examples} generated example(s))`);
+            }
+            if (!files.length)
+                out(pc.dim(`No @matrix:<name> outlines found (${ROLES_MATRIX_FILE}).`));
+            else if (opts.check && !stale.length && !errors.length)
+                ok('matrix features are up to date');
+            if (opts.check && stale.length)
+                out(`Run \`sdods matrix expand${opts.project ? ` -p ${opts.project}` : ''}\` and commit the result.`);
+        }
+        if (opts.dryRun && !opts.check)
+            return;
+        if (configInvalid && !opts.check)
+            process.exitCode = 2;
+        else if (failed)
+            process.exitCode = 3;
+    });
+}
+//# sourceMappingURL=matrix.js.map

package/dist/commands/report.js

@@ -1,11 +1,11 @@
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
 import { execa } from 'execa';
 import pc from 'picocolors';
 import { runFiles } from '@sdods/contracts';
 import { SdodsError } from '@sdods/core';
 import { createContext } from '../context.js';
-import { json, ok, out, table } from '../ui.js';
+import { json, ok, out, table, warn } from '../ui.js';
 function artifactsRoot(rootDir) {
     return resolve(rootDir, process.env.SDODS_ARTIFACTS_DIR ?? '.sdods/runs');
 }
@@ -195,7 +195,9 @@ export function register(program) {
         .action(async (dirs, opts, cmd) => {
         const ctx = createContext(cmd);
         const root = artifactsRoot(ctx.rootDir);
-        const runId = opts.run ?? latestRunId(root);
+        // `report` defines --run too, and Commander hands it to the parent wherever it appears.
+        const parent = (cmd.parent?.opts() ?? {});
+        const runId = opts.run ?? parent.run ?? latestRunId(root);
         if (!runId) {
             throw new SdodsError('CONFIG_NOT_FOUND', 'No run to merge into.', {
                 hint: 'Pass --run <id>, or run a suite first.',
@@ -233,6 +235,79 @@ export function register(program) {
             return json({ runId, merged: dirs.length, htmlReport: join(runDir, runFiles.htmlReport) });
         ok(`Merged ${dirs.length} shard report dir(s) into ${join(runDir, runFiles.htmlReport)}`);
     });
+    report
+        .command('traceability')
+        .description('Export requirement → scenario → result traceability for a run (@req:<id> tags), with an empty sign-off block')
+        .requiredOption('-p, --project <slug>', 'project slug')
+        .option('-e, --env <name>', 'only consider runs against this environment')
+        .option('--run <id>', 'run id (default: the latest run of the project)')
+        .option('--last', 'use the latest run of the project; fail if there is none')
+        .option('--format <fmt>', 'json|csv|md|html (default: from the -o extension, else json with --json, else md)')
+        .option('-o, --output <file>', 'write the export to a file instead of stdout')
+        .action(async (opts, cmd) => {
+        const ctx = createContext(cmd);
+        // `report` defines --run/--last itself, and Commander hands options it knows to the parent
+        // wherever they appear, so read them from both.
+        const parent = (cmd.parent?.opts() ?? {});
+        const runOpt = opts.run ?? parent.run;
+        const last = Boolean(opts.last ?? parent.last);
+        const { TRACEABILITY_FORMATS, buildTraceabilityReport, latestRunFor, readRunManifest, renderTraceability, } = await import('@sdods/core/analyze');
+        const output = opts.output
+            ? resolve(process.cwd(), opts.output)
+            : undefined;
+        const fromExt = output
+            ? {
+                '.json': 'json',
+                '.csv': 'csv',
+                '.md': 'md',
+                '.html': 'html',
+                '.htm': 'html',
+            }[extname(output).toLowerCase()]
+            : undefined;
+        // -o's extension decides the file format; --json then only shapes the confirmation line.
+        const format = (opts.format ?? fromExt ?? (ctx.opts.json ? 'json' : 'md'));
+        if (!TRACEABILITY_FORMATS.includes(format))
+            throw new SdodsError('CONFIG_INVALID', `Unknown format "${format}".`, {
+                hint: `Use one of: ${TRACEABILITY_FORMATS.join(', ')}.`,
+                exitCode: 2,
+            });
+        const slug = opts.project;
+        const project = { ...ctx.registry.get(slug), root: ctx.registry.rootOf(slug) };
+        const root = artifactsRoot(ctx.rootDir);
+        let run;
+        if (runOpt) {
+            const dir = join(root, runOpt);
+            if (!existsSync(dir))
+                throw new SdodsError('RUN_FAILED', `No run "${runOpt}" under ${root}.`, { exitCode: 2 });
+            const m = readRunManifest(dir);
+            if (m && m.projectSlug !== slug)
+                throw new SdodsError('CONFIG_INVALID', `Run ${runOpt} belongs to project "${m.projectSlug}", not "${slug}".`, { exitCode: 2 });
+            if (m && opts.env && m.env !== opts.env)
+                throw new SdodsError('CONFIG_INVALID', `Run ${runOpt} ran against "${m.env}", not "${opts.env}".`, { exitCode: 2 });
+            run = { runId: runOpt, dir };
+        }
+        else {
+            run = latestRunFor(root, slug, opts.env) ?? undefined;
+            if (!run && last)
+                throw new SdodsError('RUN_FAILED', `No runs of ${slug}${opts.env ? ` on ${opts.env}` : ''} under ${root}.`, {
+                    hint: `Run \`sdods run -p ${slug}\` first, or omit --last for a static matrix.`,
+                    exitCode: 2,
+                });
+            if (!run)
+                warn(`No runs of ${slug}${opts.env ? ` on ${opts.env}` : ''} found: every scenario is reported as not run.`);
+        }
+        const traceReport = await buildTraceabilityReport({ project, run });
+        const text = renderTraceability(traceReport, format);
+        if (!output)
+            return out(text);
+        mkdirSync(dirname(output), { recursive: true });
+        writeFileSync(output, text);
+        const s = traceReport.summary;
+        if (ctx.opts.json)
+            return json({ output, format, run: traceReport.run?.id ?? null, summary: s });
+        ok(`Wrote ${format} traceability export to ${output}`);
+        out(`${s.requirements} requirement(s): ${pc.green(`${s.passed} passed`)}  ${pc.red(`${s.failed} failed`)}  ${pc.yellow(`${s.notRun} not run`)}  ${s.notCovered == null ? pc.dim('not covered: unknown') : pc.magenta(`${s.notCovered} not covered`)}`);
+    });
     program
         .command('show-report')
         .description('Open the HTML report of a run')

package/dist/commands/run.d.ts

@@ -40,6 +40,7 @@ export interface RunFlags {
     trigger?: string;
     allowEmpty?: boolean;
     notify?: boolean;
+    allowPoolContention?: boolean;
 }
 export declare function register(program: Command): void;
 export declare function runCommand(flags: RunFlags, cmd: Command): Promise<number>;