cgraphx 1.2.0 → 1.3.1

package/dist/.claude-template/skills/write-api/references/interface-scope.md

@@ -0,0 +1,74 @@
+# S1 接口范围识别规范
+
+## 三级优先级
+
+按以下顺序识别需求要测的接口:
+
+1. **用户显式给** — 文件列表 / 路由前缀 / handler 函数名 / 接口路径
+2. **spec 的接口章节** — 从 `docs/features/<feature-id>/<文件前缀>-spec.md` 提取
+3. **git diff 自动提取** — 本次 feature 改动新增的路由注册点
+
+优先级高的命中就用高的,不向下降级混合使用(避免范围漂移)。用户显式给就只测用户给的;用户没给才查 spec;spec 也没有才扫 git diff。
+
+git diff 失效(改动已合并 / 事后补测)不是问题,靠优先级 1/2 自然处理。
+
+## 用户确认(必须)
+
+无论哪种来源拿到接口清单,**必须显示给用户确认**:
+
+```
+本次识别到的接口范围(来自:用户显式给 / spec 接口章节 / git diff):
+| 方法 | 路径 | handler | 是否写接口 |
+| ... | ... | ... | ... |
+
+确认这是你要测的范围?回车继续,或 Ctrl+C 取消。
+```
+
+**为什么必须确认**:AI 可能理解偏差,测错接口会浪费 S2/S3 的生成时间。用户一眼确认最稳。
+
+## 结果格式
+
+接口清单每条含:
+
+| 字段 | 说明 |
+|---|---|
+| 方法 | GET / POST / PUT / DELETE / PATCH |
+| 路径 | 如 `/api/v1/users/:id` |
+| handler | 函数全名,如 `UserController.getUser` |
+| 是否写接口 | POST/PUT/DELETE/PATCH = 是;GET = 否 |
+
+"是否写接口"决定 .bru 是否需要写 DB 副作用预期注释(见 `bru-format.md`),以及下游 `/run-api-test` 是否对它做 DB 核实。
+
+## 边界情况
+
+| 情况 | 处理 |
+|---|---|
+| 三种来源都拿不到接口 | 报"未识别到接口范围,请显式给接口清单或确认 spec 接口章节完整"并退出 |
+| spec 无接口章节且用户未显式给 | 报"spec 无接口章节,请显式给接口范围"并退出 |
+| 用户给的接口列表里有修改的老接口 | 跳过修改的老接口,只保留新增的;在测试规格 §4 标注哪些被跳过 |
+| git diff 扫到的路由注册点在 spec 里没有声明 | 仍纳入接口清单,但在测试规格 §4 标注"代码命中但 spec 未声明,需用户确认" |
+| 同一接口在多个来源里都出现 | 按优先级 1 取用户显式给为准,去重 |
+
+
+
+## 结果格式
+
+接口清单每条含:
+
+| 字段 | 说明 |
+|---|---|
+| 方法 | GET / POST / PUT / DELETE / PATCH |
+| 路径 | 如 `/api/v1/users/:id` |
+| handler | 函数全名,如 `UserController.getUser` |
+| 是否写接口 | POST/PUT/DELETE/PATCH = 是;GET = 否 |
+
+"是否写接口"决定 .bru 是否需要写 DB 副作用预期注释(见 `bru-format.md`),以及下游 `/run-api-test` 是否对它做 DB 核实。
+
+## 边界情况
+
+| 情况 | 处理 |
+|---|---|
+| 本次 feature 无新增接口 | 报"未检测到新增接口"并退出,不生成空产物 |
+| 用户给的接口列表里有修改的老接口 | 跳过修改的老接口,只保留新增的;在测试规格 §4 标注哪些被跳过 |
+| git diff 扫到的路由注册点在 spec 里没有声明 | 仍纳入接口清单,但在测试规格 §4 标注"代码命中但 spec 未声明,需用户确认是否本次新增" |
+| 同一接口在 git diff 和用户显式给里都出现 | 按优先级 1 取用户显式给为准,去重 |

