@oj-module/cli 0.2.29 → 0.2.42

package/src/cli.ts

@@ -8,9 +8,15 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import cac from "cac";
+import { emit, failEnvelope, OK_CODE } from "./cli-output";
+import { EXIT_FAILURE, EXIT_USAGE, exitCodeOf, UsageError } from "./exit-codes";
 import { findCommand, groupHelpText, HELP_GROUPS, resolveLang, topHelpSections, usageText } from "./usage";
 
-export interface CliDeps { exit?: (code: number) => never }
+export interface CliDeps {
+	exit?: (code: number) => never
+	/** 本次调用的参数（`--json` 失败信封归因用）；缺省 process.argv.slice(2) */
+	argv?: string[]
+}
 
 /** `ojm help [cmd [sub]]` → `<cmd> [sub] --help`：词形归一，交给 cac 的 help 机制。 */
 export function rewriteHelpArgv(argv: string[]): string[] {
@@ -23,41 +29,84 @@ export function rewriteHelpArgv(argv: string[]): string[] {
 
 /**
  * 未知命令兜底结果（index.ts 打印 + 退出用）。
- * help 形态（ojm nope --help / ojm help nope）：报「未知命令」exit 1——打帮助退 0 会掩盖拼写错误。
+ * help 形态（ojm nope --help / ojm help nope）：报「未知命令」exit 2——拼错属于**用法错误**，
+ * 与业务失败（1）分开，CI 才不会把「脚本写错」当成「发版被拒」。
+ * `summary` 是给机器通道的一句话（`--json` 信封的 message），`text` 是给人看的（可能是一屏帮助）。
+ */
+export function unknownCommandResult(cmd: string, lang: Lang, helpRequested: boolean): { text: string, code: number, summary: string } {
+	const summary = lang === "zh-CN"
+		? `[ojm] 未知命令：${cmd}（ojm --help 查看全部命令）`
+		: `[ojm] Unknown command: ${cmd} (run ojm --help for the full command list)`;
+	if (helpRequested)
+		return { text: summary, code: EXIT_USAGE, summary };
+	return { text: usageText(lang), code: EXIT_USAGE, summary };
+}
+
+/**
+ * 未知命令的兜底输出。`--json` 下帮助文本改走 stderr、stdout 只留失败信封——
+ * 机器通道的承诺是「一行 JSON 或空」，不能让一屏帮助混进去（实测踩过：CI 在 `ojm nope --json`
+ * 上拿到的是整页帮助，`JSON.parse` 直接炸）。
  */
-export function unknownCommandResult(cmd: string, lang: Lang, helpRequested: boolean): { text: string, code: number } {
-	if (helpRequested) {
-		return {
-			text: lang === "zh-CN"
-				? `[ojm] 未知命令：${cmd}（ojm --help 查看全部命令）`
-				: `[ojm] Unknown command: ${cmd} (run ojm --help for the full command list)`,
-			code: 1,
-		};
+export function reportUnknownCommand(cmd: string, lang: Lang, helpRequested: boolean, argv: string[] = process.argv.slice(2)): { text: string, code: number } {
+	const r = unknownCommandResult(cmd, lang, helpRequested);
+	if (argv.includes("--json")) {
+		console.error(r.text);
+		console.log(JSON.stringify(failEnvelope(cmd, "usage_error", r.summary)));
+	}
+	else if (helpRequested) {
+		console.error(r.text);
 	}
-	return { text: usageText(lang), code: 1 };
+	else {
+		console.log(r.text);
+	}
+	return { text: r.text, code: r.code };
 }
 
-/** cac 的内置报错是英文裸消息（Unknown option）——按语言重写成人话，带修复指引。 */
+/**
+ * cac 的内置报错是英文裸消息（Unknown option / missing required arg）——按语言重写成人话，带修复指引。
+ * 同时**升格为 UsageError**：这些错误一律是「命令行写错了」（exit 2），不是业务失败。
+ */
 export function localizeCacError(error: unknown, lang: Lang): unknown {
 	if (!(error instanceof Error))
 		return error;
-	const m = /^Unknown option `([^`]+)`/.exec(error.message);
-	if (!m)
-		return error;
-	return new Error(lang === "zh-CN"
-		? `[ojm] 未知选项：${m[1]}（ojm <cmd> --help 查看可用选项）`
-		: `[ojm] Unknown option: ${m[1]} (run ojm <cmd> --help for available options)`);
+	const unknownOption = /^Unknown option `([^`]+)`/.exec(error.message);
+	if (unknownOption) {
+		return new UsageError(lang === "zh-CN"
+			? `[ojm] 未知选项：${unknownOption[1]}（ojm <cmd> --help 查看可用选项）`
+			: `[ojm] Unknown option: ${unknownOption[1]} (run ojm <cmd> --help for available options)`);
+	}
+	const missingArg = /^missing required arg for `([^`]+)`/.exec(error.message);
+	if (missingArg) {
+		return new UsageError(lang === "zh-CN"
+			? `[ojm] 缺少必需参数：${missingArg[1]}（ojm <cmd> --help 查看语法）`
+			: `[ojm] Missing required argument: ${missingArg[1]} (run ojm <cmd> --help for the syntax)`);
+	}
+	return error;
 }
 
-/** 与旧 index.ts 顶层 catch 同源：message 已是人话，堆栈仅 OJM_DEBUG=1（兼容旧名 RAM_DEBUG）。 */
-export function reportCliError(error: unknown, exit: (code: number) => never): void {
+/**
+ * 与旧 index.ts 顶层 catch 同源：message 已是人话，堆栈仅 OJM_DEBUG=1（兼容旧名 RAM_DEBUG）。
+ * 退出码走 `exitCodeOf`：UsageError → 2，其余 → 1（REG-R12 三档契约）。
+ *
+ * `--json` 下失败也要给信封：CI 读完 stdout 就能分支，不必「先看退出码再猜哪条是人话」。
+ * 三种失败各一个稳定机器码：`usage_error`（2）/ `failed`（1）；成功恒 `ok`。
+ * 人话**始终**走 stderr——stdout 在有 `--json` 时恒为「一行可解析 JSON 或空」。
+ */
+export function reportCliError(error: unknown, exit: (code: number) => never, argv: string[] = process.argv.slice(2)): void {
 	const isDebug = !!(process.env.OJM_DEBUG ?? process.env.RAM_DEBUG);
 	const body = error instanceof Error ? (isDebug ? error.stack ?? error.message : error.message) : String(error);
 	console.error(/^\[ojm/.test(body) ? body : `[ojm] ${body}`);
-	exit(1);
+	if (argv.includes("--json")) {
+		const command = argv.find(a => !a.startsWith("-")) ?? "";
+		const message = error instanceof Error ? error.message : String(error);
+		const code = error instanceof UsageError ? "usage_error" : "failed";
+		// 走 console.log 与 `emit` 同一条输出通道：机器通道只有一处实现，测试也能捕获
+		console.log(JSON.stringify(failEnvelope(command, code, message)));
+	}
+	exit(exitCodeOf(error));
 }
 
-interface SiteOpts { url?: string, user?: string, pass?: string }
+interface SiteOpts { siteUrl?: string, user?: string, pass?: string }
 
 function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code: number) => never): (...args: any[]) => Promise<void> {
 	switch (def.key) {
@@ -91,15 +140,14 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 		case "new":
 			return async (name: string | undefined, extra: string[] = [], opts: { layout?: string, api?: boolean } = {}) => {
 				if (!name) {
-					console.error("[ojm] 用法：ojm new <name> [--layout container|none] [--api]（非交互环境必须显式给 name）");
-					exit(1);
-					return;
+					// 用法错误（exit 2）：缺位置参数，改命令行就能解决
+					throw new UsageError("[ojm] 用法：ojm new <name> [--layout container|none] [--api]（非交互环境必须显式给 name）");
 				}
 				// 统一审查 F8：多余位置参数显式拒绝，不能静默丢弃（ojm new crm erp 只建 crm 是事故）
 				if (extra.length > 0)
-					throw new Error(`[ojm] ojm new 只接受一个方案名（多余参数：${extra.join(" ")}）`);
+					throw new UsageError(`[ojm] ojm new 只接受一个方案名（多余参数：${extra.join(" ")}）`);
 				if (opts.layout !== undefined && opts.layout !== "container" && opts.layout !== "none")
-					throw new Error(`[ojm] --layout 只接受 container | none（实际：${opts.layout}）`);
+					throw new UsageError(`[ojm] --layout 只接受 container | none（实际：${opts.layout}）`);
 				const { createSolution } = await import("./new");
 				const created = createSolution(projectRoot, name, { layout: opts.layout as "container" | "none" | undefined, api: !!opts.api });
 				console.log(`[ojm] 已生成方案骨架：${path.relative(process.cwd(), created.dir)}`);
@@ -155,7 +203,7 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 		case "vendor":
 			return async (tag?: string, opts: { force?: boolean } = {}) => {
 				if (tag !== undefined && !/^v?\d+\.\d+\.\d+(?:-[\w.]+)?$/.test(tag))
-					throw new Error(`[ojm] 非法版本号：${tag}（形如 v0.1.11 或 0.1.11）`);
+					throw new UsageError(`[ojm] 非法版本号：${tag}（形如 v0.1.11 或 0.1.11）`);
 				const { vendorCommand } = await import("./vendor");
 				await vendorCommand(projectRoot, { force: !!opts.force, tag: tag === undefined ? undefined : (tag.startsWith("v") ? tag : `v${tag}`) });
 			};
@@ -170,35 +218,245 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 				keygenCommand({ id: opts.id, out: opts.out, yes: opts.yes });
 			};
 		case "sign":
-			return async (file: string | undefined, opts: { id?: string, key?: string, check?: boolean } = {}) => {
+			return async (file: string | undefined, opts: { id?: string, key?: string, check?: boolean, registryId?: string } = {}) => {
 				const { signCommand } = await import("./sign");
-				signCommand(file ?? "", { id: opts.id, key: opts.key, check: opts.check });
+				signCommand(file ?? "", { id: opts.id, key: opts.key, check: opts.check, registryId: opts.registryId });
+			};
+		case "config":
+			return async (sub: string | undefined, opts: { json?: boolean, showOrigin?: boolean } = {}) => {
+				const { configCommand } = await import("./config-cmd");
+				await configCommand(sub, { json: !!opts.json, showOrigin: !!opts.showOrigin, cwd: projectRoot });
 			};
 		case "publish":
-			return async (dir: string | undefined, opts: { id?: string, key?: string, check?: boolean } = {}) => {
+			return async (dir: string | undefined, opts: { id?: string, key?: string, check?: boolean, registry?: string, dryRun?: boolean, json?: boolean } = {}) => {
 				const { publishCommand } = await import("./publish");
-				publishCommand(dir ?? "", { id: opts.id, key: opts.key, check: opts.check });
+				const { describeCredential, describeSourceLevel, resolveRegistryCredential, resolveRegistrySourceOptional } = await import("./registry-source");
+				// 源：给了就必须合法（`--registry` 拼错 → exit 2）；没配则明说「只写本地、不上传」。
+				// 这里不抛「未指定仓库源」：`ojm publish` 今天仍是本地索引落盘（上传随 S4 落地），
+				// 逼它必须有源会把「本地自建 CDN」这条既有链路打死。
+				const source = resolveRegistrySourceOptional({ flag: opts.registry, cwd: projectRoot });
+				const credential = source === null ? null : resolveRegistryCredential(source, { cwd: projectRoot });
+				const human: string[] = [];
+				human.push(source === null
+					? "[ojm] 未配置仓库源：本次只重算并签名本地索引目录（不上传）；CI 用 --registry 或工程根 .ojmrc 指定"
+					: `[ojm] 仓库源 ${source.url}（来源 ${describeSourceLevel(source)}）；凭据 ${describeCredential(credential!)}`);
+				const result = publishCommand(dir ?? "", {
+					id: opts.id,
+					key: opts.key,
+					check: opts.check,
+					dryRun: !!opts.dryRun,
+					cwd: projectRoot,
+					log: line => human.push(line),
+				});
+				const rel = (p: string) => path.relative(projectRoot, p);
+				// `--check` 没过 = 业务失败（1）：签名与内容对不上，改数据就不了，得重签
+				const checkFailed = result.checkPassed === false;
+				emit({
+					command: "publish",
+					code: checkFailed ? "check_failed" : OK_CODE,
+					message: checkFailed ? "索引自检失败：签名与内容不匹配" : undefined,
+					data: {
+						dryRun: result.dryRun,
+						seq: result.seq,
+						keyId: result.keyId,
+						fingerprint: result.fingerprint,
+						registry: source === null ? null : { url: source.url, level: source.level },
+						credential: credential?.kind ?? null,
+						catalog: rel(result.catalogPath),
+						shards: result.shardPaths.map(rel),
+						writes: result.writes.map(rel),
+						checkPassed: result.checkPassed ?? null,
+					},
+					human,
+				}, { json: !!opts.json });
+				if (checkFailed)
+					exit(EXIT_FAILURE);
 			};
 		case "install":
-			return async (target: string | undefined, opts: SiteOpts & { locale?: string, name?: string, version?: string } = {}) => {
+			return async (target: string | undefined, opts: SiteOpts & { locale?: string, name?: string, version?: string, registry?: string } = {}) => {
 				const { installCommand } = await import("./install");
-				await installCommand(target ?? "", { url: opts.url, user: opts.user, pass: opts.pass, locale: opts.locale, name: opts.name, version: opts.version });
+				await installCommand(target ?? "", { siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass, locale: opts.locale, name: opts.name, version: opts.version, registry: opts.registry });
+			};
+		case "list":
+			return async (opts: SiteOpts & { all?: boolean, json?: boolean } = {}) => {
+				const { listCommand } = await import("./list");
+				await listCommand({ siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass, all: !!opts.all, json: !!opts.json });
 			};
 		case "enable":
 		case "disable":
 			return async (name: string | undefined, opts: SiteOpts = {}) => {
 				const { setEnabledCommand } = await import("./enable");
-				await setEnabledCommand(name ?? "", def.key === "enable", { url: opts.url, user: opts.user, pass: opts.pass });
+				await setEnabledCommand(name ?? "", def.key === "enable", { siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass });
 			};
 		case "uninstall":
-			return async (name: string | undefined, opts: SiteOpts = {}) => {
+			return async (name: string | undefined, opts: SiteOpts & { registry?: string } = {}) => {
 				const { uninstallCommand } = await import("./uninstall");
-				await uninstallCommand(name ?? "", { url: opts.url, user: opts.user, pass: opts.pass });
+				await uninstallCommand(name ?? "", { siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass, registry: opts.registry });
+			};
+		case "view":
+			return async (target: string | undefined, opts: SiteOpts & { json?: boolean } = {}) => {
+				const { viewCommand } = await import("./view");
+				await viewCommand(target, { siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass, json: opts.json });
 			};
 		case "trust":
 			return async (sub: string | undefined, keyId: string | undefined, pub: string | undefined, opts: SiteOpts & { task?: string } = {}) => {
 				const { trustCommand } = await import("./trust");
-				await trustCommand(sub ?? "", [keyId, pub].filter((v): v is string => v !== undefined), { url: opts.url, user: opts.user, pass: opts.pass, task: opts.task });
+				await trustCommand(sub ?? "", [keyId, pub].filter((v): v is string => v !== undefined), { siteUrl: opts.siteUrl, user: opts.user, pass: opts.pass, task: opts.task });
+			};
+		case "registry":
+			return async (sub: string | undefined, file: string | undefined, opts: { id?: string, key?: string, out?: string, site?: string, siteUrl?: string, keys?: string, registry?: string, revocations?: boolean, dryRun?: boolean, json?: boolean } = {}) => {
+				if (!sub) {
+					console.log(groupHelpText("registry", lang));
+					return;
+				}
+				if (sub === "sign") {
+					const { registrySignCommand, registryRevocationSignCommand, RegistrySignError } = await import("./registry-sign");
+					const human: string[] = [];
+					if (opts.revocations) {
+						let rev: ReturnType<typeof registryRevocationSignCommand>;
+						try {
+							rev = registryRevocationSignCommand({ file: file ?? "", id: opts.id, key: opts.key, out: opts.out, json: !!opts.json, cwd: projectRoot });
+						}
+						catch (error) {
+							if (!(error instanceof RegistrySignError))
+								throw error;
+							emit({ command: "registry sign", code: error.code, message: error.message, data: null, human: [`[ojm] ${error.message}`] }, { json: !!opts.json });
+							return exit(EXIT_FAILURE);
+						}
+						human.push(`[ojm] 第 ${rev.seq} 代吊销清单已签：${rev.keyId}（指纹 ${String(rev.fingerprint).slice(0, 16)}…）`);
+						if (rev.outPath !== null)
+							human.push(`[ojm] 回传体已写入 ${path.relative(projectRoot, rev.outPath) || rev.outPath}（POST /api/oj-registry/revocations/signature 的请求体）`);
+						emit({
+							command: "registry sign",
+							data: {
+								kind: "revocations",
+								seq: rev.seq,
+								keyId: rev.keyId,
+								fingerprint: rev.fingerprint,
+								signature: rev.signature,
+								out: rev.outPath === null ? null : path.relative(projectRoot, rev.outPath),
+							},
+							human,
+						}, { json: !!opts.json });
+						return;
+					}
+					let result: ReturnType<typeof registrySignCommand>;
+					try {
+						result = registrySignCommand({ file: file ?? "", id: opts.id, key: opts.key, out: opts.out, json: !!opts.json, cwd: projectRoot });
+					}
+					catch (error) {
+						if (!(error instanceof RegistrySignError))
+							throw error;
+						// 业务失败（1）带稳定码：CI 靠 code 分支（usage_error 补参数，这些码只能改数据/换钥匙）
+						emit({ command: "registry sign", code: error.code, message: error.message, data: null, human: [`[ojm] ${error.message}`] }, { json: !!opts.json });
+						// `return` 是必要的：测试里 exit 是 spy（不真的终止），否则会掉回下面的成功分支再抛一次
+						return exit(EXIT_FAILURE);
+					}
+					if (result.signed === 0) {
+						human.push(`[ojm] 第 ${result.gen} 代没有待签文件（已签全或全部沿用旧片）——幂等成功，未触碰私钥`);
+					}
+					else {
+						human.push(`[ojm] 第 ${result.gen} 代：签了 ${result.signed} 个文件（catalog + ${result.signed - 1} 片）`);
+						human.push(`[ojm] 签名者 ${result.keyId}（指纹 ${String(result.fingerprint).slice(0, 16)}…）`);
+					}
+					if (result.outPath !== null)
+						human.push(`[ojm] 回传体已写入 ${path.relative(projectRoot, result.outPath) || result.outPath}（POST /api/oj-registry/index/signature 的请求体）`);
+					emit({
+						command: "registry sign",
+						data: {
+							kind: "index",
+							gen: result.gen,
+							keyId: result.keyId,
+							fingerprint: result.fingerprint,
+							signed: result.signed,
+							signatures: result.signatures,
+							out: result.outPath === null ? null : path.relative(projectRoot, result.outPath),
+						},
+						human,
+					}, { json: !!opts.json });
+					return;
+				}
+				if (sub === "import") {
+					const { registryImportCommand, RegistryImportError } = await import("./registry-import");
+					let result: ReturnType<typeof registryImportCommand>;
+					try {
+						result = registryImportCommand({
+							dir: file ?? "",
+							site: opts.site,
+							out: opts.out,
+							keys: opts.keys,
+							registry: opts.registry,
+							dryRun: !!opts.dryRun,
+							json: !!opts.json,
+							cwd: projectRoot,
+						});
+					}
+					catch (error) {
+						if (error instanceof RegistryImportError) {
+							emit({ command: "registry import", code: error.code, message: error.message, data: null, human: [`[ojm] ${error.message}`] }, { json: !!opts.json });
+							return exit(EXIT_FAILURE);
+						}
+						throw error;
+					}
+					emit({
+						command: "registry import",
+						code: "ok",
+						data: {
+							dir: file ?? "",
+							target: result.written.length > 0 ? result.written[0].dest : null,
+							verified: result.verified,
+							written: result.written.map(w => w.rel),
+							revocationSeq: result.revocationSeq,
+							dryRun: !!opts.dryRun,
+						},
+						human: [result.message],
+					}, { json: !!opts.json });
+					return;
+				}
+				if (sub === "export") {
+					const { registryExportCommand, RegistryExportError } = await import("./registry-export");
+					let result: Awaited<ReturnType<typeof registryExportCommand>>;
+					try {
+						result = await registryExportCommand({
+							siteUrl: opts.siteUrl ?? "",
+							out: opts.out,
+							dryRun: !!opts.dryRun,
+							json: !!opts.json,
+							cwd: projectRoot,
+						});
+					}
+					catch (error) {
+						if (error instanceof RegistryExportError) {
+							emit({ command: "registry export", code: error.code, message: error.message, data: null, human: [`[ojm] ${error.message}`] }, { json: !!opts.json });
+							return exit(EXIT_FAILURE);
+						}
+						throw error;
+					}
+					const human = [
+						`[ojm] ${result.dryRun ? "dry-run：索引已校验通过（包体未下载）" : "离线包已导出"}：${result.packages} 个包体、${result.shards.length} 个分片、第 ${result.catalogSeq} 代索引、吊销清单第 ${result.revocationSeq} 代 → ${result.target}`,
+						`[ojm] 恢复到站点：ojm registry import ${path.relative(projectRoot, result.outDir) || result.outDir} --site <站点数据根> --keys <active索引key.json>`,
+					];
+					emit({
+						command: "registry export",
+						code: "ok",
+						data: {
+							siteUrl: result.siteUrl,
+							out: path.relative(projectRoot, result.outDir) || ".",
+							target: path.relative(projectRoot, result.target) || "registry",
+							catalogSeq: result.catalogSeq,
+							revocationSeq: result.revocationSeq,
+							shards: result.shards,
+							packages: result.packages,
+							verified: result.verified,
+							bytes: result.bytes,
+							written: result.written,
+							dryRun: result.dryRun,
+						},
+						human,
+					}, { json: !!opts.json });
+					return;
+				}
+				throw new UsageError(`[ojm] 未知 registry 子命令：${sub}（支持 sign / import / export）`);
 			};
 		case "market":
 			return async (sub: string | undefined) => {
@@ -224,6 +482,7 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 
 export function buildCli(projectRoot: string, lang: Lang = resolveLang(), deps: CliDeps = {}): CAC {
 	const exit = deps.exit ?? ((code: number) => process.exit(code) as never);
+	const argv = deps.argv ?? process.argv.slice(2);
 	const cli = cac("ojm");
 	for (const group of HELP_GROUPS) {
 		for (const def of group.commands) {
@@ -234,7 +493,7 @@ export function buildCli(projectRoot: string, lang: Lang = resolveLang(), deps:
 				cmd.allowUnknownOptions();
 			const action = makeAction(def, projectRoot, lang, exit);
 			cmd.action((...args: unknown[]) => {
-				Promise.resolve(action(...args)).catch((error: unknown) => reportCliError(error, exit));
+				Promise.resolve(action(...args)).catch((error: unknown) => reportCliError(error, exit, argv));
 			});
 		}
 	}

package/src/config-cmd.ts

@@ -0,0 +1,100 @@
+// `ojm config ls [--show-origin] [--json]`（REG-R12）：把「这次命令到底会用哪个源、凭据从哪来」
+// 一次性摆出来。
+//
+// 为什么值得一条命令：需求 §10.3 的附加规则是「执行日志必须打印最终生效的源 + 来源级别」——
+// 踩过的坑是「以为在发公司仓，其实发了缺省源」。这里把解析结果**做成可查的事实**，而不是等出错再猜。
+//
+// 三条纪律：
+//   · **永不回显 token**：只报来源（env / 用户配置 / 缺失），值一个字都不打（`describeCredential` 单点）；
+//   · **未配置不是错误**：诊断命令的职责就是把「没配」显示出来（退出码 0）；坏配置文件才是失败（1）；
+//   · `--json` 走 `emit`：stdout 只有一份信封，人话列在 `--json` 下改走 stderr。
+
+import type { EmitStreams } from "./cli-output";
+
+import process from "node:process";
+import { emit } from "./cli-output";
+import { UsageError } from "./exit-codes";
+import { describeCredential, describeSourceLevel, REGISTRY_TOKEN_ENV, resolveRegistryCredential, resolveRegistrySourceOptional } from "./registry-source";
+import { DEFAULT_SITE_URL } from "./site";
+
+export interface ConfigRow {
+	key: string
+	value: string
+	/** 该值的来源（`--show-origin` 一列；机器通道恒有，方便 CI 断言） */
+	origin: string
+}
+
+export interface ConfigOptions {
+	json?: boolean
+	showOrigin?: boolean
+	cwd?: string
+	home?: string
+	env?: NodeJS.ProcessEnv
+	out?: (line: string) => void
+	err?: (line: string) => void
+}
+
+/** 未配置的源：显式一行，而不是抛错（诊断命令要能说「这里空着」） */
+const UNSET = "（未配置）";
+
+/**
+ * 解析当前生效配置。`registry.url` 未配置时整行显示 `（未配置）`，
+ * 其余与源相关的行跟着退化——不拿缺省值假装配好了。
+ */
+export function configRows(opts: ConfigOptions = {}): ConfigRow[] {
+	const env = opts.env ?? process.env;
+	const rows: ConfigRow[] = [];
+
+	// null = 一条源都没配（诊断命令要能显示这个事实）；坏配置照旧抛，不吞成「未配置」
+	const source = resolveRegistrySourceOptional({ cwd: opts.cwd, home: opts.home, env });
+	rows.push({
+		key: "registry.url",
+		value: source?.url ?? UNSET,
+		origin: source === null ? "（--registry / .ojmrc / ~/.ojm/config.json 都未提供）" : describeSourceLevel(source),
+	});
+	rows.push({
+		key: "registry.token",
+		value: source === null ? "（无源可绑定）" : describeCredential(resolveRegistryCredential(source, { home: opts.home, env })),
+		origin: source === null ? "—" : `${REGISTRY_TOKEN_ENV} / ~/.ojm/config.json`,
+	});
+	rows.push({
+		key: "site.url",
+		value: env.OJM_SITE_URL?.trim() ? String(env.OJM_SITE_URL).trim() : DEFAULT_SITE_URL,
+		origin: env.OJM_SITE_URL?.trim() ? "OJM_SITE_URL" : "缺省",
+	});
+	const siteCreds = (env.OJM_USER ?? "") !== "" && (env.OJM_PASS ?? "") !== "";
+	rows.push({
+		key: "site.credentials",
+		value: siteCreds ? "OJM_USER / OJM_PASS（已设置）" : "缺失（用 --user/--pass 或 OJM_USER/OJM_PASS）",
+		// 只报「设没设」，永不回显账号密码
+		origin: siteCreds ? "env" : "—",
+	});
+	return rows;
+}
+
+/** 人类可读的对齐列（key 22 宽，够放 `site.credentials` 这类长键） */
+function renderRows(rows: ConfigRow[], showOrigin: boolean): string[] {
+	const width = Math.max(...rows.map(r => r.key.length));
+	return rows.map(r => `${r.key.padEnd(width)}  ${r.value}${showOrigin ? `  ← ${r.origin}` : ""}`);
+}
+
+/**
+ * `ojm config ls`（`ls` 可省略）。未知子命令 → 用法错误（2），不静默当 ls 跑——
+ * 「ojm config set」在拼错时被当成 ls 打印一堆东西，是最容易让人以为设置成功的一类假象。
+ */
+export async function configCommand(sub: string | undefined, opts: ConfigOptions = {}): Promise<void> {
+	const cmd = (sub ?? "ls").trim();
+	if (cmd !== "ls")
+		throw new UsageError(`[ojm] config 只支持 ls（当前：${cmd}）；用法：ojm config ls [--show-origin] [--json]`);
+
+	const rows = configRows(opts);
+	const streams: EmitStreams = {
+		out: opts.out ?? (line => console.log(line)),
+		err: opts.err ?? (line => console.error(line)),
+	};
+	emit({
+		command: "config ls",
+		data: { rows },
+		human: renderRows(rows, opts.showOrigin === true),
+	}, { json: opts.json === true }, streams);
+}

package/src/contract/__tests__/handler-scan.test.ts

@@ -3,9 +3,9 @@
 // market/solutions 全族失效）。镜像 oj 运行时内省语义：oj 执行工厂拿到返回对象。
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { scanHandlerFile } from "../handler-scan";
+import { handlerAbs, pathKey, scanHandlerFile } from "../handler-scan";
 
 let dir: string;
 let apiSrc: string;
@@ -25,6 +25,14 @@ function scan(name: string, text: string) {
 	return scanHandlerFile(join(apiSrc, name), join(dir, "api", "src"));
 }
 
+/** 在相对 api/src 的任意子目录下写一个 handler 并扫（目录段参数化用例） */
+function scanAt(rel: string, text: string) {
+	const file = join(dir, "api", "src", rel);
+	mkdirSync(dirname(file), { recursive: true });
+	writeFileSync(file, text);
+	return scanHandlerFile(file, join(dir, "api", "src"));
+}
+
 describe("handler-scan · 工厂形态（P2-14：export default createXxxApi(env)）", () => {
 	it("callExpression → 同名函数声明 return 对象字面量：动词键/嵌套组照常展开（dir 镜像起算）", () => {
 		const rows = scan("api.ts", `
@@ -109,3 +117,67 @@ export default api;
 		expect(viaIdent.map(r => `${r.method} ${r.full}`)).toEqual(["DELETE _platform/market/bye"]);
 	});
 });
