@sdods/cli 0.2.0

package/dist/commands/features.js

@@ -0,0 +1,57 @@
+import { relative } from 'node:path';
+import { listFeatureFiles, parseFeatureFile, scenariosOf } from '@sdods/core';
+import { createContext } from '../context.js';
+import { json, table } from '../ui.js';
+export function register(program) {
+    const features = program.command('features').description('Inspect feature files and scenarios');
+    features
+        .command('list')
+        .description('List features with module, layer, suite, scenario count and tags')
+        .requiredOption('-p, --project <slug>', 'project slug')
+        .option('--tags <expr>', 'only scenarios carrying this tag (simple @tag filter)')
+        .option('--scenarios', 'one row per scenario instead of per feature')
+        .action((opts, cmd) => {
+        const ctx = createContext(cmd);
+        const cfg = ctx.registry.resolve(opts.project);
+        const rows = [];
+        for (const file of listFeatureFiles(cfg.project.root)) {
+            const rel = relative(cfg.project.root, file).replace(/\\/g, '/');
+            const parsed = parseFeatureFile(file);
+            const mod = ctx.registry.moduleOfFeature(opts.project, rel)?.name ?? '';
+            const scenarios = scenariosOf(parsed).filter((s) => !opts.tags || s.tags.includes(opts.tags));
+            if (!scenarios.length && opts.tags)
+                continue;
+            if (opts.scenarios) {
+                for (const s of scenarios) {
+                    rows.push({
+                        feature: rel,
+                        module: mod,
+                        line: s.line,
+                        scenario: s.name,
+                        layer: s.tags.find((t) => ['@ui', '@api', '@hybrid'].includes(t)) ?? '',
+                        suite: s.tags.find((t) => cfg.project.tags.suites.map((x) => `@${x}`).includes(t)) ?? '',
+                        tags: s.tags.join(' '),
+                    });
+                }
+            }
+            else {
+                const tags = [...new Set(scenarios.flatMap((s) => s.tags))];
+                rows.push({
+                    feature: rel,
+                    module: mod,
+                    name: parsed.document.feature?.name ?? '',
+                    scenarios: scenarios.length,
+                    layers: [
+                        ...new Set(scenarios.map((s) => s.tags.find((t) => ['@ui', '@api', '@hybrid'].includes(t)) ?? '?')),
+                    ].join(','),
+                    tags: tags.join(' '),
+                    errors: parsed.errors.length,
+                });
+            }
+        }
+        if (ctx.opts.json)
+            return json(rows);
+        table(rows);
+    });
+}
+//# sourceMappingURL=features.js.map

