@openspecui/server 0.9.0 → 1.0.0

package/dist/index.mjs

@@ -4,11 +4,17 @@ import { cors } from "hono/cors";
 import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
 import { applyWSSHandler } from "@trpc/server/adapters/ws";
 import { WebSocketServer } from "ws";
-import { CliExecutor, ConfigManager, OpenSpecAdapter, OpenSpecWatcher, ReactiveContext, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, initWatcherPool, sniffGlobalCli } from "@openspecui/core";
+import { ApplyInstructionsSchema, ArtifactInstructionsSchema, ChangeStatusSchema, CliExecutor, ConfigManager, OpenSpecAdapter, OpenSpecWatcher, OpsxKernel, PtyClientMessageSchema, ReactiveContext, SchemaDetailSchema, SchemaInfoSchema, SchemaResolutionSchema, TemplatesSchema, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, initWatcherPool, isWatcherPoolInitialized, reactiveReadDir, reactiveReadFile, reactiveStat, sniffGlobalCli } from "@openspecui/core";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, matchesGlob, relative, resolve, sep } from "node:path";
 import { initTRPC } from "@trpc/server";
 import { observable } from "@trpc/server/observable";
 import { z } from "zod";
+import YAML, { parse } from "yaml";
+import { EventEmitter } from "node:events";
 import { createServer as createServer$1 } from "node:net";
+import * as pty from "@lydell/node-pty";
+import { EventEmitter as EventEmitter$1 } from "events";
 
 //#region src/reactive-subscription.ts
 /**
@@ -124,28 +130,291 @@ function createCliStreamObservable(startStream) {
 	});
 }
 
+//#endregion
+//#region src/opsx-schema.ts
+const SchemaYamlArtifactSchema = z.object({
+	id: z.string(),
+	generates: z.string(),
+	description: z.string().optional(),
+	template: z.string().optional(),
+	instruction: z.string().optional(),
+	requires: z.array(z.string()).optional()
+});
+const SchemaYamlSchema = z.object({
+	name: z.string(),
+	version: z.union([z.string(), z.number()]).optional(),
+	description: z.string().optional(),
+	artifacts: z.array(SchemaYamlArtifactSchema),
+	apply: z.object({
+		requires: z.array(z.string()).optional(),
+		tracks: z.string().optional(),
+		instruction: z.string().optional()
+	}).optional()
+});
+function parseSchemaYaml(content) {
+	const raw = parse(content);
+	const parsed = SchemaYamlSchema.safeParse(raw);
+	if (!parsed.success) throw new Error(`Invalid schema.yaml: ${parsed.error.message}`);
+	const { artifacts, apply, name, description, version } = parsed.data;
+	const detail = {
+		name,
+		description,
+		version,
+		artifacts: artifacts.map((artifact) => ({
+			id: artifact.id,
+			outputPath: artifact.generates,
+			description: artifact.description,
+			template: artifact.template,
+			instruction: artifact.instruction,
+			requires: artifact.requires ?? []
+		})),
+		applyRequires: apply?.requires ?? [],
+		applyTracks: apply?.tracks,
+		applyInstruction: apply?.instruction
+	};
+	const validated = SchemaDetailSchema.safeParse(detail);
+	if (!validated.success) throw new Error(`Invalid schema detail: ${validated.error.message}`);
+	return validated.data;
+}
+
+//#endregion
+//#region src/reactive-kv.ts
+/**
+* In-memory reactive key-value store.
+*
+* - No disk persistence — devices own their own storage (e.g. IndexedDB).
+* - Emits 'change' events when values are set or deleted.
+* - Designed for cross-device sync scenarios where the server acts as a
+*   transient rendezvous point.
+*/
+var ReactiveKV = class {
+	store = /* @__PURE__ */ new Map();
+	emitter = new EventEmitter();
+	constructor() {
+		this.emitter.setMaxListeners(200);
+	}
+	get(key) {
+		return this.store.get(key);
+	}
+	set(key, value) {
+		this.store.set(key, value);
+		this.emitter.emit("change", key);
+		this.emitter.emit(`change:${key}`, value);
+	}
+	delete(key) {
+		const existed = this.store.delete(key);
+		if (existed) {
+			this.emitter.emit("change", key);
+			this.emitter.emit(`change:${key}`, void 0);
+		}
+		return existed;
+	}
+	has(key) {
+		return this.store.has(key);
+	}
+	keys() {
+		return [...this.store.keys()];
+	}
+	/** Subscribe to changes for a specific key. Returns unsubscribe function. */
+	onKey(key, listener) {
+		const event = `change:${key}`;
+		this.emitter.on(event, listener);
+		return () => {
+			this.emitter.off(event, listener);
+		};
+	}
+	/** Subscribe to all changes. Returns unsubscribe function. */
+	onChange(listener) {
+		this.emitter.on("change", listener);
+		return () => {
+			this.emitter.off("change", listener);
+		};
+	}
+};
+/** Singleton instance shared across the server lifetime */
+const reactiveKV = new ReactiveKV();
+
 //#endregion
 //#region src/router.ts
 const t = initTRPC.context().create();
 const router = t.router;
 const publicProcedure = t.procedure;
