@lanes-sh/link 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "A self-hostable MCP gateway for all your connections, memory, skills, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://lanes.sh/link",

package/src/cli/commands/mcp/list.ts

@@ -1,8 +1,46 @@
-import { heading, print, style } from '../../output.ts';
+import { emit, heading, print, style } from '../../output.ts';
 import { assetState, plannedAssets, readAsset } from './assets.ts';
 import { HARNESSES, type Harness } from './harnesses.ts';
 import { exists } from './register.ts';
 
+/** Why a document this harness can hold is not what we ship, if it is not. */
+export type DocumentState = 'current' | 'stale' | 'missing' | 'unreadable';
+
+export interface ListedDocument {
+  readonly label: string;
+  readonly path: string;
+  readonly state: DocumentState;
+  /** Only for `unreadable` — what went wrong reading the bundled copy. */
+  readonly detail?: string;
+}
+
+export interface ListedHarness {
+  readonly id: string;
+  readonly label: string;
+  readonly installed: boolean;
+  /** The resolved binary, so a caller can see *which* claude answered. */
+  readonly binary: string | null;
+  readonly registered: boolean;
+  /**
+   * Empty when the harness is not installed, matching what the text rendering
+   * says: with no binary there is nothing to register the documents against, and
+   * reporting them would describe a setup that does not exist.
+   */
+  readonly documents: readonly ListedDocument[];
+}
+
+export interface McpListing {
+  readonly name: string;
+  readonly scope: string;
+  readonly harnesses: readonly ListedHarness[];
+}
+
+export interface McpListFlags {
+  readonly name?: string | undefined;
+  readonly scope?: string | undefined;
+  readonly json?: boolean | undefined;
+}
+
 /**
  * `lanes link mcp list` — where this endpoint is registered, and whether what
  * each harness has been told about it is still what we ship.
@@ -11,58 +49,114 @@ import { exists } from './register.ts';
  * different fixes. A registration without the skill is a working endpoint
  * nobody reaches for; a skill against no registration is a document describing
  * tools that are not there.
+ *
+ * The listing is gathered before anything is printed, so `--json` and the text
+ * rendering describe the same snapshot rather than two probes taken a moment
+ * apart. `--json` exists because this is the one command another program has a
+ * reason to read: it is how a UI decides between "add" and "re-add", and the
+ * `stale` state is the only signal that a re-run would do something.
  */
