station-kit 1.0.0

package/src/server/routes/runs.ts

@@ -0,0 +1,149 @@
+import { Hono } from "hono";
+import type { SignalRunner, SignalQueueAdapter } from "station-signal";
+import type { LogBuffer } from "../log-buffer.js";
+import type { LogStore } from "../log-store.js";
+
+export interface RunDeps {
+  signalRunner?: SignalRunner;
+  signalAdapter: SignalQueueAdapter;
+  logBuffer: LogBuffer;
+  logStore?: LogStore;
+}
+
+export function runRoutes(deps: RunDeps) {
+  const app = new Hono();
+
+  app.get("/runs", async (c) => {
+    const status = c.req.query("status");
+    const signalName = c.req.query("signalName");
+
+    // Gather runs from adapter
+    let runs: any[] = [];
+
+    if (signalName) {
+      runs = await deps.signalAdapter.listRuns(signalName);
+    } else {
+      // Get all runs by combining due + running + listing by known signals
+      const due = await deps.signalAdapter.getRunsDue();
+      const running = await deps.signalAdapter.getRunsRunning();
+      const seen = new Set<string>();
+      for (const r of [...due, ...running]) {
+        if (!seen.has(r.id)) {
+          seen.add(r.id);
+          runs.push(r);
+        }
+      }
+
+      // Also get runs from known signals
+      if (deps.signalRunner) {
+        for (const { name } of deps.signalRunner.listRegistered()) {
+          const signalRuns = await deps.signalAdapter.listRuns(name);
+          for (const r of signalRuns) {
+            if (!seen.has(r.id)) {
+              seen.add(r.id);
+              runs.push(r);
+            }
+          }
+        }
+      }
+    }
+
+    if (status) {
+      runs = runs.filter((r) => r.status === status);
+    }
+
+    // Sort by createdAt descending
+    runs.sort((a, b) => {
+      const aTime = a.createdAt instanceof Date ? a.createdAt.getTime() : new Date(a.createdAt).getTime();
+      const bTime = b.createdAt instanceof Date ? b.createdAt.getTime() : new Date(b.createdAt).getTime();
+      return bTime - aTime;
+    });
+
+    return c.json({
+      data: runs.map(serializeRun),
+      meta: { total: runs.length },
+    });
+  });
+
+  app.get("/runs/stats", async (c) => {
+    const due = await deps.signalAdapter.getRunsDue();
+    const running = await deps.signalAdapter.getRunsRunning();
+
+    // Aggregate from known signals
+    let allRuns: any[] = [...due, ...running];
+    const seen = new Set(allRuns.map((r) => r.id));
+
+    if (deps.signalRunner) {
+      for (const { name } of deps.signalRunner.listRegistered()) {
+        const signalRuns = await deps.signalAdapter.listRuns(name);
+        for (const r of signalRuns) {
+          if (!seen.has(r.id)) {
+            seen.add(r.id);
+            allRuns.push(r);
+          }
+        }
+      }
+    }
+
+    const stats = { pending: 0, running: 0, completed: 0, failed: 0, cancelled: 0 };
+    for (const r of allRuns) {
+      if (r.status in stats) {
+        stats[r.status as keyof typeof stats]++;
+      }
+    }
+
+    return c.json({ data: stats });
+  });
+
+  app.get("/runs/:id", async (c) => {
+    const id = c.req.param("id");
+    const run = await deps.signalAdapter.getRun(id);
+    if (!run) {
+      return c.json({ error: "not_found", message: "Run not found." }, 404);
+    }
+    return c.json({ data: serializeRun(run) });
+  });
+
+  app.get("/runs/:id/steps", async (c) => {
+    const id = c.req.param("id");
+    const steps = await deps.signalAdapter.getSteps(id);
+    return c.json({
+      data: steps.map((s) => ({
+        ...s,
+        startedAt: s.startedAt?.toISOString?.() ?? s.startedAt,
+        completedAt: s.completedAt?.toISOString?.() ?? s.completedAt,
+      })),
+    });
+  });
+
+  app.get("/runs/:id/logs", async (c) => {
+    const id = c.req.param("id");
+    const logs = deps.logStore?.get(id) ?? deps.logBuffer.get(id);
+    return c.json({ data: logs });
+  });
+
+  app.post("/runs/:id/cancel", async (c) => {
+    const id = c.req.param("id");
+    if (!deps.signalRunner) {
+      return c.json({ error: "read_only", message: "Station is in read-only mode." }, 403);
+    }
+    const success = await deps.signalRunner.cancel(id);
+    if (!success) {
+      return c.json({ error: "cannot_cancel", message: "Run cannot be cancelled." }, 400);
+    }
+    return c.json({ data: { cancelled: true } });
+  });
+
+  return app;
+}
+
+function serializeRun(run: any): Record<string, unknown> {
+  return {
+    ...run,
+    nextRunAt: run.nextRunAt?.toISOString?.() ?? run.nextRunAt,
+    lastRunAt: run.lastRunAt?.toISOString?.() ?? run.lastRunAt,
+    startedAt: run.startedAt?.toISOString?.() ?? run.startedAt,
+    completedAt: run.completedAt?.toISOString?.() ?? run.completedAt,
+    createdAt: run.createdAt?.toISOString?.() ?? run.createdAt,
+  };
+}

