@sdods/cli 0.2.0

package/dist/context.js

@@ -0,0 +1,22 @@
+import { ProjectRegistry, setLogJson, setLogLevel } from '@sdods/core';
+export function globalOptions(cmd) {
+    let root = cmd;
+    while (root.parent)
+        root = root.parent;
+    return root.opts();
+}
+export function createContext(cmd) {
+    const opts = globalOptions(cmd);
+    const rootDir = ProjectRegistry.findRepoRoot(opts.cwd ?? process.cwd());
+    if (opts.verbose)
+        setLogLevel('debug');
+    else if (opts.quiet)
+        setLogLevel('error');
+    if (opts.json)
+        setLogJson(true);
+    if (opts.color === false)
+        process.env.NO_COLOR = '1';
+    const registry = ProjectRegistry.discover(rootDir);
+    return { rootDir, registry, opts };
+}
+//# sourceMappingURL=context.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { buildProgram } from './program.js';
+export { createContext, type CliContext, type GlobalOptions } from './context.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+export { buildProgram } from './program.js';
+export { createContext } from './context.js';
+//# sourceMappingURL=index.js.map

package/dist/program.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+/**
+ * All commands are registered eagerly (cheap) but each module keeps heavy imports
+ * (server, agents, DB, browser runner) inside its action via dynamic import.
+ */
+export declare function buildProgram(): Command;
+//# sourceMappingURL=program.d.ts.map

package/dist/program.js

@@ -0,0 +1,90 @@
+import { Command } from 'commander';
+import { VERSION } from '@sdods/core';
+import { registerProjectCommands } from './commands/project.js';
+import { registerEnvCommands } from './commands/env.js';
+import { registerConfigCommands } from './commands/config.js';
+import { registerDoctorCommand } from './commands/doctor.js';
+import { registerWorkspaceCommands } from './commands/workspace.js';
+import { register as registerRun } from './commands/run.js';
+import { register as registerLint } from './commands/lint.js';
+import { register as registerInit } from './commands/init.js';
+import { register as registerAnalyze } from './commands/analyze.js';
+import { register as registerRecord } from './commands/record.js';
+import { register as registerHar } from './commands/har.js';
+import { register as registerAuth } from './commands/auth.js';
+import { register as registerData } from './commands/data.js';
+import { register as registerDb } from './commands/db.js';
+import { register as registerReport } from './commands/report.js';
+import { register as registerHeal } from './commands/heal.js';
+import { register as registerInsights } from './commands/insights.js';
+import { register as registerSteps } from './commands/steps.js';
+import { register as registerFeatures } from './commands/features.js';
+import { register as registerCoverage } from './commands/coverage.js';
+import { register as registerBrowsers } from './commands/browsers.js';
+import { register as registerWatch } from './commands/watch.js';
+import { register as registerTrace } from './commands/trace.js';
+import { register as registerAgent } from './commands/agent.js';
+import { register as registerProposals } from './commands/proposals.js';
+import { register as registerMcp } from './commands/mcp.js';
+import { register as registerServe } from './commands/serve.js';
+import { register as registerUsers } from './commands/users.js';
+import { register as registerTokens } from './commands/tokens.js';
+import { register as registerSchedule } from './commands/schedule.js';
+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';
+/**
+ * All commands are registered eagerly (cheap) but each module keeps heavy imports
+ * (server, agents, DB, browser runner) inside its action via dynamic import.
+ */
+export function buildProgram() {
+    const program = new Command('sdods');
+    program
+        .description('SDODS — automation and orchestration for reliable business workflows: BDD for UI, API and hybrid flows.')
+        .version(VERSION, '-V, --version')
+        .option('--json', 'machine-readable output')
+        .option('-q, --quiet', 'only errors')
+        .option('--verbose', 'debug logging')
+        .option('--cwd <dir>', 'repo root (default: auto-detect from the current directory)')
+        .option('--no-color', 'disable colours')
+        .showHelpAfterError('(add --help for usage)')
+        .showSuggestionAfterError()
+        .configureHelp({ sortSubcommands: true });
+    registerProjectCommands(program);
+    registerEnvCommands(program);
+    registerConfigCommands(program);
+    registerDoctorCommand(program);
+    registerWorkspaceCommands(program);
+    registerRun(program);
+    registerLint(program);
+    registerInit(program);
+    registerAnalyze(program);
+    registerRecord(program);
+    registerHar(program);
+    registerAuth(program);
+    registerData(program);
+    registerDb(program);
+    registerReport(program);
+    registerHeal(program);
+    registerInsights(program);
+    registerSteps(program);
+    registerFeatures(program);
+    registerCoverage(program);
+    registerBrowsers(program);
+    registerWatch(program);
+    registerTrace(program);
+    registerAgent(program);
+    registerProposals(program);
+    registerMcp(program);
+    registerServe(program);
+    registerUsers(program);
+    registerTokens(program);
+    registerSchedule(program);
+    registerIntegrations(program);
+    registerCompletion(program);
+    registerUpgrade(program);
+    registerFeedback(program);
+    return program;
+}
+//# sourceMappingURL=program.js.map

