station-kit 1.0.0

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

@@ -0,0 +1,44 @@
+import { Hono } from "hono";
+import type { SignalRunner } from "station-signal";
+import type { StationSignalSubscriber } from "../../subscriber.js";
+
+export interface V1SignalDeps {
+  signalRunner?: SignalRunner;
+  signalSubscriber?: StationSignalSubscriber;
+}
+
+export function v1SignalRoutes(deps: V1SignalDeps) {
+  const app = new Hono();
+
+  app.get("/signals", async (c) => {
+    if (deps.signalSubscriber) {
+      const meta = deps.signalSubscriber.getAllSignalMeta();
+      if (meta.length > 0) return c.json({ data: meta });
+    }
+
+    if (!deps.signalRunner) return c.json({ data: [] });
+
+    const result = deps.signalRunner
+      .listRegistered()
+      .map(({ name, filePath }) => ({ name, filePath }));
+    return c.json({ data: result });
+  });
+
+  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 });
+    }
+
+    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);
+  });
+
+  return app;
+}

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

@@ -0,0 +1,111 @@
+import { Hono } from "hono";
+import type { SignalRunner, SignalQueueAdapter } from "station-signal";
+import type { BroadcastRunner } from "station-broadcast";
+import type { StationSignalSubscriber } from "../../subscriber.js";
+
+export interface V1TriggerDeps {
+  signalRunner?: SignalRunner;
+  signalAdapter: SignalQueueAdapter;
+  broadcastRunner?: BroadcastRunner;
+  signalSubscriber?: StationSignalSubscriber;
+}
+
+export function v1TriggerRoutes(deps: V1TriggerDeps) {
+  const app = new Hono();
+
+  app.post("/trigger", async (c) => {
+    if (!deps.signalRunner) {
+      return c.json({ error: "unavailable", message: "Station is in read-only mode." }, 503);
+    }
+
+    const body = await c.req.json().catch(() => null);
+    if (!body?.signalName) {
+      return c.json({ error: "bad_request", message: "Missing signalName." }, 400);
+    }
+
+    const { signalName, input } = body;
+
+    if (!deps.signalRunner.hasSignal(signalName)) {
+      return c.json(
+        { error: "not_found", message: `Signal "${signalName}" not registered.` },
+        404,
+      );
+    }
+
+    // Resolve maxAttempts and timeout from the signal metadata if available,
+    // otherwise fall back to sensible defaults matching the existing dashboard trigger.
+    let maxAttempts = 3;
+    let timeout = 300_000;
+
+    if (deps.signalSubscriber) {
+      const meta = deps.signalSubscriber.getSignalMeta(signalName);
+      if (meta) {
+        maxAttempts = meta.maxAttempts;
+        timeout = meta.timeout;
+      }
+    }
+
+    const id = deps.signalAdapter.generateId();
+    await deps.signalAdapter.addRun({
+      id,
+      signalName,
+      kind: "trigger",
+      input: JSON.stringify(input ?? {}),
+      status: "pending",
+      attempts: 0,
+      maxAttempts,
+      timeout,
+      createdAt: new Date(),
+    });
+
+    return c.json(
+      {
+        data: { id, signalName, status: "pending", createdAt: new Date().toISOString() },
+      },
+      201,
+    );
+  });
+
+  app.post("/trigger-broadcast", async (c) => {
+    if (!deps.broadcastRunner) {
+      return c.json(
+        { error: "unavailable", message: "Broadcast runner not configured." },
+        503,
+      );
+    }
+
+    const body = await c.req.json().catch(() => null);
+    if (!body?.broadcastName) {
+      return c.json({ error: "bad_request", message: "Missing broadcastName." }, 400);
+    }
+
+    const { broadcastName, input } = body;
+
+    if (!deps.broadcastRunner.hasBroadcast(broadcastName)) {
+      return c.json(
+        { error: "not_found", message: `Broadcast "${broadcastName}" not registered.` },
+        404,
+      );
+    }
+
+    try {
+      const id = await deps.broadcastRunner.trigger(broadcastName, input ?? {});
+      return c.json(
+        {
+          data: {
+            id,
+            broadcastName,
+            status: "pending",
+            createdAt: new Date().toISOString(),
+          },
+        },
+        201,
+      );
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      return c.json({ error: "trigger_failed", message }, 400);
+    }
+  });
+
+  return app;
+}

