@openspecui/server 3.6.1 → 3.7.1

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { CliExecutor, CodeEditorThemeSchema, ConfigManager, CustomSoundHashSchema, DASHBOARD_METRIC_KEYS, DashboardConfigSchema, GitConfigSchema, HOSTED_SHELL_PROTOCOL_VERSION, MarkdownParser, NotificationPublishInputSchema, NotificationSettingsSchema, OPENSPECUI_HOOKS_VERSION, OpenSpecAdapter, OpenSpecWatcher, OpsxConfigSchema, OpsxKernel, PtyClientMessageSchema, ReactiveContext, TerminalConfigSchema, TerminalControlParser, TerminalRendererEngineSchema, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, getDetectedProjectTools, getToolInitStates, getWatcherRuntimeStatus, initWatcherPool, isWatcherPoolInitialized, resolveTerminalShellDefaults, sniffGlobalCli, subscribeWatcherRuntimeStatus, terminalNotificationEventToPublishInput } from "@openspecui/core";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { CliExecutor, CodeEditorThemeSchema, ConfigManager, CustomSoundHashSchema, DASHBOARD_METRIC_KEYS, DashboardConfigSchema, DocumentTranslationConfigSchema, GitConfigSchema, GlobalSettingsManager, MarkdownParser, NotificationPublishInputSchema, NotificationSettingsSchema, OPENSPECUI_HOOKS_VERSION, OpenSpecAdapter, OpenSpecUIGlobalSettingsSchema, OpenSpecWatcher, OpsxConfigSchema, OpsxKernel, PtyClientMessageSchema, ReactiveContext, TerminalConfigSchema, TerminalControlParser, TerminalRendererEngineSchema, TranslationCacheReadInputSchema, TranslationCacheSettingsSchema, TranslationCacheWriteInputSchema, buildBackendHealthPayload, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, getDetectedProjectTools, getToolInitStates, getWatcherRuntimeStatus, initWatcherPool, isWatcherPoolInitialized, parseOpsxEntityMetadata, parseOpsxSchemaDetail, resolveTerminalShellDefaults, sniffGlobalCli, subscribeWatcherRuntimeStatus, terminalNotificationEventToPublishInput } from "@openspecui/core";
+import { basename, dirname, join, matchesGlob, relative, resolve, sep } from "node:path";
 import { access, mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createServer as createServer$1 } from "node:net";
@@ -12,7 +12,7 @@ import { readFileSync } from "node:fs";
 import { WebSocketServer } from "ws";
 import { CustomSoundHashSchema as CustomSoundHashSchema$1, CustomSoundIdSchema, CustomSoundMetadataFileSchema, customHashFromSoundId, soundIdFromCustomHash } from "@openspecui/core/sounds";
 import { createHash } from "node:crypto";
