@ggui-ai/dev-stack 0.1.0-rc.1

package/dist/runtime-supervisor.d.ts

@@ -0,0 +1,140 @@
+/**
+ * `RuntimeSupervisor` — owns the live view of a supervised agent
+ * runtime inside `@ggui-ai/dev-stack`.
+ *
+ * Responsibilities:
+ *
+ *   1. Subscribe to the adapter's event stream on construction.
+ *   2. Keep a bounded ring buffer of recent events (status + logs +
+ *      errors) so hosts that missed the live stream (the CLI banner,
+ *      the future hub, an HTTP snapshot endpoint) can still render a
+ *      consistent "recent state" view.
+ *   3. Expose a cheap, GC-friendly {@link RuntimeStateSnapshot} for
+ *      point-in-time reads without forcing callers to subscribe.
+ *   4. Dispose cleanly — the `close()` method unsubscribes the
+ *      internal listener and forwards unsubscribe to observers.
+ *
+ * The supervisor intentionally does NOT:
+ *
+ *   - Own the handle's lifecycle. Whoever constructed the adapter
+ *     and called `start()` still owns `stop()`. Supervisor is a
+ *     read-plus-buffer layer, not a controller.
+ *   - Implement restart-on-crash. That's a higher-layer policy
+ *     needing a second adapter to validate the abstraction.
+ *   - Persist events beyond the in-memory ring. The hub's eventual
+ *     log panel is snapshot-and-tail, not full-history.
+ *   - Fan events out to multiple subscribers. The `onEvent` callback
+ *     is a single pipe — `runDev` uses it to forward into the CLI
+ *     log stream; if a future host needs multi-subscriber fanout it
+ *     wraps an `EventEmitter` around the same pipe.
+ */
+import type { AgentRuntimeAdapter, AgentRuntimeCapabilities, AgentRuntimeEvent, AgentRuntimeHandle, AgentRuntimeStatus } from '@ggui-ai/agent-runtime';
+/** Default ring-buffer depth. Chosen to render cleanly in a CLI +
+ * hub panel while staying bounded in memory (~200 entries × ~1 KiB
+ * worst case ≈ 200 KiB). */
+export declare const DEFAULT_RUNTIME_BUFFER_SIZE = 200;
+/**
+ * A ring-buffered event — identical to the adapter's
+ * `AgentRuntimeEvent` with an appended monotonic `sequence` so
+ * consumers can detect gaps without parsing timestamps.
+ */
+export type RuntimeEventRecord = ({
+    sequence: number;
+} & Extract<AgentRuntimeEvent, {
+    type: 'status';
+}>) | ({
+    sequence: number;
+} & Extract<AgentRuntimeEvent, {
+    type: 'log';
+}>) | ({
+    sequence: number;
+} & Extract<AgentRuntimeEvent, {
+    type: 'error';
+}>);
+/**
+ * Point-in-time snapshot. The HTTP surface serializes this verbatim;
+ * the CLI uses it for banner refresh; tests assert on its shape
+ * directly.
+ */
+export interface RuntimeStateSnapshot {
+    /** `true` when a runtime is currently supervised. Always `true`
+     * on a snapshot produced by a supervisor (supervisor exists iff
+     * a runtime was started). Included for HTTP parity with the
+     * "no runtime" case. */
+    readonly present: true;
+    /** Adapter name (e.g. `'node-process'`). */
+    readonly name: string;
+    /** Handle's `runId`. */
+    readonly runId: string;
+    /** Current status — matches the declarative handle snapshot. */
+    readonly status: AgentRuntimeStatus;
+    /** Adapter capabilities. */
+    readonly capabilities: AgentRuntimeCapabilities;
+    /** Timestamp (ms) the supervisor was created. Fixed per run. */
+    readonly startedAt: number;
+    /** Timestamp (ms) of the most recent event the supervisor saw,
+     * or `null` if no events have arrived yet. */
+    readonly lastEventAt: number | null;
+    /** Recent events, oldest-first. Capped at the supervisor's
+     * buffer size (default 200). */
+    readonly recentEvents: readonly RuntimeEventRecord[];
+}
+export interface RuntimeSupervisorOptions {
+    /** Adapter that produced {@link handle}. */
+    readonly adapter: AgentRuntimeAdapter;
+    /** Running handle the supervisor observes. */
+    readonly handle: AgentRuntimeHandle;
+    /** Ring-buffer capacity. Defaults to
+     * {@link DEFAULT_RUNTIME_BUFFER_SIZE}. Must be ≥ 1. */
+    readonly bufferSize?: number;
+    /** Optional forward pipe — the supervisor calls this for every
+     * event after the ring buffer is updated. `runDev` uses it to
+     * forward formatted lines into the CLI log stream. */
+    readonly onEvent?: (event: RuntimeEventRecord) => void;
+}
+/**
+ * Attach a supervisor to a running handle. Call `close()` when the
+ * runtime is torn down to release the subscription.
+ */
+export declare class RuntimeSupervisor {
+    readonly adapter: AgentRuntimeAdapter;
+    readonly handle: AgentRuntimeHandle;
+    private readonly bufferSize;
+    private readonly buffer;
+    private readonly startedAt;
+    private readonly onEvent?;
+    private readonly unsubscribe;
+    private sequence;
+    private lastEventAt;
+    constructor(options: RuntimeSupervisorOptions);
+    /** Point-in-time snapshot — shallow-immutable view of the buffer. */
+    snapshot(): RuntimeStateSnapshot;
+    /** Stop observing the handle. Safe to call repeatedly. */
+    close(): void;
+    private record;
+}
+/**
+ * The "no runtime" snapshot shape. Kept here so HTTP surfaces can
+ * serialize a consistent shape whether or not a runtime is being
+ * supervised.
+ */
+export interface EmptyRuntimeStateSnapshot {
+    readonly present: false;
+}
+/** Union over present + absent, for HTTP / CLI consumption. */
+export type AnyRuntimeStateSnapshot = RuntimeStateSnapshot | EmptyRuntimeStateSnapshot;
+/** Convenience helper for the "no runtime" case. */
+export declare function emptyRuntimeSnapshot(): EmptyRuntimeStateSnapshot;
+/**
+ * Format an event as a single log line — used by
+ * {@link RuntimeSupervisor} consumers that want to forward events
+ * into an existing text log stream (the CLI banner log, a test
+ * collector, …). Stable format:
+ *
+ *     [runtime status] ready
+ *     [runtime stdout] hello
+ *     [runtime stderr] oops
+ *     [runtime error]  boot failure
+ */
+export declare function formatRuntimeEventLine(event: RuntimeEventRecord): string;
+//# sourceMappingURL=runtime-supervisor.d.ts.map

