@sdods/cli 0.7.1 → 0.8.0

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/program.js

@@ -36,6 +36,8 @@ import { register as registerIntegrations } from './commands/integrations.js';
 import { register as registerCompletion } from './commands/completion.js';
 import { register as registerUpgrade } from './commands/upgrade.js';
 import { register as registerFeedback } from './commands/feedback.js';
+import { register as registerLoad } from './commands/load.js';
+import { register as registerMatrix } from './commands/matrix.js';
 /**
  * All commands are registered eagerly (cheap) but each module keeps heavy imports
  * (server, agents, DB, browser runner) inside its action via dynamic import.
@@ -90,6 +92,8 @@ export function buildProgram() {
     registerCompletion(program);
     registerUpgrade(program);
     registerFeedback(program);
+    registerLoad(program);
+    registerMatrix(program);
     return program;
 }
 //# sourceMappingURL=program.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "SDODS command line: run, record, analyze, agents, MCP server, scheduler and the web server.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -24,8 +24,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@sdods/contracts": "0.7.1",
-    "@sdods/core": "0.7.1",
+    "@sdods/contracts": "0.8.0",
+    "@sdods/core": "0.8.0",
     "commander": "^15.0.0",
     "execa": "^10.0.1",
     "picocolors": "^1.1.1",
@@ -34,12 +34,12 @@
     "zod": "^4.5.4",
     "@playwright/test": "^1.63.0",
     "playwright-core": "^1.63.0",
-    "@sdods/integrations": "0.7.1",
-    "@sdods/mcp": "0.7.1",
-    "@sdods/agents": "0.7.1",
-    "@sdods/db": "0.7.1",
+    "@sdods/integrations": "0.8.0",
+    "@sdods/mcp": "0.8.0",
+    "@sdods/agents": "0.8.0",
+    "@sdods/db": "0.8.0",
     "csv-parse": "^7.0.2",
-    "@sdods/server": "0.7.1"
+    "@sdods/server": "0.8.0"
   },
   "homepage": "https://sdods.com",
   "bugs": {

package/skills/sdods/SKILL.md

@@ -18,7 +18,7 @@ over shelling out.
 
 - Every scenario carries exactly one layer tag (`@ui`, `@api`, `@hybrid`) and exactly one suite tag
   (`@smoke`, `@regression`, `@sanity`). Optional: `@visual @a11y @perf @mock @data-driven @pool`,
-  and value tags `@user:<role> @data:<dataset> @har:<name> @jira:KEY @skip:<browser>`.
+  and value tags `@user:<role> @data:<dataset> @har:<name> @jira:KEY @skip:<browser> @matrix:<name> @req:<id>`, and per-scenario emulation `@locale:<bcp47> @theme:<light|dark|no-preference> @timezone:<IANA> @viewport:<W>x<H> @device:<name>`.
 - Reuse existing steps first (`sdods steps list -p <slug>`, or `step_find`). Add a step only when no
   phrasing fits, and name it in the same style.
 - Locator priority: role + name > label > test id > placeholder > text > CSS. Never XPath.
@@ -37,6 +37,7 @@ over shelling out.
 | Projects and hierarchy | `sdods project list`, `sdods workspace tree` |
 | Resolved config, with where each value came from | `sdods config show -p <slug> -e <env> --explain` |
 | Validate features | `sdods lint -p <slug>` |
+| Role × surface matrix (`roles.matrix.yaml`) | `sdods matrix expand -p <slug>` · `--check` in CI |
 | Run a slice | `sdods run -p <slug> -e <env> -l api` · `-l ui -b chromium -t @smoke` · `--process pr-check` |
 | Results | `sdods report --last`, `sdods heal report --last`, `sdods trace --last` |
 | Available steps | `sdods steps list -p <slug>` |

package/templates/projects/demo-shop/load/posts.yaml

@@ -0,0 +1,17 @@
+# Read-only load profile for `sdods load`. The staging environment points at a public sandbox
+# (JSONPlaceholder) and deliberately does NOT opt in to load, so only `--dry-run` works against it.
+description: Read posts and one post's comments
+thinkTimeSeconds: 1
+vus: 2
+duration: 20s
+thresholds:
+  http_req_duration: ['p(95)<1500']
+  http_req_failed: ['rate<0.01']
+  checks: ['rate>0.99']
+requests:
+  - name: list posts
+    path: /posts
+    expect: { status: 200, bodyContains: userId }
+  - name: post comments
+    path: /posts/1/comments
+    expect: { status: 200 }