@lanes-sh/link 0.1.0

package/src/providers/custom/load.ts

@@ -0,0 +1,115 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { defineProvider, type ProviderManifest } from '#connectivity';
+import { ConfigError, layout } from '#profile';
+import { findSecrets, formatSecretFindings } from '#profile';
+
+/**
+ * Provider manifests supplied by the operator.
+ *
+ * The built-in list is a convenience, never a boundary. Anything not shipped is
+ * a YAML file in `<workspace>/data/<profile>/providers.d/`, validated by the
+ * same schema the built-ins are — no code, no rebuild, no pull request.
+ *
+ * That is the whole scalability claim of this milestone: a service nobody has
+ * integrated costs a file.
+ *
+ * **Per profile**, which the workspace-wide directory this replaced was not. A
+ * manifest names a host, an OpenAPI document, and the credential refs that
+ * reach them, so it describes somebody's infrastructure — and work's is not
+ * personal's to read. The path comes from `layout` for the same reason every
+ * other profile-owned path does: one place that knows the on-disk shape.
+ * ADR-030.
+ */
+
+export interface LoadedManifest {
+  readonly manifest: ProviderManifest;
+  readonly path: string;
+}
+
+export async function loadProfileProviders(
+  workspaceRoot: string,
+  profile: string,
+): Promise<LoadedManifest[]> {
+  const directory = join(workspaceRoot, layout.providers(profile));
+
+  let entries: string[];
+  try {
+    entries = await readdir(directory);
+  } catch {
+    return []; // No custom providers is the normal case.
+  }
+
+  const loaded: LoadedManifest[] = [];
+
+  for (const name of entries.sort()) {
+    if (!name.endsWith('.yaml') && !name.endsWith('.yml')) continue;
+    if (name.endsWith('.example.yaml')) continue;
+
+    const path = join(directory, name);
+    loaded.push({ manifest: await parseManifestFile(path), path });
+  }
+
+  return loaded;
+}
+
+export async function parseManifestFile(path: string): Promise<ProviderManifest> {
+  return resolveSpecPath(parseManifest(await readFile(path, 'utf8'), path), path);
+}
+
+/**
+ * Make a relative `openapi` path mean what the operator meant.
+ *
+ * `docs/detailed/creating-a-provider.md` tells people to write `openapi: ./mything.json`,
+ * and until now that resolved against the *process* working directory — so it
+ * worked when you happened to run `lanes` from the right folder and failed
+ * with a confusing ENOENT everywhere else. The built-ins never noticed because
+ * they compute an absolute path from `import.meta.url`.
+ *
+ * Resolved against the manifest's own directory, the way one file referencing
+ * another normally works.
+ */
+function resolveSpecPath(manifest: ProviderManifest, source: string): ProviderManifest {
+  const connector = manifest.connector;
+  if (connector.kind !== 'http') return manifest;
+  if (/^https?:/i.test(connector.openapi) || isAbsolute(connector.openapi)) return manifest;
+
+  return {
+    ...manifest,
+    connector: { ...connector, openapi: resolve(dirname(source), connector.openapi) },
+  };
+}
+
+export function parseManifest(text: string, source = '<manifest>'): ProviderManifest {
+  let raw: unknown;
+  try {
+    raw = parseYaml(text);
+  } catch (error) {
+    throw new ConfigError(`${source}: could not parse YAML — ${(error as Error).message}`);
+  }
+
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new ConfigError(`${source}: expected a YAML mapping at the top level`);
+  }
+
+  // A manifest is config, so it is held to the same rule config is: references
+  // into the credential store, never values. Someone writing their first
+  // manifest will reach for pasting the API key directly, and this is what
+  // stops that becoming a credential in a file they might commit.
+  const secrets = findSecrets(raw);
+  if (secrets.length > 0) {
+    throw new ConfigError(
+      `${source}: ${formatSecretFindings(secrets)}`,
+      secrets.map((finding) => finding.path),
+    );
+  }
+
+  try {
+    return defineProvider(raw);
+  } catch (error) {
+    throw new ConfigError(`${source}: ${(error as Error).message}`);
+  }
+}
+
+/** A starting point, written out by `lanes link provider new`. */

