codex-webapp 0.1.0-beta.1

package/src/browserSmoke.js

@@ -0,0 +1,111 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+
+const DEFAULT_TEXT = "What should we build";
+const DEFAULT_MAX_RESPONSE_MS = 5_000;
+
+export function parseSmokeArgs(args = []) {
+  const screenshot = valueAfter(args, "--screenshot");
+  return {
+    url: valueAfter(args, "--url") ?? "http://127.0.0.1:8214/",
+    text: valueAfter(args, "--text") ?? DEFAULT_TEXT,
+    timeoutMs: Number(valueAfter(args, "--timeout-ms") ?? 10_000),
+    maxResponseMs: Number(valueAfter(args, "--max-response-ms") ?? DEFAULT_MAX_RESPONSE_MS),
+    browser: args.includes("--browser") || Boolean(screenshot),
+    screenshot,
+  };
+}
+
+export async function runSmoke(args = []) {
+  const options = parseSmokeArgs(args);
+  if (options.browser) {
+    await runBrowserSmokeWithOptions(options);
+    return;
+  }
+  await runHttpSmokeWithOptions(options);
+}
+
+export async function runHttpSmoke(args = []) {
+  await runHttpSmokeWithOptions(parseSmokeArgs(args));
+}
+
+export async function runBrowserSmoke(args = []) {
+  await runBrowserSmokeWithOptions(parseSmokeArgs(args));
+}
+
+async function runHttpSmokeWithOptions(options) {
+  const started = performance.now();
+  const response = await fetch(options.url, {
+    signal: AbortSignal.timeout(options.timeoutMs),
+  });
+  const elapsedMs = Math.round(performance.now() - started);
+  if (!response.ok) {
+    throw new Error(`HTTP smoke returned ${response.status} for ${options.url}`);
+  }
+  const text = await response.text();
+  if (!text.includes(options.text)) {
+    throw new Error(`HTTP smoke could not find visible text: ${options.text}`);
+  }
+  if (elapsedMs > options.maxResponseMs) {
+    throw new Error(
+      `HTTP smoke exceeded response budget: ${elapsedMs}ms > ${options.maxResponseMs}ms`,
+    );
+  }
+  console.log(`HTTP smoke passed: ${options.url}`);
+  console.log(`Found text: ${options.text}`);
+  console.log(`Response time: ${elapsedMs}ms (budget ${options.maxResponseMs}ms)`);
+  console.log("For screenshot evidence, rerun with --browser --screenshot <path>.");
+}
+
+async function runBrowserSmokeWithOptions(options) {
+  const playwright = await loadPlaywright();
+  const browser = await playwright.chromium.launch({ headless: true });
+  try {
+    const page = await browser.newPage({ viewport: { width: 390, height: 844 } });
+    await page.goto(options.url, {
+      waitUntil: "networkidle",
+      timeout: options.timeoutMs,
+    });
+    await page.getByText(options.text, { exact: false }).waitFor({
+      timeout: options.timeoutMs,
+    });
+    if (options.screenshot) {
+      await page.screenshot({
+        path: resolve(options.screenshot),
+        fullPage: true,
+      });
+    }
+    console.log(`Browser smoke passed: ${options.url}`);
+    console.log(`Visible text: ${options.text}`);
+  } finally {
+    await browser.close();
+  }
+}
+
+async function loadPlaywright() {
+  try {
+    return await import("playwright");
+  } catch {
+    const requireFromCwd = createRequire(resolve(process.cwd(), "package.json"));
+    try {
+      return requireFromCwd("playwright");
+    } catch {
+      throw new Error(
+        [
+          "Playwright is required for browser smoke checks.",
+          "",
+          "Install it in this project:",
+          "  npm install -D playwright",
+          "  npx playwright install chromium",
+        ].join("\n"),
+      );
+    }
+  }
+}
+
+function valueAfter(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  return value && !value.startsWith("--") ? value : undefined;
+}

package/src/codexWeb.js

