dextunnel 0.1.0

package/src/lib/fake-codex-app-server-bridge.mjs

@@ -0,0 +1,340 @@
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { mapThreadToCompanionSnapshot } from "./codex-app-server-client.mjs";
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function defaultThreads(cwd) {
+  const timestamp = nowIso();
+  return [
+    {
+      cwd,
+      id: "thr_dextunnel",
+      name: "dextunnel",
+      path: `${cwd}/.codex/fake-dextunnel.jsonl`,
+      preview: "Semantic companion thread",
+      source: "vscode",
+      status: "idle",
+      tokenUsage: null,
+      turns: [
+        {
+          id: "turn_dextunnel_1",
+          items: [
+            {
+              content: [{ text: "keep going on dextunnel", type: "text" }],
+              id: "item_user_1",
+              type: "userMessage"
+            },
+            {
+              id: "item_agent_1",
+              phase: "message",
+              text: "Dextunnel fake bridge ready.",
+              type: "agentMessage"
+            }
+          ],
+          startedAt: timestamp,
+          status: "completed",
+          updatedAt: timestamp
+        }
+      ],
+      updatedAt: timestamp
+    },
+    {
+      cwd,
+      id: "thr_marketing",
+      name: "marketing",
+      path: `${cwd}/.codex/fake-marketing.jsonl`,
+      preview: "Marketing side thread",
+      source: "vscode",
+      status: "idle",
+      tokenUsage: null,
+      turns: [
+        {
+          id: "turn_marketing_1",
+          items: [
+            {
+              content: [{ text: "review marketing notes", type: "text" }],
+              id: "item_marketing_user_1",
+              type: "userMessage"
+            },
+            {
+              id: "item_marketing_agent_1",
+              phase: "message",
+              text: "Marketing thread ready.",
+              type: "agentMessage"
+            }
+          ],
+          startedAt: timestamp,
+          status: "completed",
+          updatedAt: timestamp
+        }
+      ],
+      updatedAt: timestamp
+    }
+  ];
+}
+
+export function createFakeCodexAppServerBridge({
+  cwd = process.cwd(),
+  binaryPath = "fake-codex",
+  listenUrl = "ws://fake-codex-app-server",
+  sendDelayMs = 0
+} = {}) {
+  const threadsById = new Map(defaultThreads(cwd).map((thread) => [thread.id, structuredClone(thread)]));
+  const watchersByThreadId = new Map();
+
+  function listAllThreads() {
+    return [...threadsById.values()].sort((left, right) => {
+      const leftTime = new Date(left.updatedAt || 0).getTime();
+      const rightTime = new Date(right.updatedAt || 0).getTime();
+      return rightTime - leftTime;
+    });
+  }
+
+  function summarizeThread(thread) {
+    return {
+      cwd: thread.cwd || null,
+      id: thread.id,
+      name: thread.name || null,
+      path: thread.path || null,
+      preview: thread.preview || null,
+      source: thread.source || null,
+      status: thread.status || null,
+      updatedAt: thread.updatedAt || null
+    };
+  }
+
+  function getThread(threadId) {
+    const thread = threadsById.get(threadId);
+    return thread ? structuredClone(thread) : null;
+  }
+
+  function updateThread(threadId, updater) {
+    const current = threadsById.get(threadId);
+    if (!current) {
+      return null;
+    }
+
+    const next = updater(structuredClone(current));
+    threadsById.set(threadId, next);
+    return structuredClone(next);
+  }
+
+  async function listThreads({
+    cwd: requestedCwd = null,
+    limit = 10,
+    sourceKinds = null
+  } = {}) {
+    let threads = listAllThreads();
+    if (requestedCwd) {
+      threads = threads.filter((thread) => thread.cwd === requestedCwd);
+    }
+    if (Array.isArray(sourceKinds) && sourceKinds.length) {
+      threads = threads.filter((thread) => sourceKinds.includes(thread.source));
+    }
+    return threads.slice(0, limit).map(summarizeThread);
+  }
+
+  async function readThread(threadId) {
+    return getThread(threadId);
+  }
+
+  async function getLatestThreadForCwd(requestedCwd) {
+    const threads = await listThreads({ cwd: requestedCwd, limit: 1 });
+    if (threads.length === 0) {
+      return null;
+    }
+    return readThread(threads[0].id);
+  }
+
+  async function startThread({
+    cwd: threadCwd = cwd
+  } = {}) {
+    const id = `thr_${randomUUID().slice(0, 8)}`;
+    const timestamp = nowIso();
+    const thread = {
+      cwd: threadCwd,
+      id,
+      name: "new session",
+      path: `${threadCwd}/.codex/${id}.jsonl`,
+      preview: null,
+      source: "vscode",
+      status: "idle",
+      tokenUsage: null,
+      turns: [],
+      updatedAt: timestamp
+    };
+    threadsById.set(id, thread);
+    return summarizeThread(thread);
+  }
+
+  async function sendText({
+    threadId = null,
+    cwd: threadCwd = cwd,
+    text = "",
+    attachments = [],
+    createThreadIfMissing = true
+  } = {}) {
+    let nextThreadId = threadId;
+
+    if (!nextThreadId) {
+      if (!createThreadIfMissing) {
+        throw new Error("No fake thread selected.");
+      }
+      const created = await startThread({ cwd: threadCwd });
+      nextThreadId = created.id;
+    }
+
+    if (Number.isFinite(sendDelayMs) && sendDelayMs > 0) {
+      await delay(sendDelayMs);
+    }
+
+    const timestamp = nowIso();
+    const assistantText = text
+      ? `FAKE_BRIDGE_ACK: ${String(text).trim()}`
+      : `FAKE_BRIDGE_ACK: ${attachments.length} attachment${attachments.length === 1 ? "" : "s"}`;
+    const turnId = `turn_${randomUUID().slice(0, 8)}`;
+    const nextThread = updateThread(nextThreadId, (thread) => {
+      const turn = {
+        id: turnId,
+        items: [
+          {
+            content: text ? [{ text: String(text).trim(), type: "text" }] : [],
+            id: `item_user_${randomUUID().slice(0, 8)}`,
+            type: "userMessage"
+          },
+          {
+            id: `item_agent_${randomUUID().slice(0, 8)}`,
+            phase: "message",
+            text: assistantText,
+            type: "agentMessage"
+          }
+        ],
+        startedAt: timestamp,
+        status: "completed",
+        updatedAt: timestamp
+      };
+      return {
+        ...thread,
+        cwd: thread.cwd || threadCwd,
+        preview: assistantText,
+        status: "idle",
+        turns: [...(thread.turns || []), turn],
+        updatedAt: timestamp
+      };
+    });
+
+    const watcher = watchersByThreadId.get(nextThreadId);
+    watcher?.onNotification?.({
+      method: "turn/started",
+      params: {
+        threadId: nextThreadId,
+        turn: {
+          id: turnId
+        }
+      }
+    });
+    watcher?.onNotification?.({
+      method: "turn/completed",
+      params: {
+        threadId: nextThreadId,
+        turn: {
+          id: turnId
+        }
+      }
+    });
+
+    return {
+      mode: "start",
+      snapshot: mapThreadToCompanionSnapshot(nextThread, { limit: 60 }),
+      thread: summarizeThread(nextThread),
+      turn: {
+        id: turnId,
+        status: "completed"
+      }
+    };
+  }
+
+  async function interruptTurn() {
+    return { ok: true };
+  }
+
+  async function watchThread({
+    threadId,
+    onClose,
+    onReady
+  } = {}) {
+    let closed = false;
+    const watcher = {
+      close() {
+        if (closed) {
+          return;
+        }
+        closed = true;
+        watchersByThreadId.delete(threadId);
+        onClose?.();
+      },
+      onClose,
+      onNotification() {},
+      onReady,
+      onServerRequest() {},
+      respond() {},
+      respondError() {}
+    };
+
+    watchersByThreadId.set(threadId, watcher);
+    queueMicrotask(() => {
+      if (!closed) {
+        onReady?.();
+      }
+    });
+
+    return watcher;
+  }
+
+  return {
+    async dispose() {},
+    async ensureStarted() {},
+    getLatestThreadForCwd,
+    getStatus() {
+      return {
+        binaryPath,
+        lastError: null,
+        listenUrl,
+        pid: 0,
+        readyUrl: "http://fake-codex-app-server/readyz",
+        started: true,
+        startupLogs: ["fake bridge ready"]
+      };
+    },
+    async interruptTurn(args) {
+      return interruptTurn(args);
+    },
+    listThreads,
+    readThread,
+    async resumeThread(threadId) {
+      return summarizeThread(await readThread(threadId));
+    },
+    async rpc() {
+      throw new Error("Fake bridge does not expose raw RPC.");
+    },
+    async runTurnSession() {
+      throw new Error("Fake bridge does not expose raw turn sessions.");
+    },
+    sendText,
+    startThread,
+    async startTurn() {
+      throw new Error("Fake bridge does not expose startTurn directly.");
+    },
+    async steerTurn() {
+      throw new Error("Fake bridge does not expose steerTurn directly.");
+    },
+    watchThread,
+    async waitForTurnCompletion() {
+      return { status: "completed" };
+    }
+  };
+}

