dextunnel 0.1.0

package/public/surface-view-state.js

@@ -0,0 +1,89 @@
+export function createSurfaceViewState({
+  defaults = {},
+  scopeId = "",
+  surface = "surface",
+  storage = globalThis?.localStorage
+} = {}) {
+  const normalizedSurface = String(surface || "surface").trim().toLowerCase() || "surface";
+  const normalizedScope = String(scopeId || "").trim() || "default";
+
+  function key(kind, suffix = "") {
+    return `dextunnel:view:${normalizedSurface}:${normalizedScope}:${kind}${suffix ? `:${suffix}` : ""}`;
+  }
+
+  function readJson(storageKey, fallback) {
+    if (!storage) {
+      return fallback;
+    }
+
+    try {
+      const raw = storage.getItem(storageKey);
+      if (!raw) {
+        return fallback;
+      }
+      return JSON.parse(raw);
+    } catch {
+      return fallback;
+    }
+  }
+
+  function writeJson(storageKey, value) {
+    if (!storage) {
+      return;
+    }
+
+    try {
+      storage.setItem(storageKey, JSON.stringify(value));
+    } catch {
+      // Best effort only.
+    }
+  }
+
+  return {
+    loadExpansionMode(threadId = "none") {
+      const parsed = readJson(key("expansion-mode", String(threadId || "none")), defaults.expansionMode || "compact");
+      return parsed === "expanded" ? "expanded" : "compact";
+    },
+    loadSidebarMode() {
+      const parsed = readJson(key("sidebar-mode"), defaults.sidebarMode || "expanded");
+      return parsed === "collapsed" ? "collapsed" : "expanded";
+    },
+    loadExpandedSections(threadId = "none") {
+      const parsed = readJson(key("expanded", String(threadId || "none")), []);
+      return Array.isArray(parsed)
+        ? parsed.map((value) => String(value || "").trim()).filter(Boolean)
+        : [];
+    },
+    loadFilters() {
+      const parsed = readJson(key("filters"), defaults.filters || {});
+      if (!parsed || typeof parsed !== "object") {
+        return { ...(defaults.filters || {}) };
+      }
+
+      const next = { ...(defaults.filters || {}) };
+      for (const [name, fallback] of Object.entries(defaults.filters || {})) {
+        next[name] = typeof parsed[name] === "boolean" ? parsed[name] : fallback;
+      }
+      return next;
+    },
+    saveExpandedSections(threadId = "none", keys = []) {
+      writeJson(
+        key("expanded", String(threadId || "none")),
+        [...new Set(keys.map((value) => String(value || "").trim()).filter(Boolean))]
+      );
+    },
+    saveExpansionMode(threadId = "none", mode = "compact") {
+      writeJson(key("expansion-mode", String(threadId || "none")), mode === "expanded" ? "expanded" : "compact");
+    },
+    saveSidebarMode(mode = "expanded") {
+      writeJson(key("sidebar-mode"), mode === "collapsed" ? "collapsed" : "expanded");
+    },
+    saveFilters(filters = {}) {
+      const next = {};
+      for (const [name, fallback] of Object.entries(defaults.filters || {})) {
+        next[name] = typeof filters[name] === "boolean" ? filters[name] : fallback;
+      }
+      writeJson(key("filters"), next);
+    }
+  };
+}

package/public/voice-dictation.js

