@typeship-ax/mcp 0.8.0 → 0.10.0

package/src/core/http.ts

@@ -81,6 +81,23 @@ export class UnexpectedApiError extends ApiError<number, unknown> {
   }
 }
 
+/** A successful response declared JSON but carried a body that could not be parsed. */
+export class ResponseParseError extends Error {
+  readonly status: number;
+  readonly body: string;
+  readonly response: ResponseMeta;
+  override readonly cause?: unknown;
+
+  constructor(body: string, response: ResponseMeta, cause?: unknown) {
+    super("HTTP " + response.status + " response body was not valid JSON");
+    this.name = "ResponseParseError";
+    this.status = response.status;
+    this.body = body;
+    this.response = response;
+    this.cause = cause;
+  }
+}
+
 
 // ---------------------------------------------------------------------------
 // Optional runtime validation — zero-dependency, schema table in schemas.ts
@@ -222,7 +239,7 @@ function transportFailureMessage(method: string, url: string, cause: unknown): s
   return method + " " + url + " failed: " + detail;
 }
 
-/** The request never produced an HTTP response (network failure, timeout, abort). */
+/** The request failed before a complete HTTP response arrived (network failure, timeout, abort, or truncated body). */
 export class TransportError extends Error {
   override readonly cause?: unknown;
 
@@ -236,6 +253,7 @@ export class TransportError extends Error {
 type ErrorCtor = new (body: any, response: ResponseMeta) => ApiError<number, unknown>;
 
 export interface CoreRequest {
+  security?: Record<string, string[]>[];
   method: string;
   path: string;
   query?: Record<string, unknown>;
@@ -268,7 +286,39 @@ export interface RetryPolicy {
   retryNonIdempotent?: boolean;
 }
 
+export interface SecurityCredential {
+  headers?: Record<string, AuthValue>;
+  query?: Record<string, AuthValue>;
+}
+
+/** Resolve one complete alternative in spec order. Missing or incompatible
+ * combinations contribute no partial credentials. Anonymous operations send
+ * no generated credentials; explicit headers/hooks remain application owned. */
+function selectSecurity(requirements: Record<string, string[]>[], credentials: Record<string, SecurityCredential>): SecurityCredential {
+  for (const requirement of requirements) {
+    const names = Object.keys(requirement);
+    if (!names.length || names.some((name) => !Object.hasOwn(credentials, name))) continue;
+    const selected: SecurityCredential = { headers: Object.create(null), query: Object.create(null) };
+    const destinations = new Set<string>();
+    let conflict = false;
+    for (const name of names) {
+      for (const location of ["headers", "query"] as const) {
+        for (const [wire, value] of Object.entries(credentials[name]![location] ?? {})) {
+          const destination = location + ":" + (location === "headers" ? wire.toLowerCase() : wire);
+          if (destinations.has(destination)) conflict = true;
+          destinations.add(destination);
+          selected[location]![wire] = value;
+        }
+      }
+    }
+    if (!conflict) return selected;
+  }
+  return {};
+}
+
 export interface CoreConfig {
+  /** Named credentials are selected using each operation's requirements. */
+  credentials?: Record<string, SecurityCredential>;
   baseUrl: string;
   headers: Record<string, AuthValue>;
   /** Auth carried as query parameters (apiKey-in-query schemes). */
@@ -317,7 +367,7 @@ export interface DebugEvent {
   /** 1-based; >1 means this was a retry */
   attempt: number;
   requestId?: string;
-  /** transport failure message, when there was no response */
+  /** transport failure message, when the request failed before a complete response */
   error?: string;
 }
 
@@ -376,8 +426,14 @@ export class HttpCore {
     const policy: RetryPolicy = { ...this.config.retry, ...req.retry };
     const maxRetries = req.options?.maxRetries ?? policy.maxRetries ?? this.config.maxRetries;
     const timeoutMs = req.options?.timeoutMs ?? this.config.timeoutMs;
-    const retryAllowed = req.idempotent === true || req.method === "GET" || policy.retryNonIdempotent === true;
-    const retryableStatuses = policy.statuses ? new Set(policy.statuses) : RETRYABLE_STATUSES;
+    const retryAllowed =
+      req.idempotent === true ||
+      req.method === "GET" ||
+      req.idempotencyKey !== undefined ||
+      policy.retryNonIdempotent === true;
+    const retryableStatuses = policy.statuses
+      ? new Set(policy.statuses)
+      : RETRYABLE_STATUSES;
 
     // One key per logical call, reused on every retry — that's the point
     // of idempotency keys.
@@ -449,13 +505,14 @@ export class HttpCore {
         try {
           data = (await parseBody(response, req.method)) as T;
         } catch (cause) {
-          emitResponseDebug(response);
-          const error = new TransportError(
-            "The response body read was aborted before completing",
+          const parseError = cause instanceof ResponseParseError ? cause : undefined;
+          emitResponseDebug(response, parseError?.body);
+          const error = (parseError ?? new TransportError(
+            "The response body read failed before completing",
             cause,
-          ) as unknown as E;
+          )) as unknown as E;
           await this.config.onError?.(error, { method: req.method, path: req.path });
-          return { ok: false, error, response: meta(response) };
+          return { ok: false, error, response: parseError?.response ?? meta(response) };
         }
         emitResponseDebug(response, data);
         const responseMeta = meta(response, data);
@@ -527,8 +584,9 @@ export class HttpCore {
     attempt: number,
     autoIdempotencyKey?: string,
   ): Promise<Response> {
+    const selected = req.security && this.config.credentials ? selectSecurity(req.security, this.config.credentials) : {};
     const headers: Record<string, string> = {};
-    for (const [k, v] of Object.entries(this.config.headers)) {
+    for (const [k, v] of Object.entries({ ...this.config.headers, ...selected.headers })) {
       headers[k] = await resolveAuthValue(v);
     }
     if (req.idempotencyKey && autoIdempotencyKey) {
@@ -544,7 +602,7 @@ export class HttpCore {
 
     const context: RequestContext = {
       method: req.method,
-      url: await this.buildUrl(req),
+      url: await this.buildUrl(req, selected.query),
       headers,
       attempt,
     };
@@ -632,7 +690,7 @@ export class HttpCore {
     }
   }
 
-  private async buildUrl(req: CoreRequest): Promise<string> {
+  private async buildUrl(req: CoreRequest, authQuery?: Record<string, AuthValue>): Promise<string> {
     const base = this.config.baseUrl.replace(/\/+$/, "");
     const url = new URL(base + req.path);
     for (const [k, v] of Object.entries(req.query ?? {})) {
@@ -644,7 +702,7 @@ export class HttpCore {
         appendDeep(url.searchParams, k, v);
       }
     }
-    for (const [k, v] of Object.entries(this.config.query)) {
+    for (const [k, v] of Object.entries({ ...this.config.query, ...authQuery })) {
       url.searchParams.append(k, await resolveAuthValue(v));
     }
     return url.toString();
@@ -704,17 +762,28 @@ function serializeBody(req: CoreRequest): { body: NonNullable<RequestInit["body"
 
 async function parseBody(response: Response, method: string): Promise<unknown> {
   if (method === "HEAD" || response.status === 204 || response.status === 205) return undefined;
-  const contentType = response.headers.get("content-type") ?? "";
+  const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+  const mediaType = contentType.split(";", 1)[0]!.trim();
+  const slash = mediaType.indexOf("/");
+  const subtype = slash === -1 ? "" : mediaType.slice(slash + 1);
   try {
-    if (contentType.includes("json")) return await response.json();
+    if (subtype === "json" || subtype.endsWith("+json")) {
+      const body = await response.text();
+      if (body.length === 0) return undefined;
+      try {
+        return JSON.parse(body);
+      } catch (cause) {
+        throw new ResponseParseError(body, meta(response, body), cause);
+      }
+    }
     if (contentType.startsWith("text/")) return await response.text();
     if (response.body === null) return undefined;
     return await response.blob();
   } catch (cause) {
-    // A timed-out or aborted body read is a transport failure, not an
-    // empty body — surface it instead of faking success.
-    if (cause instanceof Error && (cause.name === "AbortError" || cause.name === "TimeoutError")) throw cause;
-    return undefined;
+    if (cause instanceof ResponseParseError) throw cause;
+    // A timed-out, aborted, or prematurely terminated body is a transport
+    // failure, not an empty body — surface it instead of faking success.
+    throw cause;
   }
 }
 

package/src/credential-storage.ts

@@ -0,0 +1,183 @@
+import { spawnSync } from "node:child_process";
+import { createCipheriv, createDecipheriv, createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { FileCredentialStore, CredentialStorageError, type CredentialCodec } from "./oauth-session.js";
+
+export interface NativeCommandResult { status: number | null; stdout: string; stderr: string; error?: unknown }
+export type NativeCommand = (executable: string, args: string[], input?: string) => NativeCommandResult;
+export interface CredentialKeyStore {
+  readonly name: string;
+  read(): Buffer | null;
+  write(key: Buffer): void;
+  /** Used only when explicitly removing this wrapping key, not ordinary logout. */
+  remove(): void;
+}
+
+const nativeCommand: NativeCommand = (executable, args, input) => {
+  const result = spawnSync(executable, args, { input, encoding: "utf8", timeout: 15_000, maxBuffer: 64 * 1024, windowsHide: true, shell: false });
+  return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "", ...(result.error ? { error: result.error } : {}) };
+};
+
+function unavailable(name: string, environmentName: string): never {
+  throw new CredentialStorageError("Cannot access " + name + ". Unlock or enable your OS credential store and retry. For a headless session, supply credentials through environment variables. Plaintext storage requires explicitly setting " + environmentName + "=file.");
+}
+function parseKey(value: string): Buffer {
+  const encoded = value.trim();
+  if (!/^[A-Za-z0-9+/]{43}=$/.test(encoded)) throw new CredentialStorageError("The OS credential key is invalid. Restore access to the original key before using the saved session.");
+  const key = Buffer.from(encoded, "base64");
+  if (key.length !== 32) throw new CredentialStorageError("The OS credential key is invalid.");
+  return key;
+}
+
+/** A small wrapping key avoids OS item-size limits; session files are encrypted
+ * separately so refresh rotation can retain the atomic file/lock transaction. */
+export function nativeCredentialKeyStore(path: string, platform: NodeJS.Platform = process.platform, run: NativeCommand = nativeCommand, environmentName = "CREDENTIAL_STORE"): CredentialKeyStore {
+  const failed = (name: string): never => unavailable(name, environmentName);
+  const identity = createHash("sha256").update(resolve(path)).digest("hex");
+  const service = "typeship.credentials." + identity;
+  const account = "session-key";
+  if (platform === "darwin") {
+    const name = "macOS Keychain";
+    const lookup = () => run("/usr/bin/security", ["find-generic-password", "-s", service, "-a", account, "-w"]);
+    return {
+      name,
+      read() {
+        const result = lookup();
+        if (!result.error && result.status === 44) return null; // errSecItemNotFound
+        if (result.error || result.status !== 0) return failed(name);
+        return parseKey(result.stdout);
+      },
+      write(key) {
+        // security's interactive command stream keeps the key off argv. All
+        // tokens below have a fixed safe alphabet; no shell or user text is run.
+        const input = "add-generic-password -U -s " + service + " -a " + account + " -w " + key.toString("base64") + "\n";
+        const result = run("/usr/bin/security", ["-i"], input);
+        if (result.error || result.status !== 0) return failed(name);
+        // Verify the write: an interactive tool's process status alone is not
+        // sufficient evidence that its command stored the requested item.
+        const saved = this.read();
+        if (!saved || !timingSafeEqual(saved, key)) return failed(name);
+      },
+      remove() {
+        const result = run("/usr/bin/security", ["delete-generic-password", "-s", service, "-a", account]);
+        if (result.error || (result.status !== 0 && result.status !== 44)) failed(name);
+      },
+    };
+  }
+  if (platform === "linux") {
+    const name = "Linux Secret Service (secret-tool)";
+    const attributes = ["service", service, "account", account];
+    return {
+      name,
+      read() {
+        const result = run("/usr/bin/secret-tool", ["lookup", ...attributes]);
+        if (!result.error && result.status === 1 && !result.stderr.trim()) return null;
+        if (result.error || result.status !== 0) return failed(name);
+        return parseKey(result.stdout);
+      },
+      write(key) {
+        const result = run("/usr/bin/secret-tool", ["store", "--label=CLI session encryption key", ...attributes], key.toString("base64"));
+        if (result.error || result.status !== 0) return failed(name);
+        const saved = this.read();
+        if (!saved || !timingSafeEqual(saved, key)) return failed(name);
+      },
+      remove() {
+        const result = run("/usr/bin/secret-tool", ["clear", ...attributes]);
+        if (result.error || result.status !== 0) failed(name);
+      },
+    };
+  }
+  if (platform === "win32") {
+    const name = "Windows DPAPI (current user)";
+    const keyPath = path + ".key";
+    const executable = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    const script = `
+$ErrorActionPreference = 'Stop'
+try {
+  Add-Type -AssemblyName System.Security
+  $payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
+  $bytes = [Convert]::FromBase64String([string]$payload.data)
+  $entropy = [Text.Encoding]::UTF8.GetBytes([string]$payload.service)
+  $scope = [System.Security.Cryptography.DataProtectionScope]::CurrentUser
+  if ($payload.action -eq 'protect') { $result = [System.Security.Cryptography.ProtectedData]::Protect($bytes, $entropy, $scope) }
+  elseif ($payload.action -eq 'unprotect') { $result = [System.Security.Cryptography.ProtectedData]::Unprotect($bytes, $entropy, $scope) }
+  else { exit 1 }
+  [Console]::Out.Write([Convert]::ToBase64String($result))
+  exit 0
+} catch { exit 1 }
+`;
+    const crypt = (action: "protect" | "unprotect", data: string) => {
+      // EncodedCommand contains fixed code only. Sensitive data goes over stdin.
+      const result = run(executable, ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], JSON.stringify({ action, data, service }));
+      if (result.error || result.status !== 0 || !result.stdout.trim()) return failed(name);
+      return result.stdout.trim();
+    };
+    return {
+      name,
+      read() {
+        let wrapped: string;
+        try { wrapped = readFileSync(keyPath, "utf8"); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; return failed(name); }
+        return parseKey(crypt("unprotect", wrapped));
+      },
+      write(key) {
+        const wrapped = crypt("protect", key.toString("base64"));
+        const temporary = keyPath + "." + randomBytes(16).toString("hex") + ".tmp";
+        try {
+          writeFileSync(temporary, wrapped, { mode: 0o600, flag: "wx", flush: true });
+          renameSync(temporary, keyPath);
+        } finally { rmSync(temporary, { force: true }); }
+        const saved = this.read();
+        if (!saved || !timingSafeEqual(saved, key)) return failed(name);
+      },
+      remove() { rmSync(keyPath, { force: true }); },
+    };
+  }
+  return { name: "OS credential storage", read: () => failed("OS credential storage on this platform"), write: () => failed("OS credential storage on this platform"), remove: () => failed("OS credential storage on this platform") };
+}
+
+export function encryptedCredentialCodec(path: string, keyStore: CredentialKeyStore): CredentialCodec {
+  const associatedData = Buffer.from("cli-credentials-v1:" + resolve(path));
+  const key = (create: boolean) => {
+    const saved = keyStore.read();
+    if (saved) return saved;
+    if (!create || existsSync(path)) throw new CredentialStorageError("The encryption key for this saved session is missing. Restore the original OS credential store, or run logout --local to remove the saved encrypted session before logging in again.");
+    const generated = randomBytes(32);
+    keyStore.write(generated);
+    return generated;
+  };
+  return {
+    name: keyStore.name,
+    prepare() { key(true); },
+    encode(plaintext) {
+      const nonce = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", key(true), nonce);
+      cipher.setAAD(associatedData);
+      const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+      return JSON.stringify({ version: 1, algorithm: "aes-256-gcm", nonce: nonce.toString("base64"), tag: cipher.getAuthTag().toString("base64"), ciphertext: ciphertext.toString("base64") });
+    },
+    decode(encoded) {
+      let envelope: { version?: unknown; algorithm?: unknown; nonce?: unknown; tag?: unknown; ciphertext?: unknown };
+      try { envelope = JSON.parse(encoded); } catch { throw new CredentialStorageError("Saved encrypted credentials are damaged. Restore the credential file before logging in again."); }
+      if (!envelope || envelope.version !== 1 || envelope.algorithm !== "aes-256-gcm" || typeof envelope.nonce !== "string" || typeof envelope.tag !== "string" || typeof envelope.ciphertext !== "string") throw new CredentialStorageError("Saved encrypted credentials use an invalid format.");
+      const secret = key(false);
+      try {
+        const nonce = Buffer.from(envelope.nonce, "base64"), tag = Buffer.from(envelope.tag, "base64");
+        if (nonce.length !== 12 || tag.length !== 16) throw new Error();
+        const decipher = createDecipheriv("aes-256-gcm", secret, nonce);
+        decipher.setAAD(associatedData); decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, "base64")), decipher.final()]).toString("utf8");
+      } catch { throw new CredentialStorageError("Saved credentials could not be authenticated. Restore the original credential file and OS key; do not reuse this session."); }
+    },
+  };
+}
+
+/** OS protection is the default. Plaintext storage is an explicit, separate
+ * store for environments where the owner accepts that tradeoff. Never migrate
+ * or fall back silently when an OS service is unavailable. */
+export function createCredentialStore(directory: string, mode: string = "os", environmentName = "CREDENTIAL_STORE"): FileCredentialStore {
+  if (mode === "file") return new FileCredentialStore(join(directory, "credentials.json"));
+  if (mode !== "os") throw new CredentialStorageError(environmentName + " must be os or file.");
+  const path = join(directory, "credentials.enc");
+  return new FileCredentialStore(path, 40_000, encryptedCredentialCodec(path, nativeCredentialKeyStore(path, process.platform, nativeCommand, environmentName)));
+}

package/src/docs.ts

@@ -55,6 +55,144 @@ function safeHttpUrl(value: string | null): string | null {
   }
 }
 
+export interface GuideMatch {
+  title: string;
+  section: string | null;
+  /** Kept for callers that displayed the original heading-only results. */
+  heading: string;
+  excerpt: string;
+  url: string;
+}
+
+interface GuidePage { title: string; url: string; description: string }
+
+/** Links in an index follow URL semantics, including site-root relative links. */
+function docsLink(base: string | null, indexUrl: string | null, value: string): string | null {
+  const index = resolveDocsContentUrl(base, indexUrl, "llms.txt");
+  if (!index) return null;
+  try { return resolveDocsContentUrl(base, indexUrl, new URL(value, index).toString()); }
+  catch { return null; }
+}
+
+export function docsIndexPages(index: string | null, base: string | null, indexUrl: string | null): GuidePage[] {
+  const pages = new Map<string, GuidePage>();
+  for (const line of (index ?? "").split("\n")) {
+    for (const match of line.matchAll(/\[([^\]]+)\]\(([^\s)]+)\)/g)) {
+      const url = docsLink(base, indexUrl, match[2]!);
+      if (!url || /\/llms(?:-full)?\.txt(?:[?#]|$)/.test(url)) continue;
+      const description = line.slice(match.index! + match[0].length).replace(/^\s*:\s*/, "").trim();
+      if (!pages.has(url)) pages.set(url, { title: match[1]!, url, description: cleanDocsText(description) });
+    }
+  }
+  return [...pages.values()];
+}
+
+function cleanDocsText(text: string): string {
+  return text.replace(/^\s*(?:>\s*)+/, "").replace(/!?\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/<[^>]*>/g, "").replace(/[*`]/g, "").replace(/^\s*[-*>]\s*/, "").replace(/\s+/g, " ").trim();
+}
+
+function docsTerms(query: string): string[] {
+  return [...new Set(query.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length >= 2))];
+}
+
+/** Rank sections, then keep the strongest section of each real page. A heading
+ * match must have content: blank lines, fences, and source markers are not hits. */
+export function searchGuidePages(
+  prose: string | null, index: string | null, base: string | null, indexUrl: string | null, query: string,
+): GuideMatch[] {
+  const pages = docsIndexPages(index, base, indexUrl);
+  const terms = docsTerms(query);
+  if (terms.length === 0) return [];
+  const phrase = query.trim().toLowerCase();
+  const candidates: { match: GuideMatch; score: number }[] = [];
+  const add = (title: string, section: string | null, url: string | null, lines: string[]) => {
+    if (!url) return;
+    const content = lines.map(cleanDocsText).filter((line) => line.length > 0);
+    if (content.length === 0) return;
+    const heading = (title + " " + (section ?? "")).toLowerCase();
+    const body = content.join(" ").toLowerCase();
+    const matched = terms.filter((term) => heading.includes(term) || body.includes(term));
+    if (matched.length === 0) return;
+    const score = matched.length * 10 + (matched.length === terms.length ? 50 : 0)
+      + (heading.includes(phrase) ? 35 : body.includes(phrase) ? 25 : 0)
+      + (title.toLowerCase().includes(phrase) ? 25 : 0)
+      + terms.filter((term) => title.toLowerCase().includes(term)).length * 5
+      + terms.filter((term) => heading.includes(term)).length * 5
+      + terms.filter((term) => section?.toLowerCase().includes(term)).length * 3;
+    const excerpt = [...content].sort((a, b) => {
+      const rank = (line: string) => terms.filter((term) => line.toLowerCase().includes(term)).length;
+      return rank(b) - rank(a);
+    })[0]!.slice(0, 240);
+    candidates.push({ match: { title, section, heading: section ?? title, excerpt, url }, score });
+  };
+  let title = "";
+  let section: string | null = null;
+  let url: string | null = null;
+  let lines: string[] = [];
+  let fence: string | null = null;
+  const flush = () => { add(title, section, url, lines); lines = []; };
+  for (const line of (prose ?? "").split("\n")) {
+    const fenced = line.trim().match(/^(`{3,}|~{3,})/);
+    if (fenced) { if (fence === null) fence = fenced[1]![0]!; else if (fenced[1]![0] === fence) fence = null; continue; }
+    if (fence !== null) { if (line.trim()) lines.push(line); continue; }
+    const heading = line.match(/^(#{1,6})\s+(.+?)\s*#*$/);
+    if (heading) {
+      flush();
+      if (heading[1] === "#") {
+        title = cleanDocsText(heading[2]!);
+        section = null;
+        const link = heading[2]!.match(/\[[^\]]+\]\(([^\s)]+)\)/);
+        url = link ? docsLink(base, indexUrl, link[1]!) : pages.find((page) => page.title.toLowerCase() === title.toLowerCase())?.url ?? null;
+      } else section = cleanDocsText(heading[2]!);
+      continue;
+    }
+    const source = line.match(/^Source:\s*(?:\[[^\]]*\]\()?<?(https?:\/\/[^\s)>]+)>?\)?\s*$/i);
+    if (source) {
+      url = docsLink(base, indexUrl, source[1]!);
+      continue;
+    }
+    // Markdown callouts are blockquotes; keep their text for search and excerpts.
+    if (!line.trim() || /^\s*(?:---+|\|[\s:|-]+\|)\s*$/.test(line) || /^\s*</.test(line)) continue;
+    lines.push(line);
+  }
+  flush();
+  // An index is useful without llms-full.txt, and may include additional pages.
+  const described = new Set(candidates.map(({ match }) => match.url.replace(/\.md(?=[?#]|$)/, "")));
+  for (const page of pages) {
+    if (!described.has(page.url.replace(/\.md(?=[?#]|$)/, ""))) add(page.title, null, page.url, [page.description || page.title]);
+  }
+  candidates.sort((a, b) => b.score - a.score || a.match.title.localeCompare(b.match.title) || a.match.url.localeCompare(b.match.url));
+  const distinct = new Map<string, GuideMatch>();
+  for (const { match } of candidates) {
+    const key = match.url.replace(/\.md(?=[?#]|$)/, "");
+    if (!distinct.has(key)) distinct.set(key, match);
+  }
+  return [...distinct.values()];
+}
+
+export async function searchConnectedGuides(
+  base: string | null, indexUrl: string | null, fetchText: (path: string) => Promise<string | null>, query: string,
+): Promise<{ guides: GuideMatch[]; status: "not_configured" | "unavailable" | "ok" }> {
+  if (!base && !indexUrl) return { guides: [], status: "not_configured" };
+  const [index, prose] = await Promise.all([fetchText("llms.txt"), fetchText("llms-full.txt")]);
+  return { guides: searchGuidePages(prose, index, base, indexUrl, query), status: index === null && prose === null ? "unavailable" : "ok" };
+}
+
+export function docsReadTarget(index: string | null, base: string | null, indexUrl: string | null, page: string): string {
+  if (/^https?:\/\//.test(page)) return page;
+  const pages = docsIndexPages(index, base, indexUrl);
+  const term = page.toLowerCase();
+  const exact = pages.find((item) => item.title.toLowerCase() === term || new URL(item.url).pathname.toLowerCase() === term);
+  if (exact) return exact.url;
+  const matches = pages.filter((item) => item.url.toLowerCase().includes(term));
+  return matches.length === 1 ? matches[0]!.url : page;
+}
+
+/** One shell argument, including URLs with quotes, query strings, or fragments. */
+export function docsReadCommand(bin: string, url: string): string {
+  return bin + " docs read '" + url.replace(/'/g, "'\\''") + "'";
+}
+
 /** Markdown-preferred fetch with same-origin redirects, one deadline, and a
  * streaming byte cap. Returns null for every invalid or failed read. */
 export async function fetchDocsText(url: string): Promise<string | null> {

package/src/errors.ts

@@ -4,7 +4,7 @@
 import { ApiError, type ResponseMeta } from "./core/http.js";
 import type { ErrorModel, ErrorModelRead } from "./types.js";
 
-export { ApiError, TransportError, UnexpectedApiError, ValidationError, type Violation, unwrap } from "./core/http.js";
+export { ApiError, ResponseParseError, TransportError, UnexpectedApiError, ValidationError, type Violation, unwrap } from "./core/http.js";
 
 /**
  * The request body, Definition source, target selection, or package name is invalid.
@@ -36,6 +36,16 @@ export class ForbiddenError extends ApiError<403, ErrorModelRead> {
   }
 }
 
+/**
+ * The key identifies changed intent.
+ * Raised for HTTP 409 responses.
+ */
+export class ConflictError extends ApiError<409, ErrorModelRead> {
+  constructor(body: ErrorModelRead, response: ResponseMeta) {
+    super("The key identifies changed intent.", 409, body, response);
+  }
+}
+
 /**
  * Spec exceeds the 10MB limit.
  * Raised for HTTP 413 responses.
@@ -57,12 +67,13 @@ export class UnprocessableEntityError extends ApiError<422, ErrorModelRead> {
 }
 
 /**
- * Too many requests. Wait for Retry-After before retrying.
+ * Too many requests, or an identical write is still in progress. Wait for Retry-After before
+ * retrying.
  * Raised for HTTP 429 responses.
  */
 export class RateLimitedError extends ApiError<429, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("Too many requests. Wait for Retry-After before retrying.", 429, body, response);
+    super("Too many requests, or an identical write is still in progress. Wait for Retry-After before retrying.", 429, body, response);
   }
 }
 
@@ -87,22 +98,12 @@ export class PaymentRequiredError extends ApiError<402, ErrorModelRead> {
 }
 
 /**
- * The Idempotency-Key was already used with different request parameters.
- * Raised for HTTP 409 responses.
- */
-export class ConflictError extends ApiError<409, ErrorModelRead> {
-  constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The Idempotency-Key was already used with different request parameters.", 409, body, response);
-  }
-}
-
-/**
- * The original idempotent request is temporarily unavailable.
+ * Project setup failed unexpectedly; the key reservation is released.
  * Raised for HTTP 500 responses.
  */
 export class InternalServerError extends ApiError<500, ErrorModelRead> {
   constructor(body: ErrorModelRead, response: ResponseMeta) {
-    super("The original idempotent request is temporarily unavailable.", 500, body, response);
+    super("Project setup failed unexpectedly; the key reservation is released.", 500, body, response);
   }
 }
 
@@ -115,3 +116,13 @@ export class NotFoundError extends ApiError<404, ErrorModelRead> {
     super("No such resource in this account.", 404, body, response);
   }
 }
+
+/**
+ * The Project was saved, but an obsolete release pull request could not be retired.
+ * Raised for HTTP 502 responses.
+ */
+export class BadGatewayError extends ApiError<502, ErrorModelRead> {
+  constructor(body: ErrorModelRead, response: ResponseMeta) {
+    super("The Project was saved, but an obsolete release pull request could not be retired.", 502, body, response);
+  }
+}