package/dist/templates/project.d.ts

@@ -0,0 +1,10 @@
+import type { ProjectConfig } from '@sdods/contracts';
+export interface TemplateInput {
+    config: ProjectConfig;
+    envName: string;
+    uiUrl: string;
+    apiUrl: string;
+}
+/** Files written by `sdods project create` (relative path → content). */
+export declare function projectTemplateFiles({ config, envName, uiUrl, apiUrl, }: TemplateInput): Record<string, string>;
+//# sourceMappingURL=project.d.ts.map

package/dist/templates/project.js

@@ -0,0 +1,115 @@
+/** Files written by `sdods project create` (relative path → content). */
+export function projectTemplateFiles({ config, envName, uiUrl, apiUrl, }) {
+    const slug = config.slug;
+    const pascal = slug.replace(/(^|-)(\w)/g, (_m, _p, c) => c.toUpperCase());
+    return {
+        [`envs/${envName}.yaml`]: `name: ${envName}
+ui:
+  baseUrl: ${uiUrl}
+api:
+  baseUrl: ${apiUrl}
+  headers: { Accept: application/json }
+  auth: { type: none }
+  # auth: { type: bearer, token: '\${API_TOKEN}' }
+users:
+  poolSize: 2
+vars: {}
+`,
+        '.env.example': `# Copy to .env.${envName} (gitignored). Values referenced as \${VAR} in yaml.\n# API_TOKEN=\n`,
+        'steps/fixtures.ts': `import { test as base, createBdd } from '@sdods/core/fixtures';
+import { HomePage } from '../pages/HomePage.js';
+import { auth } from './auth.js';
+
+/**
+ * Project-level test object: extends the SDODS merged fixtures with this project's
+ * auth strategy and page objects. playwright-bdd imports this file (importTestFrom).
+ */
+export const test = base.extend<{ homePage: HomePage }>({
+  auth: [auth, { scope: 'worker', option: true }],
+  homePage: async ({ pages }, use) => {
+    await use(pages.get(HomePage));
+  },
+});
+
+export const { Given, When, Then, Step, BeforeScenario, AfterScenario, BeforeStep, AfterStep, BeforeWorker, AfterWorker } =
+  createBdd(test);
+`,
+        'steps/auth.ts': `import { defineAuth } from '@sdods/core/auth';
+
+/** Login strategy used for storageState reuse. Replace with your app's flow. */
+export const auth = defineAuth({
+  strategy: 'none',
+});
+`,
+        [`steps/${slug}.steps.ts`]: `import { expect } from '@playwright/test';
+import { Then } from './fixtures.js';
+
+// Project-specific steps. Generic UI/API/data steps come from @sdods/core/steps.
+Then('the ${config.name} title should be visible', async ({ homePage }) => {
+  await expect(homePage.title).toBeVisible();
+});
+`,
+        'pages/HomePage.ts': `import { Fixture, Given } from 'playwright-bdd/decorators';
+import { BasePage } from '@sdods/core/pages';
+import type { test } from '../steps/fixtures.js';
+
+@Fixture<typeof test>('homePage')
+export class HomePage extends BasePage {
+  readonly title = this.heal.locator(this.page.locator('h1').first(), {
+    role: 'heading',
+    description: 'page title',
+  });
+
+  @Given('I open the home page')
+  async open() {
+    await this.goto('home');
+  }
+}
+`,
+        'features/health.feature': `@api @smoke
+Feature: ${config.name} API health
+  As an engineer I want the API to answer so that the rest of the suite is meaningful.
+
+  Scenario: The API root responds
+    When I send a GET request to "/"
+    Then the response status should be 200
+`,
+        'features/ui/home.feature': `@ui @smoke
+Feature: ${config.name} home page
+  Scenario: The home page loads
+    Given I open the home page
+    Then the page URL should contain "/"
+`,
+        'data/common/users.csv': `id,username,password,role\n1,user1,\${USER1_PASSWORD},standard\n2,user2,\${USER2_PASSWORD},standard\n3,admin1,\${ADMIN1_PASSWORD},admin\n`,
+        [`data/${envName}/.gitkeep`]: '',
+        'data/factories.ts': `import { defineFactories } from '@sdods/core/data';
+
+export default defineFactories({
+  user: (f) => ({
+    email: f.internet.email(),
+    firstName: f.person.firstName(),
+    lastName: f.person.lastName(),
+  }),
+});
+`,
+        'recorded/.gitkeep': '',
+        'har/.gitkeep': '',
+        'README.md': `# ${config.name} (${slug})
+
+SDODS project. Run:
+
+\`\`\`bash
+sdods run -p ${slug} -e ${envName} -l api
+sdods run -p ${slug} -e ${envName} -l ui -b chromium -t @smoke
+sdods lint -p ${slug}
+\`\`\`
+
+- \`sdods.project.yaml\` — project settings (layers, browsers, tags, data, auth, screenshots)
+- \`envs/\` — one yaml per environment; secrets via \`\${VAR}\` from \`.env.<env>\`
+- \`features/\` — Gherkin; \`steps/\` — project steps + fixtures; \`pages/\` — page objects (decorators)
+- \`data/\` — CSV/JSON/YAML per environment with \`data/common\` fallback
+- \`${pascal}\` page object in \`pages/HomePage.ts\` shows the heal-aware locator style
+`,
+    };
+}
+//# sourceMappingURL=project.js.map

