@linzumi/cli 0.0.1-beta → 0.0.2-beta

package/src/oauth.ts

@@ -0,0 +1,294 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Implements the runner-side browser authorization flow used
+  when the operator does not pass a pre-existing Kandan token.
+*/
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+
+export type LocalRunnerOAuthOptions = {
+  readonly kandanUrl: string;
+  readonly workspaceSlug?: string | undefined;
+  readonly channelSlug?: string | undefined;
+  readonly callbackHost?: string | undefined;
+  readonly openAuthorizationUrl?: ((url: string) => Promise<void> | void) | undefined;
+};
+
+export type LocalRunnerOAuthToken = {
+  readonly accessToken: string;
+  readonly expiresInSeconds?: number | undefined;
+};
+
+export async function acquireLocalRunnerToken(
+  options: LocalRunnerOAuthOptions,
+): Promise<string> {
+  const token = await acquireLocalRunnerTokenDetails(options);
+  return token.accessToken;
+}
+
+export async function acquireLocalRunnerTokenDetails(
+  options: LocalRunnerOAuthOptions,
+): Promise<LocalRunnerOAuthToken> {
+  const httpBaseUrl = kandanHttpBaseUrl(options.kandanUrl);
+  const state = randomBytes(18).toString("base64url");
+  const callback = await startCallbackServer({
+    host: oauthCallbackHost(options.kandanUrl, options.callbackHost),
+  });
+  const authorizeUrl = authorizationUrl({
+    httpBaseUrl,
+    redirectUri: callback.redirectUri,
+    state,
+    workspaceSlug: options.workspaceSlug,
+    channelSlug: options.channelSlug,
+  });
+
+  process.stderr.write(`Authorize the local Codex runner:\n${authorizeUrl}\n`);
+
+  try {
+    await (options.openAuthorizationUrl ?? openBrowser)(authorizeUrl);
+    const result = await callback.waitForCallback();
+
+    if (result.state !== state) {
+      throw new Error("local runner OAuth state mismatch");
+    }
+
+    return await exchangeCodeForToken({
+      httpBaseUrl,
+      code: result.code,
+      redirectUri: callback.redirectUri,
+    });
+  } finally {
+    callback.close();
+  }
+}
+
+export async function validateLocalRunnerToken(args: {
+  readonly kandanUrl: string;
+  readonly accessToken: string;
+  readonly workspaceSlug?: string | undefined;
+  readonly channelSlug?: string | undefined;
+}): Promise<boolean> {
+  const url = new URL(
+    "/api/v2/local-codex-runner/oauth/validate",
+    kandanHttpBaseUrl(args.kandanUrl),
+  );
+
+  if (args.workspaceSlug !== undefined) {
+    url.searchParams.set("workspace", args.workspaceSlug);
+  }
+
+  if (args.channelSlug !== undefined) {
+    url.searchParams.set("channel", args.channelSlug);
+  }
+
+  const response = await fetch(
+    url,
+    {
+      method: "GET",
+      headers: { authorization: `Bearer ${args.accessToken}` },
+    },
+  );
+
+  switch (response.status) {
+    case 200: {
+      const body: unknown = await response.json();
+      return typeof body === "object" && body !== null && "ok" in body && body.ok === true;
+    }
+    case 401:
+    case 403:
+      return false;
+    default:
+      throw new Error(`local runner auth validation failed with HTTP ${response.status}`);
+  }
+}
+
+export function kandanHttpBaseUrl(kandanUrl: string): string {
+  const parsed = new URL(kandanUrl);
+
+  switch (parsed.protocol) {
+    case "ws:":
+      parsed.protocol = "http:";
+      break;
+    case "wss:":
+      parsed.protocol = "https:";
+      break;
+    case "http:":
+    case "https:":
+      break;
+    default:
+      throw new Error("--kandan-url must be ws://, wss://, http://, or https://");
+  }
+
+  parsed.pathname = "";
+  parsed.search = "";
+  parsed.hash = "";
+  return parsed.toString().replace(/\/$/, "");
+}
+
+export function oauthCallbackHost(
+  kandanUrl: string,
+  explicitHost?: string | undefined,
+): string {
+  const normalizedExplicitHost = explicitHost?.trim();
+
+  if (normalizedExplicitHost !== undefined && normalizedExplicitHost !== "") {
+    return normalizedExplicitHost;
+  }
+
+  const host = new URL(kandanUrl).hostname.trim();
+
+  return isPrivateCallbackHost(host) && host !== "localhost" ? host : "127.0.0.1";
+}
+
+function isPrivateCallbackHost(host: string): boolean {
+  const octets = host.split(".").map((part) => Number.parseInt(part, 10));
+
+  if (
+    octets.length !== 4 ||
+    octets.some((part) => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
+    return host === "localhost";
+  }
+
+  const [a, b] = octets;
+
+  if (a === undefined || b === undefined) {
+    return false;
+  }
+
+  return (
+    a === 10 ||
+    a === 127 ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 169 && b === 254) ||
+    (a === 100 && b >= 64 && b <= 127)
+  );
+}
+
+function authorizationUrl(args: {
+  readonly httpBaseUrl: string;
+  readonly redirectUri: string;
+  readonly state: string;
+  readonly workspaceSlug?: string | undefined;
+  readonly channelSlug?: string | undefined;
+}): string {
+  const url = new URL("/api/v2/local-codex-runner/oauth/authorize", args.httpBaseUrl);
+  url.searchParams.set("redirect_uri", args.redirectUri);
+  url.searchParams.set("state", args.state);
+
+  if (args.workspaceSlug !== undefined) {
+    url.searchParams.set("workspace", args.workspaceSlug);
+  }
+
+  if (args.channelSlug !== undefined) {
+    url.searchParams.set("channel", args.channelSlug);
+  }
+
+  return url.toString();
+}
+
+async function exchangeCodeForToken(args: {
+  readonly httpBaseUrl: string;
+  readonly code: string;
+  readonly redirectUri: string;
+}): Promise<LocalRunnerOAuthToken> {
+  const response = await fetch(
+    new URL("/api/v2/local-codex-runner/oauth/token", args.httpBaseUrl),
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        code: args.code,
+        redirect_uri: args.redirectUri,
+      }),
+    },
+  );
+  const body: unknown = await response.json();
+
+  if (!response.ok || typeof body !== "object" || body === null) {
+    throw new Error("local runner OAuth token exchange failed");
+  }
+
+  const token = "access_token" in body ? body.access_token : undefined;
+
+  if (typeof token !== "string" || token.trim() === "") {
+    throw new Error("local runner OAuth token response did not include access_token");
+  }
+
+  const expiresIn = "expires_in" in body ? body.expires_in : undefined;
+
+  return {
+    accessToken: token,
+    expiresInSeconds: typeof expiresIn === "number" ? expiresIn : undefined,
+  };
+}
+
+function startCallbackServer(args: {
+  readonly host: string;
+}): Promise<{
+  readonly redirectUri: string;
+  readonly waitForCallback: () => Promise<{ readonly code: string; readonly state: string }>;
+  readonly close: () => void;
+}> {
+  return new Promise((resolve) => {
+    let resolveCallback:
+      | ((value: { readonly code: string; readonly state: string }) => void)
+      | undefined;
+    const callbackPromise = new Promise<{ readonly code: string; readonly state: string }>(
+      (callbackResolve) => {
+        resolveCallback = callbackResolve;
+      },
+    );
+
+    const server = Bun.serve({
+      hostname: args.host,
+      port: 0,
+      fetch(request) {
+        const url = new URL(request.url);
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+
+        if (code === null || state === null || code.trim() === "" || state.trim() === "") {
+          return new Response("Missing local runner authorization code.", { status: 400 });
+        }
+
+        resolveCallback?.({ code, state });
+        return new Response("Kandan local Codex runner authorized. You can close this tab.", {
+          headers: { "content-type": "text/plain; charset=utf-8" },
+        });
+      },
+    });
+
+    resolve({
+      redirectUri: `http://${args.host}:${server.port}/callback`,
+      waitForCallback: () => callbackPromise,
+      close: () => {
+        server.stop(true);
+      },
+    });
+  });
+}
+
+function openBrowser(url: string): Promise<void> {
+  const command =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "cmd"
+        : "xdg-open";
+  const args =
+    process.platform === "win32"
+      ? ["/c", "start", "", url]
+      : [url];
+
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => resolve());
+    child.on("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
+}

