offrouter-cli 0.0.0

package/src/commands/profiles.ts

@@ -0,0 +1,58 @@
+import type { Command } from "commander";
+import { loadConfig } from "offrouter-core";
+import { writeJson, writeText } from "./output.js";
+import type { CommandContext } from "./init.js";
+
+export function registerProfilesCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  program
+    .command("profiles")
+    .description("List OffRouter profiles and allowlist status")
+    .option("--json", "Emit JSON", false)
+    .action(async (opts: { json?: boolean }) => {
+      const { env, cwd, stdout } = ctx();
+      try {
+        const config = await loadConfig({ env, workspaceDir: cwd });
+        const profiles = Object.values(config.profiles)
+          .map((p) => ({
+            id: p.id,
+            allowlisted: config.policy.allowlistedProfiles.includes(p.id),
+            deniedProviders: p.deniedProviders ?? [],
+          }))
+          .sort((a, b) => a.id.localeCompare(b.id));
+
+        const payload = {
+          allowlistedProfiles: [...config.policy.allowlistedProfiles].sort(),
+          deniedProfilePatterns: [
+            ...(config.policy.deniedProfilePatterns ?? []),
+          ].sort(),
+          profiles,
+        };
+
+        if (opts.json) {
+          writeJson(stdout, payload);
+          return;
+        }
+        writeText(
+          stdout,
+          `Allowlisted: ${payload.allowlistedProfiles.join(", ") || "(none)"}`,
+        );
+        writeText(
+          stdout,
+          `Denied patterns: ${payload.deniedProfilePatterns.join(", ") || "(none)"}`,
+        );
+        for (const p of profiles) {
+          writeText(stdout, `profile ${p.id}: allowlisted=${p.allowlisted}`);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (opts.json) {
+          writeJson(stdout, { error: message, profiles: [] });
+          return;
+        }
+        writeText(stdout, `Failed to load profiles: ${message}`);
+      }
+    });
+}

package/src/commands/proxy.ts

@@ -0,0 +1,87 @@
+import type { Command } from "commander";
+import {
+  createResponsesProxyContext,
+  loadConfig,
+  startResponsesProxy,
+  type HarnessRef,
+} from "offrouter-core";
+import type { CommandContext } from "./init.js";
+
+/**
+ * Minimal CLI bridge for the local OpenAI Responses-compatible proxy.
+ * Provider discovery (candidates/adapters) lands in a later phase; this starts
+ * the transparent gateway with the configured policy so custom-base-URL apps
+ * can point at OffRouter today.
+ */
+export function registerProxyCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  const proxy = program
+    .command("proxy")
+    .description("OffRouter transparent-gateway proxy bridges");
+
+  proxy
+    .command("serve")
+    .description(
+      "Start the local OpenAI Responses-compatible proxy (transparent gateway)",
+    )
+    .option(
+      "-p, --port <port>",
+      "TCP port (default 8787, env OFFROUTER_PROXY_PORT)",
+      (value: string) => Number.parseInt(value, 10),
+    )
+    .option("-H, --host <host>", "Bind host (default 127.0.0.1)")
+    .option(
+      "--profile <profile>",
+      "Harness profile to route as (must be allowlisted; default proxy)",
+    )
+    .action(
+      async (opts: {
+        port?: number;
+        host?: string;
+        profile?: string;
+      }) => {
+        const { env, cwd, stderr } = ctx();
+        const config = await loadConfig({
+          env,
+          workspaceDir: cwd,
+          workspaceTrusted: false,
+        });
+
+        const profile = opts.profile ?? "proxy";
+        const harness: HarnessRef = { kind: "other", profile };
+        const context = createResponsesProxyContext({
+          policy: config.policy,
+          // Provider discovery supplies candidates/adapters in a later phase.
+          candidates: [],
+          adapters: {},
+        });
+
+        const port =
+          opts.port ??
+          Number.parseInt(env.OFFROUTER_PROXY_PORT ?? "8787", 10);
+        const host = opts.host ?? env.OFFROUTER_PROXY_HOST ?? "127.0.0.1";
+        const token = env.OFFROUTER_PROXY_TOKEN;
+
+        const handle = await startResponsesProxy(context, {
+          port,
+          host,
+          token,
+          harness,
+          workspace: { cwd, trusted: true },
+        });
+
+        stderr.write(
+          `OffRouter proxy listening on http://${host}:${handle.port} (profile=${profile})\n`,
+        );
+
+        const shutdown = async (): Promise<void> => {
+          await handle.close();
+          process.exit(0);
+        };
+        process.on("SIGINT", () => void shutdown());
+        process.on("SIGTERM", () => void shutdown());
+      },
+    );
+}