package/dist/ui.d.ts

@@ -0,0 +1,16 @@
+export interface OutputOptions {
+    json?: boolean;
+    quiet?: boolean;
+}
+export declare function out(text: string, opts?: OutputOptions): void;
+export declare function json(value: unknown): void;
+export declare function table(rows: Array<Record<string, unknown>>, columns?: string[]): void;
+export declare function ok(msg: string): void;
+export declare function warn(msg: string): void;
+export declare function info(msg: string): void;
+export declare function heading(msg: string): void;
+/** Render an error and return the process exit code. */
+export declare function renderError(e: unknown, asJson: boolean): number;
+export declare function parseIntFlag(name: string): (v: string) => number;
+export declare function collect(value: string, previous?: string[]): string[];
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.js

@@ -0,0 +1,67 @@
+import pc from 'picocolors';
+import { errorToJson, isSdodsError } from '@sdods/core';
+export function out(text, opts = {}) {
+    if (opts.quiet)
+        return;
+    process.stdout.write(text.endsWith('\n') ? text : text + '\n');
+}
+export function json(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+}
+export function table(rows, columns) {
+    if (rows.length === 0)
+        return out(pc.dim('(none)'));
+    const cols = columns ?? Object.keys(rows[0]);
+    const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? '').length)));
+    const line = (vals) => vals.map((v, i) => v.padEnd(widths[i])).join('  ');
+    out(pc.bold(line(cols)));
+    out(pc.dim(line(widths.map((w) => '─'.repeat(w)))));
+    for (const r of rows)
+        out(line(cols.map((c) => String(r[c] ?? ''))));
+}
+export function ok(msg) {
+    out(`${pc.green('✔')} ${msg}`);
+}
+export function warn(msg) {
+    process.stderr.write(`${pc.yellow('⚠')} ${msg}\n`);
+}
+export function info(msg) {
+    out(`${pc.cyan('ℹ')} ${msg}`);
+}
+export function heading(msg) {
+    out(`\n${pc.bold(pc.underline(msg))}`);
+}
+/** Render an error and return the process exit code. */
+export function renderError(e, asJson) {
+    const body = errorToJson(e);
+    if (asJson) {
+        process.stderr.write(JSON.stringify({ error: body }) + '\n');
+    }
+    else {
+        process.stderr.write(`${pc.red('✖')} ${pc.bold(body.code)}: ${body.message}\n`);
+        if (body.hint)
+            process.stderr.write(`  ${pc.dim('hint:')} ${body.hint}\n`);
+        if (body.docsUrl)
+            process.stderr.write(`  ${pc.dim('docs:')} ${body.docsUrl}\n`);
+        if (process.env.SDODS_DEBUG && e instanceof Error && e.stack)
+            process.stderr.write(pc.dim(e.stack) + '\n');
+    }
+    if (isSdodsError(e))
+        return e.exitCode;
+    return 1;
+}
+export function parseIntFlag(name) {
+    return (v) => {
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < 0)
+            throw new Error(`--${name} expects a non-negative integer, got "${v}"`);
+        return n;
+    };
+}
+export function collect(value, previous = []) {
+    return previous.concat(value
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean));
+}
+//# sourceMappingURL=ui.js.map

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@sdods/cli",
+  "version": "0.2.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>",
+  "type": "module",
+  "bin": {
+    "sdods": "./bin/sdods.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@sdods/contracts": "0.2.0",
+    "@sdods/core": "0.2.0",
+    "commander": "^15.0.0",
+    "execa": "^10.0.1",
+    "picocolors": "^1.1.1",
+    "semver": "^7.8.5",
+    "yaml": "^2.9.0",
+    "zod": "^4.5.4",
+    "@playwright/test": "^1.62.1",
+    "playwright-core": "^1.62.1",
+    "@sdods/integrations": "0.2.0",
+    "@sdods/mcp": "0.2.0",
+    "@sdods/agents": "0.2.0",
+    "@sdods/db": "0.2.0",
+    "csv-parse": "^7.0.2",
+    "@sdods/server": "0.2.0"
+  },
+  "homepage": "https://sdods.com",
+  "bugs": {
+    "url": "https://github.com/siri1410/SDODS/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siri1410/SDODS.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "sdods",
+    "automation",
+    "orchestration",
+    "testing",
+    "bdd",
+    "ai-agents",
+    "mcp"
+  ]
+}

