@sdods/cli 0.2.0

package/dist/commands/integrations.js

@@ -0,0 +1,306 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import pc from 'picocolors';
+import { SdodsError, DEFAULT_ARTIFACTS_DIR, Logger } from '@sdods/core';
+import { createContext } from '../context.js';
+import { json, ok, out, table, warn } from '../ui.js';
+const LINKS_FILE = ['.sdods', 'issue-links.json'];
+/** `sdods integrations test|notify|sync|links` — GitHub and Jira without the server or a database. */
+export function register(program) {
+    const cmd = program
+        .command('integrations')
+        .description('GitHub and Jira: test connectivity, notify runs, sync issue links');
+    cmd
+        .command('test')
+        .description('Check credentials and reachability for each enabled provider')
+        .requiredOption('-p, --project <slug>', 'project slug')
+        .option('--provider <name>', 'only this provider (github|jira)')
+        .action(async (opts, c) => {
+        const ctx = createContext(c);
+        const entry = ctx.registry.entry(opts.project);
+        const { getProviders } = await import('@sdods/integrations');
+        const providers = await getProviders(entry.config, {
+            only: opts.provider ? [opts.provider] : undefined,
+            projectRoot: entry.root,
+        });
+        const rows = [];
+        for (const p of providers) {
+            if (!p.enabled) {
+                rows.push({
+                    provider: p.name,
+                    enabled: false,
+                    ok: '-',
+                    detail: 'disabled in sdods.project.yaml',
+                    secrets: fmtSecrets(p.secrets),
+                });
+                continue;
+            }
+            if (p.initError) {
+                rows.push({
+                    provider: p.name,
+                    enabled: true,
+                    ok: false,
+                    detail: p.initError,
+                    secrets: fmtSecrets(p.secrets),
+                });
+                continue;
+            }
+            const res = await p.provider.test();
+            rows.push({
+                provider: p.name,
+                enabled: true,
+                ok: res.ok,
+                detail: res.detail,
+                secrets: fmtSecrets(p.secrets),
+            });
+        }
+        if (ctx.opts.json)
+            return json(rows);
+        if (!rows.length)
+            return warn('No integrations configured for this project.');
+        table(rows.map((r) => ({
+            ...r,
+            ok: r.ok === true ? pc.green('ok') : r.ok === false ? pc.red('FAIL') : pc.dim('-'),
+        })));
+        if (rows.some((r) => r.ok === false))
+            process.exitCode = 1;
+    });
+    cmd
+        .command('notify')
+        .description('Publish a run to enabled providers: check runs, PR comment, issues (deduplicated)')
+        .requiredOption('--run-id <id>', 'run id (directory under the artifacts dir)')
+        .option('-p, --project <slug>', 'project slug (default: from run.json)')
+        .option('--from-files', 'build the summary from the run directory (default until DB ingest lands)')
+        .option('--provider <name>', 'only this provider')
+        .option('--dry-run', 'print what would be created without calling any API')
+        .option('--report-url <url>', 'public report URL to include in comments and issues')
+        .option('--artifacts-dir <dir>', 'artifacts root', DEFAULT_ARTIFACTS_DIR)
+        .action(async (opts, c) => {
+        const ctx = createContext(c);
+        const { buildRunSummaryFromFiles, getProviders, createIntegrationContext, FileIssueLinkStore, } = await import('@sdods/integrations');
+        const artifactsRoot = join(ctx.rootDir, opts.artifactsDir);
+        const runDir = join(artifactsRoot, opts.runId);
+        if (!existsSync(runDir)) {
+            throw new SdodsError('RUN_FAILED', `Run directory not found: ${runDir}`, {
+                hint: 'Pass --artifacts-dir or check the run id (sdods report --last).',
+                exitCode: 2,
+            });
+        }
+        const summary = buildRunSummaryFromFiles(runDir, {
+            projectSlug: opts.project,
+            reportUrl: opts.reportUrl,
+        });
+        const slug = summary.run.projectSlug;
+        const entry = ctx.registry.entry(slug);
+        const providers = await getProviders(entry.config, {
+            only: opts.provider ? [opts.provider] : undefined,
+            projectRoot: entry.root,
+        });
+        const ictx = createIntegrationContext({
+            store: new FileIssueLinkStore(join(ctx.rootDir, ...LINKS_FILE)),
+            logger: new Logger('integrations'),
+            dryRun: Boolean(opts.dryRun),
+            artifactsRoot,
+        });
+        const results = [];
+        for (const p of providers) {
+            if (!p.enabled)
+                continue;
+            if (p.initError) {
+                results.push({ provider: p.name, kind: 'skipped', detail: p.initError });
+                continue;
+            }
+            try {
+                const res = await p.provider.onRunFinished(summary, ictx);
+                results.push(...res.actions);
+            }
+            catch (e) {
+                results.push({ provider: p.name, kind: 'error', detail: e.message });
+            }
+        }
+        if (ctx.opts.json)
+            return json({ run: summary.run, totals: summary.totals, actions: results });
+        const t = summary.totals;
+        out(pc.bold(`Run ${summary.run.id} · ${slug} · ${summary.run.env} · ${t.passed}/${t.total} passed, ${t.failed} failed, ${t.flaky} flaky`) + (opts.dryRun ? pc.yellow('  [dry-run]') : ''));
+        if (!results.length)
+            return warn('No enabled providers produced actions.');
+        table(results.map((r) => ({
+            provider: r.provider,
+            action: r.kind,
+            target: r.target ?? '',
+            url: r.url ?? '',
+            detail: r.detail ?? '',
+        })));
+        if (results.some((r) => r.kind === 'error'))
+            process.exitCode = 1;
+    });
+    cmd
+        .command('sync')
+        .description('Scan features for @jira:KEY / @github:N tags, create links, and refresh statuses')
+        .requiredOption('-p, --project <slug>', 'project slug')
+        .option('--provider <name>', 'only this provider')
+        .action(async (opts, c) => {
+        const ctx = createContext(c);
+        const entry = ctx.registry.entry(opts.project);
+        const { getProviders, FileIssueLinkStore } = await import('@sdods/integrations');
+        const { fingerprint } = await import('@sdods/contracts');
+        const store = new FileIssueLinkStore(join(ctx.rootDir, ...LINKS_FILE));
+        const providers = await getProviders(entry.config, {
+            only: opts.provider ? [opts.provider] : undefined,
+            projectRoot: entry.root,
+        });
+        const tagged = scanFeatureTags(join(entry.root, 'features'), entry.root);
+        const rows = [];
+        for (const p of providers) {
+            if (!p.enabled)
+                continue;
+            if (p.initError) {
+                warn(`${p.name}: ${p.initError}`);
+                continue;
+            }
+            const tagName = p.name === 'jira' || p.name === 'github' ? p.name : null;
+            if (tagName) {
+                for (const t of tagged.filter((x) => x.tag === tagName)) {
+                    const fp = fingerprint({
+                        project: entry.slug,
+                        featureUri: t.featureUri,
+                        scenarioName: t.scenarioName,
+                        exampleIndex: null,
+                        layer: t.layer,
+                    });
+                    if (await store.findByKey(entry.slug, p.name, t.key))
+                        continue;
+                    try {
+                        const ref = await p.provider.linkIssue(fp, t.key);
+                        await store.save({
+                            projectSlug: entry.slug,
+                            provider: p.name,
+                            fingerprint: fp,
+                            scenarioName: t.scenarioName,
+                            externalKey: ref.key,
+                            externalUrl: ref.url,
+                            status: ref.status,
+                            source: 'tag',
+                            lastSyncedAt: new Date().toISOString(),
+                        });
+                    }
+                    catch (e) {
+                        warn(`${p.name}: cannot link ${t.key}: ${e.message}`);
+                    }
+                }
+            }
+            const links = await store.list(entry.slug, p.name);
+            const refs = await p.provider.syncStatuses(links);
+            for (const ref of refs) {
+                const link = links.find((l) => l.externalKey === ref.key);
+                if (!link)
+                    continue;
+                await store.save({
+                    ...link,
+                    status: ref.status,
+                    closedAt: ref.status === 'closed' && link.status !== 'closed'
+                        ? new Date().toISOString()
+                        : link.closedAt,
+                    lastSyncedAt: new Date().toISOString(),
+                });
+                rows.push({
+                    provider: p.name,
+                    key: ref.key,
+                    status: ref.status,
+                    scenario: link.scenarioName,
+                    source: link.source,
+                    url: ref.url,
+                });
+            }
+        }
+        if (ctx.opts.json)
+            return json(rows);
+        if (!rows.length)
+            return ok('Nothing to sync (no enabled providers or no links).');
+        table(rows);
+    });
+    cmd
+        .command('links')
+        .description('List known issue links for a project')
+        .requiredOption('-p, --project <slug>', 'project slug')
+        .option('--provider <name>', 'only this provider')
+        .action(async (opts, c) => {
+        const ctx = createContext(c);
+        ctx.registry.entry(opts.project);
+        const { FileIssueLinkStore } = await import('@sdods/integrations');
+        const store = new FileIssueLinkStore(join(ctx.rootDir, ...LINKS_FILE));
+        const links = await store.list(opts.project, opts.provider);
+        if (ctx.opts.json)
+            return json(links);
+        table(links.map((l) => ({
+            provider: l.provider,
+            key: l.externalKey,
+            status: l.status,
+            source: l.source,
+            scenario: l.scenarioName,
+            lastRun: l.lastRunId ?? '',
+            synced: l.lastSyncedAt ?? '',
+        })));
+    });
+}
+function fmtSecrets(s) {
+    return Object.entries(s)
+        .map(([k, v]) => `${k}=${v ? pc.green('set') : pc.red('missing')}`)
+        .join(' ');
+}
+/** Lightweight feature scan for issue tags (feature-level tags inherit to scenarios). */
+export function scanFeatureTags(featuresDir, projectRoot) {
+    const out = [];
+    if (!existsSync(featuresDir))
+        return out;
+    const files = [];
+    const walk = (dir) => {
+        for (const name of readdirSync(dir).sort()) {
+            const p = join(dir, name);
+            if (statSync(p).isDirectory())
+                walk(p);
+            else if (name.endsWith('.feature'))
+                files.push(p);
+        }
+    };
+    walk(featuresDir);
+    for (const file of files) {
+        const featureUri = file.slice(projectRoot.length + 1).replace(/\\/g, '/');
+        let featureTags = [];
+        let pending = [];
+        for (const raw of readFileSync(file, 'utf8').split('\n')) {
+            const line = raw.trim();
+            if (line.startsWith('@')) {
+                pending.push(...line.split(/\s+/).filter((t) => t.startsWith('@')));
+                continue;
+            }
+            if (/^Feature:/.test(line)) {
+                featureTags = pending;
+                pending = [];
+                continue;
+            }
+            const m = /^(?:Scenario(?: Outline| Template)?|Example):\s*(.+)$/.exec(line);
+            if (!m)
+                continue;
+            const tags = [...featureTags, ...pending];
+            pending = [];
+            const layer = tags.includes('@api') ? 'api' : tags.includes('@hybrid') ? 'hybrid' : 'ui';
+            for (const t of tags) {
+                const jira = /^@jira:([A-Z][A-Z0-9]+-\d+)$/i.exec(t);
+                const gh = /^@github:(\d+)$/.exec(t);
+                if (jira)
+                    out.push({
+                        tag: 'jira',
+                        key: jira[1].toUpperCase(),
+                        featureUri,
+                        scenarioName: m[1].trim(),
+                        layer,
+                    });
+                if (gh)
+                    out.push({ tag: 'github', key: gh[1], featureUri, scenarioName: m[1].trim(), layer });
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=integrations.js.map

package/dist/commands/lint.d.ts

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

package/dist/commands/lint.js

@@ -0,0 +1,74 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+import { formatFindings, lintProject } from '@sdods/core';
+import { createContext } from '../context.js';
+import { collect, json, ok, out } from '../ui.js';
+export function register(program) {
+    program
+        .command('lint [paths...]')
+        .description('Validate feature files: Gherkin syntax, tag taxonomy, modules, undefined steps')
+        .option('-p, --project <slug>', 'project slug (default: all projects)')
+        .option('--undefined-steps', 'also detect undefined steps via bddgen (slower)')
+        .option('--fix-tags', 'insert the layer/module tag suggested by a finding')
+        .option('--strict', 'treat warnings as errors')
+        .option('--file <path>', 'lint only this feature file (repeatable)', collect, [])
+        .action(async (paths, opts, cmd) => {
+        const ctx = createContext(cmd);
+        const entries = opts.project
+            ? [ctx.registry.entry(opts.project)]
+            : ctx.registry.entriesList();
+        const all = { errors: [], warnings: [], filesChecked: 0 };
+        for (const e of entries) {
+            const cfg = ctx.registry.resolve(e.slug);
+            const files = [...paths, ...opts.file].map((f) => resolvePath(f));
+            const result = await lintProject({
+                project: cfg.project,
+                files: files.length ? files : undefined,
+                undefinedSteps: opts.undefinedSteps,
+                repoRoot: ctx.rootDir,
+            });
+            if (opts.fixTags)
+                applyTagFixes(cfg.project.root, result);
+            all.errors.push(...result.errors.map((x) => ({ ...x, project: e.slug })));
+            all.warnings.push(...result.warnings.map((x) => ({ ...x, project: e.slug })));
+            all.filesChecked += result.filesChecked;
+        }
+        const failed = all.errors.length > 0 || (opts.strict && all.warnings.length > 0);
+        if (ctx.opts.json)
+            json({ ok: !failed, ...all });
+        else if (all.errors.length || all.warnings.length)
+            out(formatFindings(all));
+        else
+            ok(`${all.filesChecked} feature file(s) linted, no findings`);
+        if (failed)
+            process.exitCode = 3;
+    });
+}
+function applyTagFixes(projectRoot, result) {
+    const byFile = new Map();
+    for (const f of [...result.errors, ...result.warnings]) {
+        if (!f.fix?.insertTag || !f.line)
+            continue;
+        const list = byFile.get(f.file) ?? [];
+        list.push({ line: f.line, tag: f.fix.insertTag });
+        byFile.set(f.file, list);
+    }
+    for (const [rel, fixes] of byFile) {
+        const file = join(projectRoot, rel);
+        const lines = readFileSync(file, 'utf8').split('\n');
+        for (const { line, tag } of fixes.sort((a, b) => b.line - a.line)) {
+            // tags live on the line above the Scenario keyword
+            const idx = line - 2;
+            if (idx >= 0 && lines[idx].trim().startsWith('@')) {
+                if (!lines[idx].includes(tag))
+                    lines[idx] = `${lines[idx]} ${tag}`;
+            }
+            else {
+                const indent = /^\s*/.exec(lines[line - 1] ?? '')?.[0] ?? '';
+                lines.splice(line - 1, 0, `${indent}${tag}`);
+            }
+        }
+        writeFileSync(file, lines.join('\n'));
+    }
+}
+//# sourceMappingURL=lint.js.map

package/dist/commands/mcp.d.ts

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

package/dist/commands/mcp.js

@@ -0,0 +1,190 @@
+import pc from 'picocolors';
+import { SdodsError } from '@sdods/core';
+import { createContext } from '../context.js';
+import { json, ok, out } from '../ui.js';
+const CLIENTS = ['claude', 'codex', 'cursor', 'vscode', 'windsurf'];
+function capsOf(raw) {
+    if (!raw || raw === 'all')
+        return raw === 'all' ? 'all' : ['core', 'analyze', 'run', 'data', 'schedules'];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function register(program) {
+    const mcp = program
+        .command('mcp')
+        .description('Start the SDODS MCP server (stdio by default) or install client configuration')
+        .option('-p, --project <slug>', 'default project for tools and prompts')
+        .option('-e, --env <name>', 'default environment')
+        .option('--caps <list>', 'capabilities: core,analyze,run,data,agents,issues,schedules or "all"', 'core,analyze,run,data,schedules')
+        .option('--http', 'serve streamable HTTP instead of stdio')
+        .option('--port <n>', 'HTTP port', '4001')
+        .option('--host <host>', 'HTTP host', '127.0.0.1')
+        .option('--token <token>', 'HTTP: accept this single bearer token (dev only; production uses `sdods tokens`)')
+        .option('--list-tools', 'print the tool catalogue and exit')
+        .action(async (opts, cmd) => {
+        const ctx = createContext(cmd);
+        const { serveSdodsStdio, serveSdodsHttp, createRegistry, buildToolContext, ALL_CAPABILITIES, } = await import('@sdods/mcp');
+        const caps = capsOf(opts.caps);
+        if (opts.listTools) {
+            const registry = createRegistry();
+            const tctx = buildToolContext({ rootDir: ctx.rootDir, caps });
+            const rows = registry.list(tctx).map((t) => ({
+                name: t.name,
+                access: t.access,
+                capability: t.capability,
+                description: t.description,
+            }));
+            if (ctx.opts.json)
+                return json(rows);
+            for (const r of rows)
+                out(`${pc.bold(r.name.padEnd(28))} ${pc.dim(r.capability.padEnd(9))} ${pc.dim(r.access.padEnd(5))} ${r.description}`);
+            out(pc.dim(`\n${rows.length} tools · capabilities: ${ALL_CAPABILITIES.join(', ')}`));
+            return;
+        }
+        if (opts.http) {
+            const token = opts.token ?? process.env.SDODS_MCP_TOKEN;
+            if (!token) {
+                throw new SdodsError('AUTH_FAILED', 'HTTP mode needs a bearer token.', {
+                    hint: 'Pass --token <secret> (dev) or set SDODS_MCP_TOKEN. Production deployments use scoped tokens from `sdods tokens create` via the web server.',
+                    exitCode: 2,
+                });
+            }
+            const srv = await serveSdodsHttp({
+                rootDir: ctx.rootDir,
+                project: opts.project,
+                env: opts.env,
+                caps,
+                port: Number(opts.port),
+                host: opts.host,
+                authenticate: (t) => (t === token ? { name: 'token', scopes: ['*'], via: 'http' } : null),
+            });
+            ok(`SDODS MCP over HTTP at http://${opts.host}:${srv.port}/mcp (Ctrl+C to stop)`);
+            await new Promise((resolve) => {
+                process.once('SIGINT', () => srv.close().then(resolve));
+                process.once('SIGTERM', () => srv.close().then(resolve));
+            });
+            return;
+        }
+        // stdio: stdout carries protocol messages only; logs go to stderr
+        serveSdodsStdio({ rootDir: ctx.rootDir, project: opts.project, env: opts.env, caps });
+        await new Promise(() => undefined);
+    });
+    mcp
+        .command('install <client>')
+        .description('Register the SDODS MCP server with a client: claude | codex | cursor | vscode | windsurf (merges, never clobbers)')
+        .option('-p, --project <slug>')
+        .option('-e, --env <name>')
+        .option('--caps <list>')
+        .option('--http-url <url>', 'configure the HTTP transport instead of stdio')
+        .option('--token-placeholder <text>', 'placeholder written for the bearer token')
+        .option('--no-playwright', 'do not add the bundled Playwright MCP server')
+        .option('--file', 'always write the config file instead of calling `claude mcp add` / `codex mcp add`')
+        .option('--print', 'print the snippet instead of writing files')
+        .action(async (client, opts, cmd) => {
+        const ctx = createContext(cmd);
+        const { installClientConfig, snippets, cliCommands } = await import('@sdods/mcp');
+        if (!CLIENTS.includes(client)) {
+            throw new SdodsError('NOT_SUPPORTED', `Unknown client "${client}".`, {
+                hint: `Use one of ${CLIENTS.join(', ')}.`,
+                exitCode: 2,
+            });
+        }
+        // commander also accepts `-p/-e/--caps` on the parent `mcp` command; honour both
+        const parent = mcp.opts();
+        const o = {
+            project: opts.project ?? parent.project,
+            env: opts.env ?? parent.env,
+            caps: opts.caps ??
+                (parent.caps !== 'core,analyze,run,data,schedules' ? parent.caps : undefined),
+            httpUrl: opts.httpUrl,
+            tokenPlaceholder: opts.tokenPlaceholder,
+            withPlaywright: opts.playwright !== false,
+        };
+        const s = snippets(o)[client];
+        if (opts.print || ctx.opts.json) {
+            if (ctx.opts.json)
+                return json({ file: s.file, config: s.json ?? s.toml, cli: s.cli });
+            out(pc.bold(s.file));
+            out(s.json ? JSON.stringify(s.json, null, 2) : (s.toml ?? ''));
+            if (s.cli)
+                out(`\n${pc.dim('or:')} ${s.cli}`);
+            return;
+        }
+        // Prefer the client's own CLI so its config format stays authoritative.
+        if (!opts.file && (client === 'claude' || client === 'codex')) {
+            const done = await registerViaClientCli(client, o, ctx.rootDir);
+            if (done) {
+                ok(`Registered the sdods MCP server with ${client} (${cliCommands(o)[client]})`);
+                if (o.withPlaywright && client === 'codex')
+                    out(pc.dim('Also registered the bundled Playwright MCP server as "playwright".'));
+                return;
+            }
+        }
+        const r = installClientConfig(ctx.rootDir, client, o);
+        ok(`${r.created ? 'Created' : 'Updated'} ${r.file}`);
+        if (s.cli)
+            out(pc.dim(`Alternative: ${s.cli}`));
+    });
+}
+/** `claude mcp add` (project scope) or `codex mcp add`; false when the CLI is unavailable. */
+async function registerViaClientCli(client, o, cwd) {
+    const { execa } = await import('execa');
+    const stdio = ['npx', 'sdods', 'mcp'];
+    if (o.project)
+        stdio.push('--project', o.project);
+    if (o.env)
+        stdio.push('--env', o.env);
+    if (o.caps)
+        stdio.push('--caps', o.caps);
+    const run = async (args) => {
+        try {
+            await execa(client, args, { cwd, timeout: 30_000 });
+            return true;
+        }
+        catch (e) {
+            const msg = String(e.stderr ?? e.message);
+            if (/ENOENT|not found/i.test(msg))
+                return false;
+            // already registered → remove and re-add so the args are current
+            if (/already exists/i.test(msg)) {
+                await execa(client, ['mcp', 'remove', args[2] ?? 'sdods'], { cwd, reject: false });
+                await execa(client, args, { cwd, timeout: 30_000 });
+                return true;
+            }
+            throw new SdodsError('NOT_SUPPORTED', `${client} mcp add failed: ${msg.trim()}`, {
+                hint: 'Re-run with --file to write the config file directly.',
+            });
+        }
+    };
+    const addArgs = client === 'claude'
+        ? o.httpUrl
+            ? ['mcp', 'add', '-s', 'project', '--transport', 'http', 'sdods', o.httpUrl]
+            : ['mcp', 'add', '-s', 'project', 'sdods', '--', ...stdio]
+        : o.httpUrl
+            ? ['mcp', 'add', 'sdods', '--url', o.httpUrl]
+            : ['mcp', 'add', 'sdods', '--', ...stdio];
+    const ok1 = await run(addArgs);
+    if (!ok1)
+        return false;
+    if (o.withPlaywright !== false) {
+        const pw = client === 'claude'
+            ? [
+                'mcp',
+                'add',
+                '-s',
+                'project',
+                'playwright',
+                '--',
+                'npx',
+                'playwright',
+                'mcp',
+                '--headless',
+            ]
+            : ['mcp', 'add', 'playwright', '--', 'npx', 'playwright', 'mcp', '--headless'];
+        await run(pw).catch(() => false);
+    }
+    return true;
+}
+//# sourceMappingURL=mcp.js.map

package/dist/commands/project.d.ts

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