@lanes-sh/link 0.1.0

package/src/connectivity/transports/imap/utf7.ts

@@ -0,0 +1,136 @@
+/**
+ * Modified UTF-7, the encoding IMAP mailbox names arrive in (RFC 3501 §5.1.3).
+ *
+ * A mailbox called `Wichtig` is fine on the wire; one called `Wichtig ✓` is
+ * `Wichtig &Ivg-`, and a Japanese folder is unreadable without this. Getting it
+ * wrong is not subtle in one direction and dangerously subtle in the other:
+ * skipping *decode* shows an agent a folder name nobody recognises, while
+ * skipping *encode* sends a `SELECT` for a mailbox the server does not have, and
+ * a `SELECT` that fails looks exactly like a mailbox that is empty.
+ *
+ * It is UTF-7 with two changes: `+` becomes `&` (because `+` is common in
+ * mailbox names), and `/` becomes `,` (because `/` is the usual hierarchy
+ * delimiter). Padding is omitted.
+ */
+
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,';
+
+/** Wire form → the name a person would recognise. */
+export function decodeMailboxName(encoded: string): string {
+  let out = '';
+  let index = 0;
+
+  while (index < encoded.length) {
+    const amp = encoded.indexOf('&', index);
+    if (amp === -1) return out + encoded.slice(index);
+
+    out += encoded.slice(index, amp);
+
+    const end = encoded.indexOf('-', amp + 1);
+    if (end === -1) {
+      // Unterminated: not legal, and not worth throwing over — a mailbox list
+      // is not the place to fail a whole call. Pass the rest through as-is.
+      return out + encoded.slice(amp);
+    }
+
+    const chunk = encoded.slice(amp + 1, end);
+    // `&-` is how a literal ampersand is written.
+    out += chunk === '' ? '&' : fromModifiedBase64(chunk);
+    index = end + 1;
+  }
+
+  return out;
+}
+
+/** The name a person typed → wire form. */
+export function encodeMailboxName(name: string): string {
+  let out = '';
+  let run = '';
+
+  const flush = (): void => {
+    if (run === '') return;
+    out += `&${toModifiedBase64(run)}-`;
+    run = '';
+  };
+
+  for (const character of name) {
+    const code = character.codePointAt(0)!;
+
+    if (character === '&') {
+      flush();
+      out += '&-';
+      continue;
+    }
+
+    // Printable US-ASCII represents itself; everything else goes to base64.
+    if (code >= 0x20 && code <= 0x7e) {
+      flush();
+      out += character;
+      continue;
+    }
+
+    run += character;
+  }
+
+  flush();
+  return out;
+}
+
+/** Modified base64 → text, by way of the UTF-16BE the bytes represent. */
+function fromModifiedBase64(chunk: string): string {
+  let bits = 0;
+  let width = 0;
+  const units: number[] = [];
+  let pending = 0;
+  let pendingBits = 0;
+
+  for (const character of chunk) {
+    const value = BASE64.indexOf(character);
+    if (value === -1) continue; // Not representable; skipping beats throwing.
+
+    bits = (bits << 6) | value;
+    width += 6;
+
+    while (width >= 8) {
+      width -= 8;
+      const byte = (bits >> width) & 0xff;
+      pending = (pending << 8) | byte;
+      pendingBits += 8;
+
+      if (pendingBits === 16) {
+        units.push(pending & 0xffff);
+        pending = 0;
+        pendingBits = 0;
+      }
+    }
+  }
+
+  // Surrogate pairs survive because they are two code units and this rebuilds
+  // code units, not code points.
+  return String.fromCharCode(...units);
+}
+
+/** Text → modified base64 of its UTF-16BE bytes. */
+function toModifiedBase64(text: string): string {
+  const bytes: number[] = [];
+  for (let index = 0; index < text.length; index++) {
+    const unit = text.charCodeAt(index);
+    bytes.push((unit >> 8) & 0xff, unit & 0xff);
+  }
+
+  let out = '';
+  let bits = 0;
+  let width = 0;
+
+  for (const byte of bytes) {
+    bits = (bits << 8) | byte;
+    width += 8;
+    while (width >= 6) {
+      width -= 6;
+      out += BASE64[(bits >> width) & 0x3f];
+    }
+  }
+
+  if (width > 0) out += BASE64[(bits << (6 - width)) & 0x3f];
+  return out;
+}

