@zackbart/connecta 0.34.0 → 0.35.0

package/dist/providers/github/api.js

@@ -0,0 +1,150 @@
+// GitHub's finite REST complement. App JWT discovery and minting remain private
+// auxiliary requests; rejected installation tokens renew on the next call only.
+import { Effect, Schema } from "effect";
+import { indexedVendor } from "../_shared/rest/kit.js";
+import { githubIndex, GITHUB_HATCH } from "./lib/discovery.js";
+import { githubSafety } from "./safety.js";
+import { INTERNAL_READS, MERGE, READ_PERMISSIONS, RELEASE_PERMISSIONS } from "./lib/operations.js";
+import { errorMeanings } from "../../http/errors.js";
+import { ConnectorCallError } from "../../errors.js";
+import { guardedClient } from "../../http/client.js";
+import { captureClassifierFacts, StatusFailure } from "../../http/errors.js";
+import { resultSafety } from "../../http/safety.js";
+import { connect, get, operations } from "../../http/vendor.js";
+const repository = { owner: Schema.String, repo: Schema.String };
+const success = Schema.Unknown;
+export const GitHubApi = indexedVendor("GitHub", githubIndex, [
+    get("repository", "/repos/:owner/:repo", { params: repository, success }),
+]);
+function rateLimited(status, retry, remaining) {
+    return status === 429 || (status === 403 && (retry !== undefined || remaining === 0));
+}
+export function rejectedToken(status, headers) {
+    if (status !== 403)
+        return status === 401;
+    const numbers = captureClassifierFacts(undefined, errors, headers)?.numbers;
+    return !rateLimited(status, numbers?.["retryAfterMs"], numbers?.["remaining"]);
+}
+const AUTH = "Verify the GitHub App key, installation, repository selection and required permissions.";
+const FAILED = "The GitHub API request failed; downstream error text is withheld.";
+function rate(input) {
+    if (!rateLimited(input.status, input.retryAfterMs, input.numbers["remaining"]))
+        return undefined;
+    const wait = input.retryAfterMs ?? input.numbers["resetAfterMs"];
+    return {
+        code: "rate_limited",
+        retryable: true,
+        ...(wait === undefined ? {} : { retryAfterMs: wait }),
+        words: () => "GitHub rate limit reached.",
+        advice: " Honor the retry timing before trying again.",
+    };
+}
+export const errors = {
+    numericFacts: {
+        retryAfterMs: {
+            header: "retry-after",
+            format: "retry-after",
+            review: "HTTP Retry-After delay for failure recovery.",
+        },
+        remaining: {
+            header: "x-ratelimit-remaining",
+            review: "GitHub classifies a 403 with no remaining requests as rate limited.",
+        },
+        resetAfterMs: {
+            header: "x-ratelimit-reset",
+            format: "epoch-seconds",
+            review: "GitHub rate-limit reset time in epoch seconds.",
+        },
+    },
+    provider: "GitHub",
+    facts: (body) => ({
+        merged: body && typeof body === "object" && "merged" in body && body.merged === false ? false : undefined,
+    }),
+    factVocabulary: { merged: [false] },
+    meanings: {
+        unknownId: "connector_call_failed",
+        provesAbsence: false,
+        conflicts: [
+            "HTTP 409 is a conflict; a merged:false response and the expected-SHA/same-repository preflight also refuse a merge",
+        ],
+    },
+    classify: [
+        ({ operation, facts }) => operation.method === "PUT" &&
+            operation.template === "/repos/{owner}/{repo}/pulls/{pull_number}/merge" &&
+            facts["merged"] === false
+            ? {
+                code: "conflict",
+                retryable: false,
+                words: () => "GitHub reported that the pull request was not merged. Read its current state before another attempt.",
+            }
+            : undefined,
+        rate,
+    ],
+    detail: ({ status: code }) => code === 401 || code === 403
+        ? AUTH
+        : code === 409
+            ? "GitHub reported a conflict. Read the current state."
+            : code === 404
+                ? "GitHub returned 404; the resource may be absent or inaccessible to this installation."
+                : FAILED,
+    statuses: {
+        401: () => ({ code: "auth_required", retryable: false }),
+        403: () => ({ code: "auth_required", retryable: false }),
+        404: () => ({ code: "connector_call_failed", retryable: false }),
+        409: () => ({ code: "conflict", retryable: false, advice: " before resubmitting" }),
+    },
+    bodyFailures: {
+        review: "GitHub failure classification uses only status and declared numeric headers; failed success reads disclose no raw cause.",
+        statusOnly: [],
+        readFailed: "GitHub's response body could not be read completely.",
+    },
+    unreadable: "GitHub returned malformed JSON; response text is withheld.",
+};
+export function githubConnection() {
+    const safety = resultSafety({
+        reviewed: {
+            refusal: (op) => githubSafety.refusal(op.method, op.template),
+            resolve: (method, path) => {
+                const { op } = githubIndex.resolve(method, path);
+                const key = `${op.method} ${op.path}`;
+                if (!READ_PERMISSIONS[key] && !RELEASE_PERMISSIONS[key] && !INTERNAL_READS.has(key) && key !== MERGE)
+                    throw new ConnectorCallError("invalid_args", "This GitHub operation is not exposed by the connection.");
+                return { method: op.method, template: op.path };
+            },
+            redact: (data, op) => githubSafety.redact(data, op.method, op.template),
+            withholdsErrors: () => true,
+        },
+        sensitiveFields: { names: [], choice: "drop" },
+    });
+    return connect(GitHubApi, guardedClient({
+        provider: "GitHub",
+        baseUrl: "https://api.github.com",
+        maxResponseBytes: 4 * 1024 * 1024,
+        headers: {
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "connecta",
+        },
+        authenticate: Effect.succeed({}),
+    }), {
+        errors,
+        safety,
+        inBandRefusals: true,
+        result: (body, answer) => answer.operation.method === "PUT" &&
+            answer.operation.template === "/repos/{owner}/{repo}/pulls/{pull_number}/merge" &&
+            body &&
+            typeof body === "object" &&
+            "merged" in body &&
+            body.merged === false
+            ? Effect.fail(new StatusFailure({ status: answer.status, headers: answer.headers, body, operation: answer.operation }))
+            : Effect.succeed(answer.bodyFormat === "empty" ? undefined : body),
+    });
+}
+export const kit = {
+    operations: operations(GitHubApi),
+    pageSize: { default: 30, max: 100 },
+    hatch: { name: GITHUB_HATCH.name, verdicts: GITHUB_HATCH.verdicts, paging: "argument" },
+    errors: errorMeanings(errors),
+    idempotencyKey: false,
+    refusesWithheld: true,
+};