package/src/lib/install-preflight.mjs

@@ -0,0 +1,373 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+
+import { buildDiscoveryLinks } from "./discovery-docs.mjs";
+
+function pluralize(count, singular, plural = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+function workspaceLabel(cwd) {
+  const parts = String(cwd || "")
+    .split("/")
+    .filter(Boolean);
+  return parts.length ? parts.slice(-2).join("/") : cwd || "this workspace";
+}
+
+function localBaseUrl(host, port) {
+  const normalizedHost = String(host || "127.0.0.1").trim() || "127.0.0.1";
+  const displayHost = normalizedHost === "0.0.0.0" ? "127.0.0.1" : normalizedHost;
+  return `http://${displayHost}:${port}`;
+}
+
+function normalizeStartupError(message, binaryPath) {
+  const text = String(message || "").trim();
+  if (!text) {
+    return "";
+  }
+
+  if (/ENOENT/i.test(text)) {
+    return `Could not launch Codex from ${binaryPath}. Install Codex or set DEXTUNNEL_CODEX_BINARY.`;
+  }
+
+  if (/Timed out waiting for codex app-server readiness\./i.test(text)) {
+    return "Codex was found, but app-server did not become ready in time.";
+  }
+
+  return text;
+}
+
+export function resolveCodexBinary(
+  binaryPath,
+  {
+    accessSyncImpl = accessSync,
+    spawnSyncImpl = spawnSync
+  } = {}
+) {
+  const configuredPath = String(binaryPath || "").trim();
+  if (!configuredPath) {
+    return {
+      configuredPath: "",
+      error: "No Codex binary is configured.",
+      found: false,
+      resolvedPath: null,
+      source: "missing"
+    };
+  }
+
+  const explicitPath = configuredPath.includes("/") || configuredPath.startsWith(".");
+  if (explicitPath) {
+    try {
+      accessSyncImpl(configuredPath, constants.X_OK);
+      return {
+        configuredPath,
+        error: null,
+        found: true,
+        resolvedPath: configuredPath,
+        source: "explicit"
+      };
+    } catch {
+      return {
+        configuredPath,
+        error: `Configured Codex binary is not executable: ${configuredPath}`,
+        found: false,
+        resolvedPath: null,
+        source: "explicit"
+      };
+    }
+  }
+
+  const locator = process.platform === "win32" ? "where" : "which";
+  try {
+    const result = spawnSyncImpl(locator, [configuredPath], {
+      encoding: "utf8"
+    });
+    const resolvedPath = String(result?.stdout || "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find(Boolean) || null;
+    if (result?.status === 0 && resolvedPath) {
+      return {
+        configuredPath,
+        error: null,
+        found: true,
+        resolvedPath,
+        source: "path"
+      };
+    }
+  } catch {
+    // Fall through to the consistent not-found payload.
+  }
+
+  return {
+    configuredPath,
+    error: `Could not find '${configuredPath}' on PATH.`,
+    found: false,
+    resolvedPath: null,
+    source: "path"
+  };
+}
+
+export async function checkReadyUrl(
+  readyUrl,
+  {
+    fetchImpl = fetch,
+    timeoutMs = 1500
+  } = {}
+) {
+  const target = String(readyUrl || "").trim();
+  if (!target) {
+    return {
+      error: "No app-server readiness URL is configured.",
+      ok: false,
+      statusCode: null
+    };
+  }
+
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+  try {
+    const response = await fetchImpl(target, {
+      method: "GET",
+      signal: controller?.signal
+    });
+    return {
+      error: response.ok ? null : `Codex app-server readiness returned HTTP ${response.status}.`,
+      ok: response.ok,
+      statusCode: response.status
+    };
+  } catch (error) {
+    return {
+      error:
+        error?.name === "AbortError"
+          ? "Timed out waiting for Codex app-server readiness."
+          : String(error?.message || error || "Unknown readiness failure."),
+      ok: false,
+      statusCode: null
+    };
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+function buildNextSteps({
+  appServerHealthy,
+  baseUrl,
+  binary,
+  host,
+  workspace
+}) {
+  if (!binary.found) {
+    return [
+      "Install Codex locally or set DEXTUNNEL_CODEX_BINARY to the Codex CLI path.",
+      "Run npm run doctor again once Codex is available.",
+      `Then open ${baseUrl}/.`
+    ];
+  }
+
+  if (!appServerHealthy) {
+    return [
+      "Make sure the configured Codex binary can launch app-server on this machine.",
+      "If Codex is installed elsewhere, set DEXTUNNEL_CODEX_BINARY to the full executable path.",
+      "Run npm run doctor again after fixing the Codex binary path."
+    ];
+  }
+
+  if (workspace.hasThreadForCwd === false) {
+    return [
+      `Open Codex in ${workspace.label} once so Dextunnel has a thread to follow.`,
+      "Refresh this page or rerun npm run doctor after the thread appears.",
+      `Then open ${baseUrl}/.`
+    ];
+  }
+
+  return [
+    `Open ${baseUrl}/.`,
+    host === "127.0.0.1"
+      ? "Use npm run start:network when you want phone or tablet access over LAN or Tailscale."
+      : "This server is already bound beyond loopback for another device on your local network.",
+    "Run npm run doctor any time you want to re-check the local setup."
+  ];
+}
+
+function buildSummary({
+  appServerHealthy,
+  binary,
+  workspace
+}) {
+  if (!binary.found) {
+    return "Dextunnel cannot find a usable Codex binary yet.";
+  }
+
+  if (!appServerHealthy) {
+    return "Dextunnel found Codex, but app-server is not ready yet.";
+  }
+
+  if (workspace.hasThreadForCwd === false) {
+    return "Codex is reachable, but this workspace does not have a visible thread yet.";
+  }
+
+  if (workspace.cwdThreadCount > 0) {
+    return `Dextunnel is ready. Found ${pluralize(workspace.cwdThreadCount, "thread")} for ${workspace.label}.`;
+  }
+
+  return "Dextunnel is ready. Open the remote and pick a live Codex thread.";
+}
+
+function buildChecks({
+  appServer,
+  appServerHealthy,
+  binary,
+  host,
+  runtimeProfile,
+  workspace
+}) {
+  return [
+    {
+      detail: binary.found
+        ? `Using ${binary.resolvedPath || binary.configuredPath}.`
+        : binary.error,
+      id: "binary",
+      label: "Codex binary",
+      severity: binary.found ? "ready" : "error"
+    },
+    {
+      detail: appServerHealthy
+        ? `Ready at ${appServer.readyUrl}.`
+        : appServer.error || "Codex app-server is not reachable yet.",
+      id: "app-server",
+      label: "Codex app-server",
+      severity: appServerHealthy ? "ready" : "error"
+    },
+    {
+      detail:
+        workspace.hasThreadForCwd === null
+          ? `Checking ${workspace.label}...`
+          : workspace.hasThreadForCwd
+            ? `${pluralize(workspace.cwdThreadCount, "thread")} visible for ${workspace.label}.`
+            : `No visible Codex thread for ${workspace.label} yet.`,
+      id: "workspace",
+      label: "Current workspace",
+      severity:
+        workspace.hasThreadForCwd === null
+          ? "warning"
+          : workspace.hasThreadForCwd
+            ? "ready"
+            : "warning"
+    },
+    {
+      detail:
+        host === "127.0.0.1"
+          ? "Loopback-only by default. Use npm run start:network for phone or tablet access."
+          : `Bound on ${host} for another device on your local network.`,
+      id: "access",
+      label: "Access mode",
+      severity: "ready"
+    },
+    {
+      detail: `Using the ${runtimeProfile} runtime profile.`,
+      id: "profile",
+      label: "Runtime profile",
+      severity: "ready"
+    }
+  ];
+}
+
+export async function buildInstallPreflight({
+  codexAppServer,
+  cwd = process.cwd(),
+  runtimeConfig = {},
+  warmup = true,
+  checkReady = checkReadyUrl,
+  resolveBinary = resolveCodexBinary
+} = {}) {
+  if (!codexAppServer?.getStatus || !codexAppServer?.listThreads) {
+    throw new Error("buildInstallPreflight requires a Codex app-server bridge.");
+  }
+
+  const bridgeStatusBefore = codexAppServer.getStatus();
+  const binary = resolveBinary(runtimeConfig.codexBinaryPath || bridgeStatusBefore.binaryPath || "");
+
+  let threads = null;
+  let warmupError = "";
+  if (warmup) {
+    try {
+      threads = await codexAppServer.listThreads({
+        archived: false,
+        limit: 50
+      });
+    } catch (error) {
+      warmupError = normalizeStartupError(error?.message, binary.configuredPath || bridgeStatusBefore.binaryPath || "codex");
+    }
+  }
+
+  const bridgeStatus = codexAppServer.getStatus();
+  const ready = await checkReady(bridgeStatus.readyUrl);
+  const appServerHealthy = Boolean(ready.ok || threads);
+  const workspaceThreads = Array.isArray(threads)
+    ? threads.filter((thread) => thread?.cwd === cwd)
+    : null;
+  const workspace = {
+    cwd,
+    cwdThreadCount: workspaceThreads?.length ?? null,
+    hasThreadForCwd: workspaceThreads == null ? null : workspaceThreads.length > 0,
+    label: workspaceLabel(cwd),
+    threadCount: Array.isArray(threads) ? threads.length : null
+  };
+  const appServer = {
+    error:
+      normalizeStartupError(bridgeStatus.lastError, binary.configuredPath || bridgeStatus.binaryPath || "codex") ||
+      warmupError ||
+      ready.error ||
+      null,
+    healthy: appServerHealthy,
+    lastError: bridgeStatus.lastError || null,
+    listenUrl: bridgeStatus.listenUrl || runtimeConfig.appServerListenUrl || "",
+    pid: bridgeStatus.pid || null,
+    ready: Boolean(ready.ok),
+    readyUrl: bridgeStatus.readyUrl || "",
+    started: Boolean(bridgeStatus.started),
+    startupLogTail: Array.isArray(bridgeStatus.startupLogs) ? bridgeStatus.startupLogs.slice(-4) : [],
+    warmupAttempted: Boolean(warmup),
+    warmupOk: Array.isArray(threads)
+  };
+  const baseUrl = localBaseUrl(runtimeConfig.host || "127.0.0.1", runtimeConfig.port || 4317);
+  const status = !binary.found || !appServerHealthy ? "error" : workspace.hasThreadForCwd ? "ready" : "warning";
+
+  return {
+    appServer,
+    checks: buildChecks({
+      appServer,
+      appServerHealthy,
+      binary,
+      host: runtimeConfig.host || "127.0.0.1",
+      runtimeProfile: runtimeConfig.runtimeProfile || "default",
+      workspace
+    }),
+    codexBinary: binary,
+    links: buildDiscoveryLinks({ baseUrl }),
+    nextSteps: buildNextSteps({
+      appServerHealthy,
+      baseUrl,
+      binary,
+      host: runtimeConfig.host || "127.0.0.1",
+      workspace
+    }),
+    runtime: {
+      appServerListenUrl: runtimeConfig.appServerListenUrl || bridgeStatus.listenUrl || "",
+      baseUrl,
+      host: runtimeConfig.host || "127.0.0.1",
+      port: runtimeConfig.port || 4317,
+      runtimeProfile: runtimeConfig.runtimeProfile || "default"
+    },
+    status,
+    summary: buildSummary({
+      appServerHealthy,
+      binary,
+      workspace
+    }),
+    workspace
+  };
+}