package/src/connectivity/transports/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Connectivity types — one folder per way of reaching a service.
+ *
+ * See `README.md` for the table mapping each folder to the `connector.kind` an
+ * operator writes, and for the rule that keeps vendor names out of all of them.
+ */
+
+export { createLocalConnector } from './local/index.ts';
+export { createMcpConnector, inferBundle, type McpConnectorOptions } from './mcp/index.ts';
+export {
+  createHttpConnector,
+  bundleForMethod,
+  globMatches,
+  type HttpConnectorOptions,
+} from './http/index.ts';
+export { createImapConnector, type ImapConnectorOptions } from './imap/index.ts';
+export { createDavConnector, type DavConnectorOptions } from './dav/index.ts';
+export { createFsConnector, type FsConnectorOptions } from './fs/index.ts';
+export { type ImapCredential } from './imap/client.ts';
+export { connectorFactory, type ConnectorFactory, type ConnectorFactoryOptions } from './factory.ts';

package/src/connectivity/transports/local/index.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import {
+  isPrompt,
+  isResource,
+  isTool,
+  type AnyConnector,
+  type Capability,
+  type CapabilityResult,
+  type ConnectorContext,
+  type DiscoveredCapability,
+  type ProviderDefinition,
+} from '#connectivity';
+
+/**
+ * The `local` connector — our own code.
+ *
+ * Thin by design: it exists so dispatch has **one** path rather than branching
+ * on whether a provider happens to carry handlers. `example` and the M4 owner
+ * layer are the only users.
+ *
+ * It is also the only connector that serves anything other than tools. A remote
+ * kind reports what an upstream server or an OpenAPI document describes, and
+ * both describe operations; resources and prompts exist only where we author
+ * the capability ourselves. Until M4 this connector dropped them in `discover`
+ * and threw in `invoke`, which is why `docs/detailed/init.md`'s "nothing in core changes
+ * to add [the owner layer]" was false — the resource path registered in
+ * `packages/mcp` could not reach a provider at all.
+ */
+export function createLocalConnector(definition: ProviderDefinition): AnyConnector {
+  return {
+    kind: 'local',
+
+    async discover(): Promise<DiscoveredCapability[]> {
+      // Local capabilities author Zod; everything downstream speaks JSON Schema,
+      // because that is what upstream servers and OpenAPI documents give us.
+      // Resources and prompts have no input schema of that shape, so they report
+      // an empty one rather than being omitted — a caller counting what a
+      // provider exposes should see all of it.
+      return definition.capabilities.map((capability) => ({
+        name: capability.name,
+        ...(capability.title ? { title: capability.title } : {}),
+        description: capability.description,
+        inputSchema: isTool(capability)
+          ? (z.toJSONSchema(capability.inputSchema) as Record<string, unknown>)
+          : {},
+        ...(bundleFor(definition, capability.name)
+          ? { bundle: bundleFor(definition, capability.name)! }
+          : {}),
+      }));
+    },
+
+    async invoke(capability, args, context: ConnectorContext): Promise<CapabilityResult> {
+      const found = definition.capabilities.find((entry) => entry.name === capability.name);
+      if (!found) {
+        throw new Error(`${definition.manifest.id}.${capability.name} is not a capability`);
+      }
+
+      if (isTool(found)) {
+        const parsed = found.inputSchema.safeParse(args);
+        if (!parsed.success) {
+          throw new Error(invalidArguments(definition, found, parsed.error.issues[0]?.message));
+        }
+
+        return found.handler(parsed.data, context.provider);
+      }
+
+      if (isResource(found)) {
+        // A `uri` argument means "read this one"; its absence means "enumerate".
+        // Core is the only caller and passes one or the other — the MCP layer
+        // builds both from the registration, so neither is client-supplied.
+        const uri = args['uri'];
+
+        if (uri === undefined) {
+          if (!found.list) {
+            throw new Error(
+              `${definition.manifest.id}.${found.name} does not enumerate: its resource space is unbounded.`,
+            );
+          }
+          return { resources: await found.list(context.provider) };
+        }
+
+        if (typeof uri !== 'string') {
+          throw new Error(`${definition.manifest.id}.${found.name} needs a string uri`);
+        }
+
+        return {
+          contents: [await found.read(uri, extractParams(found.uriTemplate, uri), context.provider)],
+        };
+      }
+
+      if (isPrompt(found)) {
+        const missing = (found.arguments ?? [])
+          .filter((argument) => argument.required && typeof args[argument.name] !== 'string')
+          .map((argument) => argument.name);
+
+        if (missing.length > 0) {
+          throw new Error(invalidArguments(definition, found, `missing ${missing.join(', ')}`));
+        }
+
+        return found.render(stringArguments(args), context.provider);
+      }
+
+      // Every branch above returns, so this is unreachable while `Capability`
+      // has three members — and becomes a compile error the moment it gains a
+      // fourth, which is the point.
+      const exhaustive: never = found;
+      return exhaustive;
+    },
+  };
+}
+
+function invalidArguments(
+  definition: ProviderDefinition,
+  capability: Capability,
+  detail: string | undefined,
+): string {
+  return `Invalid arguments for ${definition.manifest.id}.${capability.name}: ${detail ?? 'invalid'}`;
+}
+
+/**
+ * Prompt arguments are strings on the wire, and a provider's `render` is typed
+ * for that. Anything else a caller managed to attach is dropped rather than
+ * coerced: a prompt that silently received `"[object Object]"` would be worse
+ * than one that received nothing.
+ */
+function stringArguments(args: Readonly<Record<string, unknown>>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (typeof value === 'string') out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Recover a resource's own template variables from a concrete URI.
+ *
+ * The MCP SDK matches the *registered* template, which core has already
+ * rewritten to carry the profile and connection (see `scopeResourceUri` in
+ * `packages/mcp`). Matching the provider's own template here instead means a
+ * handler receives exactly the variables it declared and never learns how it
+ * was routed — the same separation `ConnectionInfo` gives a tool.
+ *
+ * Aligned from the right, because the routing segments core prepends are on the
+ * left. Deliberately a segment-wise match rather than a general RFC 6570
+ * expander: templates in this codebase use simple `{name}` expansion, and a
+ * partial implementation of the rest would be a trap.
+ */
+export function extractParams(template: string, uri: string): Record<string, string> {
+  const templateParts = splitUri(template);
+  const uriParts = splitUri(uri);
+  const params: Record<string, string> = {};
+
+  for (let offset = 1; offset <= templateParts.length; offset += 1) {
+    const templatePart = templateParts[templateParts.length - offset]!;
+    const uriPart = uriParts[uriParts.length - offset];
+    if (uriPart === undefined) break;
+
+    const variable = templatePart.match(/^\{(.+)\}$/);
+    if (variable) params[variable[1]!] = uriPart;
+  }
+
+  return params;
+}
+
+function splitUri(value: string): string[] {
+  const scheme = value.indexOf('://');
+  return (scheme === -1 ? value : value.slice(scheme + 3)).split('/').filter((part) => part !== '');
+}
+
+function bundleFor(definition: ProviderDefinition, capability: string): string | undefined {
+  return definition.manifest.bundles?.find((bundle) => bundle.capabilities.includes(capability))
+    ?.name;
+}

package/src/connectivity/transports/mcp/index.ts

@@ -0,0 +1,215 @@
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import type {
+  Connector,
+  DiscoveryContext,
+  DiscoveredCapability,
+  ToolResult,
+} from '#connectivity';
+import { READ_BUNDLE, WRITE_BUNDLE } from '#connectivity';
+
+/**
+ * The `mcp` connector — proxy an upstream MCP server.
+ *
+ * This is what makes Notion and Linear cost a fifteen-line manifest each: the
+ * vendor already wrote the integration, and they maintain it. What we add is
+ * the thing they do not have — per-capability policy, audit with redaction, and
+ * profile isolation in front of it.
+ *
+ * Capabilities are **discovered**, never declared. The upstream server is the
+ * source of truth for what it exposes, and pretending otherwise would mean a
+ * manifest going stale every time the vendor ships.
+ */
+
+export interface McpConnectorOptions {
+  readonly endpoint: string;
+  /** Supplies the bearer token for an upstream call; refreshes if needed. */
+  readonly accessToken: () => Promise<string | null>;
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+interface UpstreamTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+  annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean };
+}
+
+/**
+ * Guess a bundle from the upstream tool's own hints.
+ *
+ * MCP tools may carry a `readOnlyHint`, which is exactly the read/write split
+ * we want. Where the hint is absent we fall back to the name, and where that is
+ * ambiguous we say `write` — the safer answer, since `read` is what `connect`
+ * grants by default and over-granting is the failure that matters.
+ */
+export function inferBundle(tool: UpstreamTool, name = tool.name): string {
+  if (tool.annotations?.readOnlyHint === true) return READ_BUNDLE;
+  if (tool.annotations?.readOnlyHint === false) return WRITE_BUNDLE;
+
+  // Fallback for servers that publish no hint. Matched against the *shortened*
+  // name and tolerant of hyphens, because vendors separate words however they
+  // like — Notion uses `-`, others `_`. An unrecognised verb means `write`,
+  // which is the safer default given `read` is what connect grants.
+  return /^(get|list|search|read|find|query|fetch|describe|view|download)([-_]|$)/i.test(name)
+    ? READ_BUNDLE
+    : WRITE_BUNDLE;
+}
+
+/**
+ * Drop a redundant provider prefix from an upstream tool name.
+ *
+ * Notion names every tool `notion-*`, which would make our qualified id
+ * `notion.notion-search` and the wire name `notion_notion-search`. Stripping it
+ * is safe because the original is kept in `target.tool` and is what we actually
+ * call — this only affects how the capability is addressed in policy and audit,
+ * which is where readability matters.
+ *
+ * Skipped entirely if stripping would collide with another tool, since a
+ * shorter name is never worth routing to the wrong one.
+ */
+export function shortenName(providerId: string, name: string, all: readonly string[]): string {
+  for (const separator of ['-', '_', '.']) {
+    const prefix = `${providerId}${separator}`;
+    if (!name.startsWith(prefix) || name.length === prefix.length) continue;
+
+    const shortened = name.slice(prefix.length);
+    const collides = all.some((other) => other !== name && other === shortened);
+    return collides ? name : shortened;
+  }
+  return name;
+}
+
+/**
+ * Turn an upstream transport error into something readable.
+ *
+ * The SDK reports a bad HTTP status by appending the whole response body,
+ * which for a large tool list is tens of kilobytes of JSON scrolling past the
+ * actual problem. Worse, some servers hide a real explanation inside it:
+ * Google answers 403 with a perfectly formed JSON-RPC result whose text says
+ * the MCP API is not enabled on the project — the one sentence that tells you
+ * what to do, buried in 44KB.
+ */
+export function readableUpstreamError(error: unknown, endpoint: string): Error {
+  const message = error instanceof Error ? error.message : String(error);
+
+  const start = message.indexOf('{');
+  if (start === -1) return error instanceof Error ? error : new Error(message);
+
+  try {
+    const body = JSON.parse(message.slice(start)) as {
+      error?: { message?: string };
+      result?: { content?: Array<{ text?: string }> };
+    };
+
+    const detail = body.error?.message ?? body.result?.content?.[0]?.text;
+    if (detail) {
+      return new Error(`${new URL(endpoint).host}: ${detail.trim()}`);
+    }
+  } catch {
+    // Not JSON, or truncated — fall through to the summary below.
+  }
+
+  return new Error(`${message.slice(0, start).trim()} (${new URL(endpoint).host})`);
+}
+
+export function createMcpConnector(options: McpConnectorOptions): Connector {
+  /**
+   * A fresh client per operation.
+   *
+   * Upstream sessions are not reused across requests: the server is stateless
+   * and may be replaced between them, so holding a connection would be state we
+   * have promised not to keep. Access tokens *are* cached in memory by the
+   * caller, so the cost is one HTTP connection rather than a token exchange.
+   */
+  const connect = async (context: DiscoveryContext): Promise<Client> => {
+    const token = await options.accessToken();
+
+    const transport = new StreamableHTTPClientTransport(new URL(options.endpoint), {
+      requestInit: {
+        headers: token ? { authorization: `Bearer ${token}` } : {},
+      },
+      ...(options.fetch ? { fetch: options.fetch } : {}),
+    } as never);
+
+    const client = new Client(
+      {
+        name: 'lanes-link',
+        version: context.manifest.version,
+      },
+      {
+        // Negotiate the era rather than assuming one. A gateway proxying
+        // arbitrary vendors cannot assume they have all moved: Notion and
+        // Linear speak the modern handshake-free revision, while Google's
+        // Gmail and Drive servers are on 2025-06-18 and answer 403 to anything
+        // that arrives before `initialize`. `auto` probes with
+        // `server/discover` and falls back to the legacy handshake.
+        versionNegotiation: { mode: 'auto' },
+      },
+    );
+
+    await client.connect(transport);
+    return client;
+  };
+
+  return {
+    kind: 'mcp',
+
+    async discover(context): Promise<DiscoveredCapability[]> {
+      const client = await connect(context);
+
+      try {
+        const { tools = [] } = (await client.listTools()) as { tools?: UpstreamTool[] };
+        const names = tools.map((tool) => tool.name);
+
+        return tools.map((tool) => ({
+          name: shortenName(context.manifest.id, tool.name, names),
+          ...(tool.title ? { title: tool.title } : {}),
+          description: tool.description ?? `${context.manifest.name} ${tool.name}`,
+          inputSchema: tool.inputSchema ?? { type: 'object', properties: {} },
+          bundle: inferBundle(tool, shortenName(context.manifest.id, tool.name, names)),
+          // The upstream name is kept verbatim: ours may differ once it has
+          // been through name normalisation, and calling the wrong tool
+          // upstream would be a silent, expensive mistake.
+          target: { tool: tool.name },
+        }));
+      } catch (error) {
+        throw readableUpstreamError(error, options.endpoint);
+      } finally {
+        await client.close().catch(() => {});
+      }
+    },
+
+    async invoke(capability, args, context): Promise<ToolResult> {
+      const client = await connect(context);
+      const upstreamName = (capability.target?.['tool'] as string | undefined) ?? capability.name;
+
+      try {
+        const result = (await client.callTool({
+          name: upstreamName,
+          arguments: args as Record<string, unknown>,
+        })) as {
+          content?: Array<{ type: string; text?: string; uri?: string; name?: string }>;
+          isError?: boolean;
+        };
+
+        return {
+          content: (result.content ?? []).map((block) =>
+            block.type === 'text'
+              ? { type: 'text' as const, text: block.text ?? '' }
+              : {
+                  type: 'resource_link' as const,
+                  uri: block.uri ?? '',
+                  ...(block.name ? { name: block.name } : {}),
+                },
+          ),
+          ...(result.isError ? { isError: true } : {}),
+        };
+      } catch (error) {
+        throw readableUpstreamError(error, options.endpoint);
+      } finally {
+        await client.close().catch(() => {});
+      }
+    },
+  };
+}

