@koishi-ce/plugin-market 1.1.0 → 1.1.2

package/src/node/installer/exec.ts

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * bun 安装子进程的驱动与输出转发。
+ *
+ * Bun-first：CE 生态只存在 bun 这一种包管理器，直接驱动 bun 执行安装
+ * （上游经 which-pm-runs 探测 npm/yarn/bun，此处固定为 bun）。子进程本身的
+ * 创建见 ./proc.ts；本模块负责退出码归一化与日志转发，不持有任何服务状态。
+ */
+import { Logger } from "@koishi-ce/koishi";
+import { spawnBun } from "./proc.ts";
+
+const logger = new Logger("market");
+
+/**
+ * 在 cwd 下执行 `bun <args>`，返回退出码（spawn 失败与异常退出统一为非 0，
+ * 由调用方按失败处理）。
+ *
+ * 输出按行转发到 market 日志：未成行的尾段暂存到下一次数据到来时补齐，
+ * 避免半行日志刷屏。
+ */
+export function runBun(
+	args: string[],
+	cwd: string,
+): Promise<number> {
+	return new Promise<number>((resolve) => {
+		const child = spawnBun(args, cwd);
+		child.on("exit", (code) => resolve(code ?? -1));
+		child.on("error", () => resolve(-1));
+
+		let stderr = "";
+		child.stderr?.on("data", (data) => {
+			stderr += data.toString();
+			const lines = stderr.split("\n");
+			stderr = lines.pop() ?? "";
+			for (const line of lines) {
+				logger.warn(line);
+			}
+		});
+
+		let stdout = "";
+		child.stdout?.on("data", (data) => {
+			stdout += data.toString();
+			const lines = stdout.split("\n");
+			stdout = lines.pop() ?? "";
+			for (const line of lines) {
+				logger.info(line);
+			}
+		});
+	});
+}

package/src/node/installer/index.ts

