@oj-module/cli 0.2.1 → 0.2.5

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

@@ -0,0 +1,82 @@
+// BDD：handler AST 扫描（P2-14 裁决：修 handler-scan 认 CallExpression 工厂形态——
+// `export default createXxxApi(env)` 是调用表达式，此前不认 → route-unregistered 守卫对
+// market/solutions 全族失效）。镜像 oj 运行时内省语义：oj 执行工厂拿到返回对象。
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { scanHandlerFile } from "../handler-scan";
+
+let dir: string;
+let apiSrc: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "ojm-scan-"));
+	apiSrc = join(dir, "api", "src", "_platform", "market");
+	mkdirSync(apiSrc, { recursive: true });
+});
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+function scan(name: string, text: string) {
+	writeFileSync(join(apiSrc, name), text);
+	return scanHandlerFile(join(apiSrc, name), join(dir, "api", "src"));
+}
+
+describe("handler-scan · 工厂形态（P2-14：export default createXxxApi(env)）", () => {
+	it("callExpression → 同名函数声明 return 对象字面量：动词键/嵌套组照常展开（dir 镜像起算）", () => {
+		const rows = scan("api.ts", `
+import type { Env } from "./types";
+export function createMarketApi(env: Env) {
+	return {
+		"install": {
+			async post() { return {}; },
+		},
+		"verify": {
+			async post() { return {}; },
+			last: {
+				async get() { return {}; },
+			},
+		},
+	};
+}
+export default createMarketApi({} as Env);
+`);
+		expect(rows.map(r => `${r.method} ${r.full}`).sort()).toEqual([
+			"GET _platform/market/verify/last",
+			"POST _platform/market/install",
+			"POST _platform/market/verify",
+		]);
+	});
+
+	it("无 return 对象 / 未知 callee / 点分 callee 不可解析 → 零行（不炸不猜）", () => {
+		expect(scan("a.ts", "export default createMissingApi({});")).toEqual([]);
+		expect(scan("b.ts", `
+function createApi() { console.log("no return object"); }
+export default createApi();
+`)).toEqual([]);
+		expect(scan("c.ts", "export default (makeApi())({});")).toEqual([]);
+	});
+
+	it("既有形态回归：内联字面量与标识符 default 导出照常识别（P2-14 改动不破旧口径）", () => {
+		const inline = scan("inline.ts", `
+export default {
+	hello: {
+		get() { return {}; },
+	},
+};
+`);
+		expect(inline.map(r => `${r.method} ${r.full}`)).toEqual(["GET _platform/market/hello"]);
+		const viaIdent = scan("ident.ts", `
+const api = {
+	bye: {
+		del() { return {}; },
+	},
+};
+export default api;
+`);
+		expect(viaIdent.map(r => `${r.method} ${r.full}`)).toEqual(["DELETE _platform/market/bye"]);
+	});
+});

package/src/contract/check.ts

@@ -3,6 +3,7 @@ import type { IrEndpoint } from "./ir";
 import type { OpenApiDoc } from "./openapi-ir";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
+import { resolveConfigPath } from "../layout";
 import { readOjAnonymousPaths } from "../oj-config";
 import { emitClient } from "./emit-client";
 import { planStubWrites } from "./emit-stub";
@@ -328,7 +329,7 @@ export async function checkApi(opts: { cwd: string, exempt?: string }): Promise<
 	violations.push(...checkWsAnonymous(
 		walkWsFiles(join(opts.cwd, "api/src")),
 		join(opts.cwd, "api/src"),
-		join(opts.cwd, "api/config.yaml"),
+		resolveConfigPath(opts.cwd),
 	));
 
 	// ③ routes.js diff

package/src/contract/handler-scan.ts

@@ -136,6 +136,29 @@ function defaultExportObject(sf: ts.SourceFile, decls: Map<string, ts.ObjectLite
 	return undefined;
 }
 
