@opencode-cockpit/daemon 0.1.3 → 0.1.5

package/dist/modules/shell/pty.js

@@ -0,0 +1,59 @@
+/**
+ * PTY backend seam. The shell module depends only on these interfaces so the process layer can be
+ * swapped (Windows ConPTY, remote hosts, test fakes) without touching session logic.
+ */
+
+/** Native PTY via `Bun.spawn({ terminal })` (Bun ≥ 1.3.5). The child leads its own session and group. */
+export const bunPtyBackend = {
+  spawn(options) {
+    const proc = Bun.spawn([options.command, ...options.args], {
+      cwd: options.cwd,
+      env: options.env,
+      terminal: {
+        cols: options.cols,
+        rows: options.rows,
+        data(_terminal, chunk) {
+          // Bun reuses the buffer between callbacks.
+          options.onData(chunk.slice());
+        }
+      }
+    });
+    const pid = proc.pid;
+    const exited = proc.exited.then(() => ({
+      exitCode: proc.signalCode ? null : proc.exitCode,
+      signal: proc.signalCode ?? null
+    }));
+    return {
+      pid,
+      exited,
+      write: data => proc.terminal.write(data),
+      resize: (cols, rows) => proc.terminal.resize(cols, rows),
+      signal(signal) {
+        try {
+          process.kill(-pid, signal);
+        } catch {
+          try {
+            process.kill(pid, signal);
+          } catch {
+            // already gone
+          }
+        }
+      },
+      groupAlive() {
+        try {
+          process.kill(-pid, 0);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      close() {
+        try {
+          proc.terminal.close();
+        } catch {
+          // already closed
+        }
+      }
+    };
+  }
+};

package/dist/modules/shell/registry.js

@@ -0,0 +1,83 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+/**
+ * On-disk record of process groups the daemon owns. If the daemon dies without stopping its
+ * shells, the next daemon kills whatever is still alive from that list.
+ */
+export class ProcessRegistry {
+  entries = new Map();
+  constructor(file, log) {
+    this.file = file;
+    this.log = log;
+  }
+
+  /** Kill leftovers from a previous daemon. Returns how many process groups were reaped. */
+  reap() {
+    let previous = [];
+    try {
+      previous = JSON.parse(readFileSync(this.file, "utf8"));
+    } catch {
+      // no registry yet, or unreadable: nothing to reap
+    }
+    let reaped = 0;
+    for (const entry of previous) {
+      const started = processStartTime(entry.pid);
+      if (!started || started !== entry.started) continue; // gone, or the pid now belongs to someone else
+      signalGroup(entry.pid, "SIGKILL");
+      reaped++;
+      this.log.warn("reaped orphaned shell", {
+        id: entry.id,
+        pid: entry.pid,
+        command: entry.command
+      });
+    }
+    this.entries.clear();
+    this.flush();
+    return reaped;
+  }
+  add(id, pid, command) {
+    const started = processStartTime(pid);
+    if (!started) return;
+    this.entries.set(id, {
+      id,
+      pid,
+      started,
+      command
+    });
+    this.flush();
+  }
+  remove(id) {
+    if (this.entries.delete(id)) this.flush();
+  }
+  flush() {
+    const tmp = `${this.file}.tmp`;
+    try {
+      writeFileSync(tmp, JSON.stringify([...this.entries.values()]), {
+        mode: 0o600
+      });
+      renameSync(tmp, this.file);
+    } catch (err) {
+      this.log.warn("could not write process registry", {
+        err: String(err)
+      });
+    }
+  }
+}
+export function processStartTime(pid) {
+  const result = Bun.spawnSync(["ps", "-o", "lstart=", "-p", String(pid)], {
+    stdout: "pipe",
+    stderr: "ignore"
+  });
+  const text = result.stdout.toString().trim();
+  return result.exitCode === 0 && text ? text : undefined;
+}
+function signalGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+      // already gone
+    }
+  }
+}

package/dist/modules/shell/shell.js

