@zackbart/connecta 0.28.1 → 0.30.0

package/dist/providers/github/scope.js

@@ -0,0 +1,124 @@
+import { ConnectorCallError } from "../../errors.js";
+const OWNER = /^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/i;
+const REPO = /^[a-z0-9_.-]{1,100}$/i;
+export function target(owner, repo) {
+    if (typeof owner !== "string" ||
+        !OWNER.test(owner) ||
+        typeof repo !== "string" ||
+        !REPO.test(repo) ||
+        repo === "." ||
+        repo === "..") {
+        throw new ConnectorCallError("invalid_args", "Supply an explicit GitHub owner and repository name, without URLs or path separators.");
+    }
+    return { owner: owner.toLowerCase(), repo: repo.toLowerCase() };
+}
+export function parseScopes(input) {
+    if (!Array.isArray(input) || input.length === 0 || input.length > 100) {
+        throw new Error("scopes to contain between 1 and 100 org or repo entries with explicit access.");
+    }
+    const seen = new Set();
+    const scopes = input.map((scope) => {
+        if (!scope ||
+            (scope.org === undefined) === (scope.repo === undefined) ||
+            !["read", "read-write"].includes(scope.access) ||
+            (scope.workflows !== undefined && scope.workflows !== "write") ||
+            (scope.workflows === "write" && scope.access !== "read-write")) {
+            throw new Error("each scope to name either org or repo, explicit access, and workflows write only with read-write access.");
+        }
+        let normalized;
+        if (scope.org !== undefined) {
+            if (typeof scope.org !== "string" || !OWNER.test(scope.org))
+                throw new Error("scope org to be a GitHub organization login.");
+            normalized = {
+                org: scope.org.toLowerCase(),
+                access: scope.access,
+                ...(scope.workflows ? { workflows: scope.workflows } : {}),
+            };
+        }
+        else {
+            const parts = typeof scope.repo === "string" ? scope.repo.split("/") : [];
+            const parsed = target(parts[0], parts.length === 2 ? parts[1] : undefined);
+            normalized = {
+                repo: `${parsed.owner}/${parsed.repo}`,
+                access: scope.access,
+                ...(scope.workflows ? { workflows: scope.workflows } : {}),
+            };
+        }
+        const key = normalized.org ?? normalized.repo;
+        if (seen.has(key))
+            throw new Error("scopes without duplicate org or repo entries.");
+        seen.add(key);
+        return Object.freeze(normalized);
+    });
+    for (const scope of scopes) {
+        if (!scope.repo)
+            continue;
+        const parent = scopes.find((candidate) => candidate.org === scope.repo.split("/")[0]);
+        if (parent &&
+            ((parent.access === "read" && scope.access === "read-write") ||
+                (parent.workflows !== "write" && scope.workflows === "write"))) {
+            throw new Error("repo scopes to narrow their org grant rather than widen it.");
+        }
+    }
+    return Object.freeze(scopes);
+}
+export class ScopePolicy {
+    scopes;
+    aliases = new Map();
+    constructor(scopes) {
+        this.scopes = scopes;
+    }
+    scope(t, write = false, workflows = false) {
+        const grant = this.aliases.get(`${t.owner}/${t.repo}`) ??
+            this.scopes.find((scope) => scope.repo === `${t.owner}/${t.repo}`) ??
+            this.scopes.find((scope) => scope.org === t.owner);
+        if (!grant || (write && grant.access !== "read-write") || (workflows && grant.workflows !== "write")) {
+            throw new ConnectorCallError("invalid_args", `GitHub target or operation is outside configured scope. Allowed: ${this.summary()}. Workflow-file writes require workflows: "write" on the effective scope.`);
+        }
+        return grant;
+    }
+    bindAlias(t, grant) {
+        const name = `${t.owner}/${t.repo}`;
+        // Only authenticated installation metadata can introduce an alias. Keep
+        // the stricter grant when multiple configured names bind the same ID.
+        const previous = this.aliases.get(name);
+        if (!previous || grant.access === "read" || (previous.access === grant.access && grant.workflows !== "write")) {
+            if (this.aliases.size >= 256 && !this.aliases.has(name))
+                this.aliases.delete(this.aliases.keys().next().value);
+            this.aliases.set(name, grant);
+        }
+    }
+    summary() {
+        return this.scopes
+            .map((scope) => `${scope.org ? `org ${scope.org}` : `repo ${scope.repo}`} (${scope.access}${scope.workflows ? ", workflows write" : ""})`)
+            .join(", ");
+    }
+    owner(owner) {
+        if (typeof owner !== "string" ||
+            !OWNER.test(owner) ||
+            !this.scopes.some((scope) => scope.org === owner.toLowerCase() || scope.repo?.split("/")[0] === owner.toLowerCase())) {
+            throw new ConnectorCallError("invalid_args", `Choose a configured owner. Allowed: ${this.summary()}.`);
+        }
+        return owner.toLowerCase();
+    }
+    repositories(owner) {
+        if (this.scopes.some((scope) => scope.org === owner))
+            return undefined;
+        return this.scopes
+            .filter((scope) => scope.repo?.split("/")[0] === owner)
+            .map((scope) => scope.repo.split("/")[1]);
+    }
+}
+/** Git paths are literal, canonical paths. Reject aliases before authentication. */
+export function workflowPath(path) {
+    if (typeof path !== "string" ||
+        !path ||
+        path.startsWith("/") ||
+        /[\\%]/.test(path) ||
+        Array.from(path).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127) ||
+        path.split("/").some((part) => !part || part === "." || part === "..")) {
+        throw new ConnectorCallError("invalid_args", "File paths must be canonical relative Git paths without escapes or dot segments.");
+    }
+    const normalized = path.toLowerCase();
+    return normalized === ".github" || normalized === ".github/workflows" || normalized.startsWith(".github/workflows/");
+}

