@semanticist14/clco 0.1.0

package/scripts/mock-upstream.ts

@@ -0,0 +1,129 @@
+// Minimal mock Copilot upstream for end-to-end testing without GitHub auth.
+// Usage: bun run scripts/mock-upstream.ts [port]   then
+//        CLCO_UPSTREAM=http://127.0.0.1:<port> clco ...
+
+const port = Number(process.argv[2] ?? 9099)
+
+Bun.serve({
+  hostname: "127.0.0.1",
+  port,
+  fetch: async (req) => {
+    const url = new URL(req.url)
+    if (url.pathname === "/models") {
+      const native = ["/v1/messages", "/chat/completions"]
+      return Response.json({
+        data: [
+          // Claude-style models route through the native Anthropic endpoint,
+          // exactly as real Copilot declares them.
+          { id: "mock-opus", supported_endpoints: native },
+          { id: "mock-sonnet", supported_endpoints: native },
+          { id: "mock-haiku", supported_endpoints: native },
+          // Translation-path model, for exercising the chat dialect.
+          { id: "mock-chat", supported_endpoints: ["/chat/completions"] },
+        ].map((m) => ({
+          ...m,
+          // Matches production: GitHub returns false for every model.
+          model_picker_enabled: false,
+          policy: { state: "enabled" },
+          capabilities: {
+            type: "chat",
+            family: m.id,
+            limits: { max_prompt_tokens: 200000, max_context_window_tokens: 264000 },
+            supports: { reasoning_effort: ["low", "medium", "high", "xhigh", "max"] },
+          },
+        })),
+      })
+    }
+
+    if (url.pathname === "/v1/messages") {
+      const body = (await req.json()) as { stream?: boolean; model: string }
+      const text = "Mock native response: OK"
+      if (body.stream) {
+        return new Response(
+          [
+            `event: message_start\ndata: ${JSON.stringify({
+              type: "message_start",
+              message: {
+                id: "msg_mock",
+                type: "message",
+                role: "assistant",
+                content: [],
+                model: body.model,
+                stop_reason: null,
+                stop_sequence: null,
+                usage: { input_tokens: 5, output_tokens: 0 },
+              },
+            })}\n\n`,
+            `event: content_block_start\ndata: ${JSON.stringify({
+              type: "content_block_start",
+              index: 0,
+              content_block: { type: "text", text: "" },
+            })}\n\n`,
+            `event: content_block_delta\ndata: ${JSON.stringify({
+              type: "content_block_delta",
+              index: 0,
+              delta: { type: "text_delta", text },
+            })}\n\n`,
+            `event: content_block_stop\ndata: ${JSON.stringify({
+              type: "content_block_stop",
+              index: 0,
+            })}\n\n`,
+            `event: message_delta\ndata: ${JSON.stringify({
+              type: "message_delta",
+              delta: { stop_reason: "end_turn", stop_sequence: null },
+              usage: { output_tokens: 6 },
+            })}\n\n`,
+            `event: message_stop\ndata: ${JSON.stringify({ type: "message_stop" })}\n\n`,
+          ].join(""),
+          { headers: { "content-type": "text/event-stream" } },
+        )
+      }
+      return Response.json({
+        id: "msg_mock",
+        type: "message",
+        role: "assistant",
+        model: body.model,
+        content: [{ type: "text", text }],
+        stop_reason: "end_turn",
+        stop_sequence: null,
+        usage: { input_tokens: 5, output_tokens: 6 },
+      })
+    }
+
+    if (url.pathname !== "/chat/completions") {
+      return new Response("not found", { status: 404 })
+    }
+    const body = (await req.json()) as { stream?: boolean; model: string }
+    const chunk = (delta: unknown, finish: string | null = null) =>
+      `data: ${JSON.stringify({
+        id: "mock-1",
+        model: body.model,
+        choices: [{ index: 0, finish_reason: finish, delta }],
+      })}\n\n`
+
+    if (body.stream) {
+      return new Response(
+        [
+          chunk({ role: "assistant", content: "Mock upstream response: OK" }),
+          chunk({}, "stop"),
+          "data: [DONE]\n\n",
+        ].join(""),
+        { headers: { "content-type": "text/event-stream" } },
+      )
+    }
+    return Response.json({
+      id: "mock-1",
+      model: body.model,
+      choices: [
+        {
+          index: 0,
+          finish_reason: "stop",
+          message: { role: "assistant", content: "Mock upstream response: OK" },
+        },
+      ],
+      usage: { prompt_tokens: 5, completion_tokens: 3 },
+    })
+  },
+})
+
+console.log(`mock upstream on http://127.0.0.1:${port}`)