@@ -0,0 +1,45 @@
+export function getSpeechRecognitionCtor(root = globalThis) {
+  if (!root || typeof root !== "object") {
+    return null;
+  }
+
+  return root.SpeechRecognition || root.webkitSpeechRecognition || null;
+}
+
+export function normalizeDictationText(value = "") {
+  return String(value || "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function composeDictationDraft({
+  baseText = "",
+  committedText = "",
+  interimText = ""
+} = {}) {
+  const parts = [
+    normalizeDictationText(baseText),
+    normalizeDictationText(committedText),
+    normalizeDictationText(interimText)
+  ].filter(Boolean);
+
+  return parts.join(" ");
+}
+
+export function speechRecognitionErrorMessage(code = "") {
+  switch (String(code || "").trim()) {
+    case "aborted":
+      return "Voice memo cancelled.";
+    case "audio-capture":
+      return "No microphone is available.";
+    case "network":
+      return "Voice memo failed because speech recognition lost network access.";
+    case "not-allowed":
+    case "service-not-allowed":
+      return "Microphone access is blocked. Allow it and try again.";
+    case "no-speech":
+      return "No speech detected. Try again.";
+    default:
+      return "Voice memo failed. Try again.";
+  }
+}

package/src/bin/desktop-rehydration-smoke.mjs