package/src/server/sse.ts

@@ -0,0 +1,70 @@
+import type { StationEvent } from "./ws.js";
+
+export interface SSEClient {
+  id: string;
+  send(event: StationEvent): void;
+  close(): void;
+  readonly signalFilter: Set<string> | null;
+  readonly broadcastFilter: Set<string> | null;
+  readonly eventFilter: Set<string> | null;
+}
+
+export class SSEHub {
+  private clients = new Map<string, SSEClient>();
+
+  get clientCount(): number {
+    return this.clients.size;
+  }
+
+  addClient(client: SSEClient): void {
+    this.clients.set(client.id, client);
+  }
+
+  removeClient(id: string): void {
+    this.clients.delete(id);
+  }
+
+  broadcast(event: StationEvent): void {
+    for (const client of this.clients.values()) {
+      if (this.matchesFilter(client, event)) {
+        client.send(event);
+      }
+    }
+  }
+
+  private matchesFilter(client: SSEClient, event: StationEvent): boolean {
+    // Event type filter
+    if (client.eventFilter && !client.eventFilter.has(event.type)) {
+      return false;
+    }
+
+    // Signal name filter
+    if (client.signalFilter) {
+      const data = event.data as Record<string, unknown>;
+      const run = data?.run as Record<string, unknown> | undefined;
+      const signalName = run?.signalName ?? data?.signalName;
+      if (typeof signalName === "string" && !client.signalFilter.has(signalName)) {
+        return false;
+      }
+    }
+
+    // Broadcast name filter
+    if (client.broadcastFilter) {
+      const data = event.data as Record<string, unknown>;
+      const broadcastRun = data?.broadcastRun as Record<string, unknown> | undefined;
+      const broadcastName = broadcastRun?.broadcastName ?? data?.broadcastName;
+      if (typeof broadcastName === "string" && !client.broadcastFilter.has(broadcastName)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  close(): void {
+    for (const client of this.clients.values()) {
+      client.close();
+    }
+    this.clients.clear();
+  }
+}

package/src/server/subscriber.ts

@@ -0,0 +1,288 @@
+import { isSignal } from "station-signal";
+import { isBroadcast } from "station-broadcast";
+import type { SignalSubscriber, Run, Step } from "station-signal";
+import type { BroadcastSubscriber, BroadcastRun, BroadcastNodeRun } from "station-broadcast";
+import type { WebSocketHub } from "./ws.js";
+import type { SSEHub } from "./sse.js";
+import type { LogBuffer } from "./log-buffer.js";
+import type { LogStore } from "./log-store.js";
+import { serializeZodSchema, type SignalMeta, type BroadcastMeta } from "./metadata.js";
+
+function serializeRun(run: Run): Record<string, unknown> {
+  return {
+    ...run,
+    nextRunAt: run.nextRunAt?.toISOString(),
+    lastRunAt: run.lastRunAt?.toISOString(),
+    startedAt: run.startedAt?.toISOString(),
+    completedAt: run.completedAt?.toISOString(),
+    createdAt: run.createdAt.toISOString(),
+  };
+}
+
+function serializeBroadcastRun(run: BroadcastRun): Record<string, unknown> {
+  return {
+    ...run,
+    nextRunAt: run.nextRunAt?.toISOString(),
+    startedAt: run.startedAt?.toISOString(),
+    completedAt: run.completedAt?.toISOString(),
+    createdAt: run.createdAt.toISOString(),
+  };
+}
+
+function serializeNodeRun(nr: BroadcastNodeRun): Record<string, unknown> {
+  return {
+    ...nr,
+    startedAt: nr.startedAt?.toISOString(),
+    completedAt: nr.completedAt?.toISOString(),
+  };
+}
+
+export class StationSignalSubscriber implements SignalSubscriber {
+  private logBuffer?: LogBuffer;
+  private logStore?: LogStore;
+  private sseHub?: SSEHub;
+  private signalMetaMap = new Map<string, SignalMeta>();
+
+  constructor(private hub: WebSocketHub, logBuffer?: LogBuffer, logStore?: LogStore) {
+    this.logBuffer = logBuffer;
+    this.logStore = logStore;
+  }
+
+  /** Attach an SSE hub so events are also pushed to SSE clients. */
+  setSSEHub(sseHub: SSEHub): void {
+    this.sseHub = sseHub;
+  }
+
+  private emit(type: string, data: Record<string, unknown>): void {
+    const event = { type, timestamp: new Date().toISOString(), data };
+    this.hub.broadcast(event);
+    this.sseHub?.broadcast(event);
+  }
+
+  getSignalMeta(name: string): SignalMeta | undefined {
+    return this.signalMetaMap.get(name);
+  }
+
+  getAllSignalMeta(): SignalMeta[] {
+    return [...this.signalMetaMap.values()];
+  }
+
+  onSignalDiscovered(event: { signalName: string; filePath: string }): void {
+    this.emit("signal:discovered", event);
+
+    // Async metadata collection — import is cached by Node
+    import(event.filePath).then((mod) => {
+      for (const value of Object.values(mod)) {
+        if (isSignal(value) && value.name === event.signalName) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const sig = value as any;
+          this.signalMetaMap.set(event.signalName, {
+            name: sig.name,
+            filePath: event.filePath,
+            inputSchema: sig.inputSchema ? serializeZodSchema(sig.inputSchema) : null,
+            outputSchema: sig.outputSchema ? serializeZodSchema(sig.outputSchema) : null,
+            interval: sig.interval ?? null,
+            timeout: sig.timeout,
+            maxAttempts: sig.maxAttempts,
+            maxConcurrency: sig.maxConcurrency ?? null,
+            hasSteps: Array.isArray(sig.steps) && sig.steps.length > 0,
+            stepNames: sig.steps?.map((s: { name: string }) => s.name) ?? [],
+          });
+          break;
+        }
+      }
+    }).catch(() => {});
+  }
+
+  onRunDispatched(event: { run: Run }): void {
+    this.emit("run:dispatched", { run: serializeRun(event.run) });
+  }
+
+  onRunStarted(event: { run: Run }): void {
+    this.emit("run:started", { run: serializeRun(event.run) });
+  }
+
+  onRunCompleted(event: { run: Run; output?: string }): void {
+    this.emit("run:completed", { run: serializeRun(event.run), output: event.output });
+  }
+
+  onRunTimeout(event: { run: Run }): void {
+    this.emit("run:timeout", { run: serializeRun(event.run) });
+  }
+
+  onRunRetry(event: { run: Run; attempt: number; maxAttempts: number }): void {
+    this.emit("run:retry", {
+      run: serializeRun(event.run),
+      attempt: event.attempt,
+      maxAttempts: event.maxAttempts,
+    });
+  }
+
+  onRunFailed(event: { run: Run; error?: string }): void {
+    this.emit("run:failed", { run: serializeRun(event.run), error: event.error ?? "" });
+  }
+
+  onRunCancelled(event: { run: Run }): void {
+    this.emit("run:cancelled", { run: serializeRun(event.run) });
+  }
+
+  onRunSkipped(event: { run: Run; reason: string }): void {
+    this.emit("run:skipped", { run: serializeRun(event.run), reason: event.reason });
+  }
+
+  onRunRescheduled(event: { run: Run; nextRunAt: Date }): void {
+    this.emit("run:rescheduled", {
+      run: serializeRun(event.run),
+      nextRunAt: event.nextRunAt.toISOString(),
+    });
+  }
+
+  onStepStarted(event: { run: Run; step: Pick<Step, "id" | "runId" | "name"> }): void {
+    this.emit("step:started", { run: serializeRun(event.run), step: event.step });
+  }
+
+  onStepCompleted(event: { run: Run; step: Step }): void {
+    this.emit("step:completed", {
+      run: serializeRun(event.run),
+      step: {
+        ...event.step,
+        startedAt: event.step.startedAt?.toISOString(),
+        completedAt: event.step.completedAt?.toISOString(),
+      },
+    });
+  }
+
+  onStepFailed(event: { run: Run; step: Step }): void {
+    this.emit("step:failed", {
+      run: serializeRun(event.run),
+      step: {
+        ...event.step,
+        startedAt: event.step.startedAt?.toISOString(),
+        completedAt: event.step.completedAt?.toISOString(),
+      },
+    });
+  }
+
+  onCompleteError(event: { run: Run; error: string }): void {
+    this.emit("run:completeError", { run: serializeRun(event.run), error: event.error });
+  }
+
+  onLogOutput(event: { run: Run; level: "stdout" | "stderr"; message: string }): void {
+    const timestamp = new Date().toISOString();
+    const entry = {
+      runId: event.run.id,
+      signalName: event.run.signalName,
+      level: event.level,
+      message: event.message,
+      timestamp,
+    };
+    this.logBuffer?.add(entry);
+    this.logStore?.add(entry);
+    this.emit("log:output", entry);
+  }
+}
+
+export class StationBroadcastSubscriber implements BroadcastSubscriber {
+  private broadcastMetaMap = new Map<string, BroadcastMeta>();
+  private sseHub?: SSEHub;
+
+  constructor(private hub: WebSocketHub) {}
+
+  /** Attach an SSE hub so events are also pushed to SSE clients. */
+  setSSEHub(sseHub: SSEHub): void {
+    this.sseHub = sseHub;
+  }
+
+  private emit(type: string, data: Record<string, unknown>): void {
+    const event = { type, timestamp: new Date().toISOString(), data };
+    this.hub.broadcast(event);
+    this.sseHub?.broadcast(event);
+  }
+
+  getBroadcastMeta(name: string): BroadcastMeta | undefined {
+    return this.broadcastMetaMap.get(name);
+  }
+
+  getAllBroadcastMeta(): BroadcastMeta[] {
+    return [...this.broadcastMetaMap.values()];
+  }
+
+  onBroadcastDiscovered(event: { broadcastName: string; filePath: string }): void {
+    this.emit("broadcast:discovered", event);
+
+    import(event.filePath).then((mod) => {
+      for (const value of Object.values(mod)) {
+        if (isBroadcast(value) && value.name === event.broadcastName) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const bc = value as any;
+          this.broadcastMetaMap.set(event.broadcastName, {
+            name: bc.name,
+            filePath: event.filePath,
+            nodes: bc.nodes.map((n: { name: string; signalName: string; dependsOn: readonly string[] }) => ({
+              name: n.name,
+              signalName: n.signalName,
+              dependsOn: [...n.dependsOn],
+            })),
+            failurePolicy: bc.failurePolicy,
+            timeout: bc.timeout ?? null,
+            interval: bc.interval ?? null,
+          });
+          break;
+        }
+      }
+    }).catch(() => {});
+  }
+
+  onBroadcastQueued(event: { broadcastRun: BroadcastRun }): void {
+    this.emit("broadcast:queued", { broadcastRun: serializeBroadcastRun(event.broadcastRun) });
+  }
+
+  onBroadcastStarted(event: { broadcastRun: BroadcastRun }): void {
+    this.emit("broadcast:started", { broadcastRun: serializeBroadcastRun(event.broadcastRun) });
+  }
+
+  onBroadcastCompleted(event: { broadcastRun: BroadcastRun }): void {
+    this.emit("broadcast:completed", { broadcastRun: serializeBroadcastRun(event.broadcastRun) });
+  }
+
+  onBroadcastFailed(event: { broadcastRun: BroadcastRun; error: string }): void {
+    this.emit("broadcast:failed", {
+      broadcastRun: serializeBroadcastRun(event.broadcastRun),
+      error: event.error,
+    });
+  }
+
+  onBroadcastCancelled(event: { broadcastRun: BroadcastRun }): void {
+    this.emit("broadcast:cancelled", { broadcastRun: serializeBroadcastRun(event.broadcastRun) });
+  }
+
+  onNodeTriggered(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun }): void {
+    this.emit("node:triggered", {
+      broadcastRun: serializeBroadcastRun(event.broadcastRun),
+      nodeRun: serializeNodeRun(event.nodeRun),
+    });
+  }
+
+  onNodeCompleted(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun }): void {
+    this.emit("node:completed", {
+      broadcastRun: serializeBroadcastRun(event.broadcastRun),
+      nodeRun: serializeNodeRun(event.nodeRun),
+    });
+  }
+
+  onNodeFailed(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun; error: string }): void {
+    this.emit("node:failed", {
+      broadcastRun: serializeBroadcastRun(event.broadcastRun),
+      nodeRun: serializeNodeRun(event.nodeRun),
+      error: event.error,
+    });
+  }
+
+  onNodeSkipped(event: { broadcastRun: BroadcastRun; nodeRun: BroadcastNodeRun; reason: string }): void {
+    this.emit("node:skipped", {
+      broadcastRun: serializeBroadcastRun(event.broadcastRun),
+      nodeRun: serializeNodeRun(event.nodeRun),
+      reason: event.reason,
+    });
+  }
+}

