pennyrouter 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {
@@ -24,7 +24,7 @@
   ],
   "scripts": {
     "start": "node ./bin/pennyrouter.js",
-    "check": "node --check ./bin/pennyrouter.js && node --check ./bin/penny.js && find src -name '*.js' -print0 | xargs -0 -n1 node --check && node src/session.test.js && node src/statusline.test.js && node src/harnesses/claude-code.test.js && node src/harnesses/codex.test.js && node src/harnesses/opencode.test.js && node src/launch.test.js && node src/thread-session.test.js && node src/thread-session-codex.test.js && node src/mcp-register.test.js && node src/mcp.test.js"
+    "check": "node --check ./bin/pennyrouter.js && node --check ./bin/penny.js && find src -name '*.js' -print0 | xargs -0 -n1 node --check && node --test src/cli.test.js && node src/session.test.js && node src/statusline.test.js && node src/harnesses/claude-code.test.js && node src/harnesses/codex.test.js && node src/harnesses/opencode.test.js && node src/launch.test.js && node src/thread-session.test.js && node src/thread-session-codex.test.js && node src/mcp-register.test.js && node src/mcp.test.js"
   },
   "license": "MIT"
 }

package/src/cli.js

@@ -67,20 +67,30 @@ const HARNESS_BY_ID = {
   aider: aiderHarness,
 };
 
