khal-os 1.260324.2

package/packages/os-sdk/src/service/runtime.ts

@@ -0,0 +1,259 @@
+/**
+ * Service runtime helper — abstracts NATS connect + subscribe + graceful shutdown boilerplate.
+ *
+ * Usage:
+ *   import { createService } from '@genie-os/sdk';
+ *
+ *   createService({
+ *     name: 'my-service',
+ *     subscriptions: [
+ *       { subject: 'os.myapp.foo', handler: (msg, nc) => { ... } },
+ *     ],
+ *     onReady: async (nc, log) => { log.info('ready'); },
+ *     onShutdown: async () => { ... },
+ *   });
+ */
+
+import type { Msg } from '@nats-io/nats-core';
+import { connect, type NatsConnection } from '@nats-io/transport-node';
+import { NATS_URL } from '../config';
+import { interceptConsole } from './console-intercept';
+import type { Logger } from './logger';
+import { createLogger } from './logger';
+import { extractTrace, newSpan } from './trace';
+
+// Re-export types so callers don't need to import from @nats-io directly.
+export type { NatsConnection, Msg };
+
+/**
+ * A single NATS subject subscription with its message handler.
+ */
+export interface ServiceHandler {
+	/** NATS subject pattern to subscribe to (wildcards supported). */
+	subject: string;
+	/** Called for each incoming message. Errors are caught and logged. */
+	handler: (msg: Msg, nc: NatsConnection) => void | Promise<void>;
+}
+
+/**
+ * Observability configuration for auto-instrumentation.
+ */
+export interface ObserveConfig {
+	/** Additional subject patterns to exclude from auto-capture. */
+	exclude?: string[];
+	/** Minimum log level (default: 'info'). */
+	level?: string;
+}
+
+/**
+ * Configuration for a managed NATS service.
+ */
+export interface ServiceConfig {
+	/** Human-readable name used in log output, e.g. 'pty-service'. */
+	name: string;
+	/** Subscriptions to set up after connecting. */
+	subscriptions?: ServiceHandler[];
+	/** Called once after all subscriptions are registered. Receives logger as second arg (backward compatible). */
+	onReady?: (nc: NatsConnection, log: Logger) => void | Promise<void>;
+	/** Called during graceful shutdown before draining NATS. */
+	onShutdown?: () => void | Promise<void>;
+	/** Observability config for auto-instrumentation. */
+	observe?: ObserveConfig;
+}
+
+/** Default subject patterns excluded from handler event auto-capture. */
+const DEFAULT_EXCLUDE_PATTERNS = ['os.o11y.*', '*.data', '*.input', '*.resize', 'os.pty.*'];
+
+/**
+ * Check if a NATS subject matches any exclusion pattern.
+ * Supports `*` as a single-token wildcard and `>` as a multi-token wildcard.
+ */
+function matchesExclusion(subject: string, patterns: string[]): boolean {
+	for (const pattern of patterns) {
+		if (matchPattern(subject, pattern)) return true;
+	}
+	return false;
+}
+
+function matchPattern(subject: string, pattern: string): boolean {
+	const subParts = subject.split('.');
+	const patParts = pattern.split('.');
+
+	for (let i = 0; i < patParts.length; i++) {
+		const pat = patParts[i];
+		if (pat === '>') return true; // multi-token wildcard matches rest
+		if (i >= subParts.length) return false;
+		if (pat !== '*' && pat !== subParts[i]) return false;
+	}
+
+	return subParts.length === patParts.length;
+}
+
+/** Spawn the async message loop for a subscription. */
+function spawnMessageLoop(
+	sub: AsyncIterable<Msg>,
+	shouldInstrument: boolean,
+	nc: NatsConnection,
+	log: Logger,
+	serviceName: string,
+	subject: string,
+	handler: (msg: Msg, nc: NatsConnection) => void | Promise<void>
+): void {
+	(async () => {
+		for await (const msg of sub) {
+			if (shouldInstrument) {
+				await instrumentedHandler(nc, log, serviceName, subject, msg, handler);
+			} else {
+				await plainHandler(log, subject, msg, handler, nc);
+			}
+		}
+	})();
+}
+
+/** Handle a message without instrumentation, just error catching. */
+async function plainHandler(
+	log: Logger,
+	subject: string,
+	msg: Msg,
+	handler: (msg: Msg, nc: NatsConnection) => void | Promise<void>,
+	nc: NatsConnection
+): Promise<void> {
+	try {
+		await handler(msg, nc);
+	} catch (err) {
+		log.error(`handler error on ${subject}`, {
+			error: err instanceof Error ? err : new Error(String(err)),
+		});
+	}
+}
+
+/**
+ * Connect to NATS, register subscriptions, handle graceful shutdown, and keep the process alive.
+ *
+ * This function never resolves (it awaits nc.closed()), so it should be the last thing called.
+ * Errors during startup cause process.exit(1) via the .catch() wrapper.
+ */
+export async function createService(config: ServiceConfig): Promise<void> {
+	const { name, subscriptions = [], onReady, onShutdown, observe } = config;
+
+	const nc = await connect({ servers: NATS_URL });
+
+	// Create structured logger and intercept console for this service.
+	const log = createLogger(name, nc);
+	const _restoreConsole = interceptConsole(log);
+
+	log.info(`connected to NATS (${NATS_URL})`);
+
+	// Build merged exclusion list for auto-capture.
+	const excludePatterns = [...DEFAULT_EXCLUDE_PATTERNS, ...(observe?.exclude ?? [])];
+
+	// Register all subscriptions and spawn async iterators.
+	const subs = subscriptions.map(({ subject, handler }) => {
+		const sub = nc.subscribe(subject);
+		log.info(`subscribed to ${subject}`);
+
+		const shouldInstrument = !matchesExclusion(subject, excludePatterns);
+		spawnMessageLoop(sub, shouldInstrument, nc, log, name, subject, handler);
+
+		return sub;
+	});
+
+	// Notify the service that everything is wired up.
+	if (onReady) {
+		await onReady(nc, log);
+	}
+
+	// Graceful shutdown — guard against being called twice (e.g. SIGINT + SIGTERM).
+	let shuttingDown = false;
+
+	const shutdown = async () => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+
+		log.info('shutting down...');
+
+		for (const sub of subs) {
+			sub.unsubscribe();
+		}
+
+		if (onShutdown) {
+			try {
+				await onShutdown();
+			} catch (err) {
+				log.error('onShutdown error', {
+					error: err instanceof Error ? err : new Error(String(err)),
+				});
+			}
+		}
+
+		_restoreConsole();
+
+		// drain() waits for in-flight messages before closing — safer than close().
+		await nc.drain();
+		process.exit(0);
+	};
+
+	process.on('SIGTERM', shutdown);
+	process.on('SIGINT', shutdown);
+
+	// Keep the process alive until NATS connection closes.
+	await nc.closed();
+}
+
+/**
+ * Wraps a handler invocation with observability: trace extraction, timing, and event emission.
+ */
+async function instrumentedHandler(
+	nc: NatsConnection,
+	log: Logger,
+	serviceName: string,
+	subject: string,
+	msg: Msg,
+	handler: (msg: Msg, nc: NatsConnection) => void | Promise<void>
+): Promise<void> {
+	// Extract or generate trace context.
+	const inbound = extractTrace(msg);
+	const span = newSpan(inbound.traceId);
+	if (inbound.spanId) {
+		span.parentSpanId = inbound.spanId;
+	}
+
+	const payloadBytes = msg.data?.length ?? 0;
+	const start = performance.now();
+	let error: { message: string; stack?: string } | undefined;
+
+	try {
+		await handler(msg, nc);
+	} catch (err) {
+		const e = err instanceof Error ? err : new Error(String(err));
+		error = { message: e.message, stack: e.stack };
+		log.error(`handler error on ${subject}`, {
+			error: e,
+			trace_id: span.traceId,
+			span_id: span.spanId,
+		});
+	}
+
+	const durationMs = Math.round((performance.now() - start) * 100) / 100;
+
+	// Emit observability event (fire-and-forget).
+	const event = {
+		subject,
+		service: serviceName,
+		duration_ms: durationMs,
+		payload_bytes: payloadBytes,
+		trace_id: span.traceId,
+		span_id: span.spanId,
+		parent_span_id: span.parentSpanId,
+		ts: new Date().toISOString(),
+		...(error ? { error } : {}),
+	};
+
+	// Publish to subject-domain stream: os.o11y.events.<original-subject>
+	const eventSubject = `os.o11y.events.${subject}`;
+	try {
+		nc.publish(eventSubject, JSON.stringify(event));
+	} catch {
+		// Never let observability failures affect service operation.
+	}
+}

