@linzumi/cli 0.0.4-beta → 0.0.6-beta

package/src/pendingKandanMessageQueue.ts

@@ -0,0 +1,109 @@
+/*
+- Date: 2026-04-26
+  Spec: kandan/server_v2/plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Provides the local Codex channel session with an amortized O(1)
+  pending Kandan message queue so long shared sessions avoid repeated
+  `Array.shift()` reindexing while preserving interrupt fusion order.
+*/
+import {
+  interruptQueuedMessages,
+  type QueueInterruptResult,
+  type QueuedKandanMessage,
+} from "./kandanQueue";
+
+export type PendingKandanMessageQueue = {
+  items: QueuedKandanMessage[];
+  head: number;
+};
+
+export function createPendingKandanMessageQueue(): PendingKandanMessageQueue {
+  return {
+    items: [],
+    head: 0,
+  };
+}
+
+export function pendingKandanMessageQueueLength(
+  queue: PendingKandanMessageQueue,
+): number {
+  return queue.items.length - queue.head;
+}
+
+export function enqueuePendingKandanMessage(
+  queue: PendingKandanMessageQueue,
+  message: QueuedKandanMessage,
+): void {
+  queue.items.push(message);
+}
+
+export function dequeuePendingKandanMessage(
+  queue: PendingKandanMessageQueue,
+): QueuedKandanMessage | undefined {
+  const message = queue.items[queue.head];
+
+  if (message === undefined) {
+    compactPendingKandanMessageQueue(queue);
+    return undefined;
+  }
+
+  queue.head = queue.head + 1;
+  compactPendingKandanMessageQueue(queue);
+  return message;
+}
+
+export function requeuePendingKandanMessageFront(
+  queue: PendingKandanMessageQueue,
+  message: QueuedKandanMessage,
+): void {
+  if (queue.head > 0) {
+    queue.head = queue.head - 1;
+    queue.items[queue.head] = message;
+    return;
+  }
+
+  queue.items.unshift(message);
+}
+
+export function interruptPendingKandanMessages(
+  queue: PendingKandanMessageQueue,
+  throughSeq: number | undefined,
+): QueueInterruptResult {
+  const result = interruptQueuedMessages(pendingKandanMessages(queue), throughSeq);
+
+  if (result.ok) {
+    replacePendingKandanMessages(queue, result.queue);
+  }
+
+  return result;
+}
+
+function replacePendingKandanMessages(
+  queue: PendingKandanMessageQueue,
+  messages: QueuedKandanMessage[],
+): void {
+  queue.items = messages;
+  queue.head = 0;
+}
+
+function pendingKandanMessages(
+  queue: PendingKandanMessageQueue,
+): QueuedKandanMessage[] {
+  return queue.head === 0 ? queue.items : queue.items.slice(queue.head);
+}
+
+function compactPendingKandanMessageQueue(queue: PendingKandanMessageQueue): void {
+  if (queue.head === 0) {
+    return;
+  }
+
+  if (queue.head >= queue.items.length) {
+    queue.items = [];
+    queue.head = 0;
+    return;
+  }
+
+  if (queue.head > queue.items.length / 2) {
+    queue.items = queue.items.slice(queue.head);
+    queue.head = 0;
+  }
+}

package/src/phoenix.ts

@@ -13,6 +13,11 @@
   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.
