@sdods/cli 0.2.0

package/dist/commands/project.js

@@ -0,0 +1,133 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stringify as toYaml } from 'yaml';
+import { BrowserSchema, LayerSchema, ProjectConfigSchema, SlugSchema } from '@sdods/contracts';
+import { SdodsError, PROJECT_FILE } from '@sdods/core';
+import { createContext } from '../context.js';
+import { collect, json, ok, table } from '../ui.js';
+import { projectTemplateFiles } from '../templates/project.js';
+export function registerProjectCommands(program) {
+    const project = program.command('project').description('Create and list SDODS projects');
+    project
+        .command('list')
+        .description('List projects discovered under projects/')
+        .option('--matrix', 'emit a CI matrix (project × browser × shard)')
+        .option('--shards <n>', 'shards per browser for --matrix', '1')
+        .action((opts, cmd) => {
+        const ctx = createContext(cmd);
+        const entries = ctx.registry.entriesList();
+        if (opts.matrix) {
+            const shards = Math.max(1, Number(opts.shards));
+            // Projects with `ci.enabled: false` (e.g. ones that need their own server, like the
+            // dogfooding project) are left to dedicated jobs.
+            const matrix = entries
+                .filter((e) => e.config.ci.enabled)
+                .flatMap((e) => (e.config.ci.browsers ?? e.config.browsers).flatMap((browser) => Array.from({ length: shards }, (_, i) => ({
+                project: e.slug,
+                env: e.config.ci.env ?? e.config.envs.default,
+                tags: e.config.ci.tags ?? '',
+                browser,
+                shard: i + 1,
+                total: shards,
+            }))));
+            return json(matrix);
+        }
+        const rows = entries.map((e) => ({
+            slug: e.slug,
+            name: e.config.name,
+            layers: e.config.layers.join(','),
+            browsers: e.config.browsers.join(','),
+            envs: e.config.envs.available
+                .map((n) => (e.envsOnDisk.includes(n) ? n : `${n}(missing)`))
+                .join(','),
+            default: e.config.envs.default,
+            root: e.root,
+        }));
+        if (ctx.opts.json)
+            return json(rows);
+        table(rows, ['slug', 'name', 'layers', 'browsers', 'envs', 'default']);
+    });
+    project
+        .command('create <slug>')
+        .description('Scaffold a project: yaml, envs, fixtures, an auth stub, a page object, health features and data')
+        .option('--name <name>', 'display name')
+        .option('--layers <list>', 'comma list of ui,api,hybrid,recorded', collect, [])
+        .option('--browsers <list>', 'comma list of browsers', collect, [])
+        .option('--ui-url <url>', 'UI base URL for the first environment', 'http://localhost:3000')
+        .option('--api-url <url>', 'API base URL for the first environment', 'http://localhost:3000/api')
+        .option('--env <name>', 'first environment name', 'local')
+        .option('--test-id <attr>', 'test id attribute', 'data-testid')
+        .option('--force', 'overwrite an existing directory')
+        .action((slug, opts, cmd) => {
+        const ctx = createContext(cmd);
+        SlugSchema.parse(slug);
+        const root = join(ctx.registry.projectsDir, slug);
+        if (existsSync(join(root, PROJECT_FILE)) && !opts.force) {
+            throw new SdodsError('CONFIG_INVALID', `Project "${slug}" already exists at ${root}.`, {
+                hint: 'Pass --force to overwrite.',
+                exitCode: 2,
+            });
+        }
+        const layers = (opts.layers.length ? opts.layers : ['ui', 'api', 'hybrid']).map((l) => LayerSchema.parse(l));
+        const browsers = (opts.browsers.length ? opts.browsers : ['chromium']).map((b) => BrowserSchema.parse(b));
+        const config = ProjectConfigSchema.parse({
+            slug,
+            name: opts.name ?? slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
+            layers,
+            browsers,
+            testIdAttribute: opts.testId,
+            routes: { home: '/' },
+            envs: { default: opts.env, available: [opts.env] },
+            data: {
+                sources: {
+                    users: { type: 'csv', path: 'data/{env}/users.csv', fallback: 'data/common/users.csv' },
+                },
+            },
+        });
+        const files = projectTemplateFiles({
+            config,
+            envName: opts.env,
+            uiUrl: opts.uiUrl,
+            apiUrl: opts.apiUrl,
+        });
+        for (const [rel, content] of Object.entries(files)) {
+            const file = join(root, rel);
+            mkdirSync(join(file, '..'), { recursive: true });
+            writeFileSync(file, content);
+        }
+        const yamlText = toYaml(minimalYaml(config), { lineWidth: 100 });
+        writeFileSync(join(root, PROJECT_FILE), `# SDODS project. Reference: ${'https://docs.sdods.com/docs/reference/project-yaml'}\n${yamlText}`);
+        if (ctx.opts.json)
+            return json({ slug, root, files: [PROJECT_FILE, ...Object.keys(files)] });
+        ok(`Created project ${slug} at ${root}`);
+        for (const f of [PROJECT_FILE, ...Object.keys(files)])
+            console.log(`  ${f}`);
+        console.log(`\nNext: sdods run -p ${slug} -e ${opts.env} -l api`);
+    });
+}
+/** Keep the generated yaml readable: drop defaults the schema fills in. */
+function minimalYaml(config) {
+    return {
+        slug: config.slug,
+        name: config.name,
+        layers: config.layers,
+        browsers: config.browsers,
+        testIdAttribute: config.testIdAttribute,
+        routes: config.routes,
+        tags: { suites: config.tags.suites, extra: config.tags.extra, roles: config.tags.roles },
+        envs: config.envs,
+        data: {
+            sources: config.data.sources,
+            userPool: { dataset: 'users', roleColumn: 'role', leaseStore: 'file' },
+        },
+        auth: { strategy: 'none', storageState: true },
+        screenshots: {
+            policy: config.screenshots.policy,
+            mask: [],
+            viewport: config.screenshots.viewport,
+        },
+        heal: { enabled: true },
+        retries: { ci: 2, local: 0 },
+    };
+}
+//# sourceMappingURL=project.js.map