package/packages/os-sdk/src/service/trace.ts

@@ -0,0 +1,71 @@
+/**
+ * Distributed trace context utilities for NATS header propagation.
+ *
+ * Trace context is carried via NATS headers:
+ *   x-trace-id    — root trace identifier (shared across all spans in a request)
+ *   x-span-id     — unique identifier for this specific operation
+ *   x-parent-span-id — the span that initiated this one
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { Msg } from '@nats-io/nats-core';
+import { headers } from '@nats-io/transport-node';
+
+export const TRACE_HEADER = 'x-trace-id';
+export const SPAN_HEADER = 'x-span-id';
+export const PARENT_SPAN_HEADER = 'x-parent-span-id';
+
+export interface TraceContext {
+	traceId: string;
+	spanId: string;
+	parentSpanId?: string;
+}
+
+/** Generate a short unique ID suitable for span/trace identifiers. */
+function generateId(): string {
+	return randomUUID().replace(/-/g, '').slice(0, 16);
+}
+
+/**
+ * Extract trace context from an inbound NATS message's headers.
+ * Returns whatever headers are present; missing fields are undefined.
+ */
+export function extractTrace(msg: Msg): Partial<TraceContext> {
+	const hdrs = msg.headers;
+	if (!hdrs) return {};
+
+	return {
+		traceId: hdrs.get(TRACE_HEADER) || undefined,
+		spanId: hdrs.get(SPAN_HEADER) || undefined,
+		parentSpanId: hdrs.get(PARENT_SPAN_HEADER) || undefined,
+	};
+}
+
+/**
+ * Create a new span, optionally continuing an existing trace.
+ * If no traceId is provided, starts a new trace root.
+ */
+export function newSpan(traceId?: string): TraceContext {
+	return {
+		traceId: traceId || generateId(),
+		spanId: generateId(),
+		parentSpanId: undefined,
+	};
+}
+
+/**
+ * Inject trace context into NATS headers for outbound messages.
+ * Creates a new MsgHdrs if none provided.
+ */
+export function injectTrace(
+	hdrs: ReturnType<typeof headers> | null | undefined,
+	ctx: TraceContext
+): ReturnType<typeof headers> {
+	const h = hdrs || headers();
+	h.set(TRACE_HEADER, ctx.traceId);
+	h.set(SPAN_HEADER, ctx.spanId);
+	if (ctx.parentSpanId) {
+		h.set(PARENT_SPAN_HEADER, ctx.parentSpanId);
+	}
+	return h;
+}

