pennyrouter 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {
@@ -20,7 +20,6 @@
   "files": [
     "bin",
     "src",
-    "claude-plugin",
     "README.md"
   ],
   "scripts": {

package/src/cli.js

@@ -375,9 +375,9 @@ async function install(flags) {
   console.log("");
 
   const manifest = await loadManifest();
-  const defaultRouting = await chooseDefaultRouting(flags, selected, manifest);
 
   if (flags.dryRun) {
+    const defaultRouting = await chooseDefaultRouting(flags, selected, manifest);
     for (const harness of selected) {
       const explicit = ["claude-code", "codex"].includes(harness.id) && process.platform !== "win32";
       const command = harness.id === "claude-code" ? "penny claude" : "penny codex";
@@ -411,6 +411,25 @@ async function install(flags) {
   console.log("");
 
   const claudeAnthropicAuth = await maybeConfigureClaudeAnthropicAuth(flags, selected);
+  const gatewayBaseUrl = flags.gatewayBaseUrl || claim.gateway_base_url;
+
+  if (selected.some((harness) => harness.id === "claude-code")) {
+    if (claudeAnthropicAuth) {
+      await storeAnthropicToken({
+        gatewayBaseUrl,
+        apiKey: claim.api_key,
+        token: claudeAnthropicAuth.token,
+      });
+    }
+    console.log("Verifying modern Claude Code compatibility before changing local settings...");
+    await probeClaudeCodeGateway({ gatewayBaseUrl, apiKey: claim.api_key });
+    console.log("");
+  }
+
+  // Keep this as the final interactive choice: users first authorize their account,
+  // optionally connect their subscription, and pass compatibility checks. Then they
+  // 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"].includes(harness.id));
   let runtimeResult = null;
@@ -423,7 +442,6 @@ async function install(flags) {
   for (const harness of selected) {
     await runHarnessJob(failures, harness.id, "install", async () => {
       const plan = await harness.planInstall();
-      const gatewayBaseUrl = flags.gatewayBaseUrl || claim.gateway_base_url;
       const existingRecord = (manifest.installations || []).find(
         (candidate) => candidate.harness === harness.id,
       );
@@ -441,18 +459,6 @@ async function install(flags) {
       const claudeSubscriptionAuth = harness.id === "claude-code"
         && Boolean(claudeAnthropicAuth || existingRecord?.anthropic_token_stored);
 
-      if (harness.id === "claude-code" && claudeAnthropicAuth) {
-        await storeAnthropicToken({
-          gatewayBaseUrl,
-          apiKey: claim.api_key,
-          token: claudeAnthropicAuth.token,
-        });
-      }
-      if (harness.id === "claude-code") {
-        console.log("Verifying modern Claude Code compatibility before changing local settings...");
-        await probeClaudeCodeGateway({ gatewayBaseUrl, apiKey: claim.api_key });
-      }
-
       if (supportsPennyCommand) {
         await configurePennyHarness(harness.id, {
           apiKey: claim.api_key,
@@ -505,14 +511,22 @@ async function install(flags) {
 
   await saveManifest(manifest);
   console.log("");
-  console.log("Installed PennyRouter.");
+  console.log(records.length > 0
+    ? "PennyRouter installation complete."
+    : "PennyRouter was not installed on any selected tool.");
+  console.log(`Manifest: ${statePath("installations.json")}`);
   for (const record of records) {
     const harness = HARNESS_BY_ID[record.harness];
     if (record.launch_available) {
       const command = record.harness === "claude-code" ? "penny claude" : "penny codex";
       const native = record.harness === "claude-code" ? "claude" : "codex";
-      console.log(`Installed on ${harness?.name || record.harness}: use \`${command}\`.`);
-      console.log(`  Bare \`${native}\`: ${record.default_routing ? "PennyRouter" : "native"}`);
+      const harnessName = record.harness === "claude-code" ? "Claude Code" : "Codex";
+      const commandWidth = Math.max(command.length, native.length) + 2;
+      console.log("");
+      console.log(color(`How to Run ${harnessName}`, "bold"));
+      console.log("");
+      console.log(`  ${color(command.padEnd(commandWidth), "bold")}→ ${harnessName} with PennyRouter`);
+      console.log(`  ${color(native.padEnd(commandWidth), "bold")}→ ${record.default_routing ? `${harnessName} with PennyRouter (default routing enabled)` : `${harnessName} native`}`);
     } else {
       console.log(`Installed on ${harness?.name || record.harness}${installNoteForRecord(record)}.`);
     }
@@ -522,7 +536,7 @@ async function install(flags) {
   } else if (runtimeResult?.changed) {
     console.log("Open a new terminal (or reload your shell) before using the `penny` command.");
   }
-  console.log(`Manifest: ${statePath("installations.json")}`);
+  console.log("");
   reportFailures(failures);
 }
 
@@ -552,15 +566,31 @@ async function chooseDefaultRouting(flags, selected, manifest) {
       }
       const native = harness.id === "claude-code" ? "claude" : "codex";
       const change = await confirm(
-        `PennyRouter currently runs when you type \`${native}\`. Change it to run only with \`penny ${native}\`?`,
+        `PennyRouter currently runs when you type ${color(native, "bold")}. Change it to run only with ${color(`penny ${native}`, "bold")}?`,
       );
       out.set(harness.id, !change);
       continue;
     }
     if (newInstallChoice === null) {
-      newInstallChoice = flags.dryRun || flags.yes || !input.isTTY || !output.isTTY
-        ? false
-        : await confirm("Use PennyRouter by default when you type `claude` or `codex`?");
+      if (flags.dryRun || flags.yes || !input.isTTY || !output.isTTY) {
+        newInstallChoice = false;
+      } else {
+        for (const item of launchable) {
+          const native = item.id === "claude-code" ? "claude" : "codex";
+          const harnessName = item.id === "claude-code" ? "Claude Code" : "Codex";
+          const command = `penny ${native}`;
+          const commandWidth = Math.max(command.length, native.length) + 2;
+          console.log("");
+          console.log(color(`How to Run ${harnessName}`, "bold"));
+          console.log("");
+          console.log(`  ${color(command.padEnd(commandWidth), "bold")}→ ${harnessName} with PennyRouter`);
+          console.log(`  ${color(native.padEnd(commandWidth), "bold")}→ ${harnessName} native (recommended)`);
+        }
+        console.log("");
+        const bare = launchable.map((item) => item.id === "claude-code" ? "claude" : "codex");
+        const label = bare.length === 1 ? bare[0] : `${bare.slice(0, -1).join(", ")} and ${bare.at(-1)}`;
+        newInstallChoice = await confirm(`Also route ${color(label, "bold")} through PennyRouter by default?`);
+      }
     }
     out.set(harness.id, newInstallChoice);
   }

package/src/launch.js

@@ -19,6 +19,7 @@ const CONFIG_VERSION = 1;
 const PATH_START = "# >>> pennyrouter PATH >>>";
 const PATH_END = "# <<< pennyrouter PATH <<<";
 const CODEX_PROFILE_MARKER = "# PennyRouter per-command profile (managed; no secrets)";
+const CLAUDE_COMMAND_MARKER = "<!-- PennyRouter managed Claude command -->";
 
 export function pennyConfigDir() {
   return join(process.env.XDG_CONFIG_HOME || join(homeDir(), ".config"), "pennyrouter");
@@ -53,8 +54,8 @@ export function codexLaunchProfilePath() {
   return join(codexHome, "pennyrouter.config.toml");
 }
 
-export function claudePluginPath() {
-  return join(pennyRuntimeDir(), "claude-plugin");
+export function claudeUserCommandPath() {
+  return join(homeDir(), ".claude", "commands", "penny.md");
 }
 
 async function privateWrite(path, text) {
@@ -84,12 +85,19 @@ async function copyRuntime() {
   const source = packageRoot();
   const destination = pennyRuntimeDir();
   await mkdir(destination, { recursive: true, mode: 0o700 });
-  for (const entry of ["bin", "src", "claude-plugin"]) {
+  for (const entry of ["bin", "src"]) {
+    // Runtime upgrades must not merge with the previous package. In particular,
+    // 0.2.1 moved /penny from a skill to a command; leaving the old skill behind
+    // makes Claude discover two incompatible definitions.
+    await rm(join(destination, entry), { recursive: true, force: true });
     await cp(join(source, entry), join(destination, entry), {
       recursive: true,
       force: true,
     });
   }
+  // Remove plugin assets used by 0.2.0/0.2.1. /penny is now a managed personal
+  // command so it can use the exact unnamespaced name in every Claude session.
+  await rm(join(destination, "claude-plugin"), { recursive: true, force: true });
   await cp(join(source, "package.json"), join(destination, "package.json"), { force: true });
 }
 
@@ -172,6 +180,27 @@ async function writeClaudeLaunchSettings() {
   await privateWrite(claudeLaunchSettingsPath(), `${JSON.stringify(overlay, null, 2)}\n`);
 }
 
+async function writeClaudeUserCommand() {
+  const path = claudeUserCommandPath();
+  const existing = await readText(path, "");
+  if (existing.trim() && !existing.includes(CLAUDE_COMMAND_MARKER)) {
+    throw new Error(
+      `${path} already exists and is not managed by PennyRouter. Rename it before installing.`,
+    );
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await atomicWrite(path, [
+    "---",
+    "description: PennyRouter commands and help.",
+    "argument-hint: <command and arguments>",
+    "---",
+    CLAUDE_COMMAND_MARKER,
+    "",
+    "@penny $ARGUMENTS",
+    "",
+  ].join("\n"));
+}
+
 async function writeCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }) {
   const path = codexLaunchProfilePath();
   const existing = await readText(path, "");
@@ -194,6 +223,7 @@ export async function configurePennyHarness(harness, {
   config.api_key = apiKey;
   config.harnesses ||= {};
   if (harness === "claude-code") {
+    await writeClaudeUserCommand();
     await writeClaudeLaunchSettings();
     config.harnesses.claude = {
       enabled: true,
@@ -228,6 +258,12 @@ export async function removePennyHarness(harness) {
     await unlink(claudeLaunchSettingsPath()).catch((error) => {
       if (error.code !== "ENOENT") throw error;
     });
+    const command = await readText(claudeUserCommandPath(), "");
+    if (command.includes(CLAUDE_COMMAND_MARKER)) {
+      await unlink(claudeUserCommandPath()).catch((error) => {
+        if (error.code !== "ENOENT") throw error;
+      });
+    }
   } else if (harness === "codex") {
     const existing = await readText(codexLaunchProfilePath(), "");
     if (existing.startsWith(CODEX_PROFILE_MARKER)) {
@@ -296,7 +332,7 @@ export function buildPennyInvocation(harness, args, config) {
     if (models.fable) env.ANTHROPIC_DEFAULT_FABLE_MODEL = models.fable;
     return {
       command: "claude",
-      args: ["--settings", claudeLaunchSettingsPath(), "--plugin-dir", claudePluginPath(), ...args],
+      args: ["--settings", claudeLaunchSettingsPath(), ...args],
       env,
     };
   }

package/src/launch.test.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import {
   buildPennyInvocation,
   claudeLaunchSettingsPath,
-  claudePluginPath,
+  claudeUserCommandPath,
   codexLaunchProfilePath,
   configurePennyHarness,
   fileMode,
@@ -56,13 +56,16 @@ async function main() {
 
   try {
     const first = await installPennyRuntime();
+    const staleSkill = path.join(pennyRuntimeDir(), "claude-plugin", "skills", "penny", "SKILL.md");
+    fs.mkdirSync(path.dirname(staleSkill), { recursive: true });
+    fs.writeFileSync(staleSkill, "stale plugin file");
     const second = await installPennyRuntime();
     assert.equal(first.supported, true);
     assert.equal(first.changed, true);
     assert.equal(second.changed, false);
     assert.equal(await fileMode(pennyShimPath()), 0o755);
     assert.ok(fs.existsSync(path.join(pennyRuntimeDir(), "bin", "penny.js")));
-    assert.ok(fs.existsSync(path.join(claudePluginPath(), ".claude-plugin", "plugin.json")));
+    assert.ok(!fs.existsSync(staleSkill), "runtime upgrade removes stale plugin files");
     const rc = fs.readFileSync(path.join(home, ".zshrc"), "utf8");
     assert.equal((rc.match(/>>> pennyrouter PATH >>>/g) || []).length, 1);
 
@@ -94,7 +97,7 @@ async function main() {
     const claude = buildPennyInvocation("claude", ["--resume", "abc"], config);
     assert.equal(claude.command, "claude");
     assert.deepEqual(claude.args.slice(-2), ["--resume", "abc"]);
-    assert.ok(claude.args.includes("--plugin-dir"));
+    assert.ok(!claude.args.includes("--plugin-dir"));
     assert.equal(claude.env.ANTHROPIC_AUTH_TOKEN, "pr-super-secret");
     assert.equal(claude.env.ANTHROPIC_BASE_URL, "https://gateway.example/");
     assert.equal(claude.env.ANTHROPIC_DEFAULT_OPUS_MODEL, "Penny Opus");
@@ -105,10 +108,19 @@ async function main() {
     assert.throws(() => buildPennyInvocation("claude", ["--settings=x"], config), /manages --settings/);
     assert.throws(() => buildPennyInvocation("codex", ["-p", "other"], config), /manages --profile/);
 
-    const skill = fs.readFileSync(path.join(claudePluginPath(), "skills", "penny", "SKILL.md"), "utf8");
-    assert.ok(skill.includes("@penny $ARGUMENTS"));
+    const command = fs.readFileSync(claudeUserCommandPath(), "utf8");
+    assert.ok(command.includes("@penny $ARGUMENTS"));
 
     await removePennyHarness("claude-code");
+    assert.ok(!fs.existsSync(claudeUserCommandPath()));
+    fs.mkdirSync(path.dirname(claudeUserCommandPath()), { recursive: true });
+    fs.writeFileSync(claudeUserCommandPath(), "user-owned command\n");
+    await assert.rejects(configurePennyHarness("claude-code", {
+      apiKey: "pr-super-secret",
+      gatewayBaseUrl: "https://gateway.example/",
+      models: {},
+    }), /not managed by PennyRouter/);
+    assert.equal(fs.readFileSync(claudeUserCommandPath(), "utf8"), "user-owned command\n");
     assert.ok(fs.existsSync(codexLaunchProfilePath()));
     assert.ok(fs.existsSync(pennyShimPath()));
     await removePennyHarness("codex");

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,8 +0,0 @@
-{
-  "name": "pennyrouter",
-  "description": "PennyRouter in-session command alias for Claude Code",
-  "version": "1.0.0",
-  "author": {
-    "name": "PennyRouter"
-  }
-}

package/claude-plugin/skills/penny/SKILL.md

@@ -1,8 +0,0 @@
----
-name: penny
-description: Forward a PennyRouter command to the gateway. Use when the user invokes /penny.
-argument-hint: <command and arguments>
-disable-model-invocation: true
----
-
-@penny $ARGUMENTS