+
+describe("handler-scan · 目录段参数化（`_name_` → `{name}`，v0.1.27）", () => {
+	// 契约 route 走 matchit 语法（`{id}`），handler 目录走 `_id_`；两者是同一条路由的
+	// 两种写法。扫描器若把目录名原样拼进 full，精确对账永远命中不了，`ojm api --check`
+	// 会把「已实现的参数路由」同时报成「契约未实现」+「handler 未登记」。
+	it("整段 `_id_` 目录 → `{id}`：单段与深层嵌套都转换", () => {
+		const one = scanAt("wiki/_id_/api.ts", "export default { get() { return {}; } };");
+		expect(one.map(r => `${r.method} ${r.full}`)).toEqual(["GET wiki/{id}"]);
+
+		const deep = scanAt("wiki/_id_/item/_sku_/api.ts", "export default { del() { return {}; } };");
+		expect(deep.map(r => `${r.method} ${r.full}`)).toEqual(["DELETE wiki/{id}/item/{sku}"]);
+	});
+
+	it("`dir` 保留磁盘事实，`full` 才是 wire 路径（两者不混用）", () => {
+		const [row] = scanAt("wiki/_id_/api.ts", "export default { get() { return {}; } };");
+		expect(row.dir).toBe("wiki/_id_");
+		expect(row.full).toBe("wiki/{id}");
+		expect(handlerAbs(row)).toBe("/wiki/{id}");
+	});
+
+	it("不满足「整段 _name_」的目录保持字面（与 oj 内省同谓词）", () => {
+		const literal = ["__x__", "___", "_a{b}_", "_shared", "a_id_b"];
+		for (const seg of literal) {
+			const rows = scanAt(`m/${seg}/api.ts`, "export default { get() { return {}; } };");
+			expect(rows.map(r => r.full)).toEqual([`m/${seg}`]);
+		}
+	});
+
+	it("模块段同样适用：`_aa_/bb/api.ts` → `{aa}/bb`", () => {
+		// module-root 布局：apiDir 是模块自己的 api 目录（src/<name>/api），模块名单独传
+		const moduleDir = join(dir, "api", "src", "_aa_");
+		const file = join(moduleDir, "api", "bb", "api.ts");
+		mkdirSync(dirname(file), { recursive: true });
+		writeFileSync(file, "export default { get() { return {}; } };");
+		const rows = scanHandlerFile(file, join(moduleDir, "api"), "_aa_");
+		expect(rows.map(r => r.full)).toEqual(["{aa}/bb"]);
+	});
+
+	it("`.route` 尾巴已是 matchit 写法，不再做 `_` 转换；目录参数与相对尾自由组合", () => {
+		const rows = scanAt("wiki/_id_/api.ts", `
+function get() { return {}; }
+get.route = "{sub}";
+export default { get };
+`);
+		expect(rows.map(r => r.full)).toEqual(["wiki/{id}/{sub}"]);
+	});
+
+	it("绝对 `.route` 不受目录影响（根级挂载，full 即其自身）", () => {
+		const rows = scanAt("wiki/_id_/api.ts", `
+function get() { return {}; }
+get.route = "/audit/{tokenId}";
+export default { get };
+`);
+		expect(rows.map(r => r.full)).toEqual(["audit/{tokenId}"]);
+		expect(handlerAbs(rows[0])).toBe("/audit/{tokenId}");
+	});
+});
+
+describe("handler-scan · 对账键与契约侧同形（参数路由精确命中）", () => {
+	it("`_id_` 目录与 `{id}` 契约段产生同一 pathKey", () => {
+		const [row] = scanAt("wiki/_id_/api.ts", "export default { del() { return {}; } };");
+		expect(pathKey(row.method, row.full)).toBe(pathKey("DELETE", "wiki/{id}"));
+	});
+});