+/**
+ * 工厂形态（P2-14 裁决：修 handler-scan 认 CallExpression——`export default createXxxApi(env)`
+ * 是调用表达式，此前扫描器不认，route-unregistered 守卫对 market/solutions 全族失效）：
+ * 解析同文件同名函数声明体内 return 的对象字面量（运行时 oj 内省执行工厂拿到该对象，静态
+ * 扫描镜像此语义）。支持多个 return；对象内标识符引用仍解析文件级顶层 const。
+ */
+function factoryReturnObjects(sf: ts.SourceFile, call: ts.CallExpression): ts.ObjectLiteralExpression[] {
+	const callee = dottedNameOf(call.expression);
+	if (callee === undefined)
+		return [];
+	for (const stmt of sf.statements) {
+		if (!ts.isFunctionDeclaration(stmt) || stmt.name?.text !== callee || stmt.body === undefined)
+			continue;
+		const out: ts.ObjectLiteralExpression[] = [];
+		for (const st of stmt.body.statements) {
+			if (ts.isReturnStatement(st) && st.expression !== undefined && ts.isObjectLiteralExpression(st.expression))
+				out.push(st.expression);
+		}
+		return out;
+	}
+	return [];
+}
+
 /** 相对路由按层前缀解析（绝对 `/` 开头即根级）；与 oj 内省 resolve 同规则 */
 function resolveRoute(own: string, prefix: string): string {
 	return own.startsWith("/") ? own : (prefix ? `${prefix}/${own}` : own);
@@ -227,6 +250,15 @@ export function scanHandlerFile(filePath: string, apiSrcDir: string): HandlerRow
 		}
 		walk(root, "", filePrefix, 1);
 	}
+	else {
+		// P2-14：工厂形态（CallExpression）——组前缀从目录镜像起算（同内联字面量形态）
+		for (const stmt of sf.statements) {
+			if (ts.isExportAssignment(stmt) && !stmt.isExportEquals && ts.isCallExpression(stmt.expression)) {
+				for (const obj of factoryReturnObjects(sf, stmt.expression))
+					walk(obj, "", "", 1);
+			}
+		}
+	}
 	return rows;
 }
 

package/src/deterministic-tar.ts

