airaknit 1.1.2-rc.9

package/src/server/journey-verification.ts

@@ -0,0 +1,195 @@
+export type JourneyRouteExpectation =
+  | { kind: "exact"; value: string }
+  | { kind: "prefix"; value: string }
+
+export interface JourneyStageSpec {
+  id: string
+  label: string
+  owners: readonly string[]
+  route: JourneyRouteExpectation
+  requiredUiIds: readonly string[]
+  expectedText: readonly string[]
+}
+
+export interface JourneySpec {
+  id: string
+  label: string
+  stages: readonly JourneyStageSpec[]
+  persistenceChecks: boolean
+}
+
+export interface StageProbeResult {
+  missing: string[]
+  c3ByUiId: Record<string, string | null>
+  textByUiId: Record<string, string | null>
+}
+
+export type JourneyStageInventory = JourneyStageSpec
+export type JourneyDefinition = JourneySpec
+
+const HOME_READY_STAGE: JourneyStageSpec = {
+  id: "home.ready",
+  label: "Homepage connected with a visible project overview",
+  owners: ["c3-117"],
+  route: { kind: "exact", value: "/" },
+  requiredUiIds: [
+    "home.page",
+    "home.header",
+    "home.workspace-grid",
+    "home.project-card",
+    "home.project-overview",
+    "home.project-primary.action",
+    "home.project-secondary.action",
+  ],
+  expectedText: [
+    "Workspaces",
+    "Project Overview",
+    "Start First Task",
+  ],
+}
+
+const CHAT_READY_STAGE: JourneyStageSpec = {
+  id: "chat.ready",
+  label: "Chat shell rendered after starting a fresh task",
+  owners: ["c3-110", "c3-111", "c3-112"],
+  route: { kind: "prefix", value: "/chat/" },
+  requiredUiIds: [
+    "chat.page",
+    "chat.navbar",
+    "transcript.message-list",
+    "chat.composer",
+  ],
+  expectedText: [],
+}
+
+const FORK_DIALOG_STAGE: JourneyStageSpec = {
+  id: "fork-dialog.open",
+  label: "Fork session dialog opened from the chat navbar",
+  owners: ["c3-110"],
+  route: { kind: "prefix", value: "/chat/" },
+  requiredUiIds: [
+    "chat.fork-session.dialog",
+    "chat.fork-session.context.input",
+    "chat.fork-session.submit.action",
+    "chat.fork-session.cancel.action",
+    "chat.fork-session.preset.action",
+  ],
+  expectedText: [],
+}
+
+const MERGE_DIALOG_STAGE: JourneyStageSpec = {
+  id: "merge-dialog.open",
+  label: "Merge session dialog opened from the chat navbar",
+  owners: ["c3-110"],
+  route: { kind: "prefix", value: "/chat/" },
+  requiredUiIds: [
+    "chat.merge-session.dialog",
+    "chat.merge-session.sessions.list",
+    "chat.merge-session.context.input",
+    "chat.merge-session.submit.action",
+    "chat.merge-session.cancel.action",
+  ],
+  expectedText: [],
+}
+
+export const HOME_TO_NEW_CHAT_JOURNEY: JourneySpec = {
+  id: "homepage-to-new-chat",
+  label: "Homepage project overview -> Start First Task -> chat shell",
+  stages: [HOME_READY_STAGE, CHAT_READY_STAGE],
+  persistenceChecks: true,
+}
+
+export const HOME_TO_FORK_DIALOG_JOURNEY: JourneySpec = {
+  id: "homepage-to-fork-dialog",
+  label: "Homepage project overview -> Start First Task -> fork dialog",
+  stages: [HOME_READY_STAGE, CHAT_READY_STAGE, FORK_DIALOG_STAGE],
+  persistenceChecks: true,
+}
+
+export const HOME_TO_MERGE_DIALOG_JOURNEY: JourneySpec = {
+  id: "homepage-to-merge-dialog",
+  label: "Homepage project overview -> Start First Task -> merge dialog",
+  stages: [HOME_READY_STAGE, CHAT_READY_STAGE, MERGE_DIALOG_STAGE],
+  persistenceChecks: true,
+}
+
+export function matchesJourneyRoute(pathname: string, expectation: JourneyRouteExpectation): boolean {
+  if (expectation.kind === "exact") {
+    return pathname === expectation.value
+  }
+
+  return pathname.startsWith(expectation.value)
+}
+
+export function buildStageProbeScript(stage: JourneyStageSpec): string {
+  const uiIds = JSON.stringify([...stage.requiredUiIds])
+
+  return `(() => {
+    const uiIds = ${uiIds};
+    const textByUiId = {};
+    const c3ByUiId = {};
+    const missing = [];
+
+    for (const uiId of uiIds) {
+      const selector = '[data-ui-id="' + uiId + '"]';
+      const element = document.querySelector(selector);
+      if (!element) {
+        missing.push(uiId);
+        c3ByUiId[uiId] = null;
+        textByUiId[uiId] = null;
+        continue;
+      }
+
+      c3ByUiId[uiId] = element.getAttribute("data-ui-c3");
+      textByUiId[uiId] = element.textContent ? element.textContent.trim() : "";
+    }
+
+    return { missing, c3ByUiId, textByUiId };
+  })()`
+}
+
+export function getJourneyStage(id: JourneyStageSpec["id"]): JourneyStageSpec {
+  const stage = [
+    ...HOME_TO_NEW_CHAT_JOURNEY.stages,
+    ...HOME_TO_FORK_DIALOG_JOURNEY.stages,
+    ...HOME_TO_MERGE_DIALOG_JOURNEY.stages,
+  ].find((candidate) => candidate.id === id)
+  if (!stage) {
+    throw new Error(`Unknown journey stage: ${id}`)
+  }
+
+  return structuredClone(stage)
+}
+
+export function getJourneySpec(id: string): JourneySpec {
+  switch (id) {
+    case HOME_TO_NEW_CHAT_JOURNEY.id:
+      return structuredClone(HOME_TO_NEW_CHAT_JOURNEY)
+    case HOME_TO_FORK_DIALOG_JOURNEY.id:
+      return structuredClone(HOME_TO_FORK_DIALOG_JOURNEY)
+    case HOME_TO_MERGE_DIALOG_JOURNEY.id:
+      return structuredClone(HOME_TO_MERGE_DIALOG_JOURNEY)
+    default:
+      throw new Error(`Unknown journey: ${id}`)
+  }
+}
+
+export function getStageVerificationErrors(
+  observed: { url: string; uiIds: string[] },
+  stage: JourneyStageSpec,
+): string[] {
+  const errors: string[] = []
+  const pathname = new URL(observed.url).pathname
+
+  if (!matchesJourneyRoute(pathname, stage.route)) {
+    errors.push(`expected route ${stage.route.kind} ${stage.route.value}, got ${pathname}`)
+  }
+
+  for (const uiId of stage.requiredUiIds) {
+    if (!observed.uiIds.includes(uiId)) {
+      errors.push(`missing ui id ${uiId}`)
+    }
+  }
+
+  return errors
+}