package/templates/.claude/skills/sdods-record/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: sdods-record
+description: Record a browser flow with SDODS for a given project, environment, user role and device, save it as a runnable spec, replay it, and optionally convert it into a Gherkin feature with reusable steps. Use when the user says "record", "codegen", "capture a flow", "re-record as <role>", or wants the same flow recorded across environments or users.
+---
+
+# SDODS record & playback skill
+
+Re-runnable recipe. Ask for the parameters you do not have, then follow the steps. Never edit `main` directly; recordings land in `projects/<project>/recorded/` and conversions become proposals.
+
+## Parameters
+
+| Name | Required | Example | Notes |
+|---|---|---|---|
+| `project` | yes | `demo-shop` | `bun run sdods project list` shows slugs |
+| `env` | yes | `staging`, `local` | `bun run sdods env list -p <project>` |
+| `name` | yes | `checkout-standard` | becomes `recorded/<name>.spec.ts`; include the role in the name |
+| `role` | no | `standard`, `problem`, `admin` | leases a pool user of that role and starts logged in (storageState) |
+| `url` | no | `/inventory.html` | route path or absolute URL to open first |
+| `device` | no | `"iPhone 15"`, `"Pixel 7"` | device name for mobile emulation |
+| `browser` | no | `chromium` (default), `firefox`, `webkit` | |
+| `har` | no | `true` | also capture network into `har/<env>/<name>.har` for offline replay |
+
+## Steps
+
+1. **Check the environment** (fail fast on missing vars):
+   ```bash
+   bun run sdods doctor -p <project>
+   bun run sdods env list -p <project>
+   ```
+2. **Make sure the role has login state** (skip when no role):
+   ```bash
+   bun run sdods auth list -p <project> -e <env>
+   bun run sdods auth capture -p <project> -e <env> --user <role>      # only if missing or expired
+   ```
+3. **Record** (opens the recorder; the person performs the flow and closes the window):
+   ```bash
+   bun run sdods record -p <project> -e <env> --name <name> [--user <role>] [--url <url>] [--device "<device>"] [--browser <browser>] [--save-har]
+   ```
+   Output: `projects/<project>/recorded/<name>.spec.ts`, post-processed (SDODS fixtures, routes instead of absolute URLs, tags `@recorded @ui @regression`, header comment with project/env/role/device).
+4. **Play it back** on the same environment, then on another one:
+   ```bash
+   bun run sdods run -p <project> -e <env> -l recorded --grep "<name>"
+   bun run sdods run -p <project> -e <other-env> -l recorded --grep "<name>"
+   ```
+   Look at `.sdods/runs/<runId>/` for screenshots and the HTML report (`bun run sdods report --last --open`).
+5. **Repeat for other roles, environments or devices** by changing only the parameters. Use distinct names (`checkout-standard`, `checkout-problem`, `checkout-standard-iphone`).
+6. **Convert to Gherkin** when the flow is stable (agent proposal, reviewed by a person):
+   ```bash
+   bun run sdods record convert projects/<project>/recorded/<name>.spec.ts
+   bun run sdods proposals list
+   bun run sdods proposals show <id>
+   bun run sdods proposals accept <id> --branch sdods/<id>     # after review
+   bun run sdods lint -p <project>
+   ```
+   The proposal reuses existing steps first (`bun run sdods steps list -p <project>`), adds only unmatched steps, and creates a page object with heal-aware locators.
+7. **Offline replay** (CI-friendly) when HAR was captured:
+   ```bash
+   bun run sdods har replay -p <project> -e <env> --strict -t "@har:<name>"
+   ```
+
+## Matrix template
+
+Ask the user which cells to record, then run step 3 per cell:
+
+| role \ env | local | staging |
+|---|---|---|
+| standard | `--user standard -e local` | `--user standard -e staging` |
+| problem | `--user problem -e local` | `--user problem -e staging` |
+| admin (mobile) | `--user admin -e local --device "iPhone 15"` | `--user admin -e staging --device "iPhone 15"` |
+
+## Done when
+
+- Each recording runs green with `-l recorded` on its environment.
+- Names, roles and envs are visible in `sdods features list -p <project> --json` or `recorded/` file headers.
+- Converted features pass `sdods lint` and are tagged with one layer tag and one suite tag.

