@clien-ai/mcp 0.2.1 → 0.4.0

package/dist/tools/param-aliases.js

@@ -0,0 +1,144 @@
+/**
+ * Backward-compatible camelCase → snake_case parameter aliasing (FUL-233).
+ *
+ * The tool surface settled on snake_case params (`project_id`, `persona_id`,
+ * `job_id`, …) as every read tool landed, but five older write tools still
+ * advertised camelCase (`projectId`, `companySize`, `groundInEvidence`, …).
+ * A public API cannot simply rename those: `@clien-ai/mcp` is published to npm
+ * and existing callers pass the old spellings. So each legacy name survives as
+ * a DEPRECATED ALIAS while snake_case becomes the documented form.
+ *
+ * How it fits together — three pieces, one source of truth per tool:
+ *
+ *   1. The tool's Zod schema declares the canonical snake_case field normally,
+ *      plus the camelCase alias via `deprecatedAlias()`. Declaring the alias is
+ *      load-bearing, not cosmetic: `zodToInputSchema` stamps
+ *      `additionalProperties: false` on every advert, so an UNDECLARED alias
+ *      would be a field the schema publicly disowns while the server quietly
+ *      honours it — and strict MCP clients would drop it before it ever reached
+ *      us. Declared, the advert and the runtime tell the same story.
+ *   2. The registry entry carries the matching `paramAliases` map, and
+ *      `defineTool` wraps the handler with `normalizeParamAliases` — so a tool
+ *      cannot forget to call it, and handlers only ever see canonical keys.
+ *   3. `__tests__/param-aliases.test.ts` binds (1) to (2): every camelCase
+ *      property advertised by any registry tool must appear in that tool's
+ *      alias map, and vice versa. Adding one without the other fails there
+ *      rather than silently advertising a param nothing honours.
+ *
+ * Normalization runs BEFORE `safeParse`, which is why the alias's declared Zod
+ * type never actually validates anything — by parse time the key is gone,
+ * rewritten onto its canonical name. It exists purely so the advert is
+ * truthful. It still mirrors the canonical validator so a client reading the
+ * advert is not misled about what the alias accepts.
+ *
+ * Deliberately NOT a Zod `.refine()`/`.transform()`: those produce a
+ * `ZodEffects`, which has no `.shape`, and both `zodToInputSchema` and
+ * `__tests__/schema-contract.test.ts` depend on `.shape` (see the same note in
+ * `interview.ts` and `personas.ts`). Cross-field rules live in plain code.
+ *
+ * ── SCOPE OF THE COMPATIBILITY GUARANTEE ────────────────────────────────────
+ * An alias is honoured at `tools/call`, AND an alias-only payload is valid
+ * against the advertised schema. `required` no longer excludes alias-only calls.
+ *
+ * That second half was not free (FUL-238). An alias is a SEPARATE optional
+ * property, so it can never satisfy a `required` entry naming the canonical
+ * field — the two are different keys. The only way to make the advert accept
+ * what the runtime accepts was to drop the canonical id from `required`
+ * entirely: the three aliased ids (`create_persona` / `generate_persona`
+ * `project_id`, `enrich_persona` `persona_id`) are declared `.optional()` and
+ * their presence is enforced in the handler by `requireId` in `personas.ts` —
+ * the convention `interview_persona` (per-action ids) and `update_persona`
+ * (at-least-one-field) already use. `interview_persona`'s three ids were always
+ * this way, so they never had the gap.
+ *
+ * The trade, taken deliberately: every caller loses the advert's machine-readable
+ * "this field is mandatory" signal for those ids, so each one says REQUIRED in
+ * its `.describe()` prose and a missing id fails with a clear handler error
+ * naming the canonical param — before any HTTP call. In exchange, no client can
+ * refuse a legacy caller's payload before sending it.
+ *
+ * `__tests__/param-aliases.test.ts` pins BOTH halves — the advert no longer
+ * listing those ids in `required`, and an alias-only call still reaching the
+ * real request — so neither can drift silently.
+ */
+import { ToolError } from './errors.js';
+/**
+ * Declare a deprecated camelCase alias property for a tool's Zod schema.
+ *
+ * Pass the canonical field's BASE validator (before `.optional()`): the alias
+ * is always optional regardless of whether the canonical field is required, so
+ * a caller may supply either one.
+ */
+export function deprecatedAlias(canonical, schema) {
+    return schema
+        .optional()
+        .describe(`DEPRECATED alias for \`${canonical}\` — pass \`${canonical}\` instead. ` +
+        'Still accepted for backward compatibility. Passing both this and ' +
+        `\`${canonical}\` with DIFFERENT values is rejected.`);
+}
+/** A key counts as supplied when present and not `undefined` (explicit `null` counts). */
+function isSupplied(source, key) {
+    return key in source && source[key] !== undefined;
+}
+/**
+ * Whether two supplied values are interchangeable. Aliased params are strings
+ * and booleans today; the JSON fallback keeps the check correct if one ever
+ * becomes structured, and never throws (both values came off a JSON payload).
+ */
+function sameValue(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object')
+        return false;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Rewrite any supplied camelCase aliases onto their canonical snake_case names.
+ *
+ * Returns the input untouched (same reference) when no alias is present, so the
+ * overwhelmingly common modern call path allocates nothing. Non-object input is
+ * passed straight through — the tool's own `safeParse` owns that error message.
+ *
+ * Supplying BOTH spellings of one field is only an error when the values
+ * DIFFER: a caller that sends the same value twice is unambiguous, and failing
+ * it would break a belt-and-braces caller for no safety gain. Differing values
+ * are genuinely ambiguous, so we refuse rather than pick a winner — silently
+ * preferring one would send a persona edit to whichever project the caller
+ * did NOT mean.
+ *
+ * @throws {ToolError} when one field is supplied under both names with
+ *   different values.
+ */
+export function normalizeParamAliases(input, aliases) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        return input;
+    const source = input;
+    const supplied = Object.keys(aliases).filter((alias) => isSupplied(source, alias));
+    if (supplied.length === 0)
+        return input;
+    const out = { ...source };
+    for (const alias of supplied) {
+        const canonical = aliases[alias];
+        const aliasValue = source[alias];
+        const canonicalSupplied = isSupplied(source, canonical);
+        // A `null` alias alongside a real canonical value is a JSON-shaped "unset",
+        // not a competing answer — dropping it is unambiguous, so refusing the call
+        // would fail a caller who is not actually contradicting themselves. Left
+        // alone when the alias is the ONLY spelling supplied, so the canonical
+        // field's own Zod error ("expected string, received null") still surfaces.
+        if (aliasValue === null && canonicalSupplied && source[canonical] !== null) {
+            delete out[alias];
+            continue;
+        }
+        if (canonicalSupplied && !sameValue(source[canonical], aliasValue)) {
+            throw new ToolError(`Invalid input — \`${canonical}\` and its deprecated alias \`${alias}\` were both ` +
+                `provided with different values. Pass only \`${canonical}\`.`);
+        }
+        out[canonical] = aliasValue;
+        delete out[alias];
+    }
+    return out;
+}
+//# sourceMappingURL=param-aliases.js.map