package/src/deployments/README.md

@@ -0,0 +1,63 @@
+# Deployments
+
+Where a profile runs. A target names one, and the whole of the difference is
+two backends: a `SecretStore` and a `BlobStore`. Connections, providers, policy
+and limits are declared once and apply to every target.
+
+| Folder | Target | Secrets | Blobs | Vault |
+|---|---|---|---|---|
+| `local/` | `local` | encrypted file | `filesystem` | `file` |
+| `gcp/` | `cloud` | `gcp-secret-manager` | `gcs` (or `s3`) | `secret` |
+| `azure/` | — | not implemented | | |
+
+There is no database column, and no database. State is one object per key and
+the audit log is one object per event, both in whatever `BlobStore` the target
+already opened — so the deployed target has exactly two standing dependencies
+and neither of them is a service to provision (ADR-020, ADR-021).
+
+## Adapters are named for the protocol, deployments for the vendor
+
+`s3` needs an endpoint and a key pair; `gcs` needs neither, because it
+authenticates as the identity already present. R2, MinIO, Supabase Storage and
+AWS differ only in those values, so a vendor name on the adapter would claim a
+coupling that does not exist and would have to be either lied about or
+duplicated the first time someone pointed it elsewhere (ADR-013). The host is a
+deploy-time choice; the protocol is the interface.
+
+That is why `adapters/` is flat and shared, and why the GCP folder holds no
+storage code — only the things that genuinely are Google's: how to roll a Cloud
+Run revision, what to create before the first one, and what to ask when the
+config does not say yet.
+
+## Adding one
+
+1. A folder here.
+2. If it needs a backend nobody has written, an adapter in `adapters/` named for
+   the protocol.
+3. A case in `target.ts`, importing that adapter **inside the branch** — a local
+   run must not load a cloud client, or a missing cloud credential fails a
+   `lanes link start` that was never going to talk to that cloud.
+4. A member of the adapter enums in `#profile`'s schema, so a target can name it.
+5. To be deployable: a `DeployDriver` (`driver.ts`) and a case in `drivers.ts`,
+   imported inside the branch for the same reason. Add its name to the
+   `deploy.platform` enum in `#profile`'s schema.
+
+Nothing else in the codebase learns about it. In particular the CLI does not:
+`lanes link deploy` is a thin wrapper that dispatches to the deployment's own
+driver through `drivers.ts`, and the machinery for rolling a revision lives with
+the vendor that needs it. A driver returns its steps as **data** — argv arrays,
+never shell strings — which is what makes `--dry-run` show the real sequence and
+what lets the commands be asserted in a test with no cloud account anywhere near
+it.
+
+What is *not* the driver's: the deployment block is named `deploy` and carries a
+`platform`, so which vendor a target uses is a value rather than the name of a
+key. `project` is optional in that block and required by the driver that needs
+one, on the same reasoning as `credentials.project`.
+
+## Blob storage is not optional in a deployment
+
+`adapter: filesystem` on Cloud Run **appears to work**: every write succeeds,
+every read within the life of an instance succeeds, and the bytes are gone when
+the instance recycles. A missing adapter that throws is a smaller problem than a
+present adapter that silently loses data. See ADR-013.