wizards 0.1.9

package/apps/runtime/dist/engenty/connections-external/registry-client.js

@@ -0,0 +1,336 @@
+import { z } from "zod";
+import { createGuardedFetch } from "./net/guarded-fetch.js";
+/**
+ * Client for the integrations.sh registry (payload `version: 3`). Contacted
+ * ONLY during admin search/preview/import — never at agent runtime.
+ *
+ * The registry's own wire schema is the contract: `/api/search` returns
+ * domain-level hits each carrying a `surfaces[]` summary, and
+ * `GET /api/{domain}/surface` returns the cached catalog document shown on the
+ * public page — `surfaces[]` as a discriminated union on `type` (`http`,
+ * `mcp`, `graphql`, `cli`) plus a `credentials` registry keyed by id. Parsing
+ * stays loose (unknown keys pass through) and the raw payload is persisted on
+ * the imported record for forensics, but every field this module *acts* on is
+ * validated here.
+ *
+ * `/surface` is preferred over `/discover` (live re-probe — often hangs past
+ * our request timeout while `/surface` returns in hundreds of ms).
+ */
+const DEFAULT_REGISTRY_URL = "https://integrations.sh";
+const REQUEST_TIMEOUT_MS = 20_000;
+/** Remote MCP transports this module can actually speak. */
+const SUPPORTED_MCP_TRANSPORTS = ["streamable-http", "sse"];
+export function registryBaseUrl() {
+    return (process.env.ENGENTY_INTEGRATIONS_REGISTRY_URL ?? DEFAULT_REGISTRY_URL).replace(/\/+$/u, "");
+}
+// ---------------------------------------------------------------------------
+// Wire schemas
+// ---------------------------------------------------------------------------
+/** RFC 6902 operation, as the registry publishes spec corrections. */
+const jsonPatchOperationSchema = z
+    .object({
+    from: z.string().optional(),
+    op: z.enum(["add", "remove", "replace", "move", "copy", "test"]),
+    path: z.string(),
+    value: z.unknown().optional(),
+})
+    .loose();
+/**
+ * How one credential rides the request. `source` decides what we can map:
+ * `http` (header/query placement) and `spec`/`well-known` (auth described by
+ * the spec or an OAuth discovery document) are actionable; `cli` and
+ * `unknown` are not.
+ */
+const authMechanicsSchema = z
+    .object({
+    command: z.string().optional(),
+    env: z.array(z.string()).optional(),
+    headerName: z.string().optional(),
+    in: z.string().optional(),
+    scheme: z.string().optional(),
+    source: z.string(),
+})
+    .loose();
+/** One credential an entry needs; an entry's `use[]` are needed together (AND). */
+const authUseSchema = z
+    .object({ id: z.string(), mechanics: authMechanicsSchema })
+    .loose();
+/** `entries[]` are alternatives (OR) — any one of them authenticates. */
+const authEntrySchema = z
+    .object({ use: z.array(authUseSchema).default([]) })
+    .loose();
+const surfaceAuthSchema = z
+    .object({
+    entries: z.array(authEntrySchema).default([]),
+    status: z.string().default("unknown"),
+})
+    .loose();
+const requiredHeaderSchema = z
+    .object({
+    description: z.string().nullish(),
+    name: z.string(),
+    source: z
+        .object({ kind: z.string(), value: z.string().nullish() })
+        .loose()
+        .nullish(),
+})
+    .loose();
+const surfaceVariableSchema = z
+    .object({
+    description: z.string().nullish(),
+    in: z.string().nullish(),
+    name: z.string(),
+    resolveFrom: z.string().nullish(),
+})
+    .loose();
+const surfaceSchema = z
+    .object({
+    auth: surfaceAuthSchema.nullish(),
+    docs: z.string().nullish(),
+    name: z.string().nullish(),
+    requiredHeaders: z.array(requiredHeaderSchema).default([]),
+    slug: z.string().nullish(),
+    spec: z.string().nullish(),
+    specAlternates: z.array(z.string()).default([]),
+    specOverrides: z.array(jsonPatchOperationSchema).default([]),
+    transports: z.array(z.string()).nullish(),
+    type: z.string(),
+    url: z.string().nullish(),
+    variables: z.array(surfaceVariableSchema).default([]),
+})
+    .loose();
+const credentialSchema = z
+    .object({
+    generateUrl: z.string().nullish(),
+    label: z.string().nullish(),
+    setup: z.string().nullish(),
+    type: z.string(),
+})
+    .loose();
+/**
+ * OAuth facts probed from `/.well-known/oauth-authorization-server` &co. The
+ * `credentials` registry describes OAuth in prose only, so these endpoints are
+ * the sole machine-readable source for an authorization-code mapping.
+ */
+const oauthFactsSchema = z
+    .object({
+    authorizationEndpoint: z.string().optional(),
+    dcr: z.boolean().optional(),
+    grantTypes: z.array(z.string()).default([]),
+    registrationEndpoint: z.string().optional(),
+    scopes: z.array(z.string()).default([]),
+    tokenEndpoint: z.string().optional(),
+})
+    .loose();
+const discoverSchema = z
+    .object({
+    credentials: z.record(z.string(), credentialSchema).default({}),
+    description: z.string().nullish(),
+    detect: z
+        .object({
+        auth: z.object({ oauth: oauthFactsSchema.nullish() }).loose().nullish(),
+    })
+        .loose()
+        .nullish(),
+    domain: z.string(),
+    summary: z.string().nullish(),
+    surfaces: z.array(surfaceSchema).default([]),
+    version: z.number().optional(),
+})
+    .loose();
+/** Surface summary carried on a search hit (same identity, fewer facts). */
+const searchSurfaceSchema = z
+    .object({
+    auth: z
+        .object({
+        header: z.string().nullish(),
+        kind: z.string().nullish(),
+        note: z.string().nullish(),
+    })
+        .loose()
+        .nullish(),
+    icon: z.string().nullish(),
+    kind: z.string(),
+    slug: z.string(),
+    specOverrides: z.array(jsonPatchOperationSchema).default([]),
+    url: z.string().nullish(),
+})
+    .loose();
+const searchResultSchema = z.object({
+    description: z.string().default(""),
+    domain: z.string(),
+    kinds: z.array(z.string()).default([]),
+    name: z.string(),
+    surfaces: z.array(searchSurfaceSchema).default([]),
+    url: z.string().default(""),
+});
+const searchResponseSchema = z.object({
+    results: z.array(searchResultSchema).default([]),
+});
+/** Parse a `/api/{domain}/surface` body. Exported so fixtures parse identically. */
+export function parseSurfacePayload(data) {
+    return discoverSchema.parse(data);
+}
+/** Parse an `/api/search` body. */
+export function parseSearchResponse(data) {
+    return searchResponseSchema.parse(data).results;
+}
+function normalizeSurface(surface) {
+    if (!surface.slug) {
+        // Without a slug the surface has no stable identity to persist against.
+        return null;
+    }
+    return {
+        auth: surface.auth ?? { entries: [], status: "unknown" },
+        connect_url: surface.url ?? null,
+        docs: surface.docs ?? null,
+        kind: surface.type,
+        name: surface.name ?? null,
+        required_headers: surface.requiredHeaders,
+        slug: surface.slug,
+        spec: surface.spec ?? null,
+        spec_alternates: surface.specAlternates,
+        spec_overrides: surface.specOverrides,
+        transports: surface.transports ?? [],
+        variables: surface.variables,
+    };
+}
+/** Every slugged surface on the domain, in registry order. */
+export function registrySurfaces(payload) {
+    return payload.surfaces
+        .map(normalizeSurface)
+        .filter((surface) => surface !== null);
+}
+/**
+ * Transport to speak to an MCP surface. A surface that declares transports but
+ * no remote one (stdio-only) is not importable; an undeclared transport means
+ * the registry never probed it, and streamable HTTP is the remote default the
+ * adapter falls back from anyway.
+ */
+export function resolveMcpTransport(surface) {
+    if (surface.transports.length === 0) {
+        return "streamable-http";
+    }
+    if (surface.transports.includes("streamable-http")) {
+        return "streamable-http";
+    }
+    return surface.transports.includes("sse") ? "sse" : null;
+}
+/**
+ * Registry surfaces as import candidates. HTTP surfaces need an OpenAPI spec
+ * (a bare base URL describes no operations); MCP surfaces need a supported
+ * remote transport. GraphQL and CLI surfaces are out of scope for this module
+ * and are listed with a reason rather than hidden.
+ */
+export function discoverImportableSources(payload) {
+    const sources = [];
+    for (const surface of registrySurfaces(payload)) {
+        if (surface.kind === "http") {
+            sources.push({
+                blocked_reason: surface.spec
+                    ? null
+                    : "the registry lists no OpenAPI spec for this API — paste a spec URL on the Manual URL tab",
+                source_kind: "openapi",
+                source_url: surface.spec ?? surface.connect_url ?? "",
+                surface,
+                transport: null,
+            });
+            continue;
+        }
+        if (surface.kind === "mcp") {
+            const transport = resolveMcpTransport(surface);
+            // Transport first: a stdio-only server has no connect URL *because* it
+            // is not a remote server, and naming the transport says more.
+            let blocked = null;
+            if (!transport) {
+                blocked = `unsupported MCP transport (${surface.transports.join(", ")}) — only streamable-http and sse can be imported`;
+            }
+            else if (!surface.connect_url) {
+                blocked = "the registry lists no connect URL for this MCP server";
+            }
+            sources.push({
+                blocked_reason: blocked,
+                source_kind: "mcp",
+                source_url: surface.connect_url ?? "",
+                surface,
+                transport,
+            });
+            continue;
+        }
+        sources.push({
+            blocked_reason: `${surface.kind} surfaces cannot be imported — this module covers OpenAPI and MCP`,
+            source_kind: "openapi",
+            source_url: surface.connect_url ?? "",
+            surface,
+            transport: null,
+        });
+    }
+    return sources;
+}
+/**
+ * Re-derive the registry surface a source URL belongs to. Import calls this
+ * server-side from `domain` + `source_url` instead of trusting slug/override
+ * metadata echoed back by the client.
+ */
+export function findSurfaceForSource(payload, sourceUrl) {
+    const wanted = sourceUrl.trim();
+    for (const surface of registrySurfaces(payload)) {
+        const candidates = [
+            surface.spec,
+            ...surface.spec_alternates,
+            surface.connect_url,
+        ].filter((value) => Boolean(value));
+        if (candidates.some((value) => value === wanted)) {
+            return surface;
+        }
+    }
+    return null;
+}
+/** Discovered OAuth facts (nested under `detect.auth`). */
+export function discoverOAuthFacts(payload) {
+    return payload.detect?.auth?.oauth ?? null;
+}
+// ---------------------------------------------------------------------------
+// Requests
+// ---------------------------------------------------------------------------
+async function fetchJson(url, fetchImpl) {
+    const response = await fetchImpl(url, {
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`registry request failed (${response.status}): ${url}`);
+    }
+    return await response.json();
+}
+/**
+ * The registry host comes from `ENGENTY_INTEGRATIONS_REGISTRY_URL` — settings
+ * input, so it goes through the guard like every other outbound URL here.
+ */
+function defaultRegistryFetch() {
+    return createGuardedFetch();
+}
+export async function registrySearch(params, fetchImpl = defaultRegistryFetch()) {
+    const url = new URL(`${registryBaseUrl()}/api/search`);
+    url.searchParams.set("q", params.query);
+    if (params.kind) {
+        url.searchParams.set("kind", params.kind);
+    }
+    url.searchParams.set("limit", String(params.limit ?? 20));
+    const data = await fetchJson(url.toString(), fetchImpl);
+    return parseSearchResponse(data);
+}
+/**
+ * Load the registry's cached surface document for a domain (same facts as
+ * https://integrations.sh/{domain}/). Named "discover" for historical call
+ * sites; the upstream path is `/surface`, not the live `/discover` probe.
+ */
+export async function registryDiscover(domain, fetchImpl = defaultRegistryFetch()) {
+    const safeDomain = encodeURIComponent(domain.trim().toLowerCase());
+    const data = await fetchJson(`${registryBaseUrl()}/api/${safeDomain}/surface`, fetchImpl);
+    return {
+        parsed: parseSurfacePayload(data),
+        raw: (data ?? {}),
+    };
+}
+export { SUPPORTED_MCP_TRANSPORTS };

