@koishi-ce/plugin-market 1.1.4 → 1.3.0

package/src/{__tests__ → node/__tests__}/provider.test.ts

@@ -25,7 +25,7 @@ import {
 } from "./helpers.ts";
 
 const { default: Installer } = await import(
-	"../node/installer/index.ts"
+	"../installer/index.ts"
 );
 
 beforeAll(startApp);
@@ -202,16 +202,31 @@ describe("MarketProvider 市场数据服务", () => {
 		);
 	});
 
-	it("依赖 / 注册表数据服务读取安装器缓存", async () => {
-		const dependencies = await app
-			.get("console.services.dependencies")
-			?.get();
+	it("依赖服务两拍推送:快照先行、元数据完成后填充", async () => {
+		const service = app.get(
+			"console.services.dependencies",
+		);
+		expect(service).toBeDefined();
+		const first = await service?.get();
+		// 第一拍:本地快照先行,元数据尚在拉取
 		expect(
-			dependencies?.["koishi-plugin-demo"]?.request,
+			first?.["koishi-plugin-demo"]?.request,
 		).toBeTruthy();
+		// 等元数据拉取完成(本地 registry 桩,秒级内):条目就地填充
+		await new Promise((resolve) =>
+			setTimeout(resolve, 800),
+		);
+		expect(first?.["koishi-plugin-demo"]?.latest).toBe(
+			"2.0.0",
+		);
 		expect(
-			dependencies?.["koishi-plugin-demo"]?.latest,
-		).toBe("2.0.0");
+			first?.["koishi-plugin-demo"]?.fetching,
+		).toBeUndefined();
+		// 第二拍 get() 复用上一轮结果,不再拉取
+		const second = await service?.get();
+		expect(second?.["koishi-plugin-demo"]?.latest).toBe(
+			"2.0.0",
+		);
 
 		const registry = await app
 			.get("console.services.registry")
@@ -221,6 +236,55 @@ describe("MarketProvider 市场数据服务", () => {
 		).toContain("2.0.0");
 	});
 
+	itQuiet(
+		"registry 无此包的条目两拍后标记 not-found 负缓存",
+		async () => {
+			// 向宿主清单添加一个 registry 桩里不存在的依赖
+			const manifestPath = join(tmp, "package.json");
+			const manifest = JSON.parse(
+				await Bun.file(manifestPath).text(),
+			) as {
+				dependencies: Record<string, string>;
+			};
+			manifest.dependencies["koishi-plugin-ghost"] =
+				"^1.0.0";
+			await Bun.write(
+				manifestPath,
+				JSON.stringify(manifest, null, "\t"),
+			);
+			try {
+				const service = app.get(
+					"console.services.dependencies",
+				);
+				const snapshot = await service?.get();
+				expect(
+					snapshot?.["koishi-plugin-ghost"]?.request,
+				).toBe("1.0.0");
+				await new Promise((resolve) =>
+					setTimeout(resolve, 800),
+				);
+				expect(
+					snapshot?.["koishi-plugin-ghost"]?.error,
+				).toBe("not-found");
+				// 404 负缓存:重建快照仍标记 not-found 且不再拉取
+				const again = await service?.get();
+				expect(again?.["koishi-plugin-ghost"]?.error).toBe(
+					"not-found",
+				);
+				expect(
+					again?.["koishi-plugin-ghost"]?.fetching,
+				).toBeUndefined();
+			} finally {
+				delete manifest.dependencies["koishi-plugin-ghost"];
+				await Bun.write(
+					manifestPath,
+					JSON.stringify(manifest, null, "\t"),
+				);
+			}
+		},
+		15000,
+	);
+
 	itQuiet(
 		"搜索接口失败时 get 返回空数据与错误标记",
 		async () => {

package/src/node/dependencies/service.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 依赖管理数据服务（`dependencies` 通道）。
+ *
+ * 单向数据流的 node 侧源头：get() 同步构建本地快照（纯磁盘读取）先行
+ * 推送（条目带 fetching 标记），随后在后台并发拉取 registry 元数据填充
+ * latest / error，完成后触发通道刷新二拍推送——前端首屏因此有明确的
+ * 「加载中」态，不会把未拉取完的条目误显示为错误。
+ *
+ * node 侧并发纪律（对标参照实现）：
+ * - 单飞去重：元数据刷新任务同一时刻至多一个，并发调用复用同一任务；
+ * - 循环重扫：刷新循环每轮从快照里重新收集 fetching 条目，期间新的
+ *   get()（安装完成、客户端接入）带来的新条目自动被后续轮次接管，
+ *   不会因单飞复用旧任务而漏拉；
+ * - 过期不覆盖：拉取完成后若快照代次已更新，跳过通道刷新（新循环
+ *   完成后自会推送）。
+ */
+import { DataService } from "@koishi-ce/console";
+import type { Context, Dict } from "@koishi-ce/koishi";
+import { mapLimit } from "@koishi-ce/registry";
+import { loadManifest } from "../installer/manifest.ts";
+import {
+	collectDependencyRequests,
+	resolveLocalDependency,
+} from "./snapshot.ts";
+import type { Dependency } from "./types.ts";
+
+/** registry 元数据并发拉取上限 */
+const CONCURRENCY = 4;
+
+export class DependencyService extends DataService<
+	Dict<Dependency>
+> {
+	// 基类 DataService 声明了 console 注入，子类覆盖须一并保留
+	static override inject = ["console", "installer"];
+
+	/** 快照代次：每次 get() 自增，用于判定后台刷新结果是否已过期 */
+	private serial = 0;
+	/** 进行中的元数据刷新任务（单飞去重） */
+	declare private task: Promise<void> | undefined;
+	/** 最近一轮快照（新快照构建时复用 latest 与 404 负缓存） */
+	private snapshot: Dict<Dependency> = {};
+
+	constructor(ctx: Context) {
+		super(ctx, "dependencies", { authority: 4 });
+	}
+
+	override async get() {
+		this.serial++;
+		const manifest = loadManifest(this.ctx.baseDir);
+		const snapshot = collectDependencyRequests(
+			manifest.dependencies,
+		);
+		for (const [name, dep] of Object.entries(snapshot)) {
+			resolveLocalDependency(name, dep, {
+				previous: this.snapshot[name],
+			});
+		}
+		this.snapshot = snapshot;
+		this.ensureMetadata();
+		return snapshot;
+	}
+
+	private ensureMetadata() {
+		if (this.task) return;
+		this.task = this.refreshMetadata().finally(() => {
+			this.task = undefined;
+		});
+	}
+
+	/**
+	 * 元数据刷新循环：拉完本轮全部 fetching 条目后，若快照代次未变则
+	 * 触发通道刷新（二拍推送）；代次已变（期间有新的 get()）则重扫
+	 * fetching 条目继续，直到无新增且代次一致。
+	 */
+	private async refreshMetadata() {
+		for (;;) {
+			const serial = this.serial;
+			const targets = Object.entries(this.snapshot)
+				.filter(([, dep]) => dep.fetching)
+				.map(([name]) => name);
+			if (!targets.length) return;
+			await mapLimit(targets, CONCURRENCY, async (name) => {
+				await this.resolveMetadata(name);
+			});
+			if (serial !== this.serial) continue;
+			// 版本表经 registry 通道下发（版本下拉消费），一并刷新
+			this.ctx.get("console")?.refresh("dependencies");
+			this.ctx.get("console")?.refresh("registry");
+			return;
+		}
+	}
+
+	/** 单个条目的元数据解析：拉取版本表并填充 latest / error。 */
+	private async resolveMetadata(name: string) {
+		const dep = this.snapshot[name];
+		if (!dep?.fetching) return;
+		const installer = this.ctx.installer;
+		// getPackage 内部单飞去重并写 fullCache；失败也 resolve 空表
+		const versions = await installer.getPackage(name);
+		delete dep.fetching;
+		if (!Object.keys(versions).length) {
+			// 拉取失败：404 归类 not-found（负缓存），其余为网络错误
+			dep.error = installer.pkgErrors[name]?.notFound
+				? "not-found"
+				: "network";
+			delete dep.latest;
+			return;
+		}
+		const [latest] = Object.keys(versions);
+		if (latest !== undefined) dep.latest = latest;
+	}
+}

package/src/node/dependencies/snapshot.test.ts

@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+import { describe, expect, it } from "bun:test";
+import {
+	mkdirSync,
+	mkdtempSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	collectDependencyRequests,
+	resolveLocalDependency,
+} from "./snapshot.ts";
+import type { Dependency } from "./types.ts";
+
+/** 造一个临时宿主目录,并在 node_modules 内放置指定包的清单。 */
+function setupHost(installed: Record<string, string> = {}) {
+	const cwd = mkdtempSync(join(tmpdir(), "deps-snapshot-"));
+	for (const [name, version] of Object.entries(installed)) {
+		const dir = join(cwd, "node_modules", name);
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(
+			join(dir, "package.json"),
+			JSON.stringify({ name, version }),
+		);
+	}
+	process.chdir(cwd);
+	return () => {
+		process.chdir(join(cwd, ".."));
+		rmSync(cwd, { recursive: true, force: true });
+	};
+}
+
+describe("collectDependencyRequests", () => {
+	it("以依赖声明为底建骨架并剥掉 ^/~ 前缀", () => {
+		const result = collectDependencyRequests({
+			"koishi-plugin-demo": "^1.2.3",
+			cosmokit: "~1.8.0",
+			pinned: "2.0.0",
+		});
+		expect(result["koishi-plugin-demo"]).toEqual({
+			request: "1.2.3",
+			fetching: true,
+		});
+		expect(result["cosmokit"]?.request).toBe("1.8.0");
+		expect(result["pinned"]?.request).toBe("2.0.0");
+		// 元数据全部置为待拉取
+		expect(result["pinned"]?.fetching).toBe(true);
+	});
+});
+
+describe("resolveLocalDependency", () => {
+	it("补已装版本并保持待拉取形态", () => {
+		const teardown = setupHost({ "pkg-a": "1.0.0" });
+		try {
+			const dep: Dependency = {
+				request: "1.0.0",
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-a", dep, {
+				previous: undefined,
+			});
+			expect(dep.resolved).toBe("1.0.0");
+			expect(dep.workspace).toBe(false);
+			expect(dep.invalid).toBeUndefined();
+			// 已装且合法 semver:继续等待元数据刷新
+			expect(dep.fetching).toBe(true);
+		} finally {
+			teardown();
+		}
+	});
+
+	it("未安装的包 resolved 留空、不标 invalid", () => {
+		const teardown = setupHost();
+		try {
+			const dep: Dependency = {
+				request: "1.0.0",
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-missing", dep, {
+				previous: undefined,
+			});
+			expect(dep.resolved).toBeUndefined();
+			expect(dep.invalid).toBeUndefined();
+			expect(dep.fetching).toBe(true);
+		} finally {
+			teardown();
+		}
+	});
+
+	it("npm: 钉名别名标 alias、不判 invalid 且不参与拉取", () => {
+		const teardown = setupHost({ koishi: "4.18.11" });
+		try {
+			const dep: Dependency = {
+				request: "npm:@koishi-ce/koishi-shim@^4.18.11",
+				fetching: true,
+			};
+			resolveLocalDependency("koishi", dep, {
+				previous: undefined,
+			});
+			expect(dep.alias).toBe(true);
+			expect(dep.resolved).toBe("4.18.11");
+			expect(dep.invalid).toBeUndefined();
+			// 钉名包无更新可言:不进入 registry 元数据拉取
+			expect(dep.fetching).toBeUndefined();
+		} finally {
+			teardown();
+		}
+	});
+
+	it("非精确 semver 的请求标记 invalid 且不参与拉取", () => {
+		const teardown = setupHost();
+		try {
+			const dep: Dependency = {
+				request: "file:./plugins/foo",
+				fetching: true,
+			};
+			resolveLocalDependency("local-thing", dep, {
+				previous: undefined,
+			});
+			expect(dep.invalid).toBe(true);
+			expect(dep.fetching).toBeUndefined();
+		} finally {
+			teardown();
+		}
+	});
+
+	it("上一轮 latest 与 404 负缓存被复用,网络错误不沿用", () => {
+		const teardown = setupHost({ "pkg-a": "1.0.0" });
+		try {
+			const base = { request: "1.0.0", resolved: "1.0.0" };
+			// latest 复用:fetching 随之消除
+			const withLatest: Dependency = {
+				...base,
+				fetching: true,
+				latest: "2.0.0",
+			};
+			resolveLocalDependency("pkg-a", withLatest, {
+				previous: { ...base, latest: "2.0.0" },
+			});
+			expect(withLatest.latest).toBe("2.0.0");
+			expect(withLatest.fetching).toBeUndefined();
+
+			// not-found 复用(会话内不再重试)
+			const notFound: Dependency = {
+				...base,
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-a", notFound, {
+				previous: { ...base, error: "not-found" },
+			});
+			expect(notFound.error).toBe("not-found");
+			expect(notFound.fetching).toBeUndefined();
+
+			// 网络错误不沿用:下一轮重新拉取
+			const network: Dependency = {
+				...base,
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-a", network, {
+				previous: { ...base, error: "network" },
+			});
+			expect(network.error).toBeUndefined();
+			expect(network.fetching).toBe(true);
+		} finally {
+			teardown();
+		}
+	});
+
+	it("request 或 resolved 变化的条目不复用上一轮结果", () => {
+		const teardown = setupHost({ "pkg-a": "1.5.0" });
+		try {
+			const dep: Dependency = {
+				request: "1.5.0",
+				fetching: true,
+			};
+			resolveLocalDependency("pkg-a", dep, {
+				previous: {
+					request: "1.0.0",
+					resolved: "1.0.0",
+					latest: "2.0.0",
+					error: "not-found",
+				},
+			});
+			expect(dep.latest).toBeUndefined();
+			expect(dep.error).toBeUndefined();
+			expect(dep.fetching).toBe(true);
+		} finally {
+			teardown();
+		}
+	});
+});

