shraga 0.1.4 → 0.1.5

package/README.md

@@ -86,9 +86,59 @@ The core is deliberately small and grows through documented seams (see
 | **Route extensions** (`data/extensions/*.ext.ts`) | Drop-in public routes (webhooks, OAuth callbacks) per deployment. |
 | **`SHRAGA_OVERLAY`** | Load a whole external add-on module at startup (the overlay tier above). |
 
-## Quickstart
+## Use as a library
+
+Shraga's first-class surface is the `createShraga` factory (the package `main`/`exports`). You
+`import` it, wire your registrations against the same seams the built-ins use, then own the
+lifecycle — `start()` returns a handle you can `stop()`. The CLI and the run-from-source entry are
+thin wrappers over this exact call (`createShraga(fromEnv()).start()`).
+
+```ts
+import { createShraga } from 'shraga';
+
+const shraga = createShraga({
+  port: 3032,
+  dataDir: './data',
+  authProvider: 'local',          // 'local' (default) | 'firebase'
+});
+
+// Pre-start registration (chainable). See "The extension seams" in AGENTS.md.
+shraga
+  .registerFeature(myFeature)      // server routes/WS/consumers
+  .registerEngine(myEngine)        // a pluggable agent runtime
+  .registerExtension(register)     // same shape as a data/extensions/*.ext.ts default export
+  .registerWebhook({ source: 'stripe', verify })  // public POST /api/webhooks/stripe → typed event
+  .on('stripe', (payload, evt) => { /* handle the event */ });
+
+const handle = await shraga.start();
+console.log(`listening on ${handle.url}`);   // { app, server, port, url, emitEvent, on, ... }
+
+// later:
+await handle.stop();               // drains and closes without exiting the process
+```
+
+`ShragaOptions` is typed; anything not modelled is still reachable via `env` (Shraga is heavily
+env-driven), applied before boot:
+
+```ts
+createShraga({ env: { ANTHROPIC_API_KEY: '…', SHRAGA_FEAT_WORKSPACE: '1' } });
+```
+
+**`ServerHandle`** (returned by `start()`): `{ app, server, port, url, emitEvent, on,
+registerExtension, registerWebhook, stop }`.
+
+**Runtime plug-and-play is opt-in.** `registerFeature`/`registerEngine`/`registerExtension`/
+`registerWebhook`/`on` are meant to run **before** `start()`. If you need to register *after* boot,
+set `runtimeRegistration: true` (or `SHRAGA_RUNTIME_REGISTRATION=1`) — then the `ServerHandle`'s
+`registerExtension`/`registerWebhook`/`on` mount onto the live extension Router / event bus.
+Default is **off**, and those handle methods throw until you enable it. Only extensions, webhooks
+and event subscriptions are runtime-registerable — features and engines mount at boot and are never
+runtime-registerable, on or off.
+
+## Quickstart (CLI)
 
-Requires [Bun](https://bun.sh) ≥ 1.0.
+Requires [Bun](https://bun.sh) ≥ 1.0. Env-configured, no code — this is the `createShraga(fromEnv())`
+tier.
 
 **Fastest — run from npm:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/index.ts

@@ -56,6 +56,11 @@ export class ShragaOptions {
   /** Install process SIGTERM/SIGINT handlers (default true — the standalone server/CLI wants them).
    *  A library embedder owning its own lifecycle sets false and uses stop(). */
   installSignalHandlers?: boolean = true;
+  /** OPT-IN runtime plug-and-play (default false). When true, the ServerHandle returned by start()
+   *  can register extensions/webhooks and subscribe to events AFTER boot (they mount on the live
+   *  extension Router / event bus). When false, those handle methods throw. Pre-start registration is
+   *  unaffected either way. Features & engines are NEVER runtime-registerable (they mount at boot). */
+  runtimeRegistration?: boolean = false;
   /** Arbitrary extra environment to apply before boot (e.g. ANTHROPIC_API_KEY, SHRAGA_FEAT_*). */
   env?: Record<string, string>;
 }
@@ -103,6 +108,7 @@ class Shraga implements ShragaInstance {
     if (o.authProvider != null) process.env.AUTH_PROVIDER = o.authProvider;
     if (o.passive != null) process.env.SHRAGA_PASSIVE = o.passive ? '1' : '0';
     if (o.installSignalHandlers === false) process.env.SHRAGA_INSTALL_SIGNALS = '0';
+    if (o.runtimeRegistration != null) process.env.SHRAGA_RUNTIME_REGISTRATION = o.runtimeRegistration ? '1' : '0';
     for (const [k, v] of Object.entries(o.env ?? {})) process.env[k] = v;
   }
 
@@ -163,10 +169,12 @@ export function createShraga(options?: Partial<ShragaOptions>): ShragaInstance {
  *  run-from-source entry and the CLI pass this straight into createShraga. */
 export function fromEnv(): Partial<ShragaOptions> {
   const passive = process.env.SHRAGA_PASSIVE ?? process.env.UNCLAW_PASSIVE;
+  const runtimeReg = process.env.SHRAGA_RUNTIME_REGISTRATION;
   return {
     port: process.env.PORT ? Number(process.env.PORT) : undefined,
     dataDir: process.env.DATA_DIR || undefined,
     authProvider: (process.env.AUTH_PROVIDER as 'local' | 'firebase' | undefined) || undefined,
     passive: passive === '1' || passive === 'true' ? true : undefined,
+    runtimeRegistration: runtimeReg === '1' || runtimeReg === 'true' ? true : undefined,
   };
 }

package/src/server/boot.ts

@@ -22,6 +22,7 @@ import { requireAuth, verifyBearer, AUTH_PROVIDER, localLogin, addLocalUser, loc
 import { getMcpConfig, getRawMcpConfig, getResolvedMcpConfig, getGlobalMcpConfig, saveMcpConfig, maskEnvValues, mergeWithOriginal, type McpConfig } from './mcp.ts';
 import { streamChat, consumeStream, getAgentConfig, saveAgentConfig, type AgentConfig, type PermissionHandler, type QuestionHandler, type QuestionAnswers, type AttachmentMeta, type WsEvent } from './claude.ts';
 import { mountFeatures, registerFeature, resumeFeatureSession, collectFeatureFlags, collectSidecarRoutes } from './features.ts';
+import { registerSpaCatchAll } from './spa-catchall.ts';
 import { slackFeature } from './slack/feature.ts';
 import { dataPath } from './paths.ts';
 import { getAllSessions, getSession, getSessionHistory, upsertSession, appendMessage, saveConversation, loadConversation, setSessionDirectives, getAutoApprove, setAutoApprove, getSessionsByScheduleId, getSessionsVisibleTo, isSessionVisibleTo, setRunStatus, incrementRetryCount, resetRetryCount, getRunningSessions, updateScheduledSessionStatus, setShuttingDown, backfillSessionVisibility, writePartial, readPartial, clearPartial, registerLivePartial, unregisterLivePartial, readLivePartial, acquireSessionLock, releaseSessionLock, replaceSessionLock, isSessionLocked, getSessionAbortController, forkSession, generateSessionTitle, type ConvBlock, type ConvMessage, type SessionMeta } from './sessions.ts';
@@ -62,6 +63,8 @@ import type { Server as HttpServer } from 'node:http';
 import type { Express } from 'express';
 import { emitEvent } from './events/bus.ts';
 import type { ExtRegisterFn } from './extensions.ts';
+import type { WebhookOptions } from './events/webhook.ts';
+import type { ShragaEvent, PayloadOf } from './events/types.ts';
 
 export interface BootRegistrations {
   features?: ServerFeature[];
@@ -77,6 +80,16 @@ export interface ServerHandle {
   url: string;
   /** Publish an event onto the in-process bus (same fn extensions get as ctx.emitEvent). */
   emitEvent: typeof emitEvent;
+  /** Register an extension AFTER start() — mounts onto the live extension Router (before the SPA
+   *  catch-all), the same seam file-based *.ext.ts drop-ins hot-load through. OPT-IN: throws unless
+   *  ShragaOptions.runtimeRegistration is enabled. */
+  registerExtension: (fn: ExtRegisterFn) => Promise<void>;
+  /** Declare a verified vendor webhook AFTER start() (sugar over registerExtension — a webhook IS an
+   *  extension). OPT-IN: throws unless runtimeRegistration is enabled. */
+  registerWebhook: <K extends string>(opts: WebhookOptions<K>) => Promise<void>;
+  /** Subscribe to a typed event source AFTER start(). Returns an unsubscribe fn. OPT-IN: throws
+   *  unless runtimeRegistration is enabled. */
+  on: <K extends string>(source: K, handler: (payload: PayloadOf<K>, evt: ShragaEvent<K>) => void) => () => void;
   /** Drain in-flight streams, stop consumers, close the server. Does NOT exit the process. */
   stop: () => Promise<void>;
 }
@@ -723,9 +736,12 @@ await loadExtensions(app);
 
 if (existsSync(distPath)) app.use(express.static(distPath));
 
-// NOTE: the SPA catch-all (`app.get('*')`) is registered LATER — after mountFeatures() — so that
-// feature-contributed routes (incl. GET) are matched before falling through to index.html. Registering
-// it here would shadow every feature GET route (Express matches '*' first). See registerSpaCatchAll().
+// The SPA catch-all (`app.get('*')`) is registered LATER — after mountFeatures() — via
+// registerSpaCatchAll(), so feature/extension GET routes are matched before falling through to
+// index.html. It is re-registered on passive→active promotion (mountFeatures runs again there),
+// each call splicing out the prior catch-all layer so it stays truly LAST in the router stack.
+// In dev (no dist/) it is skipped entirely — Vite serves the SPA and a catch-all would 404-shadow it.
+// Implementation + predicate live in ./spa-catchall.ts (unit-tested there).
 
 // ── WebSocket + Server ───────────────────────────────────────────────────────
 
@@ -946,6 +962,9 @@ mountFeatures({ app, requireAuth, broadcast, passive: PASSIVE });
 // Fold in feature-contributed sidecar WS proxy routes (the core names none; each add-on adds its own).
 Object.assign(WS_PROXY_ROUTES, collectSidecarRoutes());
 
+// SPA fallback — MUST be the last GET route so it never shadows real API/feature/extension routes.
+registerSpaCatchAll(app, distPath);
+
 // ── Runtime promotion (blue-green flip) ──────────────────────────────────────
 // A passive instance can be promoted to active once traffic has been flipped to it:
 // starts every consumer/writer that passive boot skipped. One-way; idempotent-guarded.
@@ -958,6 +977,8 @@ async function activateConsumers() {
   scheduler.start(broadcast);
   startEventDispatcher();
   mountFeatures({ app, requireAuth, broadcast, passive: false });
+  // Re-place the SPA catch-all AFTER the promotion's feature mount so newly-added GET routes win.
+  registerSpaCatchAll(app, distPath);
   startSidecars().catch(err => console.error('[sidecar] startup error:', err));
   recoverInterruptedSessions().catch(err => console.error('[recovery] failed:', err));
 }
@@ -1767,12 +1788,27 @@ await new Promise<void>((resolve) => {
   });
 });
 
+// OPT-IN post-start plug-and-play. Only extensions/webhooks/events are runtime-safe (they mount on
+// the persistent extRouter / in-process bus); features & engines mount at boot and are NOT re-entrant.
+const RT_FLAG = process.env.SHRAGA_RUNTIME_REGISTRATION;
+const RUNTIME_REG = RT_FLAG === '1' || RT_FLAG === 'true';
+const runtimeGuard = (what: string) => {
+  if (!RUNTIME_REG) throw new Error(
+    `[shraga] ${what}() at runtime is disabled. Enable it with createShraga({ runtimeRegistration: true }) ` +
+    `(or SHRAGA_RUNTIME_REGISTRATION=1) before start().`,
+  );
+};
+
 return {
   app,
   server,
   port: PORT,
   url: `http://localhost:${PORT}`,
   emitEvent,
+  registerExtension: (fn) => { runtimeGuard('registerExtension'); return registerExtension(fn); },
+  // A webhook is just an extension that mounts a verified route on the extension Router — reuse the seam.
+  registerWebhook: (opts) => { runtimeGuard('registerWebhook'); return registerExtension((_r, ctx) => { ctx.registerWebhook(opts); }); },
+  on: (source, handler) => { runtimeGuard('on'); return subscribeEvent(source, handler); },
   stop: () => gracefulShutdown('stop', { exit: false }),
 };
 

package/src/server/events/bus.ts

@@ -15,6 +15,14 @@ type Listener = (evt: ShragaEvent) => void;
 
 const listeners = new Set<Listener>();
 
+/** Clear all subscribers. For tests: `listeners` is a process-global, so a test file that boots a
+ *  server (or its on() subscribers) leaks listeners into a later file's emit. Reset between files
+ *  that share bus state to stay hermetic — bun's cross-file order is not stable across platforms.
+ *  Mirrors clearTurnContext()/`__resetExtensionsForTest()`. Test-only. */
+export function __resetEventBusForTest(): void {
+  listeners.clear();
+}
+
 /** Subscribe to ALL events. Returns an unsubscribe fn. The dispatcher uses this. */
 export function subscribeEvents(fn: Listener): () => void {
   listeners.add(fn);

package/src/server/extensions.ts

@@ -49,6 +49,20 @@ let extRouter: ExpressRouter | null = null;
 let ctx: ExtensionContext | null = null;
 const pendingProgrammatic: ExtRegisterFn[] = [];
 
+/** Reset the module-global router/ctx/registry. For tests: `extRouter`, `ctx` and `loaded` are
+ *  process-globals, so a test file that boots a second createShraga server in the same bun process
+ *  inherits the PRIOR file's router — and a pre-start `registerExtension`/`registerWebhook` (which
+ *  mounts immediately once `extRouter && ctx` are set, see registerExtension) then lands on the DEAD
+ *  router instead of queueing for the new one → the new server 404s. bun's cross-file order is not
+ *  stable across platforms (a Linux CI order that macOS never hits), so a test that boots a server
+ *  must reset first to be hermetic. Mirrors clearTurnContext() in turn-context.ts. Test-only. */
+export function __resetExtensionsForTest(): void {
+  extRouter = null;
+  ctx = null;
+  loaded.clear();
+  pendingProgrammatic.length = 0;
+}
+
 async function runProgrammatic(fn: ExtRegisterFn): Promise<void> {
   try {
     await fn(extRouter!, ctx!);

package/src/server/spa-catchall.ts

@@ -0,0 +1,41 @@
+import path from 'path';
+import { existsSync } from 'fs';
+import type express from 'express';
+
+// Non-page prefixes that must fall through to a real 404 (JSON/API/transport), never the SPA shell.
+function isNonPagePath(p: string): boolean {
+  return p.startsWith('/api/') || p.startsWith('/mcp') || p.startsWith('/uploads') ||
+    p.startsWith('/internal/') || p.startsWith('/.well-known');
+}
+
+/**
+ * Register the SPA catch-all (`app.get('*')`) as the LAST GET route so it serves the built
+ * index.html for client routes/deep links (/oauth/authorize, /cli-auth, /session/x, …) while
+ * letting unmatched API/MCP/upload/internal/oauth-metadata paths fall through to a real 404.
+ *
+ * Idempotent + re-placeable: each call splices out any prior catch-all layer, so it can be called
+ * again after a later mountFeatures() (passive→active promotion) and still sit behind those routes.
+ * In dev (no built dist) it is a no-op — Vite serves the SPA and a catch-all would 404-shadow it.
+ *
+ * EXPRESS 4 COUPLING: uses the bare `app.get('*')` route and Express's private `_router.stack`.
+ * A future express@5 bump breaks this LOUDLY (path-to-regexp v8 rejects `'*'`), not silently —
+ * re-verify the promotion-path ordering if express is ever upgraded.
+ */
+export function registerSpaCatchAll(app: express.Express, distPath: string): void {
+  if (!existsSync(distPath)) return;
+  const indexHtml = path.join(distPath, 'index.html');
+  // For app.get(), the layer's `handle` is the Route's dispatcher — our tagged handler lives inside
+  // `layer.route.stack[*].handle`. Match on that so re-registration removes the stale catch-all.
+  const stack = (app as any)._router?.stack as Array<{ route?: { stack?: Array<{ handle?: { __spaCatchAll?: boolean } }> } }> | undefined;
+  if (stack) {
+    for (let i = stack.length - 1; i >= 0; i--) {
+      if (stack[i]?.route?.stack?.some((h) => h?.handle?.__spaCatchAll)) stack.splice(i, 1);
+    }
+  }
+  const handler: express.RequestHandler = (req, res, next) => {
+    if (isNonPagePath(req.path)) return next();
+    res.sendFile(indexHtml);
+  };
+  (handler as { __spaCatchAll?: boolean }).__spaCatchAll = true;
+  app.get('*', handler);
+}