package/dist/runtime-supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-supervisor.d.ts","sourceRoot":"","sources":["../src/runtime-supervisor.ts"],"names":[],"mappings":"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"}

package/dist/runtime-supervisor.js

@@ -0,0 +1,91 @@
+/** Default ring-buffer depth. Chosen to render cleanly in a CLI +
+ * hub panel while staying bounded in memory (~200 entries × ~1 KiB
+ * worst case ≈ 200 KiB). */
+export const DEFAULT_RUNTIME_BUFFER_SIZE = 200;
+/**
+ * Attach a supervisor to a running handle. Call `close()` when the
+ * runtime is torn down to release the subscription.
+ */
+export class RuntimeSupervisor {
+    adapter;
+    handle;
+    bufferSize;
+    buffer = [];
+    startedAt;
+    onEvent;
+    unsubscribe;
+    sequence = 0;
+    lastEventAt = null;
+    constructor(options) {
+        this.adapter = options.adapter;
+        this.handle = options.handle;
+        this.bufferSize = Math.max(1, options.bufferSize ?? DEFAULT_RUNTIME_BUFFER_SIZE);
+        this.onEvent = options.onEvent;
+        this.startedAt = Date.now();
+        this.unsubscribe = this.handle.subscribe((event) => this.record(event));
+    }
+    /** Point-in-time snapshot — shallow-immutable view of the buffer. */
+    snapshot() {
+        return {
+            present: true,
+            name: this.adapter.name,
+            runId: this.handle.runId,
+            status: this.handle.status,
+            capabilities: this.adapter.capabilities,
+            startedAt: this.startedAt,
+            lastEventAt: this.lastEventAt,
+            // Slice so callers can't mutate the internal ring.
+            recentEvents: this.buffer.slice(),
+        };
+    }
+    /** Stop observing the handle. Safe to call repeatedly. */
+    close() {
+        this.unsubscribe();
+    }
+    record(event) {
+        this.sequence += 1;
+        const record = { ...event, sequence: this.sequence };
+        this.buffer.push(record);
+        if (this.buffer.length > this.bufferSize) {
+            // Drop the oldest to keep memory bounded. Ring behaviour
+            // without the wrap — `recentEvents` always reads
+            // oldest-first with monotonic `sequence` so gaps (if a buffer
+            // roll happened) are observable.
+            this.buffer.shift();
+        }
+        this.lastEventAt = event.timestamp;
+        try {
+            this.onEvent?.(record);
+        }
+        catch {
+            // A broken forward pipe MUST NOT break the supervisor itself
+            // — the snapshot would still be correct. Consumers that need
+            // tighter error surfacing subscribe directly to the handle.
+        }
+    }
+}
+/** Convenience helper for the "no runtime" case. */
+export function emptyRuntimeSnapshot() {
+    return { present: false };
+}
+/**
+ * Format an event as a single log line — used by
+ * {@link RuntimeSupervisor} consumers that want to forward events
+ * into an existing text log stream (the CLI banner log, a test
+ * collector, …). Stable format:
+ *
+ *     [runtime status] ready
+ *     [runtime stdout] hello
+ *     [runtime stderr] oops
+ *     [runtime error]  boot failure
+ */
+export function formatRuntimeEventLine(event) {
+    switch (event.type) {
+        case 'status':
+            return `[runtime status] ${event.status}`;
+        case 'log':
+            return `[runtime ${event.stream}] ${event.line}`;
+        case 'error':
+            return `[runtime error]  ${event.message}`;
+    }
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@ggui-ai/dev-stack",
+  "version": "0.1.0-rc.1",
+  "description": "Shared local dev engine for the ggui protocol: local UI registry discovery, compile-on-demand, filesystem watcher with SSE, and a read-only HTTP surface for dev tooling. Framework-neutral — agent runtime supervision plugs in via an adapter seam, so no agent SDK is hardcoded.",
+  "keywords": [
+    "ggui",
+    "dev-server",
+    "mcp",
+    "ui-registry",
+    "esbuild",
+    "generative-ui"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "esbuild": "^0.25.12",
+    "tinyglobby": "^0.2.16",
+    "@ggui-ai/agent-runtime": "0.1.0-rc.1",
+    "@ggui-ai/ui-registry": "0.1.0-rc.1",
+    "@ggui-ai/project-config": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0",
+    "@ggui-ai/react": "0.1.0-rc.1",
+    "@ggui-ai/design": "0.1.0-rc.1",
+    "@ggui-ai/wire": "0.1.0-rc.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ggui-ai/ggui.git",
+    "directory": "packages/dev-stack"
+  },
+  "homepage": "https://github.com/ggui-ai/ggui/tree/main/packages/dev-stack",
+  "bugs": {
+    "url": "https://github.com/ggui-ai/ggui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "ggui contributors <hello@ggui.ai>",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/build-hub-preview.mjs",
+    "build:hub-preview": "node scripts/build-hub-preview.mjs",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit && tsc -p hub-preview-client/tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}