offrouter-cli 0.0.0

package/src/commands/doctor.ts

@@ -0,0 +1,503 @@
+import type { Command } from "commander";
+import { access, constants, readFile } from "node:fs/promises";
+import { delimiter } from "node:path";
+import { dirname, join, normalize } from "node:path";
+import {
+  evaluatePolicy,
+  loadConfig,
+  redact,
+  routeRequest,
+  type ConfigWarning,
+  type HarnessKind,
+  type PolicyConfig,
+  type RouteRequest,
+} from "offrouter-core";
+import { formatConfigError, type CliConfigError } from "./config-error.js";
+import { detectEnvironment, V1_HONESTY_LINE } from "./detection.js";
+import { writeJson, writeText, type IoStreams } from "./output.js";
+import type { CommandContext } from "./init.js";
+
+interface NodeDiagnostic {
+  version: string;
+  engineRequirement: string | null;
+  engineSource: string | null;
+  satisfiesEngine: boolean | null;
+}
+
+interface CommandAvailability {
+  command: string;
+  executable: string;
+  available: boolean;
+  path: string | null;
+}
+
+function secretValues(env: NodeJS.ProcessEnv): string[] {
+  return Object.entries(env)
+    .filter(([key, value]) => {
+      if (typeof value !== "string" || value.length === 0) return false;
+      return /(api_?key|token|secret|password)/i.test(key);
+    })
+    .map(([, value]) => value as string);
+}
+
+function redactDiagnostic(value: string, env: NodeJS.ProcessEnv): string {
+  return redact(value, secretValues(env));
+}
+
+function redactConfigError(
+  error: CliConfigError | null,
+  env: NodeJS.ProcessEnv,
+): CliConfigError | null {
+  if (!error) return null;
+  return {
+    ...error,
+    message: redactDiagnostic(error.message, env),
+    filePath: error.filePath
+      ? redactDiagnostic(error.filePath, env)
+      : error.filePath,
+    issues: error.issues?.map((issue) => redactDiagnostic(issue, env)),
+  };
+}
+
+function redactConfigWarnings(
+  warnings: ConfigWarning[],
+  env: NodeJS.ProcessEnv,
+): ConfigWarning[] {
+  return warnings.map((warning) => ({
+    filePath: redactDiagnostic(warning.filePath, env),
+    path: warning.path,
+    message: redactDiagnostic(warning.message, env),
+  }));
+}
+
+function nodeVersionTuple(version: string): [number, number, number] | null {
+  const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(version.trim());
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)];
+}
+
+function compareVersions(
+  current: [number, number, number],
+  required: [number, number, number],
+): number {
+  for (let i = 0; i < current.length; i += 1) {
+    const diff = current[i]! - required[i]!;
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+function satisfiesNodeEngine(
+  version: string,
+  requirement: string | null,
+): boolean | null {
+  if (!requirement) return null;
+  const current = nodeVersionTuple(version);
+  const required = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(
+    requirement.trim(),
+  );
+  if (!current || !required) return null;
+  return (
+    compareVersions(current, [
+      Number(required[1]),
+      Number(required[2] ?? 0),
+      Number(required[3] ?? 0),
+    ]) >= 0
+  );
+}
+
+async function findNearestPackageJson(cwd: string): Promise<string | null> {
+  let current = cwd;
+  for (;;) {
+    const candidate = join(current, "package.json");
+    try {
+      await access(candidate, constants.F_OK);
+      return candidate;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return null;
+      current = parent;
+    }
+  }
+}
+
+async function readNodeDiagnostic(cwd: string): Promise<NodeDiagnostic> {
+  const engineSource = await findNearestPackageJson(cwd);
+  let engineRequirement: string | null = null;
+  if (engineSource) {
+    try {
+      const pkg = JSON.parse(await readFile(engineSource, "utf8")) as {
+        engines?: { node?: unknown };
+      };
+      if (typeof pkg.engines?.node === "string") {
+        engineRequirement = pkg.engines.node;
+      }
+    } catch {
+      engineRequirement = null;
+    }
+  }
+
+  return {
+    version: process.version,
+    engineRequirement,
+    engineSource,
+    satisfiesEngine: satisfiesNodeEngine(process.version, engineRequirement),
+  };
+}
+
+async function executablePath(
+  executable: string,
+  env: NodeJS.ProcessEnv,
+): Promise<string | null> {
+  const pathValue = env.PATH ?? process.env.PATH ?? "";
+  const suffixes =
+    process.platform === "win32"
+      ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM")
+          .split(";")
+          .filter((suffix) => suffix.length > 0)
+      : [""];
+
+  for (const dir of pathValue.split(delimiter)) {
+    if (dir.trim() === "") continue;
+    for (const suffix of suffixes) {
+      const candidate = join(dir, `${executable}${suffix}`);
+      try {
+        await access(candidate, constants.X_OK);
+        return candidate;
+      } catch {
+        // Keep searching PATH.
+      }
+    }
+  }
+  return null;
+}
+
+async function detectCommandAvailability(
+  command: string,
+  executable: string,
+  env: NodeJS.ProcessEnv,
+): Promise<CommandAvailability> {
+  const path = await executablePath(executable, env);
+  return {
+    command,
+    executable,
+    available: path !== null,
+    path: path ? redactDiagnostic(path, env) : null,
+  };
+}
+
+// process.argv[1] is the running CLI script. When the CLI is launched from its
+// built bundle the path ends in packages/cli/dist/index.js; doctor reports it
+// as an `mcp serve` fallback when the `offrouter` binary is not on PATH.
+// Match on a normalized path suffix (not a raw substring with manual separator
+// rewriting) so platform separator differences do not break the check.
+const DIST_ENTRY_SUFFIX = join("packages", "cli", "dist", "index.js");
+
+function currentCliEntryPoint(): string | null {
+  const entryPoint = process.argv[1];
+  if (!entryPoint) return null;
+  if (!normalize(entryPoint).endsWith(DIST_ENTRY_SUFFIX)) {
+    return null;
+  }
+  return entryPoint;
+}
+
+async function detectMcpServeAvailability(
+  env: NodeJS.ProcessEnv,
+): Promise<CommandAvailability> {
+  const installed = await detectCommandAvailability(
+    "offrouter mcp serve",
+    "offrouter",
+    env,
+  );
+  if (installed.available) return installed;
+
+  const entryPoint = currentCliEntryPoint();
+  if (!entryPoint) return installed;
+  try {
+    await access(entryPoint, constants.F_OK);
+  } catch {
+    return installed;
+  }
+
+  const executable = redactDiagnostic(process.execPath, env);
+  const path = redactDiagnostic(entryPoint, env);
+  return {
+    command: `${executable} ${path} mcp serve`,
+    executable,
+    available: true,
+    path,
+  };
+}
+
+// Profile ids follow the convention "<harness>-<scope>" (for example
+// "claude-personal" or "codex-personal"), so a profile maps to its HarnessKind
+// by matching the known harness prefixes. Kept as an explicit, typed table
+// rather than ad hoc string checks so the mapping is auditable and adding a
+// harness is a single entry. None of the prefixes is a prefix of another, so
+// the lookup order does not change the result.
+const HARNESS_PROFILE_PREFIXES: ReadonlyArray<{
+  prefix: string;
+  kind: HarnessKind;
+}> = [
+  { prefix: "claude", kind: "claude" },
+  { prefix: "codex", kind: "codex" },
+  { prefix: "gemini", kind: "gemini" },
+  { prefix: "grok", kind: "grok" },
+  { prefix: "cursor", kind: "cursor" },
+  { prefix: "pi", kind: "pi" },
+];
+
+function harnessKindFromProfile(profile: string): HarnessKind {
+  const match = HARNESS_PROFILE_PREFIXES.find((entry) =>
+    profile.startsWith(entry.prefix),
+  );
+  return match?.kind ?? "other";
+}
+
+function buildDoctorRouteRequest(profile: string, cwd: string): RouteRequest {
+  return {
+    protocolVersion: "offrouter.route.v1",
+    requestId: `cli_doctor_${profile}`,
+    harness: {
+      kind: harnessKindFromProfile(profile),
+      profile,
+    },
+    task: {
+      promptPreview: "offrouter doctor profile policy check",
+      promptDigest: "doctor",
+      kind: "explain",
+      risk: "low",
+    },
+    workspace: {
+      cwd,
+      trusted: true,
+    },
+    constraints: {
+      subscriptionFirst: true,
+      allowApiKeyFallback: false,
+    },
+  };
+}
+
+function formatBoolean(value: boolean | null): string {
+  if (value === null) return "unknown";
+  return value ? "ok" : "not satisfied";
+}
+
+export function registerDoctorCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  program
+    .command("doctor")
+    .description("Inspect OffRouter readiness and configuration health")
+    .option("--json", "Emit JSON", false)
+    .option(
+      "--profile <profile>",
+      "Harness profile id to check against OffRouter policy",
+      "claude-personal",
+    )
+    .action(async (opts: { json?: boolean; profile: string }) => {
+      const { env, cwd, stdout } = ctx();
+      const [detection, rawNode, claudeCli, mcpServe] = await Promise.all([
+        detectEnvironment({ env, cwd }),
+        readNodeDiagnostic(cwd),
+        detectCommandAvailability("claude", "claude", env),
+        detectMcpServeAvailability(env),
+      ]);
+      const node: NodeDiagnostic = {
+        ...rawNode,
+        engineSource: rawNode.engineSource
+          ? redactDiagnostic(rawNode.engineSource, env)
+          : null,
+      };
+      const harnessProfiles = detection.harnessProfiles.map((profile) => ({
+        ...profile,
+        pathChecked: profile.pathChecked
+          ? redactDiagnostic(profile.pathChecked, env)
+          : profile.pathChecked,
+      }));
+      let configSummary: {
+        homeDir: string;
+        sources: string[];
+        allowlistedProfiles: string[];
+        providersConfigured: string[];
+        valid: boolean;
+        warnings: number;
+        warningDetails: ConfigWarning[];
+      };
+      let configError: CliConfigError | null = null;
+      let policyConfig: PolicyConfig;
+      try {
+        const config = await loadConfig({ env, workspaceDir: cwd });
+        policyConfig = config.policy;
+        configSummary = {
+          homeDir: redactDiagnostic(config.homeDir, env),
+          sources: config.sources.map((source) =>
+            redactDiagnostic(source, env),
+          ),
+          allowlistedProfiles: config.policy.allowlistedProfiles,
+          providersConfigured: Object.keys(config.providers).sort(),
+          valid: true,
+          warnings: config.warnings.length,
+          warningDetails: redactConfigWarnings(config.warnings, env),
+        };
+      } catch (err) {
+        configError = formatConfigError(err);
+        const safeConfigError = redactConfigError(configError, env);
+        configError = safeConfigError;
+        policyConfig = {
+          allowlistedProfiles: [],
+          deniedProfilePatterns: ["*-work"],
+          allowThirdPartySubscriptionAdapters: false,
+          deniedProviders: [],
+        };
+        configSummary = {
+          homeDir: env.OFFROUTER_HOME
+            ? redactDiagnostic(env.OFFROUTER_HOME, env)
+            : "(default)",
+          sources: [],
+          allowlistedProfiles: [],
+          providersConfigured: [],
+          valid: false,
+          warnings: 0,
+          warningDetails: [],
+        };
+      }
+
+      const request = buildDoctorRouteRequest(opts.profile, cwd);
+      const policy = evaluatePolicy(request, [], policyConfig);
+      const routeDecision = routeRequest(request, [], policyConfig);
+      const profileDenials = policy.denials
+        .filter((denial) => denial.target === "profile")
+        .map((denial) => ({
+          ...denial,
+          id: redactDiagnostic(denial.id, env),
+          message: redactDiagnostic(denial.message, env),
+        }));
+      const profileAllowed = profileDenials.length === 0;
+      const profile = {
+        profile: opts.profile,
+        allowed: profileAllowed,
+        status: profileAllowed ? "allowed" : "denied",
+        denials: profileDenials,
+        routeReadiness: {
+          blocked: routeDecision.blocked === true,
+          needsConfiguration: routeDecision.needsConfiguration === true,
+          reason: routeDecision.reason,
+          explanation: redactDiagnostic(routeDecision.explanation, env),
+        },
+      };
+
+      const localRuntime = {
+        ...detection.localRuntime,
+        ready: detection.localRuntime.health !== "unconfigured",
+      };
+      const providerAuth = {
+        ready:
+          detection.authTiers.subscription ||
+          detection.authTiers.local ||
+          detection.authTiers["api-key"],
+        authTiers: detection.authTiers,
+        envPresent: detection.apiKeyReadiness.envPresent,
+        configuredProviders: configSummary.providersConfigured,
+        apiKeyReady: detection.apiKeyReadiness.anyReady,
+      };
+
+      const payload = {
+        honesty: V1_HONESTY_LINE,
+        node,
+        harnessProfiles,
+        authTiers: detection.authTiers,
+        subscription: detection.subscription,
+        apiKeyReadiness: detection.apiKeyReadiness,
+        providerAuth,
+        localRuntime,
+        profile,
+        claudeCli,
+        mcpServe,
+        limits: detection.limits,
+        lastProviderError: detection.lastProviderError,
+        config: configSummary,
+        configError,
+      };
+
+      if (opts.json) {
+        writeJson(stdout, payload);
+        return;
+      }
+
+      writeText(stdout, V1_HONESTY_LINE);
+      writeText(
+        stdout,
+        `Node: ${node.version} (requires ${node.engineRequirement ?? "unknown"}: ${formatBoolean(node.satisfiesEngine)})`,
+      );
+      writeText(
+        stdout,
+        `Config: ${configSummary.valid ? "valid" : "invalid"}; warnings: ${configSummary.warnings}; sources: ${configSummary.sources.length}`,
+      );
+      for (const warning of configSummary.warningDetails) {
+        writeText(
+          stdout,
+          `- Config warning [${warning.path}]: ${warning.message}`,
+        );
+      }
+      writeText(
+        stdout,
+        `Selected profile: ${profile.profile} - ${profile.status}`,
+      );
+      if (profile.denials.length > 0) {
+        for (const denial of profile.denials) {
+          writeText(stdout, `- [${denial.code}] ${denial.message}`);
+        }
+      } else {
+        writeText(
+          stdout,
+          `Profile readiness: ${profile.routeReadiness.reason}; needs configuration: ${profile.routeReadiness.needsConfiguration}`,
+        );
+      }
+      writeText(
+        stdout,
+        `Claude CLI: ${claudeCli.available ? "available" : "missing"}${claudeCli.path ? ` at ${claudeCli.path}` : ""}`,
+      );
+      writeText(
+        stdout,
+        `MCP serve: ${mcpServe.available ? "available" : "missing"} via ${mcpServe.command}${mcpServe.path ? ` at ${mcpServe.path}` : ""}`,
+      );
+      writeText(
+        stdout,
+        `Provider auth: ready=${providerAuth.ready}; API keys present: ${detection.apiKeyReadiness.envPresent.join(", ") || "(none)"}; configured providers: ${configSummary.providersConfigured.join(", ") || "(none)"}`,
+      );
+      writeText(
+        stdout,
+        `Subscription: ${detection.subscription.status}; API keys present: ${detection.apiKeyReadiness.anyReady}; local runtime: ${localRuntime.health}`,
+      );
+      writeText(
+        stdout,
+        `Local runtime: ${localRuntime.health}; ready=${localRuntime.ready}; ollama host configured=${localRuntime.ollamaHostConfigured}; local binary present=${localRuntime.localBinaryPresent}`,
+      );
+      writeText(
+        stdout,
+        `Allowlisted profiles: ${configSummary.allowlistedProfiles.join(", ") || "(none)"}`,
+      );
+      writeText(
+        stdout,
+        `Configured providers: ${configSummary.providersConfigured.join(", ") || "(none)"}`,
+      );
+      writeText(
+        stdout,
+        `Limits: ${detection.limits.status} - ${detection.limits.detail}`,
+      );
+      writeText(
+        stdout,
+        `Last provider error: ${detection.lastProviderError ?? "(none)"}`,
+      );
+      if (configError) {
+        writeText(stdout, `Config error: ${configError.message}`);
+      }
+    });
+}
+
+// Re-export for status registration whenever status lives with doctor-like output.
+export type { IoStreams };

package/src/commands/hooks.ts

@@ -0,0 +1,125 @@
+import type { Command } from "commander";
+import { loadConfig } from "offrouter-core";
+import { runUserPromptSubmitHook } from "offrouter-adapter-claude";
+import type { CommandContext } from "./init.js";
+
+const HOOK_EVENT = "UserPromptSubmit" as const;
+
+function noActiveProfileOutput(): string {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: HOOK_EVENT,
+      additionalContext:
+        "OffRouter has no active profile. Set --profile or OFFROUTER_PROFILE to enable routing or policy blocking. Claude Code's primary model is unchanged in V1; OffRouter routes delegated work.",
+    },
+  });
+}
+
+function isWorkspaceTrusted(
+  explicit: boolean | undefined,
+  env: NodeJS.ProcessEnv,
+): boolean {
+  if (explicit === true) {
+    return true;
+  }
+  return env.OFFROUTER_WORKSPACE_TRUSTED === "true";
+}
+
+function resolveProfile(
+  optionProfile: string | undefined,
+  env: NodeJS.ProcessEnv,
+): string | undefined {
+  const fromOpt = optionProfile?.trim();
+  if (fromOpt) {
+    return fromOpt;
+  }
+  const fromEnv = env.OFFROUTER_PROFILE?.trim();
+  return fromEnv || undefined;
+}
+
+export function registerHooksCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  const hooks = program
+    .command("hooks")
+    .description("Harness hook bridges (stdin JSON in, JSON out)");
+
+  const claude = hooks
+    .command("claude")
+    .description("Claude Code hook bridges");
+
+  claude
+    .command("user-prompt-submit")
+    .description(
+      "Claude UserPromptSubmit bridge: read stdin, emit hook JSON only",
+    )
+    .option(
+      "--profile <profile>",
+      "Active harness profile (or set OFFROUTER_PROFILE)",
+    )
+    .option(
+      "--trusted-workspace",
+      "Mark workspace trusted for project config loading",
+      false,
+    )
+    .action(
+      async (opts: { profile?: string; trustedWorkspace?: boolean }) => {
+        const { env, cwd, stdout, stderr, readStdin } = ctx();
+        const profile = resolveProfile(opts.profile, env);
+
+        // No profile: safe context only; do not route or block.
+        if (!profile) {
+          stdout.write(noActiveProfileOutput());
+          return;
+        }
+
+        const trustedWorkspace = isWorkspaceTrusted(
+          opts.trustedWorkspace,
+          env,
+        );
+        const stdin = await readStdin();
+
+        try {
+          const config = await loadConfig({
+            env,
+            workspaceDir: cwd,
+            workspaceTrusted: trustedWorkspace,
+          });
+          const profileOverlay = config.profiles[profile];
+          const result = await runUserPromptSubmitHook(stdin, {
+            profile,
+            policy: config.policy,
+            // Live catalog discovery lands later; empty candidates still allow
+            // profile denials and configuration-needed context.
+            candidates: [],
+            trustedWorkspace,
+            routeConstraints: {
+              subscriptionFirst:
+                profileOverlay?.subscriptionFirst ??
+                config.policyDefaults.subscriptionFirst,
+              allowApiKeyFallback:
+                profileOverlay?.allowApiKeyFallback ??
+                config.policyDefaults.allowApiKeyFallback,
+            },
+          });
+          // Exact hook JSON only; no pretty-print banners or extra lines.
+          stdout.write(result.stdout);
+          if (result.stderr) {
+            stderr.write(result.stderr);
+          }
+        } catch (err) {
+          const message =
+            err instanceof Error ? err.message : "OffRouter hook failed";
+          stdout.write(
+            JSON.stringify({
+              hookSpecificOutput: {
+                hookEventName: HOOK_EVENT,
+                additionalContext: `OffRouter could not load config for hook processing: ${message}. Claude Code's primary model is unchanged in V1; OffRouter routes delegated work.`,
+              },
+            }),
+          );
+        }
+      },
+    );
+}

