@sdods/mcp 0.2.0

package/dist/fs.js

@@ -0,0 +1,184 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { runFiles, scenarioFiles, } from '@sdods/contracts';
+export const RUNS_DIR = '.sdods/runs';
+export const PROJECTS_DIR = 'projects';
+export const PROPOSALS_DIR = 'proposals';
+export function runsRoot(rootDir) {
+    return resolve(rootDir, process.env.SDODS_ARTIFACTS_DIR ?? RUNS_DIR);
+}
+export function projectRoot(rootDir, slug) {
+    const dir = resolve(rootDir, process.env.SDODS_PROJECTS_DIR ?? PROJECTS_DIR, slug);
+    if (!existsSync(join(dir, 'sdods.project.yaml'))) {
+        throw Object.assign(new Error(`Unknown project "${slug}" (no sdods.project.yaml under ${dir}).`), {
+            error: { code: 'PROJECT_NOT_FOUND' },
+        });
+    }
+    return dir;
+}
+export function readJson(file) {
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readYaml(file) {
+    if (!existsSync(file))
+        return undefined;
+    return parseYaml(readFileSync(file, 'utf8'));
+}
+/** Resolve `rel` inside `base`, refusing traversal outside it. */
+export function safeJoin(base, rel) {
+    const target = resolve(base, rel);
+    const relPath = relative(base, target);
+    if (relPath.startsWith('..') || relPath.includes(`..${sep}`) || resolve(target) !== target) {
+        throw Object.assign(new Error(`Path escapes ${base}: ${rel}`), {
+            error: { code: 'INVALID_ARGS' },
+        });
+    }
+    return target;
+}
+export function walk(dir, filter, max = 5000) {
+    const out = [];
+    const stack = [dir];
+    while (stack.length && out.length < max) {
+        const cur = stack.pop();
+        if (!existsSync(cur))
+            continue;
+        for (const name of readdirSync(cur)) {
+            if (name === 'node_modules' || name.startsWith('.') || name === 'dist')
+                continue;
+            const full = join(cur, name);
+            const st = statSync(full);
+            if (st.isDirectory())
+                stack.push(full);
+            else if (filter(full))
+                out.push(full);
+        }
+    }
+    return out.sort();
+}
+export function listRuns(rootDir, limit = 50) {
+    const root = runsRoot(rootDir);
+    if (!existsSync(root))
+        return [];
+    const entries = [];
+    for (const runId of readdirSync(root)) {
+        const dir = join(root, runId);
+        if (!statSync(dir).isDirectory())
+            continue;
+        entries.push({
+            runId,
+            dir,
+            manifest: readJson(join(dir, runFiles.manifest)),
+            summary: readJson(join(dir, runFiles.summary)),
+            mtime: statSync(dir).mtimeMs,
+        });
+    }
+    entries.sort((a, b) => b.mtime - a.mtime);
+    return entries.slice(0, limit);
+}
+export function getRun(rootDir, runId) {
+    const dir = join(runsRoot(rootDir), runId);
+    if (!existsSync(dir))
+        return undefined;
+    return {
+        runId,
+        dir,
+        manifest: readJson(join(dir, runFiles.manifest)),
+        summary: readJson(join(dir, runFiles.summary)),
+        mtime: statSync(dir).mtimeMs,
+    };
+}
+export function lastRun(rootDir) {
+    return listRuns(rootDir, 1)[0];
+}
+/** Walk `<runDir>/<slug>/<fingerprint>/r<retry>/` directories. */
+export function listScenarioDirs(runDir, slug) {
+    const out = [];
+    if (!existsSync(runDir))
+        return out;
+    const slugs = slug
+        ? [slug]
+        : readdirSync(runDir).filter((n) => !n.startsWith('.') &&
+            statSync(join(runDir, n)).isDirectory() &&
+            !['html-report', 'dashboard', 'runner-output', 'shard-reports', 'diff'].includes(n));
+    for (const s of slugs) {
+        const sDir = join(runDir, s);
+        if (!existsSync(sDir))
+            continue;
+        for (const fp of readdirSync(sDir)) {
+            const fpDir = join(sDir, fp);
+            if (!statSync(fpDir).isDirectory())
+                continue;
+            for (const r of readdirSync(fpDir)) {
+                const m = /^r(\d+)$/.exec(r);
+                if (!m)
+                    continue;
+                out.push(readScenarioDir(join(fpDir, r), fp, Number(m[1])));
+            }
+        }
+    }
+    return out;
+}
+export function readScenarioDir(dir, fingerprint, retry) {
+    const files = existsSync(dir) ? readdirSync(dir) : [];
+    const screenshots = [];
+    for (const f of files) {
+        const sc = /^scenario-(start|end|failure)\.png$/.exec(f);
+        if (sc)
+            screenshots.push({ file: f, phase: sc[1] });
+        const st = /^(\d{2})-(before|after)\.png$/.exec(f);
+        if (st)
+            screenshots.push({ file: f, phase: st[2], stepIndex: Number(st[1]) });
+    }
+    const apiSnapshots = [];
+    const apiDir = join(dir, 'api');
+    if (existsSync(apiDir)) {
+        for (const f of readdirSync(apiDir)) {
+            const m = /^(\d{2})-(\d+)-(request|response)\.json$/.exec(f);
+            if (!m)
+                continue;
+            apiSnapshots.push({
+                file: `api/${f}`,
+                stepIndex: Number(m[1]),
+                callIndex: Number(m[2]),
+                part: m[3],
+                body: readJson(join(apiDir, f)),
+            });
+        }
+    }
+    const healFile = join(dir, scenarioFiles.healLog);
+    const healEvents = existsSync(healFile)
+        ? readFileSync(healFile, 'utf8')
+            .split('\n')
+            .filter(Boolean)
+            .map((l) => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return undefined;
+            }
+        })
+            .filter(Boolean)
+        : [];
+    return {
+        fingerprint,
+        retry,
+        dir,
+        meta: readJson(join(dir, scenarioFiles.meta)),
+        screenshots: screenshots.sort((a, b) => (a.stepIndex ?? -1) - (b.stepIndex ?? -1)),
+        apiSnapshots: apiSnapshots.sort((a, b) => a.stepIndex - b.stepIndex || a.callIndex - b.callIndex),
+        healEvents,
+    };
+}
+export function screenshotUri(runId, fingerprint, retry, file) {
+    return `sdods://screenshot/${runId}/${fingerprint}/${retry}/${file}`;
+}
+//# sourceMappingURL=fs.js.map

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './registry/registry.js';
+export * from './registry/adapters.js';
+export * from './cli.js';
+export * from './fs.js';
+export * from './proposals.js';
+export * from './prompts/index.js';
+export * from './tools/index.js';
+export { parseGherkin, basicTagCheck, similarity } from './tools/feature.js';
+export { analyzeApp, analyzeCoverage, analyzeBestPractices, analyzeLocators, analyzeChangeImpact, } from './tools/analyze.js';
+export { nextCronTimes } from './tools/issue-schedule.js';
+export * from './server.js';
+export * from './transports/stdio.js';
+export * from './transports/http.js';
+export * from './install/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,15 @@
+export * from './registry/registry.js';
+export * from './registry/adapters.js';
+export * from './cli.js';
+export * from './fs.js';
+export * from './proposals.js';
+export * from './prompts/index.js';
+export * from './tools/index.js';
+export { parseGherkin, basicTagCheck, similarity } from './tools/feature.js';
+export { analyzeApp, analyzeCoverage, analyzeBestPractices, analyzeLocators, analyzeChangeImpact, } from './tools/analyze.js';
+export { nextCronTimes } from './tools/issue-schedule.js';
+export * from './server.js';
+export * from './transports/stdio.js';
+export * from './transports/http.js';
+export * from './install/index.js';
+//# sourceMappingURL=index.js.map

