@typeship-ax/mcp 0.6.0 → 0.9.1

package/dist/credential-storage.js

@@ -0,0 +1,207 @@
+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 } from "./oauth-session.js";
+const 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, environmentName) {
+    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) {
+    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, platform = process.platform, run = nativeCommand, environmentName = "CREDENTIAL_STORE") {
+    const failed = (name) => 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, data) => {
+            // 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;
+                try {
+                    wrapped = readFileSync(keyPath, "utf8");
+                }
+                catch (error) {
+                    if (error.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, keyStore) {
+    const associatedData = Buffer.from("cli-credentials-v1:" + resolve(path));
+    const key = (create) => {
+        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;
+            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, mode = "os", environmentName = "CREDENTIAL_STORE") {
+    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/dist/dates.d.ts

@@ -15,8 +15,6 @@
  * validates absolute values. Zero dependencies.
  */
 export type DateKind = "date" | "date-time";
-/** The forms a date-shaped argument accepts, for descriptions and help. */
-export declare const RELATIVE_DATE_HINT = "Accepts ISO 8601 or a relative form: -P7D, -7d, 7 days ago, today, now.";
 /**
  * Resolve a relative date expression. `null` means "not a relative form,
  * pass the value through"; `{ error }` means it looked relative but is

package/dist/dates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../src/dates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAa5C,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,4EAA4E,CAAC;AAoC5G;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,GAAE,IAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAmC/H;AAcD,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAE3D"}
+{"version":3,"file":"dates.d.ts","sourceRoot":"","sources":["../src/dates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAiD5C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,GAAE,IAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAmC/H;AAcD,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAE3D"}

package/dist/dates.js

@@ -24,7 +24,6 @@ const UNIT_MS = {
 const CALENDAR_UNITS = new Set(["mo", "month", "y", "yr", "year"]);
 const HINT = "Use a signed form: -7d or -P7D for seven days ago, +7d or +P7D for seven days ahead; or an absolute ISO 8601 value.";
 /** The forms a date-shaped argument accepts, for descriptions and help. */
-export const RELATIVE_DATE_HINT = "Accepts ISO 8601 or a relative form: -P7D, -7d, 7 days ago, today, now.";
 function shift(base, amount, unit) {
     const d = new Date(base.getTime());
     if (CALENDAR_UNITS.has(unit)) {

package/dist/docs.d.ts

@@ -0,0 +1,36 @@
+/** Shared documentation-fetch boundary for generated CLI and MCP surfaces. */
+export declare const MAX_DOCS_TEXT_BYTES = 2000000;
+export declare function resolveDocsPageUrl(base: string | null, pathOrFile: string): string | null;
+/** Resolve conventional docs files while honoring an explicitly configured
+ * llms.txt location. Guide links may live on either the docs-site origin or
+ * the index origin; no other origin is accepted. */
+export declare function resolveDocsContentUrl(base: string | null, indexUrl: string | null, pathOrFile: string): 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;
+}
+export declare function docsIndexPages(index: string | null, base: string | null, indexUrl: string | null): GuidePage[];
+/** 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 declare function searchGuidePages(prose: string | null, index: string | null, base: string | null, indexUrl: string | null, query: string): GuideMatch[];
+export declare function searchConnectedGuides(base: string | null, indexUrl: string | null, fetchText: (path: string) => Promise<string | null>, query: string): Promise<{
+    guides: GuideMatch[];
+    status: "not_configured" | "unavailable" | "ok";
+}>;
+export declare function docsReadTarget(index: string | null, base: string | null, indexUrl: string | null, page: string): string;
+/** One shell argument, including URLs with quotes, query strings, or fragments. */
+export declare function docsReadCommand(bin: string, url: string): string;
+/** Markdown-preferred fetch with same-origin redirects, one deadline, and a
+ * streaming byte cap. Returns null for every invalid or failed read. */
+export declare function fetchDocsText(url: string): Promise<string | null>;
+export {};
+//# sourceMappingURL=docs.d.ts.map

package/dist/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAE9E,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAE7C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYzF;AAED;;oDAEoD;AACpD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAkBf;AAcD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,UAAU,SAAS;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AAUvE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,CAW9G;AAUD;oFACoF;AACpF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GACtG,UAAU,EAAE,CAqEd;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,GAC/G,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAAC,MAAM,EAAE,gBAAgB,GAAG,aAAa,GAAG,IAAI,CAAA;CAAE,CAAC,CAIpF;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQvH;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;wEACwE;AACxE,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyCvE"}

package/dist/docs.js

@@ -0,0 +1,258 @@
+/** Shared documentation-fetch boundary for generated CLI and MCP surfaces. */
+export const MAX_DOCS_TEXT_BYTES = 2_000_000;
+export function resolveDocsPageUrl(base, pathOrFile) {
+    if (base === null)
+        return null;
+    try {
+        const baseUrl = new URL(base);
+        if ((baseUrl.protocol !== "https:" && baseUrl.protocol !== "http:") || baseUrl.username || baseUrl.password)
+            return null;
+        const target = /^https?:\/\//.test(pathOrFile)
+            ? new URL(pathOrFile)
+            : new URL(pathOrFile.replace(/^\/+/, ""), baseUrl.toString().replace(/\/+$/, "") + "/");
+        return target.origin === baseUrl.origin && !target.username && !target.password ? target.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve conventional docs files while honoring an explicitly configured
+ * llms.txt location. Guide links may live on either the docs-site origin or
+ * the index origin; no other origin is accepted. */
+export function resolveDocsContentUrl(base, indexUrl, pathOrFile) {
+    const exactIndex = safeHttpUrl(indexUrl);
+    if (pathOrFile === "llms.txt" && exactIndex)
+        return exactIndex;
+    if (pathOrFile === "llms-full.txt" && exactIndex) {
+        try {
+            return new URL("llms-full.txt", exactIndex).toString();
+        }
+        catch {
+            return null;
+        }
+    }
+    const primary = resolveDocsPageUrl(base, pathOrFile);
+    if (primary)
+        return primary;
+    if (!exactIndex)
+        return null;
+    try {
+        const target = /^https?:\/\//.test(pathOrFile)
+            ? new URL(pathOrFile)
+            : new URL(pathOrFile.replace(/^\/+/, ""), exactIndex);
+        const allowed = new URL(exactIndex);
+        return target.origin === allowed.origin && !target.username && !target.password ? target.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function safeHttpUrl(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = new URL(value);
+        return (parsed.protocol === "https:" || parsed.protocol === "http:") && !parsed.username && !parsed.password
+            ? parsed.toString()
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Links in an index follow URL semantics, including site-root relative links. */
+function docsLink(base, indexUrl, value) {
+    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, base, indexUrl) {
+    const pages = new Map();
+    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) {
+    return text.replace(/^\s*(?:>\s*)+/, "").replace(/!?\[([^\]]+)\]\([^)]*\)/g, "$1").replace(/<[^>]*>/g, "").replace(/[*`]/g, "").replace(/^\s*[-*>]\s*/, "").replace(/\s+/g, " ").trim();
+}
+function docsTerms(query) {
+    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, index, base, indexUrl, query) {
+    const pages = docsIndexPages(index, base, indexUrl);
+    const terms = docsTerms(query);
+    if (terms.length === 0)
+        return [];
+    const phrase = query.trim().toLowerCase();
+    const candidates = [];
+    const add = (title, section, url, lines) => {
+        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) => 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 = null;
+    let url = null;
+    let lines = [];
+    let fence = 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();
+    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, indexUrl, fetchText, query) {
+    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, base, indexUrl, page) {
+    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, url) {
+    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) {
+    try {
+        const initial = new URL(url);
+        if ((initial.protocol !== "https:" && initial.protocol !== "http:") || initial.username || initial.password)
+            return null;
+        const allowedOrigin = initial.origin;
+        let current = initial.toString();
+        const signal = AbortSignal.timeout(10_000);
+        for (let redirects = 0; redirects <= 3; redirects += 1) {
+            const response = await fetch(current, { headers: { Accept: "text/markdown, text/plain, */*" }, redirect: "manual", signal });
+            if (response.status >= 300 && response.status < 400) {
+                const location = response.headers.get("location");
+                if (!location || redirects === 3)
+                    return null;
+                const next = new URL(location, current);
+                if (next.origin !== allowedOrigin || next.username || next.password)
+                    return null;
+                current = next.toString();
+                continue;
+            }
+            if (!response.ok)
+                return null;
+            const declared = Number(response.headers.get("content-length"));
+            if (Number.isFinite(declared) && declared > MAX_DOCS_TEXT_BYTES)
+                return null;
+            if (!response.body)
+                return "";
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let bytes = 0;
+            let text = "";
+            for (;;) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                bytes += chunk.value.byteLength;
+                if (bytes > MAX_DOCS_TEXT_BYTES) {
+                    await reader.cancel();
+                    return null;
+                }
+                text += decoder.decode(chunk.value, { stream: true });
+            }
+            return text + decoder.decode();
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/errors.d.ts

@@ -1,81 +1,89 @@
 import { ApiError, type ResponseMeta } from "./core/http.js";
-import type { ErrorModel } from "./types.js";
-export { ApiError, GraphQLRequestError, TransportError, UnexpectedApiError, ValidationError, type Violation, unwrap } from "./core/http.js";
+import type { ErrorModelRead } from "./types.js";
+export { ApiError, ResponseParseError, TransportError, UnexpectedApiError, ValidationError, type Violation, unwrap } from "./core/http.js";
 /**
- * The request body, specification source, output selection, or package name is invalid.
+ * The request body, Definition source, target selection, or package name is invalid.
  * Raised for HTTP 400 responses.
  */
-export declare class BadRequestError extends ApiError<400, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class BadRequestError extends ApiError<400, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 /**
  * Missing, invalid, expired, or revoked credentials.
  * Raised for HTTP 401 responses.
  */
-export declare class UnauthorizedError extends ApiError<401, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class UnauthorizedError extends ApiError<401, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 /**
  * The credentials are valid but cannot act on the requested organization.
  * Raised for HTTP 403 responses.
  */
-export declare class ForbiddenError extends ApiError<403, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class ForbiddenError extends ApiError<403, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
+}
+/**
+ * The key identifies changed intent.
+ * Raised for HTTP 409 responses.
+ */
+export declare class ConflictError extends ApiError<409, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 /**
  * Spec exceeds the 10MB limit.
  * Raised for HTTP 413 responses.
  */
-export declare class PayloadTooLargeError extends ApiError<413, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class PayloadTooLargeError extends ApiError<413, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 /**
- * The spec could not be understood.
+ * The Definition could not be resolved or understood.
  * Raised for HTTP 422 responses.
  */
-export declare class UnprocessableEntityError extends ApiError<422, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class UnprocessableEntityError extends ApiError<422, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 /**
- * 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 declare class RateLimitedError extends ApiError<429, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class RateLimitedError extends ApiError<429, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 /**
  * Unexpected error.
  * Raised for "default" responses.
  */
-export declare class ApiResponseError extends ApiError<number, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class ApiResponseError extends ApiError<number, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 /**
- * The plan does not include another project or the requested output configuration.
+ * The plan does not include another project or the requested target configuration.
  * Raised for HTTP 402 responses.
  */
-export declare class PaymentRequiredError extends ApiError<402, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class PaymentRequiredError extends ApiError<402, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 /**
- * The Idempotency-Key was already used with different request parameters.
- * Raised for HTTP 409 responses.
- */
-export declare class ConflictError extends ApiError<409, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
-}
-/**
- * The original idempotent request is temporarily unavailable.
+ * Project setup failed unexpectedly; the key reservation is released.
  * Raised for HTTP 500 responses.
  */
-export declare class InternalServerError extends ApiError<500, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class InternalServerError extends ApiError<500, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 /**
  * No such resource in this account.
  * Raised for HTTP 404 responses.
  */
-export declare class NotFoundError extends ApiError<404, ErrorModel> {
-    constructor(body: ErrorModel, response: ResponseMeta);
+export declare class NotFoundError extends ApiError<404, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
+}
+/**
+ * The Project was saved, but an obsolete release pull request could not be retired.
+ * Raised for HTTP 502 responses.
+ */
+export declare class BadGatewayError extends ApiError<502, ErrorModelRead> {
+    constructor(body: ErrorModelRead, response: ResponseMeta);
 }
 //# sourceMappingURL=errors.d.ts.map