@oj-module/cli 0.1.17 → 0.1.20

package/src/contract/mock.ts

@@ -1,15 +1,18 @@
 import type { MockRoute, MockRouteContext } from "../dev-mock";
-import { faker } from "@faker-js/faker";
+import type { OpenApiDoc } from "./openapi-ir";
+import { readFileSync } from "node:fs";
 import { matchMockRoute } from "../dev-mock";
-import { evaluateContract } from "./evaluate";
-import { buildIr } from "./ir";
-import { discoverContracts } from "./run";
+import { jsonSchemaToSample } from "./json-schema-sample";
+import { irFromOpenapi } from "./openapi-ir";
+import { findOpenapiJson } from "./run";
 
 /**
- * AC-D14 纯前端契约 mock：契约（routes.json 背后的 schema）驱动示例值响应。
+ * AC-D14 纯前端契约 mock：openapi.json（oj v0.1.73 产物）驱动示例值响应。
+ *
+ * 翻译层退役后，事实源即 openapi.json——其 data schema 是 JSON Schema 对象，
+ * 由 `jsonSchemaToSample` 生成示例值（确定性、零依赖）。
  *
  * - 段级 matcher 自研极简实现（零新依赖）：字面段 > 参数段 > catch-all
- * - 示例值语义启发：string format 命中 faker 对应器，enum 取首值，number 取 min
  * - 手写 mock 精确匹配优先，契约 pattern 兜底（resolveMock 收敛选择序）
  * - raw 端点不进 mock 生成（二进制/流无信封可造）
  */
@@ -18,90 +21,13 @@ export interface ContractMockRoute<T = unknown> {
 	method: string
 	/** 含参数段的完整 pattern，如 "/order/item/{id}" */
 	pattern: string
-	/** 负载：matcher 调用方自定（loadContractMocks 填 data schema） */
+	/** 负载：openapi.json 解出的 data JSON Schema（由 jsonSchemaToSample 造示例值） */
 	data: T
 }
 
