offrouter-cli 0.0.0

package/src/commands/install.ts

@@ -0,0 +1,438 @@
+/**
+ * CLI install / uninstall for harness plugins (Claude / Codex V1).
+ */
+import type { Command } from "commander";
+import { loadConfig } from "offrouter-core";
+import {
+  formatInstallDiffText as formatClaudeDiff,
+  installClaudeProfile,
+  listAllowlistedPersonalClaudeProfiles,
+  rollbackClaudeProfile,
+  type ClaudeInstallResult,
+  type ClaudeRollbackResult,
+} from "offrouter-adapter-claude";
+import {
+  formatInstallDiffText as formatCodexDiff,
+  installCodexProfile,
+  listAllowlistedPersonalCodexProfiles,
+  rollbackCodexProfile,
+  type CodexInstallResult,
+  type CodexRollbackResult,
+} from "offrouter-adapter-codex";
+import {
+  formatInstallDiffText as formatGeminiDiff,
+  installGeminiProfile,
+  listAllowlistedPersonalGeminiProfiles,
+  rollbackGeminiProfile,
+  type GeminiInstallResult,
+  type GeminiRollbackResult,
+} from "offrouter-adapter-gemini";
+import {
+  formatInstallDiffText as formatGrokDiff,
+  installGrokProfile,
+  listAllowlistedPersonalGrokProfiles,
+  rollbackGrokProfile,
+  type GrokInstallResult,
+  type GrokRollbackResult,
+} from "offrouter-adapter-grok";
+import type { CommandContext } from "./init.js";
+import { writeJson, writeText } from "./output.js";
+import { honestyForHarness } from "./detection.js";
+import { formatConfigError } from "./config-error.js";
+
+type HarnessKind = "claude" | "codex" | "gemini" | "grok";
+
+type InstallResultUnion =
+  | ClaudeInstallResult
+  | CodexInstallResult
+  | GeminiInstallResult
+  | GrokInstallResult;
+type RollbackResultUnion =
+  | ClaudeRollbackResult
+  | CodexRollbackResult
+  | GeminiRollbackResult
+  | GrokRollbackResult;
+
+function assertHarness(harness: string): HarnessKind {
+  if (
+    harness !== "claude" &&
+    harness !== "codex" &&
+    harness !== "gemini" &&
+    harness !== "grok"
+  ) {
+    throw new Error(
+      `Unsupported harness "${harness}". V1 install currently supports: claude, codex, gemini, grok`,
+    );
+  }
+  return harness;
+}
+
+function harnessLabel(kind: HarnessKind): string {
+  if (kind === "codex") return "Codex";
+  if (kind === "gemini") return "Gemini";
+  if (kind === "grok") return "Grok";
+  return "Claude";
+}
+
+function allowlistedPersonalProfiles(
+  kind: HarnessKind,
+  config: Parameters<typeof listAllowlistedPersonalClaudeProfiles>[0],
+): string[] {
+  if (kind === "codex") return listAllowlistedPersonalCodexProfiles(config);
+  if (kind === "gemini") return listAllowlistedPersonalGeminiProfiles(config);
+  if (kind === "grok") return listAllowlistedPersonalGrokProfiles(config);
+  return listAllowlistedPersonalClaudeProfiles(config);
+}
+
+async function installOne(
+  kind: HarnessKind,
+  args: {
+    profile: string;
+    config: Parameters<typeof installClaudeProfile>[0]["config"];
+    env: NodeJS.ProcessEnv;
+    dryRun: boolean;
+  },
+): Promise<InstallResultUnion> {
+  if (kind === "codex") {
+    return installCodexProfile(args);
+  }
+  if (kind === "gemini") {
+    return installGeminiProfile(args);
+  }
+  if (kind === "grok") {
+    return installGrokProfile(args);
+  }
+  return installClaudeProfile(args);
+}
+
+async function rollbackOne(
+  kind: HarnessKind,
+  args: {
+    profile: string;
+    env: NodeJS.ProcessEnv;
+    dryRun: boolean;
+  },
+): Promise<RollbackResultUnion> {
+  if (kind === "codex") {
+    return rollbackCodexProfile(args);
+  }
+  if (kind === "gemini") {
+    return rollbackGeminiProfile(args);
+  }
+  if (kind === "grok") {
+    return rollbackGrokProfile(args);
+  }
+  return rollbackClaudeProfile(args);
+}
+
+function formatDiff(
+  kind: HarnessKind,
+  results: InstallResultUnion[],
+  headline?: string,
+): string {
+  if (kind === "codex") {
+    return formatCodexDiff(
+      results as unknown as CodexInstallResult[],
+      headline,
+    );
+  }
+  if (kind === "gemini") {
+    return formatGeminiDiff(
+      results as unknown as GeminiInstallResult[],
+      headline,
+    );
+  }
+  if (kind === "grok") {
+    return formatGrokDiff(results as unknown as GrokInstallResult[], headline);
+  }
+  return formatClaudeDiff(
+    results as unknown as ClaudeInstallResult[],
+    headline,
+  );
+}
+
+function resultExitCode(results: Array<{ ok: boolean }>): number {
+  return results.every((r) => r.ok) ? 0 : 1;
+}
+
+export function registerInstallCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  const install = program
+    .command("install")
+    .description(
+      "Install OffRouter into an allowlisted personal harness profile",
+    )
+    .option(
+      "--all-personal",
+      "Install into every allowlisted personal harness profile (Claude or Codex)",
+      false,
+    )
+    .option("--dry-run", "Show planned file changes without writing", false)
+    .option("--json", "Emit JSON", false)
+    .argument("[harness]", "Harness kind (V1: claude, codex)", "claude")
+    .option(
+      "--profile <profile>",
+      "Target profile id (e.g. claude-personal, codex-personal). Required unless --all-personal.",
+    )
+    .action(
+      async (
+        harness: string,
+        opts: {
+          profile?: string;
+          allPersonal?: boolean;
+          dryRun?: boolean;
+          json?: boolean;
+        },
+      ) => {
+        const { env, cwd, stdout, stderr } = ctx();
+        let kind: HarnessKind = "claude";
+        try {
+          kind = assertHarness(harness);
+          const config = await loadConfig({ env, workspaceDir: cwd });
+          const dryRun = Boolean(opts.dryRun);
+          const allPersonal = Boolean(opts.allPersonal);
+          const profile = opts.profile?.trim();
+
+          if (allPersonal && profile) {
+            throw new Error(
+              "Use either --profile <id> or --all-personal, not both.",
+            );
+          }
+
+          if (!allPersonal && !profile) {
+            throw new Error(
+              "Provide --profile <id> or --all-personal. Example: offrouter install claude --profile claude-personal --dry-run",
+            );
+          }
+
+          const targets = allPersonal
+            ? allowlistedPersonalProfiles(kind, config)
+            : [profile!];
+
+          const honesty = honestyForHarness(kind);
+          const label = harnessLabel(kind);
+
+          if (targets.length === 0) {
+            const empty: InstallResultUnion[] = [];
+            if (opts.json) {
+              writeJson(stdout, {
+                honesty,
+                dryRun,
+                harness: kind,
+                results: empty,
+                message: `No allowlisted personal ${label} profiles found for install.`,
+              });
+              return;
+            }
+            writeText(stdout, honesty);
+            writeText(
+              stdout,
+              `No allowlisted personal ${label} profiles found for install.`,
+            );
+            return;
+          }
+
+          const results: InstallResultUnion[] = [];
+          for (const target of targets) {
+            results.push(
+              await installOne(kind, { profile: target, config, env, dryRun }),
+            );
+          }
+
+          if (opts.json) {
+            writeJson(stdout, {
+              honesty,
+              dryRun,
+              harness: kind,
+              results,
+            });
+          } else {
+            writeText(stdout, honesty);
+            const headline = allPersonal
+              ? `Install matrix (allowlisted personal ${label} profiles):`
+              : undefined;
+            writeText(stdout, formatDiff(kind, results, headline).trimEnd());
+          }
+
+          if (resultExitCode(results) !== 0) {
+            const failed = results.filter((r) => !r.ok);
+            const msg = failed.map((r) => r.message).join("; ");
+            // Commander exitOverride path
+            const err = new Error(msg) as Error & { exitCode?: number };
+            err.exitCode = 1;
+            throw err;
+          }
+        } catch (err) {
+          if (
+            err &&
+            typeof err === "object" &&
+            "exitCode" in err &&
+            typeof (err as { exitCode: unknown }).exitCode === "number"
+          ) {
+            throw err;
+          }
+          const formatted = formatConfigError(err);
+          const honesty = honestyForHarness(kind);
+          if (opts.json) {
+            writeJson(stdout, {
+              honesty,
+              error: formatted,
+            });
+            const e = new Error(formatted.message) as Error & {
+              exitCode?: number;
+            };
+            e.exitCode = 1;
+            throw e;
+          }
+          writeText(stderr, formatted.message);
+          const e = new Error(formatted.message) as Error & {
+            exitCode?: number;
+          };
+          e.exitCode = 1;
+          throw e;
+        }
+      },
+    );
+
+  // Silence unused local if tree-shaking complains; keep reference stable.
+  void install;
+}
+
+export function registerUninstallCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  program
+    .command("uninstall")
+    .description("Uninstall / roll back OffRouter from a harness profile")
+    .argument("[harness]", "Harness kind (V1: claude, codex)", "claude")
+    .option(
+      "--profile <profile>",
+      "Target profile id (e.g. claude-personal, codex-personal)",
+    )
+    .option(
+      "--all-personal",
+      "Uninstall from every allowlisted personal harness profile that has install state",
+      false,
+    )
+    .option("--dry-run", "Show planned rollback without writing", false)
+    .option("--json", "Emit JSON", false)
+    .action(
+      async (
+        harness: string,
+        opts: {
+          profile?: string;
+          allPersonal?: boolean;
+          dryRun?: boolean;
+          json?: boolean;
+        },
+      ) => {
+        const { env, cwd, stdout, stderr } = ctx();
+        let kind: HarnessKind = "claude";
+        try {
+          kind = assertHarness(harness);
+          const config = await loadConfig({ env, workspaceDir: cwd });
+          const dryRun = Boolean(opts.dryRun);
+          const allPersonal = Boolean(opts.allPersonal);
+          const profile = opts.profile?.trim();
+
+          if (allPersonal && profile) {
+            throw new Error(
+              "Use either --profile <id> or --all-personal, not both.",
+            );
+          }
+
+          if (!allPersonal && !profile) {
+            throw new Error(
+              "Provide --profile <id> or --all-personal. Example: offrouter uninstall claude --profile claude-personal",
+            );
+          }
+
+          const targets = allPersonal
+            ? allowlistedPersonalProfiles(kind, config)
+            : [profile!];
+
+          const results: RollbackResultUnion[] = [];
+          for (const target of targets) {
+            results.push(
+              await rollbackOne(kind, { profile: target, env, dryRun }),
+            );
+          }
+
+          // Map rollback results into install-result-like text blocks.
+          const asInstallish: InstallResultUnion[] = results.map((r) => ({
+            ok: r.ok,
+            dryRun: r.dryRun,
+            profile: r.profile,
+            profileDir: r.profileDir,
+            changes: r.changes,
+            message: r.message,
+            errorCode: r.ok
+              ? undefined
+              : r.errorCode === "no_install_state"
+                ? "install_error"
+                : "install_error",
+          }));
+
+          const honesty = honestyForHarness(kind);
+
+          if (opts.json) {
+            writeJson(stdout, {
+              honesty,
+              dryRun,
+              harness: kind,
+              results,
+            });
+          } else {
+            writeText(stdout, honesty);
+            writeText(
+              stdout,
+              formatDiff(kind, asInstallish, "Uninstall / rollback:").trimEnd(),
+            );
+          }
+
+          // Missing state on --all-personal is soft; invalid state/errors fail.
+          const hardFailures = results.filter(
+            (r) =>
+              !r.ok && (!allPersonal || r.errorCode !== "no_install_state"),
+          );
+          if (hardFailures.length > 0) {
+            const msg = hardFailures.map((r) => r.message).join("; ");
+            const err = new Error(msg) as Error & { exitCode?: number };
+            err.exitCode = 1;
+            throw err;
+          }
+        } catch (err) {
+          if (
+            err &&
+            typeof err === "object" &&
+            "exitCode" in err &&
+            typeof (err as { exitCode: unknown }).exitCode === "number"
+          ) {
+            throw err;
+          }
+          const formatted = formatConfigError(err);
+          const honesty = honestyForHarness(kind);
+          if (opts.json) {
+            writeJson(stdout, {
+              honesty,
+              error: formatted,
+            });
+            const e = new Error(formatted.message) as Error & {
+              exitCode?: number;
+            };
+            e.exitCode = 1;
+            throw e;
+          }
+          writeText(stderr, formatted.message);
+          const e = new Error(formatted.message) as Error & {
+            exitCode?: number;
+          };
+          e.exitCode = 1;
+          throw e;
+        }
+      },
+    );
+}