package/src/contract/handler-scan.ts

@@ -41,7 +41,7 @@ export interface HandlerRow {
 	tail?: string
 	/** v0.1.64：点分 handler 链（"cccc.get"；顶层动词即方法名） */
 	chain: string
-	/** v0.1.64：组前缀解析后的有效路由全路径（base 相对、无前导 /；绝对 .route 即其自身） */
+	/** v0.1.64：组前缀解析后的有效路由全路径（base 相对、无前导 /；目录段已参数化） */
 	full: string
 	filePath: string
 }
@@ -186,11 +186,36 @@ function resolveRoute(own: string, prefix: string): string {
 	return own.startsWith("/") ? own : (prefix ? `${prefix}/${own}` : own);
 }
 
+/**
+ * 目录段 `_name_` → 参数段 `{name}`（v0.1.27，与 oj 内省同谓词）：只认整段 `_name_`，
+ * 内部名非空且不以 `_` 开头/结尾、不含 `{}`；`__x__` / `___` / `_a{b}_` 保持字面，
+ * `_shared`（无尾下划线）不受影响。
+ *
+ * 为什么扫描器必须转换：**目录镜像就是路由声明**，契约侧 route 用 matchit 语法写 `{id}`，
+ * 磁盘侧写 `_id_`——同一条路由的两种写法。原样拼进 `full` 会让精确对账永远命中不了，
+ * `ojm api --check` 于是把已实现的参数路由同时报成「契约未实现」+「handler 未登记」
+ * 两条互相矛盾的违规（且模糊兜底因静态前缀不同也接不住）。
+ */
+function wireSegmentOf(seg: string): string {
+	const m = /^_([^/{}]+)_$/.exec(seg);
+	if (!m)
+		return seg;
+	const name = m[1];
+	if (name.startsWith("_") || name.endsWith("_"))
+		return seg;
+	return `{${name}}`;
+}
+
+/** 目录镜像 → wire 路径段（逐段参数化；模块段同样适用：`_aa_/bb` → `{aa}/bb`） */
+function wireDirOf(dir: string): string {
+	return dir.split("/").map(wireSegmentOf).join("/");
+}
+
 /** 有效路由全路径（base 相对、无前导 /）：绝对 .route 取其自身，否则目录镜像 + 相对尾 */
 function fullPathOf(dir: string, tail: string | undefined): string {
 	if (tail?.startsWith("/"))
 		return tail.replace(/^\//, "");
-	return [dir, tail].filter(Boolean).join("/");
+	return [wireDirOf(dir), tail].filter(Boolean).join("/");
 }
 
 /** 对账键（方法 + 全路径） */