-/** zod schema → 示例值（语义启发；seed 可复现） */
-export function exampleFromSchema(schema: unknown, opts: { seed?: number } = {}): unknown {
-	if (opts.seed !== undefined)
-		faker.seed(opts.seed);
-	return gen(schema);
-}
-
-function gen(schema: unknown): unknown {
-	const def = (schema as { _zod?: { def?: Record<string, unknown> } })?._zod?.def;
-	if (!def)
-		return null;
-	switch (def.type) {
-		case "string": {
-			let min = 0;
-			let max = Number.POSITIVE_INFINITY;
-			for (const check of (def.checks as { _zod?: { def?: Record<string, unknown> } }[]) ?? []) {
-				const cd = check._zod?.def;
-				// 评审 F4：示例值必须满足自家约束，否则 dev 校验对 mock 误报「契约违例」
-				if (cd?.check === "min_length")
-					min = Math.max(min, cd.minimum as number);
-				if (cd?.check === "max_length")
-					max = Math.min(max, cd.maximum as number);
-				const format = cd?.format as string | undefined;
-				if (format === "email")
-					return faker.internet.email();
-				if (format === "uuid")
-					return faker.string.uuid();
-				if (format === "datetime")
-					return faker.date.recent().toISOString();
-				if (format === "date")
-					return faker.date.recent().toISOString().slice(0, 10);
-				if (format === "url")
-					return faker.internet.url();
-			}
-			let word = faker.lorem.word();
-			if (word.length < min)
-				word = faker.string.alpha(Number.isFinite(min) && min > 0 ? min : 1);
-			if (word.length > max)
-				word = word.slice(0, max);
-			return word;
-		}
-		case "number": {
-			let min: number | undefined;
-			let max: number | undefined;
-			for (const check of (def.checks as { _zod?: { def?: Record<string, unknown> } }[]) ?? []) {
-				const cd = check._zod?.def;
-				if (cd?.check === "greater_than")
-					min = cd.inclusive === false ? (cd.value as number) + 1 : (cd.value as number);
-				if (cd?.check === "less_than")
-					max = cd.inclusive === false ? (cd.value as number) - 1 : (cd.value as number);
-			}
-			return faker.number.int({ min: min ?? 1, max: max ?? (min !== undefined ? min + 1000 : 1000) });
-		}
-		case "boolean":
-			return true;
-		case "date":
-			return faker.date.recent().toISOString(); // 线上传输本就是 ISO 串
-		case "literal":
-			return (def.values as unknown[])[0];
-		case "enum":
-			return Object.keys(def.entries as object)[0];
-		case "union":
-			return gen((def.options as unknown[])[0]);
-		case "array":
-			return [gen(def.element)];
-		case "object": {
-			const out: Record<string, unknown> = {};
-			for (const [k, v] of Object.entries(def.shape as Record<string, unknown>))
-				out[k] = gen(v);
-			return out;
-		}
-		case "optional":
-			return gen(def.innerType);
-		case "nullable":
-			return null;
-		case "default":
-			return def.defaultValue;
-		default:
-			return null;
-	}
+/** JSON Schema → 示例值（确定性，无外部依赖）；data 为 undefined 时返回 null */
+export function exampleFromJsonSchema(schema: unknown): unknown {
+	return jsonSchemaToSample(schema);
 }
 
 interface Seg { kind: "literal" | "param" | "catchAll", text: string }
@@ -166,21 +92,23 @@ export function resolveMock(
 	if (hit)
 		return ctx => hit.response(ctx ?? { body: {}, query: new URLSearchParams() });
 	const fallback = matchContractRoute(contract, method, apiPath);
-	if (fallback)
-		return () => ({ code: 0, msg: "ok", data: exampleFromSchema(fallback.data) });
+	if (fallback) {
+		return () => ({
+			code: 0,
+			msg: "ok",
+			data: exampleFromJsonSchema(fallback.data),
+		});
+	}
 	return undefined;
 }
 
-/** dev 启动装载：发现 + 求值全部契约 → mock 路由表（raw 端点跳过） */
+/** dev 启动装载：openapi.json 为事实源（data schema 是 JSON Schema 对象），raw 端点跳过 */
 export async function loadContractMocks(cwd: string): Promise<ContractMockRoute[]> {
-	const routes: ContractMockRoute[] = [];
-	for (const found of discoverContracts(cwd)) {
-		const ir = buildIr(await evaluateContract(found.path, cwd));
-		for (const ep of ir) {
-			if (ep.raw)
-				continue;
-			routes.push({ method: ep.method, pattern: ep.fullPath, data: ep.dataSchema });
-		}
-	}
-	return routes;
+	const openapiPath = findOpenapiJson(cwd);
+	if (!openapiPath)
+		return [];
+	const doc = JSON.parse(readFileSync(openapiPath, "utf8")) as OpenApiDoc;
+	return irFromOpenapi(doc)
+		.filter(ep => !ep.raw)
+		.map(ep => ({ method: ep.method, pattern: ep.fullPath, data: ep.dataSchema }));
 }

package/src/contract/openapi-ir.ts

@@ -0,0 +1,145 @@
+import type { IrEndpoint } from "./ir";
+
+/**
+ * openapi.json（oj v0.1.73 `oj openapi` 产物，OpenAPI 3.1）→ IrEndpoint[]。
+ *
+ * 单一职责（SRP）：只做「openapi.json 结构 → 统一 IR」的解析，不含任何 zod / 代码发射逻辑。
+ * schema 字段在此承载 **JSON Schema 对象**（白名单子集），下游 emit-jsonschema-zod 负责转 zod。
+ *
+ * 注入安全：本模块只读取数据、产出数据，不拼任何源码字符串，故无注入面。
+ */
+
+/** JSON Schema 白名单子集（透传 openapi.json 里 oj 已校验过的契约，下游再转 zod） */
+export type JsonSchema = Record<string, unknown>;
+
+export interface OpenApiDoc {
+	openapi?: string
+	paths?: Record<string, Record<string, OpenApiOperation>>
+}
+
+export interface OpenApiOperation {
+	"operationId"?: string
+	"tags"?: string[]
+	"x-oj-file"?: string
+	"parameters"?: OpenApiParameter[]
+	"requestBody"?: { required?: boolean, content?: Record<string, { schema?: JsonSchema }> }
+	"responses"?: Record<string, { "description"?: string, "x-oj-response-enforced"?: boolean, "content"?: Record<string, { schema?: JsonSchema }> }>
+}
+
+export interface OpenApiParameter {
+	name: string
+	in: "path" | "query" | "header" | "cookie"
+	required?: boolean
+	schema?: JsonSchema
+}
+
+export interface IrFromOpenapiOptions {
+	/** wire 基础前缀（如 /v1/api）；提供则直接剥离，否则从 path + module 反推 */
+	base?: string
+	/** 已知 raw 端点路由（相对路径集合）：openapi.json 不携带 raw 标记，由 handler-scan 补充 */
+	rawPaths?: Set<string>
+}
+
+/** operationId（去 base 子路径 + 方法，非字母数字转 _）→ camelCase 端点方法名 */
+export function camelCaseOperationId(operationId: string): string {
+	return operationId
+		.split("_")
+		.filter(Boolean)
+		.map((seg, i) => (i === 0 ? seg.toLowerCase() : seg.charAt(0).toUpperCase() + seg.slice(1).toLowerCase()))
+		.join("");
+}
+
+/** 剥 base + 模块前缀，得到模块相对路径（如 /collections/{id}）；客户端用 apiPrefix + route 拼回全路径 */
+function stripBase(path: string, base: string | undefined, module: string): string {
+	let rel = path;
+	// base 缺省：从 path 反推（path 中 "/<module>" 之前的部分即 base）
+	if (!base) {
+		const idx = path.indexOf(`/${module}`);
+		if (idx >= 0)
+			base = path.slice(0, idx);
+	}
+	if (base && rel.startsWith(base))
+		rel = rel.slice(base.length);
+	const modPrefix = `/${module}`;
+	if (rel.startsWith(modPrefix))
+		rel = rel.slice(modPrefix.length);
+	return rel || "/";
+}
+
+/** 从路径模板抽取参数段名（catch-all {*path} → path） */
+function paramNamesOf(route: string): string[] {
+	return [...route.matchAll(/\{([^}]+)\}/g)].map(m => m[1].replace(/^\*/, ""));
+}
+
+/** parameters[] 按 in 通道合并为 params / query 两个 object schema（required 收集到数组） */
+function collectParams(parameters: OpenApiParameter[] | undefined): { params?: JsonSchema, query?: JsonSchema } {
+	const paramsProps: Record<string, JsonSchema> = {};
+	const paramsReq: string[] = [];
+	const queryProps: Record<string, JsonSchema> = {};
+	const queryReq: string[] = [];
+	for (const p of parameters ?? []) {
+		if (p.in === "path") {
+			paramsProps[p.name] = p.schema ?? { type: "string" };
+			if (p.required)
+				paramsReq.push(p.name);
+		}
+		else if (p.in === "query") {
+			queryProps[p.name] = p.schema ?? { type: "string" };
+			if (p.required)
+				queryReq.push(p.name);
+		}
+	}
+	const params = Object.keys(paramsProps).length
+		? { type: "object", required: paramsReq, properties: paramsProps }
+		: undefined;
+	const query = Object.keys(queryProps).length
+		? { type: "object", required: queryReq, properties: queryProps }
+		: undefined;
+	return { params, query };
+}
+
+/**
+ * responses.200 解包 data：仅当带 x-oj-response-enforced:false（= 信封 {code,msg,data}）才取
+ * properties.data 作为返回 payload；未声明 response 的端点（仅有 description:OK）返回 undefined。
+ */
+function extractDataSchema(op: OpenApiOperation): JsonSchema | undefined {
+	const r200 = op.responses?.["200"];
+	if (!r200 || r200["x-oj-response-enforced"] !== false)
+		return undefined;
+	const schema = r200.content?.["application/json"]?.schema as JsonSchema | undefined;
+	const data = (schema?.properties as Record<string, JsonSchema> | undefined)?.data;
+	return data as JsonSchema | undefined;
+}
+
+/** openapi.json → IrEndpoint[] */
+export function irFromOpenapi(doc: OpenApiDoc, opts: IrFromOpenapiOptions = {}): IrEndpoint[] {
+	const out: IrEndpoint[] = [];
+	for (const [path, methods] of Object.entries(doc.paths ?? {})) {
+		for (const [method, op] of Object.entries(methods)) {
+			const module = op.tags?.[0] ?? path.split("/").filter(Boolean)[0] ?? "";
+			const route = stripBase(path, opts.base, module);
+			const name = camelCaseOperationId(op.operationId ?? `${route}_${method}`);
+			const { params, query } = collectParams(op.parameters);
+			const body = op.requestBody?.content?.["application/json"]?.schema;
+			const dataSchema = extractDataSchema(op);
+			const apiPrefix = `/${module}`;
+			out.push({
+				name,
+				apiPrefix,
+				route,
+				"method": method.toUpperCase() as IrEndpoint["method"],
+				// fullPath = 模块前缀 + 模块相对 route（不含 oj 全局 base，base 由 oj 处理）；
+				// 与旧 IR（buildIr 的 wirePrefix+route）口径一致，供 client URL / mock / route 对账复用
+				"fullPath": apiPrefix === "/" ? route : `${apiPrefix}${route}`,
+				"paramNames": paramNamesOf(route),
+				"paramsSchema": params,
+				"querySchema": query,
+				"bodySchema": body,
+				dataSchema,
+				"raw": opts.rawPaths?.has(route) ?? false,
+				"x-oj-file": op["x-oj-file"],
+			} as IrEndpoint);
+		}
+	}
+	return out;
+}