@@ -0,0 +1,48 @@
+export const CODEX_WEB_UPSTREAM = "github:0xcaff/codex-web";
+export const CODEX_WEB_COMMIT = "585613f5a3a355af5aefc388ca4e31b07a472cda";
+export const CODEX_WEB_REFERENCE = `${CODEX_WEB_UPSTREAM}#${CODEX_WEB_COMMIT}`;
+export const DEFAULT_WEB_HOST = "127.0.0.1";
+export const DEFAULT_WEB_PORT = 8214;
+
+export function parseStartArgs(args = []) {
+  return {
+    dryRun: args.includes("--dry-run"),
+    yes: args.includes("--yes"),
+    allowNonLoopback: args.includes("--allow-non-loopback"),
+    host: valueAfter(args, "--host") ?? DEFAULT_WEB_HOST,
+    port: Number(valueAfter(args, "--port") ?? valueAfter(args, "--ui-port") ?? DEFAULT_WEB_PORT),
+  };
+}
+
+export function buildWebUrl({ host = DEFAULT_WEB_HOST, port = DEFAULT_WEB_PORT } = {}) {
+  return `http://${host}:${port}/`;
+}
+
+export function assertSafeHost(host, { allowNonLoopback = false } = {}) {
+  if (allowNonLoopback || isLoopbackHost(host)) return;
+  throw new Error(
+    "Refusing to bind codex-web to a non-loopback host without --allow-non-loopback. Put Tailscale, Cloudflare Access, WireGuard, SSH tunneling, or an equivalent trusted boundary in front before remote access.",
+  );
+}
+
+export function buildCodexWebNpxArgs({ host = DEFAULT_WEB_HOST, port = DEFAULT_WEB_PORT } = {}) {
+  return [
+    "--yes",
+    CODEX_WEB_REFERENCE,
+    "--host",
+    host,
+    "--port",
+    String(port),
+  ];
+}
+
+export function isLoopbackHost(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+
+function valueAfter(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  return value && !value.startsWith("--") ? value : undefined;
+}

package/src/commands.js

@@ -0,0 +1,193 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+import {
+  compareVersions,
+  extractVersion,
+  MIN_CODEX_VERSION,
+} from "./version.js";
+import { runSmoke } from "./browserSmoke.js";
+import {
+  CODEX_WEB_REFERENCE,
+  assertSafeHost,
+  buildCodexWebNpxArgs,
+  buildWebUrl,
+  parseStartArgs,
+} from "./codexWeb.js";
+
+const BANNER = "Codex WebApp — unofficial OpenAI Codex companion; not endorsed by OpenAI.";
+
+export function main(argv = process.argv) {
+  const command = argv[2] ?? "help";
+  if (command === "doctor") {
+    doctor();
+    return;
+  }
+  if (command === "start") {
+    start(argv.slice(3)).catch((error) => {
+      fail([
+        "Start failed.",
+        String(error?.message ?? error),
+      ]);
+    });
+    return;
+  }
+  if (command === "smoke") {
+    runSmoke(argv.slice(3)).catch((error) => {
+      fail([
+        "Smoke failed.",
+        String(error?.message ?? error),
+        "",
+        "Check that the UI server is running and that the URL is reachable.",
+      ]);
+    });
+    return;
+  }
+  help();
+}
+
+export function doctor() {
+  const codex = spawnSync("codex", ["--version"], { encoding: "utf8" });
+  const codexPath = resolveCodexPath();
+  if (codex.error || codex.status !== 0) {
+    fail([
+      "Codex CLI was not found.",
+      "",
+      "Install or update Codex first:",
+      "  npm install -g @openai/codex",
+      "",
+      "Then run:",
+      "  npx codex-webapp doctor",
+    ]);
+  }
+
+  const versionText = `${codex.stdout}${codex.stderr}`.trim();
+  const version = extractVersion(versionText);
+  if (!version || compareVersions(version, MIN_CODEX_VERSION) < 0) {
+    fail([
+      `Codex CLI ${MIN_CODEX_VERSION}+ is required for remote-control.`,
+      `Detected: ${versionText || "unknown"}`,
+      "",
+      "Update Codex:",
+      "  npm install -g @openai/codex@latest",
+      "",
+      "Then verify:",
+      "  codex remote-control --help",
+    ]);
+  }
+
+  const helpResult = spawnSync("codex", ["remote-control", "--help"], {
+    encoding: "utf8",
+  });
+  if (helpResult.status !== 0) {
+    fail([
+      "`codex remote-control --help` did not run successfully.",
+      "",
+      "Codex is installed, but this CLI may not include remote-control yet.",
+      "Update Codex and try again:",
+      "  npm install -g @openai/codex@latest",
+    ]);
+  }
+
+  ok([
+    BANNER,
+    `Codex CLI is ready: ${versionText}`,
+    `Codex executable: ${codexPath || "unknown"}`,
+    "`codex remote-control` is available.",
+    `codex-web reference: ${CODEX_WEB_REFERENCE}`,
+    "Next:",
+    "  npx codex-webapp start",
+  ]);
+}
+
+export async function start(args = []) {
+  const options = parseStartArgs(args);
+  const check = spawnSync("codex", ["remote-control", "--help"], {
+    encoding: "utf8",
+  });
+  if (check.status !== 0) {
+    fail([
+      "Cannot start because `codex remote-control` is unavailable.",
+      "Run:",
+      "  npx codex-webapp doctor",
+    ]);
+  }
+
+  assertSafeHost(options.host, { allowNonLoopback: options.allowNonLoopback });
+  const plannedWebUrl = buildWebUrl({ host: options.host, port: options.port });
+  const npxArgs = buildCodexWebNpxArgs({
+    host: options.host,
+    port: options.port,
+  });
+
+  if (options.dryRun) {
+    ok([
+      BANNER,
+      "Dry run passed.",
+      `Would start codex-web: ${plannedWebUrl}`,
+      "Would start:",
+      `  npx ${npxArgs.join(" ")}`,
+    ]);
+    return;
+  }
+
+  if (!options.yes) {
+    console.log(BANNER);
+    console.log(`About to start codex-web: ${plannedWebUrl}`);
+    console.log("Default expectation: keep it on localhost or behind Tailscale, Cloudflare Access, or an equivalent trusted boundary.");
+    console.log("Anyone who can reach this URL can operate Codex on this host.");
+    const rl = createInterface({ input, output });
+    const answer = await rl.question("Continue? Type 'yes' to start: ");
+    rl.close();
+    if (answer.trim().toLowerCase() !== "yes") {
+      console.log("Canceled.");
+      return;
+    }
+  }
+
+  console.log(`Starting codex-web from ${CODEX_WEB_REFERENCE}...`);
+  console.log(`Open: ${plannedWebUrl}`);
+  console.log("Keep this terminal open. Expose it only through a trusted local, Tailscale, Cloudflare Access, or equivalent boundary.");
+  const child = spawn("npx", npxArgs, { stdio: "inherit" });
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
+export function help() {
+  console.log(`${BANNER}
+
+Commands:
+  codex-webapp doctor       Check Codex CLI >= ${MIN_CODEX_VERSION}
+  codex-webapp start        Confirm, then start codex-web
+  codex-webapp start --dry-run
+  codex-webapp start --yes  Start without the confirmation prompt
+  codex-webapp start --port 8214
+  codex-webapp start --host 127.0.0.1
+  codex-webapp start --allow-non-loopback
+  codex-webapp smoke --url http://127.0.0.1:8214/
+  codex-webapp smoke --browser --screenshot artifacts/codex-webapp.png
+
+Quick start:
+  npx codex-webapp doctor
+`);
+}
+
+function ok(lines) {
+  for (const line of lines) console.log(line);
+}
+
+function fail(lines) {
+  console.error(BANNER);
+  for (const line of lines) console.error(line);
+  process.exit(1);
+}
+
+export function resolveCodexPath() {
+  const result = spawnSync("bash", ["-lc", "command -v codex"], {
+    encoding: "utf8",
+  });
+  if (result.status !== 0) return "";
+  return result.stdout.trim();
+}

package/src/version.js

@@ -0,0 +1,27 @@
+export const MIN_CODEX_VERSION = "0.130.0";
+
+export function extractVersion(text) {
+  const match = String(text ?? "").match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? match[0] : null;
+}
+
+export function compareVersions(left, right) {
+  const a = numericParts(left);
+  const b = numericParts(right);
+  for (let i = 0; i < 3; i += 1) {
+    if ((a[i] ?? 0) > (b[i] ?? 0)) return 1;
+    if ((a[i] ?? 0) < (b[i] ?? 0)) return -1;
+  }
+  return 0;
+}
+
+export function isRemoteControlReady(versionText) {
+  const version = extractVersion(versionText);
+  return Boolean(version && compareVersions(version, MIN_CODEX_VERSION) >= 0);
+}
+
+function numericParts(version) {
+  const normalized = extractVersion(version);
+  if (!normalized) return [0, 0, 0];
+  return normalized.split(".").map((part) => Number(part));
+}