package/templates/.claude/skills/sdods-run/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: sdods-run
+description: Run SDODS test suites for a project across environments, layers (ui/api/hybrid/recorded), browsers, suites (@smoke/@regression) and user roles, then read the results. Use when the user says "run the tests", "smoke on staging", "regression on all browsers", "run as <role>", or asks what failed.
+---
+
+# SDODS run skill
+
+## Parameters
+
+| Name | Default | Notes |
+|---|---|---|
+| `project` | only project if one exists | `bun run sdods project list` |
+| `env` | project `envs.default` | `bun run sdods env list -p <project>` |
+| `layer` | all layers in the project | `-l ui`, `-l api`, `-l hybrid`, `-l recorded` (repeatable) |
+| `browser` | project `browsers` | `-b chromium -b firefox -b webkit`, or `--project-matrix` for all |
+| `tags` | none | Cucumber expression, e.g. `"@smoke and not @mock"`, `@user:admin`, `@jira:DEMO-12` |
+| `headed` | false | `--headed` for a visible browser |
+| `workers` | runner default | `-w 2` |
+| `shard` | none | `--shard 1/3` |
+| `har` | off | `--har-replay --strict` for offline runs, `--har-update` to refresh |
+
+## Steps
+
+1. Validate before running (cheap, catches config and tag mistakes):
+   ```bash
+   bun run sdods config validate
+   bun run sdods lint -p <project>
+   bun run sdods run -p <project> -e <env> --list          # shows the run targets that would run
+   ```
+2. Run the requested slice. Typical combinations:
+   ```bash
+   bun run sdods run -p <project> -e <env> -l api                                  # API only, no browser
+   bun run sdods run -p <project> -e <env> -l ui -b chromium -t @smoke             # quick UI smoke
+   bun run sdods run -p <project> -e <env> -t @regression --project-matrix         # every browser in the yaml
+   bun run sdods run -p <project> -e <env> -t "@user:admin"                        # scenarios that lease admin users
+   bun run sdods run -p <project> -e <env> -l hybrid -w 2                          # API→UI chaining
+   bun run sdods run -p <project> -e <env> --har-replay --strict -t @smoke         # offline, CI-style
+   ```
+3. Read results:
+   ```bash
+   bun run sdods report --last                    # summary: totals, failed, flaky, report paths
+   bun run sdods report --last --open             # HTML report + dashboard
+   bun run sdods heal report --last               # locators that were healed
+   ```
+   Artifacts: `.sdods/runs/<runId>/<project>/<fingerprint>/r<retry>/` holds `scenario-start.png`, `NN-before.png`/`NN-after.png` per UI step (policy by suite tag), `api/*.json` per API call, `heal.jsonl`.
+4. If something failed, collect: the scenario name, the error from `summary.json`, the `failure.png`, and the trace (`bun run sdods trace --last`). Then either fix the feature/page object or hand it to the healer agent:
+   ```bash
+   bun run sdods agent heal -p <project> --scenario <fingerprint> --dry-run
+   ```
+5. Repeat for other environments or roles by changing `-e` / `-t "@user:<role>"` only.
+
+## Exit codes
+
+`0` all passed · `1` test failures · `2` configuration or usage error · `3` lint errors · `130` cancelled.