package/src/providers/custom/template.ts

@@ -0,0 +1,156 @@
+/**
+ * The scaffold `lanes link` writes, one per connectivity type.
+ *
+ * A custom provider is the same declaration a built-in is — this is the *only*
+ * difference between `#providers/google/gmail/` and a file an operator drops in
+ * their profile's `providers.d/`, and the point of the whole manifest design.
+ * So the template offers one starting point per `connector.kind` rather than a
+ * single generic one that would have to be edited into shape.
+ */
+
+export function manifestTemplate(kind: 'mcp' | 'http' | 'imap' | 'dav' | 'fs'): string {
+  if (kind === 'mcp') {
+    return `# A custom MCP server — a vendor's, a colleague's, or your own.
+#
+# If the server supports Dynamic Client Registration there is nothing else to
+# do: Lanes Link registers itself when you run \`lanes link connect\`.
+id: acme
+name: Acme
+description: Whatever this server exposes.
+
+connector:
+  kind: mcp
+  endpoint: https://mcp.acme.com/mcp
+
+auth:
+  kind: oauth
+  registration: dynamic     # or "manual" if the vendor makes you register an app
+`;
+  }
+
+  if (kind === 'imap') {
+    return `# Any mailbox: Fastmail, mailbox.org, a company Dovecot.
+#
+# There is no spec to read — IMAP describes its extensions but never its
+# operations — so the capability set is fixed by the protocol. Reading never
+# marks mail as read, and nothing here can delete any.
+id: fastmail
+name: Fastmail
+
+connector:
+  kind: imap
+  host: imap.fastmail.com
+  port: 993
+  smtp:
+    host: smtp.fastmail.com
+    port: 465
+    starttls: false        # 465 is implicit TLS; 587 upgrades in-band
+
+auth:
+  kind: basic              # a username and an app password, per account
+
+identity:
+  kind: connector          # the account is the name the server accepted
+
+setup:
+  docs: "Create an app password at https://app.fastmail.com/settings/security/apppw"
+  prompts:
+    - key: username
+      label: Email address
+      scope: connection
+      field: username
+    - key: password
+      label: App password
+      secret: true
+      scope: connection
+      field: password
+`;
+  }
+
+  if (kind === 'fs') {
+    return `# A folder on this machine — iCloud Drive, Dropbox, a project directory.
+#
+# No credential: the permission is the operating system's, so this only works
+# where the files actually are. Everything under the root is reachable and
+# nothing above it is, symlinks included.
+id: dropbox
+name: Dropbox
+
+connector:
+  kind: fs
+  root: ~/Dropbox
+  max_file_bytes: 262144     # one read; a large file is refused rather than truncated
+  exclude: []                # on top of .git, .ssh, node_modules, which are always refused
+
+auth:     { kind: none }
+identity: { kind: connector }
+`;
+  }
+
+  if (kind === 'dav') {
+    return `# Any CalDAV or CardDAV server: Nextcloud, Radicale, Fastmail.
+#
+# Discovery walks .well-known, then the principal, then the collection home —
+# and remembers the result per account, since many servers answer from a
+# per-user host.
+id: nextcloud_calendar
+name: Nextcloud Calendar
+
+connector:
+  kind: dav
+  base_url: https://cloud.example.com
+  service: caldav          # or carddav, for contacts
+
+auth:
+  kind: basic
+
+identity:
+  kind: connector
+
+setup:
+  docs: "Use an app password from Settings → Security."
+  prompts:
+    - key: username
+      label: Username
+      scope: connection
+      field: username
+    - key: password
+      label: App password
+      secret: true
+      scope: connection
+      field: password
+`;
+  }
+
+  return `# A REST API described by OpenAPI.
+#
+# Operations become capabilities automatically — GET and HEAD land in the
+# "read" bundle (granted by default), everything else in "write".
+id: acme
+name: Acme
+description: Whatever this API exposes.
+
+connector:
+  kind: http
+  base_url: https://api.acme.com/v1
+  openapi: https://api.acme.com/openapi.json   # a URL, or a path in this workspace
+  operations:
+    # A large spec yields hundreds of tools, which no agent can reason over.
+    # Narrow it by operationId, path, or tag.
+    include: ["*Account*", "*Payment*"]
+    exclude: []
+
+auth:
+  kind: header
+  header: X-API-Key
+  credential_ref: acme/api_key      # a reference; never the key itself
+
+setup:
+  docs: "Generate a key at https://acme.com/settings/api"
+  prompts:
+    - key: api_key
+      label: Acme API key
+      secret: true
+      credential_ref: acme/api_key
+`;
+}