@@ -0,0 +1,111 @@
+import process from "node:process";
+
+import { runDesktopRehydrationSmoke } from "../lib/desktop-rehydration-smoke.mjs";
+
+function printUsage() {
+  console.log("Usage: node src/bin/desktop-rehydration-smoke.mjs --thread-id <id> [--cwd <path>] [--skip-probe] [--json]");
+}
+
+function parseArgs(argv) {
+  const options = {
+    cwd: process.cwd(),
+    includeProbe: true,
+    json: false,
+    threadId: null
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--thread-id") {
+      options.threadId = argv[index + 1] || null;
+      index += 1;
+      continue;
+    }
+    if (value === "--cwd") {
+      options.cwd = argv[index + 1] || process.cwd();
+      index += 1;
+      continue;
+    }
+    if (value === "--skip-probe") {
+      options.includeProbe = false;
+      continue;
+    }
+    if (value === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (value === "--help" || value === "-h") {
+      options.help = true;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${value}`);
+  }
+
+  return options;
+}
+
+function printTextReport(report) {
+  console.log(`Desktop rehydration smoke for thread ${report.threadId}`);
+  console.log(`cwd: ${report.cwd}`);
+  console.log("");
+  if (report.probe.included) {
+    console.log(`Probe: ${report.probe.status}`);
+    console.log(`- prompt: ${report.probe.prompt}`);
+    console.log(`- ack: ${report.probe.ack}`);
+    if (report.probe.turnId) {
+      console.log(`- turn: ${report.probe.turnId} (${report.probe.turnStatus || "unknown"})`);
+    }
+    if (report.probe.included) {
+      console.log(`- prompt visible in app-server readback: ${report.probe.promptVisible === true ? "yes" : report.probe.promptVisible === false ? "no" : "n/a"}`);
+      console.log(`- ack visible in app-server readback: ${report.probe.ackVisible === true ? "yes" : report.probe.ackVisible === false ? "no" : "n/a"}`);
+    }
+    console.log("");
+  }
+
+  console.log("Attempts:");
+  for (const attempt of report.attempts) {
+    console.log(`- [${attempt.status}] ${attempt.label}`);
+    console.log(`  expected desktop outcome: ${attempt.expectedDesktopOutcome}`);
+    if (attempt.detail) {
+      console.log(`  detail: ${attempt.detail}`);
+    }
+  }
+
+  console.log("");
+  console.log("Manual checks:");
+  for (const check of report.manualChecks) {
+    console.log(`- ${check}`);
+  }
+}
+
+let options;
+try {
+  options = parseArgs(process.argv.slice(2));
+} catch (error) {
+  console.error(error.message);
+  printUsage();
+  process.exit(1);
+}
+
+if (options.help) {
+  printUsage();
+  process.exit(0);
+}
+
+if (!options.threadId) {
+  printUsage();
+  process.exit(1);
+}
+
+const report = await runDesktopRehydrationSmoke({
+  cwd: options.cwd,
+  includeProbe: options.includeProbe,
+  threadId: options.threadId
+});
+
+if (options.json) {
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(0);
+}
+
+printTextReport(report);

package/src/bin/dextunnel.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import {
+  packageJsonPathFromImportMetaUrl,
+  parseDextunnelCli,
+  readPackageVersion,
+  renderHelp
+} from "../lib/dextunnel-cli.mjs";
+
+const version = readPackageVersion({
+  packageJsonPath: packageJsonPathFromImportMetaUrl(import.meta.url)
+});
+
+try {
+  const command = parseDextunnelCli(process.argv.slice(2), { version });
+
+  switch (command.kind) {
+    case "help":
+      console.log(command.text);
+      break;
+    case "version":
+      console.log(command.text);
+      break;
+    case "doctor":
+      await import("./doctor.mjs");
+      break;
+    case "serve":
+      Object.assign(process.env, command.env);
+      await import("../server.mjs");
+      break;
+    default:
+      console.error(renderHelp({ version }));
+      process.exitCode = 1;
+      break;
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  console.error("");
+  console.error(renderHelp({ version }));
+  process.exitCode = 1;
+}

package/src/bin/doctor.mjs

@@ -0,0 +1,48 @@
+import { createCodexAppServerBridge } from "../lib/codex-app-server-client.mjs";
+import { buildInstallPreflight } from "../lib/install-preflight.mjs";
+import { createRuntimeConfig } from "../lib/runtime-config.mjs";
+
+const runtimeConfig = createRuntimeConfig({
+  cwd: process.cwd(),
+  env: process.env,
+  importMetaUrl: import.meta.url
+});
+
+const bridge = createCodexAppServerBridge({
+  binaryPath: runtimeConfig.codexBinaryPath,
+  listenUrl: runtimeConfig.appServerListenUrl
+});
+
+try {
+  const preflight = await buildInstallPreflight({
+    codexAppServer: bridge,
+    cwd: runtimeConfig.cwd,
+    runtimeConfig,
+    warmup: true
+  });
+
+  console.log(`Dextunnel doctor: ${preflight.status.toUpperCase()}`);
+  console.log(preflight.summary);
+  console.log("");
+  for (const check of preflight.checks) {
+    console.log(`- ${check.label}: ${check.detail}`);
+  }
+
+  if (preflight.appServer.startupLogTail.length) {
+    console.log("");
+    console.log("Recent Codex startup log:");
+    for (const line of preflight.appServer.startupLogTail) {
+      console.log(`  ${line}`);
+    }
+  }
+
+  console.log("");
+  console.log("Next steps:");
+  for (const step of preflight.nextSteps) {
+    console.log(`- ${step}`);
+  }
+
+  process.exit(preflight.status === "error" ? 1 : 0);
+} finally {
+  await bridge.dispose();
+}

package/src/bin/launch-attest.mjs

@@ -0,0 +1,39 @@
+import {
+  clearLaunchAttestations,
+  computeLaunchFingerprint,
+  defaultLaunchStatusPath,
+  writeLaunchAttestation
+} from "../lib/launch-release-bar.mjs";
+
+const command = process.argv[2];
+const statusPath = defaultLaunchStatusPath();
+
+if (command === "clear") {
+  await clearLaunchAttestations({ statusPath });
+  console.log(`Cleared launch attestations at ${statusPath}`);
+  process.exit(0);
+}
+
+if (command !== "automated-pass" && command !== "manual-pass") {
+  console.error("Usage: node src/bin/launch-attest.mjs <automated-pass|manual-pass|clear>");
+  process.exit(1);
+}
+
+const kind = command === "automated-pass" ? "automated" : "manual";
+const fingerprint = computeLaunchFingerprint();
+const state = await writeLaunchAttestation({
+  kind,
+  statusPath,
+  fingerprint
+});
+
+console.log(
+  `${kind === "automated" ? "Recorded automated launch pass" : "Recorded manual launch pass"} for ${fingerprint.fingerprint}`
+);
+console.log(`Attestations: ${statusPath}`);
+if (state.automated) {
+  console.log(`Automated: ${state.automated.recordedAt}`);
+}
+if (state.manual) {
+  console.log(`Manual: ${state.manual.recordedAt}`);
+}

package/src/bin/launch-status.mjs

@@ -0,0 +1,49 @@
+import {
+  computeLaunchFingerprint,
+  defaultLaunchStatusPath,
+  deriveLaunchBar,
+  readLaunchAttestation
+} from "../lib/launch-release-bar.mjs";
+
+const json = process.argv.includes("--json");
+
+const statusPath = defaultLaunchStatusPath();
+const fingerprint = computeLaunchFingerprint();
+const state = await readLaunchAttestation({ statusPath });
+const payload = {
+  ...deriveLaunchBar({ fingerprint: fingerprint.fingerprint, state }),
+  fingerprint: fingerprint.fingerprint,
+  statusPath
+};
+
+if (json) {
+  console.log(JSON.stringify(payload, null, 2));
+  process.exit(0);
+}
+
+console.log(`Dextunnel local launch status: ${payload.status}`);
+console.log(payload.message);
+console.log("");
+console.log("Accepted limitations:");
+for (const line of payload.acceptedLimitations) {
+  console.log(`- ${line}`);
+}
+console.log("");
+console.log("Launch references:");
+for (const doc of payload.docs) {
+  console.log(`- ${doc}`);
+}
+console.log("");
+console.log("Attestation model:");
+console.log("- automated pass is recorded only by npm run launch:check for the current repo fingerprint");
+console.log("- manual pass is a human attestation recorded by npm run launch:attest-manual");
+console.log("");
+console.log("Manual checks:");
+for (const line of payload.requiredManualChecks) {
+  console.log(`- ${line}`);
+}
+
+if (payload.staleAutomated || payload.staleManual) {
+  console.log("");
+  console.log(`Attestations: ${payload.statusPath}`);
+}

package/src/bin/mobile-link-proxy.mjs

@@ -0,0 +1,221 @@
+import http from "node:http";
+import https from "node:https";
+import { once } from "node:events";
+import { URL } from "node:url";
+
+import {
+  resolveMobileNetworkProfile,
+  withNetworkJitter
+} from "../lib/mobile-network-profile.mjs";
+
+function printUsage() {
+  console.log(
+    "Usage: node src/bin/mobile-link-proxy.mjs --target-base-url http://127.0.0.1:4317 [--listen-port 4417] [--profile weak-mobile|weak-mobile-reconnect]"
+  );
+}
+
+function parseArgs(argv) {
+  const options = {
+    listenHost: "127.0.0.1",
+    listenPort: 4417,
+    profile: "weak-mobile",
+    targetBaseUrl: ""
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+    if (arg === "--target-base-url" && argv[index + 1]) {
+      options.targetBaseUrl = argv[index + 1];
+      index += 1;
+      continue;
+    }
+    if (arg === "--listen-port" && argv[index + 1]) {
+      options.listenPort = Number(argv[index + 1]) || options.listenPort;
+      index += 1;
+      continue;
+    }
+    if (arg === "--listen-host" && argv[index + 1]) {
+      options.listenHost = argv[index + 1] || options.listenHost;
+      index += 1;
+      continue;
+    }
+    if (arg === "--profile" && argv[index + 1]) {
+      options.profile = argv[index + 1] || options.profile;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (!options.targetBaseUrl) {
+    throw new Error("--target-base-url is required.");
+  }
+
+  const profile = resolveMobileNetworkProfile(options.profile);
+  if (!profile) {
+    throw new Error(`Unknown network profile: ${options.profile}`);
+  }
+
+  return {
+    ...options,
+    profile
+  };
+}
+
+function delay(ms) {
+  if (!ms || ms <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function readRequestBody(req) {
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+  return chunks.length ? Buffer.concat(chunks) : null;
+}
+
+async function pipeWithThrottle(readable, writable, bytesPerSecond, dropAfterMs = null) {
+  let dropped = false;
+  let dropTimer = null;
+
+  if (dropAfterMs && Number.isFinite(dropAfterMs) && dropAfterMs > 0) {
+    dropTimer = setTimeout(() => {
+      dropped = true;
+      try {
+        readable.destroy(new Error("Synthetic weak-network stream drop."));
+      } catch {
+        // Ignore teardown failures.
+      }
+      try {
+        writable.destroy();
+      } catch {
+        // Ignore teardown failures.
+      }
+    }, dropAfterMs);
+  }
+
+  try {
+    for await (const chunk of readable) {
+      if (dropped || writable.destroyed) {
+        return;
+      }
+      if (!writable.write(chunk)) {
+        await once(writable, "drain");
+      }
+      if (bytesPerSecond && bytesPerSecond > 0) {
+        const waitMs = Math.ceil((Buffer.byteLength(chunk) / bytesPerSecond) * 1000);
+        if (waitMs > 0) {
+          await delay(waitMs);
+        }
+      }
+    }
+    if (!writable.destroyed) {
+      writable.end();
+    }
+  } finally {
+    if (dropTimer) {
+      clearTimeout(dropTimer);
+    }
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const targetBaseUrl = new URL(options.targetBaseUrl);
+  const clientForTarget = targetBaseUrl.protocol === "https:" ? https : http;
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const body = await readRequestBody(req);
+      const requestDelayMs = withNetworkJitter(options.profile.requestDelayMs, options.profile.jitterMs);
+      const responseDelayMs = withNetworkJitter(options.profile.responseDelayMs, options.profile.jitterMs);
+      await delay(requestDelayMs);
+
+      const targetUrl = new URL(req.url || "/", targetBaseUrl);
+      const upstream = clientForTarget.request(targetUrl, {
+        headers: {
+          ...req.headers,
+          host: targetBaseUrl.host
+        },
+        method: req.method || "GET"
+      });
+
+      upstream.on("response", async (upstreamRes) => {
+        await delay(responseDelayMs);
+        const responseHeaders = { ...upstreamRes.headers };
+        delete responseHeaders["content-length"];
+        res.writeHead(upstreamRes.statusCode || 502, responseHeaders);
+        const isSse = String(upstreamRes.headers["content-type"] || "").includes("text/event-stream");
+        await pipeWithThrottle(
+          upstreamRes,
+          res,
+          options.profile.downstreamBytesPerSecond,
+          isSse ? options.profile.dropSseAfterMs : null
+        );
+      });
+
+      upstream.on("error", (error) => {
+        if (!res.headersSent) {
+          res.writeHead(502, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: error.message }));
+          return;
+        }
+        try {
+          res.destroy(error);
+        } catch {
+          // Ignore teardown failures.
+        }
+      });
+
+      if (body?.length) {
+        if (options.profile.upstreamBytesPerSecond > 0) {
+          const waitMs = Math.ceil((body.length / options.profile.upstreamBytesPerSecond) * 1000);
+          upstream.write(body);
+          if (waitMs > 0) {
+            await delay(waitMs);
+          }
+          upstream.end();
+        } else {
+          upstream.end(body);
+        }
+      } else {
+        upstream.end();
+      }
+    } catch (error) {
+      res.writeHead(500, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: error.message }));
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.listenPort, options.listenHost, resolve);
+  });
+
+  const proxyUrl = `http://${options.listenHost}:${options.listenPort}`;
+  console.log(
+    `[mobile-link-proxy] listening=${proxyUrl} target=${targetBaseUrl.origin} profile=${options.profile.name}`
+  );
+
+  function shutdown(code = 0) {
+    server.close(() => {
+      process.exit(code);
+    });
+  }
+
+  process.on("SIGINT", () => shutdown(0));
+  process.on("SIGTERM", () => shutdown(0));
+}
+
+main().catch((error) => {
+  console.error(`[mobile-link-proxy] failed: ${error.message}`);
+  process.exit(1);
+});
+