@wootsup/mcp 0.1.0-rc.9 → 0.1.0

package/dist/modules/apimapper/connections-trim.js

@@ -0,0 +1,224 @@
+// src/modules/apimapper/connections-trim.ts — pure trim + shape-detect helpers.
+//
+// W3 Stage-2 hardening (rc.13 Welle 3) — extracted verbatim from
+// connections.ts (which had grown to 945 lines, above the ~650-line
+// module-size guideline). `applyTrim` + `extractResourceList` are
+// pre-existing pure functions (F-01/F-38 nested-shape trim and the
+// connection_resources wire-shape normaliser) — no behaviour change, this
+// is a mechanical move so connections.ts stays a lean tool-registration
+// surface. The existing connections.test.ts pins prove equivalence.
+//
+// MODULE-SIZE GUIDELINE — POST-W3 STANCE (F-1.5, Pass-1 consolidation)
+// ====================================================================
+// The original ~600/650-line ceiling was the pre-W3 target for any single
+// MCP tool-registration module. Post-W3 the practical ceiling for a
+// tool-registration module is ~900 lines once handler bodies stay co-located
+// with the registration site. The 5 *-format.ts siblings
+// (connections-format.ts, credentials-format.ts, flows-format.ts,
+// license-format.ts, settings-format.ts) hold the per-tool result builders;
+// pure helpers (this file's applyTrim/extractResourceList, the credential
+// sanitiser, node-schema, envelope, etc.) have been peeled off separately.
+// Further extraction at this point would either:
+//
+//   (a) split a handler from its `registerTool(...)` call-site, hurting
+//       readability for no measurable benefit, OR
+//   (b) duplicate the tool-registration concerns across files (every
+//       extracted handler would still have to thread the same `request`,
+//       `hintFor`, elicitation capability, format helpers, and capturing
+//       server — collapsing the module without simplifying it).
+//
+// Therefore: connections.ts (881), flows.ts (794), library.ts (658),
+// onboarding.ts (603) exceeding the ~600/650 guideline is a documented
+// trade-off, not a backlog item. New tool registrations belong with their
+// domain peers; new pure helpers go into a sibling file. This is the
+// canonical decision-record location — referenced from the post-W3 audit
+// log (Stage 1 / Finding F-1.5).
+//
+// Both functions are re-exported from connections.ts so the public surface
+// (`import { applyTrim, extractResourceList } from "./connections.js"`)
+// is unchanged for existing callers and tests.
+/**
+ * Pure trim + shape-detect for connection_data payloads.
+ *
+ * Extracted from the connection_data handler (W1.2 polish-2) so the
+ * shallow-clone contract for nested-items envelopes can be unit-tested
+ * directly, without going through the wire-roundtrip handler layer
+ * (where stubFetch's JSON.stringify masks reference identity).
+ *
+ * Detection rules (BEFORE trim):
+ * - `array`: `inner` is an Array — slice it directly when trim args are
+ *   present; otherwise returned as-is.
+ * - `nested_items`: `inner` is an object whose `items` field is an Array
+ *   — shallow-clone the envelope and slice the cloned items array. The
+ *   shallow-clone is load-bearing: if a caller passes a cached envelope
+ *   reference, mutating `.items` in place would corrupt the cache for
+ *   subsequent reads.
+ * - `other`: neither of the above — return as-is, `itemCount` undefined.
+ *
+ * Strict-trim contract: `trimmed: true` and `totalBeforeTrim` are only
+ * surfaced when the slice actually cut content (`sliced.length !==
+ * source.length`). `limit > length` returns `trimmed: undefined`
+ * (truth-in-advertising — no false-positive pagination signals).
+ *
+ * Defense-in-depth: negative AND non-finite (NaN, ±Infinity) `limit`/
+ * `offset` are clamped to 0 at the function boundary.
+ * `Number.isFinite()` returns false for NaN/Infinity/-Infinity —
+ * providing a clean "is this a usable trim integer?" guard. Combined
+ * with the `>= 0` check, any invalid input (negative, NaN, Infinity)
+ * deterministically maps to 0 = "trim to empty". `applyTrim` is an
+ * exported public surface, so the caller is not guaranteed to be the
+ * Zod-validated handler.
+ *
+ * Schema-vs-contract asymmetry: this function-level contract treats
+ * `limit=0` as a valid "explicit empty payload" signal. The MCP tool
+ * surface (Zod schema) enforces `.min(1).max(500)` and therefore
+ * rejects `limit=0` before it reaches `applyTrim`. The permissive
+ * function contract is intentionally broader than the wire contract;
+ * `limit=0` is only reachable by direct programmatic callers (e.g.
+ * unit tests, internal pipeline composers), not by AI clients hitting
+ * the MCP tool.
+ *
+ * @param inner - REST inner payload (post-envelope-unwrap, untyped)
+ * @param limit - Max items to return after offset; `undefined` = no trim,
+ *   `0` = explicit empty payload, negative/non-finite values clamp to 0.
+ *   NOTE: the MCP tool's Zod schema (`.min(1).max(500)`) rejects `0` at
+ *   the wire boundary — `limit=0` is only reachable via direct
+ *   programmatic callers, not AI clients.
+ * @param offset - Skip items before slice; `undefined` = 0,
+ *   negative/non-finite values clamp to 0
+ * @returns Trim result with `detectedShape`, `payload` (potentially
+ *   sliced), `itemCount`, `totalBeforeTrim`, and `trimmed` metadata
+ */
+export function applyTrim(inner, limit, offset) {
+    // Defense-in-depth: clamp negative AND non-finite (NaN, ±Infinity)
+    // limit/offset to 0. Number.isFinite() returns false for NaN/Infinity/
+    // -Infinity — providing a clean "is this a usable trim integer?"
+    // guard. Combined with the >= 0 check, any invalid input (negative,
+    // NaN, Infinity) deterministically maps to 0 = "trim to empty".
+    // Rationale: NaN < 0 evaluates to false (regular comparison rules),
+    // so a naive `< 0` check would let NaN fall through to Array.slice
+    // (which coerces NaN → 0 and returns []) — coincidentally safe but
+    // misleading because `trimmed: true` would still surface. Same for
+    // Infinity, which slice would treat as "no upper bound" (returning
+    // the full array but marking trimmed=false-by-accident). Treating
+    // both as "invalid → 0" yields a single consistent contract.
+    const safeLimit = limit === undefined
+        ? undefined
+        : Number.isFinite(limit) && limit >= 0
+            ? limit
+            : 0;
+    const safeOffset = offset === undefined
+        ? undefined
+        : Number.isFinite(offset) && offset >= 0
+            ? offset
+            : 0;
+    const hasTrimArgs = safeLimit !== undefined || safeOffset !== undefined;
+    if (Array.isArray(inner)) {
+        const arr = inner;
+        if (hasTrimArgs) {
+            const start = safeOffset ?? 0;
+            const end = safeLimit !== undefined ? start + safeLimit : undefined;
+            const sliced = arr.slice(start, end);
+            if (sliced.length !== arr.length) {
+                return {
+                    payload: sliced,
+                    detectedShape: "array",
+                    itemCount: sliced.length,
+                    totalBeforeTrim: arr.length,
+                    trimmed: true,
+                };
+            }
+            return {
+                payload: sliced,
+                detectedShape: "array",
+                itemCount: sliced.length,
+                totalBeforeTrim: undefined,
+                trimmed: undefined,
+            };
+        }
+        return {
+            payload: arr,
+            detectedShape: "array",
+            itemCount: arr.length,
+            totalBeforeTrim: undefined,
+            trimmed: undefined,
+        };
+    }
+    if (inner !== null &&
+        typeof inner === "object" &&
+        Array.isArray(inner.items)) {
+        const innerObj = inner;
+        const nestedItems = innerObj.items;
+        if (hasTrimArgs) {
+            const start = safeOffset ?? 0;
+            const end = safeLimit !== undefined ? start + safeLimit : undefined;
+            const sliced = nestedItems.slice(start, end);
+            // Shallow-clone — never mutate the caller's envelope object.
+            const cloned = { ...innerObj, items: sliced };
+            if (sliced.length !== nestedItems.length) {
+                return {
+                    payload: cloned,
+                    detectedShape: "nested_items",
+                    itemCount: sliced.length,
+                    totalBeforeTrim: nestedItems.length,
+                    trimmed: true,
+                };
+            }
+            return {
+                payload: cloned,
+                detectedShape: "nested_items",
+                itemCount: sliced.length,
+                totalBeforeTrim: undefined,
+                trimmed: undefined,
+            };
+        }
+        return {
+            payload: innerObj,
+            detectedShape: "nested_items",
+            itemCount: nestedItems.length,
+            totalBeforeTrim: undefined,
+            trimmed: undefined,
+        };
+    }
+    return {
+        payload: inner,
+        detectedShape: "other",
+        itemCount: undefined,
+        totalBeforeTrim: undefined,
+        trimmed: undefined,
+    };
+}
+/**
+ * A1-P3-1: pure helper that normalises the three wire-shapes the
+ * `apimapper_connection_resources` REST endpoint can return:
+ *
+ *   1. bare array — `[{...}, {...}]`
+ *   2. `{ resources: [...] }` envelope (canonical post-Wave-1B)
+ *   3. `{ items: [...] }` envelope (legacy / library-style)
+ *
+ * Anything else (null, primitive, foreign-shaped object) resolves to
+ * `[]` rather than throwing — the handler then renders `resource_count:
+ * 0` and the AI client knows the picker is empty. Throwing here would
+ * leak an opaque type-error out of the tool surface.
+ *
+ * Precedence is `bare-array > resources > items`. The `resources`-over-
+ * `items` order is pinned in connections.test.ts because callers like
+ * the ResourcePicker rely on the canonical field winning when servers
+ * accidentally emit both (defensive against backend drift).
+ *
+ * Exported so the test suite can pin each branch atomically without
+ * going through the wire-roundtrip handler layer.
+ */
+export function extractResourceList(data) {
+    if (Array.isArray(data))
+        return data;
+    if (data !== null && typeof data === "object") {
+        const obj = data;
+        if (Array.isArray(obj.resources))
+            return obj.resources;
+        if (Array.isArray(obj.items))
+            return obj.items;
+    }
+    return [];
+}
+//# sourceMappingURL=connections-trim.js.map

package/dist/modules/apimapper/connections-trim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections-trim.js","sourceRoot":"","sources":["../../../src/modules/apimapper/connections-trim.ts"],"names":[],"mappings":"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"}

package/dist/modules/apimapper/connections.d.ts

@@ -1,2 +1,14 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerConnectionTools(server: McpServer): void;
+import type { ToolRegistrar } from "./gateway/capturing-server.js";
+import { type McpServerWithElicitation } from "./elicitation.js";
+import { applyTrim, extractResourceList, type ApplyTrimResult } from "./connections-trim.js";
+export { applyTrim, extractResourceList, type ApplyTrimResult };
+/**
+ * Register the connection CRUD + probe + sample + pipeline tools.
+ *
+ * @param server      the tool registrar (essentials forward, rest captured).
+ * @param elicitation optional elicitation capability (the real McpServer, or
+ *   any `{ server: { elicitInput } }`). Supplied only by the host wiring in
+ *   index.ts. When omitted, `connection_create` falls back to a structured
+ *   error on genuine credential ambiguity instead of prompting.
+ */
+export declare function registerConnectionTools(server: ToolRegistrar, elicitation?: McpServerWithElicitation): void;