package/src/server/machine-name.ts

@@ -0,0 +1,22 @@
+import { hostname } from "node:os"
+import process from "node:process"
+import { spawnSync } from "node:child_process"
+
+function runAndRead(command: string, args: string[]) {
+  const result = spawnSync(command, args, { encoding: "utf8" })
+  if (result.status !== 0) return null
+  const value = result.stdout.trim()
+  return value || null
+}
+
+export function getMachineDisplayName() {
+  if (process.platform === "darwin") {
+    const computerName = runAndRead("scutil", ["--get", "ComputerName"])
+    if (computerName) {
+      return computerName
+    }
+  }
+
+  const rawHostname = hostname().trim()
+  return rawHostname.replace(/\.local$|\.lan$/i, "") || "This Machine"
+}

package/src/server/nats-auth.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, describe, test, expect } from "bun:test"
+import { NatsServer } from "@lagz0ne/nats-embedded"
+import { connect, type NatsConnection } from "@nats-io/transport-node"
+import { generateAuthToken } from "./nats-auth"
+
+let server: NatsServer | null = null
+let nc: NatsConnection | null = null
+
+afterEach(async () => {
+  if (nc) {
+    await nc.drain()
+    nc = null
+  }
+  if (server) {
+    await server.stop()
+    server = null
+  }
+})
+
+describe("generateAuthToken", () => {
+  test("returns a non-empty string", () => {
+    const token = generateAuthToken()
+    expect(typeof token).toBe("string")
+    expect(token.length).toBeGreaterThan(0)
+  })
+
+  test("produces unique tokens on each call", () => {
+    const tokens = new Set(Array.from({ length: 100 }, () => generateAuthToken()))
+    expect(tokens.size).toBe(100)
+  })
+
+  test("token has sufficient entropy (>= 32 chars)", () => {
+    const token = generateAuthToken()
+    expect(token.length).toBeGreaterThanOrEqual(32)
+  })
+})
+
+describe("NATS token auth integration", () => {
+  test("authenticated client connects successfully", async () => {
+    const token = generateAuthToken()
+    server = await NatsServer.start({ token })
+    nc = await connect({ servers: server.url, token })
+
+    // Verify connection works by publishing + subscribing
+    const received: string[] = []
+    const sub = nc.subscribe("test.auth")
+    void (async () => {
+      for await (const msg of sub) {
+        received.push(new TextDecoder().decode(msg.data))
+        sub.unsubscribe()
+      }
+    })()
+
+    nc.publish("test.auth", new TextEncoder().encode("hello"))
+    await nc.flush()
+    // Give subscription a moment to process
+    await new Promise((resolve) => setTimeout(resolve, 50))
+    expect(received).toContain("hello")
+  })
+
+  test("unauthenticated client is rejected", async () => {
+    const token = generateAuthToken()
+    server = await NatsServer.start({ token })
+
+    try {
+      nc = await connect({ servers: server.url })
+      // If connection somehow succeeds, verify it can't operate
+      await nc.flush()
+      // Should not reach here
+      expect(true).toBe(false)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      expect(message.toLowerCase()).toMatch(/authorization|auth|denied|closed/)
+      nc = null
+    }
+  })
+
+  test("client with wrong token is rejected", async () => {
+    const token = generateAuthToken()
+    server = await NatsServer.start({ token })
+
+    try {
+      nc = await connect({ servers: server.url, token: "wrong-token" })
+      await nc.flush()
+      expect(true).toBe(false)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      expect(message.toLowerCase()).toMatch(/authorization|auth|denied|closed/)
+      nc = null
+    }
+  })
+})

