@upturtle/wizard 0.2.1 → 0.2.3

package/README.md

@@ -8,7 +8,7 @@ npx @upturtle/wizard
 
 The installer:
 
-1. Detects which coding agent(s) you have installed (Claude Code, Cursor, Antigravity, OpenCode, Zed, Claude Desktop).
+1. Detects which coding agent(s) you have installed (Claude Code, Cursor, OpenAI Codex CLI, Antigravity, OpenCode, Zed, Claude Desktop).
 2. Shows a checkbox list — `↑`/`↓` to move, space to toggle, `a` to toggle all, enter to confirm.
 3. Opens UpTurtle in your browser to authenticate and mint a scoped personal access token.
 4. Writes the MCP server entry into each selected agent's config.
@@ -23,7 +23,7 @@ By default the wizard writes to your **user-wide** config — the MCP server is
 npx @upturtle/wizard --project
 ```
 
-Project scope is supported for `claude-code`, `cursor`, `opencode`, and `zed`. Antigravity and Claude Desktop don't have a project-level config format.
+Project scope is supported for `claude-code`, `cursor`, `opencode`, and `zed`. Antigravity, Codex CLI, and Claude Desktop don't have a project-level config format.
 
 ## Flags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upturtle/wizard",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Connects your coding agent to UpTurtle's MCP server. Detects the agent, mints a scoped PAT via browser handshake, and writes the right MCP config.",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
     "README.md"
   ],
   "scripts": {
-    "start": "node src/cli.mjs"
+    "start": "node src/cli.mjs",
+    "test": "node --test test/*.test.mjs"
   },
   "engines": {
     "node": ">=18"

package/src/agents.mjs

@@ -14,6 +14,13 @@ export const AGENTS = [
     writer: "claude-code",
     scopes: ["user", "project"],
   },
+  {
+    id: "codex",
+    label: "OpenAI Codex CLI",
+    detect: () => isOnPath("codex") || existsSync(codexConfigPath()),
+    writer: "codex",
+    scopes: ["user"],
+  },
   {
     id: "cursor",
     label: "Cursor",
@@ -78,6 +85,10 @@ export function antigravityConfigPath() {
   return join(homedir(), ".gemini", "antigravity", "mcp_config.json");
 }
 
+export function codexConfigPath() {
+  return join(homedir(), ".codex", "config.toml");
+}
+
 export function opencodeConfigPath() {
   return join(homedir(), ".config", "opencode", "opencode.json");
 }

package/src/index.mjs

@@ -100,10 +100,12 @@ function parseFlags(argv) {
     scope: "user",
     yes: false,
     help: false,
+    unsafeHost: false,
   };
   for (const a of argv) {
     if (a === "--help" || a === "-h") flags.help = true;
     else if (a === "--yes" || a === "-y") flags.yes = true;
+    else if (a === "--unsafe-host") flags.unsafeHost = true;
     else if (a.startsWith("--host=")) flags.host = a.slice("--host=".length);
     else if (a.startsWith("--agent=")) flags.agent = a.slice("--agent=".length);
     else if (a.startsWith("--scope=")) flags.scope = a.slice("--scope=".length);
@@ -114,6 +116,16 @@ function parseFlags(argv) {
     throw new Error(`--scope must be "user" or "project" (got "${flags.scope}")`);
   }
   flags.host = stripTrailingSlash(flags.host);
+  // Skip host validation when the user just wants --help — otherwise a bad
+  // UPTURTLE_HOST in the environment would prevent them from even seeing the
+  // usage that explains the rules.
+  if (!flags.help) {
+    if (flags.unsafeHost) {
+      warnUnsafeHost(flags.host);
+    } else {
+      validateHost(flags.host);
+    }
+  }
   return flags;
 }
 
@@ -121,6 +133,103 @@ function stripTrailingSlash(s) {
   return s.endsWith("/") ? s.slice(0, -1) : s;
 }
 
+/**
+ * Rejects any host that isn't on the trusted allowlist. The wizard mints a
+ * bearer token that grants the holder full access to the user's UpTurtle
+ * account, so accepting an attacker-controlled --host (or UPTURTLE_HOST) lets
+ * a malicious blog post or social-engineered command exfiltrate that token.
+ *
+ * Allowed:
+ *   - https://upturtle.com               (apex)
+ *   - https://<anything>.upturtle.com    (any subdomain — prod, staging, etc.)
+ *   - http://localhost[:port]            (local dev)
+ *   - http://127.0.0.1[:port]            (local dev)
+ *
+ * Anything else throws. Use --unsafe-host to opt into a non-allowlisted host
+ * for legitimate dev/test scenarios; that path prints a loud warning.
+ */
+export function validateHost(raw) {
+  const allowedShapes = [
+    "https://upturtle.com",
+    "https://<subdomain>.upturtle.com",
+    "http://localhost[:<port>]",
+    "http://127.0.0.1[:<port>]",
+  ];
+  const reject = (reason) => {
+    throw new Error(
+      `Refusing to use host "${raw}": ${reason}.\n` +
+        `Allowed hosts:\n` +
+        allowedShapes.map((s) => `  - ${s}`).join("\n") +
+        `\nIf you really need a different host (e.g. a personal dev preview), ` +
+        `re-run with --unsafe-host. Only do this if you trust the host — it ` +
+        `will receive an access token tied to your UpTurtle account.`,
+    );
+  };
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return reject("not a valid URL");
+  }
+
+  // Reject embedded credentials, query strings, fragments, and non-root paths.
+  // These don't need to be on the allowlist itself, but accepting them would
+  // smuggle data into the request the user can't easily see.
+  if (url.username || url.password) return reject("URL must not contain credentials");
+  if (url.search) return reject("URL must not contain a query string");
+  if (url.hash) return reject("URL must not contain a fragment");
+  if (url.pathname && url.pathname !== "/" && url.pathname !== "") {
+    return reject("URL must not contain a path");
+  }
+
+  const host = url.hostname;
+  const port = url.port;
+
+  if (url.protocol === "https:") {
+    if (port !== "" && port !== "443") return reject("https host must use the default port");
+    if (host === "upturtle.com") return;
+    if (host.endsWith(".upturtle.com") && host.length > ".upturtle.com".length) return;
+    return reject("https hosts must be upturtle.com or a subdomain of upturtle.com");
+  }
+
+  if (url.protocol === "http:") {
+    if (host !== "localhost" && host !== "127.0.0.1") {
+      return reject("http is only allowed for localhost / 127.0.0.1");
+    }
+    // Port is optional. If present, must be numeric (URL parse already
+    // guarantees that) and in the valid range.
+    if (port !== "") {
+      const n = Number(port);
+      if (!Number.isInteger(n) || n < 1 || n > 65535) return reject("invalid port");
+    }
+    return;
+  }
+
+  return reject(`unsupported protocol "${url.protocol.replace(/:$/, "")}"`);
+}
+
+function warnUnsafeHost(host) {
+  const bar = "!".repeat(72);
+  const lines = [
+    "",
+    bar,
+    "!! WARNING: --unsafe-host is set. Skipping the UpTurtle host allowlist.",
+    "!!",
+    `!! Host: ${host}`,
+    "!!",
+    "!! This wizard is about to mint an access token for your UpTurtle account",
+    "!! and hand it to the host above. If that host is not run by you or by",
+    "!! UpTurtle, the token can be used to deploy, redeploy, or delete every",
+    "!! application in your account.",
+    "!!",
+    "!! Only proceed if you typed this URL yourself and trust the operator.",
+    bar,
+    "",
+  ];
+  for (const line of lines) console.error(line);
+}
+
 // Decides which agents to install for. Order of precedence:
 //   1. Explicit --agent=id,id (skips prompt; honored even if not in detected)
 //   2. Non-interactive (--yes or non-TTY): every detected agent
@@ -259,6 +368,12 @@ function printHelp() {
 Options:
   --host=<url>      Override the UpTurtle host. Defaults to ${DEFAULT_HOST}.
                     Also: UPTURTLE_HOST=<url>.
+                    Must be upturtle.com (or a subdomain) over https, or
+                    http://localhost / 127.0.0.1 for local dev. Other hosts
+                    are rejected to keep your access token from being sent
+                    to a third party.
+  --unsafe-host     Bypass the --host allowlist. Prints a loud warning and
+                    proceeds. Only use this if you genuinely trust the host.
   --scope=<scope>   Where to write the MCP config:
                       user     — your home dir; available in every project (default).
                       project  — the current working directory; checked into git,
@@ -271,7 +386,7 @@ Options:
   --help, -h        Show this message.
 
 Project scope is supported for: claude-code, cursor, opencode, zed.
-Antigravity and Claude Desktop only support user scope (their config formats
-don't have a project-level alternative).
+Antigravity, Codex CLI, and Claude Desktop only support user scope
+(their config formats don't have a project-level alternative).
 `);
 }

