common-qa-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simplify3x
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# Common QA MCP
+
+One **product-neutral MCP** that AI clients (Claude Code, Cursor, Windsurf, …) connect to with a
+single URL + token, and which **routes** test-case-lifecycle requests to the right product:
+
+- **Walnut** — directly over its REST API (`WalnutAdapter`).
+- **SimplifyQA** — over the SimplifyQA agent's own MCP (`SimplifyQaAdapter`, an MCP client).
+
+The client sees **one tool vocabulary** and **one neutral data model** regardless of product.
+
+```
+AI client ──MCP (url + token)──▶  COMMON QA MCP  ──▶ Walnut backend (REST)
+                                        └────────▶ SimplifyQA agent MCP ──▶ SQA backend
+```
+
+## What's here
+This repo is the **standalone gateway** build of the neutral core: the API lifecycle surface —
+connection, projects, discovery, drafts, validation and save-orchestration. Files under `src/`:
+
+- `adapters/` — the `ProviderAdapter` contract + `walnut/` (REST) and `simplifyqa/` (remote MCP) drivers, and the adapter factory.
+- `connection.ts` / `requestConnection.ts` — the runtime connection (URL + token, in-memory, validate-before-adopt) and the header/URL-based config connection.
+- `domain/` — the neutral data model + validation.
+- `drafts/` — the edit-before-save draft store.
+- `tools/` — the client-facing tools: `connection.tools` (qa_connect / qa_switch_project / …), `discovery.tools` (list_projects / tc_list / tc_get), `testcase.tools` (tc_draft_*), plus `markdown` / `schemas`.
+- `server.ts` — assembles the MCP (`buildServer`).
+- `mount.ts` / `httpMain.ts` — the standalone Streamable-HTTP `/mcp` gateway + its entrypoint.
+- `vendor/` — three self-contained files vendored from the Walnut agent (`logger`, `actionSignatures`, `bridge`).
+
+> **Not here:** browser recording + the live editor. Those need a real browser/Electron window, so
+> they stay in the **Walnut agent**, which mounts this same core with those extra deps injected.
+
+## Install
+Nothing to install — AI clients launch it over stdio with `npx`. Requires Node >= 20.
+
+`.mcp.json` (Claude Code, Cursor, Windsurf, …):
+```json
+{
+  "mcpServers": {
+    "common-qa": {
+      "command": "npx",
+      "args": ["-y", "common-qa-mcp"],
+      "env": {
+        "QA_MCP_URL": "http://localhost:8080",
+        "QA_MCP_TOKEN": "<token>",
+        "QA_MCP_PROJECT_ID": "<projectId>"
+      }
+    }
+  }
+}
+```
+With no `QA_MCP_*` set it starts in **offline** mode — draft authoring only, zero network — and you
+can connect from chat with `qa_connect`.
+
+Install the Walnut QA agent (persona + tool guidance) into your project:
+```bash
+npx common-qa-mcp init-agents --loop=claude   # claude | cursor | windsurf | vscode | codex | all
+```
+
+## Develop
+```bash
+npm install
+npm run build         # tsc -> dist/
+npm start             # stdio server from dist/  (what npx runs)
+npm run dev           # same, via tsx, no build step
+npm run start:http    # HTTP gateway on http://127.0.0.1:4060/mcp  (override with PORT=)
+npm run dev:http      # HTTP gateway via tsx watch
+```
+
+## Connect an AI client over HTTP (config-based, no chat)
+`.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "common-qa": {
+      "type": "http",
+      "url": "http://127.0.0.1:4060/mcp",
+      "headers": {
+        "Authorization": "Bearer <token>",
+        "x-qa-product": "walnut",
+        "x-qa-url": "http://localhost:8080",
+        "x-project-id": "<projectId>"
+      }
+    }
+  }
+}
+```
+Switch `x-qa-product` to `simplifyqa` and point `x-qa-url` at the SimplifyQA agent's `/mcp` to route
+there instead. Everything after `Authorization` may also be passed as `?query` params, and falls
+back to the `QA_MCP_*` environment. At runtime, `qa_connect` / `qa_switch_project` override the
+connection without re-entering credentials.
+
+## SimplifyQA integration
+The SimplifyQA agent implements its own MCP exposing the provider-operation tools this gateway calls
+(`info`, `list_projects`, `list_testcases`, `get_testcase`, `create_testcase`, `update_testcase`,
+`start_run`, `get_run`, `stop_run`, …) returning the neutral shapes. See the integration guide for
+the full contract.