package/dist/providers/github/skill.generated.js

@@ -0,0 +1,8 @@
+// Generated by scripts/generate-providers.mjs; do not edit.
+export const skill = {
+    "content": "## Setup\n\nCreate a GitHub App, generate its RSA private key, and install it on every\nconfigured owner. Org grants require **All repositories**, including future\nrepositories. Exact repo grants work with selected-repository installations.\nRead-only grants request read permissions; read-write grants request only the\npermissions needed by each operation. The App needs repository Metadata,\nContents, Issues, Pull requests, Actions, Checks and Commit statuses for the\nreviewed read tools. Grant Contents, Issues, Pull requests and Actions write\nonly for the operations the deployment needs. Workflow-file edits also need\nthe App's Workflows write permission and `workflows: \"write\"` on the effective\nscope. Org grants authorize repository operations, not organization administration.\n\nPass `app: { appId, privateKey }` with the key from an environment secret, or\nomit privateKey and populate the connector's encrypted `privateKey` vault field.\nNever put private keys or installation tokens in agent instructions. Tokens\nstay in bounded runtime memory, refresh a minute before expiry, and are never\npersisted. Key rotation partitions the caches by the key's fingerprint.\nConfigured repository names bind to repository IDs on first use. Bindings last\nfor the provider instance; name lookups expire after five minutes. A rename\nkeeps its grant, while a replacement repository at the old name does not.\nReconfigure to authorize a replacement. Transfers leave the original\ninstallation and cannot use its tokens. Org grants bind to installation IDs.\n\n## Choose the target first\n\n`list_scopes({})` returns configured org/repo grants without network access.\n`list_scopes({ owner })` resolves that owner's installation and pages reachable\nrepositories. Carry its `next_page`. The connection context lists configured\nscopes and access. A repo entry overrides and may narrow its parent org entry.\nAn org grant covers current and future repositories, as long as the installation\nkeeps All repositories selected.\n\nEvery hosted call requires explicit `owner` and `repo`. Connecta checks scope\nand write access before reading the key or minting a token, and narrows each\nrepo call's token with `repository_ids` and the reviewed permissions.\nAn internal metadata-only installation token resolves names through GitHub's\ninstallation repository list; it never authenticates hosted calls or search.\nExpiry and misses refresh the name lookup without rebinding configured grants.\nUse discovery or the configured name to refresh a rename before using its new\nname; names that cannot map to a configured grant fail before operation tokens\nare minted. Cross-owner\nPR heads, cross-repository issue parents, opaque comment/review-thread IDs and\nsymlink writes are refused. The first release acts as the App; personal OAuth\nattribution is planned separately. Classification describes behavior; scope\nchecks authorize targets regardless of the pool's trust.\n\n## Tools and paging\n\nHosted schemas and results come from GitHub. Reviewed reads cover files,\ncommits, branches, tags, releases, issues, labels, PR details/diffs/reviews,\nand Actions workflows/runs/jobs. Reviewed writes cover issues, comments, PR\ncreation/updates/reviews, branches, file edits and Actions dispatch/rerun/cancel.\nCompound `issue_write` is always a write, including update/close. Review methods\nare limited to create/submit_pending/delete_pending; resolve/unresolve by opaque thread ID are\nnot exposed. Scope-changing tools, repo creation/forks, deletion/transfer,\nadministration, secrets and Copilot delegation are absent. Unknown upstream\ntools, arguments and methods require review before use.\n\nUse `search_scoped` for repositories, issues, PRs or code across installations.\nSupply literal words and an optional subset of configured org/repo selectors.\nScope qualifiers and Boolean operators are refused. Results have a partition\nID, next page, and an incomplete-results flag. Pass pages keyed by those exact\npartition IDs. Each call makes at most 20 partition requests; select fewer\nscopes when needed. Search pages stop at 10 and retain incompleteness. Returned\nrepositories are checked by ID against both deployment scopes and selected\npartitions. Issue and PR results resolve their repository URL to an ID before\nany result is returned.\nInstallation tokens do not override GitHub's own code-search access restrictions.\n\nREST complements own `create_release`, `update_release`, `delete_release` and\n`merge_pull_request`. Publishing a draft is `update_release({ draft: false })`.\nMerge requires an expected head SHA, a same-repository head/base and explicit\nworkflow-write access on the effective scope. GitHub atomically guards only the\nhead SHA, so a concurrent base retarget can introduce workflow changes despite\nan earlier file comparison. Merge is therefore disabled by default.\nRead current state before updates. A dispatched write is attempted once;\nGitHub errors never trigger an automatic write retry. Honor retry timing on\nrate limits; an ambiguous 404 may mean absence or an installation permission\ngap. Fix the App installation/key/permissions for auth errors; the App has no\ninteractive OAuth reconnect flow.\n",
+    "instructionsHeading": "Repository instructions",
+    "fragments": {
+        "guide": "## Setup\n\nCreate a GitHub App, generate its RSA private key, and install it on every\nconfigured owner. Org grants require **All repositories**, including future\nrepositories. Exact repo grants work with selected-repository installations.\nRead-only grants request read permissions; read-write grants request only the\npermissions needed by each operation. The App needs repository Metadata,\nContents, Issues, Pull requests, Actions, Checks and Commit statuses for the\nreviewed read tools. Grant Contents, Issues, Pull requests and Actions write\nonly for the operations the deployment needs. Workflow-file edits also need\nthe App's Workflows write permission and `workflows: \"write\"` on the effective\nscope. Org grants authorize repository operations, not organization administration.\n\nPass `app: { appId, privateKey }` with the key from an environment secret, or\nomit privateKey and populate the connector's encrypted `privateKey` vault field.\nNever put private keys or installation tokens in agent instructions. Tokens\nstay in bounded runtime memory, refresh a minute before expiry, and are never\npersisted. Key rotation partitions the caches by the key's fingerprint.\nConfigured repository names bind to repository IDs on first use. Bindings last\nfor the provider instance; name lookups expire after five minutes. A rename\nkeeps its grant, while a replacement repository at the old name does not.\nReconfigure to authorize a replacement. Transfers leave the original\ninstallation and cannot use its tokens. Org grants bind to installation IDs.\n\n## Choose the target first\n\n`list_scopes({})` returns configured org/repo grants without network access.\n`list_scopes({ owner })` resolves that owner's installation and pages reachable\nrepositories. Carry its `next_page`. The connection context lists configured\nscopes and access. A repo entry overrides and may narrow its parent org entry.\nAn org grant covers current and future repositories, as long as the installation\nkeeps All repositories selected.\n\nEvery hosted call requires explicit `owner` and `repo`. Connecta checks scope\nand write access before reading the key or minting a token, and narrows each\nrepo call's token with `repository_ids` and the reviewed permissions.\nAn internal metadata-only installation token resolves names through GitHub's\ninstallation repository list; it never authenticates hosted calls or search.\nExpiry and misses refresh the name lookup without rebinding configured grants.\nUse discovery or the configured name to refresh a rename before using its new\nname; names that cannot map to a configured grant fail before operation tokens\nare minted. Cross-owner\nPR heads, cross-repository issue parents, opaque comment/review-thread IDs and\nsymlink writes are refused. The first release acts as the App; personal OAuth\nattribution is planned separately. Classification describes behavior; scope\nchecks authorize targets regardless of the pool's trust.\n\n## Tools and paging\n\nHosted schemas and results come from GitHub. Reviewed reads cover files,\ncommits, branches, tags, releases, issues, labels, PR details/diffs/reviews,\nand Actions workflows/runs/jobs. Reviewed writes cover issues, comments, PR\ncreation/updates/reviews, branches, file edits and Actions dispatch/rerun/cancel.\nCompound `issue_write` is always a write, including update/close. Review methods\nare limited to create/submit_pending/delete_pending; resolve/unresolve by opaque thread ID are\nnot exposed. Scope-changing tools, repo creation/forks, deletion/transfer,\nadministration, secrets and Copilot delegation are absent. Unknown upstream\ntools, arguments and methods require review before use.\n\nUse `search_scoped` for repositories, issues, PRs or code across installations.\nSupply literal words and an optional subset of configured org/repo selectors.\nScope qualifiers and Boolean operators are refused. Results have a partition\nID, next page, and an incomplete-results flag. Pass pages keyed by those exact\npartition IDs. Each call makes at most 20 partition requests; select fewer\nscopes when needed. Search pages stop at 10 and retain incompleteness. Returned\nrepositories are checked by ID against both deployment scopes and selected\npartitions. Issue and PR results resolve their repository URL to an ID before\nany result is returned.\nInstallation tokens do not override GitHub's own code-search access restrictions.\n\nREST complements own `create_release`, `update_release`, `delete_release` and\n`merge_pull_request`. Publishing a draft is `update_release({ draft: false })`.\nMerge requires an expected head SHA, a same-repository head/base and explicit\nworkflow-write access on the effective scope. GitHub atomically guards only the\nhead SHA, so a concurrent base retarget can introduce workflow changes despite\nan earlier file comparison. Merge is therefore disabled by default.\nRead current state before updates. A dispatched write is attempted once;\nGitHub errors never trigger an automatic write retry. Honor retry timing on\nrate limits; an ambiguous 404 may mean absence or an installation permission\ngap. Fix the App installation/key/permissions for auth errors; the App has no\ninteractive OAuth reconnect flow.\n"
+    }
+};

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