package/dist/commands/feedback.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+/**
+ * `sdods feedback` — open a prefilled GitHub issue (feature request or bug report).
+ * No backend: the URL carries the fields; bug reports embed the doctor summary.
+ */
+export declare function register(program: Command): void;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -0,0 +1,96 @@
+import { execa } from 'execa';
+import pc from 'picocolors';
+import { VERSION } from '@sdods/core';
+import { json, out } from '../ui.js';
+const REPO = 'https://github.com/siri1410/SDODS';
+const DISCUSSIONS = `${REPO}/discussions/categories/ideas`;
+/**
+ * `sdods feedback` — open a prefilled GitHub issue (feature request or bug report).
+ * No backend: the URL carries the fields; bug reports embed the doctor summary.
+ */
+export function register(program) {
+    program
+        .command('feedback')
+        .description('Request a feature or report a bug (prefilled GitHub issue; opens in your browser)')
+        .option('--feature', 'feature request (default)')
+        .option('--bug', 'bug report with environment details from `sdods doctor`')
+        .option('--discuss', 'print the Discussions (ideas) URL instead')
+        .option('-t, --title <text>', 'issue title')
+        .option('-m, --message <text>', 'problem statement or observed behaviour')
+        .option('--open', 'open the URL in the default browser')
+        .action(async (opts, cmd) => {
+        const root = cmd.parent ?? cmd;
+        const asJson = Boolean(root.opts().json);
+        let url;
+        if (opts.discuss) {
+            url = DISCUSSIONS;
+        }
+        else if (opts.bug) {
+            const params = new URLSearchParams({
+                template: 'bug_report.yml',
+                title: opts.title ? `[Bug] ${opts.title}` : '[Bug] ',
+                labels: 'bug,triage',
+                'sdods-version': VERSION,
+                os: osLabel(),
+            });
+            const doctor = await doctorSummary();
+            if (doctor)
+                params.set('doctor', doctor);
+            if (opts.message)
+                params.set('actual', opts.message);
+            url = `${REPO}/issues/new?${params.toString()}`;
+        }
+        else {
+            const params = new URLSearchParams({
+                template: 'feature_request.yml',
+                title: opts.title ? `[Feature] ${opts.title}` : '[Feature] ',
+                labels: 'enhancement,triage',
+                'sdods-version': VERSION,
+            });
+            if (opts.message)
+                params.set('problem', opts.message);
+            url = `${REPO}/issues/new?${params.toString()}`;
+        }
+        if (asJson)
+            return json({ url });
+        out(url);
+        if (opts.open) {
+            const opener = process.platform === 'darwin'
+                ? 'open'
+                : process.platform === 'win32'
+                    ? 'start'
+                    : 'xdg-open';
+            await execa(opener, [url], { shell: process.platform === 'win32' }).catch(() => out(pc.dim('Could not open a browser; copy the URL above.')));
+        }
+        else {
+            out(pc.dim('Add --open to launch it in your browser.'));
+        }
+    });
+}
+function osLabel() {
+    return process.platform === 'darwin'
+        ? 'macOS'
+        : process.platform === 'linux'
+            ? 'Linux'
+            : process.platform === 'win32'
+                ? 'Windows'
+                : 'Other';
+}
+/** Compact doctor output for the bug form; never includes secret values. */
+async function doctorSummary() {
+    try {
+        const { stdout } = await execa(process.execPath, ['--import', 'tsx', new URL('../bin.ts', import.meta.url).pathname, '--json', 'doctor'], {
+            timeout: 60_000,
+            reject: false,
+        });
+        const start = stdout.indexOf('[');
+        if (start < 0)
+            return undefined;
+        const rows = JSON.parse(stdout.slice(start));
+        return JSON.stringify(rows.map((r) => ({ name: r.name, ok: r.ok, detail: r.detail })), null, 0).slice(0, 3000);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=feedback.js.map

package/dist/commands/har.d.ts

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

package/dist/commands/har.js

@@ -0,0 +1,124 @@
+import { relative } from 'node:path';
+import pc from 'picocolors';
+import { SdodsError } from '@sdods/core';
+import { createContext } from '../context.js';
+import { collect, json, ok, out, table } from '../ui.js';
+import { runCommand } from './run.js';
+function baseRunFlags(over) {
+    return { layer: [], browser: [], module: [], reporter: [], lint: true, trigger: 'cli', ...over };
+}
+export function register(program) {
+    const har = program
+        .command('har')
+        .description('Record or replay HAR files so runs work offline (browser and API layers)');
+    har
+        .command('record')
+        .description('Run @har scenarios in update mode (writes har/<env>/<name>.har), or record interactively with codegen')
+        .option('-p, --project <slug>', 'project slug')
+        .option('-e, --env <name>', 'environment')
+        .option('-t, --tags <expr>', 'tag expression, e.g. "@har:products" (default: every @har scenario)')
+        .option('-l, --layer <layer>', 'ui | api | hybrid (repeatable)', collect, [])
+        .option('-b, --browser <name>', 'browser (repeatable; default chromium)', collect, [])
+        .option('--interactive', 'open codegen with --save-har instead of running scenarios')
+        .option('--name <name>', 'HAR name for --interactive')
+        .option('--url <route|path|url>', 'start URL for --interactive', '/')
+        .option('--har-glob <glob>', 'URL glob to capture', '**/*')
+        .action(async (opts, cmd) => {
+        const ctx = createContext(cmd);
+        if (opts.interactive) {
+            if (!opts.name)
+                throw new SdodsError('CONFIG_INVALID', '--interactive needs --name <har-name>.', {
+                    exitCode: 2,
+                });
+            const entry = ctx.registry.pick(opts.project);
+            const config = ctx.registry.resolve(entry.slug, opts.env);
+            const { runCodegen } = await import('@sdods/core/recorder');
+            const { writeSidecar } = await import('@sdods/core/har');
+            const res = await runCodegen({
+                config,
+                name: opts.name,
+                url: opts.url,
+                saveHar: true,
+                harUrlGlob: opts.harGlob,
+                outputFile: `${config.runtime.artifactsDir}/../codegen-scratch/${opts.name}.spec.ts`,
+            });
+            if (!res.harFile)
+                throw new SdodsError('RUN_FAILED', 'Codegen closed without writing a HAR.', {
+                    exitCode: 1,
+                });
+            writeSidecar(config, {
+                name: opts.name,
+                project: entry.slug,
+                env: config.env.name,
+                urlGlob: opts.harGlob,
+                recordedAt: new Date().toISOString(),
+                source: 'codegen',
+                scenarios: [],
+            });
+            if (ctx.opts.json)
+                return json({ har: res.harFile });
+            return ok(`HAR written: ${relative(ctx.rootDir, res.harFile)} — tag scenarios with @har:${opts.name}`);
+        }
+        const tags = opts.tags ?? '@har:*';
+        if (tags === '@har:*') {
+            // Cucumber tag expressions have no wildcards: run every ui/hybrid/api scenario in update mode;
+            // the hook only records for scenarios that carry a @har:<name> tag.
+            out(pc.dim('no --tags given: running the project in HAR update mode (only @har-tagged scenarios record)'));
+        }
+        process.exitCode = await runCommand(baseRunFlags({
+            project: opts.project,
+            env: opts.env,
+            tags: tags === '@har:*' ? undefined : tags,
+            layer: opts.layer,
+            browser: opts.browser.length ? opts.browser : ['chromium'],
+            harUpdate: true,
+        }), cmd);
+    });
+    har
+        .command('replay')
+        .description('Run scenarios from their HAR files; --strict aborts any request that is not recorded (offline)')
+        .option('-p, --project <slug>', 'project slug')
+        .option('-e, --env <name>', 'environment')
+        .option('-t, --tags <expr>', 'tag expression (default: all)')
+        .option('-l, --layer <layer>', 'ui | api | hybrid (repeatable)', collect, [])
+        .option('-b, --browser <name>', 'browser (repeatable)', collect, [])
+        .option('--strict', 'abort requests missing from the HAR and block all other network')
+        .option('-w, --workers <n>', 'workers')
+        .action(async (opts, cmd) => {
+        process.exitCode = await runCommand(baseRunFlags({
+            project: opts.project,
+            env: opts.env,
+            tags: opts.tags,
+            layer: opts.layer,
+            browser: opts.browser,
+            harReplay: true,
+            strict: Boolean(opts.strict),
+            workers: opts.workers ? Number(opts.workers) : undefined,
+        }), cmd);
+    });
+    har
+        .command('list')
+        .description('List HAR files of a project')
+        .option('-p, --project <slug>', 'project slug')
+        .option('-e, --env <name>', 'only this environment')
+        .action(async (opts, cmd) => {
+        const ctx = createContext(cmd);
+        const entry = ctx.registry.pick(opts.project);
+        const { listHars } = await import('@sdods/core/har');
+        const rows = listHars(entry.root, opts.env).map((h) => ({
+            env: h.env,
+            name: h.name,
+            tag: `@har:${h.name}`,
+            size: `${Math.round(h.sizeBytes / 1024)} KB`,
+            api: h.apiFile ? 'yes' : '',
+            glob: h.sidecar?.urlGlob ?? '',
+            recorded: h.sidecar?.recordedAt?.slice(0, 19).replace('T', ' ') ?? '',
+            scenarios: h.sidecar?.scenarios?.length ?? 0,
+            file: relative(ctx.rootDir, h.file),
+        }));
+        if (ctx.opts.json)
+            return json(rows);
+        table(rows, ['env', 'name', 'tag', 'size', 'api', 'glob', 'recorded', 'scenarios']);
+    });
+}
+//# sourceMappingURL=har.js.map

package/dist/commands/heal.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+export declare function latestRunDir(artifactsDir: string): string | undefined;
+export declare function register(program: Command): void;
+//# sourceMappingURL=heal.d.ts.map

package/dist/commands/heal.js

@@ -0,0 +1,63 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import pc from 'picocolors';
+import { SdodsError, HealHistory, collectHealEvents, summarizeHealEvents } from '@sdods/core';
+import { createContext } from '../context.js';
+import { json, out, table } from '../ui.js';
+export function latestRunDir(artifactsDir) {
+    if (!existsSync(artifactsDir))
+        return undefined;
+    const dirs = readdirSync(artifactsDir)
+        .map((d) => join(artifactsDir, d))
+        .filter((d) => statSync(d).isDirectory() && existsSync(join(d, 'run.json')))
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    return dirs[0];
+}
+export function register(program) {
+    const heal = program.command('heal').description('Self-healing locator reports');
+    heal
+        .command('report')
+        .description('Summarise heal events from a run (or every run) and suggest locator updates')
+        .option('--run <id>', 'run id')
+        .option('--last', 'the most recent run (default)')
+        .option('--all', 'aggregate every run under the artifacts dir')
+        .option('--write-history', 'persist a heal-history.json used to bias future heals')
+        .action((opts, cmd) => {
+        const ctx = createContext(cmd);
+        const artifacts = join(ctx.rootDir, process.env.SDODS_ARTIFACTS_DIR ?? '.sdods/runs');
+        const root = opts.all
+            ? artifacts
+            : opts.run
+                ? join(artifacts, opts.run)
+                : latestRunDir(artifacts);
+        if (!root || !existsSync(root))
+            throw new SdodsError('RUN_FAILED', 'No run found.', {
+                hint: 'Run `sdods run` first or pass --run <id>.',
+                exitCode: 2,
+            });
+        const events = collectHealEvents(root);
+        const rows = summarizeHealEvents(events);
+        if (opts.writeHistory) {
+            const history = new HealHistory(join(artifacts, '..', 'heal-history.json'));
+            for (const e of events)
+                history.record(e);
+            history.save();
+        }
+        if (ctx.opts.json)
+            return json({ root, events: events.length, rows });
+        if (!rows.length)
+            return out(pc.green(`No heal events under ${root}`));
+        table(rows.map((r) => ({
+            description: r.description,
+            original: r.originalSelector,
+            occurrences: r.occurrences,
+            succeeded: r.succeeded,
+            strategy: Object.entries(r.strategies)
+                .map(([k, v]) => `${k}×${v}`)
+                .join(' '),
+            suggested: r.suggestedSelector ?? '',
+        })));
+        out(pc.dim(`${events.length} event(s) from ${root}`));
+    });
+}
+//# sourceMappingURL=heal.js.map

package/dist/commands/init.d.ts

@@ -0,0 +1,38 @@
+import type { Command } from 'commander';
+/** Root of the SDODS monorepo this CLI runs from (used by --link, which needs a real checkout). */
+export declare function sourceRepoRoot(): string;
+/**
+ * Where `init` reads the assets it copies into a new workspace. A real checkout wins, so working
+ * on SDODS scaffolds from the live `projects/demo-shop` rather than a staged copy. A published
+ * install has no checkout above it and falls back to `templates/`, put into the tarball at pack
+ * time by scripts/build-publish-assets.ts. The staged layout mirrors the repo root, so the callers
+ * below resolve the same relative paths either way.
+ */
+export declare function templateRoot(): string;
+export interface InitFlags {
+    db: 'sqlite' | 'postgres';
+    pm: 'bun' | 'pnpm';
+    demo: boolean;
+    claude?: boolean;
+    from?: string;
+    git?: boolean;
+    link?: boolean;
+    install: boolean;
+    browsers: boolean;
+    org: string;
+    orgName?: string;
+    workspace: string;
+    workspaceName?: string;
+    force?: boolean;
+}
+export declare function register(program: Command): void;
+export interface InitResult {
+    dir: string;
+    files: string[];
+    installed: boolean;
+    browsers: boolean;
+    demo: boolean;
+}
+export declare function initWorkspace(target: string, flags: InitFlags): Promise<InitResult>;
+export declare function isDir(p: string): boolean;
+//# sourceMappingURL=init.d.ts.map