package/packages/os-sdk/tsconfig.json

@@ -0,0 +1,16 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"lib": ["dom", "dom.iterable", "esnext"],
+		"strict": true,
+		"noEmit": true,
+		"esModuleInterop": true,
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"jsx": "react-jsx",
+		"incremental": true,
+		"composite": true,
+		"outDir": "./dist"
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx"]
+}

package/packages/os-ui/package.json

@@ -0,0 +1,13 @@
+{
+	"name": "@genie-os/ui",
+	"version": "0.0.1",
+	"private": true,
+	"main": "./src/index.ts",
+	"exports": {
+		".": "./src/index.ts",
+		"./server": "./src/server.ts"
+	},
+	"peerDependencies": {
+		"react": ">=19"
+	}
+}

package/packages/os-ui/src/index.ts

@@ -0,0 +1,29 @@
+// App component props type
+export type { AppComponentProps } from '@/components/apps/app-registry';
+
+// UI Components — re-export from OS host
+
+// OS Primitives
+export * from '@/components/os-primitives';
+// shadcn/ui components
+export * from '@/components/ui/badge';
+export * from '@/components/ui/button';
+export * from '@/components/ui/ContextMenu';
+export * from '@/components/ui/command';
+export * from '@/components/ui/dropdown-menu';
+export * from '@/components/ui/input';
+export * from '@/components/ui/note';
+export * from '@/components/ui/separator';
+export * from '@/components/ui/spinner';
+export * from '@/components/ui/switch';
+export * from '@/components/ui/theme-provider';
+export * from '@/components/ui/theme-switcher';
+export * from '@/components/ui/tooltip';
+// Auth
+export { useKhalAuth, useKhalAuth as useOSAuth } from '@/lib/auth/use-auth';
+export { useNats, useNatsSubscription } from '@/lib/hooks/use-nats';
+export { SUBJECTS } from '@/lib/subjects';
+export { cn } from '@/lib/utils';
+// Stores (OS-level state)
+export { useNotificationStore } from '@/stores/notification-store';
+export { useThemeStore } from '@/stores/theme-store';