@@ -0,0 +1,193 @@
+import { LineLog } from "./output/line-log.js";
+import { OutputNormalizer } from "./output/normalizer.js";
+import { RawRing } from "./output/raw-ring.js";
+import { Screen } from "./output/screen.js";
+const ERROR_LINE = /\b(error|err!|failed|failure|fatal|panic|exception|traceback)\b|✗|✖/i;
+/**
+ * One shell: a command, its PTY, and the three output views (ADR 0003).
+ * Survives restarts: `run` increments and output views continue, separated by a marker line.
+ */
+export class Shell {
+  status = "running";
+  run = 0;
+  /** First log line number belonging to the current run. */
+  runStartLine = 1;
+  lastOutputAt = Date.now();
+  listeners = new Set();
+  startedAt = 0;
+  stopRequested = false;
+  exitPromise = Promise.resolve();
+  constructor(spec, backend, limits) {
+    this.spec = spec;
+    this.backend = backend;
+    this.log = new LineLog(limits.logChars);
+    this.raw = new RawRing(limits.rawBytes);
+    this.screen = new Screen(spec.cols, spec.rows, limits.scrollback);
+    this.normalizer = this.createNormalizer();
+  }
+  get id() {
+    return this.spec.id;
+  }
+
+  /** The line currently being written (e.g. a prompt awaiting input); empty when none. */
+  get partialLine() {
+    return this.normalizer.partial;
+  }
+  get running() {
+    return this.status === "running";
+  }
+
+  /** Resolves when the current run has fully exited and been accounted for. */
+  get exited() {
+    return this.exitPromise;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  start() {
+    if (this.running && this.pty) throw new Error("shell is already running");
+    this.run++;
+    if (this.run > 1) {
+      this.normalizer.flush();
+      this.log.append(`──── restart (run ${this.run}) ────`);
+      this.screen.reset();
+    }
+    this.runStartLine = this.log.lastLine + 1;
+    this.status = "running";
+    this.startedAt = Date.now();
+    this.lastOutputAt = this.startedAt;
+    this.endedAt = undefined;
+    this.exit = undefined;
+    this.error = undefined;
+    this.summary = undefined;
+    this.stopRequested = false;
+    try {
+      this.pty = this.backend.spawn({
+        command: this.spec.command,
+        args: this.spec.args,
+        cwd: this.spec.cwd,
+        env: this.spec.env,
+        cols: this.spec.cols,
+        rows: this.spec.rows,
+        onData: chunk => this.onData(chunk)
+      });
+    } catch (err) {
+      this.pty = undefined;
+      this.status = "failed";
+      this.error = err instanceof Error ? err.message : String(err);
+      this.endedAt = Date.now();
+      this.log.append(`[cockpit] failed to start: ${this.error}`);
+      throw err;
+    }
+    const pty = this.pty;
+    this.exitPromise = pty.exited.then(exit => this.onExit(pty, exit));
+    if (this.spec.timeoutMs) {
+      this.timeout = setTimeout(() => void this.stop("SIGTERM", 3000), this.spec.timeoutMs);
+    }
+  }
+  write(data) {
+    if (!this.running || !this.pty) throw new Error(`shell is ${this.status}`);
+    return this.pty.write(data);
+  }
+  resize(cols, rows) {
+    this.spec.cols = cols;
+    this.spec.rows = rows;
+    this.screen.resize(cols, rows);
+    if (this.running) this.pty?.resize(cols, rows);
+  }
+
+  /** Signal the group, escalate to SIGKILL after `graceMs`, and reap stragglers. */
+  async stop(signal = "SIGTERM", graceMs = 3000) {
+    const pty = this.pty;
+    if (!pty || !this.running) return;
+    this.stopRequested = true;
+    pty.signal(signal);
+    const exited = await Promise.race([this.exitPromise.then(() => true), Bun.sleep(graceMs).then(() => false)]);
+    if (!exited) {
+      pty.signal("SIGKILL");
+      await this.exitPromise;
+    }
+    if (pty.groupAlive()) pty.signal("SIGKILL");
+  }
+  async snapshot() {
+    return this.screen.snapshot();
+  }
+  info() {
+    const info = {
+      id: this.spec.id,
+      title: this.spec.title,
+      command: this.spec.command,
+      args: this.spec.args,
+      cwd: this.spec.cwd,
+      owner: this.spec.owner,
+      status: this.status,
+      run: this.run,
+      startedAt: this.startedAt,
+      cols: this.spec.cols,
+      rows: this.spec.rows,
+      lines: {
+        first: this.log.firstLine,
+        last: this.log.lastLine
+      },
+      bytes: this.raw.end
+    };
+    if (this.pty) info.pid = this.pty.pid;
+    if (this.exit?.exitCode != null) info.exitCode = this.exit.exitCode;
+    if (this.exit?.signal) info.signal = this.exit.signal;
+    if (this.error) info.error = this.error;
+    if (this.summary) info.summary = this.summary;
+    if (this.endedAt) info.endedAt = this.endedAt;
+    return info;
+  }
+  dispose() {
+    clearTimeout(this.timeout);
+    this.listeners.clear();
+    this.pty?.close();
+    this.screen.dispose();
+  }
+
+  /** Last error-looking line of the current run, else its last non-empty line. */
+  summarize() {
+    const from = Math.max(this.runStartLine, this.log.lastLine - 200 + 1);
+    let last;
+    for (let n = this.log.lastLine; n >= from; n--) {
+      const text = this.log.get(n)?.trim();
+      if (!text) continue;
+      last ??= text;
+      if (ERROR_LINE.test(text)) return text.slice(0, 300);
+    }
+    return last?.slice(0, 300);
+  }
+  createNormalizer() {
+    return new OutputNormalizer(text => {
+      const line = this.log.append(text);
+      for (const l of this.listeners) l.line?.(line);
+    });
+  }
+  onData(chunk) {
+    this.lastOutputAt = Date.now();
+    const offset = this.raw.append(chunk);
+    this.screen.write(chunk);
+    this.normalizer.push(chunk);
+    const partial = this.normalizer.partial;
+    for (const l of this.listeners) {
+      l.data?.(offset, chunk);
+      if (partial) l.partial?.(partial);
+    }
+  }
+  onExit(pty, exit) {
+    if (this.pty !== pty) return; // a newer run replaced this one
+    clearTimeout(this.timeout);
+    this.normalizer.flush();
+    this.exit = exit;
+    this.endedAt = Date.now();
+    this.status = this.stopRequested || exit.signal ? "killed" : "exited";
+    this.summary = this.summarize();
+    // Session leader is gone; make sure nothing it left behind keeps running.
+    if (pty.groupAlive()) pty.signal("SIGHUP");
+    pty.close();
+    const info = this.info();
+    for (const l of this.listeners) l.exit?.(info);
+  }
+}

package/dist/modules/shell/wait.js

@@ -0,0 +1,107 @@
+import { probePort } from "./port-probe.js";
+export const PORT_POLL_MS = 250;
+
+/**
+ * Races every condition in `until` plus the timeout. Exit always ends a wait: once the process is
+ * gone no pattern, port or idle condition can still become true.
+ */
+export function waitFor(shell, params, compile) {
+  const {
+    until,
+    timeoutMs
+  } = params;
+  return new Promise(resolve => {
+    const cleanups = [];
+    let done = false;
+    const finish = outcome => {
+      if (done) return;
+      done = true;
+      for (const cleanup of cleanups) cleanup();
+      resolve(outcome);
+    };
+    const regex = until.pattern !== undefined ? compile(until.pattern, until.ignoreCase ?? false) : undefined;
+
+    // Lines already written count: "wait until ready" must succeed if it is ready already.
+    if (regex) {
+      const after = params.after ?? shell.runStartLine - 1;
+      const existing = shell.log.read({
+        after,
+        tail: 0,
+        limit: Number.MAX_SAFE_INTEGER,
+        grep: regex
+      });
+      const first = existing.lines[0];
+      if (first) return finish({
+        reason: "pattern",
+        match: first
+      });
+      // A prompt already on screen has no newline yet, so it is not in the log.
+      const partial = shell.partialLine;
+      if (partial && regex.test(partial)) {
+        return finish({
+          reason: "pattern",
+          match: {
+            n: shell.log.lastLine + 1,
+            text: partial
+          }
+        });
+      }
+    }
+    if (!shell.running) return finish({
+      reason: "exit"
+    });
+    let idleTimer;
+    const armIdle = () => {
+      if (until.idleMs === undefined) return;
+      clearTimeout(idleTimer);
+      const remaining = Math.max(0, until.idleMs - (Date.now() - shell.lastOutputAt));
+      idleTimer = setTimeout(() => finish({
+        reason: "idle"
+      }), remaining);
+    };
+    armIdle();
+    cleanups.push(() => clearTimeout(idleTimer));
+    cleanups.push(shell.subscribe({
+      line(line) {
+        if (regex?.test(line.text)) finish({
+          reason: "pattern",
+          match: line
+        });
+      },
+      partial(text) {
+        if (regex?.test(text)) finish({
+          reason: "pattern",
+          match: {
+            n: shell.log.lastLine + 1,
+            text
+          }
+        });
+      },
+      data: () => armIdle(),
+      exit: () => finish({
+        reason: "exit"
+      })
+    }));
+    if (until.port !== undefined) {
+      const port = until.port;
+      const host = until.host ?? "127.0.0.1";
+      let polling = true;
+      const poll = async () => {
+        while (polling && !done) {
+          if (await probePort(port, host)) return finish({
+            reason: "port"
+          });
+          await Bun.sleep(PORT_POLL_MS);
+        }
+      };
+      void poll();
+      cleanups.push(() => {
+        polling = false;
+      });
+    }
+    const timer = setTimeout(() => finish({
+      reason: "timeout"
+    }), timeoutMs);
+    cleanups.push(() => clearTimeout(timer));
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencode-cockpit/daemon",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "cockpitd: the process host behind opencode-cockpit (PTY shells, clean logs, wait conditions)",
   "type": "module",
   "license": "MIT",
@@ -21,12 +21,19 @@
     "terminal"
   ],
   "exports": {
-    ".": "./src/index.ts",
-    "./main": "./src/main.ts",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./main": {
+      "types": "./types/main.d.ts",
+      "default": "./dist/main.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
-    "src",
+    "dist",
+    "types",
     "README.md",
     "LICENSE"
   ],
@@ -34,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@opencode-cockpit/protocol": "0.1.3",
+    "@opencode-cockpit/protocol": "0.1.5",
     "@xterm/headless": "6.0.0"
   },
   "engines": {

package/types/core/daemon.d.ts

@@ -0,0 +1,36 @@
+import { type CockpitPaths } from "@opencode-cockpit/protocol";
+import { type Level, type Logger } from "./logger.ts";
+import type { Module } from "./module.ts";
+export interface DaemonOptions {
+    paths: CockpitPaths;
+    modules: Module[];
+    /** Shut down after this long with no clients and no busy module. 0 disables. */
+    idleTimeoutMs?: number;
+    logLevel?: Level;
+    /** Log to the log file (default) or stderr. */
+    logToFile?: boolean;
+}
+export declare const DAEMON_VERSION: string;
+/** Build id of this daemon's own code; computed once, matches what clients compute for the entry. */
+export declare const DAEMON_BUILD: string;
+export declare class Daemon {
+    private readonly options;
+    readonly log: Logger;
+    private readonly router;
+    private readonly server;
+    private readonly startedAt;
+    private idleTimer;
+    private idleCheck;
+    private stopping;
+    private resolveStopped;
+    /** Resolves once the daemon has fully shut down. */
+    readonly stopped: Promise<void>;
+    constructor(options: DaemonOptions);
+    start(): Promise<void>;
+    stop(reason?: string): Promise<void>;
+    private busy;
+    private refreshIdle;
+    /** Refuse to start if a live daemon owns the socket; otherwise clear a stale one. */
+    private claimSocket;
+    private registerCore;
+}

package/types/core/errors.d.ts

@@ -0,0 +1,4 @@
+import { RpcError } from "@opencode-cockpit/protocol";
+export declare const notFound: (what: string) => RpcError;
+export declare const invalidState: (message: string) => RpcError;
+export declare const invalidParams: (message: string, data?: unknown) => RpcError;

package/types/core/logger.d.ts

@@ -0,0 +1,11 @@
+export type Level = "debug" | "info" | "warn" | "error";
+export interface Logger {
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+    child(scope: string): Logger;
+}
+/** JSON-lines logger. Writes synchronously so the last lines survive a crash. */
+export declare function createLogger(file: string | undefined, level?: Level, scope?: string): Logger;
+export declare const silentLogger: Logger;

package/types/core/module.d.ts

@@ -0,0 +1,37 @@
+import type { MethodName, Methods, ParsedParamsOf, ResultOf } from "@opencode-cockpit/protocol";
+import type { Logger } from "./logger.ts";
+/** A connected client as seen by modules. */
+export interface Peer {
+    readonly id: number;
+    readonly name: string;
+    /** Send an event to this peer only, regardless of its subscriptions. */
+    send(topic: string, data: unknown): void;
+    /** Run when the peer disconnects. */
+    onClose(fn: () => void): void;
+    /** Topic patterns: exact (`shell.exited`), namespace (`shell.*`) or everything (`*`). */
+    readonly topics: Set<string>;
+    greet(name: string): void;
+}
+export interface CallContext {
+    peer: Peer;
+}
+export interface ModuleContext {
+    log: Logger;
+    /** Broadcast to every peer subscribed to `topic`. */
+    emit(topic: string, data: unknown): void;
+}
+type Handler<M extends MethodName> = (params: ParsedParamsOf<Methods, M>, call: CallContext) => Promise<ResultOf<Methods, M>> | ResultOf<Methods, M>;
+/** Handlers for the methods under one namespace, typed from the protocol contract. */
+export type MethodTable<NS extends string> = {
+    [M in MethodName as M extends `${NS}.${infer Rest}` ? Rest : never]: Handler<M>;
+};
+export interface Module<NS extends string = string> {
+    readonly name: NS;
+    /** Typed per namespace; erased to a plain record when modules are handled generically. */
+    readonly methods: string extends NS ? object : MethodTable<NS>;
+    start(ctx: ModuleContext): Promise<void>;
+    stop(): Promise<void>;
+    /** While true the daemon will not shut down for idleness. */
+    busy(): boolean;
+}
+export {};

package/types/core/router.d.ts

@@ -0,0 +1,11 @@
+import type { CallContext, Module } from "./module.ts";
+type AnyHandler = (params: unknown, call: CallContext) => unknown;
+/** Validates params against the protocol contract and dispatches to module handlers. */
+export declare class Router {
+    private readonly handlers;
+    add(name: string, handler: AnyHandler): void;
+    addModule(module: Module): void;
+    has(name: string): boolean;
+    dispatch(name: string, params: unknown, call: CallContext): Promise<unknown>;
+}
+export {};

package/types/core/server.d.ts

@@ -0,0 +1,49 @@
+import type { Socket } from "bun";
+import type { Logger } from "./logger.ts";
+import type { Peer } from "./module.ts";
+import type { Router } from "./router.ts";
+interface ConnState {
+    peer: PeerImpl;
+}
+declare class PeerImpl implements Peer {
+    readonly id: number;
+    private readonly socket;
+    private readonly log;
+    name: string;
+    greeted: boolean;
+    readonly topics: Set<string>;
+    private readonly closers;
+    private queue;
+    private queued;
+    closed: boolean;
+    constructor(id: number, socket: Socket<ConnState>, log: Logger);
+    greet(name: string): void;
+    onClose(fn: () => void): void;
+    send(topic: string, data: unknown): void;
+    subscribed(topic: string): boolean;
+    write(message: unknown): void;
+    drain(): void;
+    close(): void;
+    private enqueue;
+}
+export interface RpcServerHooks {
+    onConnect(count: number): void;
+    onDisconnect(count: number): void;
+}
+export declare class RpcServer {
+    private readonly router;
+    private readonly hooks;
+    private readonly log;
+    private listener;
+    private readonly peers;
+    private nextId;
+    constructor(router: Router, hooks: RpcServerHooks, log: Logger);
+    get clientCount(): number;
+    listen(path: string): void;
+    broadcast(topic: string, data: unknown): void;
+    stop(): void;
+    private drop;
+    private handleLine;
+    private invoke;
+}
+export type { PeerImpl };

package/{src/index.ts → types/index.d.ts}

@@ -1,5 +1,5 @@
-export { DAEMON_BUILD, DAEMON_VERSION, Daemon, type DaemonOptions } from "./core/daemon.ts"
-export type { CallContext, MethodTable, Module, ModuleContext, Peer } from "./core/module.ts"
-export { createModules, type ModuleOptions } from "./modules/index.ts"
-export { ShellModule, type ShellModuleOptions } from "./modules/shell/module.ts"
-export type { PtyBackend, PtyProcess, PtySpawnOptions } from "./modules/shell/pty.ts"
+export { DAEMON_BUILD, DAEMON_VERSION, Daemon, type DaemonOptions } from "./core/daemon.ts";
+export type { CallContext, MethodTable, Module, ModuleContext, Peer } from "./core/module.ts";
+export { createModules, type ModuleOptions } from "./modules/index.ts";
+export { ShellModule, type ShellModuleOptions } from "./modules/shell/module.ts";
+export type { PtyBackend, PtyProcess, PtySpawnOptions } from "./modules/shell/pty.ts";

package/types/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/types/modules/index.d.ts

@@ -0,0 +1,7 @@
+import type { Module } from "../core/module.ts";
+import { type ShellModuleOptions } from "./shell/module.ts";
+export interface ModuleOptions {
+    shell?: ShellModuleOptions;
+}
+/** Every capability the daemon hosts. Add new modules here. */
+export declare function createModules(options?: ModuleOptions): Module[];

package/types/modules/shell/ids.d.ts

@@ -0,0 +1 @@
+export declare function newShellId(): string;