-import { homedir } from "node:os";
+import { homedir, platform } from "node:os";
 import { EventEmitter } from "node:events";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -35,6 +35,9 @@ function toErrorDiagnostic$1(error) {
 function isNotNull(value) {
 	return value !== null;
 }
+function normalizeChangeFilePath(path) {
+	return path.replace(/\\/g, "/").replace(/^\/+/, "");
+}
 var DocumentService = class {
 	parser = new MarkdownParser();
 	constructor(projectDir, adapter, hookRuntime) {
@@ -176,37 +179,125 @@ var DocumentService = class {
 			return null;
 		}
 	}
+	async readEntityDetail(stage, changeId, consumer = "view", mode = "processed", options = {}) {
+		const detail = await this.adapter.readEntityDetail(stage, changeId, options);
+		if (!detail) return null;
+		const root = stage === "change" ? `openspec/changes/${changeId}` : `openspec/changes/archive/${changeId}`;
+		const processedByPath = /* @__PURE__ */ new Map();
+		const processArtifactFile = async (artifact, file) => {
+			const artifactFile = {
+				...await this.processEntityFile({
+					stage,
+					changeId,
+					root,
+					file,
+					consumer,
+					mode,
+					schemaName: detail.schemaName,
+					artifactId: artifact.id,
+					artifactOutputPath: artifact.outputPath
+				}),
+				type: "file"
+			};
+			processedByPath.set(file.path, artifactFile);
+			return artifactFile;
+		};
+		const artifacts = await Promise.all(detail.artifacts.map(async (artifact) => ({
+			...artifact,
+			files: await Promise.all(artifact.files.map((file) => processArtifactFile(artifact, file)))
+		})));
+		const files = await Promise.all(detail.files.map(async (file) => {
+			const processed = processedByPath.get(file.path);
+			if (processed) return processed;
+			return this.processEntityFile({
+				stage,
+				changeId,
+				root,
+				file,
+				consumer,
+				mode,
+				schemaName: detail.schemaName
+			});
+		}));
+		const filesByPath = new Map(files.map((file) => [file.path, file]));
+		const ungroupedFiles = detail.ungroupedFiles.map((file) => filesByPath.get(file.path) ?? file);
+		return {
+			...detail,
+			files,
+			artifacts,
+			ungroupedFiles
+		};
+	}
 	async readChangeFiles(changeId, consumer = "view", mode = "processed") {
 		const files = await this.adapter.readChangeFiles(changeId);
 		return this.processChangeFiles("change", changeId, files, consumer, mode);
 	}
+	async readChangeArtifactOutput(changeId, outputPath, consumer = "view", mode = "processed") {
+		const normalizedPath = normalizeChangeFilePath(outputPath);
+		return (await this.readChangeArtifactFiles(changeId, normalizedPath, consumer, mode)).find((file) => file.path === normalizedPath)?.content ?? null;
+	}
+	async readChangeGlobArtifactFiles(changeId, outputPath, consumer = "view", mode = "processed") {
+		const normalizedPattern = normalizeChangeFilePath(outputPath);
+		return this.readChangeArtifactFiles(changeId, normalizedPattern, consumer, mode);
+	}
 	async readArchivedChangeFiles(changeId, consumer = "view", mode = "processed") {
 		const files = await this.adapter.readArchivedChangeFiles(changeId);
 		return this.processChangeFiles("archive", changeId, files, consumer, mode);
 	}
 	async processChangeFiles(stage, changeId, files, consumer, mode) {
 		const root = stage === "change" ? `openspec/changes/${changeId}` : `openspec/changes/archive/${changeId}`;
-		return (await Promise.all(files.map(async (file) => {
-			if (file.type !== "file" || file.content === void 0 || !file.path.endsWith(".md")) return file;
-			const kind = this.inferChangeFileKind(file.path);
-			if (!kind) return file;
-			const result = await this.processDocument({
-				consumer,
-				mode,
-				document: {
-					stage,
-					kind,
-					changeId,
-					relativePath: `${root}/${file.path}`,
-					absolutePath: join(this.projectDir, root, file.path)
-				},
-				source: file.content
-			});
-			return {
-				...file,
-				content: result.markdown
-			};
-		}))).filter(isNotNull);
+		return (await Promise.all(files.map((file) => this.processChangeFile(stage, changeId, root, file, consumer, mode)))).filter(isNotNull);
+	}
+	async readChangeArtifactFiles(changeId, outputPath, consumer, mode) {
+		const matchingFiles = (await this.adapter.readChangeFiles(changeId)).filter((file) => {
+			if (file.type !== "file" || file.content === void 0) return false;
+			return matchesGlob(file.path, outputPath) || file.path === outputPath;
+		});
+		const root = `openspec/changes/${changeId}`;
+		return (await Promise.all(matchingFiles.map((file) => this.processChangeFile("change", changeId, root, file, consumer, mode)))).filter(isNotNull).filter((file) => file.type === "file" && file.content !== void 0);
+	}
+	async processChangeFile(stage, changeId, root, file, consumer, mode) {
+		if (file.type !== "file" || file.content === void 0 || !file.path.endsWith(".md")) return file;
+		const kind = this.inferChangeFileKind(file.path);
+		if (!kind) return file;
+		const result = await this.processDocument({
+			consumer,
+			mode,
+			document: {
+				stage,
+				kind,
+				changeId,
+				relativePath: `${root}/${file.path}`,
+				absolutePath: join(this.projectDir, root, file.path)
+			},
+			source: file.content
+		});
+		return {
+			...file,
+			content: result.markdown
+		};
+	}
+	async processEntityFile(input) {
+		if (input.file.type !== "file" || input.file.content === void 0 || !input.file.path.endsWith(".md")) return input.file;
+		const result = await this.processDocument({
+			consumer: input.consumer,
+			mode: input.mode,
+			document: {
+				stage: input.stage,
+				kind: "artifact",
+				changeId: input.changeId,
+				schemaName: input.schemaName,
+				artifactId: input.artifactId,
+				artifactOutputPath: input.artifactOutputPath,
+				relativePath: `${input.root}/${input.file.path}`,
+				absolutePath: join(this.projectDir, input.root, input.file.path)
+			},
+			source: input.file.content
+		});
+		return {
+			...input.file,
+			content: result.markdown
+		};
 	}
 	inferChangeFileKind(path) {
 		if (path === "proposal.md") return "proposal";
@@ -1194,16 +1285,11 @@ async function loadDashboardOverview(ctx, reason = "dashboard-refresh") {
 		updatedAt: changeMeta.updatedAt
 	}));
 	const activeChanges = selectRecentDashboardItems(allActiveChanges);
-	const archivedChanges = (await Promise.all(archiveMetas.map(async (meta) => {
-		const change = await ctx.adapter.readArchivedChange(meta.id);
-		if (!change) return null;
-		return {
-			id: meta.id,
-			createdAt: meta.createdAt,
-			updatedAt: meta.updatedAt,
-			tasksCompleted: change.tasks.filter((task) => task.completed).length
-		};
-	}))).filter((item) => item !== null);
+	const archivedChanges = archiveMetas.map((meta) => ({
+		id: meta.id,
+		createdAt: meta.createdAt,
+		updatedAt: meta.updatedAt
+	}));
 	const allSpecifications = (await Promise.all(specMetas.map(async (meta) => {
 		const spec = await ctx.adapter.readSpec(meta.id);
 		if (!spec) return null;
@@ -1218,7 +1304,7 @@ async function loadDashboardOverview(ctx, reason = "dashboard-refresh") {
 	const requirements = allSpecifications.reduce((sum, spec) => sum + spec.requirements, 0);
 	const tasksTotal = allActiveChanges.reduce((sum, change) => sum + change.progress.total, 0);
 	const tasksCompleted = allActiveChanges.reduce((sum, change) => sum + change.progress.completed, 0);
-	const archivedTasksCompleted = archivedChanges.reduce((sum, change) => sum + change.tasksCompleted, 0);
+	const archivedTasksCompleted = 0;
 	const taskCompletionPercent = tasksTotal > 0 ? Math.round(tasksCompleted / tasksTotal * 100) : null;
 	const inProgressChanges = allActiveChanges.filter((change) => change.progress.total > 0 && change.progress.completed < change.progress.total).length;
 	const specificationTrendEvents = specMetas.flatMap((spec) => {
@@ -1232,7 +1318,7 @@ async function loadDashboardOverview(ctx, reason = "dashboard-refresh") {
 		const ts = parseDatedIdTimestamp(archive.id) ?? resolveTrendTimestamp(archive.updatedAt, archive.createdAt);
 		return ts === null ? [] : [{
 			ts,
-			value: archive.tasksCompleted
+			value: 1
 		}];
 	});
 	const specMetaById = new Map(specMetas.map((meta) => [meta.id, meta]));
@@ -1339,6 +1425,29 @@ async function loadDashboardOverview(ctx, reason = "dashboard-refresh") {
 	};
 }
 
+//#endregion
+//#region src/entity-read-options.ts
+async function readEntityMetadata(ctx, stage, id) {
+	return (stage === "change" ? await ctx.adapter.readChangeFiles(id) : await ctx.adapter.readArchivedChangeFiles(id)).find((file) => file.type === "file" && file.path === ".openspec.yaml")?.content ?? null;
+}
+async function buildEntityReadOptions(ctx, stage, id) {
+	const schemaName = parseOpsxEntityMetadata(await readEntityMetadata(ctx, stage, id)).schemaName;
+	if (!schemaName) return {};
+	try {
+		await ctx.kernel.waitForWarmup();
+		await ctx.kernel.ensureSchemaDetail(schemaName);
+		await ctx.kernel.ensureSchemaYaml(schemaName);
+		const schemaYaml = ctx.kernel.getSchemaYaml(schemaName);
+		const diagnostics = schemaYaml ? parseOpsxSchemaDetail(schemaYaml, schemaName, { path: `schema:${schemaName}` }).diagnostics : [];
+		return {
+			schemas: { [schemaName]: ctx.kernel.getSchemaDetail(schemaName) },
+			schemaDiagnostics: diagnostics.length > 0 ? { [schemaName]: diagnostics } : void 0
+		};
+	} catch {
+		return { schemas: {} };
+	}
+}
+
 //#endregion
 //#region src/notification-service.ts
 var NotificationService = class {
@@ -1619,8 +1728,8 @@ function detectPtyPlatform() {
 	if (process.platform === "darwin") return "macos";
 	return "common";
 }
-function resolveDefaultShell(platform, env) {
-	if (platform === "windows") return env.ComSpec?.trim() || "cmd.exe";
+function resolveDefaultShell(platform$1, env) {
+	if (platform$1 === "windows") return env.ComSpec?.trim() || "cmd.exe";
 	return env.SHELL?.trim() || "/bin/sh";
 }
 function resolvePtyShellDefaults(opts) {
@@ -2724,6 +2833,20 @@ async function buildGitWorktreeOverview(options) {
 		};
 	});
 }
+async function resolveGitWorktreeSwitchTarget(options) {
+	const resolvedProjectDir = resolve(options.projectDir);
+	const resolvedInputPath = resolve(options.targetPath);
+	const worktrees = await listGitWorktrees(resolvedProjectDir, options.runGit ?? defaultRunGit);
+	for (const worktree of worktrees) {
+		const worktreePath = resolve(worktree.path);
+		if (!await sameGitPath(worktreePath, resolvedInputPath)) continue;
+		return {
+			path: worktreePath,
+			pathAvailable: await pathExists(worktreePath)
+		};
+	}
+	return null;
+}
 async function listCurrentWorktreeGitEntries(options) {
 	const resolvedProjectDir = resolve(options.projectDir);
 	const limit = clampEntryLimit(options.limit);
@@ -2958,6 +3081,35 @@ const soundsRouter = router({
 		return { success: true };
 	})
 });
+const globalSettingsRouter = router({
+	get: publicProcedure.query(({ ctx }) => {
+		return ctx.globalSettingsManager.readSettings();
+	}),
+	update: publicProcedure.input(OpenSpecUIGlobalSettingsSchema.partial().extend({ translationCache: TranslationCacheSettingsSchema.partial().optional() })).mutation(async ({ ctx, input }) => {
+		await ctx.globalSettingsManager.writeSettings(input);
+		return { success: true };
+	}),
+	subscribe: publicProcedure.subscription(({ ctx }) => {
+		return createReactiveSubscription(() => ctx.globalSettingsManager.readSettings());
+	})
+});
+const translationCacheRouter = router({
+	stats: publicProcedure.query(({ ctx }) => {
+		return ctx.translationCacheService.getStats();
+	}),
+	read: publicProcedure.input(TranslationCacheReadInputSchema).query(({ ctx, input }) => {
+		return ctx.translationCacheService.read(input.keyHash);
+	}),
+	write: publicProcedure.input(TranslationCacheWriteInputSchema).mutation(({ ctx, input }) => {
+		return ctx.translationCacheService.write(input);
+	}),
+	clean: publicProcedure.mutation(({ ctx }) => {
+		return ctx.translationCacheService.clean();
+	}),
+	clear: publicProcedure.mutation(({ ctx }) => {
+		return ctx.translationCacheService.clear();
+	})
+});
 const OPSX_CORE_PROFILE_WORKFLOWS = [
 	"propose",
 	"explore",
@@ -3283,19 +3435,21 @@ const archiveRouter = router({
 		return ctx.adapter.listArchivedChangesWithMeta();
 	}),
 	get: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
-		return ctx.documentService.readArchivedChange(input.id);
+		return ctx.documentService.readEntityDetail("archive", input.id, "view", "processed", await buildEntityReadOptions(ctx, "archive", input.id));
 	}),
 	getRaw: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
-		return ctx.adapter.readArchivedChangeRaw(input.id);
+		return ctx.documentService.readEntityDetail("archive", input.id, "view", "source", await buildEntityReadOptions(ctx, "archive", input.id));
 	}),
 	subscribe: publicProcedure.subscription(({ ctx }) => {
 		return createReactiveSubscription(() => ctx.adapter.listArchivedChangesWithMeta());
 	}),
 	subscribeOne: publicProcedure.input(z.object({ id: z.string() })).subscription(({ ctx, input }) => {
-		return createReactiveSubscriptionWithInput((id) => ctx.documentService.readArchivedChange(id))(input.id);
+		return createReactiveSubscriptionWithInput(async (id) => ctx.documentService.readEntityDetail("archive", id, "view", "processed", await buildEntityReadOptions(ctx, "archive", id)))(input.id);
 	}),
 	subscribeFiles: publicProcedure.input(z.object({ id: z.string() })).subscription(({ ctx, input }) => {
-		return createReactiveSubscriptionWithInput((id) => ctx.adapter.readArchivedChangeFiles(id))(input.id);
+		return createReactiveSubscriptionWithInput(async (id) => {
+			return (await ctx.documentService.readEntityDetail("archive", id, "view", "processed", await buildEntityReadOptions(ctx, "archive", id)))?.files ?? [];
+		})(input.id);
 	})
 });
 z.object({
@@ -3397,13 +3551,14 @@ const configRouter = router({
 		terminal: TerminalConfigSchema.omit({ rendererEngine: true }).partial().extend({ rendererEngine: TerminalRendererEngineSchema.optional() }).optional(),
 		dashboard: DashboardConfigSchema.partial().optional(),
 		git: GitConfigSchema.partial().optional(),
-		notifications: NotificationSettingsSchema.partial().optional()
+		notifications: NotificationSettingsSchema.partial().optional(),
+		translation: DocumentTranslationConfigSchema.partial().optional()
 	})).mutation(async ({ ctx, input }) => {
 		const hasCliCommand = input.cli !== void 0 && Object.prototype.hasOwnProperty.call(input.cli, "command");
 		const hasCliArgs = input.cli !== void 0 && Object.prototype.hasOwnProperty.call(input.cli, "args");
 		if (hasCliCommand && !hasCliArgs) {
 			await ctx.configManager.setCliCommand(input.cli?.command ?? "");
-			if (input.theme !== void 0 || input.codeEditor !== void 0 || input.appBaseUrl !== void 0 || input.opsx !== void 0 || input.terminal !== void 0 || input.dashboard !== void 0 || input.git !== void 0 || input.notifications !== void 0) await ctx.configManager.writeConfig({
+			if (input.theme !== void 0 || input.codeEditor !== void 0 || input.appBaseUrl !== void 0 || input.opsx !== void 0 || input.terminal !== void 0 || input.dashboard !== void 0 || input.git !== void 0 || input.notifications !== void 0 || input.translation !== void 0) await ctx.configManager.writeConfig({
 				theme: input.theme,
 				codeEditor: input.codeEditor,
 				appBaseUrl: input.appBaseUrl,
@@ -3411,7 +3566,8 @@ const configRouter = router({
 				terminal: input.terminal,
 				dashboard: input.dashboard,
 				git: input.git,
-				notifications: input.notifications
+				notifications: input.notifications,
+				translation: input.translation
 			});
 			return { success: true };
 		}
@@ -3820,7 +3976,7 @@ const opsxRouter = router({
 	})).query(async ({ ctx, input }) => {
 		await ctx.kernel.waitForWarmup();
 		await ctx.kernel.ensureArtifactOutput(input.changeId, input.outputPath);
-		return ctx.kernel.getArtifactOutput(input.changeId, input.outputPath);
+		return ctx.documentService.readChangeArtifactOutput(input.changeId, input.outputPath, "view", "processed");
 	}),
 	subscribeArtifactOutput: publicProcedure.input(z.object({
 		changeId: z.string(),
@@ -3829,7 +3985,7 @@ const opsxRouter = router({
 		return createReactiveSubscription(async () => {
 			await ctx.kernel.waitForWarmup();
 			await ctx.kernel.ensureArtifactOutput(input.changeId, input.outputPath);
-			return ctx.kernel.getArtifactOutput(input.changeId, input.outputPath);
+			return ctx.documentService.readChangeArtifactOutput(input.changeId, input.outputPath, "view", "processed");
 		});
 	}),
 	readGlobArtifactFiles: publicProcedure.input(z.object({
@@ -3838,7 +3994,7 @@ const opsxRouter = router({
 	})).query(async ({ ctx, input }) => {
 		await ctx.kernel.waitForWarmup();
 		await ctx.kernel.ensureGlobArtifactFiles(input.changeId, input.outputPath);
-		return ctx.kernel.getGlobArtifactFiles(input.changeId, input.outputPath);
+		return ctx.documentService.readChangeGlobArtifactFiles(input.changeId, input.outputPath, "view", "processed");
 	}),
 	subscribeGlobArtifactFiles: publicProcedure.input(z.object({
 		changeId: z.string(),
@@ -3847,7 +4003,7 @@ const opsxRouter = router({
 		return createReactiveSubscription(async () => {
 			await ctx.kernel.waitForWarmup();
 			await ctx.kernel.ensureGlobArtifactFiles(input.changeId, input.outputPath);
-			return ctx.kernel.getGlobArtifactFiles(input.changeId, input.outputPath);
+			return ctx.documentService.readChangeGlobArtifactFiles(input.changeId, input.outputPath, "view", "processed");
 		});
 	}),
 	writeArtifactOutput: publicProcedure.input(z.object({
@@ -4028,14 +4184,10 @@ const gitRouter = router({
 	}),
 	switchWorktree: publicProcedure.input(z.object({ path: z.string().min(1) })).mutation(async ({ ctx, input }) => {
 		if (!ctx.gitWorktreeHandoff) throw new Error("Worktree handoff is unavailable in this runtime.");
-		const overview = await buildGitWorktreeOverview({ projectDir: ctx.projectDir });
-		const resolvedInputPath = resolve(input.path);
-		let target = null;
-		if (overview.currentWorktree && await sameGitPath(overview.currentWorktree.path, resolvedInputPath)) target = overview.currentWorktree;
-		else for (const worktree of overview.otherWorktrees) if (await sameGitPath(worktree.path, resolvedInputPath)) {
-			target = worktree;
-			break;
-		}
+		const target = await resolveGitWorktreeSwitchTarget({
+			projectDir: ctx.projectDir,
+			targetPath: input.path
+		});
 		if (!target) throw new Error("Worktree not found.");
 		if (!target.pathAvailable) throw new Error("Worktree path is no longer available. Remove the stale worktree entry first.");
 		return ctx.gitWorktreeHandoff.ensureWorktreeServer({ targetPath: target.path });
@@ -4053,6 +4205,8 @@ const appRouter = router({
 	init: initRouter,
 	realtime: realtimeRouter,
 	config: configRouter,
+	globalSettings: globalSettingsRouter,
+	translationCache: translationCacheRouter,
 	notifications: notificationsRouter,
 	sounds: soundsRouter,
 	cli: cliRouter,
@@ -4067,7 +4221,7 @@ const appRouter = router({
 function joinParts(parts) {
 	return parts.map((part) => part?.trim() ?? "").filter((part) => part.length > 0).join("\n\n");
 }
-async function collectSearchDocuments(adapter, documentService) {
+async function collectSearchDocuments(adapter, documentService, resolveEntityReadOptions) {
 	const docs = [];
 	const specs = await adapter.listSpecsWithMeta();
 	for (const spec of specs) {
@@ -4104,20 +4258,16 @@ async function collectSearchDocuments(adapter, documentService) {
 	}
 	const archives = await adapter.listArchivedChangesWithMeta();
 	for (const archive of archives) {
-		const raw = documentService ? await documentService.readArchivedChangeRaw(archive.id, "search", "processed") : await adapter.readArchivedChangeRaw(archive.id);
-		if (!raw) continue;
+		const entityOptions = resolveEntityReadOptions ? await resolveEntityReadOptions("archive", archive.id) : void 0;
+		const entity = documentService ? await documentService.readEntityDetail("archive", archive.id, "search", "processed", entityOptions) : await adapter.readEntityDetail("archive", archive.id);
+		if (!entity) continue;
 		docs.push({
 			id: `archive:${archive.id}`,
 			kind: "archive",
 			title: archive.name,
 			href: `/archive/${encodeURIComponent(archive.id)}`,
 			path: `openspec/changes/archive/${archive.id}`,
-			content: joinParts([
-				typeof raw.proposal === "string" ? raw.proposal : raw.proposal.markdown,
-				typeof raw.tasks === "string" ? raw.tasks : raw.tasks.markdown,
-				typeof raw.design === "string" ? raw.design : raw.design?.markdown,
-				...raw.deltaSpecs.map((deltaSpec) => deltaSpec.content)
-			]),
+			content: joinParts(entity.files.filter((file) => file.type === "file").map((file) => file.content)),
 			updatedAt: archive.updatedAt
 		});
 	}
@@ -4133,9 +4283,10 @@ var SearchService = class {
 	initPromise = null;
 	rebuildPromise = null;
 	rebuildTimer = null;
-	constructor(adapter, watcher, provider = new NodeWorkerSearchProvider(), documentService) {
+	constructor(adapter, watcher, provider = new NodeWorkerSearchProvider(), documentService, resolveEntityReadOptions) {
 		this.adapter = adapter;
 		this.documentService = documentService;
+		this.resolveEntityReadOptions = resolveEntityReadOptions;
 		this.provider = provider;
 		watcher?.on("change", () => {
 			this.scheduleRebuild();
@@ -4181,7 +4332,7 @@ var SearchService = class {
 		if (!forceInit && !this.initialized) return;
 		if (this.rebuildPromise) return this.rebuildPromise;
 		this.rebuildPromise = (async () => {
-			const docs = await collectSearchDocuments(this.adapter, this.documentService);
+			const docs = await collectSearchDocuments(this.adapter, this.documentService, this.resolveEntityReadOptions);
 			if (this.initialized) await this.provider.replaceAll(docs);
 			else {
 				await this.provider.init(docs);
@@ -4196,6 +4347,227 @@ var SearchService = class {
 	}
 };
 
+//#endregion
+//#region src/translation-cache-adapter.ts
+var SqliteTranslationCacheAdapter = class {
+	database = null;
+	constructor(databasePath, createDatabase) {
+		this.databasePath = databasePath;
+		this.createDatabase = createDatabase;
+	}
+	async init() {
+		if (this.database) return;
+		await mkdir(dirname(this.databasePath), { recursive: true });
+		const database = this.createDatabase(this.databasePath);
+		database.exec(`
+      CREATE TABLE IF NOT EXISTS translation_cache_entries (
+        key_hash TEXT PRIMARY KEY,
+        cache_key TEXT NOT NULL,
+        source_text TEXT NOT NULL,
+        translated_text TEXT NOT NULL,
+        target_nodes_json TEXT,
+        source_language TEXT NOT NULL,
+        target_language TEXT NOT NULL,
+        placeholder_topology_hash TEXT NOT NULL,
+        attribute_topology_hash TEXT NOT NULL,
+        display_policy_version INTEGER NOT NULL,
+        created_at INTEGER NOT NULL,
+        last_accessed_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS translation_cache_entries_lru_idx
+        ON translation_cache_entries(last_accessed_at ASC);
+    `);
+		ensureTargetNodesJsonColumn(database);
+		this.database = database;
+	}
+	async read(keyHash, now) {
+		const database = await this.requireDatabase();
+		const row = database.prepare(`SELECT key_hash, cache_key, source_text, translated_text, target_nodes_json, source_language,
+          target_language, placeholder_topology_hash, attribute_topology_hash,
+          display_policy_version, created_at, last_accessed_at
+        FROM translation_cache_entries
+        WHERE key_hash = ?`).get(keyHash);
+		if (!isSqliteTranslationCacheRow(row)) return null;
+		database.prepare("UPDATE translation_cache_entries SET last_accessed_at = ? WHERE key_hash = ?").run(now, keyHash);
+		return {
+			keyHash: row.key_hash,
+			key: row.cache_key,
+			sourceText: row.source_text,
+			translatedText: row.translated_text,
+			...row.target_nodes_json ? { targetNodesJson: row.target_nodes_json } : {},
+			sourceLanguage: row.source_language,
+			targetLanguage: row.target_language,
+			placeholderTopologyHash: row.placeholder_topology_hash,
+			attributeTopologyHash: row.attribute_topology_hash,
+			displayPolicyVersion: row.display_policy_version,
+			createdAt: row.created_at,
+			lastAccessedAt: now
+		};
+	}
+	async write(input, now) {
+		(await this.requireDatabase()).prepare(`INSERT INTO translation_cache_entries (
+          key_hash, cache_key, source_text, translated_text, target_nodes_json, source_language,
+          target_language, placeholder_topology_hash, attribute_topology_hash,
+          display_policy_version, created_at, last_accessed_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(key_hash) DO UPDATE SET
+          cache_key = excluded.cache_key,
+          source_text = excluded.source_text,
+          translated_text = excluded.translated_text,
+          target_nodes_json = excluded.target_nodes_json,
+          source_language = excluded.source_language,
+          target_language = excluded.target_language,
+          placeholder_topology_hash = excluded.placeholder_topology_hash,
+          attribute_topology_hash = excluded.attribute_topology_hash,
+          display_policy_version = excluded.display_policy_version,
+          last_accessed_at = excluded.last_accessed_at`).run(input.keyHash, input.key, input.sourceText, input.translatedText, input.targetNodesJson ?? null, input.sourceLanguage, input.targetLanguage, input.placeholderTopologyHash, input.attributeTopologyHash, input.displayPolicyVersion, now, now);
+	}
+	async count() {
+		return readSqliteCount((await this.requireDatabase()).prepare("SELECT COUNT(*) AS count FROM translation_cache_entries").get());
+	}
+	async deleteLeastRecentlyUsed(targetEntryCount) {
+		const database = await this.requireDatabase();
+		const currentCount = await this.count();
+		const deleteCount = Math.max(0, currentCount - targetEntryCount);
+		if (deleteCount === 0) return 0;
+		database.prepare(`DELETE FROM translation_cache_entries
+        WHERE key_hash IN (
+          SELECT key_hash FROM translation_cache_entries
+          ORDER BY last_accessed_at ASC, key_hash ASC
+          LIMIT ?
+        )`).run(deleteCount);
+		return deleteCount;
+	}
+	async clean(entryLimit) {
+		const before = await this.count();
+		const target = Math.floor(entryLimit * .6);
+		const deleted = await this.deleteLeastRecentlyUsed(target);
+		return {
+			before,
+			after: await this.count(),
+			deleted
+		};
+	}
+	async clear() {
+		const database = await this.requireDatabase();
+		const before = await this.count();
+		database.prepare("DELETE FROM translation_cache_entries").run();
+		return before;
+	}
+	close() {
+		this.database?.close?.();
+		this.database = null;
+	}
+	async requireDatabase() {
+		await this.init();
+		if (!this.database) throw new Error("Translation cache database is not initialized.");
+		return this.database;
+	}
+};
+async function createRuntimeSqliteTranslationCacheAdapter(databasePath) {
+	return new SqliteTranslationCacheAdapter(databasePath, await resolveRuntimeSqliteDatabaseFactory());
+}
+async function resolveRuntimeSqliteDatabaseFactory() {
+	if (isBunRuntime()) {
+		const Database$1 = (await dynamicImport("bun:sqlite")).Database;
+		return (databasePath) => new Database$1(databasePath);
+	}
+	const Database = (await import("better-sqlite3")).default;
+	return (databasePath) => new Database(databasePath);
+}
+const dynamicImport = new Function("specifier", "return import(specifier)");
+function isBunRuntime() {
+	return typeof process.versions.bun === "string";
+}
+function ensureTargetNodesJsonColumn(database) {
+	if (!database.prepare("PRAGMA table_info(translation_cache_entries)").all().some((row) => {
+		if (!row || typeof row !== "object") return false;
+		return row.name === "target_nodes_json";
+	})) database.exec("ALTER TABLE translation_cache_entries ADD COLUMN target_nodes_json TEXT");
+}
+function isSqliteTranslationCacheRow(value) {
+	if (!value || typeof value !== "object") return false;
+	const row = value;
+	return typeof row.key_hash === "string" && typeof row.cache_key === "string" && typeof row.source_text === "string" && typeof row.translated_text === "string" && (typeof row.target_nodes_json === "string" || row.target_nodes_json === null) && typeof row.source_language === "string" && typeof row.target_language === "string" && typeof row.placeholder_topology_hash === "string" && typeof row.attribute_topology_hash === "string" && typeof row.display_policy_version === "number" && typeof row.created_at === "number" && typeof row.last_accessed_at === "number";
+}
+function readSqliteCount(value) {
+	if (!value || typeof value !== "object") return 0;
+	const count = value.count;
+	return typeof count === "number" ? count : 0;
+}
+
+//#endregion
+//#region src/translation-cache-path.ts
+function getDefaultTranslationCacheDatabasePath() {
+	return join(getOpenSpecUICacheDir(), "translation-cache.sqlite");
+}
+function getOpenSpecUICacheDir() {
+	const currentPlatform = platform();
+	if (currentPlatform === "darwin") return join(homedir(), "Library", "Caches", "openspecui");
+	if (currentPlatform === "win32") return join(process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "OpenSpecUI", "Cache");
+	return join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "openspecui");
+}
+
+//#endregion
+//#region src/translation-cache-service.ts
+var TranslationCacheService = class {
+	configManager;
+	globalSettingsManager;
+	adapter;
+	now;
+	onWriteError;
+	constructor(options) {
+		this.configManager = options.configManager;
+		this.globalSettingsManager = options.globalSettingsManager;
+		this.adapter = options.adapter;
+		this.now = options.now ?? Date.now;
+		this.onWriteError = options.onWriteError ?? (() => void 0);
+	}
+	async getStats() {
+		const [{ translation }, globalSettings] = await Promise.all([this.configManager.readConfig(), this.globalSettingsManager.readSettings()]);
+		const entryLimit = globalSettings.translationCache.entryLimit;
+		const enabled = translation.cacheEnabled;
+		return {
+			enabled,
+			entryLimit,
+			entries: enabled ? await this.adapter.count() : 0,
+			...this.adapter.databasePath ? { databasePath: this.adapter.databasePath } : {}
+		};
+	}
+	async read(keyHash) {
+		if (!(await this.configManager.readConfig()).translation.cacheEnabled) return null;
+		try {
+			return await this.adapter.read(keyHash, this.now());
+		} catch {
+			return null;
+		}
+	}
+	async write(input) {
+		const [{ translation }, globalSettings] = await Promise.all([this.configManager.readConfig(), this.globalSettingsManager.readSettings()]);
+		if (!translation.cacheEnabled) return { accepted: false };
+		this.writeAndClean(input, globalSettings.translationCache.entryLimit);
+		return { accepted: true };
+	}
+	async clean() {
+		const globalSettings = await this.globalSettingsManager.readSettings();
+		return this.adapter.clean(globalSettings.translationCache.entryLimit);
+	}
+	async clear() {
+		return { deleted: await this.adapter.clear() };
+	}
+	close() {
+		this.adapter.close?.();
+	}
+	async writeAndClean(input, entryLimit) {
+		try {
+			await this.adapter.write(input, this.now());
+			if (await this.adapter.count() >= Math.floor(entryLimit * .9)) await this.adapter.clean(entryLimit);
+		} catch (error) {
+			this.onWriteError(error);
+		}
+	}
+};
+
 //#endregion
 //#region src/workflow-invocation-service.ts
 const COMMAND_CAPABLE_ACTIONS = new Set([
@@ -4436,12 +4808,21 @@ const SERVER_PACKAGE_VERSION = getServerPackageVersion();
 function buildEmbeddedUiUrlForPort(port) {
 	return `http://localhost:${port}`;
 }
+function initializeWatcherPoolInBackground(projectDir) {
+	initWatcherPool(projectDir).catch((err) => {
+		console.error("Watcher pool initialization failed:", err);
+	});
+}
+function deferBackgroundTask(task) {
+	setTimeout(task, 0);
+}
 /**
 * Create an OpenSpecUI HTTP server with optional WebSocket support
 */
 function createServer(config) {
 	const adapter = new OpenSpecAdapter(config.projectDir);
 	const configManager = new ConfigManager(config.projectDir);
+	const globalSettingsManager = new GlobalSettingsManager();
 	const cliExecutor = new CliExecutor(configManager, config.projectDir);
 	const kernel = config.kernel;
 	const hookRuntime = createHookRuntime(config.projectDir);
@@ -4453,8 +4834,37 @@ function createServer(config) {
 	});
 	const notificationService = new NotificationService();
 	const customSoundService = new CustomSoundService();
+	let translationCacheAdapterPromise = null;
+	const getTranslationCacheAdapter = () => {
+		translationCacheAdapterPromise ??= createRuntimeSqliteTranslationCacheAdapter(getDefaultTranslationCacheDatabasePath());
+		return translationCacheAdapterPromise;
+	};
+	const translationCacheService = new TranslationCacheService({
+		configManager,
+		globalSettingsManager,
+		adapter: {
+			databasePath: getDefaultTranslationCacheDatabasePath(),
+			init: async () => (await getTranslationCacheAdapter()).init(),
+			read: async (keyHash, now) => (await getTranslationCacheAdapter()).read(keyHash, now),
+			write: async (input, now) => (await getTranslationCacheAdapter()).write(input, now),
+			count: async () => (await getTranslationCacheAdapter()).count(),
+			deleteLeastRecentlyUsed: async (targetEntryCount) => (await getTranslationCacheAdapter()).deleteLeastRecentlyUsed(targetEntryCount),
+			clean: async (entryLimit) => (await getTranslationCacheAdapter()).clean(entryLimit),
+			clear: async () => (await getTranslationCacheAdapter()).clear(),
+			close: () => {
+				translationCacheAdapterPromise?.then((cacheAdapter) => cacheAdapter.close()).catch(() => {});
+			}
+		},
+		onWriteError(error) {
+			console.warn("Translation cache write failed:", error);
+		}
+	});
 	const watcher = config.enableWatcher !== false ? new OpenSpecWatcher(config.projectDir) : void 0;
-	const searchService = new SearchService(adapter, watcher, void 0, documentService);
+	const entityReadOptionsContext = {
+		adapter,
+		kernel
+	};
+	const searchService = new SearchService(adapter, watcher, void 0, documentService, (stage, id) => buildEntityReadOptions(entityReadOptionsContext, stage, id));
 	const dashboardOverviewService = new DashboardOverviewService((reason) => loadDashboardOverview({
 		adapter,
 		configManager,
@@ -4471,15 +4881,13 @@ function createServer(config) {
 		credentials: true
 	}));
 	app.get("/api/health", (c) => {
-		return c.json({
-			status: "ok",
+		return c.json(buildBackendHealthPayload({
 			projectDir: config.projectDir,
 			projectName: basename(config.projectDir) || config.projectDir,
 			watcherEnabled: !!watcher,
 			openspecuiVersion: SERVER_PACKAGE_VERSION,
-			hostedShellProtocolVersion: HOSTED_SHELL_PROTOCOL_VERSION,
 			embeddedUiUrl: buildEmbeddedUiUrlForPort(config.port ?? 3100)
-		});
+		}));
 	});
 	app.post("/api/notifications", async (c) => {
 		const body = await c.req.json().catch(() => null);
@@ -4530,6 +4938,8 @@ function createServer(config) {
 				projectRecoveryService,
 				notificationService,
 				customSoundService,
+				globalSettingsManager,
+				translationCacheService,
 				gitWorktreeHandoff: config.gitWorktreeHandoff,
 				watcher,
 				projectDir: config.projectDir
@@ -4548,6 +4958,8 @@ function createServer(config) {
 		projectRecoveryService,
 		notificationService,
 		customSoundService,
+		globalSettingsManager,
+		translationCacheService,
 		gitWorktreeHandoff: config.gitWorktreeHandoff,
 		watcher,
 		projectDir: config.projectDir
@@ -4565,6 +4977,8 @@ function createServer(config) {
 		projectRecoveryService,
 		notificationService,
 		customSoundService,
+		globalSettingsManager,
+		translationCacheService,
 		hookRuntime,
 		watcher,
 		createContext,
@@ -4575,7 +4989,7 @@ function createServer(config) {
 * Create WebSocket server for tRPC subscriptions and PTY terminals
 */
 async function createWebSocketServer(server, httpServer, config) {
-	if (!isWatcherPoolInitialized()) await initWatcherPool(config.projectDir);
+	if (!isWatcherPoolInitialized()) deferBackgroundTask(() => initializeWatcherPoolInBackground(config.projectDir));
 	const wss = new WebSocketServer({ noServer: true });
 	const handler = applyWSSHandler({
 		wss,
@@ -4615,6 +5029,7 @@ async function createWebSocketServer(server, httpServer, config) {
 			server.searchService.dispose().catch(() => {});
 			server.dashboardOverviewService.dispose();
 			server.projectRecoveryService.dispose();
+			server.translationCacheService.close();
 		}
 	};
 }
@@ -4631,7 +5046,7 @@ async function startServer(config, setupApp) {
 	const port = await findAvailablePort(preferredPort);
 	const cliExecutor = new CliExecutor(new ConfigManager(config.projectDir), config.projectDir);
 	const kernel = new OpsxKernel(config.projectDir, cliExecutor);
-	await initWatcherPool(config.projectDir);
+	deferBackgroundTask(() => initializeWatcherPoolInBackground(config.projectDir));
 	const server = createServer({
 		...config,
 		port,
@@ -4644,14 +5059,16 @@ async function startServer(config, setupApp) {
 	});
 	const wsServer = await createWebSocketServer(server, httpServer, { projectDir: config.projectDir });
 	const url = `http://localhost:${port}`;
-	kernel.warmup().catch((err) => {
-		console.error("Kernel warmup failed:", err);
-	});
-	server.searchService.init().catch((err) => {
-		console.error("Search service warmup failed:", err);
-	});
-	server.dashboardOverviewService.init().catch((err) => {
-		console.error("Dashboard overview warmup failed:", err);
+	deferBackgroundTask(() => {
+		kernel.warmup().catch((err) => {
+			console.error("Kernel warmup failed:", err);
+		});
+		server.searchService.init().catch((err) => {
+			console.error("Search service warmup failed:", err);
+		});
+		server.dashboardOverviewService.init().catch((err) => {
+			console.error("Dashboard overview warmup failed:", err);
+		});
 	});
 	return {
 		url,
@@ -4660,6 +5077,7 @@ async function startServer(config, setupApp) {
 		close: async () => {
 			kernel.dispose();
 			await server.hookRuntime.dispose();
+			server.translationCacheService.close();
 			wsServer.close();
 			httpServer.close();
 		}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@openspecui/server",
-  "version": "3.6.1",
+  "version": "3.7.1",
   "type": "module",
   "main": "dist/index.mjs",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs"
+      "development": "./src/index.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
     }
   },
   "files": [
@@ -14,7 +16,7 @@
   "scripts": {
     "build": "tsdown src/index.ts --format esm --no-dts",
     "typecheck": "tsc -p tsconfig.check.json --noEmit",
-    "dev": "tsx watch --include '../core/dist/**' --include '../search/dist/**' src/standalone.ts",
+    "dev": "NODE_OPTIONS=\"${NODE_OPTIONS:+$NODE_OPTIONS }--conditions=development\" tsx watch --include '../core/dist/**' --include '../search/dist/**' src/standalone.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   },
@@ -24,6 +26,8 @@
     "@openspecui/core": "workspace:*",
     "@openspecui/search": "workspace:*",
     "@trpc/server": "^11.0.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.5.0",
     "hono": "^4.7.3",
     "tsx": "^4.19.2",
     "ws": "^8.18.0",