-/**
-* Dashboard router - overview and status
-*/
-const dashboardRouter = router({
-	getData: publicProcedure.query(async ({ ctx }) => {
-		return ctx.adapter.getDashboardData();
-	}),
-	isInitialized: publicProcedure.query(async ({ ctx }) => {
-		return ctx.adapter.isInitialized();
-	}),
-	subscribe: publicProcedure.subscription(({ ctx }) => {
-		return createReactiveSubscription(() => ctx.adapter.getDashboardData());
-	}),
-	subscribeInitialized: publicProcedure.subscription(({ ctx }) => {
-		return createReactiveSubscription(() => ctx.adapter.isInitialized());
-	})
-});
+function requireChangeId(changeId) {
+	if (!changeId) throw new Error("change is required");
+	return changeId;
+}
+function ensureEditableSource(source, label) {
+	if (source === "package") throw new Error(`${label} is read-only (package source)`);
+}
+function parseCliJson(raw, schema, label) {
+	const trimmed = raw.trim();
+	if (!trimmed) throw new Error(`${label} returned empty output`);
+	let parsed;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`${label} returned invalid JSON: ${message}`);
+	}
+	const result = schema.safeParse(parsed);
+	if (!result.success) throw new Error(`${label} returned unexpected JSON: ${result.error.message}`);
+	return result.data;
+}
+function resolveEntryPath(root, entryPath) {
+	const normalizedRoot = resolve(root);
+	const resolvedPath = resolve(normalizedRoot, entryPath);
+	const rootPrefix = normalizedRoot + sep;
+	if (resolvedPath !== normalizedRoot && !resolvedPath.startsWith(rootPrefix)) throw new Error("Invalid path: outside schema root");
+	return resolvedPath;
+}
+function toRelativePath(root, absolutePath) {
+	return relative(root, absolutePath).split(sep).join("/");
+}
+async function readEntriesUnderRoot(root) {
+	if (!(await reactiveStat(root))?.isDirectory) return [];
+	const collectEntries = async (dir) => {
+		const names = await reactiveReadDir(dir, { includeHidden: false });
+		const entries = [];
+		for (const name of names) {
+			const fullPath = join(dir, name);
+			const statInfo = await reactiveStat(fullPath);
+			if (!statInfo) continue;
+			const relativePath = toRelativePath(root, fullPath);
+			if (statInfo.isDirectory) {
+				entries.push({
+					path: relativePath,
+					type: "directory"
+				});
+				entries.push(...await collectEntries(fullPath));
+			} else {
+				const content = await reactiveReadFile(fullPath);
+				const size = content ? Buffer.byteLength(content, "utf-8") : void 0;
+				entries.push({
+					path: relativePath,
+					type: "file",
+					content: content ?? void 0,
+					size
+				});
+			}
+		}
+		return entries;
+	};
+	return collectEntries(root);
+}
+async function touchOpsxProjectDeps(projectDir) {
+	const openspecDir = join(projectDir, "openspec");
+	await reactiveReadFile(join(openspecDir, "config.yaml"));
+	const schemaRoot = join(openspecDir, "schemas");
+	const schemaDirs = await reactiveReadDir(schemaRoot, {
+		directoriesOnly: true,
+		includeHidden: true
+	});
+	await Promise.all(schemaDirs.map((name) => reactiveReadFile(join(schemaRoot, name, "schema.yaml"))));
+	await reactiveReadDir(join(openspecDir, "changes"), {
+		directoriesOnly: true,
+		includeHidden: true,
+		exclude: ["archive"]
+	});
+}
+async function touchOpsxChangeDeps(projectDir, changeId) {
+	const changeDir = join(projectDir, "openspec", "changes", changeId);
+	await reactiveReadDir(changeDir, { includeHidden: true });
+	await reactiveReadFile(join(changeDir, ".openspec.yaml"));
+}
+async function readGlobArtifactFiles(projectDir, changeId, outputPath) {
+	return (await readEntriesUnderRoot(join(projectDir, "openspec", "changes", changeId))).filter((entry) => entry.type === "file" && matchesGlob(entry.path, outputPath)).map((entry) => ({
+		path: entry.path,
+		type: "file",
+		content: entry.content ?? ""
+	}));
+}
+async function fetchOpsxStatus(ctx, input) {
+	const changeId = requireChangeId(input.change);
+	await touchOpsxProjectDeps(ctx.projectDir);
+	await touchOpsxChangeDeps(ctx.projectDir, changeId);
+	const args = [
+		"status",
+		"--json",
+		"--change",
+		changeId
+	];
+	if (input.schema) args.push("--schema", input.schema);
+	const result = await ctx.cliExecutor.execute(args);
+	if (!result.success) throw new Error(result.stderr || `openspec status failed (exit ${result.exitCode ?? "null"})`);
+	const status = parseCliJson(result.stdout, ChangeStatusSchema, "openspec status");
+	const changeRelDir = `openspec/changes/${changeId}`;
+	for (const artifact of status.artifacts) artifact.relativePath = `${changeRelDir}/${artifact.outputPath}`;
+	return status;
+}
+async function fetchOpsxStatusList(ctx) {
+	const changeIds = await reactiveReadDir(join(ctx.projectDir, "openspec", "changes"), {
+		directoriesOnly: true,
+		includeHidden: false,
+		exclude: ["archive"]
+	});
+	return await Promise.all(changeIds.map((changeId) => fetchOpsxStatus(ctx, { change: changeId })));
+}
+async function fetchOpsxInstructions(ctx, input) {
+	const changeId = requireChangeId(input.change);
+	await touchOpsxProjectDeps(ctx.projectDir);
+	await touchOpsxChangeDeps(ctx.projectDir, changeId);
+	const args = [
+		"instructions",
+		input.artifact,
+		"--json",
+		"--change",
+		changeId
+	];
+	if (input.schema) args.push("--schema", input.schema);
+	const result = await ctx.cliExecutor.execute(args);
+	if (!result.success) throw new Error(result.stderr || `openspec instructions failed (exit ${result.exitCode ?? "null"})`);
+	return parseCliJson(result.stdout, ArtifactInstructionsSchema, "openspec instructions");
+}
+async function fetchOpsxApplyInstructions(ctx, input) {
+	const changeId = requireChangeId(input.change);
+	await touchOpsxProjectDeps(ctx.projectDir);
+	await touchOpsxChangeDeps(ctx.projectDir, changeId);
+	const args = [
+		"instructions",
+		"apply",
+		"--json",
+		"--change",
+		changeId
+	];
+	if (input.schema) args.push("--schema", input.schema);
+	const result = await ctx.cliExecutor.execute(args);
+	if (!result.success) throw new Error(result.stderr || `openspec instructions apply failed (exit ${result.exitCode ?? "null"})`);
+	return parseCliJson(result.stdout, ApplyInstructionsSchema, "openspec instructions apply");
+}
+async function fetchOpsxSchemas(ctx) {
+	await touchOpsxProjectDeps(ctx.projectDir);
+	const result = await ctx.cliExecutor.schemas();
+	if (!result.success) throw new Error(result.stderr || `openspec schemas failed (exit ${result.exitCode ?? "null"})`);
+	return parseCliJson(result.stdout, z.array(SchemaInfoSchema), "openspec schemas");
+}
+async function fetchOpsxSchemaResolution(ctx, name) {
+	await touchOpsxProjectDeps(ctx.projectDir);
+	const result = await ctx.cliExecutor.schemaWhich(name);
+	if (!result.success) throw new Error(result.stderr || `openspec schema which failed (exit ${result.exitCode ?? "null"})`);
+	return parseCliJson(result.stdout, SchemaResolutionSchema, "openspec schema which");
+}
+async function fetchOpsxTemplates(ctx, schema) {
+	await touchOpsxProjectDeps(ctx.projectDir);
+	const result = await ctx.cliExecutor.templates(schema);
+	if (!result.success) throw new Error(result.stderr || `openspec templates failed (exit ${result.exitCode ?? "null"})`);
+	return parseCliJson(result.stdout, TemplatesSchema, "openspec templates");
+}
+async function fetchOpsxTemplateContents(ctx, schema) {
+	const templates = await fetchOpsxTemplates(ctx, schema);
+	const entries = await Promise.all(Object.entries(templates).map(async ([artifactId, info]) => {
+		return [artifactId, {
+			content: await reactiveReadFile(info.path),
+			path: info.path,
+			source: info.source
+		}];
+	}));
+	return Object.fromEntries(entries);
+}
 /**
 * Spec router - spec CRUD operations
 */