package/dist/api-test/ai-fields.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AI-inferred fields persistence (L-T-10).
+ *
+ * `enhance-prepare` reads any previously-written AI fields so a re-run keeps
+ * the AI's prior inference unless the human regenerates it. `enhance-write`
+ * (L-T-20) writes this file after the AI infers fields.
+ *
+ * Storage: `.cgraphx/api-test/ai-fields/<endpoint>.json` where `<endpoint>`
+ * is the .md filename stem (`<svc_id>_<method>`). One file per endpoint so
+ * partial reruns only touch their own file.
+ *
+ * Independent subsystem — only depends on `node:fs`/`node:path` and the
+ * `AiFields` / `Field` types.
+ */
+import type { AiFields, Field } from './types';
+/** Subdir under `.cgraphx/api-test/` holding the per-endpoint JSON files. */
+export declare const AI_FIELDS_SUBDIR = "ai-fields";
+/**
+ * Resolve the JSON path for an endpoint: `<projectRoot>/.cgraphx/api-test/
+ * ai-fields/<endpoint>.json`.
+ */
+export declare function aiFieldsFilePath(projectRoot: string, endpoint: string): string;
+/**
+ * Read previously-persisted AI fields for `endpoint`. Returns `null` when the
+ * file doesn't exist or can't be parsed (treat as "no prior inference").
+ */
+export declare function readAiFields(projectRoot: string, endpoint: string): AiFields | null;
+/**
+ * Persist AI-inferred fields for `endpoint`. Creates the parent directory if
+ * needed. `updatedAt` is stamped with the current ISO timestamp.
+ */
+export declare function writeAiFields(projectRoot: string, endpoint: string, fields: Field[]): void;
+/** Internal helpers re-exported for tests. */
+export declare const __INTERNAL_AI_FIELDS: {
+    AI_FIELDS_SUBDIR: string;
+};
+//# sourceMappingURL=ai-fields.d.ts.map

package/dist/api-test/ai-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-fields.d.ts","sourceRoot":"","sources":["../../src/api-test/ai-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAE/C,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CA0BnF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAS1F;AAED,8CAA8C;AAC9C,eAAO,MAAM,oBAAoB;;CAEhC,CAAC"}