package/scripts/write-launcher.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Writes the clco launcher. Lives here rather than inline in install.sh so
+# `clco update` can refresh it too.
+#
+# Usage: write-launcher.sh <app-dir> <bin-dir> [bun-path]
+set -euo pipefail
+
+CLCO_DIR="${1:?app dir required}"
+BIN_DIR="${2:?bin dir required}"
+BUN_BIN="${3:-$(command -v bun)}"
+[ -n "$BUN_BIN" ] || { echo "bun not found" >&2; exit 1; }
+
+# Bump when the launcher body changes; clco compares it to warn about a stale
+# launcher that predates a feature.
+LAUNCHER_VERSION=4
+
+mkdir -p "$BIN_DIR"
+[ ! -d "$BIN_DIR/clco" ] || {
+  echo "$BIN_DIR/clco is a directory, not a launcher file" >&2
+  exit 1
+}
+TMP_LAUNCHER="$(mktemp "$BIN_DIR/.clco-launcher.XXXXXX")"
+trap 'rm -f "$TMP_LAUNCHER"' EXIT
+{
+  printf '%s\n' '#!/usr/bin/env bash'
+  printf '# clco launcher v%s (generated by scripts/write-launcher.sh)\n' "$LAUNCHER_VERSION"
+  printf 'CLCO_APP_DIR=%q\n' "$CLCO_DIR"
+  printf 'CLCO_BIN_DIR=%q\n' "$BIN_DIR"
+  printf 'CLCO_BUN_BIN=%q\n' "$BUN_BIN"
+  printf 'CLCO_LAUNCHER_VERSION=%s\n' "$LAUNCHER_VERSION"
+  printf '%s\n' 'export CLCO_APP_DIR CLCO_BIN_DIR CLCO_BUN_BIN CLCO_LAUNCHER_VERSION'
+  printf '%s\n' '' \
+    '# Corporate TLS: clco adds a CA to the OS trust store itself, per request, via' \
+    '# CLCO_CA_BUNDLE — see src/tls.ts. Nothing to set here; NODE_USE_SYSTEM_CA is' \
+    '# a no-op on bun, whose default trust set already merges the system roots.' \
+    '' \
+    '# bun strips a leading "--" before scripts see it — translate it into a' \
+    '# sentinel that cli.ts understands as "everything after belongs to claude".' \
+    'if [ "${1:-}" = "--" ]; then' \
+    '  shift' \
+    '  set -- "__clco_passthrough__" "$@"' \
+    'fi' \
+    'exec "$CLCO_BUN_BIN" run --no-install "$CLCO_APP_DIR/src/cli.ts" "$@"'
+} > "$TMP_LAUNCHER"
+chmod +x "$TMP_LAUNCHER"
+mv -f "$TMP_LAUNCHER" "$BIN_DIR/clco"
+trap - EXIT

package/src/api.ts