@@ -223,17 +492,8 @@ const changeRouter = router({
 		if (!await ctx.adapter.toggleTask(input.changeId, input.taskIndex, input.completed)) throw new Error(`Failed to toggle task ${input.taskIndex} in change ${input.changeId}`);
 		return { success: true };
 	}),
-	subscribe: publicProcedure.subscription(({ ctx }) => {
-		return createReactiveSubscription(() => ctx.adapter.listChangesWithMeta());
-	}),
-	subscribeOne: publicProcedure.input(z.object({ id: z.string() })).subscription(({ ctx, input }) => {
-		return createReactiveSubscriptionWithInput((id) => ctx.adapter.readChange(id))(input.id);
-	}),
 	subscribeFiles: publicProcedure.input(z.object({ id: z.string() })).subscription(({ ctx, input }) => {
 		return createReactiveSubscriptionWithInput((id) => ctx.adapter.readChangeFiles(id))(input.id);
-	}),
-	subscribeRaw: publicProcedure.input(z.object({ id: z.string() })).subscription(({ ctx, input }) => {
-		return createReactiveSubscriptionWithInput((id) => ctx.adapter.readChangeRaw(id))(input.id);
 	})
 });
 /**
@@ -244,31 +504,6 @@ const initRouter = router({ init: publicProcedure.mutation(async ({ ctx }) => {
 	return { success: true };
 }) });
 /**
-* Project router - project-level files (project.md, AGENTS.md)
-*/
-const projectRouter = router({
-	getProjectMd: publicProcedure.query(async ({ ctx }) => {
-		return ctx.adapter.readProjectMd();
-	}),
-	getAgentsMd: publicProcedure.query(async ({ ctx }) => {
-		return ctx.adapter.readAgentsMd();
-	}),
-	saveProjectMd: publicProcedure.input(z.object({ content: z.string() })).mutation(async ({ ctx, input }) => {
-		await ctx.adapter.writeProjectMd(input.content);
-		return { success: true };
-	}),
-	saveAgentsMd: publicProcedure.input(z.object({ content: z.string() })).mutation(async ({ ctx, input }) => {
-		await ctx.adapter.writeAgentsMd(input.content);
-		return { success: true };
-	}),
-	subscribeProjectMd: publicProcedure.subscription(({ ctx }) => {
-		return createReactiveSubscription(() => ctx.adapter.readProjectMd());
-	}),
-	subscribeAgentsMd: publicProcedure.subscription(({ ctx }) => {
-		return createReactiveSubscription(() => ctx.adapter.readAgentsMd());
-	})
-});
-/**
 * Archive router - archived changes
 */
 const archiveRouter = router({
@@ -501,18 +736,374 @@ const cliRouter = router({
 	})
 });
 /**
+* OPSX router - CLI-driven workflow data
+*/
+const opsxRouter = router({
+	status: publicProcedure.input(z.object({
+		change: z.string().optional(),
+		schema: z.string().optional()
+	})).query(async ({ ctx, input }) => {
+		return fetchOpsxStatus(ctx, input);
+	}),
+	subscribeStatus: publicProcedure.input(z.object({
+		change: z.string().optional(),
+		schema: z.string().optional()
+	})).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(() => fetchOpsxStatus(ctx, input));
+	}),
+	statusList: publicProcedure.query(async ({ ctx }) => {
+		return fetchOpsxStatusList(ctx);
+	}),
+	subscribeStatusList: publicProcedure.subscription(({ ctx }) => {
+		return createReactiveSubscription(() => fetchOpsxStatusList(ctx));
+	}),
+	instructions: publicProcedure.input(z.object({
+		change: z.string().optional(),
+		artifact: z.string(),
+		schema: z.string().optional()
+	})).query(async ({ ctx, input }) => {
+		return fetchOpsxInstructions(ctx, input);
+	}),
+	subscribeInstructions: publicProcedure.input(z.object({
+		change: z.string().optional(),
+		artifact: z.string(),
+		schema: z.string().optional()
+	})).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(() => fetchOpsxInstructions(ctx, input));
+	}),
+	applyInstructions: publicProcedure.input(z.object({
+		change: z.string().optional(),
+		schema: z.string().optional()
+	})).query(async ({ ctx, input }) => {
+		return fetchOpsxApplyInstructions(ctx, input);
+	}),
+	subscribeApplyInstructions: publicProcedure.input(z.object({
+		change: z.string().optional(),
+		schema: z.string().optional()
+	})).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(() => fetchOpsxApplyInstructions(ctx, input));
+	}),
+	schemas: publicProcedure.query(async ({ ctx }) => {
+		return fetchOpsxSchemas(ctx);
+	}),
+	subscribeSchemas: publicProcedure.subscription(({ ctx }) => {
+		return createReactiveSubscription(() => fetchOpsxSchemas(ctx));
+	}),
+	templates: publicProcedure.input(z.object({ schema: z.string().optional() }).optional()).query(async ({ ctx, input }) => {
+		return fetchOpsxTemplates(ctx, input?.schema);
+	}),
+	subscribeTemplates: publicProcedure.input(z.object({ schema: z.string().optional() }).optional()).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(() => fetchOpsxTemplates(ctx, input?.schema));
+	}),
+	templateContents: publicProcedure.input(z.object({ schema: z.string().optional() }).optional()).query(async ({ ctx, input }) => {
+		return fetchOpsxTemplateContents(ctx, input?.schema);
+	}),
+	subscribeTemplateContents: publicProcedure.input(z.object({ schema: z.string().optional() }).optional()).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(() => fetchOpsxTemplateContents(ctx, input?.schema));
+	}),
+	schemaResolution: publicProcedure.input(z.object({ name: z.string() })).query(async ({ ctx, input }) => {
+		return fetchOpsxSchemaResolution(ctx, input.name);
+	}),
+	subscribeSchemaResolution: publicProcedure.input(z.object({ name: z.string() })).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(() => fetchOpsxSchemaResolution(ctx, input.name));
+	}),
+	schemaDetail: publicProcedure.input(z.object({ name: z.string() })).query(async ({ ctx, input }) => {
+		await touchOpsxProjectDeps(ctx.projectDir);
+		const schemaPath = join((await fetchOpsxSchemaResolution(ctx, input.name)).path, "schema.yaml");
+		const content = await reactiveReadFile(schemaPath);
+		if (!content) throw new Error(`schema.yaml not found at ${schemaPath}`);
+		return parseSchemaYaml(content);
+	}),
+	subscribeSchemaDetail: publicProcedure.input(z.object({ name: z.string() })).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(async () => {
+			await touchOpsxProjectDeps(ctx.projectDir);
+			const schemaPath = join((await fetchOpsxSchemaResolution(ctx, input.name)).path, "schema.yaml");
+			const content = await reactiveReadFile(schemaPath);
+			if (!content) throw new Error(`schema.yaml not found at ${schemaPath}`);
+			return parseSchemaYaml(content);
+		});
+	}),
+	schemaFiles: publicProcedure.input(z.object({ name: z.string() })).query(async ({ ctx, input }) => {
+		await touchOpsxProjectDeps(ctx.projectDir);
+		return readEntriesUnderRoot((await fetchOpsxSchemaResolution(ctx, input.name)).path);
+	}),
+	subscribeSchemaFiles: publicProcedure.input(z.object({ name: z.string() })).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(async () => {
+			await touchOpsxProjectDeps(ctx.projectDir);
+			return readEntriesUnderRoot((await fetchOpsxSchemaResolution(ctx, input.name)).path);
+		});
+	}),
+	schemaYaml: publicProcedure.input(z.object({ name: z.string() })).query(async ({ ctx, input }) => {
+		await touchOpsxProjectDeps(ctx.projectDir);
+		return reactiveReadFile(join((await fetchOpsxSchemaResolution(ctx, input.name)).path, "schema.yaml"));
+	}),
+	subscribeSchemaYaml: publicProcedure.input(z.object({ name: z.string() })).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(async () => {
+			await touchOpsxProjectDeps(ctx.projectDir);
+			return reactiveReadFile(join((await fetchOpsxSchemaResolution(ctx, input.name)).path, "schema.yaml"));
+		});
+	}),
+	writeSchemaYaml: publicProcedure.input(z.object({
+		name: z.string(),
+		content: z.string()
+	})).mutation(async ({ ctx, input }) => {
+		await touchOpsxProjectDeps(ctx.projectDir);
+		const resolution = await fetchOpsxSchemaResolution(ctx, input.name);
+		ensureEditableSource(resolution.source, "schema.yaml");
+		const schemaPath = join(resolution.path, "schema.yaml");
+		await mkdir(dirname(schemaPath), { recursive: true });
+		await writeFile(schemaPath, input.content, "utf-8");
+		return { success: true };
+	}),
+	writeSchemaFile: publicProcedure.input(z.object({
+		schema: z.string(),
+		path: z.string(),
+		content: z.string()
+	})).mutation(async ({ ctx, input }) => {
+		await touchOpsxProjectDeps(ctx.projectDir);
+		const resolution = await fetchOpsxSchemaResolution(ctx, input.schema);
+		ensureEditableSource(resolution.source, "schema file");
+		if (!input.path.trim()) throw new Error("path is required");
+		const fullPath = resolveEntryPath(resolution.path, input.path);
+		await mkdir(dirname(fullPath), { recursive: true });
+		await writeFile(fullPath, input.content, "utf-8");
+		return { success: true };
+	}),
+	createSchemaFile: publicProcedure.input(z.object({
+		schema: z.string(),
+		path: z.string(),
+		content: z.string().optional()
+	})).mutation(async ({ ctx, input }) => {
+		await touchOpsxProjectDeps(ctx.projectDir);
+		const resolution = await fetchOpsxSchemaResolution(ctx, input.schema);
+		ensureEditableSource(resolution.source, "schema file");
+		if (!input.path.trim()) throw new Error("path is required");
+		const fullPath = resolveEntryPath(resolution.path, input.path);
+		await mkdir(dirname(fullPath), { recursive: true });
+		await writeFile(fullPath, input.content ?? "", "utf-8");
+		return { success: true };
+	}),
+	createSchemaDirectory: publicProcedure.input(z.object({
+		schema: z.string(),
+		path: z.string()
+	})).mutation(async ({ ctx, input }) => {
+		await touchOpsxProjectDeps(ctx.projectDir);
+		const resolution = await fetchOpsxSchemaResolution(ctx, input.schema);
+		ensureEditableSource(resolution.source, "schema directory");
+		if (!input.path.trim()) throw new Error("path is required");
+		await mkdir(resolveEntryPath(resolution.path, input.path), { recursive: true });
+		return { success: true };
+	}),
+	deleteSchemaEntry: publicProcedure.input(z.object({
+		schema: z.string(),
+		path: z.string()
+	})).mutation(async ({ ctx, input }) => {
+		await touchOpsxProjectDeps(ctx.projectDir);
+		const resolution = await fetchOpsxSchemaResolution(ctx, input.schema);
+		ensureEditableSource(resolution.source, "schema entry");
+		if (!input.path.trim()) throw new Error("path is required");
+		const fullPath = resolveEntryPath(resolution.path, input.path);
+		if (fullPath === resolve(resolution.path)) throw new Error("cannot delete schema root");
+		await rm(fullPath, {
+			recursive: true,
+			force: true
+		});
+		return { success: true };
+	}),
+	templateContent: publicProcedure.input(z.object({
+		schema: z.string(),
+		artifactId: z.string()
+	})).query(async ({ ctx, input }) => {
+		const info = (await fetchOpsxTemplates(ctx, input.schema))[input.artifactId];
+		if (!info) throw new Error(`Template not found for ${input.schema}:${input.artifactId}`);
+		return {
+			content: await reactiveReadFile(info.path),
+			path: info.path,
+			source: info.source
+		};
+	}),
+	subscribeTemplateContent: publicProcedure.input(z.object({
+		schema: z.string(),
+		artifactId: z.string()
+	})).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(async () => {
+			const info = (await fetchOpsxTemplates(ctx, input.schema))[input.artifactId];
+			if (!info) throw new Error(`Template not found for ${input.schema}:${input.artifactId}`);
+			return {
+				content: await reactiveReadFile(info.path),
+				path: info.path,
+				source: info.source
+			};
+		});
+	}),
+	writeTemplateContent: publicProcedure.input(z.object({
+		schema: z.string(),
+		artifactId: z.string(),
+		content: z.string()
+	})).mutation(async ({ ctx, input }) => {
+		const info = (await fetchOpsxTemplates(ctx, input.schema))[input.artifactId];
+		if (!info) throw new Error(`Template not found for ${input.schema}:${input.artifactId}`);
+		ensureEditableSource(info.source, "template");
+		await mkdir(dirname(info.path), { recursive: true });
+		await writeFile(info.path, input.content, "utf-8");
+		return { success: true };
+	}),
+	deleteSchema: publicProcedure.input(z.object({ name: z.string() })).mutation(async ({ ctx, input }) => {
+		await touchOpsxProjectDeps(ctx.projectDir);
+		const resolution = await fetchOpsxSchemaResolution(ctx, input.name);
+		ensureEditableSource(resolution.source, "schema");
+		await rm(resolution.path, {
+			recursive: true,
+			force: true
+		});
+		return { success: true };
+	}),
+	projectConfig: publicProcedure.query(async ({ ctx }) => {
+		return reactiveReadFile(join(ctx.projectDir, "openspec", "config.yaml"));
+	}),
+	subscribeProjectConfig: publicProcedure.subscription(({ ctx }) => {
+		return createReactiveSubscription(async () => {
+			return reactiveReadFile(join(ctx.projectDir, "openspec", "config.yaml"));
+		});
+	}),
+	writeProjectConfig: publicProcedure.input(z.object({ content: z.string() })).mutation(async ({ ctx, input }) => {
+		const openspecDir = join(ctx.projectDir, "openspec");
+		await mkdir(openspecDir, { recursive: true });
+		await writeFile(join(openspecDir, "config.yaml"), input.content, "utf-8");
+		return { success: true };
+	}),
+	updateProjectConfigUi: publicProcedure.input(z.object({
+		"font-size": z.number().min(8).max(32).optional(),
+		"font-families": z.array(z.string()).optional(),
+		"cursor-blink": z.boolean().optional(),
+		"cursor-style": z.enum([
+			"block",
+			"underline",
+			"bar"
+		]).optional(),
+		scrollback: z.number().min(0).max(1e5).optional()
+	})).mutation(async ({ ctx, input }) => {
+		const configPath = join(ctx.projectDir, "openspec", "config.yaml");
+		let doc;
+		try {
+			const content = await readFile(configPath, "utf-8");
+			doc = YAML.parseDocument(content);
+		} catch {
+			doc = new YAML.Document({});
+		}
+		if (!doc.has("ui")) doc.set("ui", doc.createNode({}));
+		const uiNode = doc.get("ui", true);
+		for (const [key, value] of Object.entries(input)) if (value !== void 0) uiNode.set(key, value);
+		await mkdir(join(ctx.projectDir, "openspec"), { recursive: true });
+		await writeFile(configPath, doc.toString(), "utf-8");
+		return { success: true };
+	}),
+	listChanges: publicProcedure.query(async ({ ctx }) => {
+		return reactiveReadDir(join(ctx.projectDir, "openspec", "changes"), {
+			directoriesOnly: true,
+			exclude: ["archive"],
+			includeHidden: false
+		});
+	}),
+	subscribeChanges: publicProcedure.subscription(({ ctx }) => {
+		return createReactiveSubscription(async () => {
+			return reactiveReadDir(join(ctx.projectDir, "openspec", "changes"), {
+				directoriesOnly: true,
+				exclude: ["archive"],
+				includeHidden: false
+			});
+		});
+	}),
+	changeMetadata: publicProcedure.input(z.object({ changeId: z.string() })).query(async ({ ctx, input }) => {
+		return reactiveReadFile(join(ctx.projectDir, "openspec", "changes", input.changeId, ".openspec.yaml"));
+	}),
+	subscribeChangeMetadata: publicProcedure.input(z.object({ changeId: z.string() })).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(async () => {
+			return reactiveReadFile(join(ctx.projectDir, "openspec", "changes", input.changeId, ".openspec.yaml"));
+		});
+	}),
+	readArtifactOutput: publicProcedure.input(z.object({
+		changeId: z.string(),
+		outputPath: z.string()
+	})).query(async ({ ctx, input }) => {
+		return reactiveReadFile(join(ctx.projectDir, "openspec", "changes", input.changeId, input.outputPath));
+	}),
+	subscribeArtifactOutput: publicProcedure.input(z.object({
+		changeId: z.string(),
+		outputPath: z.string()
+	})).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(async () => {
+			return reactiveReadFile(join(ctx.projectDir, "openspec", "changes", input.changeId, input.outputPath));
+		});
+	}),
+	readGlobArtifactFiles: publicProcedure.input(z.object({
+		changeId: z.string(),
+		outputPath: z.string()
+	})).query(async ({ ctx, input }) => {
+		return readGlobArtifactFiles(ctx.projectDir, input.changeId, input.outputPath);
+	}),
+	subscribeGlobArtifactFiles: publicProcedure.input(z.object({
+		changeId: z.string(),
+		outputPath: z.string()
+	})).subscription(({ ctx, input }) => {
+		return createReactiveSubscription(async () => {
+			return readGlobArtifactFiles(ctx.projectDir, input.changeId, input.outputPath);
+		});
+	}),
+	writeArtifactOutput: publicProcedure.input(z.object({
+		changeId: z.string(),
+		outputPath: z.string(),
+		content: z.string()
+	})).mutation(async ({ ctx, input }) => {
+		await writeFile(join(ctx.projectDir, "openspec", "changes", input.changeId, input.outputPath), input.content, "utf-8");
+		return { success: true };
+	})
+});
+/**
+* KV router - in-memory reactive key-value store
+* No disk persistence — devices use IndexedDB for their own storage.
+*/
+const kvRouter = router({
+	get: publicProcedure.input(z.object({ key: z.string() })).query(({ input }) => {
+		return reactiveKV.get(input.key) ?? null;
+	}),
+	set: publicProcedure.input(z.object({
+		key: z.string(),
+		value: z.unknown()
+	})).mutation(({ input }) => {
+		reactiveKV.set(input.key, input.value);
+		return { success: true };
+	}),
+	delete: publicProcedure.input(z.object({ key: z.string() })).mutation(({ input }) => {
+		reactiveKV.delete(input.key);
+		return { success: true };
+	}),
+	subscribe: publicProcedure.input(z.object({ key: z.string() })).subscription(({ input }) => {
+		return observable((emit) => {
+			const current = reactiveKV.get(input.key);
+			emit.next(current ?? null);
+			const unsub = reactiveKV.onKey(input.key, (value) => {
+				emit.next(value ?? null);
+			});
+			return () => {
+				unsub();
+			};
+		});
+	})
+});
+/**
 * Main app router
 */
 const appRouter = router({
-	dashboard: dashboardRouter,
 	spec: specRouter,
 	change: changeRouter,
 	archive: archiveRouter,
-	project: projectRouter,
 	init: initRouter,
 	realtime: realtimeRouter,
 	config: configRouter,
-	cli: cliRouter
+	cli: cliRouter,
+	opsx: opsxRouter,
+	kv: kvRouter
 });
 
 //#endregion
