@zackbart/connecta 0.34.1 → 0.35.0

package/dist/provider.js

@@ -1,10 +1,7 @@
-// The one shape every maintained provider takes. Deliberately transport-free:
-// it imports neither `remoteMcp()` nor `api()`, so an `api()` provider does not
-// acquire the MCP client, OAuth, or Effect graph by using it, and a hosted
-// provider does not acquire `api()`. Its runtime imports validate plain
-// options and reviewed classification, with no I/O.
+// Transport-free maintained API provider definitions and construction validation.
 import { array, assertKnownOptions, ConfigError, fn, keys, object, opaque, required, whole, } from "./config-schema.js";
-import { reviewedClassification } from "./catalog-drift.js";
+import { aliasCallIdentity } from "./provider-call-facts.js";
+import { isConnectorCallErrorCode } from "./errors.js";
 const budget = {
     ...object({
         kind: required(opaque({
@@ -64,10 +61,75 @@ export const PROVIDER_COMMON = {
     callAdmission: CALL_ADMISSION,
 };
 const PROVIDER_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const KINDS = new Set(["mcp", "api", "composed", "dual"]);
+const BLOCK_KEY = /^[a-z][a-z0-9:-]*$/;
+/** A when-block marker, alone on its line. */
+const BLOCK_MARKER = /^<!--\s*(?:when:\s*([a-z][a-z0-9:-]*)|end)\s*-->$/;
 function nonEmpty(value) {
     return typeof value === "string" && value.trim() !== "";
 }
+/**
+ * Render a guide's selected when-blocks, or, with no selection, check them
+ * and return their keys. Markers stand alone on their lines and never nest.
+ * Removing an unselected block also removes the blank line it leaves, so
+ * paragraphs and tight lists keep their spacing.
+ */
+function guideBlocks(content, selected) {
+    const keys = new Set();
+    const kept = [];
+    let open;
+    let seam = false;
+    for (const line of content.split("\n")) {
+        const marker = BLOCK_MARKER.exec(line.trim());
+        if (marker) {
+            if (marker[1] !== undefined ? open !== undefined : open === undefined) {
+                throw new Error("when-blocks must open and close in turn, unnested");
+            }
+            if (marker[1] !== undefined)
+                keys.add((open = marker[1]));
+            else {
+                seam = selected !== undefined && !selected.has(open);
+                open = undefined;
+            }
+            continue;
+        }
+        if (/<!--\s*(?:when:|end\s*-->)/.test(line))
+            throw new Error("a when-block marker stands alone on its line");
+        if (open !== undefined && !selected?.has(open))
+            continue;
+        if (seam && !line.trim() && (kept.length === 0 || !kept.at(-1).trim()))
+            continue;
+        seam = false;
+        kept.push(line);
+    }
+    if (open !== undefined)
+        throw new Error(`the when-block "${open}" is never closed`);
+    return { text: kept.join("\n").trim(), keys };
+}
+/** A frozen copy: kit facts are review evidence `providers:generate` reads. */
+function kitFacts(kit) {
+    if (kit.errors && !isConnectorCallErrorCode(kit.errors.unknownId)) {
+        throw new Error("Provider kit errors.unknownId must be a ConnectorCallErrorCode.");
+    }
+    return Object.freeze({
+        operations: Object.freeze([...kit.operations]),
+        ...(kit.pageSize ? { pageSize: Object.freeze({ ...kit.pageSize }) } : {}),
+        ...(kit.hatch
+            ? {
+                hatch: Object.freeze({
+                    name: kit.hatch.name,
+                    verdicts: Object.freeze({ ...kit.hatch.verdicts }),
+                    ...(kit.hatch.paging ? { paging: kit.hatch.paging } : {}),
+                    ...(kit.hatch.fieldsRoot ? { fieldsRoot: kit.hatch.fieldsRoot } : {}),
+                }),
+            }
+            : {}),
+        ...(kit.errors
+            ? { errors: Object.freeze({ ...kit.errors, conflicts: Object.freeze([...kit.errors.conflicts]) }) }
+            : {}),
+        ...(kit.idempotencyKey !== undefined ? { idempotencyKey: kit.idempotencyKey } : {}),
+        ...(kit.refusesWithheld ? { refusesWithheld: true } : {}),
+    });
+}
 /**
  * Define a maintained provider: one validated description and one factory.
  *
@@ -83,23 +145,37 @@ export function defineProvider(definition) {
     if (!nonEmpty(definition.title)) {
         throw new Error(`${label} requires a non-empty title.`);
     }
-    if (!KINDS.has(definition.kind)) {
-        throw new Error(`${label} kind must be "mcp", "api", "composed", or "dual".`);
-    }
+    if (definition.kind !== "api")
+        throw new Error(`${label} kind must be "api".`);
     if (!nonEmpty(definition.skill?.content) || !nonEmpty(definition.skill.instructionsHeading)) {
         throw new Error(`${label} skill requires non-empty content and instructionsHeading.`);
     }
-    if (definition.classify !== undefined && definition.kind === "api") {
-        throw new Error(`${label} is an api() provider; annotate each authored tool instead of classifying a hosted catalog.`);
-    }
+    if (Object.hasOwn(definition, "classify"))
+        throw new Error(`${label} classify was removed; use ConnectaConfig.classification.`);
     if (!definition.options?.shape && !definition.options?.variants) {
         throw new Error(`${label} requires a closed options shape from optionsOf().`);
     }
-    // A validated, deep-frozen copy. The definition is what build and check
-    // tools read and what every later connector classifies with, so nothing
-    // reachable from it may change a verdict after review: neither the
-    // caller's original object nor a write through `factory.definition`.
-    const classify = definition.classify === undefined ? undefined : reviewedClassification(definition.classify, label);
+    const blocks = definition.blocks;
+    if (blocks !== undefined &&
+        (!Array.isArray(blocks.keys) ||
+            blocks.keys.length === 0 ||
+            !blocks.keys.every((key) => typeof key === "string" && BLOCK_KEY.test(key)) ||
+            new Set(blocks.keys).size !== blocks.keys.length ||
+            typeof blocks.select !== "function")) {
+        throw new Error(`${label} blocks require unique lowercase keys and a select function.`);
+    }
+    let used;
+    try {
+        used = guideBlocks(definition.skill.content).keys;
+    }
+    catch (error) {
+        throw new Error(`${label} skill: ${error instanceof Error ? error.message : String(error)}.`, { cause: error });
+    }
+    for (const key of used) {
+        if (!blocks?.keys.includes(key))
+            throw new Error(`${label} skill uses the when-block "${key}" its blocks omit.`);
+    }
+    // Freeze definition facts consumed by construction, generation and checks.
     if (typeof definition.create !== "function") {
         throw new Error(`${label} requires a create function.`);
     }
@@ -110,7 +186,8 @@ export function defineProvider(definition) {
             ...(definition.skill.fragments ? { fragments: Object.freeze(definition.skill.fragments) } : {}),
         }),
         ...(definition.bundle ? { bundle: Object.freeze({ ...definition.bundle }) } : {}),
-        ...(classify !== undefined ? { classify } : {}),
+        ...(blocks ? { blocks: Object.freeze({ keys: Object.freeze([...blocks.keys]), select: blocks.select }) } : {}),
+        ...(definition.kit ? { kit: kitFacts(definition.kit) } : {}),
     });
     const factoryName = `${frozen.name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())}()`;
     const factory = (id, options) => asProvider(frozen.name, frozen.options, id, options, (id, options) => {
@@ -133,7 +210,6 @@ export function defineProvider(definition) {
         const resolved = { ...options, purpose: options.purpose.trim() };
         const instructions = options.instructions?.trim();
         const connector = frozen.create(id, resolved, {
-            ...(frozen.classify !== undefined ? { classify: frozen.classify } : {}),
             connectorOptions: {
                 ...(options.readOnly !== undefined ? { readOnly: options.readOnly } : {}),
                 ...(options.authScope !== undefined ? { authScope: options.authScope } : {}),
@@ -142,7 +218,20 @@ export function defineProvider(definition) {
             },
             usageGuide(input) {
                 const heading = input.heading ?? `${frozen.title} usage`;
-                const body = [...input.context, frozen.skill.content.trim()].join("\n\n");
+                let guide = frozen.skill.content.trim();
+                if (frozen.blocks) {
+                    const { keys, select } = frozen.blocks;
+                    const selected = select(resolved);
+                    if (!Array.isArray(selected))
+                        throw new Error(`${at} requires blocks.select() to return an array of keys.`);
+                    for (const key of selected) {
+                        if (!keys.includes(key)) {
+                            throw new Error(`${at} requires blocks.select() to return declared keys; it returned ${String(key)}.`);
+                        }
+                    }
+                    guide = guideBlocks(frozen.skill.content, new Set(selected)).text;
+                }
+                const body = [...input.context, guide].join("\n\n");
                 return {
                     content: `# ${heading}\n\n${body}\n` +
                         (instructions ? `\n## ${frozen.skill.instructionsHeading}\n\n${instructions}\n` : ""),
@@ -156,28 +245,13 @@ export function defineProvider(definition) {
         }
         return connector;
     });
-    // Frozen whole: build and check tools read `definition` to learn what the
-    // factory classifies, so neither replacing nor deleting it may take effect.
-    return Object.freeze(Object.assign(factory, { definition: frozen }));
-}
-/**
- * Attach the same validated definition to an existing provider constructor.
- * Its option policy stays in its builder during the mechanical folder move;
- * adopting defineProvider's common-value policy is a separate conversion.
- */
-export function asProviderFactory(definition) {
-    const frozen = defineProvider(definition).definition;
-    const create = definition.create;
-    const factory = (id, options) => asProvider(frozen.name, frozen.options, id, options, create);
-    Object.defineProperty(factory, "name", {
-        value: frozen.name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()),
-    });
+    // Build and check tools rely on this definition remaining attached.
     return Object.freeze(Object.assign(factory, { definition: frozen }));
 }
 /**
  * Build a maintained provider's connector: refuse unknown options and
  * accessors by path before the builder reads any of them, then stamp the
- * provider onto its description, so the operator surface can say "Linear"
+ * provider onto its description, so the operator surface can say "Stripe"
  * rather than "remote MCP". This is the same construction path defineProvider
  * uses; existing constructors retain their provider-specific option policy.
  */
@@ -202,12 +276,15 @@ function asProvider(provider, shape, id, options, build) {
     const ownReadOnly = Object.getOwnPropertyDescriptor(connector, "readOnly");
     // Keep the receiver of prototype methods (including private fields). When
     // the description cannot be replaced, inherit the whole connector instead
-    // of copying it: decorators may inherit their id, methods, and review.
+    // of copying it: decorators may inherit their id and methods.
     const stamped = Object.isExtensible(connector) &&
         (!ownDescribe || ownDescribe.configurable) &&
         (options.readOnly === undefined || !ownReadOnly || ownReadOnly.configurable)
         ? connector
         : Object.create(connector);
+    // An inheriting stamp serves the connector itself, so it keeps its call identity.
+    if (stamped !== connector)
+        aliasCallIdentity(stamped, connector);
     if (options.readOnly !== undefined) {
         Object.defineProperty(stamped, "readOnly", { value: options.readOnly, enumerable: true, configurable: true });
     }

package/dist/providers/_shared/google/hatch.js

@@ -0,0 +1,91 @@
+// Opt-in plumbing only. Product PRs supply their reviewed literal verdicts.
+import { Effect } from "effect";
+import { ConnectorCallError } from "../../../errors.js";
+export function requireGoogleIndex(index) {
+    if (!index)
+        throw new Error("Google requests require their reviewed operation index.");
+    if (index.pathMatching !== "uri-template")
+        throw new Error('Google indexes require pathMatching: "uri-template".');
+}
+/** Independent of compact schema depth: only reviewed batch kinds can execute. */
+export function googleBatchGuard(body, options) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return "A Google batch body must be an object.";
+    const value = body;
+    const requests = value["requests"];
+    if (!Array.isArray(requests) || !requests.length || requests.length > (options.max ?? 100))
+        return `A Google batch needs 1–${options.max ?? 100} requests.`;
+    if (requests.some((request) => !request ||
+        typeof request !== "object" ||
+        Array.isArray(request) ||
+        Object.keys(request).length !== 1 ||
+        !options.kinds.includes(Object.keys(request)[0])))
+        return "Each Google batch request must contain exactly one reviewed request kind.";
+    const control = value["writeControl"];
+    if (options.revision &&
+        (!control || typeof control["requiredRevisionId"] !== "string" || !control["requiredRevisionId"].trim()))
+        return "This Google batch needs a nonempty writeControl.requiredRevisionId from a current read.";
+    return undefined;
+}
+/** Ensure a substituted named id still reaches the endpoint the tool declared. */
+export function googleNamedOperation(index, method, path, template) {
+    requireGoogleIndex(index);
+    if (index.resolve(method, path).op.path !== template)
+        throw new ConnectorCallError("invalid_args", "This Google id resolves to a different operation; no request was sent.");
+}
+export function googleHatchBinding(connection, options) {
+    requireGoogleIndex(options.index);
+    return {
+        index: options.index,
+        ...(options.wrapSend ? { warnings: true } : {}),
+        review: options.review,
+        ...(options.refusal ? { refusal: options.refusal } : {}),
+        refuse: (call) => {
+            for (const match of call.path.matchAll(/%([a-f0-9]{2})/gi))
+                if (/^[-A-Za-z0-9._~:]$/.test(String.fromCharCode(parseInt(match[1], 16))))
+                    return "Google paths must spell unreserved characters and action separators literally.";
+            if (call.headers && Object.keys(call.headers).length)
+                return "Google hatches do not accept caller headers.";
+            for (const key of Object.keys(call.query))
+                if ([
+                    "access_token",
+                    "oauth_token",
+                    "key",
+                    "callback",
+                    "upload_protocol",
+                    "uploadType",
+                    "userId",
+                    "quotaUser",
+                ].includes(key))
+                    return `Google query.${key} is owned by the deployment and cannot be selected by a caller.`;
+            if (call.query["alt"] !== undefined && call.query["alt"] !== "json")
+                return "Google hatches return JSON only; use a named content tool for media.";
+            return options.refuse?.(call);
+        },
+        send: (call, sendOptions) => Effect.suspend(() => {
+            // Capture the admitted wire request before the wrapper can inspect its copy.
+            const request = {
+                method: call.method,
+                path: call.path,
+                template: call.op.path,
+                query: Object.entries(call.query).flatMap(([name, value]) => value === undefined
+                    ? []
+                    : (Array.isArray(value) ? value : [value]).map((item) => [name, String(item)])),
+                headers: { accept: "application/json" },
+                ...(call.body === undefined ? {} : { json: JSON.stringify(call.body) }),
+            };
+            const optionsForSend = {
+                ...sendOptions,
+                ...(options.revisionGuarded?.(call) ? { flags: { revisionGuarded: true } } : {}),
+            };
+            let sent = false;
+            const send = () => Effect.suspend(() => {
+                if (sent)
+                    return Effect.die(new Error("A Google hatch wrapper may send its admitted request only once."));
+                sent = true;
+                return connection.sendPath(request, optionsForSend);
+            });
+            return options.wrapSend ? options.wrapSend(structuredClone(call), send) : send();
+        }),
+    };
+}