package/src/server/routes/signals.ts

@@ -0,0 +1,153 @@
+import { Hono } from "hono";
+import type { SignalRunner, SignalQueueAdapter } from "station-signal";
+import type { StationSignalSubscriber } from "../subscriber.js";
+
+export interface SignalDeps {
+  signalRunner?: SignalRunner;
+  signalAdapter: SignalQueueAdapter;
+  signalSubscriber?: StationSignalSubscriber;
+}
+
+export function signalRoutes(deps: SignalDeps) {
+  const app = new Hono();
+
+  // GET /signals — list all signals with metadata
+  app.get("/signals", async (c) => {
+    // Prefer metadata from subscriber (includes schemas, config)
+    if (deps.signalSubscriber) {
+      const meta = deps.signalSubscriber.getAllSignalMeta();
+      if (meta.length > 0) {
+        return c.json({ data: meta });
+      }
+    }
+
+    // Fallback to registry
+    if (!deps.signalRunner) {
+      return c.json({ data: [] });
+    }
+    const result = deps.signalRunner.listRegistered().map(({ name, filePath }) => ({ name, filePath }));
+    return c.json({ data: result });
+  });
+
+  // GET /signals/scheduled — recurring signals with next/last run info
+  app.get("/signals/scheduled", async (c) => {
+    const allMeta = deps.signalSubscriber?.getAllSignalMeta() ?? [];
+    const recurring = allMeta.filter((s) => s.interval);
+
+    const result: Array<{
+      name: string;
+      interval: string;
+      nextRunAt: string | null;
+      lastRunAt: string | null;
+      lastStatus: string | null;
+    }> = [];
+
+    for (const sig of recurring) {
+      const runs = await deps.signalAdapter.listRuns(sig.name);
+      const pendingRun = runs.find((r) => r.status === "pending" && r.kind === "recurring");
+      const lastRun = runs
+        .filter((r) => r.status !== "pending")
+        .sort((a, b) => {
+          const aT = a.completedAt ?? a.startedAt ?? a.createdAt;
+          const bT = b.completedAt ?? b.startedAt ?? b.createdAt;
+          const aMs = aT instanceof Date ? aT.getTime() : new Date(aT).getTime();
+          const bMs = bT instanceof Date ? bT.getTime() : new Date(bT).getTime();
+          return bMs - aMs;
+        })[0];
+
+      result.push({
+        name: sig.name,
+        interval: sig.interval!,
+        nextRunAt: pendingRun?.nextRunAt
+          ? (pendingRun.nextRunAt instanceof Date ? pendingRun.nextRunAt.toISOString() : String(pendingRun.nextRunAt))
+          : null,
+        lastRunAt: lastRun?.completedAt
+          ? (lastRun.completedAt instanceof Date ? lastRun.completedAt.toISOString() : String(lastRun.completedAt))
+          : lastRun?.startedAt
+            ? (lastRun.startedAt instanceof Date ? lastRun.startedAt.toISOString() : String(lastRun.startedAt))
+            : null,
+        lastStatus: lastRun?.status ?? null,
+      });
+    }
+
+    return c.json({ data: result });
+  });
+
+  // GET /signals/:name — single signal metadata
+  app.get("/signals/:name", async (c) => {
+    const name = c.req.param("name");
+
+    if (deps.signalSubscriber) {
+      const meta = deps.signalSubscriber.getSignalMeta(name);
+      if (meta) {
+        return c.json({ data: meta });
+      }
+    }
+
+    // Fallback: check registry
+    if (deps.signalRunner) {
+      const entry = deps.signalRunner.listRegistered().find((s) => s.name === name);
+      if (entry) {
+        return c.json({ data: { name, filePath: entry.filePath } });
+      }
+    }
+
+    return c.json({ error: "not_found", message: `Signal "${name}" not found.` }, 404);
+  });
+
+  // POST /signals/:name/trigger
+  app.post("/signals/:name/trigger", async (c) => {
+    const name = c.req.param("name");
+    if (!deps.signalRunner) {
+      return c.json({ error: "read_only", message: "Station is in read-only mode." }, 403);
+    }
+
+    if (!deps.signalRunner.hasSignal(name)) {
+      return c.json({ error: "not_found", message: `Signal "${name}" not found.` }, 404);
+    }
+
+    const body = await c.req.json().catch(() => ({}));
+    const input = body.input ?? {};
+
+    const id = deps.signalAdapter.generateId();
+    await deps.signalAdapter.addRun({
+      id,
+      signalName: name,
+      kind: "trigger",
+      input: JSON.stringify(input),
+      status: "pending",
+      attempts: 0,
+      maxAttempts: 3,
+      timeout: 5 * 60 * 1000,
+      createdAt: new Date(),
+    });
+
+    return c.json({ data: { id } });
+  });
+
+  // GET /signals/:name/runs
+  app.get("/signals/:name/runs", async (c) => {
+    const name = c.req.param("name");
+    if (!deps.signalRunner) {
+      return c.json({ data: [], meta: { total: 0 } });
+    }
+    const runs = await deps.signalRunner.listRuns(name);
+    return c.json({
+      data: runs.map(serializeRun),
+      meta: { total: runs.length },
+    });
+  });
+
+  return app;
+}
+
+function serializeRun(run: any): Record<string, unknown> {
+  return {
+    ...run,
+    nextRunAt: run.nextRunAt?.toISOString?.() ?? run.nextRunAt,
+    lastRunAt: run.lastRunAt?.toISOString?.() ?? run.lastRunAt,
+    startedAt: run.startedAt?.toISOString?.() ?? run.startedAt,
+    completedAt: run.completedAt?.toISOString?.() ?? run.completedAt,
+    createdAt: run.createdAt?.toISOString?.() ?? run.createdAt,
+  };
+}