package/src/contract/run.ts

@@ -1,25 +1,24 @@
 import type { OjSchemaDiag } from "./emit-oj-schema";
+import type { IrEndpoint } from "./ir";
+import type { OpenApiDoc } from "./openapi-ir";
 import { execFile as execFileCb } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { stringify as stringifyYaml } from "yaml";
 import { emitClient } from "./emit-client";
-import { emitOpenapiYaml, emitRoutesJson } from "./emit-meta";
 import { applyStubWrites, planStubWrites } from "./emit-stub";
-import { evaluateContract } from "./evaluate";
-import { buildIr } from "./ir";
+import { implementedRouteKeys } from "./handler-scan";
+import { irFromOpenapi } from "./openapi-ir";
 
 /**
- * AC-D7：`ojm api` 编排——discover → evaluate → IR → 发射 → 幂等写盘。
+ * AC-D7：`ojm api` 编排——发现 openapi.json → IR → 逐模块发射 __client → 写盘；
+ * 并为未实现的 handler 生成 stub（人碰过的文件永不写）。
  *
- * 发现两档（缺省并扫）：
- * - uni-dev：`api/src/<模块>/contract.ts` → client 双产物写到对应前端模块
- *   `web/src/<模块>/client/`（模块名 = apiPrefix 去首斜杠，AC-D9 字面相等，
- *   不符即人话报错）；routes.json/openapi.yaml 写契约旁；stub 写 oj 目录镜像树。
- * - 纯前端：`web/src/<模块>/client/contract.ts` → 四产物全部落契约同目录，无 stub。
+ * 单一事实源即 `openapi.json`（oj v0.1.73 `oj openapi` 产物，OpenAPI 3.1）：
+ * 项目级单文件，含全部模块。翻译层退役后不再消费旧 `contract.ts`。
  *
  * 幂等：内容无变化不写盘（读旧比对），RunResult 报告 written/skipped。
  */