@@ -0,0 +1,90 @@
+// Upstream endpoints, OAuth constants, and client identity headers.
+// The editor identity mirrors an official Copilot Chat client, which is what
+// the Copilot backend expects on api.githubcopilot.com.
+
+import { caBundle } from "./tls"
+
+// Every outbound HTTPS request clco makes goes through here so a corporate CA
+// configured via CLCO_CA_BUNDLE applies uniformly. Per-request `tls.ca` needs
+// no process-level env, so it works regardless of how clco was launched.
+export function copilotFetch(
+  url: string,
+  init?: RequestInit,
+): Promise<Response> {
+  const ca = caBundle()
+  return fetch(url, ca ? { ...init, tls: { ca } } : init)
+}
+
+export const GITHUB_BASE_URL = "https://github.com"
+export const GITHUB_API_BASE_URL = "https://api.github.com"
+export const GITHUB_CLIENT_ID = "Iv1.b507a08c87ecfe98"
+export const GITHUB_APP_SCOPES = "read:user"
+export const GITHUB_API_VERSION = "2025-04-01"
+
+const COPILOT_CHAT_VERSION =
+  process.env.CLCO_CHAT_VERSION ?? "0.26.7"
+const EDITOR_VERSION = process.env.CLCO_EDITOR_VERSION ?? "1.104.0"
+
+// Test/dev hook: point the adapter at a mock upstream; GitHub auth is skipped.
+// Must be a non-empty URL — an empty string is treated as unset everywhere
+// (single source of truth via isMockMode/copilotBaseUrl).
+export function mockUpstream(): string | undefined {
+  const value = process.env.CLCO_UPSTREAM?.trim()
+  return value ? value : undefined
+}
+
+export function isMockMode(): boolean {
+  return mockUpstream() !== undefined
+}
+
+// Business/Enterprise accounts get a different API host in the Copilot
+// token response's endpoints.api field — official clients route there, so
+// clco does too (set by token.ts after each token exchange).
+let dynamicCopilotBase: string | null = null
+
+export function setCopilotBase(url: string | null): void {
+  dynamicCopilotBase =
+    url && url.startsWith("https://") ? url.replace(/\/$/, "") : null
+}
+
+export function copilotBaseUrl(): string {
+  return mockUpstream() ?? dynamicCopilotBase ?? "https://api.githubcopilot.com"
+}
+
+export function copilotRequestHeaders(
+  token: string,
+  opts?: {
+    agentInitiated?: boolean
+    vision?: boolean
+    accept?: string
+  },
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    authorization: `Bearer ${token}`,
+    "content-type": "application/json",
+    accept: opts?.accept ?? "application/json",
+    "copilot-integration-id": "vscode-chat",
+    "editor-version": `vscode/${EDITOR_VERSION}`,
+    "editor-plugin-version": `copilot-chat/${COPILOT_CHAT_VERSION}`,
+    "user-agent": `GitHubCopilotChat/${COPILOT_CHAT_VERSION}`,
+    "openai-intent": "conversation-panel",
+    "x-github-api-version": GITHUB_API_VERSION,
+    "x-request-id": crypto.randomUUID(),
+    "x-vscode-user-agent-library-version": "electron-fetch",
+    "x-initiator": opts?.agentInitiated ? "agent" : "user",
+  }
+  if (opts?.vision) headers["copilot-vision-request"] = "true"
+  return headers
+}
+
+export function githubRequestHeaders(githubToken: string): Record<string, string> {
+  return {
+    "content-type": "application/json",
+    accept: "application/json",
+    authorization: `token ${githubToken}`,
+    "editor-version": `vscode/${EDITOR_VERSION}`,
+    "editor-plugin-version": `copilot-chat/${COPILOT_CHAT_VERSION}`,
+    "user-agent": `GitHubCopilotChat/${COPILOT_CHAT_VERSION}`,
+    "x-github-api-version": GITHUB_API_VERSION,
+  }
+}

package/src/auth.ts