package/src/phoenix.ts

@@ -0,0 +1,335 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-plan.md
+  Relationship: Implements the spec's runner-to-Kandan Phoenix websocket
+  transport for structured runner events and server control pushes.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Exposes server-pushed chat events to the channel-bound runner
+  so Kandan thread replies can drive the local Codex session.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Treats the Kandan websocket as a reconnectable transport so
+  server restarts do not terminate the durable local Codex session.
+*/
+import {
+  type JsonObject,
+  type JsonValue,
+  type KandanControl,
+  type PhoenixFrame,
+  isJsonObject
+} from "./protocol";
+
+type PendingPush = {
+  readonly resolve: (payload: JsonValue) => void;
+  readonly reject: (error: Error) => void;
+};
+
+type JoinRegistration = {
+  readonly payload: () => JsonObject;
+};
+
+export type PhoenixClient = {
+  readonly join: (
+    topic: string,
+    payload: JsonObject,
+    options?: { readonly rejoinPayload?: (() => JsonObject) | undefined }
+  ) => Promise<JsonObject>;
+  readonly push: (topic: string, event: string, payload: JsonObject) => Promise<JsonValue>;
+  readonly onControl: (callback: (control: KandanControl) => void) => void;
+  readonly onEvent: (
+    callback: (topic: string, event: string, payload: JsonValue) => void
+  ) => void;
+  readonly onReconnect: (callback: () => void | Promise<void>) => void;
+  readonly close: () => void;
+};
+
+export function phoenixWebsocketUrl(baseUrl: string, token: string): string {
+  const parsed = new URL(baseUrl);
+  parsed.pathname = parsed.pathname.replace(/\/$/, "") + "/socket/websocket";
+  parsed.searchParams.set("token", token);
+  parsed.searchParams.set("vsn", "2.0.0");
+  return parsed.toString();
+}
+
+export async function connectPhoenixClient(
+  baseUrl: string,
+  token: string,
+  socketFactory: (url: string) => WebSocket = url => new WebSocket(url)
+): Promise<PhoenixClient> {
+  const pending = new Map<string, PendingPush>();
+  const joins = new Map<string, JoinRegistration>();
+  const controlCallbacks = new Set<(control: KandanControl) => void>();
+  const eventCallbacks = new Set<(topic: string, event: string, payload: JsonValue) => void>();
+  const reconnectCallbacks = new Set<() => void | Promise<void>>();
+  const state: {
+    nextRef: number;
+    websocket: WebSocket | undefined;
+    closed: boolean;
+    connected: boolean;
+    hasEverConnected: boolean;
+    connectionGeneration: number;
+    ready: Promise<void>;
+    resolveReady: (() => void) | undefined;
+    rejectReady: ((error: Error) => void) | undefined;
+    reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  } = {
+    nextRef: 1,
+    websocket: undefined,
+    closed: false,
+    connected: false,
+    hasEverConnected: false,
+    connectionGeneration: 0,
+    ready: Promise.resolve(),
+    resolveReady: undefined,
+    rejectReady: undefined,
+    reconnectTimer: undefined,
+  };
+  const rejectPending = (message: string) => {
+    const error = new Error(message);
+    pending.forEach(pendingPush => pendingPush.reject(error));
+    pending.clear();
+  };
+
+  const resetReady = () => {
+    state.ready = new Promise((resolve, reject) => {
+      state.resolveReady = resolve;
+      state.rejectReady = reject;
+    });
+  };
+
+  const handleMessage = (event: MessageEvent) => {
+    const frame = decodeFrame(String(event.data));
+    const [, ref, topic, name, payload] = frame;
+
+    if (ref !== null && (name === "phx_reply" || name === "phx_error")) {
+      const pendingPush = pending.get(ref);
+
+      if (pendingPush !== undefined) {
+        pending.delete(ref);
+
+        if (name === "phx_error") {
+          pendingPush.reject(new Error("phoenix push failed"));
+        } else {
+          pendingPush.resolve(payload);
+        }
+      }
+    }
+
+    if (topic.startsWith("local_runner:") && name === "control" && isKandanControl(payload)) {
+      controlCallbacks.forEach(callback => callback(payload));
+    }
+
+    if (ref === null && name !== "phx_reply" && name !== "phx_error") {
+      eventCallbacks.forEach(callback => callback(topic, name, payload));
+    }
+  };
+
+  const pushOnOpenSocket = (
+    topic: string,
+    event: string,
+    payload: JsonObject
+  ): Promise<JsonValue> => {
+    const websocket = state.websocket;
+
+    if (websocket === undefined || websocket.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error("phoenix websocket is not open"));
+    }
+
+    const ref = String(state.nextRef);
+    state.nextRef += 1;
+    const frame: PhoenixFrame = [null, ref, topic, event, payload];
+
+    return new Promise((resolve, reject) => {
+      pending.set(ref, { resolve, reject });
+      websocket.send(JSON.stringify(frame));
+    });
+  };
+
+  const replayJoins = async () => {
+    for (const [topic, registration] of joins) {
+      const reply = await pushOnOpenSocket(topic, "phx_join", registration.payload());
+
+      if (!isJoinReply(reply)) {
+        throw new Error(`phoenix rejoin failed for ${topic}`);
+      }
+    }
+  };
+
+  const scheduleReconnect = () => {
+    if (state.closed || state.reconnectTimer !== undefined) {
+      return;
+    }
+
+    resetReady();
+    state.reconnectTimer = setTimeout(() => {
+      state.reconnectTimer = undefined;
+      void openSocket();
+    }, 250);
+  };
+
+  const handleDisconnect = (message: string) => {
+    state.connected = false;
+    rejectPending(message);
+    scheduleReconnect();
+  };
+
+  const openSocket = async (): Promise<void> => {
+    if (state.closed) {
+      return;
+    }
+
+    const websocket = socketFactory(phoenixWebsocketUrl(baseUrl, token));
+    state.websocket = websocket;
+    websocket.addEventListener("message", handleMessage);
+    websocket.addEventListener(
+      "close",
+      () => {
+        if (state.websocket === websocket) {
+          handleDisconnect("phoenix websocket closed");
+        }
+      },
+      { once: true },
+    );
+    websocket.addEventListener(
+      "error",
+      () => {
+        if (state.websocket === websocket) {
+          handleDisconnect("phoenix websocket error");
+        }
+      },
+      { once: true },
+    );
+
+    try {
+      await waitForOpen(websocket);
+      state.connectionGeneration += 1;
+      await replayJoins();
+      state.connected = true;
+      state.hasEverConnected = true;
+      state.resolveReady?.();
+
+      if (state.connectionGeneration > 1) {
+        reconnectCallbacks.forEach(callback => {
+          void Promise.resolve(callback()).catch(() => undefined);
+        });
+      }
+    } catch (error) {
+      if (!state.closed) {
+        if (!state.hasEverConnected) {
+          state.rejectReady?.(error instanceof Error ? error : new Error(String(error)));
+        }
+        handleDisconnect("phoenix websocket reconnect failed");
+      }
+    }
+  };
+
+  resetReady();
+  void openSocket();
+  await state.ready;
+
+  const push = async (
+    topic: string,
+    event: string,
+    payload: JsonObject
+  ): Promise<JsonValue> => {
+    await state.ready;
+    return pushOnOpenSocket(topic, event, payload);
+  };
+
+  return {
+    join: async (topic, payload, options) => {
+      const reply = await push(topic, "phx_join", payload);
+
+      if (isJoinReply(reply)) {
+        joins.set(topic, { payload: options?.rejoinPayload ?? (() => payload) });
+        return reply.response;
+      }
+
+      throw new Error(`phoenix join failed: ${joinErrorMessage(reply)}`);
+    },
+    push,
+    onControl: callback => {
+      controlCallbacks.add(callback);
+    },
+    onEvent: callback => {
+      eventCallbacks.add(callback);
+    },
+    onReconnect: callback => {
+      reconnectCallbacks.add(callback);
+    },
+    close: () => {
+      state.closed = true;
+      if (state.reconnectTimer !== undefined) {
+        clearTimeout(state.reconnectTimer);
+      }
+      state.websocket?.close();
+      rejectPending("phoenix websocket closed");
+    }
+  };
+}
+
+export function encodeFrame(frame: PhoenixFrame): string {
+  return JSON.stringify(frame);
+}
+
+export function decodeFrame(text: string): PhoenixFrame {
+  const parsed = JSON.parse(text);
+
+  if (
+    Array.isArray(parsed) &&
+    parsed.length === 5 &&
+    (parsed[0] === null || typeof parsed[0] === "string") &&
+    (parsed[1] === null || typeof parsed[1] === "string") &&
+    typeof parsed[2] === "string" &&
+    typeof parsed[3] === "string"
+  ) {
+    return parsed as unknown as PhoenixFrame;
+  }
+
+  throw new Error("invalid Phoenix frame");
+}
+
+function isJoinReply(value: JsonValue): value is {
+  readonly status: "ok";
+  readonly response: JsonObject;
+} {
+  return (
+    isJsonObject(value) &&
+    value.status === "ok" &&
+    isJsonObject(value.response)
+  );
+}
+
+function joinErrorMessage(value: JsonValue): string {
+  if (!isJsonObject(value)) {
+    return "invalid reply";
+  }
+
+  const response = value.response;
+
+  if (isJsonObject(response) && typeof response.error === "string") {
+    return response.error;
+  }
+
+  if (typeof value.error === "string") {
+    return value.error;
+  }
+
+  return "unknown";
+}
+
+function isKandanControl(value: JsonValue): value is KandanControl {
+  return isJsonObject(value) && typeof value.type === "string";
+}
+
+function waitForOpen(websocket: WebSocket): Promise<void> {
+  return new Promise((resolve, reject) => {
+    websocket.addEventListener("open", () => resolve(), { once: true });
+    websocket.addEventListener("error", () => reject(new Error("websocket open failed")), {
+      once: true
+    });
+  });
+}