package/src/server/routes/v1/auth.ts

@@ -0,0 +1,47 @@
+import { Hono } from "hono";
+import { verifyCredentials, createSessionToken, type SessionConfig } from "../../auth/session.js";
+
+export interface V1AuthRouteDeps {
+  sessionConfig?: SessionConfig;
+}
+
+export function v1AuthRoutes(deps: V1AuthRouteDeps) {
+  const app = new Hono();
+
+  app.post("/auth/login", async (c) => {
+    if (!deps.sessionConfig) {
+      return c.json({ error: "unavailable", message: "Auth not configured." }, 503);
+    }
+
+    const body = await c.req.json().catch(() => ({}));
+    const { username, password } = body;
+
+    if (!username || !password) {
+      return c.json({ error: "bad_request", message: "Missing username or password." }, 400);
+    }
+
+    if (!verifyCredentials(username, password, deps.sessionConfig)) {
+      return c.json({ error: "unauthorized", message: "Invalid credentials." }, 401);
+    }
+
+    const token = createSessionToken(deps.sessionConfig);
+    const ttlSeconds = Math.floor(
+      (deps.sessionConfig.sessionTtlMs ?? 86_400_000) / 1000,
+    );
+    c.header(
+      "Set-Cookie",
+      `station_session=${token}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${ttlSeconds}`,
+    );
+    return c.json({ data: { ok: true } });
+  });
+
+  app.post("/auth/logout", async (c) => {
+    c.header(
+      "Set-Cookie",
+      "station_session=; HttpOnly; SameSite=Lax; Path=/; Max-Age=0",
+    );
+    return c.json({ data: { ok: true } });
+  });
+
+  return app;
+}