@@ -0,0 +1,120 @@
+// 确定性 tgz 打包（P1-11，契约 C2-32）：固定 mtime=0、成员按路径字典序、权限 0644/0755、
+// uid/gid=0 且无 owner 名——同输入两次打包 sha256 相等（可复现构建，发布留痕与校验的基础）。
+// 打包自检（C2-30 构建列）：symlink/硬链接/特殊文件成员一律拒绝（tar 忠实还原链接，
+// 安装侧 list→validate→extract 三步守卫的前提是包内没有守卫绕过面）。
+// 手写 ustar 而不用系统 tar：跨平台 tar 的 mtime/权限/排序旗标方言不一，确定性无法逐字保证；
+// ustar 是 POSIX 最小形态，系统 tar -tvzf/-xzf（安装侧 extract 段的唯一消费面）原生可读。
+import { Buffer } from "node:buffer";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { gzipSync } from "node:zlib";
+
+const BLOCK = 512;
+const RECORD = 20 * BLOCK; // 常规记录长度：GNU tar 缺省 -b20，补齐以兼容最保守的读端
+
+interface Entry {
+	relPath: string
+	absPath: string
+	type: "file" | "dir"
+	size: number
+}
+
+/**
+ * 把 `dir` 的内容打包为确定性 tgz 写到 `out`（父目录自动创建），返回 tgz 的 sha256（hex）。
+ * 归档成员 = dir 下的相对路径（含唯一的顶层目录时即单根布局）。
+ */
+export async function createDeterministicTgz(dir: string, out: string): Promise<string> {
+	if (!fs.statSync(dir).isDirectory()) {
+		throw new Error(`[ojm] 确定性打包失败：${dir} 不是目录`);
+	}
+	const entries = walk(dir);
+	const body: Buffer[] = [];
+	for (const e of entries) {
+		const isDir = e.type === "dir";
+		const header = ustarHeader(e);
+		body.push(header);
+		if (!isDir) {
+			const content = fs.readFileSync(e.absPath);
+			body.push(content);
+			const pad = (BLOCK - (content.length % BLOCK)) % BLOCK;
+			if (pad > 0)
+				body.push(Buffer.alloc(pad));
+		}
+	}
+	body.push(Buffer.alloc(RECORD)); // 双零块 EOF（1024B）+ 补齐到整记录
+	// Node zlib gzip 缺省不写 MTIME/FNAME（头内时间戳恒 0、无原始文件名）——确定性由测试钉住
+	const tgz = gzipSync(Buffer.concat(body));
+	const sha256 = crypto.createHash("sha256").update(tgz).digest("hex");
+	fs.mkdirSync(path.dirname(out), { recursive: true });
+	fs.writeFileSync(out, tgz);
+	return sha256;
+}
+
+/** 深度收集全部成员并按 relPath 字典序排序（目录成员在子成员之前：`p` 是 `p/child` 的前缀） */
+function walk(dir: string): Entry[] {
+	const out: Entry[] = [];
+	const visit = (absPath: string, relPath: string) => {
+		const stat = fs.lstatSync(absPath);
+		if (stat.isSymbolicLink()) {
+			throw new Error(`[ojm] 打包自检失败（C2-30）：成员「${relPath}」是 symlink，禁入 tgz（tar 忠实还原链接，链接是安装守卫绕过面）——请改为实体文件`);
+		}
+		if (stat.isDirectory()) {
+			out.push({ relPath, absPath, type: "dir", size: 0 });
+			for (const e of fs.readdirSync(absPath, { withFileTypes: true }))
+				visit(path.join(absPath, e.name), `${relPath}/${e.name}`);
+			return;
+		}
+		if (stat.isFile()) {
+			out.push({ relPath, absPath, type: "file", size: stat.size });
+			return;
+		}
+		throw new Error(`[ojm] 打包自检失败（C2-30）：成员「${relPath}」既非文件亦非目录（lstat=${stat.mode.toString(8)}），禁入 tgz`);
+	};
+	for (const e of fs.readdirSync(dir, { withFileTypes: true }))
+		visit(path.join(dir, e.name), e.name);
+	return out.sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+}
+
+/** 512B ustar 头（POSIX 最小形态）：数字字段 NUL 结尾；uname/gname 空（无 owner 名）；mtime=0 */
+function ustarHeader(e: Entry): Buffer {
+	const fullName = e.type === "dir" ? `${e.relPath}/` : e.relPath;
+	const split = splitUstarName(fullName);
+	const h = Buffer.alloc(BLOCK);
+	h.write(split.name, 0, 100, "utf8");
+	if (split.prefix)
+		h.write(split.prefix, 345, 155, "utf8");
+	writeOctal(h, 100, 8, e.type === "dir" ? 0o755 : 0o644); // 权限固定：umask/源文件权限不泄漏
+	writeOctal(h, 108, 8, 0); // uid=0
+	writeOctal(h, 116, 8, 0); // gid=0
+	writeOctal(h, 124, 12, e.size);
+	writeOctal(h, 136, 12, 0); // mtime=0（确定性核心）
+	h.write("ustar\0", 257, 6, "binary");
+	h.write("00", 263, 2, "binary");
+	// uname/gname（265/297 各 32B）保持全零 = 无 owner 名；devmajor/devminor 全零（非常规设备）
+	h.write(e.type === "dir" ? "5" : "0", 156, 1, "binary"); // typeflag：目录/普通文件
+	h.write(" ".repeat(8), 148, 8, "binary"); // POSIX：chksum 参与求和时本字段按 8 个空格计
+	const sum = h.reduce((acc, byte) => acc + byte, 0);
+	h.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, 8, "binary"); // chksum：6 位八进制 + NUL + 空格
+	return h;
+}
+
+/** 八进制数字字段：值左补零到 size-1，NUL 结尾 */
+function writeOctal(buf: Buffer, offset: number, size: number, value: number): void {
+	buf.write(`${value.toString(8).padStart(size - 1, "0")}\0`, offset, size, "binary");
+}
+
+/** ustar name(100)/prefix(155) 拆分；容量外拒绝并给可读错误（不用 pax 扩展头——其自带元数据是确定性反面） */
+function splitUstarName(fullName: string): { name: string, prefix: string } {
+	if (fullName.length <= 100)
+		return { name: fullName, prefix: "" };
+	let cut = -1;
+	for (let i = fullName.indexOf("/"); i !== -1; i = fullName.indexOf("/", i + 1)) {
+		if (i <= 155 && fullName.length - i - 1 <= 100)
+			cut = i; // 取最后一个合法切点（确定性：fullName 相同则结果相同）
+	}
+	if (cut === -1) {
+		throw new Error(`[ojm] 打包自检失败：成员路径长度超出 ustar 容量（name ≤100 / prefix ≤155），且路径过长无法拆分：「${fullName}」（${fullName.length} 字符）——请缩短目录/文件名`);
+	}
+	return { name: fullName.slice(cut + 1), prefix: fullName.slice(0, cut) };
+}

package/src/dev.ts

@@ -33,8 +33,9 @@ import { loadContractMocks, resolveMock } from "./contract/mock";
 import { loadProjectMocks, mockStatusCode } from "./dev-mock";
 import { createReloadHub, proxyApi, proxyWsUpgrade, sseScript } from "./dev-proxy";
 import { loadHtmlTransform } from "./html-transform";
-import { resolveLayout } from "./layout";
+import { resolveConfigPath, resolveLayout } from "./layout";
 import { startOj } from "./oj";
