@linzumi/cli 0.0.5-beta → 0.0.6-beta

package/src/localCapabilities.ts

@@ -0,0 +1,130 @@
+/*
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Defines the local machine capability boundary for Kandan-
+  requested Codex session starts and future preview forwarding. Remote starts
+  are allowed only inside explicitly configured local cwd roots, and preview
+  forwarding is advertised only for explicitly configured local ports.
+*/
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+
+export type CwdCapabilityDecision =
+  | {
+      readonly ok: true;
+      readonly cwd: string;
+      readonly matchedRoot: string;
+    }
+  | {
+      readonly ok: false;
+      readonly reason:
+        | "missing_cwd"
+        | "no_allowed_cwd"
+        | "cwd_not_allowed"
+        | "cwd_not_found";
+    };
+
+export function parseAllowedCwdList(value: string | undefined): string[] {
+  if (value === undefined) {
+    return [];
+  }
+
+  return value
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part !== "");
+}
+
+export function parseAllowedPortList(value: string | undefined): number[] {
+  if (value === undefined) {
+    return [];
+  }
+
+  const ports = new Set<number>();
+
+  for (const part of value.split(",")) {
+    const trimmed = part.trim();
+
+    if (trimmed === "") {
+      continue;
+    }
+
+    const port = Number(trimmed);
+
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+      throw new Error(`invalid --forward-port: ${trimmed} is not a TCP port`);
+    }
+
+    ports.add(port);
+  }
+
+  return [...ports].sort((left, right) => left - right);
+}
+
+export function assertConfiguredAllowedCwds(
+  paths: readonly string[],
+): string[] {
+  return paths.map((path) => {
+    try {
+      return realpathSync(resolve(path));
+    } catch (_error) {
+      throw new Error(`invalid --allowed-cwd: ${path} does not exist`);
+    }
+  });
+}
+
+export function resolveAllowedCwd(
+  requestedCwd: string | undefined,
+  allowedRoots: readonly string[],
+): CwdCapabilityDecision {
+  if (requestedCwd === undefined || requestedCwd.trim() === "") {
+    return { ok: false, reason: "missing_cwd" };
+  }
+
+  if (allowedRoots.length === 0) {
+    return { ok: false, reason: "no_allowed_cwd" };
+  }
+
+  let cwd: string;
+
+  try {
+    cwd = realpathSync(resolve(requestedCwd));
+  } catch (_error) {
+    return { ok: false, reason: "cwd_not_found" };
+  }
+
+  const matchedRoot = allowedRoots.find((root) =>
+    cwdIsInsideNormalizedRoot(cwd, root),
+  );
+
+  return matchedRoot === undefined
+    ? { ok: false, reason: "cwd_not_allowed" }
+    : { ok: true, cwd, matchedRoot };
+}
+
+function cwdIsInsideNormalizedRoot(
+  cwd: string,
+  normalizedRoot: string,
+): boolean {
+  return relativePathIsInsideRoot(relative(normalizedRoot, cwd));
+}
+
+export function relativePathIsInsideRoot(pathRelativeToRoot: string): boolean {
+  return (
+    pathRelativeToRoot === "" ||
+    (!pathLooksAbsolute(pathRelativeToRoot) &&
+      pathRelativeToRoot !== ".." &&
+      !pathRelativeToRoot.startsWith("../") &&
+      !pathRelativeToRoot.startsWith("..\\") &&
+      !pathRelativeToRoot.includes("/../") &&
+      !pathRelativeToRoot.includes("\\..\\"))
+  );
+}
+
+function pathLooksAbsolute(pathValue: string): boolean {
+  return (
+    isAbsolute(pathValue) ||
+    /^[A-Za-z]:[\\/]/.test(pathValue) ||
+    pathValue.startsWith("\\\\")
+  );
+}

package/src/localCodexMessageState.ts