package/src/commands/route.ts

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import type { Command } from "commander";
+import {
+  loadConfig,
+  routeRequest,
+  type HarnessKind,
+  type RouteRequest,
+} from "offrouter-core";
+import { formatConfigError } from "./config-error.js";
+import { writeJson, writeText } from "./output.js";
+import type { CommandContext } from "./init.js";
+
+function harnessKindFromProfile(profile: string): HarnessKind {
+  if (profile.startsWith("claude")) return "claude";
+  if (profile.startsWith("codex")) return "codex";
+  if (profile.startsWith("gemini")) return "gemini";
+  if (profile.startsWith("grok")) return "grok";
+  if (profile.startsWith("cursor")) return "cursor";
+  if (profile.startsWith("pi")) return "pi";
+  return "other";
+}
+
+function buildRequest(
+  prompt: string,
+  profile: string,
+  cwd: string,
+): RouteRequest {
+  const preview = prompt.length > 200 ? `${prompt.slice(0, 200)}...` : prompt;
+  const digest = createHash("sha256").update(prompt).digest("hex");
+  return {
+    protocolVersion: "offrouter.route.v1",
+    requestId: `cli_route_${digest.slice(0, 12)}`,
+    harness: {
+      kind: harnessKindFromProfile(profile),
+      profile,
+    },
+    task: {
+      promptPreview: preview,
+      promptDigest: digest,
+      kind: "explain",
+      risk: "low",
+    },
+    workspace: {
+      cwd,
+      // CLI explain is an explicit local dry run and does not load project config.
+      // Harness adapters will pass real workspace trust when they route live work.
+      trusted: true,
+    },
+    constraints: {
+      subscriptionFirst: true,
+      allowApiKeyFallback: false,
+    },
+  };
+}
+
+export function registerRouteCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  const route = program
+    .command("route")
+    .description("Route or explain routing decisions (no live provider calls)");
+
+  route
+    .command("explain")
+    .description("Explain how OffRouter would route a prompt under policy")
+    .argument(
+      "<prompt>",
+      "Prompt text used only for preview + digest (not sent to providers)",
+    )
+    .requiredOption(
+      "--profile <profile>",
+      "Harness profile id (e.g. claude-personal)",
+    )
+    .option("--json", "Emit JSON decision", false)
+    .action(
+      async (prompt: string, opts: { profile: string; json?: boolean }) => {
+        const { env, cwd, stdout } = ctx();
+        const request = buildRequest(prompt, opts.profile, cwd);
+
+        let policyConfig;
+        try {
+          const config = await loadConfig({ env, workspaceDir: cwd });
+          policyConfig = config.policy;
+        } catch (err) {
+          const configError = formatConfigError(err);
+          const decision = {
+            protocolVersion: request.protocolVersion,
+            decisionId: `dec_${request.requestId}_config_error`,
+            requestId: request.requestId,
+            route: null,
+            reason: "config_error",
+            explanation: `Invalid OffRouter config: ${configError.message}`,
+            fallbackChain: [],
+            policyDenials: [],
+            confidence: 1,
+            auditSummary: `Blocked config_error profile=${request.harness.profile} digest=${request.task.promptDigest}`,
+            blocked: true,
+            needsConfiguration: false,
+            setupIncomplete: false,
+            setupMessage: null,
+            configError,
+          };
+          if (opts.json) {
+            writeJson(stdout, decision);
+            return;
+          }
+          writeText(
+            stdout,
+            `Cannot route (config_error): ${decision.explanation}`,
+          );
+          return;
+        }
+
+        // No provider catalog in this milestone - empty candidates yield needsConfiguration
+        // or a profile hard block for work/denied profiles.
+        const decision = routeRequest(request, [], policyConfig);
+        const setupIncomplete = decision.needsConfiguration === true;
+
+        if (opts.json) {
+          writeJson(stdout, {
+            ...decision,
+            setupIncomplete,
+            setupMessage: setupIncomplete
+              ? "Setup incomplete: configure a subscription, local runtime, or API-key provider, and allowlist a personal profile."
+              : null,
+          });
+          return;
+        }
+
+        if (
+          decision.blocked ||
+          decision.needsConfiguration ||
+          !decision.route
+        ) {
+          writeText(
+            stdout,
+            `Cannot route (${decision.reason}): ${decision.explanation}`,
+          );
+          if (decision.policyDenials && decision.policyDenials.length > 0) {
+            for (const d of decision.policyDenials) {
+              writeText(stdout, `- [${d.code}] ${d.message}`);
+            }
+          }
+          if (setupIncomplete) {
+            writeText(
+              stdout,
+              "Setup incomplete: configure a subscription, local runtime, or API-key provider, and allowlist a personal profile.",
+            );
+          }
+          return;
+        }
+
+        writeText(
+          stdout,
+          `Route: ${decision.route.provider}/${decision.route.model} (${decision.route.authTier}) - ${decision.explanation}`,
+        );
+      },
+    );
+}

