@openspecui/server 3.2.3 → 3.4.0

package/dist/index.mjs

@@ -1,17 +1,17 @@
+import { CliExecutor, CodeEditorThemeSchema, ConfigManager, DASHBOARD_METRIC_KEYS, DashboardConfigSchema, GitConfigSchema, HOSTED_SHELL_PROTOCOL_VERSION, MarkdownParser, OPENSPECUI_HOOKS_VERSION, OpenSpecAdapter, OpenSpecWatcher, OpsxConfigSchema, OpsxKernel, PtyClientMessageSchema, ReactiveContext, TerminalConfigSchema, TerminalRendererEngineSchema, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, getDetectedProjectTools, getToolInitStates, getWatcherRuntimeStatus, initWatcherPool, isWatcherPoolInitialized, resolveTerminalShellDefaults, sniffGlobalCli, subscribeWatcherRuntimeStatus } from "@openspecui/core";
+import { basename, dirname, join, 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";
 import { serve } from "@hono/node-server";
-import { CliExecutor, CodeEditorThemeSchema, ConfigManager, DASHBOARD_METRIC_KEYS, DashboardConfigSchema, GitConfigSchema, HOSTED_SHELL_PROTOCOL_VERSION, OpenSpecAdapter, OpenSpecWatcher, OpsxConfigSchema, OpsxKernel, PtyClientMessageSchema, ReactiveContext, TerminalConfigSchema, TerminalRendererEngineSchema, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, getDetectedProjectTools, getToolInitStates, getWatcherRuntimeStatus, initWatcherPool, isWatcherPoolInitialized, sniffGlobalCli, subscribeWatcherRuntimeStatus } from "@openspecui/core";
 import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
 import { applyWSSHandler } from "@trpc/server/adapters/ws";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { fileURLToPath } from "node:url";
 import { WebSocketServer } from "ws";
 import { EventEmitter } from "node:events";
 import { execFile } from "node:child_process";
-import { mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import * as pty from "@lydell/node-pty";
 import { EventEmitter as EventEmitter$1 } from "events";
@@ -21,6 +21,284 @@ import { observable } from "@trpc/server/observable";
 import { z } from "zod";
 import { NodeWorkerSearchProvider } from "@openspecui/search/node";
 
+//#region src/document-service.ts
+function toErrorDiagnostic$1(error) {
+	return {
+		level: "error",
+		message: error instanceof Error ? error.message : String(error)
+	};
+}
+function isNotNull(value) {
+	return value !== null;
+}
+var DocumentService = class {
+	parser = new MarkdownParser();
+	constructor(projectDir, adapter, hookRuntime) {
+		this.projectDir = projectDir;
+		this.adapter = adapter;
+		this.hookRuntime = hookRuntime;
+	}
+	async readProjectMd(consumer = "view", mode = "processed") {
+		const source = await this.adapter.readProjectMd();
+		if (source === null) return null;
+		return this.processDocument({
+			consumer,
+			mode,
+			document: {
+				stage: "project",
+				kind: "project",
+				relativePath: "openspec/project.md",
+				absolutePath: join(this.projectDir, "openspec", "project.md")
+			},
+			source
+		});
+	}
+	async readSpecRaw(specId, consumer = "view", mode = "processed") {
+		const source = await this.adapter.readSpecRaw(specId);
+		if (source === null) return null;
+		return this.processDocument({
+			consumer,
+			mode,
+			document: {
+				stage: "main",
+				kind: "spec",
+				specId,
+				relativePath: `openspec/specs/${specId}/spec.md`,
+				absolutePath: join(this.projectDir, "openspec", "specs", specId, "spec.md")
+			},
+			source
+		});
+	}
+	async readSpec(specId, consumer = "view", mode = "processed") {
+		try {
+			const content = await this.readSpecRaw(specId, consumer, mode);
+			if (!content) return null;
+			return this.parser.parseSpec(specId, content.markdown);
+		} catch {
+			return null;
+		}
+	}
+	async readChangeRaw(changeId, consumer = "view", mode = "processed") {
+		const raw = await this.adapter.readChangeRaw(changeId);
+		if (!raw) return null;
+		const process$1 = (kind, relativePath$1, source) => this.processDocument({
+			consumer,
+			mode,
+			document: {
+				stage: "change",
+				kind,
+				changeId,
+				relativePath: relativePath$1,
+				absolutePath: join(this.projectDir, relativePath$1)
+			},
+			source
+		});
+		const [proposal, tasks, design, deltaSpecs] = await Promise.all([
+			process$1("proposal", `openspec/changes/${changeId}/proposal.md`, raw.proposal),
+			process$1("tasks", `openspec/changes/${changeId}/tasks.md`, raw.tasks),
+			raw.design ? process$1("design", `openspec/changes/${changeId}/design.md`, raw.design) : Promise.resolve(void 0),
+			Promise.all(raw.deltaSpecs.map(async (deltaSpec) => {
+				const result = await process$1("delta-spec", `openspec/changes/${changeId}/specs/${deltaSpec.specId}/spec.md`, deltaSpec.content);
+				return {
+					specId: deltaSpec.specId,
+					content: result.markdown,
+					sourceContent: deltaSpec.content
+				};
+			}))
+		]);
+		return {
+			proposal,
+			tasks,
+			design,
+			deltaSpecs
+		};
+	}
+	async readChange(changeId, consumer = "view", mode = "processed") {
+		try {
+			const raw = await this.readChangeRaw(changeId, consumer, mode);
+			if (!raw) return null;
+			return this.parser.parseChange(changeId, raw.proposal.markdown, raw.tasks.markdown, {
+				design: raw.design?.markdown,
+				deltaSpecs: raw.deltaSpecs
+			});
+		} catch {
+			return null;
+		}
+	}
+	async readArchivedChangeRaw(changeId, consumer = "view", mode = "processed") {
+		const raw = await this.adapter.readArchivedChangeRaw(changeId);
+		if (!raw) return null;
+		const process$1 = (kind, relativePath$1, source) => this.processDocument({
+			consumer,
+			mode,
+			document: {
+				stage: "archive",
+				kind,
+				changeId,
+				relativePath: relativePath$1,
+				absolutePath: join(this.projectDir, relativePath$1)
+			},
+			source
+		});
+		const [proposal, tasks, design, deltaSpecs] = await Promise.all([
+			process$1("proposal", `openspec/changes/archive/${changeId}/proposal.md`, raw.proposal),
+			process$1("tasks", `openspec/changes/archive/${changeId}/tasks.md`, raw.tasks),
+			raw.design ? process$1("design", `openspec/changes/archive/${changeId}/design.md`, raw.design) : Promise.resolve(void 0),
+			Promise.all(raw.deltaSpecs.map(async (deltaSpec) => {
+				const result = await process$1("delta-spec", `openspec/changes/archive/${changeId}/specs/${deltaSpec.specId}/spec.md`, deltaSpec.content);
+				return {
+					specId: deltaSpec.specId,
+					content: result.markdown,
+					sourceContent: deltaSpec.content
+				};
+			}))
+		]);
+		return {
+			proposal,
+			tasks,
+			design,
+			deltaSpecs
+		};
+	}
+	async readArchivedChange(changeId, consumer = "view", mode = "processed") {
+		try {
+			const raw = await this.readArchivedChangeRaw(changeId, consumer, mode);
+			if (!raw) return null;
+			return this.parser.parseChange(changeId, raw.proposal.markdown, raw.tasks.markdown, {
+				design: raw.design?.markdown,
+				deltaSpecs: raw.deltaSpecs
+			});
+		} catch {
+			return null;
+		}
+	}
+	async readChangeFiles(changeId, consumer = "view", mode = "processed") {
+		const files = await this.adapter.readChangeFiles(changeId);
+		return this.processChangeFiles("change", changeId, files, 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);
+	}
+	inferChangeFileKind(path) {
+		if (path === "proposal.md") return "proposal";
+		if (path === "tasks.md") return "tasks";
+		if (path === "design.md") return "design";
+		if (/^specs\/[^/]+\/spec\.md$/.test(path)) return "delta-spec";
+		return null;
+	}
+	async processDocument(input) {
+		const read = async () => ({
+			markdown: input.source,
+			sourceMarkdown: input.source
+		});
+		if (input.mode === "source") return read();
+		const hooks = await this.hookRuntime.load();
+		if (!hooks.onReadDocument) return read();
+		try {
+			return {
+				...await hooks.onReadDocument({
+					version: OPENSPECUI_HOOKS_VERSION,
+					projectDir: this.projectDir,
+					consumer: input.consumer,
+					document: input.document,
+					signal: new AbortController().signal,
+					lifecycle: this.hookRuntime
+				}, read),
+				sourceMarkdown: input.source
+			};
+		} catch (error) {
+			const fallback = await read();
+			return {
+				...fallback,
+				diagnostics: [...fallback.diagnostics ?? [], toErrorDiagnostic$1(error)]
+			};
+		}
+	}
+};
+
+//#endregion
+//#region src/hook-runtime.ts
+const OPENSPECUI_HOOKS_RELATIVE_PATH = "openspec/openspecui.hooks.ts";
+function isOnReadDocumentHook(value) {
+	return typeof value === "function";
+}
+function isOnRunWorkflowHook(value) {
+	return typeof value === "function";
+}
+function normalizeHooksModule(moduleValue) {
+	if (!moduleValue || typeof moduleValue !== "object") return {};
+	const record = moduleValue;
+	const defaultRecord = record.default && typeof record.default === "object" ? record.default : {};
+	const moduleExportsRecord = record["module.exports"] && typeof record["module.exports"] === "object" ? record["module.exports"] : {};
+	return {
+		onReadDocument: isOnReadDocumentHook(record.onReadDocument) ? record.onReadDocument : isOnReadDocumentHook(defaultRecord.onReadDocument) ? defaultRecord.onReadDocument : isOnReadDocumentHook(moduleExportsRecord.onReadDocument) ? moduleExportsRecord.onReadDocument : void 0,
+		onRunWorkflow: isOnRunWorkflowHook(record.onRunWorkflow) ? record.onRunWorkflow : isOnRunWorkflowHook(defaultRecord.onRunWorkflow) ? defaultRecord.onRunWorkflow : isOnRunWorkflowHook(moduleExportsRecord.onRunWorkflow) ? moduleExportsRecord.onRunWorkflow : void 0
+	};
+}
+async function pathExists$1(path) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+var ProjectHookRuntime = class {
+	hooksPath;
+	hooksPromise = null;
+	disposeCallbacks = /* @__PURE__ */ new Set();
+	constructor(projectDir) {
+		this.hooksPath = join(projectDir, OPENSPECUI_HOOKS_RELATIVE_PATH);
+	}
+	async load() {
+		if (this.hooksPromise) return this.hooksPromise;
+		this.hooksPromise = this.loadFresh().catch(() => ({}));
+		return this.hooksPromise;
+	}
+	onDispose(cleanup) {
+		this.disposeCallbacks.add(cleanup);
+	}
+	async dispose() {
+		const callbacks = [...this.disposeCallbacks];
+		this.disposeCallbacks.clear();
+		await Promise.allSettled(callbacks.map((cleanup) => cleanup()));
+	}
+	async loadFresh() {
+		if (!await pathExists$1(this.hooksPath)) return {};
+		const { tsImport } = await import("tsx/esm/api");
+		return normalizeHooksModule(await tsImport(`${pathToFileURL(this.hooksPath).href}?t=${Date.now()}`, { parentURL: pathToFileURL(this.hooksPath).href }));
+	}
+};
+function createHookRuntime(projectDir) {
+	return new ProjectHookRuntime(projectDir);
+}
+
+//#endregion
 //#region src/port-utils.ts
 /**
 * Check if a port is available by trying to listen on it.
@@ -1145,6 +1423,15 @@ function resolveDefaultShell(platform, env) {
 	if (platform === "windows") return env.ComSpec?.trim() || "cmd.exe";
 	return env.SHELL?.trim() || "/bin/sh";
 }
+function resolvePtyShellDefaults(opts) {
+	return resolveTerminalShellDefaults({
+		platform: opts.platform,
+		env: {
+			SHELL: opts.env.SHELL,
+			ComSpec: opts.env.ComSpec
+		}
+	});
+}
 function resolvePtyCommand(opts) {
 	const command = opts.command?.trim();
 	if (command) return {
@@ -1282,6 +1569,12 @@ var PtyManager = class {
 		this.defaultCwd = defaultCwd;
 		this.platform = detectPtyPlatform();
 	}
+	getShellDefaults() {
+		return resolvePtyShellDefaults({
+			platform: this.platform,
+			env: process.env
+		});
+	}
 	create(opts) {
 		const id = `pty-${++this.idCounter}`;
 		const session = new PtySession(id, {
@@ -2313,6 +2606,47 @@ const gitEntrySelectorSchema = z.discriminatedUnion("type", [z.object({ type: z.
 	type: z.literal("commit"),
 	hash: z.string().min(1)
 })]);
+const workflowRequestedModeSchema = z.enum([
+	"compose",
+	"command",
+	"direct"
+]);
+const runWorkflowInputSchema = z.discriminatedUnion("action", [
+	z.object({
+		action: z.enum(["explore", "propose"]),
+		text: z.string()
+	}),
+	z.object({
+		action: z.literal("new"),
+		changeId: z.string(),
+		schema: z.string().optional(),
+		description: z.string().optional(),
+		extraArgs: z.array(z.string()).default([])
+	}),
+	z.object({
+		action: z.enum(["continue", "ff"]),
+		changeId: z.string(),
+		artifactId: z.string(),
+		schema: z.string().optional()
+	}),
+	z.object({
+		action: z.enum([
+			"apply",
+			"archive",
+			"verify",
+			"sync"
+		]),
+		changeId: z.string(),
+		schema: z.string().optional(),
+		strict: z.boolean().optional()
+	}),
+	z.object({
+		action: z.literal("bulk-archive"),
+		changeIds: z.array(z.string()).optional(),
+		schema: z.string().optional()
+	}),
+	z.object({ action: z.literal("onboard") })
+]);
 function requireChangeId(changeId) {
 	if (!changeId) throw new Error("change is required");
 	return changeId;
@@ -2494,7 +2828,7 @@ const specRouter = router({
 		return ctx.adapter.listSpecsWithMeta();
 	}),
 	get: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
-		return ctx.adapter.readSpec(input.id);
+		return ctx.documentService.readSpec(input.id);
 	}),
 	getRaw: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
 		return ctx.adapter.readSpecRaw(input.id);
@@ -2513,7 +2847,7 @@ const specRouter = router({
 		return createReactiveSubscription(() => ctx.adapter.listSpecsWithMeta());
 	}),
 	subscribeOne: publicProcedure.input(z.object({ id: z.string() })).subscription(({ ctx, input }) => {
-		return createReactiveSubscriptionWithInput((id) => ctx.adapter.readSpec(id))(input.id);
+		return createReactiveSubscriptionWithInput((id) => ctx.documentService.readSpec(id))(input.id);
 	}),
 	subscribeRaw: publicProcedure.input(z.object({ id: z.string() })).subscription(({ ctx, input }) => {
 		return createReactiveSubscriptionWithInput((id) => ctx.adapter.readSpecRaw(id))(input.id);
@@ -2533,7 +2867,7 @@ const changeRouter = router({
 		return ctx.adapter.listArchivedChanges();
 	}),
 	get: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
-		return ctx.adapter.readChange(input.id);
+		return ctx.documentService.readChange(input.id);
 	}),
 	getRaw: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
 		return ctx.adapter.readChangeRaw(input.id);
@@ -2585,7 +2919,7 @@ const archiveRouter = router({
 		return ctx.adapter.listArchivedChangesWithMeta();
 	}),
 	get: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
-		return ctx.adapter.readArchivedChange(input.id);
+		return ctx.documentService.readArchivedChange(input.id);
 	}),
 	getRaw: publicProcedure.input(z.object({ id: z.string() })).query(async ({ ctx, input }) => {
 		return ctx.adapter.readArchivedChangeRaw(input.id);
@@ -2594,7 +2928,7 @@ const archiveRouter = router({
 		return createReactiveSubscription(() => ctx.adapter.listArchivedChangesWithMeta());
 	}),
 	subscribeOne: publicProcedure.input(z.object({ id: z.string() })).subscription(({ ctx, input }) => {
-		return createReactiveSubscriptionWithInput((id) => ctx.adapter.readArchivedChange(id))(input.id);
+		return createReactiveSubscriptionWithInput((id) => ctx.documentService.readArchivedChange(id))(input.id);
 	}),
 	subscribeFiles: publicProcedure.input(z.object({ id: z.string() })).subscription(({ ctx, input }) => {
 		return createReactiveSubscriptionWithInput((id) => ctx.adapter.readArchivedChangeFiles(id))(input.id);
@@ -2720,6 +3054,15 @@ const configRouter = router({
 	}),
 	subscribe: publicProcedure.subscription(({ ctx }) => {
 		return createReactiveSubscription(() => ctx.configManager.readConfig());
+	}),
+	getTerminalShellDefaults: publicProcedure.query(async () => {
+		return resolveTerminalShellDefaults({
+			platform: process.platform === "win32" ? "windows" : process.platform === "darwin" ? "macos" : "common",
+			env: {
+				SHELL: process.env.SHELL,
+				ComSpec: process.env.ComSpec
+			}
+		});
 	})
 });
 /**
@@ -2882,6 +3225,12 @@ const cliRouter = router({
 * OPSX router - CLI-driven workflow data
 */
 const opsxRouter = router({
+	runWorkflow: publicProcedure.input(z.object({
+		requestedMode: workflowRequestedModeSchema,
+		input: runWorkflowInputSchema
+	})).mutation(async ({ ctx, input }) => {
+		return ctx.workflowInvocationService.runWorkflow(input.input, input.requestedMode);
+	}),
 	status: publicProcedure.input(z.object({
 		change: z.string().optional(),
 		schema: z.string().optional()
@@ -3350,11 +3699,11 @@ const appRouter = router({
 function joinParts(parts) {
 	return parts.map((part) => part?.trim() ?? "").filter((part) => part.length > 0).join("\n\n");
 }
-async function collectSearchDocuments(adapter) {
+async function collectSearchDocuments(adapter, documentService) {
 	const docs = [];
 	const specs = await adapter.listSpecsWithMeta();
 	for (const spec of specs) {
-		const raw = await adapter.readSpecRaw(spec.id);
+		const raw = documentService ? await documentService.readSpecRaw(spec.id, "search", "processed") : await adapter.readSpecRaw(spec.id);
 		if (!raw) continue;
 		docs.push({
 			id: `spec:${spec.id}`,
@@ -3362,13 +3711,13 @@ async function collectSearchDocuments(adapter) {
 			title: spec.name,
 			href: `/specs/${encodeURIComponent(spec.id)}`,
 			path: `openspec/specs/${spec.id}/spec.md`,
-			content: raw,
+			content: typeof raw === "string" ? raw : raw.markdown,
 			updatedAt: spec.updatedAt
 		});
 	}
 	const changes = await adapter.listChangesWithMeta();
 	for (const change of changes) {
-		const raw = await adapter.readChangeRaw(change.id);
+		const raw = documentService ? await documentService.readChangeRaw(change.id, "search", "processed") : await adapter.readChangeRaw(change.id);
 		if (!raw) continue;
 		docs.push({
 			id: `change:${change.id}`,
@@ -3377,9 +3726,9 @@ async function collectSearchDocuments(adapter) {
 			href: `/changes/${encodeURIComponent(change.id)}`,
 			path: `openspec/changes/${change.id}`,
 			content: joinParts([
-				raw.proposal,
-				raw.tasks,
-				raw.design,
+				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)
 			]),
 			updatedAt: change.updatedAt
@@ -3387,7 +3736,7 @@ async function collectSearchDocuments(adapter) {
 	}
 	const archives = await adapter.listArchivedChangesWithMeta();
 	for (const archive of archives) {
-		const raw = await adapter.readArchivedChangeRaw(archive.id);
+		const raw = documentService ? await documentService.readArchivedChangeRaw(archive.id, "search", "processed") : await adapter.readArchivedChangeRaw(archive.id);
 		if (!raw) continue;
 		docs.push({
 			id: `archive:${archive.id}`,
@@ -3396,9 +3745,9 @@ async function collectSearchDocuments(adapter) {
 			href: `/archive/${encodeURIComponent(archive.id)}`,
 			path: `openspec/changes/archive/${archive.id}`,
 			content: joinParts([
-				raw.proposal,
-				raw.tasks,
-				raw.design,
+				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)
 			]),
 			updatedAt: archive.updatedAt
@@ -3416,8 +3765,9 @@ var SearchService = class {
 	initPromise = null;
 	rebuildPromise = null;
 	rebuildTimer = null;
-	constructor(adapter, watcher, provider = new NodeWorkerSearchProvider()) {
+	constructor(adapter, watcher, provider = new NodeWorkerSearchProvider(), documentService) {
 		this.adapter = adapter;
+		this.documentService = documentService;
 		this.provider = provider;
 		watcher?.on("change", () => {
 			this.scheduleRebuild();
@@ -3463,7 +3813,7 @@ var SearchService = class {
 		if (!forceInit && !this.initialized) return;
 		if (this.rebuildPromise) return this.rebuildPromise;
 		this.rebuildPromise = (async () => {
-			const docs = await collectSearchDocuments(this.adapter);
+			const docs = await collectSearchDocuments(this.adapter, this.documentService);
 			if (this.initialized) await this.provider.replaceAll(docs);
 			else {
 				await this.provider.init(docs);
@@ -3478,6 +3828,218 @@ var SearchService = class {
 	}
 };
 
+//#endregion
+//#region src/workflow-invocation-service.ts
+const COMMAND_CAPABLE_ACTIONS = new Set([
+	"propose",
+	"apply",
+	"archive"
+]);
+const COMMAND_FALLBACK_REASONS = {
+	continue: "Continue uses the selected artifact context, so compose mode is required.",
+	ff: "Fast-forward from a change page uses the selected ready artifact, so compose mode is required."
+};
+function toErrorDiagnostic(error) {
+	return {
+		level: "error",
+		message: error instanceof Error ? error.message : String(error)
+	};
+}
+function withDiagnostics(result, diagnostics) {
+	return {
+		...result,
+		diagnostics: [...result.diagnostics ?? [], ...diagnostics]
+	};
+}
+function resolveInvocationMode(action, requestedMode) {
+	if (requestedMode !== "command" || COMMAND_CAPABLE_ACTIONS.has(action)) return {
+		requestedMode,
+		actualMode: requestedMode,
+		fallbackReason: null
+	};
+	return {
+		requestedMode,
+		actualMode: "compose",
+		fallbackReason: COMMAND_FALLBACK_REASONS[action] ?? "This action requires compose mode."
+	};
+}
+function buildProposeComposePrompt(text) {
+	const normalized = text.trim();
+	if (normalized.length === 0) return ["Propose a new OpenSpec change.", "Ask me what to build before creating files if the request is unclear."].join("\n");
+	return [
+		`Propose a new OpenSpec change for: ${normalized}`,
+		"",
+		"Use the OpenSpec propose workflow. If an openspec-propose skill is available, follow it. Otherwise derive a kebab-case change name, run `openspec new change \"<name>\"`, inspect `openspec status --change \"<name>\" --json`, and create every apply-required artifact using `openspec instructions <artifact-id> --change \"<name>\" --json`."
+	].join("\n");
+}
+function buildSlashCommand(input) {
+	switch (input.action) {
+		case "propose": {
+			const normalized = input.text.trim();
+			if (normalized.length === 0) return "/opsx:propose";
+			if (normalized.startsWith("/opsx:")) return normalized;
+			return `/opsx:propose ${normalized}`;
+		}
+		case "apply":
+		case "archive": return `/opsx:${input.action} ${input.changeId.trim()}`;
+		default: return null;
+	}
+}
+async function captureCliText(execute, args, fallback) {
+	const result = await execute(args);
+	const text = result.stdout.trim().length > 0 ? result.stdout.trim() : fallback;
+	if (result.success) return { text };
+	return {
+		text,
+		diagnostics: [{
+			level: "warning",
+			message: result.stderr || `openspec command exited with code ${result.exitCode ?? "null"}`
+		}]
+	};
+}
+function buildFallbackPrompt(input) {
+	switch (input.action) {
+		case "continue": return `Continue artifact ${input.artifactId} for change ${input.changeId}.`;
+		case "ff": return `Fast-forward artifact ${input.artifactId} for change ${input.changeId}.`;
+		case "apply": return `Apply change ${input.changeId} based on current completed artifacts.`;
+		case "archive": return `Archive change ${input.changeId} after verifying completion and risks.`;
+		case "sync": return `Sync specs for change ${input.changeId}.`;
+		case "verify": return `Verify change ${input.changeId}.`;
+		case "bulk-archive": return `Archive completed changes${input.changeIds?.length ? `: ${input.changeIds.join(", ")}` : ""}.`;
+		case "explore":
+		case "propose": return buildProposeComposePrompt(input.text);
+		case "new": return `Create OpenSpec change ${input.changeId}.`;
+		case "onboard": return "Start OpenSpec onboarding for this project.";
+	}
+}
+function buildArchivePrompt(changeId, statusText) {
+	const normalized = statusText.trim();
+	return [
+		`Archive planning for change "${changeId}".`,
+		"",
+		"Current openspec status:",
+		"```text",
+		normalized.length > 0 ? normalized : "(no status output)",
+		"```",
+		"",
+		"Please confirm archive readiness, highlight risks, and provide the exact next steps."
+	].join("\n");
+}
+var WorkflowInvocationService = class {
+	constructor(options) {
+		this.options = options;
+	}
+	async runWorkflow(input, requestedMode, signal = new AbortController().signal) {
+		const mode = resolveInvocationMode(input.action, requestedMode);
+		const run = () => this.runDefault(input, mode);
+		const hooks = await this.options.hookRuntime.load();
+		if (!hooks.onRunWorkflow) return run();
+		try {
+			return await hooks.onRunWorkflow({
+				version: OPENSPECUI_HOOKS_VERSION,
+				projectDir: this.options.projectDir,
+				action: input.action,
+				requestedMode,
+				input,
+				signal,
+				lifecycle: this.options.hookRuntime
+			}, run);
+		} catch (error) {
+			return withDiagnostics(await run(), [toErrorDiagnostic(error)]);
+		}
+	}
+	async runDefault(input, mode) {
+		if (mode.actualMode === "command") {
+			const text = buildSlashCommand(input);
+			if (text) return {
+				kind: "agent-command",
+				text,
+				mode
+			};
+		}
+		if (input.action === "new") {
+			const args = [
+				"new",
+				"change",
+				input.changeId.trim()
+			];
+			const schema = input.schema?.trim();
+			const description = input.description?.trim();
+			if (schema) args.push("--schema", schema);
+			if (description) args.push("--description", description);
+			args.push(...input.extraArgs.map((arg) => arg.trim()).filter((arg) => arg.length > 0));
+			return {
+				kind: "cli-command",
+				command: "openspec",
+				args,
+				mode
+			};
+		}
+		if (input.action === "verify") {
+			const args = [
+				"validate",
+				input.changeId,
+				"--type",
+				"change"
+			];
+			if (input.strict) args.push("--strict");
+			return {
+				kind: "cli-command",
+				command: "openspec",
+				args,
+				mode
+			};
+		}
+		if (input.action === "propose" || input.action === "explore") return {
+			kind: "agent-prompt",
+			text: buildProposeComposePrompt(input.text),
+			format: "markdown",
+			mode
+		};
+		const executeCli = this.options.executeCli;
+		if (executeCli && (input.action === "continue" || input.action === "ff" || input.action === "apply" || input.action === "archive")) {
+			if ((input.action === "continue" || input.action === "ff") && !input.artifactId.trim()) return {
+				kind: "agent-prompt",
+				text: buildFallbackPrompt(input),
+				format: "markdown",
+				mode,
+				diagnostics: [{
+					level: "warning",
+					message: "Artifact id is required for this action."
+				}]
+			};
+			const captured = await captureCliText(executeCli, input.action === "continue" || input.action === "ff" ? [
+				"instructions",
+				input.artifactId,
+				"--change",
+				input.changeId
+			] : input.action === "apply" ? [
+				"instructions",
+				"apply",
+				"--change",
+				input.changeId
+			] : [
+				"status",
+				"--change",
+				input.changeId
+			], buildFallbackPrompt(input));
+			return {
+				kind: "agent-prompt",
+				text: input.action === "archive" ? buildArchivePrompt(input.changeId, captured.text) : captured.text,
+				format: "markdown",
+				mode,
+				diagnostics: captured.diagnostics
+			};
+		}
+		return {
+			kind: "agent-prompt",
+			text: buildFallbackPrompt(input),
+			format: "markdown",
+			mode
+		};
+	}
+};
+
 //#endregion
 //#region src/server.ts
 /**
@@ -3514,8 +4076,15 @@ function createServer(config) {
 	const configManager = new ConfigManager(config.projectDir);
 	const cliExecutor = new CliExecutor(configManager, config.projectDir);
 	const kernel = config.kernel;
+	const hookRuntime = createHookRuntime(config.projectDir);
+	const documentService = new DocumentService(config.projectDir, adapter, hookRuntime);
+	const workflowInvocationService = new WorkflowInvocationService({
+		projectDir: config.projectDir,
+		hookRuntime,
+		executeCli: (args) => cliExecutor.execute(args)
+	});
 	const watcher = config.enableWatcher !== false ? new OpenSpecWatcher(config.projectDir) : void 0;
-	const searchService = new SearchService(adapter, watcher);
+	const searchService = new SearchService(adapter, watcher, void 0, documentService);
 	const dashboardOverviewService = new DashboardOverviewService((reason) => loadDashboardOverview({
 		adapter,
 		configManager,
@@ -3550,8 +4119,10 @@ function createServer(config) {
 			createContext: () => ({
 				adapter,
 				configManager,
+				documentService,
 				cliExecutor,
 				kernel,
+				workflowInvocationService,
 				searchService,
 				dashboardOverviewService,
 				projectRecoveryService,
@@ -3564,8 +4135,10 @@ function createServer(config) {
 	const createContext = () => ({
 		adapter,
 		configManager,
+		documentService,
 		cliExecutor,
 		kernel,
+		workflowInvocationService,
 		searchService,
 		dashboardOverviewService,
 		projectRecoveryService,
@@ -3577,11 +4150,14 @@ function createServer(config) {
 		app,
 		adapter,
 		configManager,
+		documentService,
 		cliExecutor,
 		kernel,
+		workflowInvocationService,
 		searchService,
 		dashboardOverviewService,
 		projectRecoveryService,
+		hookRuntime,
 		watcher,
 		createContext,
 		port: config.port ?? 3100
@@ -3675,6 +4251,7 @@ async function startServer(config, setupApp) {
 		preferredPort,
 		close: async () => {
 			kernel.dispose();
+			await server.hookRuntime.dispose();
 			wsServer.close();
 			httpServer.close();
 		}
@@ -3682,4 +4259,4 @@ async function startServer(config, setupApp) {
 }
 
 //#endregion
-export { createServer, createWebSocketServer, findAvailablePort, isPortAvailable, startServer };
+export { DocumentService, OPENSPECUI_HOOKS_RELATIVE_PATH, ProjectHookRuntime, WorkflowInvocationService, createHookRuntime, createServer, createWebSocketServer, findAvailablePort, isPortAvailable, startServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openspecui/server",
-  "version": "3.2.3",
+  "version": "3.4.0",
   "type": "module",
   "main": "dist/index.mjs",
   "exports": {
@@ -25,6 +25,7 @@
     "@openspecui/search": "workspace:*",
     "@trpc/server": "^11.0.0",
     "hono": "^4.7.3",
+    "tsx": "^4.19.2",
     "ws": "^8.18.0",
     "yaml": "^2.8.0",
     "yargs": "^18.0.0",
@@ -35,7 +36,6 @@
     "@types/ws": "^8.5.13",
     "@types/yargs": "^17.0.35",
     "tsdown": "^0.16.6",
-    "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^4.1.0"
   },