@@ -0,0 +1,51 @@
+import { type GoogleWorkspaceOptions } from "../_shared/google/workspace.js";
+export type { GoogleServiceAccount, GoogleSubjectContext, GoogleWorkspaceOptions, GoogleWorkspaceSubject, } from "../_shared/google/workspace.js";
+/**
+ * Gmail's API root, confined to the delegated user's own mailbox: `me` is the
+ * token's subject, and no path can climb out of it.
+ */
+export declare const GMAIL_API_BASE_URL = "https://gmail.googleapis.com/gmail/v1/users/me";
+/**
+ * Exactly the scopes this connection requests, and exactly what the Admin
+ * console's domain-wide delegation entry must list (comma-separated there).
+ * `gmail.compose` technically permits sending; the tool surface does not.
+ */
+export declare const GMAIL_SCOPES: readonly ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.compose"];
+/** Options for {@link gmail}: the shared Workspace delegation options. */
+export type GmailOptions = GoogleWorkspaceOptions;
+/**
+ * A maintained, draft-only Gmail connection acting as each signed-in
+ * Workspace user through a delegated service account.
+ *
+ * Setup, once per Workspace (shared with every Workspace provider):
+ *
+ * 1. In a Google Cloud project, enable the **Gmail API**.
+ * 2. Create a service account. Grant it no IAM roles: delegation, not project
+ *    permission, is what reaches mailboxes.
+ * 3. Create a JSON key for it. If key creation is refused, the organization
+ *    policy `iam.disableServiceAccountKeyCreation` is enforced; an org policy
+ *    administrator can override it for this project alone.
+ * 4. Copy the service account's numeric **client ID** (the key's `client_id`).
+ * 5. As a Workspace super admin: Admin console → Security → Access and data
+ *    control → API controls → Manage Domain Wide Delegation → Add new. Paste
+ *    the client ID and exactly these scopes, comma-separated
+ *    ({@link GMAIL_SCOPES}):
+ *    `https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.compose`.
+ *    A new grant can take up to 24 hours to apply.
+ * 6. Configure inbound auth: a `subject` function is never asked about an
+ *    open deployment's anonymous requests, which fail `auth_required`.
+ *    Then give the deployment the key as a secret and map callers to mailboxes:
+ *
+ * ```ts
+ * gmail("mail", {
+ *   purpose: "Staff email triage and reply drafting",
+ *   serviceAccount: env.GOOGLE_SERVICE_ACCOUNT_JSON,
+ *   subject: (identity) => mailboxes[identity.principal?.id ?? ""],
+ * });
+ * ```
+ *
+ * `gmail.compose` technically allows sending; this connection never does,
+ * because no tool reaches a send method. Drafts are additive writes the host
+ * approves through call_destructive_tool or a trusted program.
+ */
+export declare const gmail: import("../../provider.js").ProviderFactory<GoogleWorkspaceOptions>;