package/src/commands/login.ts

@@ -0,0 +1,33 @@
+import type { Command } from "commander";
+import { V1_HONESTY_LINE } from "./detection.js";
+import { writeJson, writeText } from "./output.js";
+import type { CommandContext } from "./init.js";
+
+export function registerLoginCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  program
+    .command("login")
+    .description(
+      "Guide official provider login / token-helper flows (no credential scraping)",
+    )
+    .argument("[provider]", "Provider id (optional)")
+    .option("--json", "Emit JSON", false)
+    .action(async (provider: string | undefined, opts: { json?: boolean }) => {
+      const { stdout } = ctx();
+      const payload = {
+        honesty: V1_HONESTY_LINE,
+        provider: provider ?? null,
+        status: "not_implemented",
+        message:
+          "Login uses official provider login, token-helper, OAuth, or user-provided API key surfaces only. Provider adapters land in a later milestone.",
+      };
+      if (opts.json) {
+        writeJson(stdout, payload);
+        return;
+      }
+      writeText(stdout, V1_HONESTY_LINE);
+      writeText(stdout, payload.message);
+    });
+}

package/src/commands/mcp.ts

@@ -0,0 +1,35 @@
+import type { Command } from "commander";
+import { runMcpCli } from "offrouter-mcp";
+import type { CommandContext } from "./init.js";
+
+export function registerMcpCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  const mcp = program
+    .command("mcp")
+    .description("OffRouter MCP stdio server bridges");
+
+  mcp
+    .command("serve")
+    .description(
+      "Start the OffRouter MCP stdio server (route/delegate/status tools)",
+    )
+    .action(async (_opts: unknown, command: Command) => {
+      const { env, cwd, stdout, stderr } = ctx();
+      // Forward only unknown/passthrough args after `serve`; Commander already
+      // handled --help before invoking this action.
+      const forwarded = command.args ?? [];
+      const code = await runMcpCli(forwarded, {
+        env,
+        cwd,
+        stdout,
+        stderr,
+      });
+      if (code !== 0) {
+        const err = new Error(`MCP server exited with code ${code}`);
+        (err as { exitCode?: number }).exitCode = code;
+        throw err;
+      }
+    });
+}

