ompchamber 0.5.0 → 0.6.0

package/src/client/hooks/editor/use-file-editor.ts

@@ -40,9 +40,11 @@ export interface UseFileEditorResult {
   saveNow: () => void;
   copy: () => void;
   download: () => void;
-  /** Forget cached content for the active file and read it again. */
-  reload: () => void;
-  /** Forget all cached content (e.g. a workspace refresh). */
+  /**
+   * Re-read every cached file from disk (e.g. a workspace refresh). Content
+   * already on screen stays until the fresh bytes land, and a file with
+   * unsaved edits is left alone.
+   */
   reset: () => void;
   /** Drop cached content for files no longer open. */
   retain: (ids: Array<number | string>) => void;
@@ -77,6 +79,8 @@ export function useFileEditor(
   const [loadError, setLoadError] = useState<string | null>(null);
   const [saveStatus, setSaveStatus] = useState<FileEditorSaveStatus>('idle');
   const [copied, setCopied] = useState(false);
+  /** Bumped by `reset()` to re-run the read effect for the active file. */
+  const [revision, setRevision] = useState(0);
 
   const key = target ? targetKey(target) : '';
   const content = target ? (contents[key] ?? target.content ?? '') : '';
@@ -87,6 +91,14 @@ export function useFileEditor(
   const loadedRef = useRef<Set<string>>(new Set());
   const pendingRef = useRef<{ timer: number; file: FileEditorTarget; content: string } | null>(null);
 
+  // Live mirrors of the content maps: a read response resolves long after it
+  // was requested, and it has to know whether the buffer it read is still the
+  // one on screen.
+  const contentsRef = useRef(contents);
+  contentsRef.current = contents;
+  const baselinesRef = useRef(baselines);
+  baselinesRef.current = baselines;
+
   const remember = useCallback((fileKey: string, text: string) => {
     setContents((prev) => ({ ...prev, [fileKey]: text }));
     setBaselines((prev) => ({ ...prev, [fileKey]: text }));
@@ -145,8 +157,11 @@ export function useFileEditor(
       return;
     }
 
+    // Only a key with nothing on screen yet shows the loading state: a
+    // re-read (refreshKey / reset) must not flash a spinner over live content.
+    const firstLoad = contentsRef.current[fileKey] === undefined;
     let cancelled = false;
-    setIsLoading(true);
+    if (firstLoad) setIsLoading(true);
     setLoadError(null);
     const params = new URLSearchParams({ path: target.path });
     if (target.root) params.set('root', target.root);
@@ -164,10 +179,20 @@ export function useFileEditor(
       })
       .then((text) => {
         if (cancelled) return;
+        // These bytes were read before the response arrived, so anything typed
+        // since is newer. Applying them would replace those keystrokes (and,
+        // once a refresh is triggered by a save, wipe the editor back to an
+        // empty buffer) — instead let the queued write own the key.
+        const typed = contentsRef.current[fileKey];
+        if (typed !== undefined && typed !== baselinesRef.current[fileKey]) return;
+        const queued = pendingRef.current;
+        if (queued && targetKey(queued.file) === fileKey) return;
         remember(fileKey, text ?? (fallback ? fallback(target.name) : ''));
       })
       .catch((err: unknown) => {
         if (cancelled) return;
+        // A failed re-read keeps what is on screen; only a first load reports.
+        if (!firstLoad) return;
         if (reportLoadError) {
           remember(fileKey, '');
           setLoadError(err instanceof Error ? err.message : 'Failed to read file');
@@ -182,7 +207,7 @@ export function useFileEditor(
     return () => {
       cancelled = true;
     };
-  }, [key, target, fallback, reportLoadError, remember]);
+  }, [key, target, fallback, reportLoadError, remember, revision]);
 
   useEffect(() => {
     if (saveStatus !== 'saved') return;
@@ -239,21 +264,13 @@ export function useFileEditor(
     URL.revokeObjectURL(url);
   }, [target, contents, downloadMimeType]);
 
-  const reload = useCallback(() => {
-    if (!key) return;
-    loadedRef.current.delete(key);
-    setContents((prev) => {
-      if (prev[key] === undefined) return prev;
-      const next = { ...prev };
-      delete next[key];
-      return next;
-    });
-  }, [key]);
-
   const reset = useCallback(() => {
+    // Invalidate every key, then let the read effect refetch the active one.
+    // Content is deliberately NOT cleared: it stays on screen until the fresh
+    // bytes land, so a refresh can never blank the editor (or drop the file
+    // that is open) while the request is in flight.
     loadedRef.current.clear();
-    setContents({});
-    setBaselines({});
+    setRevision((prev) => prev + 1);
   }, []);
 
   const retain = useCallback((ids: Array<number | string>) => {
@@ -295,7 +312,6 @@ export function useFileEditor(
     saveNow,
     copy,
     download,
-    reload,
     reset,
     retain,
   };

package/src/server/index.ts

@@ -1,9 +1,12 @@
 import { Elysia } from 'elysia';
+import pkg from '@/../package.json';
 import { apiRoutes } from '@/server/routes';
 import { ssrRoutes } from '@/server/plugins/ssr';
 import { getDatabasePath } from '@/server/db.server';
 import { fetchOmpRegistrySnapshot } from '@/server/lib/models/provider-registry.server';
 import { ompStartupError, ompStartupLogLines } from '@/server/lib/omp/core/startup';
+import { readInstanceRecord, removeInstanceRecord, writeInstanceRecord } from '@/server/lib/lifecycle/instance';
+import { acquirePortLock, claimPort, PortInUseError } from '@/server/lib/lifecycle/port-guard';
 import { isMockMode } from '@/server/mock.server';
 
 // Refuse to run without a resolvable omp binary — before the listener opens and
@@ -24,10 +27,57 @@ console.log(`[ompchamber] db:             ${await getDatabasePath()}`);
 
 const port = Number(Bun.env.PORT) || 3000;
 const host = Bun.env.HOST || 'localhost';
+const mode = Bun.env.NODE_ENV === 'production' ? 'prod' : 'dev';
+const launchMode = Bun.env.OMPCHAMBER_LAUNCH_MODE === 'daemon' || Bun.env.OMPCHAMBER_LAUNCH_MODE === 'foreground'
+  ? Bun.env.OMPCHAMBER_LAUNCH_MODE
+  : 'direct';
+
+const lock = await acquirePortLock(port);
+if (!lock) {
+  console.error(`[ompchamber] another OMPChamber instance is starting on port ${port} right now — retry in a moment.`);
+  process.exit(1);
+}
 
 const app = new Elysia().use(apiRoutes).use(ssrRoutes);
 
-await app.listen({ port, hostname: host });
+try {
+  await claimPort({
+    port,
+    host,
+    listen: async () => {
+      // `reusePort: false` is load-bearing: Elysia's Bun adapter hardcodes
+      // `reusePort: true`, which lets a second server bind a port already in
+      // use and then sit invisible while the first-bound socket takes every
+      // connection.
+      await app.listen({ port, hostname: host, reusePort: false });
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(error instanceof PortInUseError ? `[ompchamber] ${message}` : `[ompchamber] could not listen on ${host}:${port} — ${message}`);
+  process.exit(1);
+} finally {
+  lock.release();
+}
+
+// The record is written by the process that owns the port, so `status`, `stop`
+// and the next `serve` see dev, foreground and daemon servers alike. A hot
+// reload re-runs this entry in the same process: keeping the first `startedAt`
+// for a PID that already recorded this port is what makes `status` report real
+// uptime instead of resetting it on every save.
+const previousRecord = readInstanceRecord(port);
+if (!writeInstanceRecord({
+  pid: process.pid,
+  port,
+  host,
+  mode,
+  launchMode,
+  startedAt: previousRecord?.pid === process.pid ? previousRecord.startedAt : new Date().toISOString(),
+  version: pkg.version,
+})) {
+  console.log('[ompchamber] instance record not written (data directory not writable) — `ompchamber status` will fall back to probing this port');
+}
+process.on('exit', () => removeInstanceRecord(port));
 
 // The listener is already accepting requests here, so the probe only postpones
 // this last banner line, never startup. Printing it after the probe keeps the

package/src/server/lib/lifecycle/identity.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Process identity for a PID recorded for a port.
+ *
+ * Liveness alone cannot answer "is this PID still an OMPChamber server": after
+ * an ungraceful exit the PID can be recycled to an unrelated process, and a
+ * liveness-only check then reports a live instance nobody is serving — which
+ * either blocks startup on a free port or, worse, lets a stale record name a
+ * stranger. Identity therefore comes from the OS command line, so a recycled
+ * PID reads back as `mismatched`.
+ *
+ * Where `ps` is unavailable (minimal containers) the on-disk `/proc` entry
+ * still answers the identity question on Linux; on Windows, where neither is
+ * cheap, identity is reported as `unknown` and callers fall back to liveness.
+ */
+
+import fs from 'fs';
+
+export type ProcessState = 'dead' | 'matched' | 'mismatched' | 'unknown';
+
+interface ProcessRow {
+  pid: number;
+  /** `ps` state column — `Z…` means defunct (exited, awaiting reaping). */
+  state: string;
+  command: string;
+}
+
+let cachedTable: { at: number; rows: ProcessRow[] } | null = null;
+
+/**
+ * One snapshot of the process table, memoized for a startup decision.
+ *
+ * Every question in a port check happens within milliseconds, so a briefly
+ * cached view is strictly better than spawning `ps` per question.
+ */
+function readProcessTable(maxAgeMs = 250): ProcessRow[] {
+  if (cachedTable && Date.now() - cachedTable.at < maxAgeMs) return cachedTable.rows;
+  const rows: ProcessRow[] = [];
+  try {
+    const snapshot = Bun.spawnSync({
+      cmd: ['ps', '-ax', '-o', 'pid=,stat=,command='],
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    if (snapshot.success) {
+      for (const line of snapshot.stdout.toString().split('\n')) {
+        const match = /^\s*(\d+)\s+(\S+)\s+(.*)$/.exec(line);
+        if (!match) continue;
+        rows.push({ pid: Number(match[1]), state: match[2], command: match[3].trim() });
+      }
+    }
+  } catch {
+    // No `ps` on PATH: identity falls back to /proc, liveness to signal 0.
+  }
+  cachedTable = { at: Date.now(), rows };
+  return rows;
+}
+
+/**
+ * Liveness check. Never throws.
+ *
+ * A defunct (zombie) PID still answers signal 0 — the process has exited and is
+ * only waiting for its parent to reap it — so a zombie counts as not alive: it
+ * holds no port and will never run again. Without this, a stop that worked
+ * looks like a process that "ignored SIGTERM", and stop-waits spin until their
+ * timeout.
+ */
+export function isProcessAlive(pid: number): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  const row = readProcessTable().find((entry) => entry.pid === pid);
+  return row ? !row.state.startsWith('Z') : true;
+}
+
+/** Command line for a live PID, or null when this platform cannot report one. */
+function readProcessCommandLine(pid: number): string | null {
+  const row = readProcessTable().find((entry) => entry.pid === pid);
+  if (row) return row.command.length > 0 ? row.command : null;
+  if (process.platform === 'linux') {
+    try {
+      return fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ').trim() || null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * `dead` | `matched` | `mismatched` | `unknown` for a PID.
+ *
+ * `unknown` means identity could not be read; callers treat it as "alive but
+ * unverified" — never as confirmation that the PID is ours.
+ */
+export function getProcessState(pid: number): ProcessState {
+  if (!isProcessAlive(pid)) return 'dead';
+  const command = readProcessCommandLine(pid);
+  if (command === null) return 'unknown';
+  return command.toLowerCase().includes('ompchamber') ? 'matched' : 'mismatched';
+}

package/src/server/lib/lifecycle/instance.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The per-port instance record: who is serving this port, in what mode, since
+ * when.
+ *
+ * Written by the server that owns the port (not by the CLI that happened to
+ * spawn it), so a server started by `bun run dev`, by `--foreground`, or by the
+ * daemon path is discoverable the same way. Writes are best-effort: a read-only
+ * data directory must degrade `status` to a probe, never take the server down.
+ */
+
+import fs from 'fs';
+
+import { getInstancePath, getRunDir } from '@/server/lib/lifecycle/paths';
+
+export type InstanceMode = 'dev' | 'prod';
+export type InstanceLaunchMode = 'daemon' | 'foreground' | 'direct';
+
+export interface InstanceRecord {
+  pid: number;
+  port: number;
+  host: string;
+  mode: InstanceMode;
+  launchMode: InstanceLaunchMode;
+  startedAt: string;
+  version: string;
+}
+
+function isLaunchMode(value: unknown): value is InstanceLaunchMode {
+  return value === 'daemon' || value === 'foreground' || value === 'direct';
+}
+
+/** Record for `port`, or null when absent or unreadable. */
+export function readInstanceRecord(port: number | string): InstanceRecord | null {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(getInstancePath(port), 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    const record = parsed as Record<string, unknown>;
+    if (typeof record.pid !== 'number' || typeof record.port !== 'number') return null;
+    return {
+      pid: record.pid,
+      port: record.port,
+      host: typeof record.host === 'string' ? record.host : 'localhost',
+      mode: record.mode === 'prod' ? 'prod' : 'dev',
+      launchMode: isLaunchMode(record.launchMode) ? record.launchMode : 'direct',
+      startedAt: typeof record.startedAt === 'string' ? record.startedAt : '',
+      version: typeof record.version === 'string' ? record.version : '',
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Every readable record in the run directory. */
+export function listInstanceRecords(): InstanceRecord[] {
+  const records: InstanceRecord[] = [];
+  try {
+    for (const file of fs.readdirSync(getRunDir())) {
+      const match = /^(\d+)\.json$/.exec(file);
+      if (!match) continue;
+      const record = readInstanceRecord(match[1]);
+      if (record) records.push(record);
+    }
+  } catch {
+    // No run directory yet: nothing has ever been served.
+  }
+  return records;
+}
+
+/**
+ * Persist the record for its port (sibling temp file + rename, mode 0600).
+ * Returns false instead of throwing when the data directory is not writable.
+ */
+export function writeInstanceRecord(record: InstanceRecord): boolean {
+  const target = getInstancePath(record.port);
+  const temp = `${target}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(temp, JSON.stringify(record, null, 2), { mode: 0o600 });
+    fs.renameSync(temp, target);
+    return true;
+  } catch {
+    try {
+      fs.rmSync(temp, { force: true });
+    } catch {
+      // Best-effort cleanup only.
+    }
+    return false;
+  }
+}
+
+/** Drop the record for `port`. Never throws. */
+export function removeInstanceRecord(port: number | string): void {
+  try {
+    fs.rmSync(getInstancePath(port), { force: true });
+  } catch {
+    // Best-effort: a stale record is detected by PID identity on the next read.
+  }
+}

package/src/server/lib/lifecycle/occupant.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Who is serving a port right now.
+ *
+ * Two independent sources answer that question, and they are deliberately
+ * combined: the instance record (written by the server itself) and the live
+ * `/api/health` probe. The record is the only source for a port whose server is
+ * deaf (hung, suspended, still starting), while the probe is the only source
+ * for a server started outside the CLI — a `bun run dev` server must be
+ * discoverable, and before this module it was invisible to every CLI command.
+ */
+
+import { getProcessState, isProcessAlive } from '@/server/lib/lifecycle/identity';
+import { readInstanceRecord } from '@/server/lib/lifecycle/instance';
+import { fetchHealth } from '@/server/lib/lifecycle/probe';
+
+export interface Occupant {
+  pid: number;
+  port: number;
+  host?: string;
+  version?: string;
+  /** `dev` | `prod` as reported by the live server, else from the record. */
+  mode?: string;
+  launchMode?: string;
+  startedAt?: string;
+  uptime?: number;
+  source: 'registry+probe' | 'probe' | 'registry';
+  /** True when the occupant answered `/api/health` as OMPChamber itself. */
+  confirmedByHealth: boolean;
+}
+
+/** The OMPChamber instance on `port`, or null when the port is free/foreign. */
+export async function findOccupant(port: number, host?: string | null): Promise<Occupant | null> {
+  const record = readInstanceRecord(port);
+  const recordIsLive = record !== null
+    && isProcessAlive(record.pid)
+    && getProcessState(record.pid) !== 'mismatched';
+
+  const health = await fetchHealth(port, record?.host ?? host);
+  const healthPid = health?.pid;
+  if (health && typeof healthPid === 'number' && isProcessAlive(healthPid)) {
+    return {
+      pid: healthPid,
+      port,
+      host: record?.host ?? host ?? undefined,
+      version: health.version ?? record?.version,
+      mode: health.mode ?? record?.mode,
+      launchMode: record?.launchMode,
+      startedAt: health.startedAt ?? record?.startedAt,
+      uptime: health.uptime,
+      source: recordIsLive && record.pid === healthPid ? 'registry+probe' : 'probe',
+      confirmedByHealth: true,
+    };
+  }
+
+  if (record && recordIsLive) {
+    return {
+      pid: record.pid,
+      port,
+      host: record.host,
+      version: record.version,
+      mode: record.mode,
+      launchMode: record.launchMode,
+      startedAt: record.startedAt,
+      source: 'registry',
+      confirmedByHealth: false,
+    };
+  }
+
+  return null;
+}
+
+/** One-line identity for logs and errors: `pid 1234 (dev, direct, v0.5.0, up 2m)`. */
+export function describeOccupant(occupant: Occupant): string {
+  const details: string[] = [];
+  if (occupant.mode) details.push(occupant.mode);
+  if (occupant.launchMode) details.push(occupant.launchMode);
+  if (occupant.version) details.push(`v${occupant.version}`);
+  const age = occupantAge(occupant);
+  if (age) details.push(`up ${age}`);
+  if (!occupant.confirmedByHealth) details.push('unconfirmed');
+  const suffix = details.length > 0 ? ` (${details.join(', ')})` : '';
+  return `pid ${occupant.pid}${suffix}`;
+}
+
+function occupantAge(occupant: Occupant): string | null {
+  const seconds = typeof occupant.uptime === 'number'
+    ? Math.round(occupant.uptime)
+    : occupant.startedAt
+      ? Math.round((Date.now() - Date.parse(occupant.startedAt)) / 1000)
+      : Number.NaN;
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}

package/src/server/lib/lifecycle/paths.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Where OMPChamber keeps per-port runtime state.
+ *
+ * Both the server and the CLI need these paths, and they must agree: the server
+ * owns the record for the port it listens on, and the CLI reads that same record
+ * to answer `status` / `stop` / `logs`. One module is what makes the agreement
+ * structural — the previous split (CLI wrote, server never did) is why a server
+ * started outside the CLI was invisible to every CLI command.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+/**
+ * Root of OMPChamber's own state (~/.ompchamber, or OMPCHAMBER_DATA_DIR).
+ *
+ * `os.homedir()` rather than HOME: a process started without a shell (cron,
+ * launchd, a service) has no HOME, and an empty value would silently move the
+ * data directory to a cwd-relative path.
+ */
+export function getDataDir(): string {
+  const override = (Bun.env.OMPCHAMBER_DATA_DIR ?? '').trim();
+  if (override) {
+    return path.resolve(override.startsWith('~') ? path.join(os.homedir(), override.slice(1)) : override);
+  }
+  return path.join(os.homedir(), '.ompchamber');
+}
+
+/** Directory holding per-instance records and handover locks (mode 0700). */
+export function getRunDir(): string {
+  const dir = path.join(getDataDir(), 'run');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+/** `<data>/run/<port>.json` — the record written by the server serving `port`. */
+export function getInstancePath(port: number | string): string {
+  return path.join(getRunDir(), `${port}.json`);
+}
+
+/** `<data>/run/<port>.lock` — held only while a port handover is in progress. */
+export function getLockPath(port: number | string): string {
+  return path.join(getRunDir(), `${port}.lock`);
+}