-const SUPPORTED_HARNESS_IDS = Object.keys(HARNESS_BY_ID).join(",");
-const DEFAULT_INSTALL_HARNESS_IDS = ["claude-code", "codex", "opencode"];
-const CLAUDE_PROVIDER_OPTIONS = [
-  { id: "subscription", name: "Claude subscription" },
-  { id: "anthropic-api", name: "Anthropic API key" },
-  { id: "openrouter", name: "OpenRouter API key" },
-  { id: "anthropic-proxy", name: "Other proxy (custom base URL)" },
-];
-const CODEX_PROVIDER_OPTIONS = [
-  { id: "subscription", name: "ChatGPT subscription" },
-  { id: "openai-api", name: "OpenAI API key" },
-  { id: "openai-proxy", name: "Other OpenAI-compatible proxy" },
-  { id: "openrouter", name: "OpenRouter API key" },
-];
+export const SUPPORTED_HARNESS_IDS = Object.keys(HARNESS_BY_ID).join(",");
+
+// The GUI installer (apps/setup/swift) asks the install questions itself and hands the answers
+// back through --config, so it needs to know the same harness ids and funding options this file
+// branches on. It fetches this manifest from the published package over a CDN rather than
+// duplicating the lists in Swift. Reading it here too is what keeps the two honest: there is one
+// definition, and the code that acts on it is the code that reads it.
+export const INSTALL_MANIFEST = JSON.parse(
+  readFileSync(new URL("./install-manifest.json", import.meta.url), "utf8"),
+);
+
+const DEFAULT_INSTALL_HARNESS_IDS = INSTALL_MANIFEST.default_harness_ids;
+const CLAUDE_PROVIDER_OPTIONS = INSTALL_MANIFEST.funding_groups.claude.options
+  .map(({ id, name }) => ({ id, name }));
+const CODEX_PROVIDER_OPTIONS = INSTALL_MANIFEST.funding_groups.codex.options
+  .map(({ id, name }) => ({ id, name }));
+
+/** Harnesses the manifest gives a `penny <name>` launcher, keyed by id. */
+const PENNY_COMMAND_BY_HARNESS = Object.fromEntries(
+  INSTALL_MANIFEST.harnesses
+    .filter((harness) => harness.penny_command)
+    .map((harness) => [harness.id, harness.penny_command]),
+);
+const LAUNCHABLE_HARNESS_IDS = Object.keys(PENNY_COMMAND_BY_HARNESS);
 
 export async function main(argv = process.argv.slice(2)) {
   const { command, flags } = parseArgs(argv);
@@ -225,7 +235,7 @@ function parseArgs(argv) {
 // non-interactive paths unchanged. CLI flags win over the config file where both are given.
 // Funding choices imply --yes (skip remaining prompts) but, unlike bare --yes, do NOT suppress
 // the Claude subscription browser sign-in — see maybeConfigureClaudeAnthropicAuth.
-function applyConfigFile(flags) {
+export function applyConfigFile(flags) {
   let config;
   try {
     config = JSON.parse(readFileSync(flags.configPath, "utf8"));
@@ -241,20 +251,27 @@ function applyConfigFile(flags) {
   if (claudeFunding.has("subscription") && flags.anthropicAuth === undefined) {
     flags.anthropicAuth = true;
   }
-  if (claudeFunding.has("anthropic-api") && flags.anthropicApiKey === undefined) {
-    flags.anthropicApiKey = config.anthropicApiKey || "";
-  }
-  if ((claudeFunding.has("openrouter") || codexFunding.has("openrouter"))
-      && flags.openrouterApiKey === undefined) {
-    flags.openrouterApiKey = config.openrouterApiKey || "";
-  }
-  if (codexFunding.has("openai-api") && flags.openaiApiKey === undefined) {
-    flags.openaiApiKey = config.openaiApiKey || "";
+  // Every funding option the manifest describes carries the fields it needs, and their
+  // config_key is the flags field they populate. Copying them generically means a new option
+  // works here the moment it is added to the manifest, instead of needing a branch per option.
+  for (const [group, chosen] of [["claude", claudeFunding], ["codex", codexFunding]]) {
+    for (const option of INSTALL_MANIFEST.funding_groups[group].options) {
+      if (!chosen.has(option.id)) continue;
+      for (const field of option.fields) {
+        if (flags[field.config_key] === undefined) {
+          flags[field.config_key] = config[field.config_key] || "";
+        }
+      }
+    }
   }
-  if (claudeFunding.has("anthropic-proxy")) {
-    if (flags.proxyBaseUrl === undefined) flags.proxyBaseUrl = config.proxyBaseUrl || "";
-    if (flags.proxyApiKey === undefined) flags.proxyApiKey = config.proxyApiKey || "";
+
+  // A private gateway is independent of funding: it changes where the CLI claims its key and
+  // stores credentials, so it applies whatever providers were picked.
+  for (const field of INSTALL_MANIFEST.advanced.fields) {
+    const value = String(config[field.config_key] || "").trim();
+    if (value && flags[field.config_key] === undefined) flags[field.config_key] = value;
   }
+  if (flags.gatewayBaseUrl) flags.privateGateway = true;
 
   flags.yes = true;
   flags.fromConfig = true;
@@ -535,9 +552,8 @@ export async function install(flags = {}) {
   if (flags.dryRun) {
     const defaultRouting = await chooseDefaultRouting(flags, selected, manifest);
     for (const harness of selected) {
-      const explicit = ["claude-code", "codex", "opencode"].includes(harness.id);
-      const command = harness.id === "claude-code"
-        ? "penny claude" : harness.id === "codex" ? "penny codex" : "penny opencode";
+      const command = PENNY_COMMAND_BY_HARNESS[harness.id];
+      const explicit = Boolean(command);
       console.log(`Will install on ${harness.name}${explicit ? ` via ${command}` : installNoteForHarness(harness.id)}.`);
       if (defaultRouting.get(harness.id)) {
         console.log(`Will also route bare ${harness.id === "claude-code" ? "claude" : harness.id} through PennyRouter.`);
@@ -607,6 +623,16 @@ export async function install(flags = {}) {
     funding = await configureUserFunding(
       flags, needsAuth, claudeAnthropicAuth, claudeProviders, codexProviders);
     gatewayBaseUrl = flags.gatewayBaseUrl || claim.gateway_base_url;
+    if (flags.gatewayBaseUrl) {
+      const normalized = normalizeGatewayBaseUrl(flags.gatewayBaseUrl);
+      if (!normalized) {
+        throw new Error(
+          `--gateway-base-url "${flags.gatewayBaseUrl}" is not a usable URL. Use a host like `
+          + "localhost:8400 or https://gateway.example.com.",
+        );
+      }
+      gatewayBaseUrl = normalized;
+    }
 
     // A user-supplied proxy may live on a private network that the hosted gateway cannot
     // reach. Let interactive installs choose the gateway after they choose the proxy: blank
@@ -615,10 +641,20 @@ export async function install(flags = {}) {
     // explicit localhost:8400 developer shortcut and skips this prompt.
     if ((claudeProviders.has("anthropic-proxy") || codexProviders.has("openai-proxy")) && !flags.gatewayBaseUrl
         && !flags.yes && input.isTTY && output.isTTY) {
-      const privateGateway = (await promptText(
+      const answer = (await promptText(
         "PennyRouter gateway URL for this proxy (blank for hosted gateway): ",
       )).trim();
-      if (privateGateway) {
+      if (answer) {
+        const privateGateway = normalizeGatewayBaseUrl(answer);
+        if (!privateGateway) {
+          throw new Error(
+            `"${answer}" is not a usable gateway URL. Use a host like `
+            + "localhost:8400 or https://gateway.example.com.",
+          );
+        }
+        // Show the normalized form: the user typed "localhost:8000" and everything from here on
+        // uses "http://localhost:8000", so any later error names a URL they recognize.
+        if (privateGateway !== answer) console.log(`Using gateway ${privateGateway}.`);
         gatewayBaseUrl = privateGateway;
         flags.privateGateway = true;
       }
@@ -633,7 +669,8 @@ export async function install(flags = {}) {
         console.log("");
         console.log(`Private gateway: ${gatewayBaseUrl}`);
         console.log("Your PennyRouter administrator issues keys for this gateway.");
-        privateKey = (await promptText("Paste your private gateway key (pr-...): ")).trim();
+        // No echo: this is an issued credential, and a visible paste lingers in scrollback.
+        privateKey = (await promptSecretish("Paste your private gateway key (pr-...): ")).trim();
       }
       if (!privateKey) {
         throw new Error(
@@ -650,19 +687,20 @@ export async function install(flags = {}) {
     }
 
     for (const credential of funding.credentials) {
-      await storeUpstreamCredential({
+      await withGatewayContext(gatewayBaseUrl, () => storeUpstreamCredential({
         gatewayBaseUrl,
         apiKey: claim.api_key,
         provider: credential.provider,
         token: credential.token,
         metadata: credential.metadata,
-      });
+      }));
     }
   }
 
   if (needsAuth.some((harness) => harness.id === "claude-code")) {
     console.log("Verifying modern Claude Code compatibility before changing local settings...");
-    await probeClaudeCodeGateway({ gatewayBaseUrl, apiKey: claim.api_key });
+    await withGatewayContext(
+      gatewayBaseUrl, () => probeClaudeCodeGateway({ gatewayBaseUrl, apiKey: claim.api_key }));
     console.log("");
   }
 
@@ -671,7 +709,7 @@ export async function install(flags = {}) {
   // choose the visible command behavior with all relevant context in front of them.
   const defaultRouting = await chooseDefaultRouting(flags, selected, manifest);
 
-  const launchable = selected.filter((harness) => ["claude-code", "codex", "opencode"].includes(harness.id));
+  const launchable = selected.filter((harness) => LAUNCHABLE_HARNESS_IDS.includes(harness.id));
   let runtimeResult = null;
   if (launchable.length > 0) {
     runtimeResult = await installPennyRuntime({ updatePath: !flags.noPathUpdate });
@@ -685,7 +723,7 @@ export async function install(flags = {}) {
       const existingRecord = (manifest.installations || []).find(
         (candidate) => candidate.harness === harness.id,
       );
-      const supportsPennyCommand = ["claude-code", "codex", "opencode"].includes(harness.id);
+      const supportsPennyCommand = LAUNCHABLE_HARNESS_IDS.includes(harness.id);
       const makeDefault = defaultRouting.get(harness.id) ?? true;
       const hadGlobalRouting = Boolean(existingRecord && existingRecord.default_routing !== false);
 
@@ -771,8 +809,7 @@ export async function install(flags = {}) {
   for (const record of records) {
     const harness = HARNESS_BY_ID[record.harness];
     if (record.launch_available) {
-      const command = record.harness === "claude-code"
-        ? "penny claude" : record.harness === "codex" ? "penny codex" : "penny opencode";
+      const command = PENNY_COMMAND_BY_HARNESS[record.harness];
       const native = record.harness === "claude-code" ? "claude"
         : record.harness === "codex" ? "codex" : "opencode";
       const harnessName = record.harness === "claude-code" ? "Claude Code"
@@ -844,6 +881,46 @@ function mcpTargets(flags) {
 /** The gateway URL worth pinning into the MCP entry, or "" for the default.
     The MCP server already falls back to production on its own, so writing that value would only
     freeze today's default into every user's config. */
+/* Users type gateways the way they say them out loud — "localhost:8000",
+   "gateway.example.com". Those are not absolute URLs, so fetch() rejects them with a bare
+   "fetch failed" long after the prompt, where the cause is invisible. Supply the obvious scheme
+   (plain http for loopback, https elsewhere) and prove the result parses, so a typo fails here
+   instead. Returns null when the value cannot be salvaged. */
+function normalizeGatewayBaseUrl(raw) {
+  const value = String(raw || "").trim().replace(/\/+$/, "");
+  if (!value) return null;
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value)
+    ? value
+    : `${/^(localhost|127\.0\.0\.1|\[::1\])(:|$)/i.test(value) ? "http" : "https"}://${value}`;
+  let parsed;
+  try {
+    parsed = new URL(withScheme);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+  if (!parsed.hostname) return null;
+  return withScheme.replace(/\/+$/, "");
+}
+
+/* A gateway that is unreachable (wrong host, wrong port, not running) surfaces from fetch() as
+   an opaque "fetch failed" with no status. Name the gateway we could not reach so the user knows
+   which URL to fix. Real HTTP errors carry their own message and pass through untouched. */
+async function withGatewayContext(gatewayBaseUrl, action) {
+  try {
+    return await action();
+  } catch (error) {
+    const message = String(error?.message || error);
+    if (/fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ECONNRESET|network/i.test(message)) {
+      throw new Error(
+        `Could not reach the PennyRouter gateway at ${gatewayBaseUrl} (${message}). `
+        + "Check that the URL is correct and that the gateway is running.",
+      );
+    }
+    throw error;
+  }
+}
+
 function customGatewayBaseUrl(url) {
   const value = String(url || "").trim().replace(/\/+$/, "");
   return !value || value === DEFAULT_GATEWAY_BASE_URL ? "" : value;
@@ -985,7 +1062,7 @@ async function update(flags) {
 
   const failures = [];
   let runtimeResult = null;
-  if (targets.some((record) => ["claude-code", "codex", "opencode"].includes(record.harness))) {
+  if (targets.some((record) => LAUNCHABLE_HARNESS_IDS.includes(record.harness))) {
     runtimeResult = await installPennyRuntime({ updatePath: !flags.noPathUpdate });
   }
 
@@ -994,7 +1071,7 @@ async function update(flags) {
     if (!harness) continue;
 
     await runHarnessJob(failures, record.harness, "update", async () => {
-      const supportsPennyCommand = ["claude-code", "codex", "opencode"].includes(record.harness);
+      const supportsPennyCommand = LAUNCHABLE_HARNESS_IDS.includes(record.harness);
       // An update rewrites the harness's own config only when that config is ours to
       // rewrite — i.e. the bare command still routes through the gateway. In penny-only
       // mode the harness config belongs to the user and we touch just the launch profile.
@@ -1678,8 +1755,7 @@ async function status() {
       console.log(`  Upstream proxy: ${record.proxy_base_url}${note}`);
     }
     if (record.launch_available) {
-      const command = record.harness === "claude-code"
-        ? "penny claude" : record.harness === "codex" ? "penny codex" : "penny opencode";
+      const command = PENNY_COMMAND_BY_HARNESS[record.harness];
       console.log(`  command: ${command}`);
       console.log(`  bare command: ${record.default_routing ? "PennyRouter" : "native"}`);
     }

package/src/cli.test.js

@@ -3,7 +3,9 @@ import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
-import { harnessFundingChanged, main } from "./cli.js";
+import {
+  applyConfigFile, harnessFundingChanged, INSTALL_MANIFEST, main, SUPPORTED_HARNESS_IDS,
+} from "./cli.js";
 
 // --config lets a GUI installer (the macOS DMG) answer install questions up front instead of
 // over a TTY. These tests drive it through `main()` in --dry-run, which prints its plan and
@@ -194,3 +196,76 @@ test("auth anthropic --forget honors --local", async () => {
   ]));
   assert.ok(lines.some((line) => line.includes("localhost:8400")));
 });
+
+// --- Manifest contract -------------------------------------------------------------------
+// The GUI installer (apps/setup/swift) builds its whole question flow from install-manifest.json,
+// fetched from the published package. These tests pin the parts Swift depends on and, more
+// importantly, prove the manifest still describes what this file actually does — a funding option
+// the GUI can offer but --config cannot apply is the exact drift the manifest exists to prevent.
+
+test("every manifest funding field is applied by --config", () => {
+  // Asserts on applyConfigFile directly rather than through a --dry-run install: the dry run
+  // returns before configureUserFunding, so it cannot observe a field that was never copied.
+  for (const [group, configKey] of [["claude", "claudeFunding"], ["codex", "codexFunding"]]) {
+    for (const option of INSTALL_MANIFEST.funding_groups[group].options) {
+      if (option.fields.length === 0) continue;
+      const config = { harnesses: ["claude-code", "codex"], [configKey]: [option.id] };
+      for (const field of option.fields) config[field.config_key] = `value-${field.config_key}`;
+      withConfigFile(config, (path) => {
+        const flags = { configPath: path };
+        applyConfigFile(flags);
+        for (const field of option.fields) {
+          assert.equal(
+            flags[field.config_key], `value-${field.config_key}`,
+            `${group}/${option.id}: --config ignored ${field.config_key}`,
+          );
+        }
+      });
+    }
+  }
+});
+
+test("manifest harness ids are all installable", () => {
+  const supported = SUPPORTED_HARNESS_IDS.split(",");
+  for (const harness of INSTALL_MANIFEST.harnesses) {
+    assert.ok(supported.includes(harness.id), `${harness.id} is not a supported harness`);
+  }
+});
+
+test("manifest config paths match what each harness detects", () => {
+  // Swift decides which tools to pre-check by testing these paths itself, so a path that drifts
+  // from the harness module makes the GUI silently under-detect an installed tool.
+  const expected = {
+    "claude-code": ["~/.claude/settings.json"],
+    codex: ["~/.codex/config.toml"],
+    opencode: ["~/.config/opencode/opencode.jsonc", "~/.config/opencode/opencode.json"],
+  };
+  for (const harness of INSTALL_MANIFEST.harnesses) {
+    assert.deepEqual(harness.config_paths, expected[harness.id], `${harness.id} config paths`);
+  }
+});
+
+test("--config applies a private gateway and its key", async () => {
+  await withConfigFile(
+    {
+      harnesses: ["claude-code"],
+      claudeFunding: ["subscription"],
+      gatewayBaseUrl: "http://localhost:8400",
+      privateKey: "pr-test-private",
+    },
+    async (path) => {
+      const lines = await captureLogs(() => main(["install", "--config", path, "--dry-run"]));
+      assert.ok(lines.some((line) => line.includes("localhost:8400")));
+    },
+  );
+});
+
+test("--config leaves the hosted gateway alone when no private gateway is given", async () => {
+  await withConfigFile(
+    { harnesses: ["claude-code"], claudeFunding: ["subscription"] },
+    async (path) => {
+      const lines = await captureLogs(() => main(["install", "--config", path, "--dry-run"]));
+      assert.ok(!lines.some((line) => line.includes("localhost:8400")));
+    },
+  );
+});

package/src/install-manifest.json

@@ -0,0 +1,128 @@
+{
+  "schema_version": 1,
+  "default_harness_ids": ["claude-code", "codex", "opencode"],
+  "harnesses": [
+    {
+      "id": "claude-code",
+      "name": "Claude Code",
+      "config_paths": ["~/.claude/settings.json"],
+      "penny_command": "penny claude",
+      "funding_group": "claude"
+    },
+    {
+      "id": "codex",
+      "name": "Codex",
+      "config_paths": ["~/.codex/config.toml"],
+      "penny_command": "penny codex",
+      "funding_group": "codex"
+    },
+    {
+      "id": "opencode",
+      "name": "OpenCode",
+      "config_paths": [
+        "~/.config/opencode/opencode.jsonc",
+        "~/.config/opencode/opencode.json"
+      ],
+      "penny_command": "penny opencode",
+      "funding_group": null
+    }
+  ],
+  "funding_groups": {
+    "claude": {
+      "config_key": "claudeFunding",
+      "title": "Claude Code funding",
+      "options": [
+        {
+          "id": "subscription",
+          "name": "Claude subscription",
+          "fields": []
+        },
+        {
+          "id": "anthropic-api",
+          "name": "Anthropic API key",
+          "fields": [
+            { "config_key": "anthropicApiKey", "label": "Anthropic API key", "secret": true }
+          ]
+        },
+        {
+          "id": "openrouter",
+          "name": "OpenRouter API key",
+          "fields": [
+            { "config_key": "openrouterApiKey", "label": "OpenRouter API key", "secret": true }
+          ]
+        },
+        {
+          "id": "anthropic-proxy",
+          "name": "Other proxy (custom base URL)",
+          "fields": [
+            {
+              "config_key": "proxyBaseUrl",
+              "label": "Proxy base URL",
+              "secret": false,
+              "placeholder": "https://proxy.example.com"
+            },
+            { "config_key": "proxyApiKey", "label": "Proxy API key", "secret": true }
+          ]
+        }
+      ]
+    },
+    "codex": {
+      "config_key": "codexFunding",
+      "title": "Codex funding",
+      "options": [
+        {
+          "id": "subscription",
+          "name": "ChatGPT subscription",
+          "fields": []
+        },
+        {
+          "id": "openai-api",
+          "name": "OpenAI API key",
+          "fields": [
+            { "config_key": "openaiApiKey", "label": "OpenAI API key", "secret": true }
+          ]
+        },
+        {
+          "id": "openai-proxy",
+          "name": "Other OpenAI-compatible proxy",
+          "fields": [
+            {
+              "config_key": "openaiProxyBaseUrl",
+              "label": "OpenAI proxy base URL",
+              "secret": false,
+              "placeholder": "https://proxy.example.com/v1"
+            },
+            { "config_key": "openaiProxyApiKey", "label": "OpenAI proxy API key", "secret": true }
+          ]
+        },
+        {
+          "id": "openrouter",
+          "name": "OpenRouter API key",
+          "fields": [
+            { "config_key": "openrouterApiKey", "label": "OpenRouter API key", "secret": true }
+          ]
+        }
+      ]
+    }
+  },
+  "advanced": {
+    "title": "Private gateway",
+    "description": "Route through your own PennyRouter gateway instead of the hosted one.",
+    "fields": [
+      {
+        "config_key": "gatewayBaseUrl",
+        "label": "Gateway base URL",
+        "secret": false,
+        "placeholder": "https://gateway.example.com",
+        "requires_https": true
+      },
+      {
+        "config_key": "privateKey",
+        "label": "Private gateway key",
+        "secret": true,
+        "placeholder": "pr-...",
+        "prefix": "pr-"
+      }
+    ]
+  }
+}