package/templates/.env.example

@@ -0,0 +1,62 @@
+# ── SDODS: tokens and keys ─────────────────────────────────────────────────
+# Nothing here is mandatory for the platform itself. SDODS API tokens are
+# self-issued and free (`sdods tokens create`). Check status: `sdods doctor`.
+#
+#   mandatory  only when the feature next to it is used
+#   one-of     agents need ANY ONE of the four options in the Agents block
+#   optional   turns on an integration
+#   ci-only    GitHub Actions secrets, never needed locally
+
+# ── Database (mandatory: none; DATABASE_URL only when DB_DRIVER=postgres) ─────
+DB_DRIVER=sqlite
+SQLITE_PATH=.sdods/sdods.db
+# DATABASE_URL=postgres://sdods:sdods@localhost:5432/sdods
+
+# ── Web server (`sdods serve`) — SESSION_SECRET mandatory for serve only ────
+PORT=4444
+HOST=127.0.0.1
+SESSION_SECRET=change-me-32-chars-minimum-please   # openssl rand -hex 32
+# SDODS_PUBLIC_URL=https://sdods.example.com
+# AUTH_DISABLED=1   # local dev only
+
+# Where projects and run artifacts live (defaults shown)
+# SDODS_PROJECTS_DIR=projects
+# SDODS_ARTIFACTS_DIR=.sdods/runs
+
+# ── Agents (one-of; every agent command also has --dry-run and --adapter fake) ─
+# Pick ONE way for agents to reach a model. Auto-detection order when unset:
+#   ANTHROPIC_API_KEY → `claude` CLI on PATH → `codex` CLI on PATH → OPENAI_API_KEY
+#   → a local Ollama → fake
+# SDODS_LLM_PROVIDER=claude-code      # claude | claude-code | codex | openai-compatible | ollama | fake
+#
+# 1) Claude via API key (billed by Anthropic)
+# ANTHROPIC_API_KEY=
+#
+# 2) Claude Code CLI login — no key needed: `npm i -g @anthropic-ai/claude-code && claude login`
+#    (adapter claude-code; optional SDODS_CLAUDE_CODE_MODEL=... to pin a model)
+#
+# 3) Codex CLI login — no key needed: `npm i -g @openai/codex && codex login`
+#    (adapter codex; optional SDODS_CODEX_MODEL=... to pin a model)
+#
+# 4) Any OpenAI-compatible endpoint (billed by the provider)
+# OPENAI_API_KEY=
+# OPENAI_BASE_URL=                      # optional: Azure, vLLM, LM Studio, llama.cpp
+#
+# 5) A model on this machine — no key, no per-token cost (adapter ollama)
+#    `ollama serve && ollama pull qwen2.5-coder:7b`
+# OLLAMA_HOST=http://127.0.0.1:11434
+# OLLAMA_MODEL=qwen2.5-coder:7b
+# OLLAMA_CONTEXT_LENGTH=16384           # Ollama defaults to 4096 and truncates longer prompts
+
+# ── Integrations (optional; project yaml stores only the variable NAMES) ──────
+# GITHUB_TOKEN=            # check runs, PR comments, issues
+# JIRA_EMAIL=              # Jira Cloud basic auth
+# JIRA_API_TOKEN=
+
+# ── SDODS's own token (optional, free): MCP over HTTP and CI ingest ─────────
+# SDODS_SERVER_URL=http://127.0.0.1:4444
+# SDODS_TOKEN=amx_...    # sdods tokens create --user <name> --scopes runs:ingest,runs:read
+
+# ── CI-only GitHub secrets (never needed locally) ────────────────────────────
+# FIREBASE_SERVICE_ACCOUNT_AUTOMAX_DOCS   docs deploy (Firebase Hosting)
+# NPM_TOKEN                               publishing @sdods/* packages

