offrouter-adapter-grok 0.2.0 → 0.2.2

package/src/install.ts

@@ -1,473 +0,0 @@
-/**
- * Profile-scoped installer for Grok personal profiles.
- *
- * Mirrors the Codex adapter's TOML model but writes ONE MCP server entry into
- * the Grok profile's TOML config file (profile-scoped) at
- * <profileDir>/config.toml and records rollback metadata inside the target
- * profile (.offrouter/grok-install-state.json).
- *
- * Grok Build config.toml is parsed/stringified with smol-toml (same version as
- * core/codex), never ad hoc string surgery. MCP servers live under the
- * top-level `mcp_servers` table.
- */
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import { constants } from "node:fs";
-import { createHash } from "node:crypto";
-import { dirname, join } from "node:path";
-import { homedir as osHomedir } from "node:os";
-import {
-  ROUTE_PROTOCOL_VERSION,
-  routeRequest,
-  type OffRouterConfig,
-  type PolicyDenialCode,
-  type RouteRequest,
-} from "offrouter-core";
-import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
-import { z } from "zod";
-import {
-  isGrokHarnessProfile,
-  isSafeProfileId,
-  isWorkLikeProfile,
-  resolveGrokProfileDir,
-} from "./profile.js";
-
-export const GROK_INSTALL_STATE_REL =
-  ".offrouter/grok-install-state.json" as const;
-
-export const GROK_CONFIG_REL = "config.toml" as const;
-
-/** Table name and command/args for the OffRouter MCP server entry. */
-const OFFROUTER_MCP_SERVER_NAME = "offrouter";
-const OFFROUTER_MCP_COMMAND = "offrouter";
-const OFFROUTER_MCP_ARGS: readonly string[] = ["mcp", "serve"];
-
-export const GrokInstallStateSchema = z.object({
-  version: z.literal(1),
-  profile: z.string().min(1),
-  harness: z.literal("grok"),
-  installedAt: z.string().min(1),
-  configRelative: z.literal(GROK_CONFIG_REL),
-  files: z.record(
-    z.string().min(1),
-    z.object({
-      previous: z.string().nullable(),
-      hash: z.string().optional(),
-    }),
-  ),
-});
-
-export type GrokInstallState = z.infer<typeof GrokInstallStateSchema>;
-
-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 GrokInstallOptions {
-  profile: string;
-  config: OffRouterConfig;
-  env?: NodeJS.ProcessEnv;
-  homedir?: () => string;
-  dryRun?: boolean;
-}
-
-export interface GrokInstallResult {
-  ok: boolean;
-  dryRun: boolean;
-  profile: string;
-  profileDir: string;
-  changes: InstallFileChange[];
-  message: string;
-  errorCode?: PolicyDenialCode | "install_error";
-  statePath?: string;
-}
-
-async function pathExists(path: string): Promise<boolean> {
-  try {
-    await access(path, constants.F_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function sha256(content: string): string {
-  return createHash("sha256").update(content).digest("hex");
-}
-
-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}`;
-  }
-}
-
-/**
- * Produce the desired config.toml content for the OffRouter MCP entry using a
- * TOML parser (smol-toml) instead of ad hoc string surgery.
- *
- * - Missing/empty file => fresh config containing only the MCP entry.
- * - Existing file already has [mcp_servers.offrouter] with matching
- *   command/args => return the original bytes unchanged (idempotent).
- * - Existing file has a conflicting offrouter entry (or none) => set/replace
- *   the entry and stringify, preserving all other unrelated keys.
- *
- * smol-toml does not preserve comments on round-trip; that is accepted as
- * best-effort per the project rule against ad hoc config parsing.
- */
-export function patchConfigForMcp(existing: string | null): string {
-  if (existing === null || existing.trim() === "") {
-    return stringifyToml(freshOffrouterConfig());
-  }
-
-  const root: Record<string, unknown> = parseToml(existing);
-  const servers = isTomlTable(root.mcp_servers) ? root.mcp_servers : undefined;
-
-  if (
-    servers !== undefined &&
-    isOffrouterMcpEntry(servers[OFFROUTER_MCP_SERVER_NAME])
-  ) {
-    return existing;
-  }
-
-  const nextRoot: Record<string, unknown> = {
-    ...root,
-    mcp_servers: {
-      ...(servers ?? {}),
-      [OFFROUTER_MCP_SERVER_NAME]: offrouterMcpEntry(),
-    },
-  };
-  return stringifyToml(nextRoot);
-}
-
-function isTomlTable(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/**
- * True when an existing [mcp_servers.offrouter] entry already matches the
- * OffRouter command/args. Detects a correct prior install by value (not by
- * string equality) so a conflicting entry is overwritten.
- */
-function isOffrouterMcpEntry(value: unknown): boolean {
-  if (!isTomlTable(value)) {
-    return false;
-  }
-  if (value.command !== OFFROUTER_MCP_COMMAND) {
-    return false;
-  }
-  const args = value.args;
-  if (!Array.isArray(args) || args.length !== OFFROUTER_MCP_ARGS.length) {
-    return false;
-  }
-  return args.every((item, index) => item === OFFROUTER_MCP_ARGS[index]);
-}
-
-function offrouterMcpEntry(): Record<string, unknown> {
-  return {
-    command: OFFROUTER_MCP_COMMAND,
-    args: [...OFFROUTER_MCP_ARGS],
-  };
-}
-
-function freshOffrouterConfig(): Record<string, unknown> {
-  return {
-    mcp_servers: {
-      [OFFROUTER_MCP_SERVER_NAME]: offrouterMcpEntry(),
-    },
-  };
-}
-
-function tinyPolicyProbeRequest(profile: string): RouteRequest {
-  return {
-    requestId: "install-policy-probe",
-    protocolVersion: ROUTE_PROTOCOL_VERSION,
-    harness: { kind: "grok", 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 };
-}
-
-/**
- * Install the OffRouter Grok MCP entry into a single profile directory.
- */
-export async function installGrokProfile(
-  options: GrokInstallOptions,
-): Promise<GrokInstallResult> {
-  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 = resolveGrokProfileDir(profile, { env, homedir });
-  const statePath = join(profileDir, GROK_INSTALL_STATE_REL);
-  const configPath = join(profileDir, GROK_CONFIG_REL);
-
-  if (!isGrokHarnessProfile(profile)) {
-    return {
-      ok: false,
-      dryRun,
-      profile,
-      profileDir,
-      changes: [],
-      message:
-        "Grok install supports only profile ids named grok or starting with grok-.",
-      errorCode: "install_error",
-    };
-  }
-
-  // Work-like profile ids (e.g. grok-work, grok-work-staging) are never
-  // installable, even when allowlisted. This mirrors the filter used by
-  // listAllowlistedPersonalGrokProfiles 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 grok-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",
-    };
-  }
-
-  // Preserve original previous contents across re-installs (idempotent rollback).
-  let priorState: GrokInstallState | null = null;
-  if (await pathExists(statePath)) {
-    try {
-      const raw = await readFile(statePath, "utf8");
-      priorState = GrokInstallStateSchema.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[] = [];
-
-  // --- config.toml MCP entry ---
-  let current: string | null = null;
-  if (await pathExists(configPath)) {
-    current = await readFile(configPath, "utf8");
-  }
-
-  const priorFile = priorState?.files[GROK_CONFIG_REL];
-  const previous = priorFile !== undefined ? priorFile.previous : current;
-
-  const desired = patchConfigForMcp(current);
-
-  let kind: InstallChangeKind;
-  if (current === null) {
-    kind = "create";
-  } else if (current === desired) {
-    kind = "unchanged";
-  } else {
-    kind = "update";
-  }
-
-  changes.push({
-    path: configPath,
-    relativePath: GROK_CONFIG_REL,
-    kind,
-    summary: changeSummary(kind, GROK_CONFIG_REL),
-  });
-
-  if (!dryRun && kind !== "unchanged") {
-    await mkdir(dirname(configPath), { recursive: true });
-    await writeFile(configPath, desired, "utf8");
-  }
-
-  // --- install state metadata ---
-  const state: GrokInstallState = {
-    version: 1,
-    profile,
-    harness: "grok",
-    installedAt: priorState?.installedAt ?? new Date().toISOString(),
-    configRelative: GROK_CONFIG_REL,
-    files: {
-      [GROK_CONFIG_REL]: {
-        previous,
-        hash: sha256(desired),
-      },
-    },
-  };
-
-  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: GROK_INSTALL_STATE_REL,
-    kind: stateKind,
-    summary: changeSummary(stateKind, GROK_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 Grok MCP entry 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: GrokInstallResult[],
-  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";
-}

package/src/profile.ts

@@ -1,99 +0,0 @@
-/**
- * Grok profile directory resolution and allowlist helpers.
- *
- * Mirrors the Codex adapter's profile isolation model:
- * - env OFFROUTER_GROK_PROFILES_DIR set => <root>/<profile>
- * - profile === "grok" => env GROK_HOME || ~/.grok   (bare global; only
- *   mutable when explicitly allowlisted)
- * - otherwise => ~/.<profile>   (e.g. grok-personal => ~/.grok-personal)
- */
-import { homedir as osHomedir } from "node:os";
-import { join, resolve } from "node:path";
-import type { OffRouterConfig } from "offrouter-core";
-
-export 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);
-}
-
-export interface ResolveGrokProfileDirOptions {
-  env?: NodeJS.ProcessEnv;
-  homedir?: () => string;
-}
-
-function envValue(
-  env: NodeJS.ProcessEnv | undefined,
-  key: string,
-): string | undefined {
-  const v = env?.[key]?.trim();
-  return v || undefined;
-}
-
-/**
- * Resolve the on-disk Grok profile directory for a OffRouter profile id.
- *
- * - When OFFROUTER_GROK_PROFILES_DIR is set: $DIR/<profile>
- * - profile id `grok` -> GROK_HOME (if set) else ~/.grok
- * - otherwise -> ~/.<profile> (e.g. grok-personal -> ~/.grok-personal)
- */
-export function resolveGrokProfileDir(
-  profile: string,
-  options: ResolveGrokProfileDirOptions = {},
-): 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_GROK_PROFILES_DIR");
-  if (profilesRoot) {
-    return resolve(join(profilesRoot, profile));
-  }
-  if (profile === "grok") {
-    const grokHome = envValue(env, "GROK_HOME");
-    return resolve(grokHome ?? join(home, ".grok"));
-  }
-  return resolve(join(home, `.${profile}`));
-}
-
-/**
- * Personal Grok profiles only: id starts with "grok" or is exactly "grok".
- */
-export function isGrokHarnessProfile(profile: string): boolean {
-  return profile === "grok" || profile.startsWith("grok-");
-}
-
-export function isWorkLikeProfile(profile: string): boolean {
-  return profile.endsWith("-work") || profile.includes("-work-");
-}
-
-function matchGlob(pattern: string, value: string): boolean {
-  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
-  const re = new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
-  return re.test(value);
-}
-
-/**
- * Allowlisted personal Grok profiles eligible for install --all-personal.
- * Excludes the bare global `grok` profile (only mutable when explicit) and
- * work-like ids, and applies deniedProfilePatterns glob filters.
- */
-export function listAllowlistedPersonalGrokProfiles(
-  config: OffRouterConfig,
-): string[] {
-  return [...config.policy.allowlistedProfiles]
-    .filter(
-      (id) =>
-        isSafeProfileId(id) &&
-        isGrokHarnessProfile(id) &&
-        id !== "grok" &&
-        !isWorkLikeProfile(id) &&
-        !(config.policy.deniedProfilePatterns ?? []).some((p) =>
-          matchGlob(p, id),
-        ),
-    )
-    .sort((a, b) => a.localeCompare(b));
-}