package/dist/tools/param-aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-aliases.js","sourceRoot":"","sources":["../../src/tools/param-aliases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAKvC;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAiB,EACjB,MAAoB;IAEpB,OAAO,MAAM;SACV,QAAQ,EAAE;SACV,QAAQ,CACP,0BAA0B,SAAS,eAAe,SAAS,cAAc;QACvE,mEAAmE;QACnE,KAAK,SAAS,uCAAuC,CACxD,CAAA;AACL,CAAC;AAED,0FAA0F;AAC1F,SAAS,UAAU,CAAC,MAA+B,EAAE,GAAW;IAC9D,OAAO,GAAG,IAAI,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAA;AACnD,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,CAAU,EAAE,CAAU;IACvC,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAChC,IAAI,OAAO,CAAC,KAAK,OAAO,CAAC;QAAE,OAAO,KAAK,CAAA;IACvC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACvC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;AAChD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,OAAiB;IACrE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAErF,MAAM,MAAM,GAAG,KAAgC,CAAA;IAC/C,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;IAClF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEvC,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,EAAE,CAAA;IACzB,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAE,CAAA;QACjC,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAChC,MAAM,iBAAiB,GAAG,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;QAEvD,4EAA4E;QAC5E,4EAA4E;QAC5E,yEAAyE;QACzE,uEAAuE;QACvE,2EAA2E;QAC3E,IAAI,UAAU,KAAK,IAAI,IAAI,iBAAiB,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC;YAC3E,OAAO,GAAG,CAAC,KAAK,CAAC,CAAA;YACjB,SAAQ;QACV,CAAC;QAED,IAAI,iBAAiB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,SAAS,CACjB,qBAAqB,SAAS,iCAAiC,KAAK,eAAe;gBACjF,+CAA+C,SAAS,KAAK,CAChE,CAAA;QACH,CAAC;QACD,GAAG,CAAC,SAAS,CAAC,GAAG,UAAU,CAAA;QAC3B,OAAO,GAAG,CAAC,KAAK,CAAC,CAAA;IACnB,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}