@@ -0,0 +1,337 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 插件市场的安装服务（`installer` 服务，同时是本目录入口）。
+ *
+ * 本目录按职责拆分，本文件只保留服务本体（缓存、依赖汇总、安装编排与
+ * 重载判定）：
+ * - `./manifest.ts`　项目根 package.json 的读写与护栏判定
+ * - `./versions.ts`　远端版本探测与兼容性过滤
+ * - `./exec.ts`　bun 安装子进程的驱动与输出转发
+ * - `./integrity.ts`　安装完整性校验（isolated 布局链接探测）
+ * - `./registry-config.ts`　本机 npm registry 配置探测
+ * - `./proc.ts`　bun 安装子进程的创建封装
+ */
+import type {} from "@koishi-ce/console";
+import {
+	type Context,
+	type Dict,
+	type HTTP,
+	Logger,
+	Schema,
+	Service,
+	Time,
+	valueMap,
+} from "@koishi-ce/koishi";
+import type {} from "@koishi-ce/loader";
+import type {} from "@koishi-ce/plugin-market";
+import {
+	isResidentInCache,
+	mapLimit,
+	type RemotePackage,
+} from "@koishi-ce/registry";
+import { satisfies, valid } from "semver";
+import { runBun } from "./exec.ts";
+import { findMissingDeps } from "./integrity.ts";
+import {
+	type LocalPackage,
+	loadManifest,
+	writeManifest,
+} from "./manifest.ts";
+import {
+	getLocalRegistry,
+	NPM_OFFICIAL_REGISTRY,
+} from "./registry-config.ts";
+import {
+	fetchVersions,
+	getVersions,
+	type VersionMap,
+} from "./versions.ts";
+
+const logger = new Logger("market");
+
+export interface Dependency {
+	/**
+	 * requested semver range
+	 * @example `^1.2.3` -> `1.2.3`
+	 */
+	request: string;
+	/**
+	 * installed package version
+	 * @example `1.2.5`
+	 */
+	resolved?: string | undefined;
+	/** whether it is a workspace package */
+	workspace?: boolean | undefined;
+	/** valid (unsupported) syntax */
+	invalid?: boolean | undefined;
+	/** latest version */
+	latest?: string | undefined;
+}
+
+class Installer extends Service {
+	declare http: HTTP;
+	declare endpoint: string | undefined;
+	public fullCache: Dict<VersionMap> = {};
+	public tempCache: Dict<VersionMap> = {};
+
+	private pkgTasks: Dict<Promise<VersionMap>> = {};
+	private manifest: LocalPackage;
+	declare private depTask: Promise<Dict<Dependency>>;
+	private flushData: () => void;
+
+	override config: Installer.Config;
+
+	constructor(ctx: Context, config: Installer.Config) {
+		super(ctx, "installer");
+		this.config = config;
+		this.manifest = loadManifest(this.cwd);
+		this.flushData = ctx.throttle(() => {
+			ctx
+				.get("console")
+				?.broadcast("market/registry", this.tempCache);
+			this.tempCache = {};
+		}, 500);
+	}
+
+	get cwd() {
+		return this.ctx.baseDir;
+	}
+
+	override async start() {
+		const { endpoint, timeout } = this.config;
+		this.endpoint =
+			endpoint ??
+			getLocalRegistry(this.cwd) ??
+			NPM_OFFICIAL_REGISTRY;
+		const options: HTTP.Config = {};
+		if (this.endpoint) options.endpoint = this.endpoint;
+		if (timeout !== undefined) options.timeout = timeout;
+		this.http = this.ctx.http.extend(options);
+	}
+
+	resolveName(name: string) {
+		if (name.startsWith("@koishijs/plugin-")) return [name];
+		if (name.match(/(^|\/)koishi-plugin-/)) return [name];
+		if (name[0] === "@") {
+			const [left, right] = name.split("/");
+			return [`${left}/koishi-plugin-${right}`];
+		} else {
+			return [
+				`@koishijs/plugin-${name}`,
+				`koishi-plugin-${name}`,
+			];
+		}
+	}
+
+	async findVersion(names: string[]) {
+		const entries = await Promise.all(
+			names.map(async (name) => {
+				try {
+					const versions = Object.entries(
+						await this.getPackage(name),
+					);
+					const [latest] = versions;
+					if (!latest) return undefined;
+					return { [name]: latest[0] };
+				} catch {
+					return undefined;
+				}
+			}),
+		);
+		return entries.find(
+			(entry): entry is Dict<string> => entry !== undefined,
+		);
+	}
+
+	private async _getPackage(name: string) {
+		try {
+			const versions = await fetchVersions(this.http, name);
+			this.fullCache[name] = this.tempCache[name] =
+				versions;
+			this.flushData();
+			return versions;
+		} catch (error) {
+			logger.warn(error);
+			return {};
+		}
+	}
+
+	setPackage(name: string, versions: RemotePackage[]) {
+		this.fullCache[name] = this.tempCache[name] =
+			getVersions(versions);
+		this.flushData();
+		this.pkgTasks[name] = Promise.resolve(
+			this.fullCache[name],
+		);
+	}
+
+	getPackage(name: string) {
+		return (this.pkgTasks[name] ||= this._getPackage(name));
+	}
+
+	private async _getDeps() {
+		const result = valueMap(
+			this.manifest.dependencies,
+			(request) => {
+				return {
+					request: request.replace(/^[~^]/, ""),
+				} as Dependency;
+			},
+		);
+		await mapLimit(
+			Object.keys(result),
+			10,
+			async (name) => {
+				const dep = result[name];
+				if (!dep) return;
+				try {
+					// some dependencies may be left with no local installation
+					const meta = loadManifest(name);
+					dep.resolved = meta.version;
+					dep.workspace = meta.$workspace;
+					if (meta.$workspace) return;
+				} catch {}
+
+				if (!valid(dep.request)) {
+					dep.invalid = true;
+				}
+
+				const versions = await this.getPackage(name);
+				if (versions) dep.latest = Object.keys(versions)[0];
+			},
+		);
+		return result;
+	}
+
+	getDeps() {
+		return (this.depTask ||= this._getDeps());
+	}
+
+	refreshData() {
+		this.ctx.get("console")?.refresh("registry");
+		this.ctx.get("console")?.refresh("packages");
+	}
+
+	refresh(refresh = false) {
+		this.pkgTasks = {};
+		this.fullCache = {};
+		this.tempCache = {};
+		this.depTask = this._getDeps();
+		if (!refresh) return;
+		this.refreshData();
+	}
+
+	async exec(args: string[]) {
+		// Bun-first：CE 生态只存在 bun 这一种包管理器，直接驱动 bun 执行
+		// 安装（上游经 which-pm-runs 探测 npm/yarn/bun，此处固定为 bun）
+		args.unshift("install");
+		return runBun(args, this.cwd);
+	}
+
+	async override(deps: Dict<string | null>) {
+		this.manifest = await writeManifest(this.cwd, deps);
+	}
+
+	private _install() {
+		const args: string[] = [];
+		if (this.endpoint) {
+			args.push("--registry", this.endpoint);
+		}
+		return this.exec(args);
+	}
+
+	private _getLocalDeps(override: Dict<string | null>) {
+		return valueMap(override, (request, name) => {
+			const dep = { request } as Dependency;
+			try {
+				const meta = loadManifest(name);
+				dep.resolved = meta.version;
+				dep.workspace = meta.$workspace;
+			} catch {}
+			return dep;
+		});
+	}
+
+	async install(
+		deps: Dict<string | null>,
+		forced?: boolean,
+	) {
+		const localDeps = this._getLocalDeps(deps);
+		await this.override(deps);
+
+		let shouldInstall = forced === true;
+		for (const name in deps) {
+			const request = deps[name];
+			const local = localDeps[name];
+			if (
+				local?.workspace ||
+				(request &&
+					local?.resolved &&
+					satisfies(local.resolved, request, {
+						includePrerelease: true,
+					}))
+			)
+				continue;
+			shouldInstall = true;
+			break;
+		}
+
+		if (shouldInstall) {
+			const code = await this._install();
+			if (code) return code;
+			// isolated 布局的增量安装可能漏建新包目录的依赖链接(机理
+			// 见 integrity.ts 模块注释):装完即校验,缺失时补跑一次
+			// 安装——bun 按磁盘实际状态重建链接,秒级自愈,无需人工
+			const missing = findMissingDeps(this.cwd, deps);
+			if (missing.length) {
+				logger.warn(
+					`检测到增量安装未建立部分依赖链接(isolated 布局已知缺陷),正在补装: ${missing.join("; ")}`,
+				);
+				const retry = await this._install();
+				if (retry) return retry;
+				if (findMissingDeps(this.cwd, deps).length) {
+					logger.warn(
+						"自动补装后依赖链接仍不完整,请在项目根目录运行 bun install --force 并重启 koishi",
+					);
+				}
+			}
+		}
+
+		this.refresh();
+		const newDeps = await this.getDeps();
+		for (const name in localDeps) {
+			const local = localDeps[name];
+			const newDep = newDeps[name];
+			if (!local || !newDep || local.workspace) continue;
+			if (newDep.resolved === local.resolved) continue;
+			// 版本变化且旧版本仍驻留内存时才需要整进程重载（判定不走
+			// 解析 API，规避 Bun 负缓存，见 isResidentInCache）
+			if (isResidentInCache(name))
+				this.ctx.loader.fullReload();
+		}
+		this.refreshData();
+
+		return 0;
+	}
+
+	// erasableSyntaxOnly 禁止含运行时值的 namespace，
+	// 原 namespace 内的 Config 常量移到此处的静态字段，对外形状不变
+	static Config: Schema<Installer.Config> = Schema.object({
+		endpoint: Schema.string().role("link"),
+		timeout: Schema.number()
+			.role("time")
+			.default(Time.second * 5),
+	}); // TODO .hidden()
+}
+
+declare namespace Installer {
+	export interface Config {
+		endpoint?: string;
+		timeout?: number;
+	}
+}
+
+export default Installer;