-export async function mcpList(options: { name?: string | undefined; scope?: string | undefined }): Promise<void> {
+export async function mcpList(options: McpListFlags): Promise<void> {
   const name = options.name ?? 'lanes-link';
   const scope = options.scope ?? 'user';
 
-  heading(`Registered as ${style.bold(name)}`);
+  const listing = await listRegistrations(name, scope);
+
+  await emit(options.json, listing, () => render(listing));
+}
+
+/** The whole answer, gathered. No printing, so a caller can have it as data. */
+export async function listRegistrations(name: string, scope: string): Promise<McpListing> {
+  const harnesses: ListedHarness[] = [];
 
   for (const harness of HARNESSES) {
     const binary = Bun.which(harness.binary);
 
     if (!binary) {
-      print(`  ${harness.label.padEnd(14)} ${style.dim('not installed')}`);
+      harnesses.push({
+        id: harness.id,
+        label: harness.label,
+        installed: false,
+        binary: null,
+        registered: false,
+        documents: [],
+      });
       continue;
     }
 
-    print(
-      `  ${harness.label.padEnd(14)} ${
-        exists(binary, harness, name)
-          ? style.green('registered')
-          : style.dim(`not registered — lanes link mcp add ${harness.id}`)
-      }`,
-    );
-
-    for (const line of await documentLines(harness, scope)) print(`  ${' '.repeat(14)} ${line}`);
+    harnesses.push({
+      id: harness.id,
+      label: harness.label,
+      installed: true,
+      binary,
+      registered: exists(binary, harness, name),
+      documents: await documents(harness, scope),
+    });
   }
+
+  return { name, scope, harnesses };
 }
 
-/** One line per document this harness can hold, saying whether it is current. */
-async function documentLines(harness: Harness, scope: string): Promise<string[]> {
-  const lines: string[] = [];
+/** One entry per document this harness can hold, saying whether it is current. */
+async function documents(harness: Harness, scope: string): Promise<ListedDocument[]> {
+  const listed: ListedDocument[] = [];
 
   for (const plan of plannedAssets(harness, scope)) {
     try {
-      const state = await assetState(plan, await readAsset(plan.asset));
-
-      lines.push(
-        state === 'current'
-          ? style.dim(`${plan.asset.label}: `) + style.green('up to date')
-          : style.dim(
-              state === 'stale'
-                ? `${plan.asset.label}: out of date — lanes link mcp add ${harness.id}`
-                : `${plan.asset.label}: not installed — lanes link mcp add ${harness.id}`,
-            ),
-      );
+      listed.push({
+        label: plan.asset.label,
+        path: plan.path,
+        state: await assetState(plan, await readAsset(plan.asset)),
+      });
     } catch (error) {
       // A checkout without `instructions/` — a container image, say. Worth one
       // line rather than a thrown error that hides the registration column.
-      lines.push(style.dim(`${plan.asset.label}: ${message(error)}`));
+      listed.push({
+        label: plan.asset.label,
+        path: plan.path,
+        state: 'unreadable',
+        detail: message(error),
+      });
+    }
+  }
+
+  return listed;
+}
+
+function render(listing: McpListing): void {
+  heading(`Registered as ${style.bold(listing.name)}`);
+
+  for (const harness of listing.harnesses) {
+    if (!harness.installed) {
+      print(`  ${harness.label.padEnd(14)} ${style.dim('not installed')}`);
+      continue;
+    }
+
+    print(
+      `  ${harness.label.padEnd(14)} ${
+        harness.registered
+          ? style.green('registered')
+          : style.dim(`not registered — lanes link mcp add ${harness.id}`)
+      }`,
+    );
+
+    for (const document of harness.documents) {
+      print(`  ${' '.repeat(14)} ${documentLine(harness.id, document)}`);
     }
   }
+}
 
-  return lines;
+function documentLine(id: string, document: ListedDocument): string {
+  switch (document.state) {
+    case 'current':
+      return style.dim(`${document.label}: `) + style.green('up to date');
+    case 'stale':
+      return style.dim(`${document.label}: out of date — lanes link mcp add ${id}`);
+    case 'missing':
+      return style.dim(`${document.label}: not installed — lanes link mcp add ${id}`);
+    case 'unreadable':
+      return style.dim(`${document.label}: ${document.detail}`);
+  }
 }
 
 function message(error: unknown): string {

package/src/cli/main.ts

@@ -321,7 +321,11 @@ export async function run(argv: readonly string[]): Promise<void> {
           return mcpStdio({ ...global, ...(flags['only'] === true ? { only: true } : {}) });
         case 'list':
         case undefined:
-          return mcpList({ name: text(flags, 'name'), scope: text(flags, 'scope') });
+          return mcpList({
+            name: text(flags, 'name'),
+            scope: text(flags, 'scope'),
+            json: flags['json'] === true,
+          });
         default:
           throw new Error(`Unknown: ${PROGRAM} mcp ${second}`);
       }

package/src/providers/bunq/hints.ts

@@ -29,7 +29,9 @@ export const BUNQ_HINTS: Record<string, string> = {
   UPDATE_DraftPayment_for_User_MonetaryAccount:
     'Changes a draft that is still pending — status ACCEPTED sends it, REJECTED cancels it. ' +
     'previous_updated_timestamp is required and comes from reading the draft first; it is what stops two ' +
-    'callers acting on the same draft.',
+    'callers acting on the same draft. Those two fields are the entire call — bunq refuses entries and ' +
+    'number_of_required_accepts here as superfluous — so changing what a draft pays means rejecting it and ' +
+    'creating another.',
 
   CREATE_PaymentBatch_for_User_MonetaryAccount:
     'Up to 350 payments in one call. Executes immediately, like a direct payment, and is all-or-nothing: bunq rejects ' +

package/src/providers/bunq/redact.ts

@@ -51,14 +51,25 @@ export const BUNQ_REDACT: Record<string, string[]> = {
     'status',
     'schedule',
   ],
+  // Five, not seven: `entries` and `number_of_required_accepts` are no longer
+  // arguments at all. This is the one write here whose event cannot name an
+  // amount or a counterparty, because the call does not carry them — it says
+  // which draft was accepted and against which version of it, and that is
+  // everything there is to keep.
+  //
+  // Not everything a reader wants, though, and worth being honest that the gap
+  // is real rather than closed. The entries are on the event that *created* the
+  // draft, and nothing joins the two: an `AuditEvent` records arguments only,
+  // and bunq returns the draft id in the create's response. Reconstructing what
+  // an ACCEPTED draft paid means matching by hand. `context.audit.annotate`,
+  // which `gmail.send_message` uses to record resolved facts, is the shape of a
+  // fix and is a change to dispatch rather than to this list.
   UPDATE_DraftPayment_for_User_MonetaryAccount: [
     'userID',
     'monetary-accountID',
     'itemId',
     'status',
-    'entries',
     'previous_updated_timestamp',
-    'number_of_required_accepts',
   ],
   CREATE_PaymentBatch_for_User_MonetaryAccount: ['userID', 'monetary-accountID', 'payments'],
 };

package/src/providers/bunq/specs/bunq.v1.json

@@ -144,7 +144,26 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/DraftPayment"
+                "type": "object",
+                "description": "The whole of what this call takes. bunq refuses any other field here as superfluous — the rest of the schema it shares belongs to the call that creates one.",
+                "properties": {
+                  "status": {
+                    "type": "string",
+                    "description": "The status of the DraftPayment.",
+                    "readOnly": false,
+                    "writeOnly": false
+                  },
+                  "previous_updated_timestamp": {
+                    "type": "string",
+                    "description": "The last updated_timestamp that you received for this DraftPayment. This needs to be provided to prevent race conditions.",
+                    "readOnly": false,
+                    "writeOnly": true
+                  }
+                },
+                "required": [
+                  "status",
+                  "previous_updated_timestamp"
+                ]
               }
             }
           }