@@ -522,13 +1113,13 @@ const appRouter = router({
 * Uses default binding (both IPv4 and IPv6) to detect conflicts.
 */
 function isPortAvailable(port) {
-	return new Promise((resolve) => {
+	return new Promise((resolve$1) => {
 		const server = createServer$1();
 		server.once("error", () => {
-			resolve(false);
+			resolve$1(false);
 		});
 		server.once("listening", () => {
-			server.close(() => resolve(true));
+			server.close(() => resolve$1(true));
 		});
 		server.listen(port);
 	});
@@ -550,6 +1141,340 @@ async function findAvailablePort(startPort, maxAttempts = 10) {
 	throw new Error(`No available port found in range ${startPort}-${startPort + maxAttempts - 1}`);
 }
 
+//#endregion
+//#region src/pty-manager.ts
+const DEFAULT_SCROLLBACK = 1e3;
+const DEFAULT_MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+function detectPtyPlatform() {
+	if (process.platform === "win32") return "windows";
+	if (process.platform === "darwin") return "macos";
+	return "common";
+}
+var PtySession = class extends EventEmitter$1 {
+	id;
+	command;
+	args;
+	platform;
+	createdAt;
+	process;
+	titleInterval = null;
+	lastTitle = "";
+	buffer = [];
+	bufferByteLength = 0;
+	maxBufferLines;
+	maxBufferBytes;
+	isExited = false;
+	exitCode = null;
+	constructor(id, opts) {
+		super();
+		this.id = id;
+		this.createdAt = Date.now();
+		const shell = opts.command ?? process.env.SHELL ?? "/bin/sh";
+		const args = opts.command ? opts.args ?? [] : [];
+		this.command = shell;
+		this.args = args;
+		this.platform = opts.platform;
+		this.maxBufferLines = opts.scrollback ?? DEFAULT_SCROLLBACK;
+		this.maxBufferBytes = opts.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+		this.process = pty.spawn(shell, args, {
+			name: "xterm-256color",
+			cols: opts.cols ?? 80,
+			rows: opts.rows ?? 24,
+			cwd: opts.cwd,
+			env: {
+				...process.env,
+				TERM: "xterm-256color"
+			}
+		});
+		this.process.onData((data) => {
+			this.appendBuffer(data);
+			this.emit("data", data);
+		});
+		this.process.onExit(({ exitCode }) => {
+			if (this.titleInterval) {
+				clearInterval(this.titleInterval);
+				this.titleInterval = null;
+			}
+			this.isExited = true;
+			this.exitCode = exitCode;
+			this.emit("exit", exitCode);
+		});
+		this.titleInterval = setInterval(() => {
+			try {
+				const title = this.process.process;
+				if (title && title !== this.lastTitle) {
+					this.lastTitle = title;
+					this.emit("title", title);
+				}
+			} catch {}
+		}, 1e3);
+	}
+	get title() {
+		return this.lastTitle;
+	}
+	appendBuffer(data) {
+		let chunk = data;
+		if (chunk.length > this.maxBufferBytes) chunk = chunk.slice(-this.maxBufferBytes);
+		this.buffer.push(chunk);
+		this.bufferByteLength += chunk.length;
+		while (this.bufferByteLength > this.maxBufferBytes && this.buffer.length > 0) {
+			const removed = this.buffer.shift();
+			this.bufferByteLength -= removed.length;
+		}
+		while (this.buffer.length > this.maxBufferLines) {
+			const removed = this.buffer.shift();
+			this.bufferByteLength -= removed.length;
+		}
+	}
+	getBuffer() {
+		return this.buffer.join("");
+	}
+	write(data) {
+		if (!this.isExited) this.process.write(data);
+	}
+	resize(cols, rows) {
+		if (!this.isExited) this.process.resize(cols, rows);
+	}
+	close() {
+		if (this.titleInterval) {
+			clearInterval(this.titleInterval);
+			this.titleInterval = null;
+		}
+		try {
+			this.process.kill();
+		} catch {}
+		this.removeAllListeners();
+	}
+	toInfo() {
+		return {
+			id: this.id,
+			title: this.lastTitle,
+			command: this.command,
+			args: this.args,
+			platform: this.platform,
+			isExited: this.isExited,
+			exitCode: this.exitCode,
+			createdAt: this.createdAt
+		};
+	}
+};
+var PtyManager = class {
+	sessions = /* @__PURE__ */ new Map();
+	idCounter = 0;
+	platform;
+	constructor(defaultCwd) {
+		this.defaultCwd = defaultCwd;
+		this.platform = detectPtyPlatform();
+	}
+	create(opts) {
+		const id = `pty-${++this.idCounter}`;
+		const session = new PtySession(id, {
+			cols: opts.cols,
+			rows: opts.rows,
+			command: opts.command,
+			args: opts.args,
+			cwd: this.defaultCwd,
+			scrollback: opts.scrollback,
+			maxBufferBytes: opts.maxBufferBytes,
+			platform: this.platform
+		});
+		this.sessions.set(id, session);
+		return session;
+	}
+	get(id) {
+		return this.sessions.get(id);
+	}
+	list() {
+		const result = [];
+		for (const session of this.sessions.values()) result.push(session.toInfo());
+		return result;
+	}
+	write(id, data) {
+		this.sessions.get(id)?.write(data);
+	}
+	resize(id, cols, rows) {
+		this.sessions.get(id)?.resize(cols, rows);
+	}
+	close(id) {
+		const session = this.sessions.get(id);
+		if (session) {
+			session.close();
+			this.sessions.delete(id);
+		}
+	}
+	closeAll() {
+		for (const session of this.sessions.values()) session.close();
+		this.sessions.clear();
+	}
+};
+
+//#endregion
+//#region src/pty-websocket.ts
+function createPtyWebSocketHandler(ptyManager) {
+	return (ws) => {
+		const cleanups = /* @__PURE__ */ new Map();
+		const send = (msg) => {
+			if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg));
+		};
+		const sendError = (code, message, opts) => {
+			send({
+				type: "error",
+				code,
+				message,
+				sessionId: opts?.sessionId
+			});
+		};
+		const attachToSession = (session, opts) => {
+			const sessionId = session.id;
+			cleanups.get(sessionId)?.();
+			if (opts?.cols && opts?.rows && !session.isExited) session.resize(opts.cols, opts.rows);
+			const onData = (data) => {
+				send({
+					type: "output",
+					sessionId,
+					data
+				});
+			};
+			const onExit = (exitCode) => {
+				send({
+					type: "exit",
+					sessionId,
+					exitCode
+				});
+			};
+			const onTitle = (title) => {
+				send({
+					type: "title",
+					sessionId,
+					title
+				});
+			};
+			session.on("data", onData);
+			session.on("exit", onExit);
+			session.on("title", onTitle);
+			cleanups.set(sessionId, () => {
+				session.removeListener("data", onData);
+				session.removeListener("exit", onExit);
+				session.removeListener("title", onTitle);
+				cleanups.delete(sessionId);
+			});
+		};
+		ws.on("message", (raw) => {
+			let parsed;
+			try {
+				parsed = JSON.parse(String(raw));
+			} catch {
+				sendError("INVALID_JSON", "Invalid JSON payload");
+				return;
+			}
+			const parsedMessage = PtyClientMessageSchema.safeParse(parsed);
+			if (!parsedMessage.success) {
+				const firstIssue = parsedMessage.error.issues[0]?.message;
+				sendError("INVALID_MESSAGE", firstIssue ?? "Invalid PTY message");
+				return;
+			}
+			const msg = parsedMessage.data;
+			switch (msg.type) {
+				case "create": {
+					const session = ptyManager.create({
+						cols: msg.cols,
+						rows: msg.rows,
+						command: msg.command,
+						args: msg.args
+					});
+					send({
+						type: "created",
+						requestId: msg.requestId,
+						sessionId: session.id,
+						platform: session.platform
+					});
+					attachToSession(session);
+					break;
+				}
+				case "attach": {
+					const session = ptyManager.get(msg.sessionId);
+					if (!session) {
+						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
+						send({
+							type: "exit",
+							sessionId: msg.sessionId,
+							exitCode: -1
+						});
+						break;
+					}
+					attachToSession(session, {
+						cols: msg.cols,
+						rows: msg.rows
+					});
+					const buffer = session.getBuffer();
+					if (buffer) send({
+						type: "buffer",
+						sessionId: session.id,
+						data: buffer
+					});
+					if (session.title) send({
+						type: "title",
+						sessionId: session.id,
+						title: session.title
+					});
+					if (session.isExited) send({
+						type: "exit",
+						sessionId: session.id,
+						exitCode: session.exitCode ?? -1
+					});
+					break;
+				}
+				case "list":
+					send({
+						type: "list",
+						sessions: ptyManager.list().map((s) => ({
+							id: s.id,
+							title: s.title,
+							command: s.command,
+							args: s.args,
+							platform: s.platform,
+							isExited: s.isExited,
+							exitCode: s.exitCode
+						}))
+					});
+					break;
+				case "input": {
+					const session = ptyManager.get(msg.sessionId);
+					if (!session) {
+						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
+						break;
+					}
+					session.write(msg.data);
+					break;
+				}
+				case "resize": {
+					const session = ptyManager.get(msg.sessionId);
+					if (!session) {
+						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
+						break;
+					}
+					session.resize(msg.cols, msg.rows);
+					break;
+				}
+				case "close": {
+					const session = ptyManager.get(msg.sessionId);
+					if (!session) {
+						sendError("SESSION_NOT_FOUND", `Session not found: ${msg.sessionId}`, { sessionId: msg.sessionId });
+						break;
+					}
+					cleanups.get(msg.sessionId)?.();
+					ptyManager.close(session.id);
+					break;
+				}
+			}
+		});
+		ws.on("close", () => {
+			for (const cleanup of cleanups.values()) cleanup();
+			cleanups.clear();
+		});
+	};
+}
+
 //#endregion
 //#region src/server.ts
 /**
@@ -571,6 +1496,7 @@ function createServer(config) {
 	const adapter = new OpenSpecAdapter(config.projectDir);
 	const configManager = new ConfigManager(config.projectDir);
 	const cliExecutor = new CliExecutor(configManager, config.projectDir);
+	const kernel = config.kernel;
 	const watcher = config.enableWatcher !== false ? new OpenSpecWatcher(config.projectDir) : void 0;
 	const app = new Hono();
 	const corsOrigins = config.corsOrigins ?? ["http://localhost:5173", "http://localhost:3000"];
@@ -594,6 +1520,7 @@ function createServer(config) {
 				adapter,
 				configManager,
 				cliExecutor,
+				kernel,
 				watcher,
 				projectDir: config.projectDir
 			})
@@ -603,6 +1530,7 @@ function createServer(config) {
 		adapter,
 		configManager,
 		cliExecutor,
+		kernel,
 		watcher,
 		projectDir: config.projectDir
 	});
@@ -611,34 +1539,46 @@ function createServer(config) {
 		adapter,
 		configManager,
 		cliExecutor,
+		kernel,
 		watcher,
 		createContext,
 		port: config.port ?? 3100
 	};
 }
 /**
-* Create WebSocket server for tRPC subscriptions
+* Create WebSocket server for tRPC subscriptions and PTY terminals
 */
 async function createWebSocketServer(server, httpServer, config) {
-	await initWatcherPool(config.projectDir);
+	if (!isWatcherPoolInitialized()) await initWatcherPool(config.projectDir);
 	const wss = new WebSocketServer({ noServer: true });
 	const handler = applyWSSHandler({
 		wss,
 		router: appRouter,
 		createContext: server.createContext
 	});
+	const ptyManager = new PtyManager(config.projectDir);
+	const ptyWss = new WebSocketServer({ noServer: true });
+	const ptyHandler = createPtyWebSocketHandler(ptyManager);
+	ptyWss.on("connection", ptyHandler);
 	httpServer.on("upgrade", (...args) => {
 		const [request, socket, head] = args;
-		if (request.url?.startsWith("/trpc")) wss.handleUpgrade(request, socket, head, (ws) => {
+		if (request.url?.startsWith("/ws/pty")) ptyWss.handleUpgrade(request, socket, head, (ws) => {
+			ptyWss.emit("connection", ws, request);
+		});
+		else if (request.url?.startsWith("/trpc")) wss.handleUpgrade(request, socket, head, (ws) => {
 			wss.emit("connection", ws, request);
 		});
 	});
 	server.watcher?.start();
 	return {
 		wss,
+		ptyWss,
+		ptyManager,
 		handler,
 		close: () => {
 			handler.broadcastReconnectNotification();
+			ptyManager.closeAll();
+			ptyWss.close();
 			wss.close();
 			server.watcher?.stop();
 		}
@@ -655,9 +1595,13 @@ async function createWebSocketServer(server, httpServer, config) {
 async function startServer(config, setupApp) {
 	const preferredPort = config.port ?? 3100;
 	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);
 	const server = createServer({
 		...config,
-		port
+		port,
+		kernel
 	});
 	if (setupApp) setupApp(server.app);
 	const httpServer = serve({
@@ -665,11 +1609,16 @@ async function startServer(config, setupApp) {
 		port
 	});
 	const wsServer = await createWebSocketServer(server, httpServer, { projectDir: config.projectDir });
+	const url = `http://localhost:${port}`;
+	kernel.warmup().catch((err) => {
+		console.error("Kernel warmup failed:", err);
+	});
 	return {
-		url: `http://localhost:${port}`,
+		url,
 		port,
 		preferredPort,
 		close: async () => {
+			kernel.dispose();
 			wsServer.close();
 			httpServer.close();
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openspecui/server",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "type": "module",
   "main": "dist/index.mjs",
   "exports": {
@@ -13,12 +13,14 @@
   ],
   "dependencies": {
     "@hono/node-server": "^1.14.1",
+    "@lydell/node-pty": "^1.1.0",
     "@trpc/server": "^11.0.0",
     "hono": "^4.7.3",
     "ws": "^8.18.0",
+    "yaml": "^2.8.0",
     "yargs": "^18.0.0",
     "zod": "^3.24.1",
-    "@openspecui/core": "0.9.0"
+    "@openspecui/core": "1.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
@@ -31,7 +33,7 @@
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm --no-dts",
-    "typecheck": "tsc --noEmit -p tsconfig.check.json",
+    "typecheck": "tsc --noEmit",
     "dev": "tsx watch src/standalone.ts",
     "test": "vitest run",
     "test:watch": "vitest"