@@ -0,0 +1,135 @@
+/*
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Defines the user-visible local Codex message state model and
+  the Codex notification-to-state mapping used by Kandan to show queued,
+  processing, approval, failed, ignored, and processed states consistently.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-port-forward-approval.md
+  Relationship: Allows local runner approval states to carry explicit
+  UI choices so descendant port-forward prompts can reuse the existing
+  Kandan approval bottom bar.
+*/
+import { objectValue, stringValue } from "./json";
+import type { JsonObject, JsonRpcRequest } from "./protocol";
+
+export type LocalCodexProcessingReason =
+  | "starting turn"
+  | "streaming response"
+  | "running terminal command"
+  | "interrupt requested"
+  | "awaiting approval";
+
+export type CodexApprovalMessageState = {
+  readonly requestId: string;
+  readonly kind: string;
+  readonly summary: string;
+  readonly reason?: string | undefined;
+  readonly choices?: readonly ApprovalChoice[] | undefined;
+  readonly allowedActorSlug?: string | undefined;
+  readonly allowedActorUserId?: number | undefined;
+};
+
+export type ApprovalChoice = {
+  readonly decision: string;
+  readonly label: string;
+  readonly description?: string | undefined;
+};
+
+export type ActiveProcessingState =
+  | {
+      readonly seq: number;
+      readonly reason: Exclude<LocalCodexProcessingReason, "awaiting approval">;
+    }
+  | {
+      readonly seq: number;
+      readonly reason: "awaiting approval";
+      readonly approval: CodexApprovalMessageState;
+    };
+
+export type LocalCodexMessageState =
+  | { readonly status: "queued" }
+  | { readonly status: "processed" }
+  | {
+      readonly status: "processing";
+      readonly reason: LocalCodexProcessingReason;
+      readonly approval?: CodexApprovalMessageState | undefined;
+    }
+  | { readonly status: "ignored"; readonly reason: string }
+  | { readonly status: "failed"; readonly reason: string };
+
+export function codexApprovalMessageState(
+  request: JsonRpcRequest,
+): CodexApprovalMessageState {
+  const params = objectValue(request.params) ?? {};
+  const command = stringValue(params.command) ?? stringValue(params.cmd);
+  const filePath =
+    stringValue(params.path) ??
+    stringValue(params.filePath) ??
+    stringValue(params.file);
+  const summary =
+    command ??
+    filePath ??
+    stringValue(params.reason) ??
+    stringValue(params.summary) ??
+    request.method;
+
+  return {
+    requestId: String(request.id),
+    kind: request.method,
+    summary,
+  };
+}
+
+export function approvalRequestKey(requestId: string, sourceSeq: number): string {
+  return `${sourceSeq}:${requestId}`;
+}
+
+export function processingReasonForCodexNotification(
+  method: string,
+  params: JsonObject,
+): Exclude<LocalCodexProcessingReason, "awaiting approval"> | undefined {
+  if (method === "item/agentMessage/delta" || method === "item/reasoning/textDelta") {
+    return "streaming response";
+  }
+
+  if (
+    method.startsWith("item/commandExecution/") ||
+    method === "command/exec/outputDelta"
+  ) {
+    return "running terminal command";
+  }
+
+  const item = objectValue(params.item) ?? params;
+  const itemType = stringValue(item.type);
+
+  switch (itemType) {
+    case "commandExecution":
+    case "terminalInput":
+      return "running terminal command";
+    case "agentMessage":
+    case "reasoning":
+    case "fileChange":
+    case "web_search_call":
+    case "webSearchCall":
+    case "webSearch":
+      return "streaming response";
+    default:
+      return undefined;
+  }
+}
+
+export function processingMessageStateFromActive(
+  state: ActiveProcessingState,
+): Extract<LocalCodexMessageState, { readonly status: "processing" }> {
+  switch (state.reason) {
+    case "awaiting approval":
+      return { status: "processing", reason: state.reason, approval: state.approval };
+    case "starting turn":
+    case "streaming response":
+    case "running terminal command":
+    case "interrupt requested":
+      return { status: "processing", reason: state.reason };
+  }
+}

package/src/localCodexTurnState.ts

@@ -0,0 +1,108 @@
+/*
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Defines the pure local Codex turn lifecycle helpers used by
+  the channel-session orchestrator for interruption, active-turn lookup,
+  completion, failure cleanup, and forwarding eligibility.
+*/
+
+export type TurnState =
+  | { readonly status: "idle" }
+  | {
+      readonly status: "starting";
+      readonly queuedSeq: number;
+      readonly interruptAfterStart: boolean;
+    }
+  | { readonly status: "active"; readonly turnId: string; readonly queuedSeq: number }
+  | { readonly status: "completing"; readonly turnId: string; readonly queuedSeq: number };
+
+export function activeTurnId(turn: TurnState): string | undefined {
+  switch (turn.status) {
+    case "active":
+    case "completing":
+      return turn.turnId;
+    case "idle":
+    case "starting":
+      return undefined;
+  }
+}
+
+export function activeQueuedSeqForTurn(
+  turn: TurnState,
+  turnId: string,
+): number | undefined {
+  switch (turn.status) {
+    case "active":
+    case "completing":
+      return turn.turnId === turnId ? turn.queuedSeq : undefined;
+    case "idle":
+    case "starting":
+      return undefined;
+  }
+}
+
+export function interruptibleQueuedSeq(turn: TurnState): number | undefined {
+  switch (turn.status) {
+    case "active":
+    case "starting":
+      return turn.queuedSeq;
+    case "idle":
+    case "completing":
+      return undefined;
+  }
+}
+
+export function markInterruptAfterStart(turn: TurnState): TurnState {
+  switch (turn.status) {
+    case "starting":
+      return {
+        status: "starting",
+        queuedSeq: turn.queuedSeq,
+        interruptAfterStart: true,
+      };
+    case "idle":
+    case "active":
+    case "completing":
+      return turn;
+  }
+}
+
+export function turnCanForwardByState(turn: TurnState, turnId: string): boolean {
+  switch (turn.status) {
+    case "active":
+    case "completing":
+      return turn.turnId === turnId;
+    case "idle":
+    case "starting":
+      return false;
+  }
+}
+
+export function completingQueuedSeqForTurn(
+  turn: TurnState,
+  turnId: string,
+): number | undefined {
+  switch (turn.status) {
+    case "active":
+      return turn.turnId === turnId ? turn.queuedSeq : undefined;
+    case "idle":
+    case "starting":
+    case "completing":
+      return undefined;
+  }
+}
+
+export function shouldClearTurnAfterFailure(
+  turn: TurnState,
+  turnId: string,
+): boolean {
+  switch (turn.status) {
+    case "starting":
+      return true;
+    case "active":
+    case "completing":
+      return turn.turnId === turnId;
+    case "idle":
+      return false;
+  }
+}