@linzumi/cli 0.0.20-beta → 0.0.22-beta

package/src/portForwardWatcher.ts

@@ -1,404 +0,0 @@
-/*
-- Date: 2026-04-26
-  Spec: plans/2026-04-26-local-runner-port-forward-approval.md
-  Relationship: Detects descendant listener ports for the local Codex runner so
-  Kandan can prompt the authorized listener user before exposing a local
-  service through the runner forward route.
-*/
-import { spawnSync } from "node:child_process";
-import { basename } from "node:path";
-
-export type ProcessRow = {
-  readonly pid: number;
-  readonly ppid: number;
-  readonly command: string;
-};
-
-export type ListenSocketRow = {
-  readonly pid: number;
-  readonly port: number;
-  readonly command: string;
-};
-
-export type PortForwardCandidate = {
-  readonly port: number;
-  readonly pid: number;
-  readonly command: string;
-  readonly cwd?: string | undefined;
-};
-
-export type PortForwardWatcher = {
-  readonly close: () => void;
-};
-
-export type PortForwardWatcherOptions = {
-  readonly rootPid?: number | undefined;
-  readonly intervalMs?: number | undefined;
-  readonly debounceMs?: number | undefined;
-  readonly scanProcesses?: (() => readonly ProcessRow[]) | undefined;
-  readonly scanListenSockets?: (() => readonly ListenSocketRow[]) | undefined;
-  readonly scanProcessCwds?: ((pids: readonly number[]) => ReadonlyMap<number, string>) | undefined;
-  readonly nowMs?: (() => number) | undefined;
-  readonly onCandidate: (candidate: PortForwardCandidate) => void | Promise<void>;
-  readonly onError?: ((error: Error) => void) | undefined;
-};
-
-const defaultIntervalMs = 2_000;
-const defaultDebounceMs = 750;
-
-export type ObservedPortForwardCandidate = {
-  readonly candidate: PortForwardCandidate;
-  readonly firstSeenAtMs: number;
-};
-
-export function startPortForwardWatcher(
-  options: PortForwardWatcherOptions,
-): PortForwardWatcher {
-  const rootPid = options.rootPid ?? process.pid;
-  const intervalMs = options.intervalMs ?? defaultIntervalMs;
-  const debounceMs = options.debounceMs ?? defaultDebounceMs;
-  const scanProcesses = options.scanProcesses ?? readProcessRows;
-  const scanListenSockets = options.scanListenSockets ?? readListenSocketRows;
-  const scanProcessCwds = options.scanProcessCwds ?? readProcessCwdRows;
-  const nowMs = options.nowMs ?? Date.now;
-  const candidateStabilityByPort = new Map<number, ObservedPortForwardCandidate>();
-  const emittedByPort = new Map<number, PortForwardCandidate>();
-  const inFlight = { value: false };
-
-  const scan = () => {
-    if (inFlight.value) {
-      return;
-    }
-
-    inFlight.value = true;
-    void Promise.resolve()
-      .then(async () => {
-        const descendants = descendantPidSet(scanProcesses(), rootPid);
-        const sockets = scanListenSockets();
-        const candidatePids = sockets
-          .filter(socket => descendants.has(socket.pid))
-          .map(socket => socket.pid);
-        const candidates = detectedForwardCandidates(
-          sockets,
-          descendants,
-          scanProcessCwds(candidatePids),
-        );
-        const stable = stableForwardCandidates(
-          candidateStabilityByPort,
-          candidates,
-          nowMs(),
-          debounceMs,
-        );
-        const changes = changedForwardCandidates(emittedByPort, stable.stableCandidates);
-        candidateStabilityByPort.clear();
-        emittedByPort.clear();
-
-        for (const [port, observed] of stable.nextObservedByPort) {
-          candidateStabilityByPort.set(port, observed);
-        }
-
-        for (const [port, candidate] of changes.nextObservedByPort) {
-          emittedByPort.set(port, candidate);
-        }
-
-        for (const candidate of changes.changedCandidates) {
-          await options.onCandidate(candidate);
-        }
-      })
-      .catch(error => {
-        options.onError?.(error instanceof Error ? error : new Error(String(error)));
-      })
-      .finally(() => {
-        inFlight.value = false;
-      });
-  };
-
-  scan();
-  const interval = setInterval(scan, intervalMs);
-
-  return {
-    close: () => clearInterval(interval),
-  };
-}
-
-export function changedForwardCandidates(
-  previousObservedByPort: ReadonlyMap<number, PortForwardCandidate>,
-  candidates: readonly PortForwardCandidate[],
-): {
-  readonly nextObservedByPort: Map<number, PortForwardCandidate>;
-  readonly changedCandidates: PortForwardCandidate[];
-} {
-  const nextObservedByPort = new Map<number, PortForwardCandidate>();
-  const changedCandidates: PortForwardCandidate[] = [];
-
-  for (const candidate of candidates) {
-    nextObservedByPort.set(candidate.port, candidate);
-    const previous = previousObservedByPort.get(candidate.port);
-
-    if (previous === undefined || !sameForwardCandidate(previous, candidate)) {
-      changedCandidates.push(candidate);
-    }
-  }
-
-  return { nextObservedByPort, changedCandidates };
-}
-
-export function stableForwardCandidates(
-  previousObservedByPort: ReadonlyMap<number, ObservedPortForwardCandidate>,
-  candidates: readonly PortForwardCandidate[],
-  nowMs: number,
-  debounceMs: number,
-): {
-  readonly nextObservedByPort: Map<number, ObservedPortForwardCandidate>;
-  readonly stableCandidates: PortForwardCandidate[];
-} {
-  const nextObservedByPort = new Map<number, ObservedPortForwardCandidate>();
-  const stableCandidates: PortForwardCandidate[] = [];
-
-  for (const candidate of candidates) {
-    const previous = previousObservedByPort.get(candidate.port);
-    const firstSeenAtMs =
-      previous !== undefined && sameForwardCandidate(previous.candidate, candidate)
-        ? previous.firstSeenAtMs
-        : nowMs;
-    const observed = { candidate, firstSeenAtMs };
-    nextObservedByPort.set(candidate.port, observed);
-
-    if (debounceMs <= 0 || nowMs - firstSeenAtMs >= debounceMs) {
-      stableCandidates.push(candidate);
-    }
-  }
-
-  return { nextObservedByPort, stableCandidates };
-}
-
-export function sameForwardCandidate(
-  left: PortForwardCandidate,
-  right: PortForwardCandidate,
-): boolean {
-  return (
-    left.port === right.port &&
-    left.pid === right.pid &&
-    left.command === right.command &&
-    left.cwd === right.cwd
-  );
-}
-
-export function descendantPidSet(
-  rows: readonly ProcessRow[],
-  rootPid: number,
-): Set<number> {
-  const childrenByParent = new Map<number, number[]>();
-
-  for (const row of rows) {
-    const existing = childrenByParent.get(row.ppid) ?? [];
-    childrenByParent.set(row.ppid, [...existing, row.pid]);
-  }
-
-  const descendants = new Set<number>();
-  const queue = [...(childrenByParent.get(rootPid) ?? [])];
-
-  while (queue.length > 0) {
-    const pid = queue.shift();
-
-    if (pid === undefined || descendants.has(pid)) {
-      continue;
-    }
-
-    descendants.add(pid);
-    queue.push(...(childrenByParent.get(pid) ?? []));
-  }
-
-  return descendants;
-}
-
-export function detectedForwardCandidates(
-  sockets: readonly ListenSocketRow[],
-  descendantPids: ReadonlySet<number>,
-  processCwds: ReadonlyMap<number, string> = new Map(),
-): PortForwardCandidate[] {
-  return sockets
-    .filter(socket => descendantPids.has(socket.pid))
-    .filter(socket => socket.port > 0 && socket.port < 65_536)
-    .sort((left, right) => left.port - right.port)
-    .map(socket => {
-      const cwd = processCwds.get(socket.pid);
-
-      return {
-        port: socket.port,
-        pid: socket.pid,
-        command: socket.command,
-        ...(cwd === undefined ? {} : { cwd }),
-      };
-    });
-}
-
-export function parseProcessRows(output: string): ProcessRow[] {
-  return output
-    .split("\n")
-    .map(line => line.trim())
-    .filter(line => line !== "")
-    .map(line => {
-      const match = line.match(/^(\d+)\s+(\d+)\s+(.*)$/);
-
-      if (match === null) {
-        return undefined;
-      }
-
-      return {
-        pid: Number(match[1]),
-        ppid: Number(match[2]),
-        command: match[3] ?? "",
-      };
-    })
-    .filter((row): row is ProcessRow => row !== undefined);
-}
-
-export function parseLsofListenRows(output: string): ListenSocketRow[] {
-  const rows: ListenSocketRow[] = [];
-  let currentPid: number | undefined;
-  let currentCommand: string | undefined;
-
-  for (const rawLine of output.split("\n")) {
-    const line = rawLine.trim();
-
-    if (line.startsWith("p")) {
-      currentPid = Number(line.slice(1));
-      currentCommand = undefined;
-      continue;
-    }
-
-    if (line.startsWith("c")) {
-      currentCommand = line.slice(1);
-      continue;
-    }
-
-    if (!line.startsWith("n") || currentPid === undefined) {
-      continue;
-    }
-
-    const port = portFromLsofName(line.slice(1));
-
-    if (port !== undefined) {
-      rows.push({
-        pid: currentPid,
-        port,
-        command: currentCommand ?? "unknown",
-      });
-    }
-  }
-
-  return rows;
-}
-
-export function parseLsofCwdRows(output: string): Map<number, string> {
-  const rows = new Map<number, string>();
-  let currentPid: number | undefined;
-
-  for (const rawLine of output.split("\n")) {
-    const line = rawLine.trim();
-
-    if (line.startsWith("p")) {
-      currentPid = Number(line.slice(1));
-      continue;
-    }
-
-    if (line.startsWith("n") && currentPid !== undefined) {
-      const cwd = line.slice(1).trim();
-
-      if (cwd !== "") {
-        rows.set(currentPid, cwd);
-      }
-    }
-  }
-
-  return rows;
-}
-
-function readProcessRows(): ProcessRow[] {
-  const result = spawnSync("ps", ["-axo", "pid=,ppid=,command="], {
-    encoding: "utf8",
-  });
-
-  if (result.error !== undefined) {
-    throw result.error;
-  }
-
-  if (result.status !== 0) {
-    throw new Error(`ps failed with status ${result.status}: ${result.stderr}`);
-  }
-
-  return parseProcessRows(result.stdout);
-}
-
-function readListenSocketRows(): ListenSocketRow[] {
-  const result = spawnSync(
-    "lsof",
-    ["-nP", "-iTCP", "-sTCP:LISTEN", "-FpPcn"],
-    { encoding: "utf8" },
-  );
-
-  if (result.error !== undefined) {
-    throw result.error;
-  }
-
-  if (result.status !== 0) {
-    if (result.status === 1 && result.stdout.trim() === "") {
-      return [];
-    }
-
-    throw new Error(`lsof failed with status ${result.status}: ${result.stderr}`);
-  }
-
-  return parseLsofListenRows(result.stdout);
-}
-
-function readProcessCwdRows(pids: readonly number[]): ReadonlyMap<number, string> {
-  const uniquePids = [...new Set(pids)].filter(pid => Number.isInteger(pid) && pid > 0);
-
-  if (uniquePids.length === 0) {
-    return new Map();
-  }
-
-  const result = spawnSync(
-    "lsof",
-    ["-a", "-p", uniquePids.join(","), "-d", "cwd", "-Fn"],
-    { encoding: "utf8" },
-  );
-
-  if (result.error !== undefined) {
-    throw result.error;
-  }
-
-  if (result.status !== 0) {
-    if (result.status === 1 && result.stdout.trim() === "") {
-      return new Map();
-    }
-
-    throw new Error(`lsof cwd failed with status ${result.status}: ${result.stderr}`);
-  }
-
-  return parseLsofCwdRows(result.stdout);
-}
-
-function portFromLsofName(name: string): number | undefined {
-  const match = name.match(/:(\d+)(?:\s|\(|$)/);
-
-  if (match === null) {
-    return undefined;
-  }
-
-  const port = Number(match[1]);
-
-  return Number.isInteger(port) ? port : undefined;
-}
-
-export function commandLabel(command: string): string {
-  const trimmed = command.trim();
-
-  if (trimmed === "") {
-    return "unknown";
-  }
-
-  return basename(trimmed.split(/\s+/)[0] ?? trimmed);
-}

package/src/protocol.ts

@@ -1,321 +0,0 @@
-/*
-- Date: 2026-04-24
-  Spec: plans/2026-04-24-local-codex-runner-plan.md
-  Relationship: Defines the spec's first local runner protocol types for
-  Phoenix frames, Codex JSON-RPC envelopes, runner events, and controls.
-
-- Date: 2026-04-24
-  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
-  Relationship: Defines the channel-bound runner options used to bind one
-  local Codex process to a Kandan channel/thread and listener selector.
-
-- Date: 2026-04-25
-  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
-  Relationship: Defines the typed runner control that carries a Kandan
-  Approve/Deny decision back to the local Codex app-server approval request
-  without exposing a browser-to-runner socket.
-
-- Date: 2026-04-26
-  Spec: plans/2026-04-26-local-codex-driver-worldclass-spec.md
-  Relationship: Carries the runner streaming flush interval so live Codex
-  output can be batched before Kandan persistence without changing the logical
-  transcript protocol.
-
-- Date: 2026-04-26
-  Spec: plans/2026-04-26-local-runner-forwarding-and-editor-plan.md
-  Relationship: Defines the typed control used by Kandan to ask a connected
-  runner to perform one bounded HTTP request against an explicitly allowed
-  local preview port, and the typed control used to ask the runner to start a
-  loopback-only local code-server editor for an allowed cwd.
-
-- Date: 2026-04-26
-  Spec: plans/2026-04-26-local-runner-port-forward-approval.md
-  Relationship: Defines the typed approval control Kandan sends after the
-  in-app local port prompt is resolved by the authorized listener user.
-
-- Date: 2026-04-26
-  Spec: plans/2026-04-26-local-runner-subdomain-forwarding-epr.md
-  Relationship: Defines the typed WebSocket forwarding controls used by
-  isolated preview subdomains.
-
-- Date: 2026-05-02
-  Spec: plans/2026-05-02-agent-first-zero-to-codex-launch-plan.md
-  Relationship: Keeps the npm CLI runner protocol in parity with the legacy
-  runner for runtime session setting updates.
-*/
-export type JsonValue =
-  | null
-  | boolean
-  | number
-  | string
-  | JsonValue[]
-  | { readonly [key: string]: JsonValue };
-
-export type JsonObject = { readonly [key: string]: JsonValue };
-
-export type JsonRpcId = string | number;
-
-export type JsonRpcRequest = {
-  readonly jsonrpc: "2.0";
-  readonly id: JsonRpcId;
-  readonly method: string;
-  readonly params?: JsonObject;
-};
-
-export type JsonRpcNotification = {
-  readonly jsonrpc: "2.0";
-  readonly method: string;
-  readonly params?: JsonObject;
-};
-
-export type JsonRpcResponse =
-  | {
-      readonly jsonrpc: "2.0";
-      readonly id: JsonRpcId;
-      readonly result: JsonValue;
-    }
-  | {
-      readonly jsonrpc: "2.0";
-      readonly id: JsonRpcId;
-      readonly error: {
-        readonly code: number;
-        readonly message: string;
-        readonly data?: JsonValue;
-      };
-    };
-
-export type JsonRpcMessage =
-  | JsonRpcRequest
-  | JsonRpcNotification
-  | JsonRpcResponse;
-
-export type PhoenixFrame = readonly [
-  joinRef: string | null,
-  ref: string | null,
-  topic: string,
-  event: string,
-  payload: JsonValue,
-];
-
-export type RunnerToKandanEvent =
-  | {
-      readonly kind: "instance_started";
-      readonly payload: JsonObject;
-    }
-  | {
-      readonly kind: "instance_stopped";
-      readonly payload: JsonObject;
-    }
-  | {
-      readonly kind: "codex_notification";
-      readonly payload: {
-        readonly instanceId: string;
-        readonly seq: number;
-        readonly method: string;
-        readonly params: JsonObject;
-        readonly receivedAt: string;
-      };
-    }
-  | {
-      readonly kind: "codex_request";
-      readonly payload: JsonObject;
-    }
-  | {
-      readonly kind: "codex_response";
-      readonly payload: JsonObject;
-    }
-  | {
-      readonly kind: "codex_error";
-      readonly payload: JsonObject;
-    }
-  | {
-      readonly kind: "heartbeat";
-      readonly payload: JsonObject;
-    };
-
-export type KandanControl =
-  | {
-      readonly type: "start_instance";
-      readonly instanceId?: string;
-      readonly cwd?: string;
-      readonly workDescription?: string;
-      readonly launchTui?: boolean;
-      readonly model?: string;
-      readonly reasoningEffort?: string;
-      readonly approvalPolicy?: string;
-      readonly sandbox?: string;
-      readonly fast?: boolean;
-    }
-  | {
-      readonly type: "stop_instance";
-      readonly instanceId: string;
-    }
-  | {
-      readonly type: "kill_instance";
-      readonly instanceId: string;
-    }
-  | {
-      readonly type: "start_turn";
-      readonly instanceId: string;
-      readonly threadId: string;
-      readonly input: JsonValue[];
-    }
-  | {
-      readonly type: "steer_turn";
-      readonly instanceId: string;
-      readonly threadId: string;
-      readonly turnId: string;
-      readonly input: JsonValue[];
-    }
-  | {
-      readonly type: "interrupt_turn";
-      readonly instanceId: string;
-      readonly threadId: string;
-      readonly turnId?: string;
-    }
-  | {
-      readonly type: "interrupt_queued_messages";
-      readonly instanceId: string;
-      readonly threadId: string;
-      readonly throughSeq?: number;
-    }
-  | {
-      readonly type: "resolve_codex_approval_request";
-      readonly instanceId: string;
-      readonly threadId: string;
-      readonly sourceSeq: number;
-      readonly requestId: string;
-      readonly decision: "approve" | "deny";
-    }
-  | {
-      readonly type: "update_session_settings";
-      readonly instanceId?: string;
-      readonly threadId: string;
-      readonly model?: string | null;
-      readonly reasoningEffort?: string | null;
-      readonly approvalPolicy?: string | null;
-      readonly sandbox?: string | null;
-      readonly fast?: boolean;
-    }
-  | {
-      readonly type: "resolve_port_forward_request";
-      readonly instanceId: string;
-      readonly requestId: string;
-      readonly decision: "approve" | "deny";
-      readonly actorUserId?: number | undefined;
-      readonly actorSlug?: string | undefined;
-    }
-  | {
-      readonly type: "read_thread";
-      readonly instanceId: string;
-      readonly threadId: string;
-      readonly includeTurns?: boolean;
-    }
-  | {
-      readonly type: "forward_http_request";
-      readonly instanceId?: string;
-      readonly requestId: string;
-      readonly port: number;
-      readonly method: string;
-      readonly path: string;
-      readonly queryString?: string;
-      readonly headers?: JsonValue;
-      readonly bodyBase64?: string;
-    }
-  | {
-      readonly type: "forward_websocket_open";
-      readonly instanceId?: string;
-      readonly socketId: string;
-      readonly port: number;
-      readonly path: string;
-      readonly queryString?: string;
-      readonly headers?: JsonValue;
-    }
-  | {
-      readonly type: "forward_websocket_send";
-      readonly instanceId?: string;
-      readonly socketId: string;
-      readonly opcode: "text" | "binary" | "ping" | "pong";
-      readonly bodyBase64: string;
-    }
-  | {
-      readonly type: "forward_websocket_close";
-      readonly instanceId?: string;
-      readonly socketId: string;
-    }
-  | {
-      readonly type: "update_runner_config";
-      readonly instanceId?: string;
-      readonly allowedCwds: readonly string[];
-      readonly configVersion?: number;
-    }
-  | {
-      readonly type: "start_local_editor";
-      readonly instanceId?: string;
-      readonly requestId?: string;
-      readonly cwd: string;
-      readonly browserBaseUrl?: string;
-      readonly collaboration?: {
-        readonly provider: "oct";
-        readonly editorSessionId: number;
-        readonly runtimeSessionId: string;
-        readonly roomId: string;
-        readonly extensionAssetPath: string;
-        readonly serverAssetPath: string;
-        readonly bootstrapToken?: string;
-      };
-    };
-
-export type KandanChannelSessionOptions = {
-  readonly workspaceSlug: string;
-  readonly channelSlug: string;
-  readonly kandanThreadId: string | undefined;
-  readonly listenUser: string;
-  readonly model?: string | undefined;
-  readonly reasoningEffort?: string | undefined;
-  readonly sandbox?: string | undefined;
-  readonly approvalPolicy?: string | undefined;
-  readonly streamFlushMs?: number | undefined;
-};
-
-export function parseJsonObject(text: string): JsonObject {
-  const parsed = JSON.parse(text);
-
-  if (isJsonObject(parsed)) {
-    return parsed;
-  }
-
-  throw new Error("expected JSON object");
-}
-
-export function isJsonObject(value: unknown): value is JsonObject {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-export function requireString(value: unknown, label: string): string {
-  if (typeof value === "string" && value.trim() !== "") {
-    return value.trim();
-  }
-
-  throw new Error(`${label} must be a non-empty string`);
-}
-
-export function requirePositiveInteger(value: unknown, label: string): number {
-  if (Number.isInteger(value) && typeof value === "number" && value > 0) {
-    return value;
-  }
-
-  throw new Error(`${label} must be a positive integer`);
-}
-
-export function extractCodexIds(params: JsonObject): JsonObject {
-  const entries = [
-    ["threadId", params.threadId],
-    ["turnId", params.turnId],
-    ["itemId", params.itemId],
-    ["processId", params.processId],
-    ["requestId", params.requestId],
-  ].filter((entry): entry is [string, JsonValue] => entry[1] !== undefined);
-
-  return Object.fromEntries(entries) as JsonObject;
-}