package/src/server/ws.ts

@@ -0,0 +1,44 @@
+import { WebSocketServer, WebSocket } from "ws";
+import type { Server } from "node:http";
+
+export interface StationEvent {
+  type: string;
+  timestamp: string;
+  data: Record<string, unknown>;
+}
+
+export class WebSocketHub {
+  private wss: WebSocketServer | null = null;
+  private clients = new Set<WebSocket>();
+
+  attach(server: Server): void {
+    this.wss = new WebSocketServer({ server, path: "/api/events" });
+
+    this.wss.on("connection", (ws) => {
+      this.clients.add(ws);
+      ws.on("close", () => {
+        this.clients.delete(ws);
+      });
+      ws.on("error", () => {
+        this.clients.delete(ws);
+      });
+    });
+  }
+
+  get clientCount(): number {
+    return this.clients.size;
+  }
+
+  broadcast(event: StationEvent): void {
+    const payload = JSON.stringify(event);
+    for (const ws of this.clients) {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(payload);
+      }
+    }
+  }
+
+  close(): void {
+    this.wss?.close();
+  }
+}

package/station.config.example.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "station-kit";
+// import { SqliteAdapter } from "station-adapter-sqlite";
+// import { BroadcastSqliteAdapter } from "station-adapter-sqlite/broadcast";
+
+export default defineConfig({
+  port: 4400,
+  signalsDir: "./signals",
+  // broadcastsDir: "./broadcasts",
+
+  // Uncomment to use SQLite for persistent storage:
+  // adapter: new SqliteAdapter({ dbPath: "./jobs.db" }),
+  // broadcastAdapter: new BroadcastSqliteAdapter({ dbPath: "./jobs.db" }),
+
+  // Set to false for read-only mode (observe existing adapter data without running signals):
+  // runRunners: false,
+});

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "jsx": "preserve",
+    "noUnusedLocals": false,
+    "noUnusedParameters": false
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "src/app", ".next"]
+}

package/tsconfig.next.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "noEmit": true,
+    "incremental": true,
+    "allowJs": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["src/app", "next-env.d.ts", ".next/types/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}