package/dist/install/index.d.ts

@@ -0,0 +1,46 @@
+export type McpClient = 'claude' | 'codex' | 'cursor' | 'vscode' | 'windsurf';
+export declare const MCP_CLIENTS: McpClient[];
+export interface SnippetOptions {
+    project?: string;
+    env?: string;
+    caps?: string;
+    /** when set, produce HTTP config instead of stdio */
+    httpUrl?: string;
+    tokenPlaceholder?: string;
+    /** command used to start the stdio server */
+    command?: string;
+    args?: string[];
+    withPlaywright?: boolean;
+}
+export declare function serverEntry(o: SnippetOptions, client: McpClient): Record<string, unknown>;
+export declare function playwrightEntry(): Record<string, unknown>;
+/** `codex mcp add` / `claude mcp add` command lines for the same configuration. */
+export declare function cliCommands(o: SnippetOptions): {
+    claude: string;
+    codex: string;
+};
+/** Codex keeps MCP servers in `~/.codex/config.toml` under `[mcp_servers.<name>]`. */
+export declare function codexTomlEntries(o: SnippetOptions): Record<string, Record<string, unknown>>;
+export declare function codexConfigPath(): string;
+export declare function snippets(o: SnippetOptions): Record<McpClient, {
+    file: string;
+    json?: Record<string, unknown>;
+    toml?: string;
+    cli?: string;
+}>;
+/** Write (merge) the client config file; never clobbers other servers. */
+export declare function installClientConfig(rootDir: string, client: McpClient, o: SnippetOptions): {
+    file: string;
+    merged: Record<string, unknown>;
+    created: boolean;
+};
+/**
+ * Merge `[mcp_servers.sdods]` (and playwright) into the Codex config, keeping every other
+ * table and server intact. Used when the `codex` CLI is not available to do it itself.
+ */
+export declare function installCodexConfig(o: SnippetOptions, file?: string): {
+    file: string;
+    merged: Record<string, unknown>;
+    created: boolean;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/install/index.js

@@ -0,0 +1,146 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+export const MCP_CLIENTS = ['claude', 'codex', 'cursor', 'vscode', 'windsurf'];
+function stdioArgs(o) {
+    const args = [...(o.args ?? ['sdods', 'mcp'])];
+    if (o.project)
+        args.push('--project', o.project);
+    if (o.env)
+        args.push('--env', o.env);
+    if (o.caps)
+        args.push('--caps', o.caps);
+    return args;
+}
+export function serverEntry(o, client) {
+    const token = o.tokenPlaceholder ?? (client === 'vscode' ? '${input:sdods-token}' : '<YOUR_SDODS_TOKEN>');
+    if (o.httpUrl) {
+        return { type: 'http', url: o.httpUrl, headers: { Authorization: `Bearer ${token}` } };
+    }
+    return { command: o.command ?? 'npx', args: stdioArgs(o) };
+}
+export function playwrightEntry() {
+    return { command: 'npx', args: ['playwright', 'mcp', '--headless'] };
+}
+/** `codex mcp add` / `claude mcp add` command lines for the same configuration. */
+export function cliCommands(o) {
+    const stdio = `${o.command ?? 'npx'} ${stdioArgs(o).join(' ')}`;
+    const token = o.tokenPlaceholder ?? '$SDODS_TOKEN';
+    return {
+        claude: o.httpUrl
+            ? `claude mcp add --transport http sdods ${o.httpUrl} --header "Authorization: Bearer ${token}"`
+            : `claude mcp add sdods -- ${stdio}`,
+        codex: o.httpUrl
+            ? `codex mcp add sdods --url ${o.httpUrl} --bearer-token-env-var SDODS_TOKEN`
+            : `codex mcp add sdods -- ${stdio}`,
+    };
+}
+/** Codex keeps MCP servers in `~/.codex/config.toml` under `[mcp_servers.<name>]`. */
+export function codexTomlEntries(o) {
+    const sdods = o.httpUrl
+        ? { url: o.httpUrl, bearer_token_env_var: 'SDODS_TOKEN' }
+        : { command: o.command ?? 'npx', args: stdioArgs(o) };
+    const out = { sdods };
+    if (o.withPlaywright !== false)
+        out.playwright = playwrightEntry();
+    return out;
+}
+export function codexConfigPath() {
+    return join(process.env.CODEX_HOME ?? join(homedir(), '.codex'), 'config.toml');
+}
+export function snippets(o) {
+    const pw = o.withPlaywright === false ? {} : { playwright: playwrightEntry() };
+    const cli = cliCommands(o);
+    return {
+        claude: {
+            file: '.mcp.json',
+            json: { mcpServers: { sdods: serverEntry(o, 'claude'), ...pw } },
+            cli: cli.claude,
+        },
+        codex: {
+            file: codexConfigPath(),
+            toml: stringifyToml({ mcp_servers: codexTomlEntries(o) }),
+            cli: cli.codex,
+        },
+        cursor: {
+            file: '.cursor/mcp.json',
+            json: { mcpServers: { sdods: serverEntry(o, 'cursor'), ...pw } },
+        },
+        windsurf: {
+            file: '.windsurf/mcp.json',
+            json: { mcpServers: { sdods: serverEntry(o, 'windsurf'), ...pw } },
+        },
+        vscode: {
+            file: '.vscode/mcp.json',
+            json: {
+                servers: { sdods: serverEntry(o, 'vscode'), ...pw },
+                ...(o.httpUrl
+                    ? {
+                        inputs: [
+                            {
+                                id: 'sdods-token',
+                                type: 'promptString',
+                                description: 'SDODS API token',
+                                password: true,
+                            },
+                        ],
+                    }
+                    : {}),
+            },
+        },
+    };
+}
+/** Write (merge) the client config file; never clobbers other servers. */
+export function installClientConfig(rootDir, client, o) {
+    if (client === 'codex')
+        return installCodexConfig(o);
+    const s = snippets(o)[client];
+    const file = join(rootDir, s.file);
+    const existing = existsSync(file) ? safeParse(readFileSync(file, 'utf8')) : {};
+    const merged = { ...existing };
+    const key = client === 'vscode' ? 'servers' : 'mcpServers';
+    merged[key] = {
+        ...(existing[key] ?? {}),
+        ...(s.json?.[key] ?? {}),
+    };
+    if (client === 'vscode' && s.json?.inputs) {
+        const inputs = (existing.inputs ?? []).filter((i) => i.id !== 'sdods-token');
+        merged.inputs = [...inputs, ...s.json.inputs];
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(merged, null, 2) + '\n');
+    return { file, merged, created: Object.keys(existing).length === 0 };
+}
+/**
+ * Merge `[mcp_servers.sdods]` (and playwright) into the Codex config, keeping every other
+ * table and server intact. Used when the `codex` CLI is not available to do it itself.
+ */
+export function installCodexConfig(o, file = codexConfigPath()) {
+    const existing = existsSync(file) ? safeParseToml(readFileSync(file, 'utf8')) : {};
+    const servers = {
+        ...(existing.mcp_servers ?? {}),
+        ...codexTomlEntries(o),
+    };
+    const merged = { ...existing, mcp_servers: servers };
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, stringifyToml(merged) + '\n');
+    return { file, merged, created: Object.keys(existing).length === 0 };
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+}
+function safeParseToml(text) {
+    try {
+        return parseToml(text);
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/prompts/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Role prompts shared by the MCP `prompts/*` surface and the SDODS agents.
+ * Kept as TypeScript strings so both packages import them without file I/O.
+ */
+export type RoleName = 'planner' | 'generator' | 'healer' | 'upgrader' | 'reviewer';
+export declare const CONVENTIONS = "# SDODS conventions (read first)\n\nSDODS is an automation and orchestration platform with a reusable architecture.\n\n- One project = `projects/<slug>/sdods.project.yaml` + `envs/<env>.yaml`; features live in `features/<module>/`.\n- Every scenario carries exactly one layer tag (@ui, @api, @hybrid) and exactly one suite tag (@smoke, @regression, @sanity).\n  Optional tags: @visual @a11y @perf @mock @data-driven @pool, value tags @user:<role> @data:<dataset> @har:<name> @jira:KEY @skip:<browser>.\n- Reuse existing steps first (call step_list / step_find). Add a new step only when no existing phrasing fits; name it in the same style.\n- Locator priority: role+name > label > test id (project testIdAttribute) > placeholder > text > CSS. Never XPath.\n- Page objects use step decorators (@Fixture, @Given/@When/@Then) and heal-aware locators (`this.heal.locator(primary, { role, name, testId, description })`).\n- Never write to the working tree: propose files with feature_write / proposal tools; a person reviews and accepts.\n- Keep scenarios independent, deterministic, and free of sleeps; prefer API seeding over UI setup; clean up created data.\n- Secrets are never literals; reference ${VAR}.\n- Stop when you run out of budget or turns and summarise what remains.";
+/** The rules that still apply when there is no room for the full conventions. */
+export declare const SMALL_CONVENTIONS = "SDODS rules:\n- Every Feature has one layer tag: @ui, @api or @hybrid.\n- Every Scenario has one suite tag: @smoke, @regression or @sanity.\n- Reuse an existing step pattern; never invent one.\n- You never edit files. feature_write creates a proposal a person reviews.\n- Call one tool per reply, with a single JSON object of arguments.";
+export declare const ROLE_PROMPTS: Record<RoleName, {
+    title: string;
+    description: string;
+    body: string;
+}>;
+/**
+ * Prompts for the small profile.
+ *
+ * The full conventions are 600 tokens of dense, multi-clause prose: a frontier model reads all of
+ * it, a 7B model follows the first two bullets and forgets the rest. These say one thing per line,
+ * name the tools in the order they should be called, and show one correct call — which is what the
+ * measured difference between a usable and a useless answer looked like.
+ */
+export declare const SMALL_MODEL_PROMPTS: Record<RoleName, string>;
+export interface PromptContext {
+    project?: string;
+    env?: string;
+    goal?: string;
+    steps?: string[];
+    extra?: string;
+    /** 'small' swaps the conventions and the role body for their short forms. */
+    profile?: 'full' | 'small';
+}
+export declare function renderPrompt(role: RoleName, ctx?: PromptContext): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/prompts/index.js

@@ -0,0 +1,151 @@
+export const CONVENTIONS = `# SDODS conventions (read first)
+
+SDODS is an automation and orchestration platform with a reusable architecture.
+
+- One project = \`projects/<slug>/sdods.project.yaml\` + \`envs/<env>.yaml\`; features live in \`features/<module>/\`.
+- Every scenario carries exactly one layer tag (@ui, @api, @hybrid) and exactly one suite tag (@smoke, @regression, @sanity).
+  Optional tags: @visual @a11y @perf @mock @data-driven @pool, value tags @user:<role> @data:<dataset> @har:<name> @jira:KEY @skip:<browser>.
+- Reuse existing steps first (call step_list / step_find). Add a new step only when no existing phrasing fits; name it in the same style.
+- Locator priority: role+name > label > test id (project testIdAttribute) > placeholder > text > CSS. Never XPath.
+- Page objects use step decorators (@Fixture, @Given/@When/@Then) and heal-aware locators (\`this.heal.locator(primary, { role, name, testId, description })\`).
+- Never write to the working tree: propose files with feature_write / proposal tools; a person reviews and accepts.
+- Keep scenarios independent, deterministic, and free of sleeps; prefer API seeding over UI setup; clean up created data.
+- Secrets are never literals; reference \${VAR}.
+- Stop when you run out of budget or turns and summarise what remains.`;
+/** The rules that still apply when there is no room for the full conventions. */
+export const SMALL_CONVENTIONS = `SDODS rules:
+- Every Feature has one layer tag: @ui, @api or @hybrid.
+- Every Scenario has one suite tag: @smoke, @regression or @sanity.
+- Reuse an existing step pattern; never invent one.
+- You never edit files. feature_write creates a proposal a person reviews.
+- Call one tool per reply, with a single JSON object of arguments.`;
+export const ROLE_PROMPTS = {
+    planner: {
+        title: 'SDODS planner',
+        description: 'Explore an application (or its source/OpenAPI) and produce a tagged test plan.',
+        body: `You are the SDODS PLANNER.
+
+Goal: produce \`docs/test-plans/<name>.md\` for the requested feature area.
+
+Method:
+1. Read the project config (project_get_config) and existing features (feature_list) to avoid duplicates.
+2. Explore the application: if a browser MCP is available, navigate the relevant routes and take ARIA snapshots; otherwise read source roots and the OpenAPI spec (analyze_project, analyze_routes).
+3. Write independent scenarios grouped by module. For each: title, preconditions, Gherkin steps (reuse step phrasing from step_list), the layer and suite tag, data needs (@data:/@user:), negative cases, and which existing steps already cover it.
+4. Include an "Out of scope / risks" section and an estimate of new steps needed.
+5. Save the plan through the proposal tools; do not modify features directly.`,
+    },
+    generator: {
+        title: 'SDODS generator',
+        description: 'Turn a plan, a goal, or a recorded spec into feature files, steps and page objects.',
+        body: `You are the SDODS GENERATOR.
+
+Goal: produce feature files (and only-when-needed steps and page objects) as a proposal.
+
+Rules:
+- Start with step_list; match every step you write to an existing pattern verbatim when one exists.
+- Feature files go under \`projects/<slug>/features/<module>/<name>.feature\` with one layer tag and one suite tag at Feature level plus the module tag.
+- Use Scenario Outline with a \`# title-format:\` comment for data-driven cases; prefer datasets (@data:) over inline literals for credentials.
+- New steps go to \`projects/<slug>/steps/<module>.steps.ts\` using the project's \`steps/fixtures.ts\` exports; new page objects to \`projects/<slug>/pages/<Name>Page.ts\` with decorators and heal-aware locators.
+- Validate with feature_parse and feature_lint before proposing. Run at most 3 scenarios with run_tests to verify; if they fail for environmental reasons, tag @fixme with a reason.
+- Output: one proposal with all files and a summary of what was reused vs added.`,
+    },
+    healer: {
+        title: 'SDODS healer',
+        description: 'Diagnose a failing scenario and propose the smallest locator/step fix.',
+        body: `You are the SDODS HEALER.
+
+Input: a run id and scenario fingerprint (run_get_scenario), the error, before/after screenshots, heal events and locator stats (heal_events, heal_locator_stats).
+
+Method:
+1. Classify the failure: locator changed, timing, data, environment, or a real product bug.
+2. For locator failures prefer role/label/test-id locators; use heal_events candidates that succeeded. Never loosen an assertion to make a test pass.
+3. If history shows the scenario flaky (alternating outcomes), propose a @flaky @retries:2 quarantine with a note instead of a code change.
+4. Propose the minimal patch (page object or step) via feature_write/proposal tools, then re-run only that scenario (run_tests with tags/scenario filter) at most 3 times.
+5. Report: root cause, change, verification result, and whether a product bug should be filed (issue_create when asked).`,
+    },
+    upgrader: {
+        title: 'SDODS upgrader',
+        description: 'Map code or API changes to affected scenarios and propose additions/updates.',
+        body: `You are the SDODS UPGRADER.
+
+Input: a project plus a git diff range or an OpenAPI old/new pair (analyze_change_impact, analyze_coverage).
+
+Method:
+1. Identify changed routes, components, endpoints and schemas.
+2. Map them to modules and existing features; list scenarios that need updating and gaps that need new scenarios.
+3. Propose updated/new feature files and data rows (datasets) as a proposal; never delete scenarios, mark deprecated ones with @fixme and a reason.
+4. Summarise coverage before/after and anything you could not map.`,
+    },
+    reviewer: {
+        title: 'SDODS reviewer',
+        description: 'Review feature files for tagging, reuse, data-driven refactors and best practices.',
+        body: `You are the SDODS REVIEWER.
+
+Input: feature files (feature_read/feature_parse), the step list and analyze_best_practices output.
+
+Produce a review with: tag-policy violations, duplicated or near-duplicate steps (suggest reuse), scenarios that should become a Scenario Outline with a dataset, missing @a11y/@visual/@perf coverage on key pages, brittle locators in page objects, hardcoded URLs or secrets, and ordering/independence problems. Offer concrete rewrites as a proposal when the change is mechanical.`,
+    },
+};
+/**
+ * Prompts for the small profile.
+ *
+ * The full conventions are 600 tokens of dense, multi-clause prose: a frontier model reads all of
+ * it, a 7B model follows the first two bullets and forgets the rest. These say one thing per line,
+ * name the tools in the order they should be called, and show one correct call — which is what the
+ * measured difference between a usable and a useless answer looked like.
+ */
+export const SMALL_MODEL_PROMPTS = {
+    planner: `You plan tests for SDODS. One tool call per reply, in this order:
+1. project_get_config({"project":"<slug>"}), then feature_list({"project":"<slug>"}).
+2. analyze_routes or analyze_coverage — find what is untested.
+3. feature_write — save the plan as docs/test-plans/<name>.md via extraFiles.
+Write scenarios as titles plus steps chosen from the step list below. Never invent a step.`,
+    generator: `You write Gherkin for SDODS. One tool call per reply, in this order:
+1. step_find({"project":"<slug>","phrase":"<what you are testing>"}) — pick patterns from the result.
+2. feature_parse({"project":"<slug>","text":"<your draft>"}) — fix whatever it reports.
+3. feature_write({"project":"<slug>","path":"<module>/<name>.feature","text":"<final text>"}).
+Rules:
+- The Feature line is preceded by exactly one layer tag (@ui, @api or @hybrid).
+- Every Scenario carries exactly one suite tag (@smoke, @regression or @sanity).
+- Only use step patterns from the list below. Never invent a step.
+Example call:
+feature_write({"project":"shop","path":"auth/login.feature","text":"@ui\nFeature: Login\n\n  @smoke\n  Scenario: Valid credentials\n    Given I am on the login page\n"})`,
+    healer: `You fix one failing SDODS scenario. One tool call per reply, in this order:
+1. analyze_failure — read the error.
+2. run_get_scenario or heal_events — see what the locator did.
+3. feature_read — read the file you intend to change.
+4. feature_write — propose the smallest possible change.
+Change one locator or one step. Do not rewrite the scenario. If the application is broken rather
+than the test, say so in the summary and write nothing.`,
+    upgrader: `You update SDODS tests after a code change. One tool call per reply, in this order:
+1. analyze_change_impact — which scenarios the change touches.
+2. feature_read — read one of them.
+3. feature_write — propose the update.
+Only change what the diff forces. Use step patterns from the list below.`,
+    reviewer: `You review SDODS feature files. One tool call per reply, in this order:
+1. feature_list({"project":"<slug>"}), then feature_read({"project":"<slug>","path":"<file>"}).
+2. analyze_best_practices and analyze_locators — get the findings.
+3. Write your review as text. Do not call feature_write unless asked to change something.
+Report: missing or duplicated tags, steps that could be reused, CSS locators that should be role
+or test-id locators. Be specific: name the file and the line.`,
+};
+export function renderPrompt(role, ctx = {}) {
+    const p = ROLE_PROMPTS[role];
+    const lines = ctx.profile === 'small'
+        ? [SMALL_CONVENTIONS, '', SMALL_MODEL_PROMPTS[role], '']
+        : [CONVENTIONS, '', p.body, ''];
+    if (ctx.project)
+        lines.push(`Project: ${ctx.project}${ctx.env ? ` · environment: ${ctx.env}` : ''}`);
+    if (ctx.goal)
+        lines.push(`Goal: ${ctx.goal}`);
+    if (ctx.steps?.length) {
+        const limit = ctx.profile === 'small' ? 60 : 400;
+        lines.push('', 'Existing step patterns (reuse these first):');
+        for (const s of ctx.steps.slice(0, limit))
+            lines.push(`- ${s}`);
+    }
+    if (ctx.extra)
+        lines.push('', ctx.extra);
+    return lines.join('\n');
+}
+//# sourceMappingURL=index.js.map

package/dist/proposals.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Proposals are the ONLY write path for agents and MCP write tools: files land under
+ * `proposals/<id>/files/<path>` with a manifest, and a person applies them.
+ */
+export type ProposalStatus = 'pending' | 'accepted' | 'rejected';
+export type ProposalFileOp = 'add' | 'modify' | 'delete';
+export interface ProposalFile {
+    path: string;
+    op: ProposalFileOp;
+    /** relative to the proposal dir; absent for delete */
+    from?: string;
+}
+export interface ProposalManifest {
+    id: string;
+    role: string;
+    project?: string;
+    env?: string;
+    createdAt: string;
+    status: ProposalStatus;
+    summary: string;
+    costUsd?: number;
+    model?: string;
+    files: ProposalFile[];
+    verification?: {
+        ranScenarios?: string[];
+        status?: 'passed' | 'failed' | 'not-run';
+        notes?: string;
+    };
+    reviewedAt?: string;
+    reviewedBy?: string;
+    appliedTo?: string;
+}
+export interface CreateProposalInput {
+    role: string;
+    project?: string;
+    env?: string;
+    summary: string;
+    files: Array<{
+        path: string;
+        content?: string;
+        op?: ProposalFileOp;
+    }>;
+    costUsd?: number;
+    model?: string;
+    verification?: ProposalManifest['verification'];
+}
+export declare class ProposalStore {
+    readonly rootDir: string;
+    readonly dir: string;
+    constructor(rootDir: string);
+    private manifestPath;
+    create(input: CreateProposalInput): ProposalManifest;
+    list(filter?: {
+        status?: ProposalStatus;
+        project?: string;
+    }): ProposalManifest[];
+    get(id: string): ProposalManifest | undefined;
+    readFile(id: string, file: ProposalFile): string | undefined;
+    /** Unified-ish diff for review (no external dependency). */
+    diff(id: string): string;
+    /** Apply to `targetRoot` (default: the repo). Returns the written paths. */
+    accept(id: string, opts?: {
+        targetRoot?: string;
+        reviewedBy?: string;
+    }): string[];
+    reject(id: string, reason?: string, reviewedBy?: string): ProposalManifest;
+    sizeOf(id: string): number;
+}
+/** Line-based diff with +/- markers (LCS on lines, adequate for review output). */
+export declare function simpleDiff(before: string, after: string): string;
+//# sourceMappingURL=proposals.d.ts.map