package/dist/adapters/factory.d.ts

@@ -0,0 +1,15 @@
+import type { ProviderAdapter } from './types.js';
+import type { QaConfig } from '../config.js';
+/**
+ * Builds the adapter for the current connection.
+ *
+ * In the Common QA MCP, BOTH products are reached the SAME way: a remote MCP hop to that product's
+ * agent MCP (`config.url` = its `/mcp` endpoint), forwarding the neutral provider-op calls. So there
+ * is a single driver -- `RemoteMcpAdapter` -- regardless of `provider`; the product is just a label
+ * for routing/logging. The Common MCP no longer talks any product's REST directly (the Walnut REST
+ * logic now lives in the Walnut MCP / walnut-agent, exactly like SQA's lives in the SQA MCP).
+ *
+ * Offline mode (no credentials) builds nothing -- draft authoring needs no backend.
+ */
+export declare function createAdapter(config: QaConfig): ProviderAdapter | null;
+//# sourceMappingURL=factory.d.ts.map

package/dist/adapters/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/adapters/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAG7C;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,GAAG,IAAI,CAGtE"}

package/dist/adapters/factory.js

@@ -0,0 +1,18 @@
+import { RemoteMcpAdapter } from './remoteMcp/adapter.js';
+/**
+ * Builds the adapter for the current connection.
+ *
+ * In the Common QA MCP, BOTH products are reached the SAME way: a remote MCP hop to that product's
+ * agent MCP (`config.url` = its `/mcp` endpoint), forwarding the neutral provider-op calls. So there
+ * is a single driver -- `RemoteMcpAdapter` -- regardless of `provider`; the product is just a label
+ * for routing/logging. The Common MCP no longer talks any product's REST directly (the Walnut REST
+ * logic now lives in the Walnut MCP / walnut-agent, exactly like SQA's lives in the SQA MCP).
+ *
+ * Offline mode (no credentials) builds nothing -- draft authoring needs no backend.
+ */
+export function createAdapter(config) {
+    if (config.mode !== 'connected')
+        return null;
+    return new RemoteMcpAdapter(config);
+}
+//# sourceMappingURL=factory.js.map

package/dist/adapters/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/adapters/factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,MAAgB;IAC5C,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC"}

package/dist/adapters/remoteMcp/adapter.d.ts