package/dist/commands/proposals.d.ts

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

package/dist/commands/proposals.js

@@ -0,0 +1,106 @@
+import { execFileSync } from 'node:child_process';
+import pc from 'picocolors';
+import { SdodsError } from '@sdods/core';
+import { createContext } from '../context.js';
+import { json, ok, out, table } from '../ui.js';
+export function register(program) {
+    const proposals = program
+        .command('proposals')
+        .description('Review and apply proposals written by agents and MCP write tools');
+    proposals
+        .command('list')
+        .description('List proposals (newest first)')
+        .option('--status <s>', 'pending | accepted | rejected')
+        .option('-p, --project <slug>')
+        .action(async (opts, cmd) => {
+        const ctx = createContext(cmd);
+        const { ProposalStore } = await import('@sdods/mcp');
+        const rows = new ProposalStore(ctx.rootDir)
+            .list({ status: opts.status, project: opts.project })
+            .map((m) => ({
+            id: m.id,
+            role: m.role,
+            project: m.project ?? '',
+            status: m.status,
+            files: m.files.length,
+            summary: m.summary.slice(0, 70),
+            created: m.createdAt,
+        }));
+        if (ctx.opts.json)
+            return json(rows);
+        table(rows);
+    });
+    proposals
+        .command('show <id>')
+        .description('Show a proposal: manifest and diff against the working tree')
+        .action(async (id, _opts, cmd) => {
+        const ctx = createContext(cmd);
+        const { ProposalStore } = await import('@sdods/mcp');
+        const store = new ProposalStore(ctx.rootDir);
+        const m = store.get(id);
+        if (!m)
+            throw new SdodsError('CONFIG_NOT_FOUND', `Unknown proposal ${id}`, {
+                hint: 'Run `sdods proposals list`.',
+                exitCode: 2,
+            });
+        const diff = store.diff(id);
+        if (ctx.opts.json)
+            return json({ ...m, diff });
+        out(`${pc.bold(m.id)} ${pc.dim(`(${m.role}, ${m.status})`)}\n${m.summary}\n`);
+        for (const f of m.files)
+            out(`  ${f.op === 'add' ? pc.green('+') : f.op === 'delete' ? pc.red('-') : pc.yellow('~')} ${f.path}`);
+        out('');
+        for (const line of diff.split('\n'))
+            out(line.startsWith('+')
+                ? pc.green(line)
+                : line.startsWith('-')
+                    ? pc.red(line)
+                    : pc.dim(line));
+    });
+    proposals
+        .command('accept <id>')
+        .description('Apply a proposal to the working tree (optionally on a new git branch)')
+        .option('--branch <name>', 'create/switch to this branch first')
+        .option('--reviewed-by <name>')
+        .option('--no-lint', 'skip sdods lint after applying')
+        .action(async (id, opts, cmd) => {
+        const ctx = createContext(cmd);
+        const { ProposalStore } = await import('@sdods/mcp');
+        const store = new ProposalStore(ctx.rootDir);
+        const m = store.get(id);
+        if (!m)
+            throw new SdodsError('CONFIG_NOT_FOUND', `Unknown proposal ${id}`, { exitCode: 2 });
+        if (opts.branch) {
+            try {
+                execFileSync('git', ['checkout', '-B', opts.branch], {
+                    cwd: ctx.rootDir,
+                    stdio: 'ignore',
+                });
+            }
+            catch (e) {
+                throw new SdodsError('RUN_FAILED', `Could not switch to branch ${opts.branch}: ${e.message}`);
+            }
+        }
+        const written = store.accept(id, { reviewedBy: opts.reviewedBy ?? process.env.USER });
+        if (ctx.opts.json)
+            return json({ id, written, branch: opts.branch });
+        for (const w of written)
+            ok(w);
+        if (opts.lint !== false && m.project) {
+            out(pc.dim(`Next: sdods lint -p ${m.project}`));
+        }
+    });
+    proposals
+        .command('reject <id>')
+        .description('Reject a proposal')
+        .option('--reason <text>')
+        .action(async (id, opts, cmd) => {
+        const ctx = createContext(cmd);
+        const { ProposalStore } = await import('@sdods/mcp');
+        const m = new ProposalStore(ctx.rootDir).reject(id, opts.reason, process.env.USER);
+        if (ctx.opts.json)
+            return json(m);
+        ok(`Rejected ${m.id}`);
+    });
+}
+//# sourceMappingURL=proposals.js.map