package/apps/runtime/dist/engenty/connections-external/registry-source.js

@@ -0,0 +1,82 @@
+import { findSurfaceForSource, registryDiscover, registrySearch, } from "./registry-client.js";
+/**
+ * The registry publishes a service's surfaces twice: the per-domain catalog
+ * document (`/api/{domain}/surface`) carries the rich facts — required
+ * headers, URL variables, transports, credential mechanics — while the search
+ * catalog carries a summary per surface, and today it is the search view that
+ * carries the `specOverrides` corrections. Neither is a superset.
+ *
+ * `resolveRegistrySource` takes the two facts the caller is allowed to supply
+ * — domain and source URL — and re-derives one surface from both views by
+ * exact URL match. Nothing is matched fuzzily: a correction published against
+ * one spec URL is never applied to a different one.
+ */
+/** Catalog `kind` values mapped onto surface-document `type` values. */
+function catalogKindToSurfaceKind(kind) {
+    return kind === "openapi" ? "http" : kind;
+}
+/** A search-catalog surface expressed in the surface-document shape. */
+function surfaceFromCatalog(entry) {
+    if (!entry.url) {
+        return null;
+    }
+    const kind = catalogKindToSurfaceKind(entry.kind);
+    return {
+        auth: {
+            entries: [],
+            // The catalog states only whether a credential is needed, never how it
+            // rides the request — `mapAuth` falls back to the spec and OAuth facts.
+            status: entry.auth?.kind === "none" ? "none" : "unknown",
+        },
+        connect_url: kind === "http" ? null : entry.url,
+        docs: null,
+        kind,
+        name: null,
+        required_headers: [],
+        slug: entry.slug,
+        spec: kind === "http" ? entry.url : null,
+        spec_alternates: [],
+        spec_overrides: entry.specOverrides,
+        transports: [],
+        variables: [],
+    };
+}
+function catalogSurfacesForDomain(results, domain) {
+    const wanted = domain.trim().toLowerCase();
+    return results
+        .filter((result) => result.domain.trim().toLowerCase() === wanted)
+        .flatMap((result) => result.surfaces);
+}
+/**
+ * Resolve the registry surface behind `sourceUrl`. Registry lookups are best
+ * effort: a registry outage degrades an import to a plain URL import rather
+ * than failing it.
+ */
+export async function resolveRegistrySource(params) {
+    const [discover, searchResults] = await Promise.all([
+        registryDiscover(params.domain, params.fetchImpl).catch(() => null),
+        registrySearch({ limit: 10, query: params.domain }, params.fetchImpl).catch(() => []),
+    ]);
+    const documentSurface = discover
+        ? findSurfaceForSource(discover.parsed, params.sourceUrl)
+        : null;
+    const catalogEntry = catalogSurfacesForDomain(searchResults, params.domain).find((entry) => entry.url === params.sourceUrl.trim());
+    if (!documentSurface) {
+        return {
+            discover,
+            surface: catalogEntry ? surfaceFromCatalog(catalogEntry) : null,
+        };
+    }
+    if (documentSurface.spec_overrides.length > 0 || !catalogEntry) {
+        return { discover, surface: documentSurface };
+    }
+    // Same URL in both views: take the document's facts and the catalog's
+    // corrections.
+    return {
+        discover,
+        surface: {
+            ...documentSurface,
+            spec_overrides: catalogEntry.specOverrides,
+        },
+    };
+}