package/src/server/routes/v1/broadcasts.ts

@@ -0,0 +1,84 @@
+import { Hono } from "hono";
+import type { BroadcastRunner, BroadcastQueueAdapter, BroadcastRun } from "station-broadcast";
+import type { StationBroadcastSubscriber } from "../../subscriber.js";
+
+export interface V1BroadcastDeps {
+  broadcastRunner?: BroadcastRunner;
+  broadcastAdapter?: BroadcastQueueAdapter;
+  broadcastSubscriber?: StationBroadcastSubscriber;
+}
+
+export function v1BroadcastRoutes(deps: V1BroadcastDeps) {
+  const app = new Hono();
+
+  app.get("/broadcasts", async (c) => {
+    if (deps.broadcastSubscriber) {
+      const meta = deps.broadcastSubscriber.getAllBroadcastMeta();
+      if (meta.length > 0) return c.json({ data: meta });
+    }
+
+    if (!deps.broadcastRunner) return c.json({ data: [] });
+
+    // BroadcastRunner.listRegistered() returns { name, nodeCount, failurePolicy, timeout?, interval? }
+    const result = deps.broadcastRunner.listRegistered();
+    return c.json({ data: result });
+  });
+
+  app.get("/broadcasts/:name", async (c) => {
+    const name = c.req.param("name");
+
+    if (deps.broadcastSubscriber) {
+      const meta = deps.broadcastSubscriber.getBroadcastMeta(name);
+      if (meta) return c.json({ data: meta });
+    }
+
+    if (deps.broadcastRunner) {
+      const entry = deps.broadcastRunner.listRegistered().find((b) => b.name === name);
+      if (entry) return c.json({ data: entry });
+    }
+
+    return c.json({ error: "not_found", message: `Broadcast "${name}" not found.` }, 404);
+  });
+
+  app.get("/broadcast-runs/:id", async (c) => {
+    if (!deps.broadcastAdapter) {
+      return c.json({ error: "unavailable", message: "No broadcast adapter configured." }, 503);
+    }
+    const id = c.req.param("id");
+    const run = await deps.broadcastAdapter.getBroadcastRun(id);
+    if (!run) {
+      return c.json({ error: "not_found", message: "Broadcast run not found." }, 404);
+    }
+    return c.json({ data: serializeBroadcastRun(run) });
+  });
+
+  app.get("/broadcast-runs/:id/nodes", async (c) => {
+    if (!deps.broadcastAdapter) {
+      return c.json({ error: "unavailable", message: "No broadcast adapter configured." }, 503);
+    }
+    const id = c.req.param("id");
+    const nodes = await deps.broadcastAdapter.getNodeRuns(id);
+    return c.json({
+      data: nodes.map((n) => ({
+        ...n,
+        startedAt: n.startedAt?.toISOString?.() ?? n.startedAt,
+        completedAt: n.completedAt?.toISOString?.() ?? n.completedAt,
+      })),
+    });
+  });
+
+  // Cancel endpoint is not included here — it requires "cancel" scope
+  // and is mounted separately in the server wiring.
+
+  return app;
+}
+
+function serializeBroadcastRun(run: BroadcastRun): Record<string, unknown> {
+  return {
+    ...run,
+    nextRunAt: run.nextRunAt?.toISOString?.() ?? run.nextRunAt,
+    startedAt: run.startedAt?.toISOString?.() ?? run.startedAt,
+    completedAt: run.completedAt?.toISOString?.() ?? run.completedAt,
+    createdAt: run.createdAt?.toISOString?.() ?? run.createdAt,
+  };
+}

package/src/server/routes/v1/events.ts