package/src/server/nats-auth.ts

@@ -0,0 +1,6 @@
+import { randomBytes } from "node:crypto"
+
+/** Generates a URL-safe base64 auth token for NATS server + client connections. */
+export function generateAuthToken(): string {
+  return randomBytes(32).toString("base64url")
+}

package/src/server/nats-bind-guard.test.ts

@@ -0,0 +1,71 @@
+import { describe, test, expect } from "bun:test"
+import { requiresCalloutForBind } from "./nats-bind-guard"
+
+describe("requiresCalloutForBind", () => {
+  // ── Allowed combinations ────────────────────────────────────────────────────
+
+  test("loopback 127.0.0.1 + token → ok (dev default)", () => {
+    expect(requiresCalloutForBind("127.0.0.1", "token")).toEqual({ ok: true })
+  })
+
+  test("loopback localhost + token → ok", () => {
+    expect(requiresCalloutForBind("localhost", "token")).toEqual({ ok: true })
+  })
+
+  test("loopback ::1 + token → ok", () => {
+    expect(requiresCalloutForBind("::1", "token")).toEqual({ ok: true })
+  })
+
+  test("loopback 127.0.0.1 + callout → ok", () => {
+    expect(requiresCalloutForBind("127.0.0.1", "callout")).toEqual({ ok: true })
+  })
+
+  test("wide 0.0.0.0 + callout → ok (tailnet path)", () => {
+    expect(requiresCalloutForBind("0.0.0.0", "callout")).toEqual({ ok: true })
+  })
+
+  test("tailnet IP + callout → ok", () => {
+    expect(requiresCalloutForBind("100.64.1.1", "callout")).toEqual({ ok: true })
+  })
+
+  // ── Disallowed combinations ─────────────────────────────────────────────────
+
+  test("wide 0.0.0.0 + token → refused with reason", () => {
+    const result = requiresCalloutForBind("0.0.0.0", "token")
+    expect(result.ok).toBe(false)
+    expect(result.reason).toMatch(/Refusing to bind NATS to 0\.0\.0\.0 in token mode/)
+    expect(result.reason).toMatch(/NATS_AUTH_MODE=callout/)
+  })
+
+  test("tailnet IP + token → refused with reason", () => {
+    const result = requiresCalloutForBind("100.64.1.1", "token")
+    expect(result.ok).toBe(false)
+    expect(result.reason).toMatch(/Refusing to bind NATS to 100\.64\.1\.1 in token mode/)
+  })
+
+  test("arbitrary private IP + token → refused", () => {
+    const result = requiresCalloutForBind("192.168.1.10", "token")
+    expect(result.ok).toBe(false)
+  })
+
+  test("reason message is non-empty when refused", () => {
+    const result = requiresCalloutForBind("10.0.0.1", "token")
+    expect(result.ok).toBe(false)
+    expect(typeof result.reason).toBe("string")
+    expect((result.reason ?? "").length).toBeGreaterThan(0)
+  })
+
+  // ── Case-insensitive loopback match ─────────────────────────────────────────
+
+  test("LOCALHOST (uppercase) + token → ok (case-insensitive loopback)", () => {
+    expect(requiresCalloutForBind("LOCALHOST", "token")).toEqual({ ok: true })
+  })
+
+  test("Localhost (mixed-case) + token → ok", () => {
+    expect(requiresCalloutForBind("Localhost", "token")).toEqual({ ok: true })
+  })
+
+  test("  localhost  (whitespace) + token → ok", () => {
+    expect(requiresCalloutForBind("  localhost  ", "token")).toEqual({ ok: true })
+  })
+})