+
+- Date: 2026-04-26
+  Spec: plans/2026_04_26_linzumi_cli_review_followups_note.md
+  Relationship: Treats non-ok Phoenix replies for runner pushes as transport
+  failures so failed Kandan writes cannot be mistaken for synchronized state.
 */
 import {
   type JsonObject,
@@ -23,6 +28,7 @@ import {
 } from "./protocol";
 
 type PendingPush = {
+  readonly event: string;
   readonly resolve: (payload: JsonValue) => void;
   readonly reject: (error: Error) => void;
 };
@@ -48,6 +54,14 @@ export type PhoenixClient = {
 
 export function phoenixWebsocketUrl(baseUrl: string, token: string): string {
   const parsed = new URL(baseUrl);
+  switch (parsed.protocol) {
+    case "http:":
+      parsed.protocol = "ws:";
+      break;
+    case "https:":
+      parsed.protocol = "wss:";
+      break;
+  }
   parsed.pathname = parsed.pathname.replace(/\/$/, "") + "/socket/websocket";
   parsed.searchParams.set("token", token);
   parsed.searchParams.set("vsn", "2.0.0");
@@ -112,6 +126,8 @@ export async function connectPhoenixClient(
 
         if (name === "phx_error") {
           pendingPush.reject(new Error("phoenix push failed"));
+        } else if (isNonOkPushReply(payload) && pendingPush.event !== "phx_join") {
+          pendingPush.reject(new Error(`phoenix push failed: ${replyErrorMessage(payload)}`));
         } else {
           pendingPush.resolve(payload);
         }
@@ -143,7 +159,7 @@ export async function connectPhoenixClient(
     const frame: PhoenixFrame = [null, ref, topic, event, payload];
 
     return new Promise((resolve, reject) => {
-      pending.set(ref, { resolve, reject });
+      pending.set(ref, { event, resolve, reject });
       websocket.send(JSON.stringify(frame));
     });
   };
@@ -304,6 +320,10 @@ function isJoinReply(value: JsonValue): value is {
 }
 
 function joinErrorMessage(value: JsonValue): string {
+  return replyErrorMessage(value);
+}
+
+function replyErrorMessage(value: JsonValue): string {
   if (!isJsonObject(value)) {
     return "invalid reply";
   }
@@ -321,6 +341,10 @@ function joinErrorMessage(value: JsonValue): string {
   return "unknown";
 }
 
+function isNonOkPushReply(value: JsonValue): boolean {
+  return isJsonObject(value) && value.status !== "ok";
+}
+
 function isKandanControl(value: JsonValue): value is KandanControl {
   return isJsonObject(value) && typeof value.type === "string";
 }

package/src/portForwardApproval.ts

@@ -0,0 +1,181 @@
+/*
+- Date: 2026-04-27
+  Spec: plans/2026-04-26-local-runner-subdomain-forwarding-epr.md
+  Relationship: Keeps local runner port-forward approval and revocation policy
+  pure so security decisions are tested directly instead of hiding inside the
+  channel-session orchestration module.
+*/
+import { type JsonObject } from "./protocol";
+import {
+  commandLabel,
+  sameForwardCandidate,
+  type PortForwardCandidate,
+} from "./portForwardWatcher";
+
+export type PendingPortForwardRequest = {
+  readonly requestId: string;
+  readonly port: number;
+  readonly pid: number;
+  readonly command: string;
+  readonly cwd?: string | undefined;
+  readonly sourceSeq: number;
+};
+
+export type PortForwardCandidateReview =
+  | {
+      readonly type: "skip";
+      readonly reason:
+        | "thread_not_bound"
+        | "suppressed_port"
+        | "already_pending"
+        | "already_approved"
+        | "recently_dismissed";
+    }
+  | { readonly type: "remember_approved_target"; readonly target: PortForwardCandidate }
+  | {
+      readonly type: "revoke_and_prompt";
+      readonly revoked: PortForwardCandidate;
+      readonly candidate: PortForwardCandidate;
+      readonly reason: "listener_changed";
+    }
+  | { readonly type: "prompt"; readonly candidate: PortForwardCandidate };
+
+export function reviewPortForwardCandidate(options: {
+  readonly candidate: PortForwardCandidate;
+  readonly threadBound: boolean;
+  readonly suppressedPorts?: ReadonlySet<number> | undefined;
+  readonly approvedPorts: ReadonlySet<number>;
+  readonly approvedTargets: ReadonlyMap<number, PortForwardCandidate>;
+  readonly dismissedTargets?: ReadonlyMap<number, PortForwardCandidate> | undefined;
+  readonly pendingRequests: readonly PendingPortForwardRequest[];
+}): PortForwardCandidateReview {
+  if (!options.threadBound) {
+    return { type: "skip", reason: "thread_not_bound" };
+  }
+
+  if (options.suppressedPorts?.has(options.candidate.port) === true) {
+    return { type: "skip", reason: "suppressed_port" };
+  }
+
+  const dismissedTarget = options.dismissedTargets?.get(options.candidate.port);
+
+  if (
+    dismissedTarget !== undefined &&
+    sameDismissedPortForwardTarget(dismissedTarget, options.candidate)
+  ) {
+    return { type: "skip", reason: "recently_dismissed" };
+  }
+
+  if (options.approvedPorts.has(options.candidate.port)) {
+    const approvedTarget = options.approvedTargets.get(options.candidate.port);
+
+    if (approvedTarget === undefined) {
+      return { type: "remember_approved_target", target: options.candidate };
+    }
+
+    if (sameForwardCandidate(approvedTarget, options.candidate)) {
+      return { type: "skip", reason: "already_approved" };
+    }
+
+    return {
+      type: "revoke_and_prompt",
+      revoked: approvedTarget,
+      candidate: options.candidate,
+      reason: "listener_changed",
+    };
+  }
+
+  if (options.pendingRequests.some(request => request.port === options.candidate.port)) {
+    return { type: "skip", reason: "already_pending" };
+  }
+
+  return { type: "prompt", candidate: options.candidate };
+}
+
+export function pendingRequestFromCandidate(options: {
+  readonly requestId: string;
+  readonly sourceSeq: number;
+  readonly candidate: PortForwardCandidate;
+}): PendingPortForwardRequest {
+  return {
+    requestId: options.requestId,
+    port: options.candidate.port,
+    pid: options.candidate.pid,
+    command: options.candidate.command,
+    ...(options.candidate.cwd === undefined ? {} : { cwd: options.candidate.cwd }),
+    sourceSeq: options.sourceSeq,
+  };
+}
+
+export function approvedTargetFromRequest(
+  request: PendingPortForwardRequest,
+): PortForwardCandidate {
+  return {
+    port: request.port,
+    pid: request.pid,
+    command: request.command,
+    ...(request.cwd === undefined ? {} : { cwd: request.cwd }),
+  };
+}
+
+export function portForwardPromptLabel(candidate: PortForwardCandidate): string {
+  return commandLabel(candidate.command);
+}
+
+export function portForwardPromptBody(
+  candidate: PortForwardCandidate,
+  requestId: string,
+): string {
+  const label = portForwardPromptLabel(candidate);
+  const cwdLine = candidate.cwd === undefined ? undefined : `Working directory: ${candidate.cwd}`;
+
+  return [
+    `Detected ${label} listening from a descendant process.`,
+    `Port: ${candidate.port}`,
+    `PID: ${candidate.pid}`,
+    `Command: ${candidate.command}`,
+    ...(cwdLine === undefined ? [] : [cwdLine]),
+    "Kandan can open this as an authenticated HTTP, HTTPS, or WebSocket preview. It does not expose arbitrary TCP or UDP protocols.",
+    "Open this preview in Kandan?",
+    "",
+    `Fallback commands: ${portForwardDecisionCommand("approve", requestId)} or ${portForwardDecisionCommand("deny", requestId)}`,
+  ].join("\n");
+}
+
+export function portForwardPromptReason(candidate: PortForwardCandidate): string {
+  return [
+    `Port ${candidate.port}`,
+    `PID ${candidate.pid}`,
+    `command: ${candidate.command}`,
+    ...(candidate.cwd === undefined ? [] : [`cwd: ${candidate.cwd}`]),
+    "preview protocols: HTTP, HTTPS, WebSocket",
+  ].join(" / ");
+}
+
+export function portForwardDecisionCommand(
+  decision: "approve" | "deny",
+  requestId: string,
+): string {
+  return `/kandan ${decision}-port-forward ${requestId}`;
+}
+
+export function forwardPreviewPath(runnerId: string, port: number): string {
+  return `/local-codex-runners/${encodeURIComponent(runnerId)}/forwards/${port}/preview`;
+}
+
+export function revocationCapabilities(
+  capabilities: JsonObject | undefined,
+  port: number,
+): JsonObject {
+  return {
+    ...(capabilities ?? {}),
+    revokedPorts: [port],
+  };
+}
+
+function sameDismissedPortForwardTarget(
+  left: PortForwardCandidate,
+  right: PortForwardCandidate,
+): boolean {
+  return left.port === right.port && left.command === right.command && left.cwd === right.cwd;
+}