package/src/node/dependencies/snapshot.ts

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 宿主依赖本地快照的构建纯函数。
+ *
+ * 两步：collectDependencyRequests 以宿主 package.json 的依赖声明为底
+ * 构建骨架；resolveLocalDependency 逐包读 node_modules 补已装版本与
+ * workspace 标记。全程只碰本地磁盘、不发网络请求——registry 元数据由
+ * DependencyService 的刷新阶段另行填充。
+ *
+ * 上一轮条目的复用规则（防闪烁 + 负缓存语义）：
+ * - request 与 resolved 未变时沿用 latest（省一次 registry 往返）；
+ * - 仅 404（not-found）的 error 被沿用（registry 确认无此包，会话内
+ *   不再重试）；网络错误的 error 不沿用，下一轮 get() 会重新拉取。
+ */
+import type { Dict } from "@koishi-ce/koishi";
+import { valid } from "semver";
+import { loadManifest } from "../installer/manifest.ts";
+import type { Dependency } from "./types.ts";
+
+/** 以宿主 dependencies 声明为底构建快照骨架（元数据字段全部置为待拉取）。 */
+export function collectDependencyRequests(
+	dependencies: Record<string, string>,
+): Dict<Dependency> {
+	const result: Dict<Dependency> = {};
+	for (const [name, request] of Object.entries(
+		dependencies,
+	)) {
+		// 剥掉 ^/~ 前缀：后续 valid() 判定与 latest 比较都按精确版本语义进行
+		result[name] = {
+			request: request.replace(/^[~^]/, ""),
+			fetching: true,
+		};
+	}
+	return result;
+}
+
+/** 逐包本地解析所需的上下文：上一轮同名条目（复用 latest 与 404 负缓存）。 */
+export interface LocalResolveContext {
+	previous: Dependency | undefined;
+}
+
+/**
+ * 单个依赖条目的本地解析：已装版本 / workspace 标记 / invalid 标记，
+ * 就地修改传入的 dep。node_modules 内无此包时 resolved 留空，由后续
+ * 元数据刷新阶段补齐。
+ */
+export function resolveLocalDependency(
+	name: string,
+	dep: Dependency,
+	ctx: LocalResolveContext,
+): void {
+	try {
+		// 已装版本读 node_modules 内的 package.json；未安装/读取失败留空
+		const meta = loadManifest(name);
+		dep.resolved = meta.version;
+		dep.workspace = meta.$workspace;
+		if (meta.$workspace) {
+			// workspace 包不参与 registry 拉取与更新判定
+			delete dep.fetching;
+		}
+	} catch {
+		// 尚未安装（或残留声明）：保持待拉取形态
+	}
+
+	if (dep.request.startsWith("npm:")) {
+		// npm: 协议钉名别名（下游 shim 占名）：声明键与真实包名不同是
+		// 设计内行为，语义上等同 workspace——固定钉死、无更新可言
+		dep.alias = true;
+		delete dep.fetching;
+	} else if (!dep.workspace && !valid(dep.request)) {
+		// 非精确 semver 的请求（file: 路径、git/url 串等）：不参与
+		// latest 刷新，前端据此降级展示
+		dep.invalid = true;
+		delete dep.fetching;
+	}
+
+	const { previous } = ctx;
+	if (
+		previous &&
+		previous.request === dep.request &&
+		previous.resolved === dep.resolved
+	) {
+		if (previous.latest) {
+			dep.latest = previous.latest;
+			delete dep.fetching;
+		}
+		// 404 负缓存：registry 已确认无此包，会话内不再重试；
+		// 网络错误不沿用，下一轮 get() 重新拉取
+		if (previous.error === "not-found") {
+			dep.error = "not-found";
+			delete dep.fetching;
+		}
+	}
+}