package/packages/os-ui/src/server.ts

@@ -0,0 +1,4 @@
+// Server-safe exports for API routes and background services.
+// Keep this entrypoint free of client hooks/components.
+
+export { SUBJECTS } from '@/lib/subjects';

package/packages/os-ui/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"lib": ["dom", "dom.iterable", "esnext"],
+		"strict": true,
+		"noEmit": true,
+		"esModuleInterop": true,
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"jsx": "react-jsx",
+		"incremental": true,
+		"composite": true,
+		"outDir": "./dist",
+		"paths": {
+			"@/*": ["../../src/*"]
+		}
+	},
+	"include": ["src/**/*.ts", "src/**/*.tsx"]
+}

package/packages/settings-app/components.ts

@@ -0,0 +1,12 @@
+'use client';
+
+import { type ComponentType, lazy } from 'react';
+
+interface AppComponentProps {
+	windowId: string;
+	meta?: Record<string, unknown>;
+}
+
+export const components: Record<string, ComponentType<AppComponentProps>> = {
+	settings: lazy(() => import('./views/settings/Settings').then((m) => ({ default: m.Settings }))),
+};

package/packages/settings-app/manifest.ts

@@ -0,0 +1,18 @@
+export default {
+	id: 'settings-app',
+	views: [
+		{
+			id: 'settings',
+			label: 'Settings',
+			permission: 'settings',
+			minRole: 'platform-dev' as const,
+			defaultSize: { width: 800, height: 600 },
+			component: './views/settings/Settings',
+		},
+	],
+	desktop: {
+		icon: '/icons/dusk/system_preferences.svg',
+		categories: ['System'],
+		comment: 'Desktop settings',
+	},
+};

package/packages/settings-app/package.json

@@ -0,0 +1,14 @@
+{
+	"name": "@genie-os/settings-app",
+	"version": "0.0.1",
+	"private": true,
+	"main": "./manifest.ts",
+	"exports": {
+		".": "./manifest.ts",
+		"./components": "./components.ts",
+		"./views/*": "./views/*"
+	},
+	"peerDependencies": {
+		"react": ">=19"
+	}
+}