@@ -0,0 +1,92 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ConnectedQaConfig } from '../../config.js';
+import type { ProjectInfo, ProviderAdapter } from '../types.js';
+import type { ActionDef, CloudRunner, DatasetInfo, EntityRef, EnvInfo, JournalOp, JournalView, MemberOp, ObjectQuery, ProjectSummary, QaObject, RunOptions, RunRef, RunStatus, RunTarget, SavedRef, Story, StoryQuery, StorySummary, Suite, SuiteSummary, TcQuery, TcSummary, TestCase } from '../../domain/types.js';
+/**
+ * RemoteMcpAdapter -- the generic "forward to a product MCP" driver of the Common QA MCP.
+ *
+ * BOTH products are reached the same way: a thin MCP CLIENT holds a connection to the product's
+ * agent MCP (`cfg.url` = that product's `/mcp` endpoint) and fulfils each neutral ProviderAdapter
+ * method by calling the correspondingly-named PROVIDER-OP tool on it (info -> `info`, listTestCases
+ * -> `list_testcases`, ...), reading the neutral payload out of `structuredContent[<key>]`. This is
+ * the provider-op contract in docs/sqa-agent-mcp-integration-guide.md -- the SAME for the Walnut MCP
+ * and the product MCP, so the Common MCP forwards to both identically.
+ *
+ * The bearer token (+ x-project-id) is forwarded to the product MCP on every request. The client
+ * connects lazily on first use (and re-arms on failure), so constructing the adapter is cheap.
+ */
+export type RemoteTransportFactory = () => Transport;
+export declare class RemoteMcpAdapter implements ProviderAdapter {
+    private readonly cfg;
+    /** Test seam: inject a pre-linked in-memory transport instead of a real HTTP one. */
+    private readonly transportFactory?;
+    private clientPromise;
+    constructor(cfg: ConnectedQaConfig, 
+    /** Test seam: inject a pre-linked in-memory transport instead of a real HTTP one. */
+    transportFactory?: RemoteTransportFactory | undefined);
+    private headers;
+    private client;
+    /**
+     * callTool with transparent ONE-shot reconnect on a stale session. If the product MCP was
+     * restarted, our cached client holds a dead session id and the first call throws "Session not
+     * found"; we drop the client so `client()` re-connects fresh, then retry exactly once. Any other
+     * error (or a second failure) propagates. Without this, every call after a product restart failed
+     * until THIS process was restarted too.
+     */
+    private callTool;
+    /** Project-scoped provider-ops need a selected project. `list_projects` is the ONE exception (it
+     *  lists ACROSS projects, so it must work with none selected). Guarding here turns an opaque backend
+     *  400 ("Project ID and User ID are required") into a clear instruction so the AI client asks the
+     *  user to pick a project first. */
+    private assertProject;
+    /** Call a remote provider-op tool and pull the neutral payload from structuredContent[key]. */
+    private call;
+    /** For void ops (delete/stop): only surface an error, ignore any payload. */
+    private callVoid;
+    info(): Promise<ProjectInfo>;
+    listProjects(): Promise<ProjectSummary[]>;
+    listTestCases(q: TcQuery): Promise<TcSummary[]>;
+    getTestCase(id: string): Promise<TestCase>;
+    createTestCase(tc: TestCase): Promise<SavedRef>;
+    updateTestCase(id: string, tc: TestCase): Promise<SavedRef>;
+    deleteTestCase(id: string): Promise<void>;
+    cloneTestCase(id: string, title?: string): Promise<SavedRef>;
+    searchObjects(q: ObjectQuery): Promise<QaObject[]>;
+    createObject(o: QaObject): Promise<QaObject>;
+    actionsCatalog(platform?: string): Promise<ActionDef[]>;
+    listSuites(): Promise<SuiteSummary[]>;
+    getSuite(id: string): Promise<Suite>;
+    listStories(q: StoryQuery): Promise<StorySummary[]>;
+    getStory(id: string): Promise<Story>;
+    readJournal(tcId: string): Promise<JournalView>;
+    editJournal(tcId: string, ops: JournalOp[]): Promise<JournalView>;
+    createSuite(s: Suite): Promise<SavedRef>;
+    updateSuiteMembers(id: string, ops: MemberOp[]): Promise<Suite>;
+    deleteSuite(id: string): Promise<void>;
+    startRun(target: RunTarget, opts: RunOptions): Promise<RunRef>;
+    getRun(runId: string): Promise<RunStatus>;
+    stopRun(runId: string): Promise<void>;
+    listCloudRunners(): Promise<CloudRunner[]>;
+    /**
+     * Raw passthrough: forward a tool call to the product MCP verbatim and return its CallToolResult.
+     * For AGENT-BOUND tools (recording/browser) the Common MCP proxies rather than wraps -- it cannot
+     * implement them (they need the product's real browser), so it relays the call and the result.
+     * Stale-session resilient via `callTool`.
+     */
+    callRaw(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    /** The product MCP's advertised tools (name + description + inputSchema), for building passthrough
+     *  proxies of its agent-bound surface. The inputSchema is mirrored so the client's model knows each
+     *  tool's real parameters (ref/object_name/expected/value/…) instead of guessing against a
+     *  permissive schema. */
+    listAgentTools(): Promise<Array<{
+        name: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+    }>>;
+    listEnvironments(): Promise<EnvInfo[]>;
+    listDatasets(tcId?: string): Promise<DatasetInfo[]>;
+    getObject(id: string): Promise<QaObject>;
+    productUrlFor(entity: EntityRef): string;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapters/remoteMcp/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/remoteMcp/adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/remoteMcp/adapter.js

@@ -0,0 +1,219 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+function firstText(res) {
+    const content = res.content;
+    return content?.find((c) => c?.type === 'text')?.text ?? '';
+}
+/**
+ * True when a call failed because the product MCP's SESSION is gone -- almost always because that
+ * process was restarted (e.g. an agent rebuild), which invalidates the session id our cached client
+ * holds. The Streamable-HTTP transport surfaces this as a -32001 "Session not found" while POSTing.
+ * We treat it as "reconnect and retry once", NOT a real failure.
+ */
+function isStaleSession(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return /session not found|-32001/i.test(msg);
+}
+export class RemoteMcpAdapter {
+    constructor(cfg, 
+    /** Test seam: inject a pre-linked in-memory transport instead of a real HTTP one. */
+    transportFactory) {
+        this.cfg = cfg;
+        this.transportFactory = transportFactory;
+        this.clientPromise = null;
+    }
+    // Bearer token forwarded unchanged to the product MCP; x-project-id only when we have one (a key is
+    // project-scoped server-side, so it may be absent). Mirrors the guide's auth section.
+    headers() {
+        const h = { Authorization: `Bearer ${this.cfg.token}` };
+        if (this.cfg.projectId)
+            h['x-project-id'] = this.cfg.projectId;
+        return h;
+    }
+    async client() {
+        if (!this.clientPromise) {
+            this.clientPromise = (async () => {
+                const client = new Client({ name: 'common-qa-mcp', version: '0.1.0' });
+                // The `as Transport` cast bridges exactOptionalPropertyTypes: StreamableHTTPClientTransport
+                // implements Transport, but the SDK's own .d.ts (built without EOPT) leaves its optional
+                // callbacks (onclose?/onerror?/onmessage?) without `| undefined`, which this project's EOPT
+                // rejects on assignment. The class genuinely satisfies the interface at runtime.
+                const transport = this.transportFactory
+                    ? this.transportFactory()
+                    : new StreamableHTTPClientTransport(new URL(this.cfg.url), { requestInit: { headers: this.headers() } });
+                await client.connect(transport);
+                return client;
+            })().catch((e) => {
+                // Re-arm so the next call retries instead of reusing a rejected promise forever.
+                this.clientPromise = null;
+                throw e instanceof Error
+                    ? new Error(`Could not reach the product MCP at ${this.cfg.url}: ${e.message}`)
+                    : e;
+            });
+        }
+        return this.clientPromise;
+    }
+    /**
+     * callTool with transparent ONE-shot reconnect on a stale session. If the product MCP was
+     * restarted, our cached client holds a dead session id and the first call throws "Session not
+     * found"; we drop the client so `client()` re-connects fresh, then retry exactly once. Any other
+     * error (or a second failure) propagates. Without this, every call after a product restart failed
+     * until THIS process was restarted too.
+     */
+    async callTool(name, args) {
+        try {
+            return await (await this.client()).callTool({ name, arguments: args });
+        }
+        catch (e) {
+            if (!isStaleSession(e))
+                throw e;
+            this.clientPromise = null; // discard the dead session; client() mints a new one
+            return await (await this.client()).callTool({ name, arguments: args });
+        }
+    }
+    /** Project-scoped provider-ops need a selected project. `list_projects` is the ONE exception (it
+     *  lists ACROSS projects, so it must work with none selected). Guarding here turns an opaque backend
+     *  400 ("Project ID and User ID are required") into a clear instruction so the AI client asks the
+     *  user to pick a project first. */
+    assertProject(op) {
+        if (!this.cfg.projectId && op !== 'list_projects') {
+            throw new Error('No project selected. Call list_projects to see the available projects, then ' +
+                'qa_switch_project({ projectId }) to choose one — test cases, runs and objects are all ' +
+                'scoped to a project.');
+        }
+    }
+    /** Call a remote provider-op tool and pull the neutral payload from structuredContent[key]. */
+    async call(name, args, key) {
+        this.assertProject(name);
+        const res = await this.callTool(name, args);
+        if (res.isError) {
+            throw new Error(firstText(res) || `product MCP tool "${name}" returned an error.`);
+        }
+        const sc = res.structuredContent;
+        if (!sc || !(key in sc)) {
+            throw new Error(`product MCP tool "${name}" did not return structuredContent.${key}.`);
+        }
+        return sc[key];
+    }
+    /** For void ops (delete/stop): only surface an error, ignore any payload. */
+    async callVoid(name, args) {
+        this.assertProject(name);
+        const res = await this.callTool(name, args);
+        if (res.isError) {
+            throw new Error(firstText(res) || `product MCP tool "${name}" returned an error.`);
+        }
+    }
+    async info() {
+        return this.call('info', {}, 'info');
+    }
+    async listProjects() {
+        return this.call('list_projects', {}, 'projects');
+    }
+    async listTestCases(q) {
+        return this.call('list_testcases', q, 'testCases');
+    }
+    async getTestCase(id) {
+        return this.call('get_testcase', { id }, 'tc');
+    }
+    async createTestCase(tc) {
+        return this.call('create_testcase', { tc }, 'saved');
+    }
+    async updateTestCase(id, tc) {
+        return this.call('update_testcase', { id, tc }, 'saved');
+    }
+    async deleteTestCase(id) {
+        await this.callVoid('delete_testcase', { id });
+    }
+    async cloneTestCase(id, title) {
+        return this.call('clone_testcase', { id, ...(title !== undefined ? { title } : {}) }, 'saved');
+    }
+    async searchObjects(q) {
+        return this.call('search_objects', q, 'objects');
+    }
+    async createObject(o) {
+        return this.call('create_object', { object: o }, 'object');
+    }
+    async actionsCatalog(platform) {
+        return this.call('actions_catalog', platform !== undefined ? { platform } : {}, 'actions');
+    }
+    async listSuites() {
+        return this.call('list_suites', {}, 'suites');
+    }
+    async getSuite(id) {
+        return this.call('get_suite', { id }, 'suite');
+    }
+    async listStories(q) {
+        return this.call('list_stories', q, 'stories');
+    }
+    async getStory(id) {
+        return this.call('get_story', { id }, 'story');
+    }
+    async readJournal(tcId) {
+        return this.call('read_journal', { id: tcId }, 'view');
+    }
+    async editJournal(tcId, ops) {
+        return this.call('edit_journal', { id: tcId, ops }, 'view');
+    }
+    async createSuite(s) {
+        return this.call('create_suite', { suite: s }, 'saved');
+    }
+    async updateSuiteMembers(id, ops) {
+        return this.call('update_suite_members', { id, ops }, 'suite');
+    }
+    async deleteSuite(id) {
+        await this.callVoid('delete_suite', { id });
+    }
+    // Execution forwards to the product MCP's own run ops (start_run / get_run / stop_run). For
+    // SimplifyQA those are agent MCP tools; the gateway stays product-neutral and just relays.
+    async startRun(target, opts) {
+        return this.call('start_run', { target, options: opts }, 'run');
+    }
+    async getRun(runId) {
+        return this.call('get_run', { runId }, 'run');
+    }
+    async stopRun(runId) {
+        await this.callVoid('stop_run', { runId });
+    }
+    async listCloudRunners() {
+        return this.call('list_cloud_runners', {}, 'runners');
+    }
+    /**
+     * Raw passthrough: forward a tool call to the product MCP verbatim and return its CallToolResult.
+     * For AGENT-BOUND tools (recording/browser) the Common MCP proxies rather than wraps -- it cannot
+     * implement them (they need the product's real browser), so it relays the call and the result.
+     * Stale-session resilient via `callTool`.
+     */
+    async callRaw(name, args) {
+        return (await this.callTool(name, args));
+    }
+    /** The product MCP's advertised tools (name + description + inputSchema), for building passthrough
+     *  proxies of its agent-bound surface. The inputSchema is mirrored so the client's model knows each
+     *  tool's real parameters (ref/object_name/expected/value/…) instead of guessing against a
+     *  permissive schema. */
+    async listAgentTools() {
+        const client = await this.client();
+        const res = await client.listTools();
+        return res.tools.map((t) => ({
+            name: t.name,
+            ...(t.description ? { description: t.description } : {}),
+            ...(t.inputSchema ? { inputSchema: t.inputSchema } : {}),
+        }));
+    }
+    async listEnvironments() {
+        return this.call('list_environments', {}, 'environments');
+    }
+    async listDatasets(tcId) {
+        return this.call('list_datasets', tcId !== undefined ? { tcId } : {}, 'datasets');
+    }
+    async getObject(id) {
+        return this.call('get_object', { id }, 'object');
+    }
+    // Deep link into the SimplifyQA UI. The AUTHORITATIVE link comes from SavedRef.productUrl (returned
+    // by create/update); this synchronous fallback is best-effort off the MCP endpoint origin -- it
+    // cannot round-trip to the remote, so callers should prefer SavedRef.productUrl when they have it.
+    productUrlFor(entity) {
+        const base = this.cfg.url.replace(/\/+$/, '').replace(/\/mcp$/i, '');
+        return `${base}/${entity.kind}/${entity.id}`;
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapters/remoteMcp/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/adapters/remoteMcp/adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/types.d.ts

@@ -0,0 +1,77 @@
+import type { ActionDef, CloudRunner, DatasetInfo, EntityRef, EnvInfo, JournalOp, JournalView, MemberOp, ObjectQuery, ProjectSummary, QaObject, RunOptions, RunRef, RunStatus, RunTarget, SavedRef, Story, StoryQuery, StorySummary, Suite, SuiteSummary, TcQuery, TcSummary, TestCase } from '../domain/types.js';
+export type ProjectInfo = {
+    provider: 'walnut' | 'simplifyqa';
+    projectId: string;
+    projectName: string;
+    counts?: Record<string, number> | undefined;
+};
+/**
+ * Full adapter contract (design spec §5, ~20 methods). Tools and the UI see only this
+ * neutral surface -- WalnutAdapter (Tasks 5-6) and SimplifyQaAdapter (Tasks 11-12) each
+ * implement it against their own REST API via a QaHttp client (src/adapters/http.ts).
+ * Optional methods (`?`) are genuinely optional per product (e.g. `cloneTestCase` is
+ * native on Walnut but a get+create composite on SQA; `listDatasets`/`getObject` are
+ * walnut-first / migration-only) -- callers must treat their absence as "not supported
+ * by this provider", not as a bug.
+ */
+export interface ProviderAdapter {
+    /** Validates url+token+project. */
+    info(): Promise<ProjectInfo>;
+    /** Projects visible to the connected token -- for name→id resolution and browsing. */
+    listProjects(): Promise<ProjectSummary[]>;
+    listTestCases(q: TcQuery): Promise<TcSummary[]>;
+    /** Neutral, steps included. */
+    getTestCase(id: string): Promise<TestCase>;
+    createTestCase(tc: TestCase): Promise<SavedRef>;
+    /** Full-doc semantics. */
+    updateTestCase(id: string, tc: TestCase): Promise<SavedRef>;
+    deleteTestCase(id: string): Promise<void>;
+    /** Walnut native; SQA = get+create. */
+    cloneTestCase?(id: string, title?: string): Promise<SavedRef>;
+    searchObjects(q: ObjectQuery): Promise<QaObject[]>;
+    createObject(o: QaObject): Promise<QaObject>;
+    /** Valid action vocabulary per technology (cached by the caller). */
+    actionsCatalog(platform?: string): Promise<ActionDef[]>;
+    /** Walnut-only: the recording-JOURNAL view of a test case (steps derived from its journal seed,
+     *  or the persisted steps when no seed exists) — the read side of journal-first editing. Absent on
+     *  providers with no recording journal. */
+    readJournal?(tcId: string): Promise<JournalView>;
+    /** Walnut-only: apply granular modify ops (add/remove/update/move step, wrap in loop/if, insert
+     *  nested) to a test case and persist — the write side of journal-first editing. */
+    editJournal?(tcId: string, ops: JournalOp[]): Promise<JournalView>;
+    listSuites(): Promise<SuiteSummary[]>;
+    getSuite(id: string): Promise<Suite>;
+    createSuite(s: Suite): Promise<SavedRef>;
+    updateSuiteMembers(id: string, ops: MemberOp[]): Promise<Suite>;
+    deleteSuite(id: string): Promise<void>;
+    /** USER STORIES — read side of story-driven authoring (list + read-with-AC). `getStory` accepts a
+     *  Mongo _id or a US_/Jira business key. Optional: only products with a story backlog implement them. */
+    listStories?(q: StoryQuery): Promise<StorySummary[]>;
+    getStory?(id: string): Promise<Story>;
+    startRun(target: RunTarget, opts: RunOptions): Promise<RunRef>;
+    /** Per-step results when terminal. */
+    getRun(runId: string): Promise<RunStatus>;
+    stopRun(runId: string): Promise<void>;
+    /** Cloud runner VMs registered to the project, with online status. Optional: only products with a
+     *  cloud-execution fabric implement it; absence = "this provider has no cloud runners". */
+    listCloudRunners?(): Promise<CloudRunner[]>;
+    /** Passthrough for AGENT-BOUND tools (recording/browser) the Common MCP proxies rather than wraps.
+     *  Only the remote-MCP forwarder implements these; `unknown` is a CallToolResult (kept SDK-free
+     *  here). */
+    callRaw?(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /** The product MCP's advertised tools (name + description + inputSchema), for building those proxies
+     *  with the real per-tool parameter schema mirrored to the client. */
+    listAgentTools?(): Promise<Array<{
+        name: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+    }>>;
+    listEnvironments(): Promise<EnvInfo[]>;
+    /** Walnut-first. */
+    listDatasets?(tcId?: string): Promise<DatasetInfo[]>;
+    /** Full locator bag; needed by migration (§7A). */
+    getObject?(id: string): Promise<QaObject>;
+    /** Deep link into product UI. */
+    productUrlFor(entity: EntityRef): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"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"}

package/dist/adapters/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":""}

package/dist/adapters/walnut/actionTypes.d.ts

@@ -0,0 +1,16 @@
+import type { ActionDef, Step } from '../../domain/types.js';
+export type WalnutPlatform = 'web' | 'android' | 'api' | 'database' | 'mainframe';
+export declare const WALNUT_ACTIONS: Record<WalnutPlatform, string[]>;
+/** Flattens a per-platform action-type catalog into `ActionDef[]`, tagging every entry. */
+export declare function actionDefsFrom(catalog: Record<WalnutPlatform, string[]>): ActionDef[];
+/**
+ * The single shared `catalogFor` callback every offline draft tool passes to
+ * `validateTestCase` -- no network, no adapter, just the static WALNUT_ACTIONS
+ * table above. Maps a neutral `Step.stepType` to its WALNUT_ACTIONS bucket;
+ * `control_flow` is exempted by `validateTestCase` itself before this is ever
+ * consulted, and a stepType with no offline vocabulary (`function`) yields an
+ * empty Set, which `validateTestCase` treats as "nothing to check" rather than
+ * "nothing is valid".
+ */
+export declare function offlineCatalogFor(step: Step): Set<string>;
+//# sourceMappingURL=actionTypes.d.ts.map

package/dist/adapters/walnut/actionTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionTypes.d.ts","sourceRoot":"","sources":["../../../src/adapters/walnut/actionTypes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAG7D,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,UAAU,GAAG,WAAW,CAAC;AAsElF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,CAqD3D,CAAC;AAEF,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,EAAE,CAIrF;AAQD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAEzD"}