offrouter-adapter-claude 0.0.0

package/src/install.ts

@@ -0,0 +1,595 @@
+/**
+ * Profile-scoped installer for Claude Code personal profiles.
+ *
+ * Copies the repo-neutral plugins/claude-offrouter package into the selected
+ * profile directory under skills/offrouter, patches hooks to set
+ * OFFROUTER_PROFILE for the selected profile only, and records rollback
+ * metadata inside the target profile (.offrouter/claude-install-state.json).
+ */
+import {
+  access,
+  copyFile,
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { constants } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir as osHomedir } from "node:os";
+import {
+  ROUTE_PROTOCOL_VERSION,
+  routeRequest,
+  type OffRouterConfig,
+  type PolicyDenialCode,
+  type RouteRequest,
+} from "offrouter-core";
+import { z } from "zod";
+
+export const CLAUDE_INSTALL_STATE_REL =
+  ".offrouter/claude-install-state.json" as const;
+
+export const INSTALLED_PLUGIN_REL = "skills/offrouter" as const;
+
+const InstallFileStateSchema = z.object({
+  previous: z.string().nullable(),
+  hash: z.string().optional(),
+});
+
+export const ClaudeInstallStateSchema = z.object({
+  version: z.literal(1),
+  profile: z.string().min(1),
+  harness: z.literal("claude"),
+  installedAt: z.string().min(1),
+  pluginRootRelative: z.string().min(1),
+  files: z.record(z.string().min(1), InstallFileStateSchema),
+});
+
+export type ClaudeInstallState = z.infer<typeof ClaudeInstallStateSchema>;
+
+export type InstallChangeKind = "create" | "update" | "unchanged" | "remove";
+
+export interface InstallFileChange {
+  path: string;
+  relativePath: string;
+  kind: InstallChangeKind;
+  /** Diff-like summary line for human output. */
+  summary: string;
+}
+
+export interface ClaudeInstallOptions {
+  profile: string;
+  config: OffRouterConfig;
+  env?: NodeJS.ProcessEnv;
+  homedir?: () => string;
+  dryRun?: boolean;
+  /** Override source plugin directory (tests). Defaults to repo plugins/claude-offrouter. */
+  pluginSourceDir?: string;
+}
+
+export interface ClaudeInstallResult {
+  ok: boolean;
+  dryRun: boolean;
+  profile: string;
+  profileDir: string;
+  changes: InstallFileChange[];
+  message: string;
+  errorCode?: PolicyDenialCode | "install_error";
+  statePath?: string;
+}
+
+export interface ResolveClaudeProfileDirOptions {
+  env?: NodeJS.ProcessEnv;
+  homedir?: () => string;
+}
+
+const HOOKS_REL = "hooks/hooks.json";
+const SAFE_PROFILE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function isSafeProfileId(profile: string): boolean {
+  return SAFE_PROFILE_ID_RE.test(profile);
+}
+
+function envValue(
+  env: NodeJS.ProcessEnv | undefined,
+  key: string,
+): string | undefined {
+  const v = env?.[key]?.trim();
+  return v || undefined;
+}
+
+/**
+ * Resolve the on-disk Claude profile directory for a OffRouter profile id.
+ *
+ * - When OFFROUTER_CLAUDE_PROFILES_DIR is set: $DIR/<profile>
+ * - profile id `claude` -> ~/.claude (the only path that may touch global Claude)
+ * - otherwise -> ~/.<profile> (e.g. claude-personal -> ~/.claude-personal)
+ */
+export function resolveClaudeProfileDir(
+  profile: string,
+  options: ResolveClaudeProfileDirOptions = {},
+): string {
+  if (!isSafeProfileId(profile)) {
+    throw new Error(
+      `Unsafe profile id "${profile}". Use letters, numbers, dots, underscores, and dashes only.`,
+    );
+  }
+  const env = options.env ?? process.env;
+  const home = (options.homedir ?? osHomedir)();
+  const profilesRoot = envValue(env, "OFFROUTER_CLAUDE_PROFILES_DIR");
+  if (profilesRoot) {
+    return resolve(join(profilesRoot, profile));
+  }
+  if (profile === "claude") {
+    return resolve(join(home, ".claude"));
+  }
+  return resolve(join(home, `.${profile}`));
+}
+
+/**
+ * Personal Claude profiles only: id starts with "claude" or is exactly "claude",
+ * not a work profile by default pattern.
+ */
+export function isClaudeHarnessProfile(profile: string): boolean {
+  return profile === "claude" || profile.startsWith("claude-");
+}
+
+export function isWorkLikeProfile(profile: string): boolean {
+  return profile.endsWith("-work") || profile.includes("-work-");
+}
+
+/**
+ * Allowlisted personal Claude profiles eligible for install --all-personal.
+ */
+export function listAllowlistedPersonalClaudeProfiles(
+  config: OffRouterConfig,
+): string[] {
+  return [...config.policy.allowlistedProfiles]
+    .filter(
+      (id) =>
+        isSafeProfileId(id) &&
+        isClaudeHarnessProfile(id) &&
+        id !== "claude" &&
+        !isWorkLikeProfile(id) &&
+        !(config.policy.deniedProfilePatterns ?? []).some((p) =>
+          matchGlob(p, id),
+        ),
+    )
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function matchGlob(pattern: string, value: string): boolean {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+  return re.test(value);
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function listFilesRecursive(root: string): Promise<string[]> {
+  const out: string[] = [];
+  async function walk(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile()) {
+        out.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return out.sort();
+}
+
+function toPosixRel(from: string, to: string): string {
+  return relative(from, to).split(sep).join("/");
+}
+
+function sha256(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+/**
+ * Default plugin source: monorepo plugins/claude-offrouter relative to this package.
+ */
+export function defaultPluginSourceDir(): string {
+  // packages/adapter-claude/src -> ../../../plugins/claude-offrouter
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, "../../../plugins/claude-offrouter");
+}
+
+function tinyPolicyProbeRequest(profile: string): RouteRequest {
+  return {
+    requestId: "install-policy-probe",
+    protocolVersion: ROUTE_PROTOCOL_VERSION,
+    harness: { kind: "claude", profile },
+    task: {
+      promptPreview: "install policy probe",
+      promptDigest: "sha256:install-policy-probe",
+      kind: "other",
+      risk: "low",
+    },
+    workspace: { cwd: "/tmp/offrouter-install-probe", trusted: true },
+    constraints: {
+      subscriptionFirst: true,
+      allowApiKeyFallback: false,
+    },
+  };
+}
+
+/**
+ * Use routeRequest with empty candidates so work/unallowlisted profile denials
+ * reuse the same core policy codes users see from route explain / hooks.
+ */
+export function evaluateInstallProfilePolicy(
+  profile: string,
+  config: OffRouterConfig,
+): { allowed: boolean; errorCode?: PolicyDenialCode; message?: string } {
+  const decision = routeRequest(
+    tinyPolicyProbeRequest(profile),
+    [],
+    config.policy,
+  );
+  const denials = decision.policyDenials ?? [];
+  const hard = denials.find(
+    (d) =>
+      d.code === "work_profile_denied" ||
+      d.code === "profile_not_allowlisted" ||
+      d.code === "privacy_label_denied",
+  );
+  if (hard) {
+    return {
+      allowed: false,
+      errorCode: hard.code,
+      message: hard.message,
+    };
+  }
+  // Empty candidates also sets needsConfiguration + may include
+  // profile_not_allowlisted even for personal unallowlisted. When allowlisted,
+  // only needsConfiguration remains; that is fine for install.
+  const profileDenial = denials.find((d) => d.target === "profile");
+  if (profileDenial) {
+    return {
+      allowed: false,
+      errorCode: profileDenial.code,
+      message: profileDenial.message,
+    };
+  }
+  if (!config.policy.allowlistedProfiles.includes(profile)) {
+    return {
+      allowed: false,
+      errorCode: "profile_not_allowlisted",
+      message: `Profile ${profile} is not allowlisted. Add it explicitly before installing or routing.`,
+    };
+  }
+  return { allowed: true };
+}
+
+function patchHooksCommand(sourceJson: string, profile: string): string {
+  const parsed = JSON.parse(sourceJson) as {
+    description?: string;
+    hooks?: {
+      UserPromptSubmit?: Array<{
+        hooks?: Array<{
+          type?: string;
+          command?: string;
+          timeout?: number;
+        }>;
+      }>;
+    };
+  };
+
+  const entries = parsed.hooks?.UserPromptSubmit ?? [];
+  for (const entry of entries) {
+    for (const hook of entry.hooks ?? []) {
+      if (hook.type === "command" && typeof hook.command === "string") {
+        // Ensure profile is set for this install; do not inject workspace trust.
+        const base = hook.command
+          .replace(/\bOFFROUTER_PROFILE=\S+\s*/g, "")
+          .replace(/\bOFFROUTER_WORKSPACE_TRUSTED=\S+\s*/g, "")
+          .trim();
+        // Prefer env assignment before the offrouter binary for shell hooks.
+        if (!base.includes("offrouter hooks claude user-prompt-submit")) {
+          hook.command = `OFFROUTER_PROFILE=${profile} offrouter hooks claude user-prompt-submit`;
+        } else {
+          hook.command = `OFFROUTER_PROFILE=${profile} ${base}`;
+        }
+      }
+    }
+  }
+
+  return `${JSON.stringify(parsed, null, 2)}\n`;
+}
+
+async function desiredPluginContents(
+  pluginSourceDir: string,
+  profile: string,
+): Promise<Map<string, string>> {
+  const files = await listFilesRecursive(pluginSourceDir);
+  const map = new Map<string, string>();
+  for (const full of files) {
+    const rel = toPosixRel(pluginSourceDir, full);
+    let content = await readFile(full, "utf8");
+    if (rel === HOOKS_REL) {
+      content = patchHooksCommand(content, profile);
+    }
+    map.set(rel, content);
+  }
+  return map;
+}
+
+function changeSummary(kind: InstallChangeKind, relativePath: string): string {
+  switch (kind) {
+    case "create":
+      return `+ ${relativePath}`;
+    case "update":
+      return `~ ${relativePath}`;
+    case "unchanged":
+      return `= ${relativePath}`;
+    case "remove":
+      return `- ${relativePath}`;
+    default:
+      return `? ${relativePath}`;
+  }
+}
+
+/**
+ * Install the OffRouter Claude plugin into a single profile directory.
+ */
+export async function installClaudeProfile(
+  options: ClaudeInstallOptions,
+): Promise<ClaudeInstallResult> {
+  const {
+    profile,
+    config,
+    dryRun = false,
+    env = process.env,
+    homedir = osHomedir,
+  } = options;
+  if (!isSafeProfileId(profile)) {
+    return {
+      ok: false,
+      dryRun,
+      profile,
+      profileDir: "",
+      changes: [],
+      message:
+        "Unsafe profile id. Use letters, numbers, dots, underscores, and dashes only.",
+      errorCode: "install_error",
+    };
+  }
+  const profileDir = resolveClaudeProfileDir(profile, { env, homedir });
+  const statePath = join(profileDir, CLAUDE_INSTALL_STATE_REL);
+  const pluginTarget = join(profileDir, INSTALLED_PLUGIN_REL);
+
+  if (!isClaudeHarnessProfile(profile)) {
+    return {
+      ok: false,
+      dryRun,
+      profile,
+      profileDir,
+      changes: [],
+      message:
+        "Claude install supports only profile ids named claude or starting with claude-.",
+      errorCode: "install_error",
+    };
+  }
+
+  // Work-like profile ids (e.g. claude-work, claude-work-staging) are never
+  // installable, even when allowlisted. This mirrors the filter used by
+  // listAllowlistedPersonalClaudeProfiles so explicit and --all-personal
+  // installs apply the same personal-only boundary.
+  if (isWorkLikeProfile(profile)) {
+    return {
+      ok: false,
+      dryRun,
+      profile,
+      profileDir,
+      changes: [],
+      message: `Profile ${profile} looks like a work profile and is never installable, even if allowlisted. Use a personal profile such as claude-personal.`,
+      errorCode: "work_profile_denied",
+    };
+  }
+
+  const policy = evaluateInstallProfilePolicy(profile, config);
+  if (!policy.allowed) {
+    return {
+      ok: false,
+      dryRun,
+      profile,
+      profileDir,
+      changes: [],
+      message: policy.message ?? `Profile ${profile} is not installable.`,
+      errorCode: policy.errorCode ?? "install_error",
+    };
+  }
+
+  const pluginSourceDir = options.pluginSourceDir ?? defaultPluginSourceDir();
+  if (!(await isDirectory(pluginSourceDir))) {
+    return {
+      ok: false,
+      dryRun,
+      profile,
+      profileDir,
+      changes: [],
+      message: `Plugin source not found: ${pluginSourceDir}`,
+      errorCode: "install_error",
+    };
+  }
+
+  const desired = await desiredPluginContents(pluginSourceDir, profile);
+
+  // Preserve original previous contents across re-installs (idempotent rollback).
+  let priorState: ClaudeInstallState | null = null;
+  if (await pathExists(statePath)) {
+    try {
+      const raw = await readFile(statePath, "utf8");
+      priorState = ClaudeInstallStateSchema.parse(JSON.parse(raw));
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false,
+        dryRun,
+        profile,
+        profileDir,
+        changes: [],
+        message: `Invalid install state at ${statePath}: ${detail}`,
+        errorCode: "install_error",
+      };
+    }
+  }
+
+  const changes: InstallFileChange[] = [];
+  const nextFiles: ClaudeInstallState["files"] = {};
+
+  for (const [rel, content] of desired) {
+    const abs = join(pluginTarget, rel);
+    const relativePath = `${INSTALLED_PLUGIN_REL}/${rel}`;
+    let previous: string | null = null;
+    let current: string | null = null;
+    if (await pathExists(abs)) {
+      current = await readFile(abs, "utf8");
+    }
+
+    if (priorState?.files[relativePath]) {
+      previous = priorState.files[relativePath]!.previous;
+    } else {
+      previous = current;
+    }
+
+    let kind: InstallChangeKind;
+    if (current === null) {
+      kind = "create";
+    } else if (current === content) {
+      kind = "unchanged";
+    } else {
+      kind = "update";
+    }
+
+    changes.push({
+      path: abs,
+      relativePath,
+      kind,
+      summary: changeSummary(kind, relativePath),
+    });
+    nextFiles[relativePath] = {
+      previous,
+      hash: sha256(content),
+    };
+
+    if (!dryRun && kind !== "unchanged") {
+      await mkdir(dirname(abs), { recursive: true });
+      await writeFile(abs, content, "utf8");
+    }
+  }
+
+  // Always plan state metadata write
+  const state: ClaudeInstallState = {
+    version: 1,
+    profile,
+    harness: "claude",
+    installedAt: priorState?.installedAt ?? new Date().toISOString(),
+    pluginRootRelative: INSTALLED_PLUGIN_REL,
+    files: nextFiles,
+  };
+
+  const stateJson = `${JSON.stringify(state, null, 2)}\n`;
+  let stateKind: InstallChangeKind = "create";
+  if (await pathExists(statePath)) {
+    const existing = await readFile(statePath, "utf8");
+    stateKind = existing === stateJson ? "unchanged" : "update";
+  }
+  changes.push({
+    path: statePath,
+    relativePath: CLAUDE_INSTALL_STATE_REL,
+    kind: stateKind,
+    summary: changeSummary(stateKind, CLAUDE_INSTALL_STATE_REL),
+  });
+
+  if (!dryRun && stateKind !== "unchanged") {
+    await mkdir(dirname(statePath), { recursive: true });
+    await writeFile(statePath, stateJson, "utf8");
+  }
+
+  const wrote = changes.filter(
+    (c) => c.kind === "create" || c.kind === "update",
+  );
+  const message = dryRun
+    ? `Dry run: would apply ${wrote.length} file change(s) for profile ${profile}.`
+    : `Installed OffRouter Claude plugin for profile ${profile} (${wrote.length} file change(s)).`;
+
+  return {
+    ok: true,
+    dryRun,
+    profile,
+    profileDir,
+    changes,
+    message,
+    statePath,
+  };
+}
+
+/**
+ * Human-readable diff-like text for an install/uninstall result matrix.
+ */
+export function formatInstallDiffText(
+  results: ClaudeInstallResult[],
+  headline?: string,
+): string {
+  const lines: string[] = [];
+  if (headline) {
+    lines.push(headline);
+  }
+  for (const result of results) {
+    lines.push(``);
+    lines.push(
+      `## ${result.profile} (${result.ok ? (result.dryRun ? "dry-run" : "applied") : "error"})`,
+    );
+    lines.push(`profileDir: ${result.profileDir}`);
+    if (!result.ok) {
+      lines.push(`error: ${result.message}`);
+      continue;
+    }
+    for (const change of result.changes) {
+      if (change.kind === "unchanged") continue;
+      lines.push(change.summary);
+    }
+    const unchanged = result.changes.filter(
+      (c) => c.kind === "unchanged",
+    ).length;
+    if (unchanged > 0) {
+      lines.push(`= ${unchanged} unchanged`);
+    }
+    lines.push(result.message);
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+/** Copy helper retained for future link-mode installs. */
+export async function copyPluginFile(
+  source: string,
+  dest: string,
+): Promise<void> {
+  await mkdir(dirname(dest), { recursive: true });
+  await copyFile(source, dest);
+}