@openspecui/server 1.2.0 → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenSpecUI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.mjs

@@ -1,20 +1,22 @@
+import { createServer as createServer$1 } from "node:net";
 import { serve } from "@hono/node-server";
-import { CliExecutor, ConfigManager, OpenSpecAdapter, OpenSpecWatcher, OpsxKernel, PtyClientMessageSchema, ReactiveContext, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, initWatcherPool, isWatcherPoolInitialized, sniffGlobalCli } from "@openspecui/core";
+import { CliExecutor, ConfigManager, DASHBOARD_METRIC_KEYS, DashboardConfigSchema, OpenSpecAdapter, OpenSpecWatcher, OpsxKernel, PtyClientMessageSchema, ReactiveContext, TerminalConfigSchema, TerminalRendererEngineSchema, contextStorage, getAllTools, getAvailableTools, getConfiguredTools, getDefaultCliCommandString, getWatcherRuntimeStatus, initWatcherPool, isWatcherPoolInitialized, reactiveExists, reactiveReadDir, reactiveReadFile, sniffGlobalCli } 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 { WebSocketServer } from "ws";
-import { createServer as createServer$1 } from "node:net";
 import * as pty from "@lydell/node-pty";
 import { EventEmitter } from "events";
 import { SearchQuerySchema } from "@openspecui/search";
 import { initTRPC } from "@trpc/server";
 import { observable } from "@trpc/server/observable";
+import { execFile } from "node:child_process";
+import { EventEmitter as EventEmitter$1 } from "node:events";
 import { mkdir, rm, writeFile } from "node:fs/promises";
-import { dirname, join, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
 import { z } from "zod";
-import { EventEmitter as EventEmitter$1 } from "node:events";
 import { NodeWorkerSearchProvider } from "@openspecui/search/node";
 
 //#region src/port-utils.ts
@@ -477,6 +479,368 @@ function createCliStreamObservable(startStream) {
 	});
 }
 