package/src/commands/status.ts

@@ -0,0 +1,111 @@
+import type { Command } from "commander";
+import { loadConfig } from "offrouter-core";
+import { formatConfigError, type CliConfigError } from "./config-error.js";
+import { detectEnvironment, V1_HONESTY_LINE } from "./detection.js";
+import { writeJson, writeText } from "./output.js";
+import type { CommandContext } from "./init.js";
+
+export function registerStatusCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  program
+    .command("status")
+    .description("Show OffRouter status")
+    .option("--providers", "Include per-provider readiness detail", false)
+    .option("--json", "Emit JSON", false)
+    .action(async (opts: { providers?: boolean; json?: boolean }) => {
+      const { env, cwd, stdout } = ctx();
+      const detection = await detectEnvironment({ env, cwd });
+
+      let providers: Array<{
+        id: string;
+        enabled: boolean;
+        authTierHints: string[];
+        subscriptionStatus: string;
+        apiKeyReady: boolean;
+        localReady: boolean;
+        limitStatus: string;
+        lastError: string | null;
+      }> = [];
+      let configError: CliConfigError | null = null;
+
+      try {
+        const config = await loadConfig({ env, workspaceDir: cwd });
+        providers = Object.values(config.providers)
+          .map((p) => ({
+            id: p.id,
+            enabled: p.enabled,
+            authTierHints: [
+              ...(detection.authTiers.subscription
+                ? (["subscription"] as const)
+                : []),
+              ...(detection.authTiers.local ? (["local"] as const) : []),
+              ...(detection.authTiers["api-key"] ? (["api-key"] as const) : []),
+            ],
+            subscriptionStatus: detection.subscription.status,
+            apiKeyReady: detection.apiKeyReadiness.anyReady,
+            localReady: detection.localRuntime.health !== "unconfigured",
+            limitStatus: detection.limits.status,
+            lastError: detection.lastProviderError,
+          }))
+          .sort((a, b) => a.id.localeCompare(b.id));
+      } catch (err) {
+        configError = formatConfigError(err);
+        providers = [];
+      }
+
+      // When no providers are configured, still expose a readiness row for status --providers.
+      if (opts.providers && providers.length === 0) {
+        providers = [
+          {
+            id: "(none-configured)",
+            enabled: false,
+            authTierHints: Object.entries(detection.authTiers)
+              .filter(([, v]) => v)
+              .map(([k]) => k),
+            subscriptionStatus: detection.subscription.status,
+            apiKeyReady: detection.apiKeyReadiness.anyReady,
+            localReady: detection.localRuntime.health !== "unconfigured",
+            limitStatus: detection.limits.status,
+            lastError: detection.lastProviderError,
+          },
+        ];
+      }
+
+      const payload = {
+        honesty: V1_HONESTY_LINE,
+        harnessProfiles: detection.harnessProfiles,
+        authTiers: detection.authTiers,
+        subscription: detection.subscription,
+        apiKeyReadiness: detection.apiKeyReadiness,
+        localRuntime: detection.localRuntime,
+        limits: detection.limits,
+        lastProviderError: detection.lastProviderError,
+        configError,
+        ...(opts.providers ? { providers } : {}),
+      };
+
+      if (opts.json) {
+        writeJson(stdout, payload);
+        return;
+      }
+
+      writeText(stdout, V1_HONESTY_LINE);
+      writeText(
+        stdout,
+        `Subscription: ${detection.subscription.status}; API-key ready: ${detection.apiKeyReadiness.anyReady}; local: ${detection.localRuntime.health}`,
+      );
+      if (opts.providers) {
+        for (const p of providers) {
+          writeText(
+            stdout,
+            `provider ${p.id}: enabled=${p.enabled} subscription=${p.subscriptionStatus} apiKeyReady=${p.apiKeyReady} localReady=${p.localReady} limits=${p.limitStatus}`,
+          );
+        }
+      }
+      if (configError) {
+        writeText(stdout, `Config error: ${configError.message}`);
+      }
+    });
+}