@@ -0,0 +1,71 @@
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import crypto from "node:crypto";
+import type { SSEHub, SSEClient } from "../../sse.js";
+import type { StationEvent } from "../../ws.js";
+
+export interface V1EventDeps {
+  sseHub: SSEHub;
+}
+
+export function v1EventRoutes(deps: V1EventDeps) {
+  const app = new Hono();
+
+  app.get("/events", (c) => {
+    const signalFilter = c.req.query("signals")
+      ? new Set(c.req.query("signals")!.split(",").filter(Boolean))
+      : null;
+    const broadcastFilter = c.req.query("broadcasts")
+      ? new Set(c.req.query("broadcasts")!.split(",").filter(Boolean))
+      : null;
+    const eventFilter = c.req.query("events")
+      ? new Set(c.req.query("events")!.split(",").filter(Boolean))
+      : null;
+
+    return streamSSE(c, async (stream) => {
+      const clientId = crypto.randomUUID();
+      let eventCounter = 0;
+
+      const client: SSEClient = {
+        id: clientId,
+        signalFilter,
+        broadcastFilter,
+        eventFilter,
+        send(event: StationEvent) {
+          eventCounter++;
+          stream.writeSSE({
+            event: event.type,
+            data: JSON.stringify(event.data),
+            id: `evt_${eventCounter}`,
+          });
+        },
+        close() {
+          stream.close();
+        },
+      };
+
+      deps.sseHub.addClient(client);
+
+      // Keep connection alive with a periodic heartbeat comment
+      const heartbeat = setInterval(() => {
+        stream.writeSSE({ event: "heartbeat", data: "" });
+      }, 30_000);
+
+      // Clean up when client disconnects
+      stream.onAbort(() => {
+        clearInterval(heartbeat);
+        deps.sseHub.removeClient(clientId);
+      });
+
+      // Hold the connection open indefinitely until the client disconnects.
+      // The stream will be closed by onAbort or by the SSEHub.close() method.
+      await new Promise<void>((resolve) => {
+        stream.onAbort(() => {
+          resolve();
+        });
+      });
+    });
+  });
+
+  return app;
+}

package/src/server/routes/v1/health.ts

@@ -0,0 +1,41 @@
+import { Hono } from "hono";
+import type { SignalQueueAdapter } from "station-signal";
+import type { BroadcastQueueAdapter } from "station-broadcast";
+
+export interface V1HealthDeps {
+  signalAdapter: SignalQueueAdapter;
+  broadcastAdapter?: BroadcastQueueAdapter;
+}
+
+export function v1HealthRoutes(deps: V1HealthDeps) {
+  const app = new Hono();
+
+  app.get("/health", async (c) => {
+    let signalOk = false;
+    let broadcastOk = false;
+
+    try {
+      signalOk = await deps.signalAdapter.ping();
+    } catch {
+      // ping failed — signalOk stays false
+    }
+
+    if (deps.broadcastAdapter) {
+      try {
+        broadcastOk = await deps.broadcastAdapter.ping();
+      } catch {
+        // ping failed — broadcastOk stays false
+      }
+    }
+
+    return c.json({
+      data: {
+        ok: signalOk && (!deps.broadcastAdapter || broadcastOk),
+        signal: signalOk,
+        broadcast: deps.broadcastAdapter ? broadcastOk : null,
+      },
+    });
+  });
+
+  return app;
+}

package/src/server/routes/v1/keys.ts

@@ -0,0 +1,57 @@
+import { Hono } from "hono";
+import type { KeyStore } from "../../auth/keys.js";
+
+export interface V1KeyDeps {
+  keyStore?: KeyStore;
+}
+
+export function v1KeyRoutes(deps: V1KeyDeps) {
+  const app = new Hono();
+
+  app.post("/keys", async (c) => {
+    if (!deps.keyStore) {
+      return c.json({ error: "unavailable", message: "Auth not configured." }, 503);
+    }
+
+    const body = await c.req.json().catch(() => ({}));
+    const name = body.name || "Unnamed key";
+    const scopes = Array.isArray(body.scopes) ? body.scopes : ["trigger", "read"];
+
+    const { key, record } = deps.keyStore.create(name, scopes);
+    return c.json(
+      {
+        data: {
+          id: record.id,
+          name: record.name,
+          key, // Only returned at creation time
+          keyPrefix: record.keyPrefix,
+          scopes: record.scopes,
+          createdAt: record.createdAt,
+        },
+      },
+      201,
+    );
+  });
+
+  app.get("/keys", async (c) => {
+    if (!deps.keyStore) {
+      return c.json({ error: "unavailable", message: "Auth not configured." }, 503);
+    }
+    const keys = deps.keyStore.list();
+    return c.json({ data: keys });
+  });
+
+  app.delete("/keys/:id", async (c) => {
+    if (!deps.keyStore) {
+      return c.json({ error: "unavailable", message: "Auth not configured." }, 503);
+    }
+    const id = c.req.param("id");
+    const success = deps.keyStore.revoke(id);
+    if (!success) {
+      return c.json({ error: "not_found", message: "Key not found." }, 404);
+    }
+    return c.json({ data: { revoked: true } });
+  });
+
+  return app;
+}