@@ -0,0 +1,130 @@
+// GitHub OAuth device flow. The resulting user token (gho_...) is long-lived
+// and stored via config.ts; it is exchanged for short-lived Copilot tokens in
+// token.ts.
+
+import {
+  GITHUB_API_BASE_URL,
+  GITHUB_APP_SCOPES,
+  GITHUB_BASE_URL,
+  GITHUB_CLIENT_ID,
+  copilotFetch,
+  githubRequestHeaders,
+  isMockMode,
+} from "./api"
+import { loadAuth, saveAuth } from "./config"
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+export interface GithubIdentity {
+  token: string
+  login?: string
+  fresh: boolean
+}
+
+export async function ensureGithubToken(): Promise<GithubIdentity> {
+  // Mock mode (CLCO_UPSTREAM set): no GitHub involved at all.
+  if (isMockMode()) {
+    return { token: "mock", fresh: false }
+  }
+  const saved = await loadAuth()
+  if (saved?.github_token) {
+    return { token: saved.github_token, login: saved.login, fresh: false }
+  }
+  const { token, login } = await runDeviceFlow()
+  return { token, login, fresh: true }
+}
+
+export async function runDeviceFlow(): Promise<{ token: string; login?: string }> {
+  const res = await copilotFetch(`${GITHUB_BASE_URL}/login/device/code`, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({
+      client_id: GITHUB_CLIENT_ID,
+      scope: GITHUB_APP_SCOPES,
+    }),
+    signal: AbortSignal.timeout(15_000),
+  })
+  if (!res.ok) {
+    throw new Error(`device code request failed: HTTP ${res.status}`)
+  }
+  const dc = (await res.json()) as {
+    device_code: string
+    user_code: string
+    verification_uri: string
+    expires_in: number
+    interval: number
+  }
+
+  console.log("\nGitHub authentication required:")
+  console.log(`  1. Open in your browser: ${dc.verification_uri}`)
+  console.log(`  2. Enter the code: \x1b[1m${dc.user_code}\x1b[0m\n`)
+
+  if (process.platform === "darwin") {
+    const open = Bun.spawn(["open", dc.verification_uri], {
+      stdout: "ignore",
+      stderr: "ignore",
+    })
+    await open.exited.catch(() => {})
+  }
+
+  let interval = (dc.interval + 1) * 1000
+  const deadline = Date.now() + dc.expires_in * 1000
+  while (Date.now() < deadline) {
+    await sleep(interval)
+    let body: {
+      access_token?: string
+      error?: string
+      error_description?: string
+    }
+    try {
+      const poll = await copilotFetch(`${GITHUB_BASE_URL}/login/oauth/access_token`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json",
+        },
+        body: JSON.stringify({
+          client_id: GITHUB_CLIENT_ID,
+          device_code: dc.device_code,
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        }),
+        signal: AbortSignal.timeout(15_000),
+      })
+      if (!poll.ok) {
+        // 4xx won't heal by waiting; 5xx might.
+        if (poll.status >= 400 && poll.status < 500) {
+          throw new Error(`device flow polling failed: HTTP ${poll.status}`)
+        }
+        console.error(`[clco] polling error HTTP ${poll.status} - retrying`)
+        continue
+      }
+      body = (await poll.json()) as typeof body
+    } catch (err) {
+      if (err instanceof Error && err.message.startsWith("device flow")) throw err
+      continue
+    }
+
+    if (body.access_token) {
+      const token = body.access_token
+      let login: string | undefined
+      try {
+        const user = await copilotFetch(`${GITHUB_API_BASE_URL}/user`, {
+          headers: githubRequestHeaders(token),
+        })
+        if (user.ok) login = ((await user.json()) as { login?: string }).login
+      } catch {
+        // login display is best-effort
+      }
+      await saveAuth({ github_token: token, login })
+      return { token, login }
+    }
+    if (body.error === "slow_down") {
+      interval += 5000
+    } else if (body.error && body.error !== "authorization_pending") {
+      throw new Error(
+        `device flow failed: ${body.error} ${body.error_description ?? ""}`,
+      )
+    }
+  }
+  throw new Error("device flow timed out")
+}

package/src/blocks.ts