package/src/commands/init.ts

@@ -0,0 +1,59 @@
+import type { Command } from "commander";
+import { detectEnvironment, V1_HONESTY_LINE } from "./detection.js";
+import { writeJson, writeText, type IoStreams } from "./output.js";
+
+export interface CommandContext {
+  env: NodeJS.ProcessEnv;
+  cwd: string;
+  stdout: IoStreams;
+  stderr: IoStreams;
+  /** Read full stdin (injected string in tests, process.stdin otherwise). */
+  readStdin: () => Promise<string>;
+}
+
+export function registerInitCommand(
+  program: Command,
+  ctx: () => CommandContext,
+): void {
+  program
+    .command("init")
+    .description("Detect environment and scaffold OffRouter config")
+    .option("--dry-run", "Report detection without writing config", false)
+    .option("--json", "Emit JSON", false)
+    .action(async (opts: { dryRun?: boolean; json?: boolean }) => {
+      const { env, cwd, stdout } = ctx();
+      const detection = await detectEnvironment({ env, cwd });
+      const dryRun = Boolean(opts.dryRun);
+      const wroteConfig = false;
+
+      if (opts.json) {
+        writeJson(stdout, {
+          dryRun,
+          wroteConfig,
+          honesty: V1_HONESTY_LINE,
+          detection: {
+            harnessProfiles: detection.harnessProfiles,
+            authTiers: detection.authTiers,
+            subscription: detection.subscription,
+            apiKeyReadiness: detection.apiKeyReadiness,
+            localRuntime: detection.localRuntime,
+            limits: detection.limits,
+            lastProviderError: detection.lastProviderError,
+          },
+        });
+        return;
+      }
+
+      writeText(stdout, V1_HONESTY_LINE);
+      writeText(
+        stdout,
+        dryRun
+          ? "Dry run: no config files written."
+          : "Init writing is reserved for a later milestone; use --dry-run for detection.",
+      );
+      writeText(
+        stdout,
+        `Subscription: ${detection.subscription.status}; API-key ready: ${detection.apiKeyReadiness.anyReady}; local: ${detection.localRuntime.health}`,
+      );
+    });
+}