package/src/providers/bunq/specs/vendor.ts

@@ -22,6 +22,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { OpenAPIToolGenerator, type McpOpenAPITool } from 'mcp-from-openapi';
 import { cutCycles, referenced, type Spec } from '../../shared/openapi.ts';
+import { projectRequestBody } from '../../shared/vendor-operations.ts';
 
 const SOURCE = 'https://raw.githubusercontent.com/bunq/doc/master/swagger.json';
 const OUT = 'bunq.v1.json';
@@ -187,6 +188,34 @@ function dropReadOnly(node: unknown): number {
   return dropped;
 }
 
+/**
+ * The operations bunq describes with the schema of a *different* operation.
+ *
+ * `PUT .../draft-payment/{itemId}` points at `DraftPayment`, the same schema as
+ * the `POST` that creates one, which requires `entries` and
+ * `number_of_required_accepts`. For a create those two *are* the payment. For an
+ * update bunq refuses both as superfluous — its own generated SDK sends only
+ * `status`, `previous_updated_timestamp` and `schedule` here — so the tool asked
+ * for exactly what the bank rejects and every accept failed. Worse than the
+ * error: made to send `entries` for a draft that has them, a model reaches for
+ * the array echoed back or for `[]`, and both ask bunq to rewrite what the draft
+ * pays on the way to approving it. A hint cannot fix a required argument, which
+ * is the difference between this and the `payments`-is-really-an-array note
+ * above: nothing stops an agent sending an array, and nothing lets it omit a
+ * required field. `required` is asserted here rather than projected because
+ * bunq's own is the one written for the create.
+ *
+ * `schedule` is deliberately not projected: it carries `recurrence_unit` and
+ * `recurrence_size`, so approving a one-off draft would be a place to acquire a
+ * standing order — the risk `OPERATIONS` gives for leaving the scheduling
+ * *endpoints* out. Not the whole of that risk, though: `CREATE_DraftPayment`
+ * still offers the same field, because it comes with bunq's create schema.
+ * Closing that changes what the provider can do rather than whether a call
+ * works, and is not done here.
+ */
+const UPDATE_BODIES: Record<string, readonly string[]> = {
+  UPDATE_DraftPayment_for_User_MonetaryAccount: ['status', 'previous_updated_timestamp'],
+};
 
 async function vendor(): Promise<void> {
   const response = await fetch(SOURCE);
@@ -246,6 +275,34 @@ async function vendor(): Promise<void> {
   }
 
   const schemas = spec.components?.schemas ?? {};
+
+  const projected = new Set<string>();
+  for (const item of Object.values(paths)) {
+    for (const [method, operation] of Object.entries(item)) {
+      if (!METHODS.includes(method)) continue;
+      const fields = operation.operationId ? UPDATE_BODIES[operation.operationId] : undefined;
+      if (!fields || !operation.operationId) continue;
+
+      projectRequestBody(
+        operation as unknown as Record<string, unknown>,
+        operation.operationId,
+        schemas,
+        fields,
+        'The whole of what this call takes. bunq refuses any other field here as superfluous — the rest ' +
+          'of the schema it shares belongs to the call that creates one.',
+      );
+      projected.add(operation.operationId);
+    }
+  }
+
+  // The same refusal as `missing` above, and for a sharper reason: an entry that
+  // matches nothing narrows nothing, and what is left is the wide body this
+  // exists to remove — printed as a success.
+  const unprojected = Object.keys(UPDATE_BODIES).filter((id) => !projected.has(id));
+  if (unprojected.length > 0) {
+    throw new Error(`UPDATE_BODIES names operations the spec does not have — ${unprojected.join(', ')}`);
+  }
+
   const keep = referenced(paths, schemas);
   const trimmedSchemas = Object.fromEntries(
     Object.entries(schemas).filter(([name]) => keep.has(name)),
@@ -295,7 +352,8 @@ async function vendor(): Promise<void> {
     `  bunq   ${String(Object.keys(paths).length).padStart(2)} paths, ` +
       `${seen.size} operations, ${Object.keys(trimmedSchemas).length} schemas, ` +
       `${cuts} cycle${cuts === 1 ? '' : 's'} cut, ${headers} protocol params dropped, ` +
-      `${readOnly} read-only fields dropped, ${size}KB`,
+      `${readOnly} read-only fields dropped, ${projected.size} update ` +
+      `bod${projected.size === 1 ? 'y' : 'ies'} projected, ${size}KB`,
   );
 
   await report(trimmed);

package/src/providers/shared/vendor-operations.ts

@@ -96,3 +96,84 @@ export function narrowRequestBody(
   body.content = Object.fromEntries(kept.map((type) => [type, body.content![type]]));
   return before.length - kept.length;
 }
+
+/**
+ * Replace a request body with a projection of the schema it points at.
+ *
+ * The third surgery on this axis, and the first about the body being *wrong*
+ * rather than too wide. A document that describes two operations with one schema
+ * describes at least one of them wrongly, and `required` is where it bites: the
+ * generated tool asks for arguments the vendor refuses on the call they are
+ * attached to, so there is no correct call to make. It fails at the vendor, on
+ * every attempt, and nothing before the request can see it.
+ *
+ * Projecting rather than hand-writing is what keeps this tied to the document.
+ * The named fields are copied out of the vendor's own schema with their types
+ * and descriptions, so the tool still says what the vendor says. Everything this
+ * cannot verify it refuses instead: a field that is gone, a field the document
+ * marks read-only, a body offering a content type this does not rewrite, a
+ * `$ref` that does not point into `components.schemas`. A vendor refresh should
+ * fail loudly here rather than quietly restore the body it was called to fix.
+ *
+ * `required` is the one thing NOT projected — it is the caller's assertion, and
+ * necessarily so, since the whole disease is a `required` written for the other
+ * operation. Say why in the caller.
+ *
+ * `note` becomes the body schema's description. It lands in the committed
+ * document for whoever reads it there; it does **not** reach the agent, because
+ * the generator flattens body properties to the top level and drops the body
+ * schema's own description. The sentence an agent needs goes in `hints`.
+ *
+ * Apply before reachability, so a schema the projection no longer reaches leaves
+ * the document rather than lingering unused.
+ */
+export function projectRequestBody(
+  operation: Record<string, unknown>,
+  operationId: string,
+  schemas: Record<string, unknown>,
+  fields: readonly string[],
+  note: string,
+): void {
+  const content = (operation['requestBody'] as { content?: Record<string, { schema?: { $ref?: string } }> })
+    ?.content;
+  const types = Object.keys(content ?? {});
+
+  const other = types.filter((type) => type !== 'application/json');
+  if (!content || types.length === 0 || other.length > 0) {
+    // A body left pointing at the wide schema on a second content type is the
+    // bug still present on whichever branch the generator happens to prefer.
+    throw new Error(
+      `${operationId}: expected a lone application/json request body to project, found ${types.join(', ') || 'none'}`,
+    );
+  }
+
+  const json = content['application/json'];
+  const reference = json?.schema?.$ref;
+  if (!json || typeof reference !== 'string' || !reference.startsWith('#/components/schemas/')) {
+    throw new Error(`${operationId}: request body is ${reference ?? 'not a $ref'}, not a schema reference`);
+  }
+
+  const name = reference.slice('#/components/schemas/'.length);
+  const source = (schemas[name] as { properties?: Record<string, unknown> } | undefined)?.properties ?? {};
+
+  const properties: Record<string, unknown> = {};
+  for (const field of fields) {
+    const property = source[field] as { readOnly?: boolean } | undefined;
+    if (!property) throw new Error(`${operationId}: ${name} no longer describes "${field}"`);
+    if (property.readOnly === true) {
+      // Projected fields are inlined into the path, where the read-only strip
+      // does not reach — so a field the vendor computes would survive here and
+      // be demanded as an argument it ignores.
+      throw new Error(`${operationId}: ${name}.${field} is read-only and cannot be a request field`);
+    }
+    properties[field] = property;
+  }
+
+  json.schema = {
+    type: 'object',
+    description: note,
+    properties,
+    required: [...fields],
+  } as never;
+}
+