package/src/commands/update.ts

@@ -0,0 +1,62 @@
+import type { Command } from "commander";
+import type { CommandContext } from "./init.js";
+import { writeJson, writeText } from "./output.js";
+import { fetchCatalogCache } from "../catalog-cache.js";
+
+/**
+ * `offrouter update` — fetch the latest model catalog and cache it locally.
+ * No telemetry. The only network call is a GET to the public static catalog
+ * file; no user data is transmitted.
+ */
+export function registerUpdateCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  program
+    .command("update")
+    .description(
+      "Fetch and cache the latest model catalog from the remote source",
+    )
+    .option("--json", "Emit JSON", false)
+    .option("--dry-run", "Fetch but do not write cache", false)
+    .action(async (opts: { json?: boolean; dryRun?: boolean }) => {
+      const { env, stdout } = ctx();
+      const dryRun = opts.dryRun ?? false;
+
+      const result = await fetchCatalogCache({
+        env,
+        dryRun,
+      });
+
+      const familyCount = result.data?.families.length ?? 0;
+
+      if (opts.json) {
+        writeJson(stdout, {
+          source: result.source,
+          fetchedAt: result.fetchedAt,
+          familyCount,
+          dryRun,
+          version: result.data?.version ?? null,
+        });
+        return;
+      }
+
+      if (result.source === "network") {
+        const verb = dryRun ? "Fetched (dry-run, not cached)" : "Updated";
+        writeText(
+          stdout,
+          `${verb} catalog: ${familyCount} model families from remote (${result.fetchedAt})`,
+        );
+      } else if (result.source === "cache") {
+        writeText(
+          stdout,
+          `Using cached catalog: ${familyCount} model families (offline, fetched ${result.fetchedAt})`,
+        );
+      } else {
+        writeText(
+          stdout,
+          "No catalog data available. Using built-in catalog.",
+        );
+      }
+    });
+}