package/src/node/dependencies/types.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2019-present Shigma and Koishijs contributors.
+// Copyright (c) 2026-present Koishi-CE contributors.
+
+/**
+ * 依赖条目类型定义（dependencies 数据通道的值类型）。
+ *
+ * 单个依赖条目的请求范围、已装版本与来源标记；latest / error / fetching
+ * 三个可选字段由元数据刷新阶段填充，前端依赖页的分类状态机据此判定
+ * 六态。类型集中在此，node 侧声明与 client 侧镜像（console-services.ts）
+ * 均从这里取形状。
+ */
+
+/** registry 元数据拉取失败的归类：404（registry 无此包）与其余（网络等） */
+export type DependencyError = "not-found" | "network";
+
+/** 依赖条目：请求范围、已装版本、来源标记与最新版信息。 */
+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;
+	/**
+	 * npm: 协议钉名别名（下游 shim 占名机制，如
+	 * `npm:@koishi-ce/koishi-shim@^4.18.11`）：设计内形态而非异常，
+	 * 不判 invalid、不参与 registry 元数据拉取与更新判定
+	 */
+	alias?: boolean | undefined;
+	/** valid (unsupported) syntax */
+	invalid?: boolean | undefined;
+	/** latest version */
+	latest?: string | undefined;
+	/** registry 元数据拉取失败的归类（缺失代表尚在拉取或已成功） */
+	error?: DependencyError | undefined;
+	/** 本轮元数据尚未拉取完成（前端据此显示加载中而非错误） */
+	fetching?: boolean | undefined;
+}