package/dist/providers/github/index.d.ts

@@ -1,9 +1,8 @@
 import { type ProviderOptions } from "../../provider.js";
-import { type GitHubApp } from "./auth.js";
-import { type GitHubScope } from "./scope.js";
-export type { GitHubApp } from "./auth.js";
-export type { GitHubScope } from "./scope.js";
-export declare const GITHUB_MCP_ENDPOINT = "https://api.githubcopilot.com/mcp/";
+import { type GitHubApp } from "./lib/auth.js";
+import { type GitHubScope } from "./lib/scope.js";
+export type { GitHubApp } from "./lib/auth.js";
+export type { GitHubScope } from "./lib/scope.js";
 export interface GitHubOptions extends ProviderOptions {
     app: GitHubApp;
     /** Mixed org and exact repository grants, with explicit access. */

package/dist/providers/github/index.js

@@ -1,37 +1,22 @@
-import { remoteMcp } from "../../connectors/remote-mcp.js";
 import { array, keys, optionsOf } from "../../config-schema.js";
 import { ConnectorCallError } from "../../errors.js";
-import { redactSentSecrets } from "../../sent-secrets.js";
+import { delegatesEachCall, knownProviderFailure } from "../../provider-call.js";
 import { defineProvider, PROVIDER_COMMON } from "../../provider.js";
-import { AppAuth } from "./auth.js";
-import { HOSTED_CLASSIFICATION, HOSTED_ROUTES, hostedTarget } from "./hosted.js";
-import { restConnector } from "./rest.js";
-import { parseScopes, ScopePolicy } from "./scope.js";
+import { kit } from "./api.js";
+import { AppAuth } from "./lib/auth.js";
+import { restConnector } from "./tools.js";
+import { parseScopes, ScopePolicy } from "./lib/scope.js";
 import { skill } from "./skill.generated.js";
-export const GITHUB_MCP_ENDPOINT = "https://api.githubcopilot.com/mcp/";
-const CLASSIFICATION = {
-    unlisted: "hide",
-    tools: {
-        ...HOSTED_CLASSIFICATION.tools,
-        list_scopes: "read",
-        search_scoped: "read",
-        create_release: "write",
-        update_release: "destructive",
-        delete_release: "destructive",
-        merge_pull_request: "destructive",
-    },
-};
 /** One GitHub App, multiple owner installations, explicit org/repo grants. */
 export const github = defineProvider({
     name: "github",
     title: "GitHub",
-    kind: "composed",
+    kind: "api",
     skill,
-    classify: CLASSIFICATION,
+    kit,
     bundle: {
-        baselineGzip: 164063,
-        maxGzip: 224063,
-        note: "./providers/github initial measured baseline includes the hosted MCP SDK plus portable GitHub App signing, exact routing and REST complements; cap retains the existing 60,000-byte provider headroom policy.",
+        baselineGzip: 451137,
+        note: "./providers/github merged step-2 snapshot measures 451,137 B gzip standalone before recording these bundle facts (#703), Node 26.12.0 with zlib-ng 1.3.1, scripts/bundle-size.mjs. The complete immutable 1,204-operation index is retained. The same-toolchain pre-change probe was 335,233 B; growth is approximately 115 KB, below the approved 300 KB gate. This entry includes the shared Effect provider kit, paid once per deployment; standalone provider sizes are not additive. Provider entries are reported, not capped (#899).",
     },
     options: optionsOf()({
         ...PROVIDER_COMMON,
@@ -40,45 +25,23 @@ export const github = defineProvider({
     }),
     create(id, options, provider) {
         if (options.authScope === "personal")
-            throw new Error("shared GitHub App identity; per-user OAuth attribution is planned separately for 0.29.");
+            throw new Error("shared GitHub App identity; per-user OAuth attribution is planned separately.");
         const policy = new ScopePolicy(parseScopes(options.scopes));
         const auth = new AppAuth(options.app, policy);
         const rest = restConnector(id, auth, policy);
+        // Delegation invokes these captured functions with Reflect.apply, never
+        // through a property or a function's own `call`.
+        const restCall = rest.callTool;
         const usageGuide = provider.usageGuide({
-            context: [`Act as the GitHub App. Reachable configuration: ${policy.summary()}.`, `Purpose: ${options.purpose}`],
-            summary: "GitHub App scopes, installation routing, confined search and workflow-file limits.",
+            context: [
+                `Act as the GitHub App. Reachable configuration: ${policy.summary()}.`,
+                `Purpose: ${options.purpose}`,
+                "The App identity is already configured. Installation access is resolved on use; ask the operator to repair configuration only after an auth failure.",
+                ...(options.readOnly === true ? ["This connection is read-only; every write is refused."] : []),
+            ],
+            summary: "GitHub App repository reads, scoped data search, release writes and guarded merges.",
             required: true,
         });
-        // Each operation owns its token-bound client, transport and callback.
-        // It closes them before returning; no shared header or client mutation.
-        const hosted = (token, classify = HOSTED_CLASSIFICATION) => remoteMcp(id, {
-            url: GITHUB_MCP_ENDPOINT,
-            requireHttps: true,
-            redirects: "none",
-            classify,
-            auth: {
-                type: "request",
-                token: async () => token,
-                headers: {
-                    "X-MCP-Toolsets": "repos,git,issues,pull_requests,actions,labels",
-                    "X-MCP-Tools": Object.keys(HOSTED_ROUTES).join(","),
-                },
-            },
-        });
-        const withHosted = async (token, ctx, run) => {
-            const client = hosted(token);
-            try {
-                return await run(client);
-            }
-            catch (error) {
-                if (error instanceof ConnectorCallError && error.code === "auth_required")
-                    await auth.rejectToken(token);
-                throw redactSentSecrets(ctx, error);
-            }
-            finally {
-                await client.closeScope?.(ctx);
-            }
-        };
         const credential = options.app.privateKey === undefined
             ? {
                 label: "GitHub App private key",
@@ -86,55 +49,35 @@ export const github = defineProvider({
                 fields: [{ name: "privateKey", label: "Private key PEM", inputType: "password" }],
             }
             : undefined;
-        return {
+        // Each call goes to its REST boundary, whose write-outcome verdict stands.
+        return delegatesEachCall({
             id,
             title: options.title ?? "GitHub",
+            // Preserve the REST tools' existing MCP result envelope.
             kind: "mcp",
             authScope: "shared",
             ...provider.connectorOptions,
             ...(credential ? { credential } : {}),
-            classification: provider.classify,
             description: `GitHub App access to ${policy.summary()}.`,
             usageGuide,
             describe: () => ({
                 source: { kind: "custom" },
-                endpoint: { origin: "https://api.githubcopilot.com", path: "/mcp/" },
+                endpoint: { origin: "https://api.github.com", path: "/" },
                 auth: { mode: "request", header: "Authorization", scheme: "Bearer" },
             }),
+            staticTools: rest.staticTools,
             async listTools(ctx) {
-                // Catalog discovery authenticates only a configured scope, with read
-                // permissions. Fetch one complete vendor catalog and preserve schemas.
-                const first = policy.scopes[0];
-                const owner = first.org ?? first.repo.split("/")[0];
-                const repos = first.repo ? [first.repo.split("/")[1]] : undefined;
-                const token = await auth.token(owner, repos, {
-                    contents: "read",
-                    issues: "read",
-                    pull_requests: "read",
-                    actions: "read",
-                    checks: "read",
-                    statuses: "read",
-                }, ctx);
-                const facts = await withHosted(token, ctx, (client) => client.listTools(ctx));
-                const complement = await rest.listTools(ctx);
-                // Names not reviewed never leave this boundary, including collisions
-                // with the REST complement. The registry alone applies verdicts.
-                return [...facts.filter((tool) => Object.hasOwn(HOSTED_ROUTES, tool.name)), ...complement];
+                return rest.listTools(ctx);
             },
             async callTool(name, args, ctx, callOptions) {
-                if (Object.hasOwn(HOSTED_ROUTES, name)) {
-                    const route = hostedTarget(name, args, policy);
-                    const token = await auth.repo(route.target, route.permissions, ctx);
-                    return withHosted(token, ctx, (client) => client.callTool(name, args, ctx, callOptions));
-                }
-                if (!Object.hasOwn(CLASSIFICATION.tools, name))
-                    throw new ConnectorCallError("invalid_args", "This GitHub tool is not in the reviewed allowlist.");
-                const result = await rest.callTool(name, args, ctx, callOptions);
+                if (!rest.staticTools?.some((tool) => tool.name === name))
+                    throw knownProviderFailure(new ConnectorCallError("invalid_args", "This GitHub tool is not in the REST tool set."));
+                const result = await Reflect.apply(restCall, rest, [name, args, ctx, callOptions]);
                 return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result };
             },
             async status() {
                 return { state: "ok", message: "GitHub App configured; installation access is resolved lazily on use." };
             },
-        };
+        });
     },
 });

package/dist/providers/github/{auth.d.ts → lib/auth.d.ts}

@@ -1,5 +1,5 @@
-import { type GuardedRequest } from "../../connectors/guarded-fetch.js";
-import type { ConnectorContext } from "../../types.js";
+import { type GuardedRequest } from "../../../connectors/guarded-fetch.js";
+import type { ConnectorContext } from "../../../types.js";
 import { ScopePolicy, type Target } from "./scope.js";
 export interface GitHubApp {
     appId: string | number;
@@ -17,9 +17,11 @@ export declare class AppAuth {
     private readonly orgInstallations;
     private readonly configuredDer?;
     private readonly appId;
+    private readonly send;
     constructor(app: GitHubApp, policy: ScopePolicy);
     private key;
-    json(request: GuardedRequest, bearer: string, ctx: ConnectorContext): Promise<unknown>;
+    /** `write` sends the request once: a failure that may follow the change is not retryable. */
+    json(request: GuardedRequest, bearer: string, ctx: ConnectorContext, write?: boolean): Promise<unknown>;
     private invalidate;
     rejectToken(bearer: string): Promise<void>;
     private installation;

package/dist/providers/github/{auth.js → lib/auth.js}

@@ -1,8 +1,10 @@
-import { guardedFetch, retryAfterMs } from "../../connectors/guarded-fetch.js";
-import { ConnectorCallError } from "../../errors.js";
-import { attachFailureFacts } from "../../operator-record.js";
+import { guardedFetch } from "../../../connectors/guarded-fetch.js";
+import { ConnectorCallError } from "../../../errors.js";
+import { captureClassifierFacts, StatusFailure, toConnectorCallError, withClassifierFacts, } from "../../../http/errors.js";
+import { errors, rejectedToken } from "../api.js";
 import { appJwt, privateKeyDer } from "./key.js";
 import { target } from "./scope.js";
+import { sentSecretsFor } from "../../../sent-secrets.js";
 const MAX_ENTRIES = 256;
 const REFRESH_MARGIN = 60_000;
 const INSTALLATION_TTL = 300_000;
@@ -30,6 +32,17 @@ export class AppAuth {
     orgInstallations = new Map();
     configuredDer;
     appId;
+    send = guardedFetch({
+        provider: "GitHub",
+        baseUrl: "https://api.github.com",
+        maxResponseBytes: 4 * 1024 * 1024,
+        headers: {
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "connecta",
+        },
+        authenticate: () => ({}),
+    });
     constructor(app, policy) {
         this.app = app;
         this.policy = policy;
@@ -48,6 +61,8 @@ export class AppAuth {
     }
     async key(ctx) {
         ctx.signal?.throwIfAborted();
+        if (this.app.privateKey !== undefined)
+            sentSecretsFor(ctx).add(this.app.privateKey);
         let der = this.configuredDer;
         if (!der) {
             const pem = await ctx.credential?.get("privateKey");
@@ -67,49 +82,30 @@ export class AppAuth {
             fingerprint: `${this.appId}:${Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("")}`,
         };
     }
-    async json(request, bearer, ctx) {
+    /** `write` sends the request once: a failure that may follow the change is not retryable. */
+    async json(request, bearer, ctx, write = false) {
         ctx.signal?.throwIfAborted();
-        const transport = guardedFetch({
-            provider: "GitHub",
-            baseUrl: "https://api.github.com",
-            maxResponseBytes: 4 * 1024 * 1024,
-            headers: {
-                Accept: "application/vnd.github+json",
-                "X-GitHub-Api-Version": "2022-11-28",
-                "User-Agent": "connecta",
-            },
-            authenticate: () => ({ Authorization: `Bearer ${bearer}` }),
-        });
-        return transport(request, ctx, async (response) => {
+        return this.send({
+            classification: write ? "write" : "read",
+            ...request,
+            headers: { ...request.headers, Authorization: `Bearer ${bearer}` },
+        }, ctx, async (response) => {
             if (!response.ok) {
                 // Dispose of the body without interpreting error text or Content-Type.
                 await response.prefix(0);
-                const status = response.status;
-                const reset = Number(response.headers.get("x-ratelimit-reset"));
-                const retry = retryAfterMs(response.headers);
-                const wait = retry ?? (Number.isFinite(reset) && reset > 0 ? Math.max(0, reset * 1000 - Date.now()) : undefined);
-                const rate = status === 429 ||
-                    (status === 403 && (retry !== undefined || response.headers.get("x-ratelimit-remaining") === "0"));
-                if (status === 401 || (status === 403 && !rate))
+                if (rejectedToken(response.status, response.headers))
                     this.invalidate(bearer);
-                const code = rate
-                    ? "rate_limited"
-                    : status === 401 || status === 403
-                        ? "auth_required"
-                        : status === 409
-                            ? "conflict"
-                            : status >= 500
-                                ? "unavailable"
-                                : "connector_call_failed";
-                throw attachFailureFacts(new ConnectorCallError(code, rate
-                    ? "GitHub rate limit reached. Honor the retry timing before trying again."
-                    : code === "auth_required"
-                        ? "Verify the GitHub App key, installation, repository selection and required permissions."
-                        : code === "conflict"
-                            ? "GitHub rejected a stale version. Read the current state before resubmitting."
-                            : status === 404
-                                ? "GitHub returned 404; the resource may be absent or inaccessible to this installation."
-                                : "The GitHub API request failed; downstream error text is withheld.", { retryable: rate || status >= 500, ...(rate && wait !== undefined ? { retryAfterMs: wait } : {}) }), { httpStatus: status });
+                const failure = withClassifierFacts(new StatusFailure({
+                    status: response.status,
+                    headers: response.headers,
+                    body: undefined,
+                    operation: { method: request.method, template: request.path },
+                }), captureClassifierFacts(undefined, errors, response.headers));
+                throw toConnectorCallError(failure, errors, {
+                    classification: write ? "write" : "read",
+                    dispatches: [],
+                    withholds: () => true,
+                });
             }
             const parsed = await response.jsonResult();
             ctx.signal?.throwIfAborted();
@@ -147,7 +143,7 @@ export class AppAuth {
         }
         let found;
         for (let page = 1; page <= 20; page++) {
-            const data = await this.json({ method: "GET", path: "/app/installations", query: { per_page: 100, page } }, jwt, ctx);
+            const data = await this.json({ auxiliary: true, method: "GET", path: "/app/installations", query: { per_page: 100, page } }, jwt, ctx);
             if (!Array.isArray(data))
                 throw new ConnectorCallError("connector_call_failed", "GitHub returned an invalid installation list.");
             for (const item of data) {
@@ -204,7 +200,7 @@ export class AppAuth {
         const found = new Map();
         const configured = this.policy.scopes.filter((scope) => scope.repo?.startsWith(`${owner}/`));
         for (let page = 1; page <= 100; page++) {
-            const data = record(await this.json({ method: "GET", path: "/installation/repositories", query: { per_page: 100, page } }, resolver, ctx));
+            const data = record(await this.json({ auxiliary: true, method: "GET", path: "/installation/repositories", query: { per_page: 100, page } }, resolver, ctx));
             if (!Array.isArray(data.repositories))
                 throw new ConnectorCallError("connector_call_failed", "GitHub returned an invalid repository list.");
             for (const item of data.repositories) {
@@ -303,6 +299,7 @@ export class AppAuth {
         let response;
         try {
             response = record(await this.json({
+                auxiliary: true,
                 method: "POST",
                 path: `/app/installations/${installation.id}/access_tokens`,
                 body: { permissions: permissionSet, ...(repositorySet ? { repository_ids: repositorySet } : {}) },

package/dist/providers/github/lib/discovery.js

@@ -0,0 +1,132 @@
+import { OperationIndex } from "../../_shared/rest/operation-index.js";
+import { githubPage } from "../../../http/hatch-paging.js";
+import { openapi } from "../openapi.generated.js";
+import { READ_PERMISSIONS, RELEASE_PERMISSIONS, INTERNAL_READS, MERGE } from "./operations.js";
+import { workflowPath } from "./scope.js";
+import { ConnectorCallError } from "../../../errors.js";
+/** Only the documented contents path can consume several literal URL segments. */
+export function contentsPath(path) {
+    // Preserve the shared refusal of URL suffixes and unfilled placeholders.
+    if (/[?#{}]/.test(path))
+        return path;
+    const match = /^(\/repos\/[^/]+\/[^/]+\/contents\/)(.+)$/.exec(path);
+    if (!match)
+        return path;
+    let relative;
+    try {
+        relative = decodeURIComponent(match[2]);
+    }
+    catch {
+        // Keep malformed encodings for the index's standard refusal.
+        return path;
+    }
+    workflowPath(relative);
+    return match[1] + encodeURIComponent(relative);
+}
+// Prefer the deployed coverage for natural queries. Explicit paths and queries
+// without reviewed matches retain full-pin refusal discovery. Metadata, contract
+// lookup, validation and the manifest still use the complete immutable pin.
+class RepositoryIndex extends OperationIndex {
+    resolve(method, path) {
+        if (method === "GET" && /^\/repos\/[^/]+\/[^/]+\/contents$/.test(path)) {
+            // GitHub documents omitted path as the root directory. Reuse the pinned
+            // contents contract; validate owner/repo normally, and never send this
+            // placeholder. The actual resource request keeps the /contents URL.
+            const match = super.resolve(method, `${path}/root`);
+            return { ...match, params: { ...match.params, path: "" } };
+        }
+        try {
+            return super.resolve(method, contentsPath(path));
+        }
+        catch (error) {
+            if (method === "GET" &&
+                error instanceof ConnectorCallError &&
+                error.code === "invalid_args" &&
+                error.message.includes(" operation in the pinned API index ") &&
+                /^\/repos\/[^/]+\/[^/]+\/(?:commits|compare)\/[^/]+\/.+/.test(path))
+                throw new ConnectorCallError("invalid_args", `${error.message} Encode '/' inside refs as %2F.`);
+            throw error;
+        }
+    }
+    contract(op, only) {
+        const contract = super.contract(op, only);
+        if (op.path === "/repos/{owner}/{repo}/contents/{path}")
+            for (const param of contract.parameters)
+                if (param.name === "path")
+                    param.description =
+                        "Canonical relative file or directory path; nested paths such as src/index.ts are accepted. For the root directory use /repos/{owner}/{repo}/contents without a final path.";
+        if (["/repos/{owner}/{repo}/commits/{ref}", "/repos/{owner}/{repo}/compare/{basehead}"].includes(op.path))
+            for (const param of contract.parameters)
+                if (param.name === "ref" || param.name === "basehead")
+                    param.description =
+                        "Repository-local ref or SHA; encode a slash inside a branch name as %2F. Compare uses BASE...HEAD. Owner-prefixed refs containing a colon are refused.";
+        return contract;
+    }
+    search(query, options) {
+        const all = super.search(query, { ...options, limit: this.ops.length });
+        if (query.trim().startsWith("/"))
+            return all.slice(0, options.limit);
+        const preferred = all.filter((op) => {
+            const key = `${op.method} ${op.path}`;
+            return READ_PERMISSIONS[key] || RELEASE_PERMISSIONS[key] || INTERNAL_READS.has(key) || key === MERGE;
+        });
+        // The shared lexical framing drops "latest". Bare release discovery
+        // therefore leads with the collection and latest read; explicit actions,
+        // method filters and paths still discover every reviewed release write.
+        const found = /^releases?$/i.test(query.trim()) && (options.method === undefined || options.method === "GET")
+            ? preferred.filter((op) => op.method === "GET" &&
+                ["/repos/{owner}/{repo}/releases", "/repos/{owner}/{repo}/releases/latest"].includes(op.path))
+            : preferred;
+        return (found.length ? found : all).slice(0, options.limit);
+    }
+}
+export const githubIndex = new RepositoryIndex({
+    ...openapi,
+    ops: openapi.ops.map((row) => {
+        const [method, path, id, summary, tag, ...server] = row;
+        const alias = method === "PATCH" && path === "/repos/{owner}/{repo}/releases/{release_id}"
+            ? " (Publish a release by updating draft to false)"
+            : path === "/repos/{owner}/{repo}/releases/latest"
+                ? " (Latest published release)"
+                : path.includes("/pulls")
+                    ? " (PR pull request)"
+                    : path.includes("/contents/")
+                        ? " (Read file or directory contents)"
+                        : "";
+        return [method, path, id, summary + alias, tag, ...server];
+    }),
+}, { vendor: "github", title: "GitHub", slashParams: ["path", "ref", "basehead"] });
+for (const key of [...Object.keys(READ_PERMISSIONS), ...Object.keys(RELEASE_PERMISSIONS), ...INTERNAL_READS, MERGE]) {
+    if (!githubIndex.ops.some((op) => `${op.method} ${op.path}` === key))
+        throw new Error(`GitHub reviewed operation is absent from the pin: ${key}`);
+}
+export const GITHUB_VERDICTS = {
+    ...Object.fromEntries(Object.keys(READ_PERMISSIONS).map((key) => [key, "read"])),
+    ...Object.fromEntries(Object.keys(RELEASE_PERMISSIONS).map((key) => [key, "destructive"])),
+    [MERGE]: "refuse",
+    ...Object.fromEntries([...INTERNAL_READS].map((key) => [key, "refuse"])),
+};
+export const GITHUB_NAMED = {
+    [MERGE]: "merge_pull_request",
+    "GET /installation/repositories": "list_scopes",
+    "GET /search/repositories": "search_scoped",
+    "GET /search/issues": "search_scoped",
+    "GET /search/code": "search_scoped",
+};
+const adapter = githubPage("https://api.github.com");
+export const GITHUB_PAGES = Object.fromEntries(githubIndex.ops
+    .filter((op) => {
+    const key = `${op.method} ${op.path}`;
+    return (READ_PERMISSIONS[key] && githubIndex.contract(op).parameters.some((p) => p.in === "query" && p.name === "page"));
+})
+    .map((op) => [`${op.method} ${op.path}`, adapter]));
+export const GITHUB_HATCH = {
+    name: "github",
+    title: "GitHub",
+    index: githubIndex,
+    verdicts: GITHUB_VERDICTS,
+    named: GITHUB_NAMED,
+    pages: GITHUB_PAGES,
+    pageCursor: "argument",
+    pathExample: "/repos/alice/widget/issues",
+};