@semanticist14/clco 0.1.0

package/src/browsermcp.ts

@@ -0,0 +1,430 @@
+// Browser control for clco sessions, via Playwright MCP.
+//
+// Claude Code's own Chrome integration (--chrome) is gated on the session's
+// OAuth scope and is therefore always off here: clco authenticates with
+// ANTHROPIC_AUTH_TOKEN against its own adapter, which Claude Code treats as an
+// env-var session limited to user:inference. An MCP server has no such gate,
+// so browser control has to come from one.
+//
+// Playwright MCP in --extension mode attaches to a tab already open in the
+// user's own browser, with their logins and cookies intact, rather than the
+// fresh profile a headless run would get. Other projects do the same thing,
+// but this is the one with ~4.6M weekly downloads and active releases, so
+// clco supports exactly it rather than maintaining a catalogue.
+
+import { readdir } from "node:fs/promises"
+import { copilotFetch } from "./api"
+import {
+  caBundle,
+  caChildPath,
+  caPaths,
+  isCertValidityError,
+  isTlsTrustError,
+} from "./tls"
+import { homedir, platform } from "node:os"
+import { join } from "node:path"
+
+export const EXTENSION_ID = "mmlmfjhmonkocbjadbfplnigmagldckm"
+// The name the Web Store actually shows. It was "Playwright MCP Bridge" here,
+// which is how the project describes the extension in its docs but not what
+// the listing is called - so searching the store for it finds nothing, and
+// following the link lands on a page with a different name, which reads like
+// the wrong page.
+export const EXTENSION_NAME = "Playwright Extension"
+// The id-only form, which the Web Store 301s to the slug form. It is 73
+// characters against the slug form's 94, and that is the difference between
+// fitting inside a clack note box at 80 columns and being wrapped mid-URL -
+// where it can be neither clicked nor copied, which is how a required install
+// step went unnoticed.
+export const EXTENSION_URL =
+  `https://chromewebstore.google.com/detail/${EXTENSION_ID}`
+// @latest. The server half is fetched from npm each session, and the extension
+// half auto-updates from the Web Store and cannot be pinned alongside it, so
+// pinning the server lets the two drift. Pinning also does not
+// make browser control work offline - the registry is consulted either way on
+// any machine that has not just run that exact version.
+//
+// Neither spec is a supply-chain control. The repo's bun.lock does not cover
+// this package: it is resolved by a bunx subprocess of claude, in its own
+// generated lockfile, with no integrity hash clco ever sees. A pinned version
+// string bounds the window and makes the choice attributable; it verifies
+// nothing.
+//
+// CLCO_MCP_PACKAGE overrides the spec - an internal mirror, a pinned version,
+// a rollback past a bad release.
+export const MCP_PACKAGE = "@playwright/mcp@latest"
+
+/** The spec clco will actually register, override included. */
+export function mcpPackage(): string {
+  return process.env.CLCO_MCP_PACKAGE || MCP_PACKAGE
+}
+
+/**
+ * Whether probing registry.npmjs.org says anything about the configured spec.
+ *
+ * Compares the package NAME, not the whole spec: two of CLCO_MCP_PACKAGE's
+ * three documented uses - pinning a version and rolling back past a bad
+ * release - leave the registry exactly where it was, so keying this on the
+ * full spec switched the check off for a corporate user who had merely pinned.
+ * A file:/link: version needs no registry at all, so it counts as neither.
+ */
+export function probesDefaultRegistry(pkg = mcpPackage()): boolean {
+  const at = pkg.lastIndexOf("@")
+  // at > 0, not >= 0: lastIndexOf returns -1 for a spec with no "@" and
+  // slice(0, -1) then quietly drops the last character ("playwright-mcp" ->
+  // "playwright-mc"), and index 0 is a scope marker, not a version separator.
+  const name = at > 0 ? pkg.slice(0, at) : pkg
+  const version = at > 0 ? pkg.slice(at + 1) : ""
+  if (version.includes(":") || version.includes("/")) return false
+  return name === MCP_PACKAGE.slice(0, MCP_PACKAGE.lastIndexOf("@"))
+}
+/** Set by the extension; with it the bridge attaches without a dialog. */
+export const TOKEN_ENV = "PLAYWRIGHT_MCP_EXTENSION_TOKEN"
+
+/**
+ * bunx when clco is running under bun, which it is — the launcher execs bun,
+ * so requiring Node as well was an extra dependency for no reason. Verified
+ * the server runs under bun, and bun honours NODE_EXTRA_CA_CERTS the same way,
+ * so the corporate CA still reaches it. npx remains the fallback for anyone
+ * running clco under Node.
+ */
+export function runner(): string {
+  if (typeof Bun !== "undefined" && Bun.which("bunx")) return "bunx"
+  return "npx"
+}
+
+/**
+ * Per-profile extension directories, by platform. Edge is included because
+ * both the extension and --extension mode support it.
+ */
+function browserRoots(home = homedir()): string[] {
+  switch (platform()) {
+    case "darwin":
+      return [
+        join(home, "Library", "Application Support", "Google", "Chrome"),
+        join(home, "Library", "Application Support", "Microsoft Edge"),
+      ]
+    case "win32": {
+      const local = process.env.LOCALAPPDATA ?? join(home, "AppData", "Local")
+      return [
+        join(local, "Google", "Chrome", "User Data"),
+        join(local, "Microsoft", "Edge", "User Data"),
+      ]
+    }
+    default:
+      return [
+        join(home, ".config", "google-chrome"),
+        join(home, ".config", "chromium"),
+        join(home, ".config", "microsoft-edge"),
+      ]
+  }
+}
+
+/**
+ * Whether the bridge extension is installed.
+ *
+ * Deliberately not probed over the network: the MCP server is spawned per
+ * conversation, so at clco startup nothing is listening and a probe would
+ * report "missing" for a working install.
+ */
+export async function extensionInstalled(home = homedir()): Promise<boolean> {
+  for (const root of browserRoots(home)) {
+    let profiles: string[]
+    try {
+      profiles = await readdir(root)
+    } catch {
+      continue
+    }
+    for (const profile of profiles) {
+      try {
+        const ids = await readdir(join(root, profile, "Extensions"))
+        if (ids.includes(EXTENSION_ID)) return true
+      } catch {
+        // not a profile directory, or no extensions in it
+      }
+    }
+  }
+  return false
+}
+
+/**
+ * The --mcp-config payload registering the server for this session only.
+ * Null without the extension: the server is only half of it, and registering
+ * it alone produces tools that fail on every call.
+ */
+export function browserMcpConfig(
+  installed: boolean,
+  /** Null means "no CA", which an ambient CLCO_CA_BUNDLE must not override. */
+  caBundleValue: string | null = process.env.CLCO_CA_BUNDLE ?? null,
+  /** Read here rather than at module load so a test can set it. */
+  pkg = mcpPackage(),
+): string | null {
+  if (!installed) return null
+  const env: Record<string, string> = {}
+  // npx fetches from the registry over its own TLS, outside clco's
+  // copilotFetch, so a corporate CA has to be handed down explicitly -
+  // otherwise browser control is the one feature that still breaks on the
+  // network clco was hardened for.
+  //
+  // One path, and one clco actually read: NODE_EXTRA_CA_CERTS names a single
+  // file while CLCO_CA_BUNDLE takes several, and forwarding a path clco had
+  // already logged as unreadable left the child with nothing but a warning on
+  // a stderr claude's UI does not show.
+  const first =
+    caBundleValue === null
+      ? undefined
+      : caBundleValue === process.env.CLCO_CA_BUNDLE
+        ? caChildPath()
+        : caPaths(caBundleValue)[0]
+  if (first) env.NODE_EXTRA_CA_CERTS = first
+  // The extension token deliberately does NOT go here. This object becomes an
+  // --mcp-config argv element, and argv is readable by other local users, so
+  // naming the token here published it. It reaches the server through claude's
+  // environment instead (setupEnv), which MCP children inherit.
+  return JSON.stringify({
+    mcpServers: {
+      playwright: {
+        command: runner(),
+        args: ["-y", pkg, "--extension"],
+        ...(Object.keys(env).length > 0 ? { env } : {}),
+      },
+    },
+  })
+}
+
+// The extension mints a base64url value; nothing else should be accepted.
+// A paste can easily pick up a shell prompt or a stray line, and storing that
+// silently produces a token that never works and no clue why.
+const TOKEN_SHAPE = /^[A-Za-z0-9_-]{20,}$/
+
+/**
+ * Accept what the extension actually puts on screen. It shows the whole
+ * assignment, so pasting that verbatim is the obvious move — as is pasting
+ * just the value, or a line copied with `export` in front. A multi-line paste
+ * keeps only the line carrying the token, since a terminal submits at the
+ * first newline and the rest would be lost anyway.
+ *
+ * Returns null for input that is not a token, so the caller can say so rather
+ * than store it.
+ */
+export function parseToken(input: string): string | null | undefined {
+  const lines = input.split(/[\r\n]+/).map((l) => l.trim()).filter(Boolean)
+  if (lines.length === 0) return undefined // skipped
+  const line =
+    lines.find((l) => l.includes(`${TOKEN_ENV}=`)) ??
+    lines.find((l) => TOKEN_SHAPE.test(l)) ??
+    lines[0]!
+  const bare = line.replace(/^export\s+/, "")
+  const value = bare.includes(`${TOKEN_ENV}=`)
+    ? bare.slice(bare.indexOf(`${TOKEN_ENV}=`) + TOKEN_ENV.length + 1)
+    : bare
+  const cleaned = value.trim().replace(/^(['"])(.*)\1$/, "$2").trim()
+  if (!cleaned) return undefined
+  return TOKEN_SHAPE.test(cleaned) ? cleaned : null
+}
+
+/** Why browser control will or will not work, in the words the user needs. */
+export type RegistryStatus = "ok" | "tls" | "expired" | "blocked" | "slow"
+
+const REGISTRY_PROBE_TIMEOUT_MS = 2_500
+
+/**
+ * Whether the registry can actually be reached, and if not, why.
+ *
+ * The package is resolved from npm at session start, so on a network that
+ * blocks or re-signs it the server never starts - and the failure would
+ * otherwise surface only as an MCP connection error inside claude, with clco's
+ * own startup line still claiming success. This has to be a real request: an
+ * earlier version ran `bunx --version`, which prints locally and therefore
+ * returned "reachable" on an air-gapped machine.
+ *
+ * A TLS rejection is reported apart from a block because they need different
+ * things from the user - one needs their company CA, the other cannot be fixed
+ * from here at all.
+ */
+export async function registryStatus(
+  timeoutMs = REGISTRY_PROBE_TIMEOUT_MS,
+  /** Overridden in tests; the probe has no other way to reach a TLS failure. */
+  url = "https://registry.npmjs.org/@playwright/mcp",
+): Promise<RegistryStatus> {
+  try {
+    // copilotFetch, so a corporate CA applies here exactly as it does to the
+    // Copilot calls - otherwise this would report "blocked" on the very
+    // networks the CA support exists for.
+    const res = await copilotFetch(url, {
+      method: "HEAD",
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    return res.ok ? "ok" : "blocked"
+  } catch (err) {
+    if (isTlsTrustError(err)) return "tls"
+    // The host answered and the chain may be fine; the dates are not. No CA
+    // fixes that, so it is not "tls" - but it is not "cannot reach" either,
+    // which is how a lapsed proxy certificate sent the user to their firewall
+    // team.
+    if (isCertValidityError(err)) return "expired"
+    // A 2.5s budget is clco's alone - the bunx inside claude has none - so a
+    // slow proxy must not be reported as a verdict that tools will not appear.
+    if ((err as Error)?.name === "TimeoutError") return "slow"
+    return "blocked"
+  }
+}
+
+/**
+ * Fold a status line to the terminal, continuing with a two-space indent.
+ *
+ * These lines carry a verdict AND a remedy, which is the point of them, so
+ * they do not fit an 80-column terminal on one line - and a terminal-wrapped
+ * line breaks mid-word and mid-URL, which is how a required install step went
+ * unread. Shortening them instead would delete the remedy, so they fold.
+ */
+function fold(text: string, width = 76): string {
+  const out: string[] = []
+  let line = ""
+  for (const word of text.split(" ")) {
+    const indent = out.length === 0 ? "" : "  "
+    if (line === "") line = indent + word
+    else if (`${line} ${word}`.length <= width) line += ` ${word}`
+    else {
+      out.push(line)
+      line = `  ${word}`
+    }
+  }
+  if (line !== "") out.push(line)
+  return out.join("\n")
+}
+
+/**
+ * One line for the startup summary, alongside adapter and model. Whether a
+ * session is attached is not knowable here — the server starts per
+ * conversation — so this reports what clco did, and whether a connect dialog
+ * is coming.
+ */
+export function startupLine(
+  enabled: boolean,
+  installed: boolean,
+  token?: string,
+  /** bunx ships with bun, which the installer guarantees; npx is a fallback. */
+  hasRunner = Bun.which("bunx") !== null || Bun.which("npx") !== null,
+  /** Undefined when not checked. */
+  registry?: RegistryStatus,
+  /** False when clco stood aside for a user-supplied --mcp-config. */
+  registered?: boolean,
+  pkg = mcpPackage(),
+  /** Whether a CA bundle actually LOADED - not merely whether the var is set. */
+  caLoaded = caBundle() !== undefined,
+): string | null {
+  if (!enabled) return null
+  if (!installed) {
+    // Two lines on purpose: the URL has to start a line to survive an 80-column
+    // terminal intact, and this is the one clco message whose whole job is to
+    // get a link in front of the user.
+    return (
+      `! browser: no tools - "${EXTENSION_NAME}" is not installed in Chrome,\n` +
+      `  and only you can add it:\n  ${EXTENSION_URL}`
+    )
+  }
+  if (!hasRunner) {
+    return "! browser: neither bunx nor npx found - cannot start Playwright MCP"
+  }
+  if (registered === false) {
+    return "! browser: skipped - your own --mcp-config takes over"
+  }
+  // Exhaustive by construction: a new RegistryStatus that nobody handles used
+  // to fall through to the success line, i.e. silent success for a failure.
+  if (registry !== undefined && registry !== "ok") {
+    const line: Record<Exclude<RegistryStatus, "ok">, string> = {
+      tls:
+        "TLS rejected by registry.npmjs.org - browser tools will not appear." +
+        // Telling someone to set a variable they already set is the advice
+        // this line exists to avoid giving. Keyed on whether a bundle LOADED,
+        // not on whether the variable is set.
+        (caLoaded
+          ? " Your CLCO_CA_BUNDLE does not cover this chain."
+          : " Set CLCO_CA_BUNDLE to your company CA."),
+      expired:
+        "registry.npmjs.org presented an expired certificate - browser tools" +
+        " will not appear. No CA file fixes this; check the proxy, or your clock.",
+      blocked: "cannot reach registry.npmjs.org - browser tools will not appear",
+      // No number: the budget is clco's own and the bunx inside claude has none.
+      slow: "registry.npmjs.org is slow to answer - browser tools may be slow to appear",
+    }
+    return fold(`! browser: ${line[registry]}`)
+  }
+  // Name the exact spec: it is user-overridable, it is what runs, and after a
+  // bad upstream release "which version did that session run?" has to be
+  // answerable from something.
+  //
+  // And say when nothing was checked - a bare "+" would assert a check that
+  // never ran. "Not the default package" rather than "another registry":
+  // CLCO_MCP_PACKAGE names a package, and which registry serves it lives in
+  // .npmrc, so a fork published to npmjs is unprobed without being elsewhere.
+  const notes = [
+    registry === undefined && !probesDefaultRegistry(pkg)
+      ? "not the default package, so the registry check was skipped"
+      : null,
+    token ? null : "connect dialog each session",
+  ].filter(Boolean)
+  return fold(`+ browser: ${pkg}${notes.length > 0 ? ` (${notes.join("; ")})` : ""}`)
+}
+
+/**
+ * What setup shows before asking anything: the state, without advice to run
+ * the very command that is running.
+ */
+export function setupNote(installed: boolean, pkg = mcpPackage()): string {
+  // Three separate things, and the old wording ran them together: it said
+  // "clco registers no browser server", which reads as though the extension
+  // WERE the server. It is not - clco registers the server, the extension is
+  // what lets that server drive the user's own tab, and the token only skips a
+  // click. Conflating them left people unsure what they had actually agreed to.
+  if (installed) {
+    return (
+      `${EXTENSION_NAME} found, so both halves are in place:\n` +
+      `  clco  registers ${pkg} --extension each session\n` +
+      `  you   click the extension to share a tab\n` +
+      `Tools then arrive as mcp__playwright__*.\n` +
+      `\n` +
+      `The token prompt after this is optional - press Enter to skip it.`
+    )
+  }
+  return (
+    `Browser control is two halves, and clco only owns one:\n` +
+    `  clco  registers ${pkg}, which it fetches from npm\n` +
+    `  you   install one Chrome extension, which clco cannot do\n` +
+    `\n` +
+    `The extension is what lets that server drive YOUR tab, with your\n` +
+    `logins, instead of a fresh throwaway profile. Without it clco\n` +
+    `registers no server at all, since a server with no tab to attach to\n` +
+    `would only fail on every call - so no browser tools appear.\n` +
+    `\n` +
+    `Install "${EXTENSION_NAME}", then restart clco:\n` +
+    `${EXTENSION_URL}\n` +
+    `\n` +
+    `Answering Yes now is fine - install it whenever you like.`
+  )
+}
+
+export function extensionHint(installed: boolean, token?: string, pkg = mcpPackage()): string {
+  if (!installed) {
+    return (
+      `Browser control is ON, but the Chrome extension it needs is not\n` +
+      `installed, so clco registers no server and no tools appear.\n` +
+      `Only you can install it - clco cannot:\n` +
+      `${EXTENSION_URL}`
+    )
+  }
+  // Whether a session is actually attached cannot be known here: the server
+  // starts per conversation and the extension connects to it afterwards. A
+  // stored token is the closest thing to a prediction, since it is exactly
+  // what removes the manual connect step.
+  return (
+    `${EXTENSION_NAME} found. Registering ${pkg} --extension\n` +
+    `each session. Tools arrive as mcp__playwright__*.\n` +
+    (token
+      ? `Token stored, so sessions attach without the connect dialog.`
+      : `No token stored - optional, and only affects the click: each\n` +
+        `session shows the connect dialog instead. The extension offers a\n` +
+        `${TOKEN_ENV} value; store it with:\n  pbpaste | clco token`)
+  )
+}

package/src/catalog.ts

@@ -0,0 +1,147 @@
+// Bridge between Copilot's model slugs and Claude Code's own model catalog.
+//
+// Copilot spells versions with dots ("claude-haiku-4.5"); Claude Code's
+// catalog uses dashes ("claude-haiku-4-5"). When the dashed form is a real
+// catalog id we advertise that instead, and the row needs no `behavesAs` —
+// Claude Code then applies the model's genuine context window, effort tiers
+// and prompt profile. Only slugs with no catalog twin fall back to
+// `behavesAs`, which borrows another model's client-side handling.
+
+/**
+ * Fallback catalog, captured from Claude Code 2.1.268. Only used when the
+ * installed binary cannot be scanned (see loadCatalog) — pinning the real
+ * list to a clco release would make every claude upgrade a silent liability:
+ * an id that moves out from under us drops its row from /model with no error.
+ */
+const FALLBACK_CATALOG_IDS: readonly string[] = [
+  "claude-fable-5",
+  "claude-fable-5-1",
+  "claude-haiku-4",
+  "claude-haiku-4-5",
+  "claude-opus-4",
+  "claude-opus-4-0",
+  "claude-opus-4-1",
+  "claude-opus-4-5",
+  "claude-opus-4-6",
+  "claude-opus-4-7",
+  "claude-opus-4-8",
+  "claude-opus-5",
+  "claude-sonnet-3-7",
+  "claude-sonnet-4",
+  "claude-sonnet-4-0",
+  "claude-sonnet-4-5",
+  "claude-sonnet-4-6",
+  "claude-sonnet-5",
+]
+
+// Resolved once per process from the installed claude binary, cached on disk
+// per version so the ~0.7s scan is paid only after a claude upgrade.
+let catalogIds: Set<string> = new Set(FALLBACK_CATALOG_IDS)
+
+/** Ids the installed Claude Code knows. */
+export function catalogModelIds(): ReadonlySet<string> {
+  return catalogIds
+}
+
+/** Claude Code's newest id per family, used to resolve `behavesAs` targets. */
+export const LATEST_PER_FAMILY: Readonly<Record<ModelFamily, string>> = {
+  opus: "claude-opus-5",
+  sonnet: "claude-sonnet-5",
+  haiku: "claude-haiku-4-5",
+  fable: "claude-fable-5-1",
+}
+
+export type ModelFamily = "opus" | "sonnet" | "haiku" | "fable"
+
+export function familyOf(id: string): ModelFamily {
+  if (id.includes("opus")) return "opus"
+  if (id.includes("haiku")) return "haiku"
+  if (id.includes("fable")) return "fable"
+  return "sonnet"
+}
+
+/**
+ * The id to show Claude Code for an upstream slug, or null when the slug has
+ * no catalog twin. Returns the slug itself when it is already a catalog id.
+ */
+/**
+ * Read the catalog out of the claude binary, so clco tracks whatever version
+ * is actually installed instead of whatever was current when clco shipped.
+ * Cached by binary path + size + mtime; any failure keeps the fallback.
+ */
+export async function loadCatalog(binary: string): Promise<void> {
+  const { readFile, writeFile, mkdir, stat } = await import("node:fs/promises")
+  const { homedir } = await import("node:os")
+  const { join } = await import("node:path")
+  const dir = join(homedir(), ".config", "clco")
+  let key: string
+  try {
+    const s = await stat(binary)
+    key = `${s.size}-${Math.round(s.mtimeMs)}`
+  } catch {
+    return
+  }
+  const cache = join(dir, "catalog.json")
+  try {
+    const saved = JSON.parse(await readFile(cache, "utf8")) as {
+      key?: string
+      ids?: string[]
+    }
+    if (saved.key === key && saved.ids?.length) {
+      catalogIds = new Set(saved.ids)
+      return
+    }
+  } catch {
+    // no cache yet, or unreadable — rescan
+  }
+  try {
+    const bytes = await readFile(binary)
+    const found = new TextDecoder("latin1")
+      .decode(bytes)
+      .match(/claude-(?:opus|sonnet|haiku|fable)-\d[0-9a-z-]*/g)
+    if (!found?.length) return
+    const ids = [...new Set(found)]
+    catalogIds = new Set(ids)
+    await mkdir(dir, { recursive: true, mode: 0o700 }).catch(() => {})
+    await writeFile(cache, JSON.stringify({ key, ids })).catch(() => {})
+  } catch {
+    // unreadable binary — the fallback list still applies
+  }
+}
+
+export function advertisedId(upstreamId: string): string | null {
+  if (catalogIds.has(upstreamId)) return upstreamId
+  const dashed = upstreamId.replace(/\./g, "-")
+  return catalogIds.has(dashed) ? dashed : null
+}
+
+/**
+ * A catalog id whose client-side handling a non-catalog model can borrow.
+ * Prefers a same-family model the upstream actually serves, so the mapping
+ * ages with both sides at once. The target only has to be an id Claude Code
+ * knows, not one the upstream serves, so a static per-family id backs it up —
+ * without that, an upstream carrying no Claude models at all would leave every
+ * row unborrowed and therefore unofferable, i.e. an empty /model.
+ */
+export function resolveBehavesAs(
+  family: ModelFamily,
+  upstreamIds: readonly string[],
+): string {
+  const known = upstreamIds
+    .map(advertisedId)
+    .filter((id): id is string => id !== null)
+  const catalog = [...catalogIds]
+  return (
+    known.find((id) => familyOf(id) === family) ??
+    known.find((id) => familyOf(id) === "sonnet") ??
+    known[0] ??
+    // Nothing the upstream serves is catalog-known, so fall back to the
+    // installed catalog itself rather than to an id baked into clco.
+    (catalogIds.has(LATEST_PER_FAMILY[family])
+      ? LATEST_PER_FAMILY[family]
+      : (catalog.find((id) => familyOf(id) === family) ??
+        catalog.find((id) => familyOf(id) === "sonnet") ??
+        catalog[0] ??
+        LATEST_PER_FAMILY[family]))
+  )
+}