package/src/node/deps.ts

@@ -8,19 +8,6 @@ import type {
 	DependencyMetaKey,
 	RemotePackage,
 } from "@koishi-ce/registry";
-import type { Dependency } from "./installer/index.ts";
-
-class DependencyProvider extends DataService<
-	Dict<Dependency>
-> {
-	constructor(ctx: Context) {
-		super(ctx, "dependencies", { authority: 4 });
-	}
-
-	override async get() {
-		return this.ctx.installer.getDeps();
-	}
-}
 
 class RegistryProvider extends DataService<
 	Dict<Dict<Pick<RemotePackage, DependencyMetaKey>>>
@@ -34,4 +21,4 @@ class RegistryProvider extends DataService<
 	}
 }
 
-export { DependencyProvider, RegistryProvider };
+export { RegistryProvider };

package/src/node/index.ts

@@ -16,16 +16,15 @@ import type {
 import { gt } from "semver";
 import messageZhCN from "../../locales/message.zh-CN.yml";
 import schemaZhCN from "../../locales/schema.zh-CN.yml";
-import {
-	DependencyProvider,
-	RegistryProvider,
-} from "./deps.ts";
+import { DependencyService } from "./dependencies/service.ts";
+import type { Dependency } from "./dependencies/types.ts";
+import { RegistryProvider } from "./deps.ts";
 import Installer from "./installer/index.ts";
 import MarketProvider from "./market.ts";
 
 export * from "../shared/index.ts";
-
-export { DependencyProvider, Installer, RegistryProvider };
+export type { Dependency };
+export { DependencyService, Installer, RegistryProvider };
 
 declare module "@koishi-ce/koishi" {
 	interface Context {
@@ -36,7 +35,7 @@ declare module "@koishi-ce/koishi" {
 declare module "@koishi-ce/console" {
 	namespace Console {
 		interface Services {
-			dependencies: DependencyProvider;
+			dependencies: DependencyService;
 			registry: RegistryProvider;
 		}
 	}
@@ -243,7 +242,7 @@ export function apply(ctx: Context, config: Config) {
 	});
 
 	ctx.inject(["console", "installer"], (ctx) => {
-		ctx.plugin(DependencyProvider);
+		ctx.plugin(DependencyService);
 		ctx.plugin(RegistryProvider);
 		ctx.plugin(MarketProvider, config.search);