@@ -31,38 +30,18 @@ export interface RunResult {
 	stubs: { created: number, updated: number, skipped: number }
 }
 
-export interface DiscoveredContract {
-	/** contract.ts 绝对路径 */
-	path: string
-	/** 模块名（uni-dev = api/src 下一级目录名；纯前端 = web/src 下一级目录名） */
-	module: string
-	kind: "uni-dev" | "frontend"
-}
+/** 发现 openapi.json（oj v0.1.73 `oj openapi` 产物）。候选位置：显式传入 > `<cwd>/openapi.json` > `<cwd>/api/openapi.json` */
+const OPENAPI_CANDIDATES = ["openapi.json", "api/openapi.json"];
 
-/** 发现契约文件：api/src/<m>/contract.ts + web/src/<m>/client/contract.ts */
-export function discoverContracts(cwd: string): DiscoveredContract[] {
-	const found: DiscoveredContract[] = [];
-	const apiSrc = join(cwd, "api/src");
-	if (existsSync(apiSrc)) {
-		for (const entry of readdirSync(apiSrc, { withFileTypes: true })) {
-			if (!entry.isDirectory())
-				continue;
-			const p = join(apiSrc, entry.name, "contract.ts");
-			if (existsSync(p))
-				found.push({ path: p, module: entry.name, kind: "uni-dev" });
-		}
-	}
-	const modulesSrc = join(cwd, "web/src");
-	if (existsSync(modulesSrc)) {
-		for (const entry of readdirSync(modulesSrc, { withFileTypes: true })) {
-			if (!entry.isDirectory())
-				continue;
-			const p = join(modulesSrc, entry.name, "client", "contract.ts");
-			if (existsSync(p))
-				found.push({ path: p, module: entry.name, kind: "frontend" });
-		}
+function findOpenapiJson(cwd: string, explicit?: string): string | undefined {
+	if (explicit)
+		return join(cwd, explicit);
+	for (const rel of OPENAPI_CANDIDATES) {
+		const p = join(cwd, rel);
+		if (existsSync(p))
+			return p;
 	}
-	return found.sort((a, b) => (a.path < b.path ? -1 : 1));
+	return undefined;
 }
 
 /** 内容无变化不写盘；返回是否写入 */
@@ -76,108 +55,80 @@ function writeIfChanged(path: string, content: string, result: RunResult): void
 	result.written.push(path);
 }
 
-/** 单份契约的四产物落盘路径（run 与 --check 共用，DRY） */
-export function artifactPaths(found: DiscoveredContract, cwd: string): { client: string, schemas: string, routes: string, openapi: string } {
-	if (found.kind === "uni-dev") {
-		const moduleClientDir = join(cwd, "web/src", found.module, "client");
-		return {
-			client: join(moduleClientDir, "api.ts"),
-			schemas: join(moduleClientDir, "api.schemas.ts"),
-			routes: join(dirname(found.path), "routes.json"),
-			openapi: join(dirname(found.path), "openapi.yaml"),
-		};
-	}
-	const dir = dirname(found.path);
-	return {
-		client: join(dir, "api.ts"),
-		schemas: join(dir, "api.schemas.ts"),
-		routes: join(dir, "routes.json"),
-		openapi: join(dir, "openapi.yaml"),
-	};
-}
-
-/** 契约 → IR（含 uni-dev 的 AC-D9 字面相等校验）；run 与 --check 共用 */
-export async function irOf(found: DiscoveredContract, cwd: string) {
-	const exports = await evaluateContract(found.path, cwd);
-	const ir = buildIr(exports);
-	if (ir.length === 0)
-		throw new Error(`[ojm-api] ${found.path} 没有 defineApi 端点——契约文件至少导出一个端点，否则请删除该文件。`);
-	if (found.kind === "uni-dev") {
-		// AC-D9：uni-dev 形态 apiPrefix 字面等于 oj 模块段（= 目录名）
-		for (const ep of ir) {
-			if (ep.apiPrefix !== `/${found.module}`) {
-				throw new Error(`[ojm-api] ${found.path} 端点 "${ep.name}" apiPrefix "${ep.apiPrefix}" 与目录名 "${found.module}" 不符——uni-dev 形态要求字面相等（AC-D9），请改 apiPrefix 或移动契约目录。`);
-			}
-		}
+/** IR 按模块（apiPrefix 去首斜杠）分组，供逐模块 emitClient 落 __client */
+function groupIrByModule(ir: IrEndpoint[]): Map<string, IrEndpoint[]> {
+	const byModule = new Map<string, IrEndpoint[]>();
+	for (const ep of ir) {
+		const module = ep.apiPrefix.replace(/^\//, "");
+		const list = byModule.get(module);
+		if (list)
+			list.push(ep);
+		else
+			byModule.set(module, [ep]);
 	}
-	return ir;
+	return byModule;
 }
 
-async function runOne(found: DiscoveredContract, cwd: string, result: RunResult): Promise<void> {
-	const ir = await irOf(found, cwd);
-
-	const client = emitClient(ir, { target: "module", module: found.module });
-	const routesJson = emitRoutesJson(ir);
-	const openapi = emitOpenapiYaml(ir, { title: `${found.module} api`, version: "0.0.0" });
+/** 暴露给 check.ts 复用（同源 openapi.json 发现逻辑，DRY） */
+export { findOpenapiJson, groupIrByModule };
 
-	const paths = artifactPaths(found, cwd);
-	writeIfChanged(paths.client, client["api.ts"], result);
-	writeIfChanged(paths.schemas, client["api.schemas.ts"], result);
-	writeIfChanged(paths.routes, routesJson, result);
-	writeIfChanged(paths.openapi, openapi, result);
-	if (found.kind === "uni-dev") {
-		// stub：oj 目录镜像树（人碰过的文件永不写——plan 阶段已按指纹判好）
+/**
+ * openapi.json → irFromOpenapi → 逐模块 emitClient → 写 `web/src/<模块>/__client/`；
+ * 并为未实现的 handler 生成 stub（oj 目录镜像树，指纹幂等）。
+ * raw 信号 openapi.json 不携带，由 opts.rawPaths（handler-scan 补充）标记；未提供则按非 raw。
+ */
+async function runFromOpenapi(openapiPath: string, cwd: string, result: RunResult, rawPaths?: Set<string>): Promise<void> {
+	const doc = JSON.parse(readFileSync(openapiPath, "utf8")) as OpenApiDoc;
+	const ir = irFromOpenapi(doc, { rawPaths });
+	const byModule = groupIrByModule(ir);
+	result.contracts += byModule.size;
+	for (const [module, eps] of byModule) {
+		const client = emitClient(eps, { target: "module", module });
+		const clientDir = join(cwd, "web/src", module, "__client");
+		writeIfChanged(join(clientDir, "api.ts"), client["api.ts"], result);
+		writeIfChanged(join(clientDir, "api.schemas.ts"), client["api.schemas.ts"], result);
+	}
+	// stub：oj 目录镜像树（人碰过的文件永不写——plan 阶段已按指纹判好）。
+	// 已实现键全量扫一遍传入：嵌套组（模块根单文件）实现的端点不再生成镜像 stub。
+	const apiSrcDir = join(cwd, "api/src");
+	if (existsSync(apiSrcDir)) {
 		const diag: OjSchemaDiag = { warnings: [] };
-		const writes = await planStubWrites(ir, { apiSrcDir: join(cwd, "api/src"), diag });
+		const writes = await planStubWrites(ir, { apiSrcDir, diag, implemented: implementedRouteKeys(apiSrcDir) });
 		const counts = applyStubWrites(writes);
 		result.stubs.created += counts.created;
 		result.stubs.updated += counts.updated;
 		result.stubs.skipped += counts.skipped;
-		// .schema 降级必须说出来：oj 关键字是白名单，表达不了的约束后端就不校验了
 		for (const w of diag.warnings)
 			console.warn(`[ojm-api] ⚠️ ${w}`);
 	}
 }
 
-/** ojm api 主入口：发现全部契约并逐一生成产物 */
-export async function runApi(opts: { cwd: string }): Promise<RunResult> {
-	const contracts = discoverContracts(opts.cwd);
-	if (contracts.length === 0) {
-		throw new Error(`[ojm-api] ${opts.cwd} 下没有发现契约文件——默认发现：api/src/*/contract.ts（uni-dev）与 web/src/*/client/contract.ts（纯前端）。存量工程请迁移：modules/ → web/、模块内 api/ → client/（生成物与契约同迁）。`);
+/** ojm api 主入口：消费 openapi.json（oj v0.1.73 `oj openapi` 产物）生成 __client + stub */
+export async function runApi(opts: { cwd: string, openapi?: string, rawPaths?: Set<string> }): Promise<RunResult> {
+	const result: RunResult = { contracts: 0, written: [], skipped: [], stubs: { created: 0, updated: 0, skipped: 0 } };
+	const openapiPath = findOpenapiJson(opts.cwd, opts.openapi);
+	if (!openapiPath) {
+		throw new Error(`[ojm-api] ${opts.cwd} 下未发现 openapi.json——请先运行 oj v0.1.73 的 \`oj openapi -c config -d api/src -b /api -o openapi.json\` 生成（OpenAPI 3.1，含全部模块）。\`ojm api\` 的单一事实源即 openapi.json，不再消费旧 contract.ts。`);
 	}
-	const result: RunResult = { contracts: contracts.length, written: [], skipped: [], stubs: { created: 0, updated: 0, skipped: 0 } };
-	for (const found of contracts)
-		await runOne(found, opts.cwd, result);
+	await runFromOpenapi(openapiPath, opts.cwd, result, opts.rawPaths);
 	return result;
 }
 
 /**
- * R5：`ojm api --docs`——聚合全部契约的 OpenAPI → redoc 渲染静态站。
- * uni-dev 形态（存在 api/src 契约）落 `api/docs/index.html`，纯前端落 `docs/api/index.html`；
- * 聚合 spec 同目录落 `openapi.yaml`（评审可直读）。redoc CLI 缺失时人话报错。
+ * R5：`ojm api --docs`——聚合 openapi.json 的 paths → redoc 渲染静态站。
+ * uni-dev 形态（存在 api/src）落 `api/docs/index.html`，纯前端落 `docs/api/index.html`。
+ * redoc CLI 缺失时人话报错。
  */
 export async function runApiDocs(cwd: string, opts: { redocBin?: string, fetchJs?: (url: string) => Promise<string> } = {}): Promise<string> {
-	const contracts = discoverContracts(cwd);
-	if (contracts.length === 0) {
-		throw new Error(`[ojm-api] ${cwd} 下没有发现契约文件——默认发现：api/src/*/contract.ts（uni-dev）与 web/src/*/client/contract.ts（纯前端）。`);
-	}
-
-	// 聚合：逐契约 IR → openapi doc → paths 合并（operation 打模块 tag）
-	const paths: Record<string, Record<string, unknown>> = {};
-	for (const found of contracts) {
-		const ir = await irOf(found, cwd);
-		const doc = parseYaml(emitOpenapiYaml(ir, { title: `${found.module} api`, version: "0.0.0" })) as { paths: Record<string, Record<string, { tags?: string[] }>> };
-		for (const [p, methods] of Object.entries(doc.paths)) {
-			for (const [method, op] of Object.entries(methods)) {
-				if (paths[p]?.[method])
-					throw new Error(`[ojm-api] 聚合冲突：${method.toUpperCase()} ${p} 被多个契约声明——请检查各模块 apiPrefix 是否撞车。`);
-				op.tags = [found.module];
-				(paths[p] ??= {})[method] = op;
-			}
-		}
+	const openapiPath = findOpenapiJson(cwd);
+	if (!openapiPath) {
+		throw new Error(`[ojm-api] ${cwd} 下未发现 openapi.json——请先运行 \`oj openapi\` 生成（\`ojm api --docs\` 聚合其 paths 渲染文档）。`);
 	}
+	const doc = JSON.parse(readFileSync(openapiPath, "utf8")) as { paths?: Record<string, Record<string, unknown>> };
+	const paths = doc.paths ?? {};
+	const isUniDev = existsSync(join(cwd, "api/src"));
 
-	const outDir = contracts.some(c => c.kind === "uni-dev") ? join(cwd, "api/docs") : join(cwd, "docs/api");
+	const outDir = isUniDev ? join(cwd, "api/docs") : join(cwd, "docs/api");
 	mkdirSync(outDir, { recursive: true });
 	const specPath = join(outDir, "openapi.yaml");
 	writeFileSync(specPath, stringifyYaml({ openapi: "3.1.0", info: { title: "API 文档", version: "0.0.0" }, paths }));

package/src/dev.ts

@@ -25,7 +25,7 @@ import { spawn } from "node:child_process";
 import { existsSync, watch } from "node:fs";
 import http from "node:http";
 
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import process from "node:process";
 import readline from "node:readline";
 import { buildModules } from "./build";
@@ -244,30 +244,25 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 		}, 300);
 	};
 	try {
-		watch(layout.watchTarget, { recursive: true }, (_event, filename) => {
-			if (!filename)
-				return;
-			// 契约文件变更：先 runApi 重生成 client（落 web 树 → 二次触发本 watch 走重建）
-			if (filename.endsWith("contract.ts"))
-				regenContracts();
+		watch(layout.watchTarget, { recursive: true }, () => {
+			// 契约产物（__client）由 regenContracts 落 web 树 → 二次触发本 watch 走重建
 			trigger();
 		});
 	}
 	catch {
 		// 某些平台不支持 recursive，退化为不自动重建（手动 ojm build 仍可用）
 	}
-	// uni-dev 契约在 api/src（不在模块 watch 范围内），单独挂 watcher
+	// uni-dev 契约源在 api/src（不在模块 watch 范围内）。新流水线（oj v0.1.73）：
+	// contract.ts 已退役，dev 改 handler `.schema`/`.response` 后按约定手动重跑
+	// `oj openapi -o openapi.json`——监听工程根该文件变化触发 __client 重生成
+	// （落 web 树 → 二次触发上方 watch 走重建）。
 	try {
-		const apiSrc = `${projectRoot}/api/src`;
-		if (existsSync(apiSrc)) {
-			watch(apiSrc, { recursive: true }, (_event, filename) => {
-				if (filename?.endsWith("contract.ts"))
-					regenContracts();
-			});
-		}
+		const specPath = join(projectRoot, "openapi.json");
+		if (existsSync(specPath))
+			watch(specPath, () => regenContracts());
 	}
 	catch {
-		// 同上：平台不支持 recursive 时退化为手动 ojm api
+		// 同上：平台不支持时退化为手动 ojm api
 	}
 
 	// Vite 风格快捷键：r 热更新 / h 帮助 / c 清屏 / o 打开浏览器 / q 退出。
@@ -329,7 +324,12 @@ export interface DevKeymapDeps {
 	oj: OjProcess | undefined
 	hub: { close: () => void }
 	port: number
-	input?: NodeJS.ReadStream
+	/**
+	 * 键盘输入流：默认 `process.stdin`（TTY）；测试可注入任意 Readable（如 PassThrough）。
+	 * 宽松成 ReadableStream + 可选 setRawMode：keypress 监听与非 TTY 路径都不依赖 TTY 方法，
+	 * 而 `NodeJS.ReadStream` 强求 isTTY/setRawMode 等成员，注入流无法满足（TS2740）。
+	 */
+	input?: NodeJS.ReadableStream & { setRawMode?: (mode: boolean) => unknown }
 	openBrowser?: (url: string) => void
 	onReload: () => void
 	onQuit: () => void
@@ -346,7 +346,9 @@ function defaultOpenBrowser(url: string): void {
 }
 
 export function setupDevKeymap(deps: DevKeymapDeps): void {
-	const input = deps.input ?? process.stdin;
+	// 显式标注收敛 `??` 的联合类型（ReadStream ∩ 可选 setRawMode 的并集会让 .on 签名不可调和）
+	type KeymapInput = NodeJS.ReadableStream & { setRawMode?: (mode: boolean) => unknown };
+	const input: KeymapInput = deps.input ?? process.stdin;
 	const log = deps.log ?? ((msg: string) => console.log(msg));
 	const open = deps.openBrowser ?? defaultOpenBrowser;
 	const url = `http://localhost:${deps.port}`;