package/src/server/nats-bind-guard.ts

@@ -0,0 +1,42 @@
+/**
+ * Guard: a wide (non-loopback) NATS bind is only permitted in callout mode.
+ *
+ * Decision 0007: never expose a shared-token bus on the tailnet.
+ * Loopback + token stays allowed (dev default).
+ * Non-loopback + callout is allowed (tailnet path); logs a note.
+ * Non-loopback + token is refused at startup with a fatal error message.
+ */
+
+/** The set of host values that are considered loopback/local-only. */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"])
+
+export type AuthMode = "callout" | "token"
+
+export interface BindGuardResult {
+  ok: boolean
+  /** Present only when ok is false. */
+  reason?: string
+}
+
+/**
+ * Pure predicate — no side effects.
+ *
+ * Returns `{ ok: false, reason }` when binding a non-loopback host in token
+ * mode (decision 0007), `{ ok: true }` otherwise.
+ */
+export function requiresCalloutForBind(
+  host: string,
+  authMode: AuthMode,
+): BindGuardResult {
+  const isLoopback = LOOPBACK_HOSTS.has(host.trim().toLowerCase())
+  if (!isLoopback && authMode !== "callout") {
+    return {
+      ok: false,
+      reason:
+        `Refusing to bind NATS to ${host} in token mode — ` +
+        `a shared-token bus must not be exposed beyond loopback; ` +
+        `set NATS_AUTH_MODE=callout`,
+    }
+  }
+  return { ok: true }
+}

package/src/server/nats-bridge.test.ts