package/templates/docker-compose.yml

@@ -0,0 +1,40 @@
+services:
+  postgres:
+    image: postgres:16
+    container_name: sdods-postgres
+    environment:
+      POSTGRES_USER: sdods
+      POSTGRES_PASSWORD: sdods
+      POSTGRES_DB: sdods
+    ports:
+      - '5432:5432'
+    volumes:
+      - sdods-pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U sdods -d sdods']
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  # Optional: the SDODS web server on Postgres. Build with `docker build -t sdods .` first.
+  sdods:
+    image: sdods:latest
+    profiles: ['server']
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      DB_DRIVER: postgres
+      DATABASE_URL: postgres://sdods:sdods@postgres:5432/sdods
+      HOST: 0.0.0.0
+      PORT: 4444
+      SESSION_SECRET: change-me-32-chars-minimum-please
+    ports:
+      - '4444:4444'
+    volumes:
+      - ./projects:/app/projects
+      - sdods-runs:/app/.sdods
+
+volumes:
+  sdods-pgdata:
+  sdods-runs:

package/templates/projects/demo-shop/.env.example

@@ -0,0 +1,4 @@
+# Copy to .env.staging / .env.local next to this file (both are gitignored).
+DEMO_SHOP_PASSWORD=secret_sauce
+# API_TOKEN=
+# SDODS_TESTDATA_DB_URL=file:./projects/demo-shop/data/staging/testdata.sqlite

package/templates/projects/demo-shop/data/common/posts.yaml

@@ -0,0 +1,11 @@
+# Rows for the "posts" dataset (JSONPlaceholder ids and their owners).
+rows:
+  - id: 1
+    userId: 1
+    title: sunt aut facere repellat provident occaecati excepturi optio reprehenderit
+  - id: 11
+    userId: 2
+    title: et ea vero quia laudantium autem
+  - id: 21
+    userId: 3
+    title: asperiores ea ipsam voluptatibus modi minima quia sint

package/templates/projects/demo-shop/data/common/products.json

@@ -0,0 +1,8 @@
+[
+  { "id": 4, "name": "Sauce Labs Backpack", "price": 29.99 },
+  { "id": 0, "name": "Sauce Labs Bike Light", "price": 9.99 },
+  { "id": 1, "name": "Sauce Labs Bolt T-Shirt", "price": 15.99 },
+  { "id": 5, "name": "Sauce Labs Fleece Jacket", "price": 49.99 },
+  { "id": 2, "name": "Sauce Labs Onesie", "price": 7.99 },
+  { "id": 3, "name": "Test.allTheThings() T-Shirt (Red)", "price": 15.99 }
+]