+import { ensureDevCert } from "./oj-cert";
 import { readOjApiPrefix } from "./oj-config";
 import { createStaticHandler, decodeReqPath, listenOnFreePort } from "./static-handler";
 import { resolveShellDist } from "./versions";
@@ -84,13 +85,14 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 	const transform = await loadHtmlTransform(projectRoot);
 
 	// 2) oj 后端（工程有 api/config.yaml 时全栈形态；桩可注入）
-	const configPath = resolve(projectRoot, "api/config.yaml");
+	const configPath = resolveConfigPath(projectRoot);
 	let oj: OjProcess | undefined;
 	let ojTarget: string | undefined;
 	// 反代前缀跟随 config 的 mounts:（api 挂载 prefix；F2：改前缀后硬编码 /api 会静默失效）
 	let apiBase = "/api";
 	if (!opts.frontendOnly && existsSync(configPath)) {
 		apiBase = readOjApiPrefix(configPath);
+		await ensureDevCert(configPath);
 		const starter = opts.ojStarter ?? ((cfg: string, b: string, apiSrc: string) => startOj(cfg, b, apiSrc));
 		oj = starter(configPath, apiBase, resolve(projectRoot, "api/src"));
 		try {

package/src/enable.ts

@@ -0,0 +1,28 @@
+// ojm enable/disable（P1-13，D8）：生命周期开关瘦客户端——POST /api/_platform/market/enable
+// 触发站点侧 setEnabled 四处同写（锁/sidecar/route/modules.json，D12）。本地零状态，纯转发。
+import process from "node:process";
+import { callApi, login, resolveSite } from "./site";
+
+export interface EnableOptions {
+	url?: string
+	user?: string
+	pass?: string
+	/** 测试注入；缺省 globalThis.fetch */
+	fetchFn?: typeof fetch
+}
+
+/**
+ * 启用/禁用命令体：登录 → POST enable {name, enabled} → 打印服务端人话 message。
+ * ok:false = 域逻辑拒绝（未装/空锁拒启/版本目录缺失），打印 message 并置 exitCode 1。
+ */
+export async function setEnabledCommand(name: string, enabled: boolean, opts: EnableOptions = {}): Promise<void> {
+	if (name.trim() === "")
+		throw new Error("[ojm] 用法：ojm enable|disable <name>——name 为已安装方案名");
+	const fetchFn = opts.fetchFn ?? globalThis.fetch;
+	const { base, user, pass } = resolveSite(opts);
+	const token = await login(fetchFn, base, user, pass);
+	const result = await callApi<{ ok: boolean, message: string }>(fetchFn, base, token, "POST", "/api/_platform/market/enable", { name: name.trim(), enabled });
+	console.log(`[ojm] ${result.message}`);
+	if (!result.ok)
+		process.exitCode = 1;
+}

package/src/index.ts

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
-import { parseApiArgs, parseInitArgs, parseVendorArgs } from "./args";
+import { parseApiArgs, parseBuildArgs, parseInitArgs, parseLifecycleArgs, parseVendorArgs } from "./args";
 import { buildBackend, buildModules } from "./build";
+import { buildBundle } from "./bundle";
 import { devServer } from "./dev";
 import { mergeManifests, printInfo } from "./info";
 import { initProject } from "./init";
@@ -31,11 +32,18 @@ async function main() {
 	}
 
 	switch (command) {
-		case "build":
+		case "build": {
+			const { bundle, out } = parseBuildArgs(process.argv.slice(3));
+			if (bundle) {
+				// 方案包构建（P1-11）：契约校验 fail-fast → 确定性 tgz + sha256（消费方：市场安装器）
+				await buildBundle(projectRoot, { out });
+				break;
+			}
 			// 设计 §5：后端 oj build（零 DB 副作用）→ 前端全站合并（仅 build 清场合并）
 			await buildBackend(projectRoot);
 			await buildModules(projectRoot, { mergeSite: true });
 			break;
+		}
 		case "init": {
 			const { dest, yes } = parseInitArgs(process.argv.slice(3));
 			await initProject(dest ? path.resolve(dest) : projectRoot, { yes });
@@ -100,6 +108,59 @@ async function main() {
 		case "merge":
 			await mergeManifests(process.argv[3] ?? "", process.argv.slice(4));
 			break;
+		case "keygen": {
+			// 签名密钥对生成（P2-4，作者工具链）：缺省 ~/.ojm/keys/<id>，工程树内落盘需 --yes
+			const { parseKeygenArgs } = await import("./keygen");
+			const { keygenCommand } = await import("./keygen");
+			const { id, out, yes } = parseKeygenArgs(process.argv.slice(3));
+			keygenCommand({ id, out, yes });
+			break;
+		}
+		case "sign": {
+			// detached 侧车签名（P2-4，G4 载体）：ojm sign <tgz> [--id <publisher.id>] [--key <pem>] [--check]
+			const { parseSignArgs } = await import("./sign");
+			const { signCommand } = await import("./sign");
+			const { positionals, id, key, check } = parseSignArgs(process.argv.slice(3));
+			signCommand(positionals[0] ?? "", { id, key, check });
+			break;
+		}
+		case "install": {
+			// 方案包安装瘦客户端（P1-13，D6）：file 上传 / CDN 市场源 → 轮询任务至终态
+			const { positionals, url, user, pass, locale, name, version } = parseLifecycleArgs(process.argv.slice(3));
+			const { installCommand } = await import("./install");
+			await installCommand(positionals[0] ?? "", { url, user, pass, locale, name, version });
+			break;
+		}
+		case "enable":
+		case "disable": {
+			// 生命周期开关瘦客户端（P1-13，D8）：站点侧 setEnabled 四处同写
+			const { positionals, url, user, pass } = parseLifecycleArgs(process.argv.slice(3));
+			const { setEnabledCommand } = await import("./enable");
+			await setEnabledCommand(positionals[0] ?? "", command === "enable", { url, user, pass });
+			break;
+		}
+		case "uninstall": {
+			// 卸载瘦客户端（P1-15a，缺口 B）：站点侧 runUninstall 四处同删 + 权限级联
+			const { positionals, url, user, pass } = parseLifecycleArgs(process.argv.slice(3));
+			const { uninstallCommand } = await import("./uninstall");
+			await uninstallCommand(positionals[0] ?? "", { url, user, pass });
+			break;
+		}
+		case "trust": {
+			// 信任库运维瘦客户端（P2-2，C2-38/39）：ls / add <key_id> <pubkey_hex> / revoke <key_id> / confirm --task
+			const { positionals, url, user, pass, task } = parseLifecycleArgs(process.argv.slice(3));
+			const { trustCommand } = await import("./trust");
+			await trustCommand(positionals[0] ?? "", positionals.slice(1), { url, user, pass, task });
+			break;
+		}
+		case "publish": {
+			// 索引发布（P3-5/6/7，作者工具链）：重算 bundles/manifests 索引 + detached .sig 签名写回
+			const { parsePublishArgs } = await import("./publish");
+			const { publishCommand } = await import("./publish");
+			const { positionals, id, key, check } = parsePublishArgs(process.argv.slice(3));
+			publishCommand(positionals[0] ?? "", { id, key, check });
+			break;
+		}
 		default: {
 			if (command && OJ_PASSTHROUGH.has(command)) {
 				const { runOjSubcommand } = await import("./oj-cmd");

package/src/info.ts

@@ -13,6 +13,7 @@ import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import { loadModulesConfig } from "./config";
+import { resolveConfigPath } from "./layout";
 import { mergeModuleManifests } from "./manifest";
 import { readOjApiPrefix, readOjServerField } from "./oj-config";
 import { isSupportedOjVersion, MIN_OJ_VERSION, readLocalVersion, resolveOjBin } from "./vendor";
@@ -71,7 +72,7 @@ function probeOjHealth(base: string, port: number): Promise<Record<string, unkno
 /** CLI 默认观测：真跑 `bin/oj -V` 与真探 /health */
 export function realOjObservability(projectRoot: string): OjObservability {
 	const ojBin = resolveOjBin(projectRoot);
-	const configPath = path.join(projectRoot, "api/config.yaml");
+	const configPath = resolveConfigPath(projectRoot);
 	return {
 		ojVersion: () => (fs.existsSync(ojBin) ? probeOjVersion(ojBin) : null),
 		ojHealth: () => {
@@ -120,7 +121,7 @@ export async function printInfo(projectRoot: string, oj: OjObservability = realO
 
 	// ---- 后端（oj）观测段：工程有 config.yaml 或 bin/oj 才展示；观测不可达仅降级不失败 ----
 	let backendBlock = "";
-	const configPath = path.join(projectRoot, "api/config.yaml");
+	const configPath = resolveConfigPath(projectRoot);
 	const ojBin = resolveOjBin(projectRoot);
 	if (fs.existsSync(configPath) || fs.existsSync(ojBin)) {
 		// 安装标记（ojm vendor/init 下载时写入）；bin/oj 存在但无标记 → 未知