@@ -0,0 +1,198 @@
+// The one place that decides what an Anthropic content block means.
+//
+// It used to be twenty `block.type === "..."` comparisons spread across
+// translate.ts and responses.ts, each an if/else-if chain with no final else.
+// A block type none of them listed therefore contributed nothing and said
+// nothing: a PDF attachment (`document`) was dropped on the floor and the
+// model answered confidently about a file it had never seen. Nothing in the
+// type system could catch that, because every block arrives through
+// `JSON.parse` and Claude Code adds block types on its own schedule.
+//
+// So the knowledge lives here, once, and the dispatch is exhaustive: adding a
+// type to KNOWN_BLOCKS without handling it fails `tsc`, and anything NOT in
+// KNOWN_BLOCKS becomes a visible placeholder rather than silence. The dialects
+// then only decide how to render a classified block, never what one is.
+
+export interface TextBlock {
+  type: "text"
+  text: string
+  /** Copilot's prompt-cache marker rides on the block Claude Code sends. */
+  cache_control?: { type: string }
+}
+
+export interface ThinkingBlock {
+  type: "thinking"
+  thinking: string
+}
+
+/** Thinking the upstream redacted; it carries no readable text. */
+export interface RedactedThinkingBlock {
+  type: "redacted_thinking"
+  data: string
+}
+
+export interface ImageBlock {
+  type: "image"
+  source: { type: string; media_type: string; data: string }
+}
+
+/** A file attachment. No translated dialect has anywhere to put one. */
+export interface DocumentBlock {
+  type: "document"
+  source: { type: string; media_type?: string; data?: string; url?: string }
+  title?: string
+}
+
+export interface ToolUseBlock {
+  type: "tool_use"
+  id: string
+  name: string
+  input: Record<string, unknown>
+}
+
+export interface ToolResultBlock {
+  type: "tool_result"
+  tool_use_id: string
+  is_error?: boolean
+  content?: string | Array<TextBlock | ImageBlock | ThinkingBlock>
+}
+
+export type ContentBlock =
+  | TextBlock
+  | ThinkingBlock
+  | RedactedThinkingBlock
+  | ImageBlock
+  | DocumentBlock
+  | ToolUseBlock
+  | ToolResultBlock
+
+/**
+ * Every type this file knows how to classify. The exhaustive switch below is
+ * checked against it, so extending this list without extending the switch is
+ * a compile error - which is the whole point of the file.
+ */
+export const KNOWN_BLOCKS = [
+  "text",
+  "thinking",
+  "redacted_thinking",
+  "image",
+  "document",
+  "tool_use",
+  "tool_result",
+] as const
+
+export type KnownBlockType = (typeof KNOWN_BLOCKS)[number]
+
+const KNOWN = new Set<string>(KNOWN_BLOCKS)
+
+/**
+ * A block as it arrives: off the wire via JSON.parse, so nothing about it is
+ * guaranteed. Taking `unknown` rather than a shaped type is deliberate - the
+ * whole failure this file fixes was code that trusted a shape the wire never
+ * promised.
+ */
+export type RawBlock = unknown
+
+function field(block: unknown, key: string): unknown {
+  return typeof block === "object" && block !== null
+    ? (block as Record<string, unknown>)[key]
+    : undefined
+}
+
+/** What a dialect has to render. `unsupported` is never silence. */
+export type Classified =
+  | { kind: "text"; text: string }
+  | { kind: "image"; block: ImageBlock }
+  | { kind: "tool_use"; block: ToolUseBlock }
+  | { kind: "tool_result"; block: ToolResultBlock }
+  /**
+   * Carried forward as text so the model is told something was there. A
+   * dropped block changes the answer; a named placeholder only shortens it,
+   * and the user can see which it was.
+   */
+  | { kind: "unsupported"; blockType: string; text: string }
+
+/** Wire strings are not guaranteed to be strings. */
+function str(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function assertNever(value: never): never {
+  throw new Error(`unhandled content block: ${JSON.stringify(value)}`)
+}
+
+function placeholder(blockType: string, detail?: string): Classified {
+  return {
+    kind: "unsupported",
+    blockType,
+    text: `[clco: a ${blockType} block was not forwarded - this model's dialect has no equivalent${
+      detail ? `, ${detail}` : ""
+    }]`,
+  }
+}
+
+/**
+ * Classify one block. Unknown types and known-but-unforwardable types both
+ * come back as `unsupported`, distinguishable by `blockType`.
+ */
+export function classifyBlock(block: RawBlock): Classified {
+  const raw = field(block, "type")
+  const type = typeof raw === "string" ? raw : "(missing type)"
+  if (!KNOWN.has(type)) return placeholder(type)
+  return classifyKnown(block, type as KnownBlockType)
+}
+
+// `block` stays raw here rather than being asserted to ContentBlock: it came
+// off the wire, so a field the interface calls required may simply be absent,
+// and each case narrows only what it actually reads.
+function classifyKnown(block: unknown, type: KnownBlockType): Classified {
+  switch (type) {
+    case "text":
+      return { kind: "text", text: str(field(block, "text")) }
+    // Reasoning text is ordinary text to a dialect that has no thinking
+    // channel; dropping it loses the assistant's own stated reasoning from
+    // the transcript it is about to continue.
+    case "thinking":
+      return { kind: "text", text: str(field(block, "thinking")) }
+    // Nothing readable to forward, and it is not a loss worth narrating on
+    // every turn - the upstream redacted it, not clco.
+    case "redacted_thinking":
+      return { kind: "text", text: "" }
+    case "image":
+      return { kind: "image", block: block as unknown as ImageBlock }
+    case "document": {
+      const title = str(field(block, "title"))
+      return placeholder(
+        "document",
+        title ? `titled ${JSON.stringify(title)}` : "no text extracted",
+      )
+    }
+    case "tool_use":
+      return { kind: "tool_use", block: block as unknown as ToolUseBlock }
+    case "tool_result":
+      return { kind: "tool_result", block: block as unknown as ToolResultBlock }
+    default:
+      return assertNever(type)
+  }
+}
+
+/** Classify a whole message body, with the string shorthand expanded. */
+export function classifyContent(content: unknown): Classified[] {
+  if (content === undefined || content === null) return []
+  if (typeof content === "string") return [{ kind: "text", text: content }]
+  if (!Array.isArray(content)) return []
+  return content.map(classifyBlock)
+}
+
+/** The block types in a body that clco could not forward, for diagnostics. */
+export function unsupportedTypes(blocks: Classified[]): string[] {
+  return [
+    ...new Set(
+      blocks
+        .filter((b): b is Extract<Classified, { kind: "unsupported" }> =>
+          b.kind === "unsupported",
+        )
+        .map((b) => b.blockType),
+    ),
+  ]
+}