@@ -0,0 +1,141 @@
+import { afterEach, describe, test, expect } from "bun:test"
+import { NatsBridge } from "./nats-bridge"
+import { connect } from "@nats-io/transport-node"
+
+const decoder = new TextDecoder()
+let bridge: NatsBridge | null = null
+
+afterEach(async () => {
+  if (bridge) {
+    await bridge.dispose()
+    bridge = null
+  }
+})
+
+describe("NatsBridge", () => {
+  test("create() starts NATS server and connects", async () => {
+    bridge = await NatsBridge.create()
+    expect(bridge.natsUrl).toMatch(/^nats:\/\/127\.0\.0\.1:\d+$/)
+    expect(bridge.natsWsUrl).toMatch(/^ws:\/\/127\.0\.0\.1:\d+\/?$/)
+    expect(bridge.natsWsPort).toBeGreaterThan(0)
+  })
+
+  test("create() can bind on all interfaces while advertising localhost URLs", async () => {
+    bridge = await NatsBridge.create({
+      bindHost: "0.0.0.0",
+      advertisedHost: "127.0.0.1",
+    })
+
+    expect(bridge.natsUrl).toMatch(/^nats:\/\/127\.0\.0\.1:\d+$/)
+    expect(bridge.natsWsUrl).toMatch(/^ws:\/\/127\.0\.0\.1:\d+\/?$/)
+
+    const testClient = await connect({ servers: bridge.natsUrl })
+    await testClient.drain()
+  })
+
+  test("publish() delivers message to subscriber", async () => {
+    bridge = await NatsBridge.create()
+
+    // Connect a test subscriber
+    const testClient = await connect({ servers: bridge.natsUrl })
+    const sub = testClient.subscribe("test.subject")
+    await testClient.flush()
+
+    // Publish via bridge
+    bridge.publish("test.subject", { hello: "world" })
+
+    // Receive message
+    const msg = await (async () => {
+      for await (const m of sub) {
+        return JSON.parse(decoder.decode(m.data))
+      }
+    })()
+
+    expect(msg).toEqual({ hello: "world" })
+
+    await testClient.drain()
+  })
+
+  test("publish() handles multiple subjects", async () => {
+    bridge = await NatsBridge.create()
+
+    const testClient = await connect({ servers: bridge.natsUrl })
+    const received: Array<{ subject: string; data: unknown }> = []
+
+    const sub1 = testClient.subscribe("runtime.snap.sidebar")
+    const sub2 = testClient.subscribe("runtime.snap.chat.abc")
+
+    // Collect in background
+    const collect = async (sub: AsyncIterable<{ data: Uint8Array; subject: string }>, count: number) => {
+      let n = 0
+      for await (const m of sub) {
+        received.push({ subject: m.subject, data: JSON.parse(decoder.decode(m.data)) })
+        if (++n >= count) break
+      }
+    }
+
+    const p1 = collect(sub1, 1)
+    const p2 = collect(sub2, 1)
+
+    await testClient.flush()
+
+    bridge.publish("runtime.snap.sidebar", { type: "sidebar" })
+    bridge.publish("runtime.snap.chat.abc", { type: "chat", chatId: "abc" })
+
+    await Promise.all([p1, p2])
+
+    expect(received).toHaveLength(2)
+    expect(received.find((r) => r.subject === "runtime.snap.sidebar")?.data).toEqual({ type: "sidebar" })
+    expect(received.find((r) => r.subject === "runtime.snap.chat.abc")?.data).toEqual({ type: "chat", chatId: "abc" })
+
+    await testClient.drain()
+  })
+
+  test("dispose() cleanly stops NATS server", async () => {
+    bridge = await NatsBridge.create()
+    const url = bridge.natsUrl
+
+    await bridge.dispose()
+    bridge = null
+
+    // Connection to stopped server should fail
+    try {
+      await connect({ servers: url, maxReconnectAttempts: 0, reconnect: false })
+      expect(true).toBe(false) // should not reach
+    } catch (error) {
+      expect(error).toBeDefined()
+    }
+  })
+
+  test("wildcard subscription receives matching messages", async () => {
+    bridge = await NatsBridge.create()
+
+    const testClient = await connect({ servers: bridge.natsUrl })
+    const received: string[] = []
+
+    const sub = testClient.subscribe("runtime.snap.>")
+
+    const collect = async (count: number) => {
+      let n = 0
+      for await (const m of sub) {
+        received.push(m.subject)
+        if (++n >= count) break
+      }
+    }
+
+    const p = collect(3)
+    await testClient.flush()
+
+    bridge.publish("runtime.snap.sidebar", {})
+    bridge.publish("runtime.snap.update", {})
+    bridge.publish("runtime.snap.chat.xyz", {})
+
+    await p
+
+    expect(received).toContain("runtime.snap.sidebar")
+    expect(received).toContain("runtime.snap.update")
+    expect(received).toContain("runtime.snap.chat.xyz")
+
+    await testClient.drain()
+  })
+})