package/src/server/routes/v1/runs.ts

@@ -0,0 +1,97 @@
+import { Hono } from "hono";
+import type { SignalRunner, SignalQueueAdapter, Run } from "station-signal";
+import type { LogBuffer } from "../../log-buffer.js";
+import type { LogStore } from "../../log-store.js";
+
+export interface V1RunDeps {
+  signalRunner?: SignalRunner;
+  signalAdapter: SignalQueueAdapter;
+  logBuffer: LogBuffer;
+  logStore?: LogStore;
+}
+
+// Cancel endpoint is not included here — it requires "cancel" scope
+// and is mounted separately in the server wiring.
+
+export function v1RunRoutes(deps: V1RunDeps) {
+  const app = new Hono();
+
+  app.get("/runs", async (c) => {
+    const status = c.req.query("status");
+    const signalName = c.req.query("signalName");
+    const limit = Math.min(parseInt(c.req.query("limit") ?? "50", 10) || 50, 200);
+
+    let runs: Run[] = [];
+
+    if (signalName) {
+      runs = await deps.signalAdapter.listRuns(signalName);
+    } else if (deps.signalRunner) {
+      const seen = new Set<string>();
+      for (const { name } of deps.signalRunner.listRegistered()) {
+        const signalRuns = await deps.signalAdapter.listRuns(name);
+        for (const r of signalRuns) {
+          if (!seen.has(r.id)) {
+            seen.add(r.id);
+            runs.push(r);
+          }
+        }
+      }
+    }
+
+    if (status) {
+      runs = runs.filter((r) => r.status === status);
+    }
+
+    runs.sort((a, b) => {
+      const aTime = a.createdAt instanceof Date
+        ? a.createdAt.getTime()
+        : new Date(a.createdAt as unknown as string).getTime();
+      const bTime = b.createdAt instanceof Date
+        ? b.createdAt.getTime()
+        : new Date(b.createdAt as unknown as string).getTime();
+      return bTime - aTime;
+    });
+
+    runs = runs.slice(0, limit);
+
+    return c.json({ data: runs.map(serializeRun), meta: { total: runs.length } });
+  });
+
+  app.get("/runs/:id", async (c) => {
+    const id = c.req.param("id");
+    const run = await deps.signalAdapter.getRun(id);
+    if (!run) return c.json({ error: "not_found", message: "Run not found." }, 404);
+    return c.json({ data: serializeRun(run) });
+  });
+
+  app.get("/runs/:id/steps", async (c) => {
+    const id = c.req.param("id");
+    const steps = await deps.signalAdapter.getSteps(id);
+    return c.json({
+      data: steps.map((s) => ({
+        ...s,
+        startedAt: s.startedAt?.toISOString?.() ?? s.startedAt,
+        completedAt: s.completedAt?.toISOString?.() ?? s.completedAt,
+      })),
+    });
+  });
+
+  app.get("/runs/:id/logs", async (c) => {
+    const id = c.req.param("id");
+    const logs = deps.logStore?.get(id) ?? deps.logBuffer.get(id);
+    return c.json({ data: logs });
+  });
+
+  return app;
+}
+
+function serializeRun(run: Run): Record<string, unknown> {
+  return {
+    ...run,
+    nextRunAt: run.nextRunAt?.toISOString?.() ?? run.nextRunAt,
+    lastRunAt: run.lastRunAt?.toISOString?.() ?? run.lastRunAt,
+    startedAt: run.startedAt?.toISOString?.() ?? run.startedAt,
+    completedAt: run.completedAt?.toISOString?.() ?? run.completedAt,
+    createdAt: run.createdAt?.toISOString?.() ?? run.createdAt,
+  };
+}