package/src/commands/models.ts

@@ -0,0 +1,168 @@
+import type { Command } from "commander";
+import { loadConfig, BUILTIN_PROVIDERS } from "offrouter-core";
+import { formatConfigError, type CliConfigError } from "./config-error.js";
+import { writeJson, writeText } from "./output.js";
+import type { CommandContext } from "./init.js";
+import { readCatalogCache, resolveCacheDir } from "../catalog-cache.js";
+import type { CachedModelFamily } from "../catalog-cache.js";
+
+/**
+ * A single model entry in the merged output.
+ * source: "builtin" from core package, "cached" from remote catalog, "config" from profile config.
+ */
+export interface ModelEntry {
+  providerId: string;
+  modelId: string;
+  displayName?: string;
+  family?: string;
+  source: "builtin" | "cached" | "config";
+}
+
+function builtinToEntries(): ModelEntry[] {
+  const entries: ModelEntry[] = [];
+  for (const provider of BUILTIN_PROVIDERS) {
+    for (const model of provider.knownModels) {
+      entries.push({
+        providerId: provider.providerId,
+        modelId: model.modelId,
+        displayName: model.displayName,
+        family: model.family,
+        source: "builtin",
+      });
+    }
+  }
+  return entries;
+}
+
+function cachedToEntries(cached: { families: CachedModelFamily[] }): ModelEntry[] {
+  return cached.families.map((f) => ({
+    providerId: f.providerId,
+    modelId: f.modelId,
+    displayName: f.displayName,
+    family: f.family,
+    source: "cached" as const,
+  }));
+}
+
+/**
+ * Merge builtin and cached model entries.
+ * Cached models with the same (providerId, modelId) override builtin entries.
+ * Config provider entries are appended separately.
+ */
+function mergeModels(
+  builtin: ModelEntry[],
+  cached: ModelEntry[],
+  config: ModelEntry[],
+): ModelEntry[] {
+  // Build a set of (providerId,modelId) from cached entries that override builtin
+  const cachedKeys = new Set<string>();
+  for (const entry of cached) {
+    cachedKeys.add(`${entry.providerId}:${entry.modelId}`);
+  }
+
+  // Filter builtin entries that are not overridden by cached
+  const merged = builtin.filter(
+    (b) => !cachedKeys.has(`${b.providerId}:${b.modelId}`),
+  );
+
+  // Add all cached entries
+  merged.push(...cached);
+
+  // Add config entries (providers from config.toml)
+  // Config entries with same (providerId, modelId) override both builtin and cached
+  const mergedKeys = new Set<string>();
+  for (const entry of merged) {
+    mergedKeys.add(`${entry.providerId}:${entry.modelId}`);
+  }
+  for (const entry of config) {
+    if (!mergedKeys.has(`${entry.providerId}:${entry.modelId}`)) {
+      merged.push(entry);
+    }
+  }
+
+  return merged;
+}
+
+export function registerModelsCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  program
+    .command("models")
+    .description(
+      "List known models from builtin catalog, cached remote catalog, and config",
+    )
+    .option("--json", "Emit JSON", false)
+    .action(async (opts: { json?: boolean }) => {
+      const { env, cwd, stdout } = ctx();
+
+      // 1. Builtin models from offrouter-core
+      const builtinEntries = builtinToEntries();
+
+      // 2. Cached models from remote catalog (if available)
+      let cachedEntries: ModelEntry[] = [];
+      const cacheDir = resolveCacheDir(env);
+      const cachedData = readCatalogCache(cacheDir);
+      if (cachedData) {
+        cachedEntries = cachedToEntries(cachedData);
+      }
+
+      // 3. Config providers
+      let configEntries: ModelEntry[] = [];
+      let configError: CliConfigError | null = null;
+      try {
+        const config = await loadConfig({ env, workspaceDir: cwd });
+        configEntries = Object.keys(config.providers)
+          .sort()
+          .map((providerId) => ({
+            providerId,
+            modelId: "*",
+            source: "config" as const,
+          }));
+      } catch (err) {
+        configError = formatConfigError(err);
+      }
+
+      // Merge: cached overrides builtin (same providerId+modelId), config appended
+      const models = mergeModels(builtinEntries, cachedEntries, configEntries);
+
+      if (opts.json) {
+        writeJson(stdout, {
+          models,
+          builtinCount: builtinEntries.length,
+          cachedCount: cachedEntries.length,
+          configCount: configEntries.length,
+          configError,
+        });
+        return;
+      }
+      if (configError) {
+        writeText(stdout, `Config error: ${configError.message}`);
+        return;
+      }
+      if (models.length === 0) {
+        writeText(
+          stdout,
+          "No models available.",
+        );
+        return;
+      }
+      // Group by source for display
+      const builtinModels = models.filter((m) => m.source === "builtin");
+      const cachedModels = models.filter((m) => m.source === "cached");
+      const configProviderIds = models.filter((m) => m.source === "config");
+
+      writeText(stdout, `Models (${models.length} total):`);
+      writeText(stdout, `  Built-in: ${builtinModels.length} models`);
+      writeText(stdout, `  Cached: ${cachedModels.length} models`);
+      writeText(stdout, `  Config providers: ${configProviderIds.length}`);
+      writeText(stdout, "");
+      for (const m of models) {
+        const name = m.displayName ? `${m.displayName} (${m.modelId})` : m.modelId;
+        writeText(
+          stdout,
+          `  ${m.providerId}/${name} (${m.source})`,
+        );
+      }
+    });
+}

package/src/commands/output.ts

@@ -0,0 +1,11 @@
+export interface IoStreams {
+  write(chunk: string): boolean | void;
+}
+
+export function writeJson(stream: IoStreams, value: unknown): void {
+  stream.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function writeText(stream: IoStreams, text: string): void {
+  stream.write(text.endsWith("\n") ? text : `${text}\n`);
+}