+//#endregion
+//#region src/dashboard-git-snapshot.ts
+const execFileAsync$1 = promisify(execFile);
+const EMPTY_DIFF = {
+	files: 0,
+	insertions: 0,
+	deletions: 0
+};
+async function defaultRunGit(cwd, args) {
+	try {
+		const { stdout } = await execFileAsync$1("git", args, {
+			cwd,
+			encoding: "utf8",
+			maxBuffer: 8 * 1024 * 1024
+		});
+		return {
+			ok: true,
+			stdout
+		};
+	} catch {
+		return {
+			ok: false,
+			stdout: ""
+		};
+	}
+}
+function parseShortStat(output) {
+	const files = Number(/(\d+)\s+files? changed/.exec(output)?.[1] ?? 0);
+	const insertions = Number(/(\d+)\s+insertions?\(\+\)/.exec(output)?.[1] ?? 0);
+	const deletions = Number(/(\d+)\s+deletions?\(-\)/.exec(output)?.[1] ?? 0);
+	return {
+		files: Number.isFinite(files) ? files : 0,
+		insertions: Number.isFinite(insertions) ? insertions : 0,
+		deletions: Number.isFinite(deletions) ? deletions : 0
+	};
+}
+function parseNumStat(output) {
+	let files = 0;
+	let insertions = 0;
+	let deletions = 0;
+	for (const line of output.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const [addRaw, deleteRaw] = trimmed.split("	");
+		if (!addRaw || !deleteRaw) continue;
+		files += 1;
+		if (addRaw !== "-") insertions += Number(addRaw) || 0;
+		if (deleteRaw !== "-") deletions += Number(deleteRaw) || 0;
+	}
+	return {
+		files,
+		insertions,
+		deletions
+	};
+}
+function normalizeGitPath(path) {
+	return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function relativePath(fromDir, target) {
+	const rel = relative(fromDir, target);
+	if (!rel || rel.length === 0) return ".";
+	return rel;
+}
+function parseBranchName(branchRef, detached) {
+	if (detached) return "(detached)";
+	if (!branchRef) return "(unknown)";
+	return branchRef.replace(/^refs\/heads\//, "");
+}
+function parseWorktreeList(porcelain) {
+	const entries = [];
+	let current = null;
+	const flush = () => {
+		if (!current) return;
+		entries.push(current);
+		current = null;
+	};
+	for (const line of porcelain.split("\n")) {
+		if (line.startsWith("worktree ")) {
+			flush();
+			current = {
+				path: line.slice(9).trim(),
+				branchRef: null,
+				detached: false
+			};
+			continue;
+		}
+		if (!current) continue;
+		if (line.startsWith("branch ")) {
+			current.branchRef = line.slice(7).trim();
+			continue;
+		}
+		if (line === "detached") {
+			current.detached = true;
+			continue;
+		}
+	}
+	flush();
+	return entries;
+}
+function parseRelatedChanges(paths) {
+	const related = /* @__PURE__ */ new Set();
+	for (const path of paths) {
+		const normalized = normalizeGitPath(path);
+		const activeMatch = /^openspec\/changes\/([^/]+)\//.exec(normalized);
+		if (activeMatch?.[1]) {
+			related.add(activeMatch[1]);
+			continue;
+		}
+		const archiveMatch = /^openspec\/changes\/archive\/([^/]+)\//.exec(normalized);
+		if (archiveMatch?.[1]) {
+			const fullName = archiveMatch[1];
+			related.add(fullName.replace(/^\d{4}-\d{2}-\d{2}-/, ""));
+		}
+	}
+	return [...related].sort((a, b) => a.localeCompare(b));
+}
+async function resolveDefaultBranch(projectDir, runGit) {
+	const remoteHead = await runGit(projectDir, [
+		"symbolic-ref",
+		"--quiet",
+		"--short",
+		"refs/remotes/origin/HEAD"
+	]);
+	const remoteRef = remoteHead.stdout.trim();
+	if (remoteHead.ok && remoteRef) return remoteRef;
+	const localHead = await runGit(projectDir, [
+		"rev-parse",
+		"--abbrev-ref",
+		"HEAD"
+	]);
+	const localRef = localHead.stdout.trim();
+	if (localHead.ok && localRef && localRef !== "HEAD") return localRef;
+	return "main";
+}
+async function collectCommitEntries(options) {
+	const { worktreePath, defaultBranch, maxCommitEntries, runGit } = options;
+	const entries = [];
+	const commits = await runGit(worktreePath, [
+		"log",
+		"--format=%H%x1f%s",
+		`-n${maxCommitEntries}`,
+		`${defaultBranch}..HEAD`
+	]);
+	if (commits.ok) for (const line of commits.stdout.split("\n")) {
+		if (!line.trim()) continue;
+		const [hash, title = ""] = line.split("");
+		if (!hash) continue;
+		const diffResult = await runGit(worktreePath, [
+			"show",
+			"--numstat",
+			"--format=",
+			hash
+		]);
+		const changedFiles = (await runGit(worktreePath, [
+			"show",
+			"--name-only",
+			"--format=",
+			hash
+		])).stdout.split("\n").map((item) => item.trim()).filter((item) => item.length > 0);
+		entries.push({
+			type: "commit",
+			hash,
+			title: title.trim() || hash.slice(0, 7),
+			relatedChanges: parseRelatedChanges(changedFiles),
+			diff: diffResult.ok ? parseNumStat(diffResult.stdout) : EMPTY_DIFF
+		});
+	}
+	const trackedResult = await runGit(worktreePath, [
+		"diff",
+		"--numstat",
+		"HEAD"
+	]);
+	const trackedFilesResult = await runGit(worktreePath, [
+		"diff",
+		"--name-only",
+		"HEAD"
+	]);
+	const untrackedResult = await runGit(worktreePath, [
+		"ls-files",
+		"--others",
+		"--exclude-standard"
+	]);
+	const trackedFiles = trackedFilesResult.stdout.split("\n").map((item) => item.trim()).filter((item) => item.length > 0);
+	const untrackedFiles = untrackedResult.stdout.split("\n").map((item) => item.trim()).filter((item) => item.length > 0);
+	const allUncommittedFiles = new Set([...trackedFiles, ...untrackedFiles]);
+	const trackedDiff = trackedResult.ok ? parseNumStat(trackedResult.stdout) : EMPTY_DIFF;
+	entries.push({
+		type: "uncommitted",
+		title: "Uncommitted",
+		relatedChanges: parseRelatedChanges([...allUncommittedFiles]),
+		diff: {
+			files: allUncommittedFiles.size,
+			insertions: trackedDiff.insertions,
+			deletions: trackedDiff.deletions
+		}
+	});
+	return entries;
+}
+async function collectWorktree(options) {
+	const { projectDir, worktree, defaultBranch, runGit, maxCommitEntries } = options;
+	const worktreePath = resolve(worktree.path);
+	const resolvedProjectDir = resolve(projectDir);
+	const aheadBehindResult = await runGit(worktreePath, [
+		"rev-list",
+		"--left-right",
+		"--count",
+		`${defaultBranch}...HEAD`
+	]);
+	let ahead = 0;
+	let behind = 0;
+	if (aheadBehindResult.ok) {
+		const [behindRaw, aheadRaw] = aheadBehindResult.stdout.trim().split(/\s+/);
+		ahead = Number(aheadRaw) || 0;
+		behind = Number(behindRaw) || 0;
+	}
+	const diffResult = await runGit(worktreePath, [
+		"diff",
+		"--shortstat",
+		`${defaultBranch}...HEAD`
+	]);
+	const diff = diffResult.ok ? parseShortStat(diffResult.stdout) : EMPTY_DIFF;
+	const entries = await collectCommitEntries({
+		worktreePath,
+		defaultBranch,
+		maxCommitEntries,
+		runGit
+	});
+	return {
+		path: worktreePath,
+		relativePath: relativePath(resolvedProjectDir, worktreePath),
+		branchName: parseBranchName(worktree.branchRef, worktree.detached),
+		isCurrent: resolvedProjectDir === worktreePath,
+		ahead,
+		behind,
+		diff,
+		entries
+	};
+}
+async function buildDashboardGitSnapshot(options) {
+	const runGit = options.runGit ?? defaultRunGit;
+	const maxCommitEntries = options.maxCommitEntries ?? 8;
+	const resolvedProjectDir = resolve(options.projectDir);
+	const defaultBranch = await resolveDefaultBranch(resolvedProjectDir, runGit);
+	const worktreeResult = await runGit(resolvedProjectDir, [
+		"worktree",
+		"list",
+		"--porcelain"
+	]);
+	const parsed = worktreeResult.ok ? parseWorktreeList(worktreeResult.stdout) : [];
+	const baseWorktrees = parsed.length > 0 ? parsed : [{
+		path: resolvedProjectDir,
+		branchRef: null,
+		detached: false
+	}];
+	const worktrees = await Promise.all(baseWorktrees.map((worktree) => collectWorktree({
+		projectDir: resolvedProjectDir,
+		worktree,
+		defaultBranch,
+		runGit,
+		maxCommitEntries
+	})));
+	worktrees.sort((a, b) => {
+		if (a.isCurrent !== b.isCurrent) return a.isCurrent ? -1 : 1;
+		return a.branchName.localeCompare(b.branchName);
+	});
+	return {
+		defaultBranch,
+		worktrees
+	};
+}
+
+//#endregion
+//#region src/dashboard-time-trends.ts
+const MIN_TREND_POINT_LIMIT = 20;
+const MAX_TREND_POINT_LIMIT = 500;
+const DEFAULT_TREND_POINT_LIMIT = 100;
+const TARGET_TREND_BARS = 20;
+const DAY_MS = 1440 * 60 * 1e3;
+function clampPointLimit(pointLimit) {
+	if (!Number.isFinite(pointLimit)) return DEFAULT_TREND_POINT_LIMIT;
+	return Math.max(MIN_TREND_POINT_LIMIT, Math.min(MAX_TREND_POINT_LIMIT, Math.trunc(pointLimit)));
+}
+function createEmptyTrendSeries() {
+	return Object.fromEntries(DASHBOARD_METRIC_KEYS.map((metric) => [metric, []]));
+}
+function normalizeEvents(events, pointLimit) {
+	return events.filter((event) => Number.isFinite(event.ts) && event.ts > 0 && Number.isFinite(event.value)).sort((a, b) => a.ts - b.ts).slice(-pointLimit);
+}
+function buildTimeWindow(options) {
+	const { probeEvents, targetBars, rightEdgeTs } = options;
+	if (probeEvents.length === 0) return null;
+	const probeEnd = probeEvents[probeEvents.length - 1].ts;
+	const end = typeof rightEdgeTs === "number" && Number.isFinite(rightEdgeTs) && rightEdgeTs > 0 ? Math.max(probeEnd, rightEdgeTs) : probeEnd;
+	const probeStart = probeEvents[0].ts;
+	const rangeMs = Math.max(1, end - probeStart);
+	const bucketMs = rangeMs >= DAY_MS ? Math.max(DAY_MS, Math.ceil(rangeMs / targetBars / DAY_MS) * DAY_MS) : Math.max(1, Math.ceil(rangeMs / targetBars));
+	const windowStart = end - bucketMs * targetBars;
+	return {
+		windowStart,
+		bucketMs,
+		bucketEnds: Array.from({ length: targetBars }, (_, index) => windowStart + bucketMs * (index + 1))
+	};
+}
+function bucketizeTrend(events, reducer, rightEdgeTs) {
+	if (events.length === 0) return [];
+	const timeWindow = buildTimeWindow({
+		probeEvents: events,
+		targetBars: TARGET_TREND_BARS,
+		rightEdgeTs
+	});
+	if (!timeWindow) return [];
+	const { windowStart, bucketMs, bucketEnds } = timeWindow;
+	const sums = Array.from({ length: bucketEnds.length }, () => 0);
+	const counts = Array.from({ length: bucketEnds.length }, () => 0);
+	let baseline = 0;
+	for (const event of events) {
+		if (event.ts <= windowStart) {
+			if (reducer === "sum-cumulative") baseline += event.value;
+			continue;
+		}
+		const offset = event.ts - windowStart;
+		const index = Math.max(0, Math.min(bucketEnds.length - 1, Math.ceil(offset / bucketMs) - 1));
+		sums[index] += event.value;
+		counts[index] += 1;
+	}
+	let cumulative = baseline;
+	let carry = baseline !== 0 ? baseline : events[0].value;
+	return bucketEnds.map((ts, index) => {
+		if (reducer === "sum") return {
+			ts,
+			value: sums[index]
+		};
+		if (reducer === "sum-cumulative") {
+			cumulative += sums[index];
+			return {
+				ts,
+				value: cumulative
+			};
+		}
+		if (counts[index] > 0) carry = sums[index] / counts[index];
+		return {
+			ts,
+			value: carry
+		};
+	});
+}
+function buildDashboardTimeTrends(options) {
+	const pointLimit = clampPointLimit(options.pointLimit);
+	const trends = createEmptyTrendSeries();
+	for (const metric of DASHBOARD_METRIC_KEYS) {
+		if (options.availability[metric].state !== "ok") continue;
+		trends[metric] = bucketizeTrend(normalizeEvents(options.events[metric], pointLimit), options.reducers?.[metric] ?? "sum", options.rightEdgeTs);
+	}
+	return {
+		trends,
+		trendMeta: {
+			pointLimit,
+			lastUpdatedAt: options.timestamp
+		}
+	};
+}
+
 //#endregion
 //#region src/reactive-kv.ts
 /**
@@ -597,6 +961,76 @@ function createReactiveSubscriptionWithInput(task) {
 const t = initTRPC.context().create();
 const router = t.router;
 const publicProcedure = t.procedure;
+const execFileAsync = promisify(execFile);
+const dashboardGitTaskStatusEmitter = new EventEmitter$1();
+dashboardGitTaskStatusEmitter.setMaxListeners(200);
+const dashboardGitTaskStatus = {
+	running: false,
+	inFlight: 0,
+	lastStartedAt: null,
+	lastFinishedAt: null,
+	lastReason: null,
+	lastError: null
+};
+function getDashboardGitTaskStatus() {
+	return { ...dashboardGitTaskStatus };
+}
+function emitDashboardGitTaskStatus() {
+	dashboardGitTaskStatusEmitter.emit("change", getDashboardGitTaskStatus());
+}
+function beginDashboardGitTask(reason) {
+	dashboardGitTaskStatus.inFlight += 1;
+	dashboardGitTaskStatus.running = true;
+	dashboardGitTaskStatus.lastStartedAt = Date.now();
+	dashboardGitTaskStatus.lastReason = reason;
+	dashboardGitTaskStatus.lastError = null;
+	emitDashboardGitTaskStatus();
+}
+function endDashboardGitTask(error) {
+	dashboardGitTaskStatus.inFlight = Math.max(0, dashboardGitTaskStatus.inFlight - 1);
+	dashboardGitTaskStatus.running = dashboardGitTaskStatus.inFlight > 0;
+	dashboardGitTaskStatus.lastFinishedAt = Date.now();
+	if (error) dashboardGitTaskStatus.lastError = error instanceof Error ? error.message : String(error);
+	emitDashboardGitTaskStatus();
+}
+function parseGitDirFromDotGitFile(content) {
+	const line = content.split(/\r?\n/).map((item) => item.trim()).find((item) => item.startsWith("gitdir:"));
+	if (!line) return null;
+	const rawPath = line.slice(7).trim();
+	return rawPath.length > 0 ? rawPath : null;
+}
+function getDashboardGitRefreshStampPath(projectDir) {
+	return join(projectDir, "openspec", ".openspecui-dashboard-git-refresh.stamp");
+}
+async function touchDashboardGitRefreshStamp(projectDir, reason) {
+	const stampPath = getDashboardGitRefreshStampPath(projectDir);
+	await mkdir(dirname(stampPath), { recursive: true });
+	await writeFile(stampPath, `${Date.now()} ${reason}\n`, "utf8");
+}
+async function registerDashboardGitReactiveDeps(projectDir) {
+	await reactiveReadDir(projectDir, {
+		includeHidden: true,
+		exclude: ["node_modules"]
+	});
+	await reactiveReadFile(getDashboardGitRefreshStampPath(projectDir));
+	const dotGitPath = join(projectDir, ".git");
+	if (!await reactiveExists(dotGitPath)) return;
+	const dotGitFileContent = await reactiveReadFile(dotGitPath);
+	if (dotGitFileContent !== null) {
+		const gitDirRaw = parseGitDirFromDotGitFile(dotGitFileContent);
+		if (!gitDirRaw) return;
+		const gitDirPath = resolve(projectDir, gitDirRaw);
+		await reactiveReadDir(gitDirPath, { includeHidden: true });
+		await reactiveReadFile(join(gitDirPath, "HEAD"));
+		await reactiveReadFile(join(gitDirPath, "index"));
+		await reactiveReadFile(join(gitDirPath, "packed-refs"));
+		return;
+	}
+	await reactiveReadDir(dotGitPath, { includeHidden: true });
+	await reactiveReadFile(join(dotGitPath, "HEAD"));
+	await reactiveReadFile(join(dotGitPath, "index"));
+	await reactiveReadFile(join(dotGitPath, "packed-refs"));
+}
 function requireChangeId(changeId) {
 	if (!changeId) throw new Error("change is required");
 	return changeId;
@@ -668,6 +1102,210 @@ async function fetchOpsxTemplateContents(ctx, schema) {
 	await ctx.kernel.ensureTemplateContents(schema);
 	return ctx.kernel.getTemplateContents(schema);
 }
+function buildSystemStatus(ctx) {
+	const runtime = getWatcherRuntimeStatus();
+	return {
+		projectDir: ctx.projectDir,
+		watcherEnabled: runtime?.initialized ?? false,
+		watcherGeneration: runtime?.generation ?? 0,
+		watcherReinitializeCount: runtime?.reinitializeCount ?? 0,
+		watcherLastReinitializeReason: runtime?.lastReinitializeReason ?? null
+	};
+}
+function resolveTrendTimestamp(primary, secondary) {
+	if (typeof primary === "number" && Number.isFinite(primary) && primary > 0) return primary;
+	if (typeof secondary === "number" && Number.isFinite(secondary) && secondary > 0) return secondary;
+	return null;
+}
+function parseDatedIdTimestamp(id) {
+	const match = /^(\d{4})-(\d{2})-(\d{2})(?:-|$)/.exec(id);
+	if (!match) return null;
+	const year = Number(match[1]);
+	const month = Number(match[2]);
+	const day = Number(match[3]);
+	if (!Number.isInteger(year) || !Number.isInteger(month) || !Number.isInteger(day)) return null;
+	if (month < 1 || month > 12) return null;
+	if (day < 1 || day > 31) return null;
+	const ts = Date.UTC(year, month - 1, day);
+	return Number.isFinite(ts) ? ts : null;
+}
+function createEmptyTriColorTrends() {
+	return Object.fromEntries(DASHBOARD_METRIC_KEYS.map((metric) => [metric, []]));
+}
+async function readLatestCommitTimestamp(projectDir) {
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"log",
+			"-1",
+			"--format=%ct"
+		], {
+			cwd: projectDir,
+			maxBuffer: 1024 * 1024,
+			encoding: "utf8"
+		});
+		const seconds = Number(stdout.trim());
+		return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : null;
+	} catch {
+		return null;
+	}
+}
+async function fetchDashboardOverview(ctx, reason = "dashboard-refresh") {
+	if (contextStorage.getStore()) await registerDashboardGitReactiveDeps(ctx.projectDir);
+	const now = Date.now();
+	const [specMetas, changeMetas, archiveMetas] = await Promise.all([
+		ctx.adapter.listSpecsWithMeta(),
+		ctx.adapter.listChangesWithMeta(),
+		ctx.adapter.listArchivedChangesWithMeta()
+	]);
+	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 specifications = (await Promise.all(specMetas.map(async (meta) => {
+		const spec = await ctx.adapter.readSpec(meta.id);
+		if (!spec) return null;
+		return {
+			id: meta.id,
+			name: meta.name,
+			requirements: spec.requirements.length,
+			updatedAt: meta.updatedAt
+		};
+	}))).filter((item) => item !== null).sort((a, b) => b.requirements - a.requirements || b.updatedAt - a.updatedAt);
+	const activeChanges = changeMetas.map((change) => ({
+		id: change.id,
+		name: change.name,
+		progress: change.progress,
+		updatedAt: change.updatedAt
+	}));
+	const requirements = specifications.reduce((sum, spec) => sum + spec.requirements, 0);
+	const tasksTotal = activeChanges.reduce((sum, change) => sum + change.progress.total, 0);
+	const tasksCompleted = activeChanges.reduce((sum, change) => sum + change.progress.completed, 0);
+	const archivedTasksCompleted = archivedChanges.reduce((sum, change) => sum + change.tasksCompleted, 0);
+	const taskCompletionPercent = tasksTotal > 0 ? Math.round(tasksCompleted / tasksTotal * 100) : null;
+	const inProgressChanges = activeChanges.filter((change) => change.progress.total > 0 && change.progress.completed < change.progress.total).length;
+	const specificationTrendEvents = specMetas.flatMap((spec) => {
+		const ts = resolveTrendTimestamp(spec.createdAt, spec.updatedAt);
+		return ts === null ? [] : [{
+			ts,
+			value: 1
+		}];
+	});
+	const completedTrendEvents = archivedChanges.flatMap((archive) => {
+		const ts = parseDatedIdTimestamp(archive.id) ?? resolveTrendTimestamp(archive.updatedAt, archive.createdAt);
+		return ts === null ? [] : [{
+			ts,
+			value: archive.tasksCompleted
+		}];
+	});
+	const specMetaById = new Map(specMetas.map((meta) => [meta.id, meta]));
+	const requirementTrendEvents = specifications.flatMap((spec) => {
+		const meta = specMetaById.get(spec.id);
+		const ts = resolveTrendTimestamp(meta?.updatedAt, meta?.createdAt);
+		return ts === null ? [] : [{
+			ts,
+			value: spec.requirements
+		}];
+	});
+	const hasObjectiveSpecificationTrend = specificationTrendEvents.length > 0 || specifications.length === 0;
+	const hasObjectiveRequirementTrend = requirementTrendEvents.length > 0 || requirements === 0;
+	const hasObjectiveCompletedTrend = completedTrendEvents.length > 0 || archiveMetas.length === 0;
+	const config = await ctx.configManager.readConfig();
+	beginDashboardGitTask(reason);
+	let latestCommitTs = null;
+	let git;
+	try {
+		const gitSnapshotPromise = buildDashboardGitSnapshot({ projectDir: ctx.projectDir }).catch(() => ({
+			defaultBranch: "main",
+			worktrees: []
+		}));
+		latestCommitTs = await readLatestCommitTimestamp(ctx.projectDir);
+		git = await gitSnapshotPromise;
+	} catch (error) {
+		endDashboardGitTask(error);
+		throw error;
+	}
+	endDashboardGitTask(null);
+	const cardAvailability = {
+		specifications: hasObjectiveSpecificationTrend ? { state: "ok" } : {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		requirements: hasObjectiveRequirementTrend ? { state: "ok" } : {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		activeChanges: {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		inProgressChanges: {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		completedChanges: hasObjectiveCompletedTrend ? { state: "ok" } : {
+			state: "invalid",
+			reason: "objective-history-unavailable"
+		},
+		taskCompletionPercent: {
+			state: "invalid",
+			reason: taskCompletionPercent === null ? "semantic-uncomputable" : "objective-history-unavailable"
+		}
+	};
+	const trendKinds = {
+		specifications: "monotonic",
+		requirements: "monotonic",
+		activeChanges: "bidirectional",
+		inProgressChanges: "bidirectional",
+		completedChanges: "monotonic",
+		taskCompletionPercent: "bidirectional"
+	};
+	const { trends: baselineTrends, trendMeta } = buildDashboardTimeTrends({
+		pointLimit: config.dashboard.trendPointLimit,
+		timestamp: now,
+		rightEdgeTs: latestCommitTs,
+		availability: cardAvailability,
+		events: {
+			specifications: specificationTrendEvents,
+			requirements: requirementTrendEvents,
+			activeChanges: [],
+			inProgressChanges: [],
+			completedChanges: completedTrendEvents,
+			taskCompletionPercent: []
+		},
+		reducers: {
+			specifications: "sum",
+			requirements: "sum",
+			completedChanges: "sum"
+		}
+	});
+	return {
+		summary: {
+			specifications: specifications.length,
+			requirements,
+			activeChanges: activeChanges.length,
+			inProgressChanges,
+			completedChanges: archiveMetas.length,
+			archivedTasksCompleted,
+			tasksTotal,
+			tasksCompleted,
+			taskCompletionPercent
+		},
+		trends: baselineTrends,
+		triColorTrends: createEmptyTriColorTrends(),
+		trendKinds,
+		cardAvailability,
+		trendMeta,
+		specifications,
+		activeChanges,
+		git
+	};
+}
 /**
 * Spec router - spec CRUD operations
 */
@@ -875,25 +1513,17 @@ const configRouter = router({
 			"dark",
 			"system"
 		]).optional(),
-		terminal: z.object({
-			fontSize: z.number().min(8).max(32).optional(),
-			fontFamily: z.string().optional(),
-			cursorBlink: z.boolean().optional(),
-			cursorStyle: z.enum([
-				"block",
-				"underline",
-				"bar"
-			]).optional(),
-			scrollback: z.number().min(0).max(1e5).optional()
-		}).optional()
+		terminal: TerminalConfigSchema.omit({ rendererEngine: true }).partial().extend({ rendererEngine: TerminalRendererEngineSchema.optional() }).optional(),
+		dashboard: DashboardConfigSchema.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.terminal !== void 0) await ctx.configManager.writeConfig({
+			if (input.theme !== void 0 || input.terminal !== void 0 || input.dashboard !== void 0) await ctx.configManager.writeConfig({
 				theme: input.theme,
-				terminal: input.terminal
+				terminal: input.terminal,
+				dashboard: input.dashboard
 			});
 			return { success: true };
 		}
@@ -1330,9 +1960,63 @@ const searchRouter = router({
 	})
 });
 /**
+* System router - runtime status and heartbeat-friendly subscription
+*/
+const systemRouter = router({
+	status: publicProcedure.query(({ ctx }) => {
+		return buildSystemStatus(ctx);
+	}),
+	subscribe: publicProcedure.subscription(({ ctx }) => {
+		return observable((emit) => {
+			emit.next(buildSystemStatus(ctx));
+			const timer = setInterval(() => {
+				emit.next(buildSystemStatus(ctx));
+			}, 3e3);
+			timer.unref();
+			return () => {
+				clearInterval(timer);
+			};
+		});
+	})
+});
+/**
+* Dashboard router - objective project overview for UI
+*/
+const dashboardRouter = router({
+	get: publicProcedure.query(async ({ ctx }) => {
+		return fetchDashboardOverview(ctx, "dashboard.get");
+	}),
+	subscribe: publicProcedure.subscription(({ ctx }) => {
+		return createReactiveSubscription(async () => {
+			return fetchDashboardOverview(ctx, "dashboard.subscribe");
+		});
+	}),
+	refreshGitSnapshot: publicProcedure.input(z.object({ reason: z.string().optional() }).optional()).mutation(async ({ ctx, input }) => {
+		const reason = input?.reason?.trim() || "manual-refresh";
+		await touchDashboardGitRefreshStamp(ctx.projectDir, reason);
+		return { success: true };
+	}),
+	gitTaskStatus: publicProcedure.query(() => {
+		return getDashboardGitTaskStatus();
+	}),
+	subscribeGitTaskStatus: publicProcedure.subscription(() => {
+		return observable((emit) => {
+			emit.next(getDashboardGitTaskStatus());
+			const handler = (status) => {
+				emit.next(status);
+			};
+			dashboardGitTaskStatusEmitter.on("change", handler);
+			return () => {
+				dashboardGitTaskStatusEmitter.off("change", handler);
+			};
+		});
+	})
+});
+/**
 * Main app router
 */
 const appRouter = router({
+	dashboard: dashboardRouter,
 	spec: specRouter,
 	change: changeRouter,
 	archive: archiveRouter,
@@ -1342,7 +2026,8 @@ const appRouter = router({
 	cli: cliRouter,
 	opsx: opsxRouter,
 	kv: kvRouter,
-	search: searchRouter
+	search: searchRouter,
+	system: systemRouter
 });
 
 //#endregion
@@ -1561,7 +2246,12 @@ async function createWebSocketServer(server, httpServer, config) {
 	const handler = applyWSSHandler({
 		wss,
 		router: appRouter,
-		createContext: server.createContext
+		createContext: server.createContext,
+		keepAlive: {
+			enabled: true,
+			pingMs: 3e4,
+			pongWaitMs: 5e3
+		}
 	});
 	const ptyManager = new PtyManager(config.projectDir);
 	const ptyWss = new WebSocketServer({ noServer: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openspecui/server",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "type": "module",
   "main": "dist/index.mjs",
   "exports": {
@@ -20,8 +20,8 @@
     "yaml": "^2.8.0",
     "yargs": "^18.0.0",
     "zod": "^3.24.1",
-    "@openspecui/core": "1.2.0",
-    "@openspecui/search": "1.1.0"
+    "@openspecui/search": "1.1.0",
+    "@openspecui/core": "1.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
@@ -34,7 +34,7 @@
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm --no-dts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.check.json --noEmit",
     "dev": "tsx watch --include '../core/dist/**' --include '../search/dist/**' src/standalone.ts",
     "test": "vitest run",
     "test:watch": "vitest"