package/dist/commands/record.d.ts

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

package/dist/commands/record.js

@@ -0,0 +1,174 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { execa } from 'execa';
+import pc from 'picocolors';
+import { SdodsError, VERSION } from '@sdods/core';
+import { createContext } from '../context.js';
+import { json, ok, out, warn } from '../ui.js';
+function addRecordOptions(cmd) {
+    return cmd
+        .option('-p, --project <slug>', 'project slug')
+        .option('-e, --env <name>', 'environment name')
+        .option('--name <name>', 'recording name → recorded/<name>.spec.ts (default: rec-<timestamp>)')
+        .option('--url <route|path|url>', 'route name from the project yaml, a path, or an absolute URL', '/')
+        .option('--device <name>', 'device name, e.g. "iPhone 15"')
+        .option('--user <role>', 'use a pool user of this role and start logged in (storageState)')
+        .option('-b, --browser <name>', 'chromium | firefox | webkit', 'chromium')
+        .option('--save-har', 'also capture network into har/<env>/<name>.har')
+        .option('--har-glob <glob>', 'URL glob for --save-har', '**/*')
+        .option('--viewport <WxH>', 'viewport, e.g. 1280x720 (ignored with --device)')
+        .option('--tag <tag>', 'extra tag for the recorded spec (repeatable)', (v, p = []) => p.concat(v), [])
+        .option('--no-post-process', 'keep the raw codegen output');
+}
+async function recordAction(flags, cmd) {
+    const ctx = createContext(cmd);
+    const entry = ctx.registry.pick(flags.project);
+    const config = ctx.registry.resolve(entry.slug, flags.env);
+    const { runCodegen, postProcessRecording } = await import('@sdods/core/recorder');
+    const { writeSidecar } = await import('@sdods/core/har');
+    const { captureAuth, poolUsers } = await import('@sdods/core/auth/capture');
+    const { AuthStateCache } = await import('@sdods/core');
+    const name = flags.name ?? `rec-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}`;
+    const browser = (flags.browser ?? 'chromium');
+    // logged-in start: make sure the first user of the role has a fresh storage state
+    let storageStatePath;
+    let userName;
+    if (flags.user) {
+        const users = await poolUsers(config, flags.user);
+        const user = users[0];
+        userName = user.username;
+        const cache = new AuthStateCache(config);
+        if (!cache.isFresh(user)) {
+            out(pc.dim(`no fresh login state for ${user.username}; capturing…`));
+            const res = await captureAuth({ config, role: flags.user, index: 0, browserName: browser });
+            if (!res[0]?.file)
+                warn(`could not capture login state (${res[0]?.skipped ?? 'unknown'}); recording without it`);
+        }
+        if (cache.isFresh(user))
+            storageStatePath = cache.fileFor(user);
+    }
+    out(pc.dim(`recording ${name} · project ${entry.slug} · env ${config.env.name}${flags.user ? ` · user ${userName} (${flags.user})` : ''}${flags.device ? ` · device ${flags.device}` : ''}`));
+    const result = await runCodegen({
+        config,
+        name,
+        url: flags.url,
+        device: flags.device,
+        browser,
+        storageStatePath,
+        saveHar: flags.saveHar,
+        harUrlGlob: flags.harGlob,
+        viewport: flags.viewport,
+    });
+    if (!result.produced) {
+        throw new SdodsError('RUN_FAILED', 'Codegen closed without writing a spec (nothing was recorded).', {
+            exitCode: 1,
+        });
+    }
+    let summary = {};
+    if (flags.postProcess !== false) {
+        const source = readFileSync(result.outputFile, 'utf8');
+        const processed = postProcessRecording(source, {
+            meta: {
+                project: entry.slug,
+                env: config.env.name,
+                name,
+                recordedAt: new Date().toISOString(),
+                url: flags.url,
+                user: userName,
+                role: flags.user,
+                device: flags.device,
+                browser,
+                har: result.harFile ? name : undefined,
+                sdodsVersion: VERSION,
+                playwright: await playwrightVersion(ctx.rootDir),
+            },
+            baseUrls: [config.env.ui.baseUrl, ...config.env.aliases],
+            tags: ['@recorded', '@ui', '@regression', ...flags.tag],
+        });
+        writeFileSync(result.outputFile, processed.code);
+        for (const w of processed.warnings)
+            warn(w);
+        summary = {
+            fragileLocators: processed.fragileLocators,
+            rewrittenUrls: processed.rewrittenUrls,
+            wrapped: processed.wrapped,
+        };
+    }
+    if (result.harFile) {
+        writeSidecar(config, {
+            name,
+            project: entry.slug,
+            env: config.env.name,
+            urlGlob: flags.harGlob ?? '**/*',
+            recordedAt: new Date().toISOString(),
+            source: 'codegen',
+            scenarios: [name],
+        });
+    }
+    const spec = relative(ctx.rootDir, result.outputFile);
+    if (ctx.opts.json)
+        return json({ name, spec, har: result.harFile, user: userName, role: flags.user, ...summary });
+    ok(`Recorded ${spec}${result.harFile ? ` (+ HAR ${relative(ctx.rootDir, result.harFile)})` : ''}`);
+    if (summary.fragileLocators)
+        warn(`${summary.fragileLocators} CSS/XPath locator(s) marked // sdods:fragile — prefer role/label/test-id locators.`);
+    out(pc.dim(`play back:  sdods run -p ${entry.slug} -e ${config.env.name} -l recorded --grep "${name}"`));
+    out(pc.dim(`convert:    sdods record convert ${spec}`));
+}
+export function register(program) {
+    const record = addRecordOptions(program
+        .command('record')
+        .description('Record a browser session into a runnable spec under recorded/ (alias: codegen)'));
+    record.action(recordAction);
+    record
+        .command('convert <spec>')
+        .description('Ask the generator agent to turn a recorded spec into a feature + steps proposal (reviewed, never auto-applied)')
+        .option('-p, --project <slug>', 'project slug (default: inferred from the spec path)')
+        .option('--dry-run', 'print the prompt and plan without calling a model')
+        .option('--adapter <name>', 'claude | claude-code | codex | openai | ollama | fake; default: auto-detect')
+        .option('--model <id>', 'model override')
+        .option('--profile <name>', 'auto | full | small — how much of the platform the model is shown')
+        .action(async (spec, opts, cmd) => {
+        const ctx = createContext(cmd);
+        if (!existsSync(spec))
+            throw new SdodsError('CONFIG_NOT_FOUND', `Spec not found: ${spec}`, { exitCode: 2 });
+        // The generator agent works on a project; a spec under projects/<slug>/recorded names it.
+        const project = opts.project ?? /(?:^|\/)projects\/([^/]+)\//.exec(spec)?.[1];
+        if (!project)
+            throw new SdodsError('CONFIG_INVALID', `Cannot tell which project ${spec} belongs to.`, {
+                hint: 'Pass -p <slug>, or keep recordings under projects/<slug>/recorded/.',
+                exitCode: 2,
+            });
+        const args = [process.argv[1], 'agent', 'generate', '-p', project, '--spec', spec];
+        if (opts.dryRun)
+            args.push('--dry-run');
+        if (opts.adapter)
+            args.push('--adapter', opts.adapter);
+        if (opts.model)
+            args.push('--model', opts.model);
+        if (opts.profile)
+            args.push('--profile', opts.profile);
+        if (ctx.opts.json)
+            args.push('--json');
+        const res = await execa(process.execPath, ['--import', 'tsx', ...args], {
+            cwd: ctx.rootDir,
+            stdio: 'inherit',
+            reject: false,
+        });
+        if (res.exitCode === 2) {
+            warn('The agent layer is not available in this build yet; the recording stays runnable under recorded/.');
+        }
+        process.exitCode = res.exitCode ?? 1;
+    });
+    const codegen = addRecordOptions(program.command('codegen').description('Alias of record'));
+    codegen.action(recordAction);
+}
+async function playwrightVersion(cwd) {
+    try {
+        const { stdout } = await execa('npx', ['playwright', '--version'], { cwd });
+        return stdout.trim().replace(/^Version\s+/i, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=record.js.map

package/dist/commands/report.d.ts

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