package/apps/runtime/dist/engenty/connections-external/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared shapes for imported external connectors. The importer normalizes an
+ * OpenAPI spec or MCP tool list into `NormalizedAction[]` at import time; the
+ * stored record is the single source the boot path registers from — no spec
+ * re-parsing (and no executor/Effect code) runs at boot or execute time.
+ */
+export {};

package/apps/runtime/dist/engenty/connections-github/connector.js

@@ -0,0 +1,209 @@
+import { defineConnector, } from "../shims/connections-sdk.js";
+import { z } from "zod";
+/**
+ * The GitHub connector exposes the repository + pull-request surface the hosted
+ * coder needs. Deliberately NARROW in v1:
+ *
+ * - read actions (`repos_list`, `repo_get`, `pr_get`) are auto-allowed and,
+ *   because they are low-risk, are reachable from Code Mode's read-only execute.
+ * - `pr_create` is the sole `write` action (approval-gated by the connections
+ *   policy) — the human sign-off on delivering a coder's work as a PR.
+ *
+ * The clone/push CREDENTIAL is intentionally NOT a connector action: read
+ * actions are reachable from Code Mode (any low-risk catalog op can be invoked
+ * there), so returning a raw token as an action output would leak it into an
+ * agent-visible surface. The coder's repo checkout obtains its token through a
+ * dedicated, non-gateway core route instead (see PLAN-engenty-coder Phase 2).
+ *
+ * The single `repo` OAuth scope is requested up front (via `baseScopes`) so
+ * enabling `pr_create` later never forces a re-consent.
+ */
+const GITHUB_API_BASE = "https://api.github.com";
+const GITHUB_API_VERSION = "2022-11-28";
+/** GitHub returns application-level failures as non-2xx with a JSON `message`. */
+async function githubApi(ctx, path, init) {
+    const response = await ctx.fetchImpl(`${GITHUB_API_BASE}${path}`, {
+        method: init?.method ?? "GET",
+        headers: {
+            accept: "application/vnd.github+json",
+            authorization: `Bearer ${ctx.accessToken}`,
+            "x-github-api-version": GITHUB_API_VERSION,
+            ...(init?.body === undefined
+                ? {}
+                : { "content-type": "application/json" }),
+        },
+        ...(init?.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+    });
+    if (!response.ok) {
+        let message = `${response.status}`;
+        try {
+            const data = (await response.json());
+            if (data.message) {
+                message = `${data.message} (${response.status})`;
+            }
+        }
+        catch {
+            // Non-JSON error body; fall back to the status code.
+        }
+        throw new Error(`github_api_error: ${message}`);
+    }
+    return (await response.json());
+}
+function mapRepo(repo) {
+    return {
+        default_branch: repo.default_branch ?? "",
+        description: repo.description ?? null,
+        full_name: repo.full_name ?? "",
+        html_url: repo.html_url ?? "",
+        private: repo.private ?? false,
+    };
+}
+function mapPull(pull) {
+    return {
+        base: pull.base?.ref ?? "",
+        head: pull.head?.ref ?? "",
+        html_url: pull.html_url ?? "",
+        merged: pull.merged ?? false,
+        number: pull.number ?? 0,
+        state: pull.state ?? "",
+        title: pull.title ?? "",
+    };
+}
+const repoFullName = z
+    .string()
+    .regex(/^[^/\s]+\/[^/\s]+$/, "Expected 'owner/repo'.")
+    .describe("Repository in 'owner/repo' form (e.g. engenty/engenty).");
+const listReposInput = z.object({
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Maximum repositories to return (1-50, default 30)."),
+});
+const getRepoInput = z.object({ repo: repoFullName });
+const getPullInput = z.object({
+    repo: repoFullName,
+    number: z.number().int().positive().describe("Pull request number."),
+});
+const createPullInput = z.object({
+    repo: repoFullName,
+    title: z.string().min(1).describe("Pull request title."),
+    head: z
+        .string()
+        .min(1)
+        .describe("Name of the branch with the changes (e.g. coder/task-123)."),
+    base: z
+        .string()
+        .min(1)
+        .describe("Branch to merge into (e.g. the repository default branch)."),
+    body: z.string().optional().describe("Pull request description (Markdown)."),
+    draft: z
+        .boolean()
+        .optional()
+        .describe("Open the pull request as a draft (default false)."),
+});
+const actions = [
+    {
+        description: "List repositories the connected GitHub account can access, most recently updated first.",
+        group: "read",
+        handler: async (input, ctx) => {
+            const args = listReposInput.parse(input);
+            const repos = await githubApi(ctx, `/user/repos?per_page=${args.limit ?? 30}&sort=updated&affiliation=owner,collaborator,organization_member`);
+            return { repositories: repos.map(mapRepo) };
+        },
+        id: "repos_list",
+        inputSchema: listReposInput,
+        providerScopes: [],
+        summary: "List GitHub repositories",
+    },
+    {
+        description: "Fetch metadata for a single repository (default branch, visibility).",
+        group: "read",
+        handler: async (input, ctx) => {
+            const args = getRepoInput.parse(input);
+            const repo = await githubApi(ctx, `/repos/${args.repo}`);
+            return mapRepo(repo);
+        },
+        id: "repo_get",
+        inputSchema: getRepoInput,
+        providerScopes: [],
+        summary: "Get a GitHub repository",
+    },
+    {
+        description: "Fetch a pull request by number (state, branches, merge status, URL).",
+        group: "read",
+        handler: async (input, ctx) => {
+            const args = getPullInput.parse(input);
+            const pull = await githubApi(ctx, `/repos/${args.repo}/pulls/${args.number}`);
+            return mapPull(pull);
+        },
+        id: "pr_get",
+        inputSchema: getPullInput,
+        providerScopes: [],
+        summary: "Get a GitHub pull request",
+    },
+    {
+        description: "Open a pull request from an already-pushed head branch into a base branch.",
+        group: "write",
+        handler: async (input, ctx) => {
+            const args = createPullInput.parse(input);
+            const pull = await githubApi(ctx, `/repos/${args.repo}/pulls`, {
+                method: "POST",
+                body: {
+                    title: args.title,
+                    head: args.head,
+                    base: args.base,
+                    ...(args.body === undefined ? {} : { body: args.body }),
+                    ...(args.draft === undefined ? {} : { draft: args.draft }),
+                },
+            });
+            return mapPull(pull);
+        },
+        id: "pr_create",
+        inputSchema: createPullInput,
+        providerScopes: [],
+        summary: "Create a GitHub pull request",
+    },
+];
+export const githubConnector = defineConnector({
+    actions,
+    auth: {
+        kind: "oauth2",
+        oauth2: {
+            authUrl: "https://github.com/login/oauth/authorize",
+            // `repo` up front so enabling pr_create later never forces re-consent.
+            baseScopes: ["repo"],
+            clientIdEnv: "GITHUB_OAUTH_CLIENT_ID",
+            clientSecretEnv: "GITHUB_OAUTH_CLIENT_SECRET",
+            resolveAccount: async (accessToken, fetchImpl) => {
+                const response = await fetchImpl(`${GITHUB_API_BASE}/user`, {
+                    headers: {
+                        accept: "application/vnd.github+json",
+                        authorization: `Bearer ${accessToken}`,
+                        "x-github-api-version": GITHUB_API_VERSION,
+                    },
+                });
+                if (!response.ok) {
+                    throw new Error(`github_http_error: /user returned ${response.status}`);
+                }
+                const data = (await response.json());
+                return {
+                    label: data.login ?? "GitHub",
+                    ...(data.id ? { externalId: String(data.id) } : {}),
+                };
+            },
+            scopeSeparator: " ",
+            // GitHub returns a form-encoded token body unless JSON is requested.
+            tokenRequestHeaders: { accept: "application/json" },
+            tokenUrl: "https://github.com/login/oauth/access_token",
+        },
+    },
+    description: "GitHub access as the connected account: repositories and pull requests.",
+    icon: "logo:github",
+    id: "github",
+    moduleId: "connections-github",
+    name: "GitHub",
+    toolPrefix: "github",
+});