package/src/index.ts

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import type { CommandContext } from "./commands/init.js";
+import { registerInitCommand } from "./commands/init.js";
+import { registerDoctorCommand } from "./commands/doctor.js";
+import { registerLoginCommand } from "./commands/login.js";
+import { registerModelsCommand } from "./commands/models.js";
+import { registerProfilesCommand } from "./commands/profiles.js";
+import { registerRouteCommand } from "./commands/route.js";
+import { registerStatusCommand } from "./commands/status.js";
+import { registerUpdateCommand } from "./commands/update.js";
+import { registerMcpCommand } from "./commands/mcp.js";
+import { registerHooksCommand } from "./commands/hooks.js";
+import { registerProxyCommand } from "./commands/proxy.js";
+import {
+  registerInstallCommand,
+  registerUninstallCommand,
+} from "./commands/install.js";
+import type { IoStreams } from "./commands/output.js";
+
+export const CLI_PACKAGE = "offrouter-cli" as const;
+
+export interface RunCliOptions {
+  /** Working directory for config / workspace trust. */
+  cwd?: string;
+  /** Env override (tests). */
+  env?: NodeJS.ProcessEnv;
+  /** Injected stdin for hook bridges (tests). */
+  stdin?: string;
+  stdout?: IoStreams;
+  stderr?: IoStreams;
+}
+
+function defaultStream(stream: NodeJS.WriteStream): IoStreams {
+  return {
+    write(chunk: string) {
+      return stream.write(chunk);
+    },
+  };
+}
+
+async function readProcessStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Build the Commander program without parsing argv.
+ * Register commands against a shared context factory for injectable IO.
+ */
+export function createProgram(options: RunCliOptions = {}): Command {
+  let stdinCache: string | undefined;
+  const readStdin = async (): Promise<string> => {
+    if (options.stdin !== undefined) {
+      return options.stdin;
+    }
+    if (stdinCache !== undefined) {
+      return stdinCache;
+    }
+    stdinCache = await readProcessStdin();
+    return stdinCache;
+  };
+
+  const ctx = (): CommandContext => ({
+    env: options.env ?? process.env,
+    cwd: options.cwd ?? process.cwd(),
+    stdout: options.stdout ?? defaultStream(process.stdout),
+    stderr: options.stderr ?? defaultStream(process.stderr),
+    readStdin,
+  });
+
+  const stdout = options.stdout ?? defaultStream(process.stdout);
+  const stderr = options.stderr ?? defaultStream(process.stderr);
+
+  const program = new Command();
+  program
+    .name("offrouter")
+    .description(
+      "Local-first router for coding-agent harnesses. Claude Code's primary model is unchanged in V1; OffRouter routes delegated work.",
+    )
+    .version("0.0.0")
+    .showHelpAfterError()
+    .configureOutput({
+      writeOut: (str) => {
+        stdout.write(str);
+      },
+      writeErr: (str) => {
+        stderr.write(str);
+      },
+    })
+    .exitOverride();
+
+  registerInitCommand(program, ctx);
+  registerDoctorCommand(program, ctx);
+  registerLoginCommand(program, ctx);
+  registerModelsCommand(program, ctx);
+  registerProfilesCommand(program, ctx);
+  registerRouteCommand(program, ctx);
+  registerStatusCommand(program, ctx);
+  registerUpdateCommand(program, ctx);
+  registerMcpCommand(program, ctx);
+  registerHooksCommand(program, ctx);
+  registerProxyCommand(program, ctx);
+  registerInstallCommand(program, ctx);
+  registerUninstallCommand(program, ctx);
+
+  return program;
+}
+
+/**
+ * Parse argv (without node/script) and run the selected command.
+ * @returns process exit code (0 success, nonzero usage/runtime failure)
+ */
+export async function runCli(
+  argv: string[] = process.argv.slice(2),
+  options: RunCliOptions = {},
+): Promise<number> {
+  const stderr = options.stderr ?? defaultStream(process.stderr);
+  const program = createProgram(options);
+
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return 0;
+  } catch (err) {
+    // Commander exitOverride throws CommanderError with exitCode.
+    if (
+      err &&
+      typeof err === "object" &&
+      "exitCode" in err &&
+      typeof (err as { exitCode: unknown }).exitCode === "number"
+    ) {
+      const code = (
+        err as { exitCode: number; message?: string; code?: string }
+      ).exitCode;
+      // help/version use exitCode 0
+      if (code === 0) {
+        return 0;
+      }
+      const message = err instanceof Error ? err.message : "Command failed";
+      if (message) {
+        stderr.write(`${message}\n`);
+      }
+      return code || 1;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    stderr.write(`${message}\n`);
+    return 1;
+  }
+}
+
+function isEntrypoint(): boolean {
+  if (!process.argv[1]) {
+    return false;
+  }
+  try {
+    return (
+      realpathSync(process.argv[1]) ===
+      realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isEntrypoint()) {
+  void runCli(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"],
+  "references": [
+    { "path": "../core" },
+    { "path": "../adapter-claude" },
+    { "path": "../adapter-codex" },
+    { "path": "../adapter-gemini" },
+    { "path": "../adapter-grok" },
+    { "path": "../mcp" }
+  ]
+}