package/src/providers/example/provider.ts

@@ -0,0 +1,207 @@
+import { z } from 'zod';
+import { defineLocalProvider, keepKeys, type ProviderContext } from '#connectivity';
+
+/**
+ * The example provider — the reference every other provider is written
+ * against, and small enough to reproduce verbatim in
+ * `docs/detailed/creating-a-provider.md`.
+ *
+ * It is also load-bearing beyond being a sample. It declares no auth
+ * requirement and touches no third-party service, which makes it an *owner
+ * provider* in miniature — the same shape memory, skills, and vault take in
+ * M3. If this works, that shape is proven before those exist, and `lanes link connect
+ * example` opening no browser proves the CLI does not assume OAuth-shaped
+ * setup.
+ *
+ * Note what is absent: no `connection` argument is declared anywhere. Core
+ * injects it, fills its enum per profile from resolved policy, and resolves it
+ * to `context.connection` before a handler runs. A provider never thinks about
+ * which account it is serving — that is ADR-001, and it is what lets one tool
+ * set scale to any number of accounts.
+ */
+
+const NOTE_KEY_PREFIX = 'note:';
+
+async function readNote(context: ProviderContext, key: string): Promise<string | null> {
+  return context.state.get(`${NOTE_KEY_PREFIX}${key}`);
+}
+
+export const exampleProvider = defineLocalProvider({
+  id: 'example',
+  name: 'Example',
+  version: '1.0.0',
+  description:
+    'A trivial provider with no external service. Serves as the provider SDK reference and as a way to exercise connection isolation without any credentials.',
+
+  configSchema: z.object({}),
+  connectionSchema: z.object({}),
+
+  bundles: [
+    {
+      name: 'read',
+      description: 'Read notes and echo messages.',
+      oauth_scopes: [],
+      capabilities: ['echo', 'get_note', 'list_notes'],
+      default: true,
+    },
+    {
+      name: 'write',
+      description: 'Create and modify notes.',
+      oauth_scopes: [],
+      capabilities: ['set_note', 'delete_note'],
+    },
+  ],
+
+  capabilities: [
+    {
+      kind: 'tool',
+      name: 'echo',
+      title: 'Echo a message',
+      description:
+        'Return the supplied message unchanged, prefixed with the connection it was routed to. Useful for confirming which account a call reached.',
+      inputSchema: z.object({
+        message: z.string().min(1).describe('Text to echo back'),
+      }),
+      // The message is the whole payload, so recording it verbatim is the
+      // useful choice here. A provider handling real content would not.
+      redact: keepKeys('message'),
+      async handler({ message }, context) {
+        return {
+          content: [{ type: 'text', text: `[${context.connection.key}] ${message}` }],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'set_note',
+      title: 'Store a note',
+      description:
+        'Store a note against this connection. Notes are scoped to the connection, so the same key holds a different value on each one.',
+      inputSchema: z.object({
+        key: z.string().min(1).describe('Note identifier'),
+        value: z.string().describe('Note contents'),
+      }),
+      // The key is safe to record; the value is the content itself.
+      redact: keepKeys('key'),
+      async handler({ key, value }, context) {
+        await context.state.set(`${NOTE_KEY_PREFIX}${key}`, value);
+        context.audit.annotate({ bytes: value.length });
+
+        return {
+          content: [{ type: 'text', text: `Stored note "${key}" on ${context.connection.key}.` }],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'get_note',
+      title: 'Read a note',
+      description: 'Read a note stored against this connection.',
+      inputSchema: z.object({
+        key: z.string().min(1).describe('Note identifier'),
+      }),
+      redact: keepKeys('key'),
+      async handler({ key }, context) {
+        const value = await readNote(context, key);
+
+        if (value === null) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `No note "${key}" on ${context.connection.key}.`,
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        return { content: [{ type: 'text', text: value }] };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'delete_note',
+      title: 'Delete a note',
+      description: 'Remove a note from this connection.',
+      inputSchema: z.object({
+        key: z.string().min(1).describe('Note identifier'),
+      }),
+      redact: keepKeys('key'),
+      async handler({ key }, context) {
+        await context.state.delete(`${NOTE_KEY_PREFIX}${key}`);
+        return {
+          content: [{ type: 'text', text: `Deleted note "${key}" from ${context.connection.key}.` }],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'list_notes',
+      title: 'List note keys',
+      description: 'List the keys of every note stored against this connection.',
+      inputSchema: z.object({}),
+      async handler(_input, context) {
+        const keys = (await context.state.keys())
+          .filter((key) => key.startsWith(NOTE_KEY_PREFIX))
+          .map((key) => key.slice(NOTE_KEY_PREFIX.length));
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text:
+                keys.length > 0
+                  ? keys.join('\n')
+                  : `No notes on ${context.connection.key} yet.`,
+            },
+          ],
+        };
+      },
+    },
+
+    /**
+     * A resource rather than a tool, deliberately — ADR-006.
+     *
+     * A note is read-oriented structured context addressed by a stable
+     * identifier, which is exactly what resources are for. Making everything a
+     * tool is the easy default and the wrong one; the distinction matters much
+     * more for M3's memory and skills than it does here, so it is worth
+     * exercising now while the cost of getting it wrong is nil.
+     */
+    {
+      kind: 'resource',
+      name: 'note',
+      title: 'Note',
+      description: 'A stored note, addressed by key.',
+      uriTemplate: 'example://note/{key}',
+      mimeType: 'text/plain',
+
+      async list(context) {
+        const keys = await context.state.keys();
+        return keys
+          .filter((key) => key.startsWith(NOTE_KEY_PREFIX))
+          .map((key) => {
+            const name = key.slice(NOTE_KEY_PREFIX.length);
+            return { uri: `example://note/${encodeURIComponent(name)}`, name };
+          });
+      },
+
+      async read(uri, params, context) {
+        const key = params['key'];
+        if (!key) throw new Error(`Malformed note URI: ${uri}`);
+
+        const value = await readNote(context, decodeURIComponent(key));
+        if (value === null) throw new Error(`No note "${key}" on ${context.connection.key}`);
+
+        return { uri, mimeType: 'text/plain', text: value };
+      },
+    },
+  ],
+});
+
+export default exampleProvider;

package/src/providers/google/calendar/index.ts

@@ -0,0 +1,66 @@
+import { defineProvider } from '#connectivity';
+import { CALENDAR_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleSetup } from '../shared/setup.ts';
+import { CALENDAR_REDACT } from './redact.ts';
+
+/**
+ * Read and write events without holding the calendar.
+ *
+ * Google splits Calendar the way it splits Drive, and here the split is usable.
+ * `calendar.events` reaches every event on every calendar and reaches nothing
+ * else: it cannot create a calendar, delete one, or change who it is shared
+ * with. Those are `auth/calendar`, which is this provider's `mail.google.com`
+ * and is not requested.
+ *
+ * `calendar.readonly` sits beside it and is not redundant. Two of the reads
+ * accept nothing narrower — listing the calendars, and `freeBusy`, which is the
+ * "when am I free" primitive and answers across calendars whose contents the
+ * token may not read. Dropping it would cost the two operations an assistant
+ * needs most.
+ *
+ * `calendar.events` is marked broad in `../shared/scopes.ts` and should stay
+ * marked. Two narrower scopes do exist — `calendar.events.owned` and
+ * `calendar.app.created`, Calendar's answer to `drive.file` — and neither is
+ * usable: the vendored spec's per-operation `security` blocks name only the
+ * scopes Google published when it was generated, so requesting one would fail
+ * `specs.test.ts` and, more to the point, would fail at Google.
+ * `calendar.app.created` also has the `drive.file` disease in a worse form — it
+ * reaches only calendars this app made, and the calendar anyone means is the
+ * primary one they already had.
+ *
+ * Note the `base_url`: Calendar carries its version in the host, like Drive
+ * (`/calendar/v3` + `/calendars/{id}/events`). Copying the Sheets shape yields
+ * `/v3/v3/...` and a 404 on every call.
+ */
+const CALENDAR_SCOPES = [
+  'https://www.googleapis.com/auth/calendar.readonly',
+  'https://www.googleapis.com/auth/calendar.events',
+];
+
+export const calendar = defineProvider({
+  id: 'calendar',
+  name: 'Google Calendar',
+  description:
+    'Read and write calendar events — list, search, create, reschedule, and cancel — and answer when you are free, via the Calendar REST API.',
+  connector: {
+    kind: 'http',
+    base_url: 'https://www.googleapis.com/calendar/v3',
+    openapi: specPath('calendar.v3.json'),
+  },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: GOOGLE_APP,
+    scopes: CALENDAR_SCOPES,
+    ...GOOGLE_OAUTH,
+  },
+  identity: CALENDAR_IDENTITY,
+  setup: googleSetup('Calendar', CALENDAR_SCOPES, {
+    // `calendar-json.googleapis.com`, not `calendar.googleapis.com`. The
+    // service is registered under its discovery host, and enabling the
+    // plausible-looking name leaves consent succeeding and every call
+    // answering 403 — the failure this whole setup block exists to prevent.
+    apis: ['calendar-json.googleapis.com'],
+  }),
+  redact: CALENDAR_REDACT,
+});

package/src/providers/google/calendar/redact.ts

@@ -0,0 +1,40 @@
+/**
+ * What survives into the audit log when an event is read or changed.
+ *
+ * The generated tools flatten a request body into top-level arguments, so
+ * `summary`, `description`, `location`, and `attendees` really are argument
+ * names here — and they are the meeting. Keeping them would put "1:1 re
+ * redundancy consultation" and the list of who was invited in a log meant to
+ * record that a change happened, not to hold a second copy of the calendar.
+ *
+ * `sendUpdates` is kept on every write, and it is the one flag worth reading
+ * back: cancelling a meeting quietly and cancelling it with mail to everyone
+ * invited are different acts, and only this argument tells them apart.
+ *
+ * `q` is withheld on Gmail's reasoning — a search is a question, and "who am I
+ * meeting about the redundancy" is content whoever typed it did not expect to
+ * keep. `freebusy.query`'s `items` is withheld on the same ground, which is the
+ * one call worth explaining: `calendarId` is kept everywhere else because it
+ * names the resource being read or written, but a `freeBusy` `items` list is a
+ * set of *people you asked about*. That is the query, not the subject.
+ */
+export const CALENDAR_REDACT: Record<string, string[]> = {
+  'calendarList.list': ['minAccessRole', 'showHidden', 'maxResults'],
+  'events.list': [
+    'calendarId',
+    'timeMin',
+    'timeMax',
+    'singleEvents',
+    'orderBy',
+    'maxResults',
+    'showDeleted',
+    'eventTypes',
+  ],
+  'events.get': ['calendarId', 'eventId'],
+  'events.instances': ['calendarId', 'eventId', 'timeMin', 'timeMax', 'maxResults'],
+  'freebusy.query': ['timeMin', 'timeMax', 'timeZone'],
+  'events.insert': ['calendarId', 'sendUpdates', 'conferenceDataVersion'],
+  'events.patch': ['calendarId', 'eventId', 'sendUpdates'],
+  'events.delete': ['calendarId', 'eventId', 'sendUpdates'],
+  'events.move': ['calendarId', 'eventId', 'destination', 'sendUpdates'],
+};

package/src/providers/google/contacts/index.ts

@@ -0,0 +1,50 @@
+import { defineProvider } from '#connectivity';
+import { GOOGLE_APP, GOOGLE_OAUTH, PEOPLE_IDENTITY, specPath } from '../shared/oauth.ts';
+import { googleSetup } from '../shared/setup.ts';
+import { CONTACTS_REDACT } from './redact.ts';
+
+/**
+ * Read-only, so that "email Bob" resolves to an address.
+ *
+ * Two scopes, because Google keeps contacts in two places.
+ * `contacts.readonly` is the address book someone curated;
+ * `contacts.other.readonly` is where Gmail files an address written to but
+ * never saved, which is where most of the Bobs actually are. Asking for only
+ * the first would answer confidently and wrongly for the common case.
+ *
+ * Both are read-only, so neither is marked broad. The write scope is
+ * `contacts`, it permanently deletes, and it is not requested — nothing here
+ * writes. A contact card is the shape where a round trip silently destroys
+ * data, which is the same reason `icloud_contacts` declines to edit one.
+ *
+ * The provider is `contacts` while Google's API is People. That mismatch is
+ * load-bearing in `redact.ts` — see the note there — and it is deliberate: the
+ * thing an operator connects is their contacts, and `icloud_contacts` is
+ * already the neighbour in the list.
+ */
+const CONTACTS_SCOPES = [
+  'https://www.googleapis.com/auth/contacts.readonly',
+  'https://www.googleapis.com/auth/contacts.other.readonly',
+];
+
+export const contacts = defineProvider({
+  id: 'contacts',
+  name: 'Google Contacts',
+  description:
+    'Look up a saved contact by name to find their address or phone number, including the addresses Gmail saved automatically. Read-only, via the People REST API.',
+  connector: {
+    kind: 'http',
+    base_url: 'https://people.googleapis.com',
+    openapi: specPath('people.v1.json'),
+  },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: GOOGLE_APP,
+    scopes: CONTACTS_SCOPES,
+    ...GOOGLE_OAUTH,
+  },
+  identity: PEOPLE_IDENTITY,
+  setup: googleSetup('Contacts', CONTACTS_SCOPES, { apis: ['people.googleapis.com'] }),
+  redact: CONTACTS_REDACT,
+});

package/src/providers/google/contacts/redact.ts

@@ -0,0 +1,21 @@
+/**
+ * What survives into the audit log when contacts are searched.
+ *
+ * The keys carry a `people.` prefix that no other Google provider here needs,
+ * and it is not a typo. `shortenName` strips the *provider id* from an
+ * operationId, and this provider is `contacts` while Google's operationIds all
+ * say `people` — so nothing is stripped, and the capability really is called
+ * `people.people.searchContacts`. A key written `people.searchContacts` would
+ * match nothing, withhold every value, and look exactly like redaction working.
+ *
+ * `query` is withheld throughout. A name someone is looking up is content, and
+ * it is the line `icloud_contacts.search_contacts` already draws. What is kept
+ * is the shape of the request: how many were asked for, which fields, and — on
+ * `getBatchGet` — the opaque resource names, which are identifiers rather than
+ * anything a person wrote.
+ */
+export const CONTACTS_REDACT: Record<string, string[]> = {
+  'people.people.searchContacts': ['pageSize', 'readMask'],
+  'people.otherContacts.search': ['pageSize', 'readMask'],
+  'people.people.getBatchGet': ['resourceNames', 'personFields'],
+};