package/src/writers.mjs

@@ -5,6 +5,7 @@ import { spawnSync } from "node:child_process";
 import {
   antigravityConfigPath,
   claudeDesktopConfigPath,
+  codexConfigPath,
   opencodeConfigPath,
   zedConfigPath,
 } from "./agents.mjs";
@@ -14,6 +15,7 @@ const SERVER_KEY = "upturtle";
 export const WRITERS = {
   "claude-code": writeClaudeCode,
   "cursor": writeCursor,
+  "codex": writeCodex,
   "antigravity": writeAntigravity,
   "opencode": writeOpenCode,
   "zed": writeZed,
@@ -135,6 +137,60 @@ function writeZed({ host, secret, scope }) {
   });
 }
 
+function writeCodex({ host, secret, scope }) {
+  if (scope === "project") {
+    throw new Error(
+      "Codex CLI's MCP config is user-wide only (`~/.codex/config.toml`). " +
+        "Re-run without --scope=project for this agent.");
+  }
+  const path = codexConfigPath();
+  const block =
+    `[mcp_servers.${SERVER_KEY}]\n` +
+    `command = "npx"\n` +
+    `args = ["-y", "mcp-remote", "${host}/mcp", "--header", "Authorization: Bearer ${secret}"]\n`;
+
+  let existing = "";
+  if (existsSync(path)) {
+    existing = readFileSync(path, "utf8");
+  }
+  const updated = upsertTomlTable(existing, `mcp_servers.${SERVER_KEY}`, block);
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, updated, "utf8");
+  return { configPath: path };
+}
+
+// Naive TOML table upsert: replaces the `[<header>]` block (if present),
+// otherwise appends. The block runs from its `[header]` line to the next
+// top-level `[` or end-of-file. Good enough for our single-block writes —
+// avoids pulling in a TOML parser dependency.
+function upsertTomlTable(source, header, block) {
+  const headerLine = `[${header}]`;
+  const lines = source.split("\n");
+  const startIdx = lines.findIndex((line) => line.trim() === headerLine);
+
+  const trimmedBlock = block.endsWith("\n") ? block : block + "\n";
+
+  if (startIdx === -1) {
+    const prefix = source.length === 0 || source.endsWith("\n") ? source : source + "\n";
+    const separator = prefix.endsWith("\n\n") || prefix.length === 0 ? "" : "\n";
+    return prefix + separator + trimmedBlock;
+  }
+
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (/^\s*\[/.test(lines[i])) {
+      endIdx = i;
+      break;
+    }
+  }
+  const before = lines.slice(0, startIdx).join("\n");
+  const after = lines.slice(endIdx).join("\n");
+  const beforePart = before.length === 0 ? "" : before.endsWith("\n") ? before : before + "\n";
+  const afterPart = after.length === 0 ? "" : after.startsWith("\n") ? after : "\n" + after;
+  return beforePart + trimmedBlock + afterPart;
+}
+
 function writeClaudeDesktop({ host, secret, scope }) {
   if (scope === "project") {
     throw new Error(