package/src/server/nats-bridge.ts

@@ -0,0 +1,111 @@
+import { NatsServer } from "@lagz0ne/nats-embedded"
+import { connect, type NatsConnection } from "@nats-io/transport-node"
+import { LOG_PREFIX } from "../shared/branding"
+
+const encoder = new TextEncoder()
+
+function tokenOption(token?: string): { token: string } | undefined {
+  return token ? { token } : undefined
+}
+
+export interface CreateNatsBridgeOptions {
+  token?: string
+  bindHost?: string
+  advertisedHost?: string
+}
+
+function normalizeAdvertisedHost(bindHost: string, advertisedHost?: string): string {
+  if (advertisedHost) return advertisedHost
+  return bindHost === "0.0.0.0" ? "127.0.0.1" : bindHost
+}
+
+function rewriteUrlHost(rawUrl: string, host: string): string {
+  const url = new URL(rawUrl)
+  url.hostname = host
+  return url.toString().replace(/\/$/, "")
+}
+
+export class NatsBridge {
+  readonly natsUrl: string
+  readonly natsWsUrl: string
+  readonly natsWsPort: number
+  readonly authToken: string | undefined
+
+  private readonly server: NatsServer
+  readonly nc: NatsConnection
+  private disposed = false
+
+  private constructor(
+    server: NatsServer,
+    connection: NatsConnection,
+    advertisedNatsUrl: string,
+    advertisedWsUrl: string,
+    token?: string
+  ) {
+    this.server = server
+    this.nc = connection
+    this.natsUrl = advertisedNatsUrl
+    this.natsWsUrl = advertisedWsUrl
+    this.natsWsPort = server.wsPort!
+    this.authToken = token
+  }
+
+  static async create(options: CreateNatsBridgeOptions = {}): Promise<NatsBridge> {
+    const bindHost = options.bindHost ?? "127.0.0.1"
+    const advertisedHost = normalizeAdvertisedHost(bindHost, options.advertisedHost)
+    const server = await NatsServer.start({
+      host: bindHost,
+      websocket: true,
+      jetstream: true,
+      ...tokenOption(options.token),
+    })
+
+    if (!server.wsUrl || !server.wsPort) {
+      await server.stop()
+      throw new Error("NATS server started without WebSocket support")
+    }
+
+    const connection = await connect({
+      servers: rewriteUrlHost(server.url, advertisedHost),
+      ...tokenOption(options.token),
+    })
+
+    const advertisedNatsUrl = rewriteUrlHost(server.url, advertisedHost)
+    const advertisedWsUrl = rewriteUrlHost(server.wsUrl, advertisedHost)
+
+    console.warn(LOG_PREFIX, `NATS bridge started — TCP: ${advertisedNatsUrl}, WS: ${advertisedWsUrl}`)
+
+    const bridge = new NatsBridge(server, connection, advertisedNatsUrl, advertisedWsUrl, options.token)
+
+    void server.exited.then((code) => {
+      if (!bridge.disposed) {
+        console.warn(LOG_PREFIX, `NATS server exited unexpectedly with code ${code}`)
+      }
+    })
+
+    return bridge
+  }
+
+  publish(subject: string, data: unknown): void {
+    if (this.disposed) return
+    try {
+      this.nc.publish(subject, encoder.encode(JSON.stringify(data)))
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.warn(LOG_PREFIX, `NATS publish failed on ${subject}: ${message}`)
+    }
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return
+    this.disposed = true
+    try {
+      await this.nc.drain()
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.warn(LOG_PREFIX, `NATS connection drain failed: ${message}`)
+    }
+    await this.server.stop()
+    console.warn(LOG_PREFIX, "NATS bridge stopped")
+  }
+}