package/dist/api-test/ai-fields.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * AI-inferred fields persistence (L-T-10).
+ *
+ * `enhance-prepare` reads any previously-written AI fields so a re-run keeps
+ * the AI's prior inference unless the human regenerates it. `enhance-write`
+ * (L-T-20) writes this file after the AI infers fields.
+ *
+ * Storage: `.cgraphx/api-test/ai-fields/<endpoint>.json` where `<endpoint>`
+ * is the .md filename stem (`<svc_id>_<method>`). One file per endpoint so
+ * partial reruns only touch their own file.
+ *
+ * Independent subsystem — only depends on `node:fs`/`node:path` and the
+ * `AiFields` / `Field` types.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__INTERNAL_AI_FIELDS = exports.AI_FIELDS_SUBDIR = void 0;
+exports.aiFieldsFilePath = aiFieldsFilePath;
+exports.readAiFields = readAiFields;
+exports.writeAiFields = writeAiFields;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Subdir under `.cgraphx/api-test/` holding the per-endpoint JSON files. */
+exports.AI_FIELDS_SUBDIR = 'ai-fields';
+/**
+ * Resolve the JSON path for an endpoint: `<projectRoot>/.cgraphx/api-test/
+ * ai-fields/<endpoint>.json`.
+ */
+function aiFieldsFilePath(projectRoot, endpoint) {
+    return path.join(projectRoot, '.cgraphx', 'api-test', exports.AI_FIELDS_SUBDIR, `${endpoint}.json`);
+}
+/**
+ * Read previously-persisted AI fields for `endpoint`. Returns `null` when the
+ * file doesn't exist or can't be parsed (treat as "no prior inference").
+ */
+function readAiFields(projectRoot, endpoint) {
+    const file = aiFieldsFilePath(projectRoot, endpoint);
+    let content;
+    try {
+        content = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            typeof parsed.endpoint !== 'string' ||
+            !Array.isArray(parsed.fields)) {
+            return null;
+        }
+        return {
+            endpoint: parsed.endpoint,
+            fields: parsed.fields,
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist AI-inferred fields for `endpoint`. Creates the parent directory if
+ * needed. `updatedAt` is stamped with the current ISO timestamp.
+ */
+function writeAiFields(projectRoot, endpoint, fields) {
+    const file = aiFieldsFilePath(projectRoot, endpoint);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const payload = {
+        endpoint,
+        fields,
+        updatedAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(file, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+}
+/** Internal helpers re-exported for tests. */
+exports.__INTERNAL_AI_FIELDS = {
+    AI_FIELDS_SUBDIR: exports.AI_FIELDS_SUBDIR,
+};
+//# sourceMappingURL=ai-fields.js.map

package/dist/api-test/ai-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-fields.js","sourceRoot":"","sources":["../../src/api-test/ai-fields.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAcH,4CAEC;AAMD,oCA0BC;AAMD,sCASC;AA7DD,4CAA8B;AAC9B,gDAAkC;AAIlC,6EAA6E;AAChE,QAAA,gBAAgB,GAAG,WAAW,CAAC;AAE5C;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,WAAmB,EAAE,QAAgB;IACpE,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,wBAAgB,EAAE,GAAG,QAAQ,OAAO,CAAC,CAAC;AAC9F,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,WAAmB,EAAE,QAAgB;IAChE,MAAM,IAAI,GAAG,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrD,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAsB,CAAC;QACxD,IACE,OAAO,MAAM,KAAK,QAAQ;YAC1B,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;YACnC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAC7B,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAiB;YAChC,SAAS,EAAE,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;SACxE,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,WAAmB,EAAE,QAAgB,EAAE,MAAe;IAClF,MAAM,IAAI,GAAG,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrD,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,OAAO,GAAa;QACxB,QAAQ;QACR,MAAM;QACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IACF,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAC1E,CAAC;AAED,8CAA8C;AACjC,QAAA,oBAAoB,GAAG;IAClC,gBAAgB,EAAhB,wBAAgB;CACjB,CAAC"}

package/dist/api-test/assemble.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Assemble phase — source real parameter values for each endpoint and write
+ * them into the `.bru` `body:json` block.
+ *
+ * Spec contract (T-40): three-tier fallback per endpoint:
+ *   1. fixture hit  → use `fixtures[<svc_id>_<methodName>]`.params verbatim.
+ *   2. db-query     → for each Field with `sourceTable`, run
+ *                     `cgraphx db query --sql "SELECT ... LIMIT 1" --format json`
+ *                     via the dist binary (subprocess). `literal` fields are
+ *                     filled directly; `fixtureOnly` fields require a fixture
+ *                     (else the endpoint is skip).
+ *   3. skip         → db-query CLI failure → `db_query_failed`;
+ *                     any field missing source/literal/fixture → `assemble_failed`.
+ *
+ * Independent subsystem — does NOT import from `src/dbquery/`. The db-query
+ * CLI is invoked as a subprocess (subsystem isolation per spec §12). The
+ * subprocess wrapper lives in `./db-query-cli.ts` so tests can `vi.spyOn`
+ * the export and intercept calls from this module.
+ *
+ * Public surface:
+ *   - `assembleEndpoint(endpoint, config, fixtures, projectRoot)`
+ *     → `{ body, skipped, reason }`
+ *   - `writeBruBody(bruPath, body)` — patches a `.bru` file's `body:json` block.
+ *   - `replaceBodyJsonBlock(bruContent, newBody)` — pure-string transform.
+ *   - re-exports `runDbQueryCli` / `DbQueryResult` from `./db-query-cli` so
+ *     callers can import everything from one place.
+ */
+import type { ApiTestConfig, Endpoint, Field, Fixtures } from './types';
+import { runDbQueryCli, type DbQueryResult } from './db-query-cli';
+export { runDbQueryCli, type DbQueryResult };
+/** Outcome of assembling one endpoint. */
+export interface AssembleResult {
+    /** JSON string ready to drop into a `.bru` `body:json` block. Empty when `skipped`. */
+    body: string;
+    skipped: boolean;
+    reason: string | null;
+}
+/**
+ * Assemble the request body for one endpoint following the three-tier
+ * fallback: fixture > db-query > skip.
+ *
+ * Fixture key: `<svc_id>_<methodName>` (matches the `.bru` filename stem).
+ * Fixture `params` is used verbatim as the body array (positional per
+ * method-declaration order).
+ *
+ * For db-query sourcing, fields are grouped by `paramIndex` and one object
+ * per param is emitted (in paramIndex order). The body is always a JSON
+ * array — `[{...param0}, {...param1}, ...]`.
+ */
+export declare function assembleEndpoint(endpoint: Endpoint, _config: ApiTestConfig, fixtures: Fixtures, projectRoot: string): Promise<AssembleResult>;
+/**
+ * Build the `SELECT ... FROM ... WHERE ... LIMIT 1` SQL for a db-query-sourced
+ * field. `sourceFilter` is optional; `sourceColumn` and `sourceTable` are
+ * required (caller guards).
+ */
+declare function buildSourceSql(field: Field): string;
+/**
+ * Patch a `.bru` file's `body:json` block content in place. Reads the file,
+ * replaces whatever is between `body:json {` and the matching closing `}`,
+ * and writes it back. Preserves the rest of the file verbatim.
+ *
+ * Returns the new content (also written to disk). Caller is responsible for
+ * the file existing.
+ */
+export declare function writeBruBody(bruPath: string, body: string): Promise<string>;
+/**
+ * Pure-string transform: replace the inner content of the `body:json { ... }`
+ * block in a `.bru` file. If the block can't be located, returns the input
+ * unchanged (defensive — scan phase always emits one).
+ */
+export declare function replaceBodyJsonBlock(bruContent: string, newBody: string): string;
+/** Internal helpers re-exported for tests. */
+export declare const __INTERNAL_ASSEMBLE: {
+    buildSourceSql: typeof buildSourceSql;
+};
+//# sourceMappingURL=assemble.d.ts.map

package/dist/api-test/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../src/api-test/assemble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,KAAK,EACL,QAAQ,EACT,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGnE,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,CAAC;AAE7C,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,cAAc,CAAC,CAyEzB;AAED;;;;GAIG;AACH,iBAAS,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAG5C;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKjF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIhF;AAED,8CAA8C;AAC9C,eAAO,MAAM,mBAAmB;;CAE/B,CAAC"}

package/dist/api-test/assemble.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * Assemble phase — source real parameter values for each endpoint and write
+ * them into the `.bru` `body:json` block.
+ *
+ * Spec contract (T-40): three-tier fallback per endpoint:
+ *   1. fixture hit  → use `fixtures[<svc_id>_<methodName>]`.params verbatim.
+ *   2. db-query     → for each Field with `sourceTable`, run
+ *                     `cgraphx db query --sql "SELECT ... LIMIT 1" --format json`
+ *                     via the dist binary (subprocess). `literal` fields are
+ *                     filled directly; `fixtureOnly` fields require a fixture
+ *                     (else the endpoint is skip).
+ *   3. skip         → db-query CLI failure → `db_query_failed`;
+ *                     any field missing source/literal/fixture → `assemble_failed`.
+ *
+ * Independent subsystem — does NOT import from `src/dbquery/`. The db-query
+ * CLI is invoked as a subprocess (subsystem isolation per spec §12). The
+ * subprocess wrapper lives in `./db-query-cli.ts` so tests can `vi.spyOn`
+ * the export and intercept calls from this module.
+ *
+ * Public surface:
+ *   - `assembleEndpoint(endpoint, config, fixtures, projectRoot)`
+ *     → `{ body, skipped, reason }`
+ *   - `writeBruBody(bruPath, body)` — patches a `.bru` file's `body:json` block.
+ *   - `replaceBodyJsonBlock(bruContent, newBody)` — pure-string transform.
+ *   - re-exports `runDbQueryCli` / `DbQueryResult` from `./db-query-cli` so
+ *     callers can import everything from one place.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__INTERNAL_ASSEMBLE = exports.runDbQueryCli = void 0;
+exports.assembleEndpoint = assembleEndpoint;
+exports.writeBruBody = writeBruBody;
+exports.replaceBodyJsonBlock = replaceBodyJsonBlock;
+const fs = __importStar(require("node:fs"));
+const db_query_cli_1 = require("./db-query-cli");
+Object.defineProperty(exports, "runDbQueryCli", { enumerable: true, get: function () { return db_query_cli_1.runDbQueryCli; } });
+/**
+ * Assemble the request body for one endpoint following the three-tier
+ * fallback: fixture > db-query > skip.
+ *
+ * Fixture key: `<svc_id>_<methodName>` (matches the `.bru` filename stem).
+ * Fixture `params` is used verbatim as the body array (positional per
+ * method-declaration order).
+ *
+ * For db-query sourcing, fields are grouped by `paramIndex` and one object
+ * per param is emitted (in paramIndex order). The body is always a JSON
+ * array — `[{...param0}, {...param1}, ...]`.
+ */
+async function assembleEndpoint(endpoint, _config, fixtures, projectRoot) {
+    const fixtureKey = `${endpoint.svcId}_${endpoint.method}`;
+    const fixture = fixtures[fixtureKey];
+    // ─── Priority 1: fixture hit ────────────────────────────────────────────
+    if (fixture) {
+        const body = JSON.stringify(fixture.params);
+        return { body, skipped: false, reason: null };
+    }
+    // ─── Priority 2: db-query ───────────────────────────────────────────────
+    // No fields → can't assemble (the analyze phase either skipped or produced
+    // nothing). Mark `assemble_failed` so the .md reflects it.
+    if (endpoint.fields.length === 0) {
+        return { body: '', skipped: true, reason: 'assemble_failed' };
+    }
+    // fixtureOnly fields require a fixture (which we don't have here).
+    for (const f of endpoint.fields) {
+        if (f.fixtureOnly) {
+            return { body: '', skipped: true, reason: 'assemble_failed' };
+        }
+    }
+    // Group fields by paramIndex (one body object per method parameter).
+    const paramGroups = new Map();
+    for (const f of endpoint.fields) {
+        const arr = paramGroups.get(f.paramIndex) ?? [];
+        arr.push(f);
+        paramGroups.set(f.paramIndex, arr);
+    }
+    const paramIndices = [...paramGroups.keys()].sort((a, b) => a - b);
+    const bodyArray = [];
+    for (const idx of paramIndices) {
+        const fields = paramGroups.get(idx);
+        const paramObj = {};
+        for (const f of fields) {
+            // literal — fill directly.
+            if (f.literal !== null) {
+                paramObj[f.name] = f.literal;
+                continue;
+            }
+            // db-query sourced field.
+            if (f.sourceTable && f.sourceColumn) {
+                const sql = buildSourceSql(f);
+                const result = await (0, db_query_cli_1.runDbQueryCli)(sql, projectRoot);
+                if (!result.ok) {
+                    return { body: '', skipped: true, reason: 'db_query_failed' };
+                }
+                const row = result.rows[0];
+                if (!row) {
+                    // Query succeeded but returned no rows — field value can't be sourced.
+                    return { body: '', skipped: true, reason: 'assemble_failed' };
+                }
+                const value = row[f.sourceColumn];
+                if (value === undefined || value === null) {
+                    return { body: '', skipped: true, reason: 'assemble_failed' };
+                }
+                paramObj[f.name] = value;
+            }
+            else {
+                // No source, no literal, no fixture → can't source this field.
+                return { body: '', skipped: true, reason: 'assemble_failed' };
+            }
+        }
+        bodyArray.push(paramObj);
+    }
+    return { body: JSON.stringify(bodyArray), skipped: false, reason: null };
+}
+/**
+ * Build the `SELECT ... FROM ... WHERE ... LIMIT 1` SQL for a db-query-sourced
+ * field. `sourceFilter` is optional; `sourceColumn` and `sourceTable` are
+ * required (caller guards).
+ */
+function buildSourceSql(field) {
+    const filter = field.sourceFilter ? ` WHERE ${field.sourceFilter}` : '';
+    return `SELECT ${field.sourceColumn} FROM ${field.sourceTable}${filter} LIMIT 1`;
+}
+/**
+ * Patch a `.bru` file's `body:json` block content in place. Reads the file,
+ * replaces whatever is between `body:json {` and the matching closing `}`,
+ * and writes it back. Preserves the rest of the file verbatim.
+ *
+ * Returns the new content (also written to disk). Caller is responsible for
+ * the file existing.
+ */
+async function writeBruBody(bruPath, body) {
+    const content = await fs.promises.readFile(bruPath, 'utf8');
+    const updated = replaceBodyJsonBlock(content, body);
+    await fs.promises.writeFile(bruPath, updated, 'utf8');
+    return updated;
+}
+/**
+ * Pure-string transform: replace the inner content of the `body:json { ... }`
+ * block in a `.bru` file. If the block can't be located, returns the input
+ * unchanged (defensive — scan phase always emits one).
+ */
+function replaceBodyJsonBlock(bruContent, newBody) {
+    const re = /(body:json\s*\{\n)([\s\S]*?)(\n\})/;
+    if (!re.test(bruContent))
+        return bruContent;
+    return bruContent.replace(re, `$1    ${newBody}$3`);
+}
+/** Internal helpers re-exported for tests. */
+exports.__INTERNAL_ASSEMBLE = {
+    buildSourceSql,
+};
+//# sourceMappingURL=assemble.js.map

package/dist/api-test/assemble.js.map

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

package/dist/api-test/bru-cli-invoker.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Bruno CLI subprocess invoker — isolated in its own module so tests can
+ * `vi.spyOn` the `invokeBrunoCli` export and intercept calls from
+ * `bru-runner.ts`.
+ *
+ * Why a separate module: same reason as `db-query-cli.ts` — when the
+ * subprocess call lives in the same module as its caller, vitest's
+ * `vi.spyOn(module, 'fn')` cannot intercept the internal bare-local-binding
+ * call. Cross-module imports route through the namespace, which the spy CAN
+ * replace.
+ *
+ * Independent subsystem — does NOT import from `src/extraction/` /
+ * `src/resolution/` / `src/db/`. The Bruno CLI is invoked as a subprocess
+ * (spec §12 isolation).
+ */
+/** Result of one Bruno CLI invocation. */
+export interface BrunoCliInvocation {
+    /** Combined stdout from the subprocess. */
+    stdout: string;
+    /** Combined stderr from the subprocess. */
+    stderr: string;
+    /** Process exit code (null if the process was killed by signal). */
+    exitCode: number | null;
+    /** True when the subprocess was killed by the timeout. */
+    timedOut: boolean;
+}
+export interface InvokeBrunoCliOptions {
+    /** Working directory for the subprocess. */
+    cwd: string;
+    /** Hard kill timeout in milliseconds. */
+    timeoutMs: number;
+    /** Max stdout/stderr buffer size in bytes (default 10 MB). */
+    maxBuffer?: number;
+}
+/**
+ * Invoke `npx @usebruno/cli` with the given args. Returns the captured
+ * stdout/stderr/exitCode. The caller is responsible for arg construction
+ * (see `bru-runner.ts`).
+ *
+ * Exported so tests can `vi.spyOn(bruCliInvoker, 'invokeBrunoCli')` instead
+ * of spawning a real subprocess / real Bruno CLI.
+ */
+export declare function invokeBrunoCli(args: string[], options: InvokeBrunoCliOptions): BrunoCliInvocation;
+/**
+ * Probe whether the Bruno CLI is available. Tries, in order:
+ *   1. `npx @usebruno/cli --version` (preferred — always works if npm cache
+ *      has the package, even without global install).
+ *   2. Global `bru` command (`which bru`).
+ *   3. Global `bruno` command (`which bruno`).
+ *
+ * Returns the resolved command + base args for subsequent `invokeBrunoCli`
+ * calls, or `null` when no Bruno CLI is reachable.
+ *
+ * Exported so tests can spy on it to simulate "Bruno CLI unavailable".
+ */
+export declare function detectBrunoCli(): {
+    command: string;
+    baseArgs: string[];
+} | null;
+/**
+ * Resolve the collection directory. If `filter.service` is set, narrow to
+ * `<collectionDir>/<service>/` when it exists; otherwise fall back to the
+ * whole collection dir (Bruno CLI will just find no matching requests).
+ */
+export declare function resolveCollectionDir(collectionDir: string, filter?: {
+    service?: string;
+}): string;
+/** Internal helper re-exported for tests. */
+export declare const __INTERNAL_BRU_CLI_INVOKER: {
+    resolveCollectionDir: typeof resolveCollectionDir;
+};
+//# sourceMappingURL=bru-cli-invoker.d.ts.map

package/dist/api-test/bru-cli-invoker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bru-cli-invoker.d.ts","sourceRoot":"","sources":["../../src/api-test/bru-cli-invoker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,qBAAqB,GAC7B,kBAAkB,CA2BpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CA8C/E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5B,MAAM,CAQR;AAED,6CAA6C;AAC7C,eAAO,MAAM,0BAA0B;;CAEtC,CAAC"}