package/src/node/installer/integrity.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 安装完整性校验：Bun isolated 布局的增量安装缺陷防御。
+ *
+ * 背景（2026-09-07 实证）：升级插件时包目录 hash 变化，而其依赖的解析
+ * 结果未变，bun 的增量安装跳过新包目录内的依赖链接建立——插件入口（顶层
+ * symlink）可加载，内部依赖的 require 却炸 MODULE_NOT_FOUND；此时补跑一次
+ * 普通 bun install，bun 按磁盘实际状态检测到包不完整即重建链接（秒级）。
+ * 本模块只负责「发现问题」，补救（补装、告警）由 installer 侧完成。
+ *
+ * 全程只走 existsSync / readFileSync / realpathSync，不触碰解析 API
+ * （防父目录快照缓存，与 registry 的 resolvePackageJson 同一纪律）。
+ */
+import {
+	existsSync,
+	readFileSync,
+	realpathSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { Dict } from "@koishi-ce/koishi";
+import type { LocalPackage } from "./manifest.ts";
+
+/**
+ * 从 fromDir 沿 node_modules 链纯 fs 探测依赖包,命中返回其真实目录。
+ * realpath 化是 isolated 布局的关键:顶层条目是 symlink,包的依赖链接
+ * 挂在 .bun 真实目录的同级 node_modules,从链接路径向上爬会错误地查
+ * 顶层(isolated 不提升传递依赖)。
+ */
+function probePackage(
+	fromDir: string,
+	name: string,
+): string | undefined {
+	let dir = resolve(fromDir);
+	for (;;) {
+		const manifestPath = join(
+			dir,
+			"node_modules",
+			name,
+			"package.json",
+		);
+		if (existsSync(manifestPath)) {
+			try {
+				return dirname(realpathSync(manifestPath));
+			} catch {
+				return undefined;
+			}
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
+}
+
+/**
+ * 从本次安装的包出发递归纯 fs 探测依赖可达性，返回「包: 缺失依赖」描述
+ * 列表。peer / optional 依赖由宿主或按需提供不入校验；workspace / alias
+ * 等非 semver 声明的落盘名与键名无直接映射，同样跳过。
+ *
+ * @param root 项目根目录
+ * @param deps 依赖增删清单（值为 null 表示卸载该依赖）
+ */
+export function findMissingDeps(
+	root: string,
+	deps: Dict<string | null>,
+): string[] {
+	const problems: string[] = [];
+	const visited = new Set<string>();
+	const walk = (dir: string, label: string) => {
+		if (visited.has(dir)) return;
+		visited.add(dir);
+		let manifest: LocalPackage;
+		try {
+			manifest = JSON.parse(
+				readFileSync(join(dir, "package.json"), "utf8"),
+			) as LocalPackage;
+		} catch {
+			return;
+		}
+		for (const [dep, request] of Object.entries(
+			manifest.dependencies ?? {},
+		)) {
+			if (request.includes(":")) continue;
+			const depDir = probePackage(dir, dep);
+			if (!depDir) {
+				problems.push(`${label} 的依赖 ${dep} 未被链接`);
+				continue;
+			}
+			walk(depDir, `${label} → ${dep}`);
+		}
+	};
+	for (const name in deps) {
+		const request = deps[name];
+		if (!request || request.includes(":")) continue;
+		const dir = probePackage(root, name);
+		// 顶层包未落盘属于安装失败,由退出码与后续加载告警兜底,
+		// 不属于「包已装但链接缺失」的补装场景
+		if (!dir) continue;
+		walk(dir, name);
+	}
+	return problems;
+}

package/src/node/installer/manifest.ts

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 项目根 package.json（安装清单）的读写与护栏判定。
+ *
+ * 只做纯 fs 的清单操作，与 registry 的交互（版本探测、http 缓存）无关，
+ * 故独立于 installer 服务；依赖链接的探测属安装完整性校验，见
+ * ./integrity.ts。
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+	type Dict,
+	defineProperty,
+} from "@koishi-ce/koishi";
+import {
+	type PackageJson,
+	resolvePackageJson,
+} from "@koishi-ce/registry";
+
+/** 本地 package.json 的解析结果；dependencies 由归一化保证必有 */
+export interface LocalPackage extends PackageJson {
+	private?: boolean;
+	$workspace?: boolean;
+	dependencies: Record<string, string>;
+}
+
+/**
+ * 判断依赖声明是否受护栏保护、不可被安装清单覆盖或删除。两类：
+ * - `workspace:` 声明是本仓库（monorepo）对上游名的归属（如 koishi
+ *   裸名 shim，见 packages/shim/koishi）；
+ * - `npm:@koishi-ce/...` alias 是下游脚手架生成项目对上游名的归属
+ *   （如 "koishi": "npm:@koishi-ce/koishi-shim@^4.18.11"，见
+ *   packages/shim/koishi-shim）。
+ * 两者被覆盖或删除都会让 peer 解析失去归属，重新拉下 npm 官方包形成
+ * 第二份框架副本。
+ */
+function isGuardedRequest(
+	request: string | undefined,
+): boolean {
+	return (
+		request?.startsWith("workspace:") === true ||
+		request?.startsWith("npm:@koishi-ce") === true
+	);
+}
+
+export function loadManifest(name: string): LocalPackage {
+	// resolvePackageJson 以纯 fs 探测为主路径：市场安装流程在包落盘前的
+	// 探测不能触碰解析 API，否则触发 Bun 的父目录快照缓存（装完即失败）
+	const filename = resolvePackageJson(name);
+	const meta: LocalPackage = JSON.parse(
+		readFileSync(filename, "utf8"),
+	);
+	meta.dependencies ||= {};
+	defineProperty(
+		meta,
+		"$workspace",
+		!filename.includes("node_modules"),
+	);
+	return meta;
+}
+
+/**
+ * 把依赖增删写回项目根 package.json，返回写回后的清单。
+ *
+ * 现读现写：调用方持有的清单原为构造期的启动快照，运行期间根
+ * package.json 可能已被外部更新，基于快照整体重写会抹掉变更，故此处
+ * 重新读盘。受护栏保护的声明（见 isGuardedRequest）既不覆盖也不删除。
+ *
+ * @param cwd 项目根目录
+ * @param deps 依赖增删清单（值为 null 表示卸载该依赖）
+ */
+export async function writeManifest(
+	cwd: string,
+	deps: Dict<string | null>,
+): Promise<LocalPackage> {
+	const filename = resolve(cwd, "package.json");
+	const manifest: LocalPackage = JSON.parse(
+		readFileSync(filename, "utf8"),
+	);
+	manifest.dependencies ||= {};
+	for (const key in deps) {
+		if (deps[key]) {
+			if (isGuardedRequest(manifest.dependencies[key])) {
+				continue;
+			}
+			manifest.dependencies[key] = deps[key];
+		} else if (
+			!isGuardedRequest(manifest.dependencies[key])
+		) {
+			delete manifest.dependencies[key];
+		}
+	}
+	manifest.dependencies = Object.fromEntries(
+		Object.entries(manifest.dependencies).sort((a, b) =>
+			a[0].localeCompare(b[0]),
+		),
+	);
+	// 仓库格式权威是 biome（tab 缩进），按 tab 写出避免装插件后
+	// package.json 被重排成空格、lint 报格式漂移
+	await Bun.write(
+		filename,
+		`${JSON.stringify(manifest, null, "\t")}\n`,
+	);
+	return manifest;
+}

package/src/node/installer/registry-config.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 本机 npm registry 配置探测（零子进程）。
+ *
+ * 实现已收敛到 @koishi-ce/utils 的 npm-registry 模块（与 create-koishi-ce
+ * 的 registry.ts 共享同一实现），此处按原公共 API 再导出；官方源回落由
+ * installer 在调用处以 NPM_OFFICIAL_REGISTRY 兜底，保证 http 恒有
+ * endpoint 可拼接相对 URL——缺省时相对请求会在 resolveURL 抛 Invalid URL。
+ */
+export {
+	getLocalRegistry,
+	NPM_OFFICIAL_REGISTRY,
+} from "@koishi-ce/utils";

package/src/node/installer/versions.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 远端包版本探测与归一化。
+ *
+ * 从 registry 取回版本数组后，过滤掉与当前框架不兼容的版本，再归一化为
+ * 「版本号 → peer 依赖声明 / 弃用标记」的映射并按版本号降序排列（首项即
+ * 最新版）。纯 IO + 纯函数，不持有服务状态；缓存与去重由 installer 侧负责。
+ */
+import {
+	type Dict,
+	type HTTP,
+	pick,
+} from "@koishi-ce/koishi";
+import Scanner, {
+	type DependencyMetaKey,
+	type Registry,
+	type RemotePackage,
+} from "@koishi-ce/registry";
+import { compare, satisfies } from "semver";
+
+/** 归一化后的版本表：版本号 → 依赖元信息（键序即降序，首项为最新版） */
+export type VersionMap = Dict<
+	Pick<RemotePackage, DependencyMetaKey>
+>;
+
+/** 把 registry 返回的版本数组归一化并降序排列 */
+export function getVersions(
+	versions: RemotePackage[],
+): VersionMap {
+	return Object.fromEntries(
+		versions
+			.map(
+				(item) =>
+					[
+						item.version,
+						pick(item, [
+							"peerDependencies",
+							"peerDependenciesMeta",
+							"deprecated",
+						]),
+					] as const,
+			)
+			.sort(([a], [b]) => compare(b, a)),
+	);
+}
+
+/**
+ * 取回单个包的可用版本表（已过滤不兼容版本）。
+ *
+ * 兼容性口径：`koishi` 本体按 4.x 判定；其余包若确认为插件则要求与
+ * 4.x 兼容（Scanner 的判定基于包名与 remote 元信息）。
+ *
+ * @throws 网络或 registry 响应异常时向上抛出，由调用方决定日志口径
+ */
+export async function fetchVersions(
+	http: HTTP,
+	name: string,
+): Promise<VersionMap> {
+	const registry = await http.get<Registry>(`/${name}`);
+	return getVersions(
+		Object.values(registry.versions).filter((remote) => {
+			if (name === "koishi")
+				return satisfies(remote.version, "4");
+			return (
+				!Scanner.isPlugin(name) ||
+				Scanner.isCompatible("4", remote)
+			);
+		}),
+	);
+}