@lanes-sh/link 0.6.10 → 0.7.0

package/src/providers/example/provider.ts

@@ -4,7 +4,7 @@ import { defineLocalProvider, keepKeys, type ProviderContext } from '#connectivi
 /**
  * The example provider — the reference every other provider is written
  * against, and small enough to reproduce verbatim in
- * `docs/detailed/creating-a-provider.md`.
+ * `https://lanes.sh/docs/link/creating-a-provider`.
  *
  * 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

package/src/providers/expensify/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Expensify registers us at connect time — nothing for an operator to set up. */
+export const expensify = defineProvider({
+  id: 'expensify',
+  name: 'Expensify',
+  description: 'Expenses, reports, and receipts, via Expensify\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.expensify.com/mcp/' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

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

@@ -0,0 +1,21 @@
+import { defineProvider } from '#connectivity';
+import { FASTMAIL_APP, fastmailSetup } from '../shared/setup.ts';
+
+export const fastmailCalendar = defineProvider({
+  id: 'fastmail_calendar',
+  name: 'Fastmail Calendar',
+  description: 'Read and create events in Fastmail calendars over CalDAV.',
+  connector: { kind: 'dav', base_url: 'https://caldav.fastmail.com', service: 'caldav' },
+  auth: { kind: 'basic', app: FASTMAIL_APP },
+  identity: { kind: 'connector' },
+  setup: fastmailSetup('Fastmail Calendar'),
+  redact: {
+    list_events: ['calendar', 'start', 'end', 'limit'],
+    get_event: ['calendar', 'uid'],
+    // The uid and calendar say *which* event changed; the summary and location
+    // are the content of it.
+    update_event: ['calendar', 'uid'],
+    delete_event: ['calendar', 'uid'],
+    create_event: ['calendar'],
+  },
+});

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

@@ -0,0 +1,17 @@
+import { defineProvider } from '#connectivity';
+import { FASTMAIL_APP, fastmailSetup } from '../shared/setup.ts';
+
+export const fastmailContacts = defineProvider({
+  id: 'fastmail_contacts',
+  name: 'Fastmail Contacts',
+  description: 'Search and read contacts in a Fastmail address book over CardDAV.',
+  connector: { kind: 'dav', base_url: 'https://carddav.fastmail.com', service: 'carddav' },
+  auth: { kind: 'basic', app: FASTMAIL_APP },
+  identity: { kind: 'connector' },
+  setup: fastmailSetup('Fastmail Contacts'),
+  redact: {
+    // Not `query`: a name is content.
+    search_contacts: ['addressbook', 'limit'],
+    create_contact: ['addressbook'],
+  },
+});

package/src/providers/fastmail/index.ts

@@ -0,0 +1,4 @@
+/** Fastmail's three providers, sharing one app password. */
+export { fastmailCalendar } from './calendar/index.ts';
+export { fastmailContacts } from './contacts/index.ts';
+export { fastmailMail } from './mail/index.ts';

package/src/providers/fastmail/mail/index.ts

@@ -0,0 +1,38 @@
+import { defineProvider } from '#connectivity';
+import { FASTMAIL_APP, fastmailSetup } from '../shared/setup.ts';
+
+export const fastmailMail = defineProvider({
+  // `fastmail_mail`, not `fastmail`: the bare name is the credential app the
+  // three share, so `lanes link connect fastmail` fans out to all of them and
+  // asks for the password once. Same arrangement as iCloud.
+  id: 'fastmail_mail',
+  name: 'Fastmail Mail',
+  description:
+    'Read, search, and send mail in a Fastmail mailbox over IMAP and SMTP, with an app password that does not expire.',
+  connector: {
+    kind: 'imap',
+    host: 'imap.fastmail.com',
+    port: 993,
+    smtp: { host: 'smtp.fastmail.com', port: 587, starttls: true },
+  },
+  auth: { kind: 'basic', app: FASTMAIL_APP },
+  identity: { kind: 'connector' },
+  setup: fastmailSetup('Fastmail'),
+  redact: {
+    // Never the search terms — a query is content, and "who did I email about
+    // the diagnosis" is the whole message.
+    search_messages: ['mailbox', 'limit', 'unseen', 'flagged'],
+    // Identifiers only, and all of them: which mailbox, which message, which
+    // attachment. What the file turned out to be — name, size, type, digest —
+    // is recorded by the handler through `audit.annotate`, the same way the send
+    // path records what it attached.
+    get_attachment: ['mailbox', 'uid', 'message_id', 'attachment_id'],
+    get_message: ['mailbox', 'uid', 'include_body'],
+    mark_messages: ['mailbox', 'add_flags', 'remove_flags'],
+    move_messages: ['mailbox', 'destination', 'destination_flag'],
+    // Nothing. The recipients and the body are the message, and `attachments`
+    // may literally contain a file — what was attached is recorded by the send
+    // path itself through `audit.annotate`.
+    send_message: [],
+  },
+});

package/src/providers/fastmail/shared/setup.ts

@@ -0,0 +1,52 @@
+export const FASTMAIL_APP = 'fastmail';
+
+/**
+ * Fastmail: one account, three providers, one app password.
+ *
+ * The same shape as iCloud and for the same reason — mail is IMAP, calendars
+ * are CalDAV, and a manifest has one connector — but arrived at from the
+ * opposite direction. Apple has no other route; Fastmail has a JMAP API and
+ * simply does not need one here, because a single app password can be issued
+ * with access to mail, calendars and contacts together, and the three transports
+ * this repository already speaks reach all of it.
+ *
+ * `app: fastmail` resolves all three to one `fastmail/<account>` credential, so
+ * the password is typed once. Fastmail lets you narrow an app password to one
+ * protocol; if you do, connect the providers you scoped it for and no others —
+ * a password scoped to mail authenticates against CalDAV and then finds nothing.
+ */
+export const fastmailSetup = (product: string) => ({
+  summary:
+    `${product} uses an app password rather than your Fastmail password, which Fastmail refuses ` +
+    `for IMAP, CalDAV and CardDAV. You are asked once: one app password can cover Mail, ` +
+    `Calendars and Contacts together, because Fastmail issues it per app rather than per service.`,
+  docs_url: 'https://www.fastmail.help/hc/en-us/articles/360058752854',
+  steps: [
+    'Sign in at https://app.fastmail.com and open Settings → Privacy & Security → Integrations.',
+    'Under "App passwords", choose "New app password". Name it "Lanes Link" — the name is the only way to revoke this one later without cutting off your other devices.',
+    'For access, pick the set that matches what you are connecting. "Mail (IMAP/SMTP)" covers the mail provider; "Contacts (CardDAV)" and "Calendars (CalDAV)" cover the other two. Choosing all three is what lets you type the password once.',
+    'Copy the password Fastmail shows. It is shown once, and it is not your account password.',
+    'You are asked for your address next — the full one you sign in with, which may be at fastmail.com or at your own domain.',
+  ],
+  troubleshooting:
+    'For Fastmail this is almost always the account password used where an app password belongs, or an app ' +
+    'password scoped to a protocol other than the one being connected — one scoped to Mail alone will not ' +
+    'authenticate against CalDAV. Create one at https://app.fastmail.com under Settings → Privacy & Security ' +
+    '→ Integrations and re-run: lanes link connect fastmail --replace.',
+  prompts: [
+    {
+      key: 'username',
+      label: 'Fastmail address (the full email address)',
+      secret: false,
+      scope: 'connection' as const,
+      field: 'username' as const,
+    },
+    {
+      key: 'password',
+      label: 'App password',
+      secret: true,
+      scope: 'connection' as const,
+      field: 'password' as const,
+    },
+  ],
+});

package/src/providers/figma/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Figma registers us at connect time — nothing for an operator to set up. */
+export const figma = defineProvider({
+  id: 'figma',
+  name: 'Figma',
+  description: 'Files, designs, components, and Dev Mode context, via Figma\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.figma.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/fireflies/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Fireflies registers us at connect time — nothing for an operator to set up. */
+export const fireflies = defineProvider({
+  id: 'fireflies',
+  name: 'Fireflies',
+  description: 'Meeting transcripts, summaries, and action items, via Fireflies\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://api.fireflies.ai/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/flagsmith/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Flagsmith registers us at connect time — nothing for an operator to set up. */
+export const flagsmith = defineProvider({
+  id: 'flagsmith',
+  name: 'Flagsmith',
+  description: 'Feature flags, segments, and environments, via Flagsmith\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.flagsmith.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/gamma/index.ts

@@ -0,0 +1,10 @@
+import { defineProvider } from '#connectivity';
+
+/** Gamma registers us at connect time — nothing for an operator to set up. */
+export const gamma = defineProvider({
+  id: 'gamma',
+  name: 'Gamma',
+  description: 'Presentations and documents, generated and read back, via Gamma\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.gamma.app/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+});

package/src/providers/github/index.ts

@@ -16,7 +16,7 @@ import { GITHUB_REDACT } from './redact.ts';
  * The toolsets header is the whole reason `connector.headers` exists. GitHub
  * serves a different tool list per toolset and `all` is far more than an agent
  * reasons over; this asks for the ones an agent working in a repository
- * actually uses. It is one string to change, and `docs/detailed/setup/github.md`
+ * actually uses. It is one string to change, and `https://lanes.sh/docs/link/github`
  * records the read-only variant for someone who wants a narrower connection.
  */
 export const github = defineProvider({
@@ -41,7 +41,7 @@ export const github = defineProvider({
       'GitHub issues a fine-grained personal access token for this. There is no OAuth app to register: ' +
       'GitHub\'s MCP server does not support the dynamic registration Notion and Linear use, and an OAuth ' +
       'app of your own would need a fixed callback port, which this CLI does not have. You are asked once.',
-    docs: 'docs/detailed/setup/github.md',
+    docs: 'https://lanes.sh/docs/link/github',
     docs_url: 'https://github.com/settings/personal-access-tokens',
     steps: [
       'Open https://github.com/settings/personal-access-tokens and choose "Generate new token".',

package/src/providers/google/gmail/attachment.ts

@@ -40,7 +40,22 @@ export function gmailAttachments(input: {
     return (await response.json()) as Record<string, unknown>;
   };
 
-  return async ({ messageId, attachmentId }) => {
+  return async ({ messageId, uid, attachmentId }) => {
+    // Gmail's REST API has no mailbox uid — a message is named by the id
+    // `messages.list` reports, and a label is not a folder to EXAMINE. Saying so
+    // and naming the key that does work is the whole job here: the alternative
+    // is a caller who read "uid" in the shared schema getting a 404 from Google
+    // that explains nothing.
+    if (uid !== undefined) {
+      throw new Error(
+        'Gmail names a message by its id rather than a mailbox uid. Use message_id, with the id ' +
+          'gmail.users_messages_list reports. A uid belongs to the IMAP providers — gmail_imap, icloud_mail, fastmail_mail.',
+      );
+    }
+    if (messageId === undefined) {
+      throw new Error('Re-attaching from Gmail needs message_id.');
+    }
+
     const message = await get(`/messages/${encodeURIComponent(messageId)}?format=full`);
     const parts = attachmentParts(message['payload']);
 

package/src/providers/google/gmail-imap/index.ts

@@ -10,7 +10,7 @@ import { defineProvider } from '#connectivity';
  * - The REST provider (`gmail`) authorises in a browser, and an OAuth client
  *   left in "Testing" has every refresh token it issues expired after seven
  *   days. Publishing the client fixes that and is the better answer where it is
- *   available — see ADR-038 and `docs/detailed/setup/google.md`.
+ *   available — see ADR-038 and `https://lanes.sh/docs/link/google`.
  * - The key route (`auth.assertion` on `gmail`) does not apply at all. A service
  *   account has no mailbox of its own, so it can only reach one by acting as
  *   somebody, and that grant is domain-wide delegation — made in a Workspace
@@ -71,7 +71,7 @@ export const gmailImap = defineProvider({
       'browser and nothing has to be re-approved later. This is the personal-account route: ' +
       'Google turned off basic authentication for Workspace accounts in March 2025, and a Workspace ' +
       'administrator can disable app passwords for the whole domain.',
-    docs: 'docs/detailed/setup/google.md',
+    docs: 'https://lanes.sh/docs/link/google',
     docs_url: 'https://support.google.com/accounts/answer/185833',
     steps: [
       'Two-Step Verification has to be on. Without it Google does not offer app passwords at all, and the page below returns "the setting you are looking for is not available for your account" rather than saying why. Turn it on at https://myaccount.google.com/signinoptions/twosv.',
@@ -111,6 +111,11 @@ export const gmailImap = defineProvider({
     // Never the search terms — a query is content, and "who did I email about
     // the diagnosis" is the whole message.
     search_messages: ['mailbox', 'limit', 'unseen', 'flagged'],
+    // Identifiers only, and all of them: which mailbox, which message, which
+    // attachment. What the file turned out to be — name, size, type, digest —
+    // is recorded by the handler through `audit.annotate`, the same way the send
+    // path records what it attached.
+    get_attachment: ['mailbox', 'uid', 'message_id', 'attachment_id'],
     get_message: ['mailbox', 'uid', 'include_body'],
     mark_messages: ['mailbox', 'add_flags', 'remove_flags'],
     // `destination_flag` alongside `destination`: two spellings of the same

package/src/providers/google/shared/oauth.ts

@@ -25,7 +25,7 @@ export const GOOGLE_APP = 'google';
  *
  * What this buys the operator is the whole of `setup/google.md`: no project, no
  * console, and no scope list to transcribe. What it costs is recorded in
- * ADR-028 and in the guarantee table in `docs/detailed/security.md` — chiefly
+ * ADR-028 and in the guarantee table in `https://lanes.sh/docs/link/security` — chiefly
  * that the exchange stops being local.
  *
  * What it does *not* buy, and used to claim to: escape from the seven-day

package/src/providers/google/shared/service-account.ts

@@ -75,7 +75,7 @@ export const googleServiceAccount = (
           `route works only where a Google Workspace administrator has authorised the key to act ` +
           `as a user in their domain. On a personal Google account, use the browser instead` +
           (instead ? `, or ${instead}, which is an app password over IMAP and does not expire either.` : '.'),
-    docs: 'docs/detailed/setup/google.md',
+    docs: 'https://lanes.sh/docs/link/google',
     docs_url: 'https://console.cloud.google.com/iam-admin/serviceaccounts',
     steps: [
       'Create or pick a project at https://console.cloud.google.com',

package/src/providers/google/shared/setup.ts

@@ -38,7 +38,7 @@ export const googleSetup = (
 
   return {
     summary: `${product} signs in with Google. By default it authorises against the OAuth client Lanes operates, so there is nothing to register and no client secret on this machine — the code is exchanged for a token by the Lanes API, which holds that secret. Pass --own-client to register a client of your own instead; the steps below are that path, asked once per profile and then covering every Google account you connect.`,
-    docs: 'docs/detailed/setup/google.md',
+    docs: 'https://lanes.sh/docs/link/google',
     docs_url: 'https://console.cloud.google.com/auth',
     // AUDIENCE leads with Internal, and the ordering is the point rather than a
     // preference. The seven-day `invalid_grant` everyone hits is a property of

package/src/providers/google/specs/calendar.v3.json

@@ -1085,38 +1085,6 @@
           "type": "string"
         }
       },
-      "key": {
-        "description": "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.",
-        "in": "query",
-        "name": "key",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "oauth_token": {
-        "description": "OAuth 2.0 token for the current user.",
-        "in": "query",
-        "name": "oauth_token",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "prettyPrint": {
-        "description": "Returns response with indentations and line breaks.",
-        "in": "query",
-        "name": "prettyPrint",
-        "schema": {
-          "type": "boolean"
-        }
-      },
-      "quotaUser": {
-        "description": "An opaque string that represents a user for quota purposes. Must not exceed 40 characters.",
-        "in": "query",
-        "name": "quotaUser",
-        "schema": {
-          "type": "string"
-        }
-      },
       "userIp": {
         "description": "Deprecated. Please use quotaUser instead.",
         "in": "query",

package/src/providers/google/specs/docs.v1.json

@@ -206,26 +206,6 @@
   },
   "components": {
     "parameters": {
-      "_.xgafv": {
-        "description": "V1 error format.",
-        "in": "query",
-        "name": "$.xgafv",
-        "schema": {
-          "enum": [
-            "1",
-            "2"
-          ],
-          "type": "string"
-        }
-      },
-      "access_token": {
-        "description": "OAuth access token.",
-        "in": "query",
-        "name": "access_token",
-        "schema": {
-          "type": "string"
-        }
-      },
       "alt": {
         "description": "Data format for response.",
         "in": "query",
@@ -239,14 +219,6 @@
           "type": "string"
         }
       },
-      "callback": {
-        "description": "JSONP",
-        "in": "query",
-        "name": "callback",
-        "schema": {
-          "type": "string"
-        }
-      },
       "fields": {
         "description": "Selector specifying which fields to include in a partial response.",
         "in": "query",
@@ -254,54 +226,6 @@
         "schema": {
           "type": "string"
         }
-      },
-      "key": {
-        "description": "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.",
-        "in": "query",
-        "name": "key",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "oauth_token": {
-        "description": "OAuth 2.0 token for the current user.",
-        "in": "query",
-        "name": "oauth_token",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "prettyPrint": {
-        "description": "Returns response with indentations and line breaks.",
-        "in": "query",
-        "name": "prettyPrint",
-        "schema": {
-          "type": "boolean"
-        }
-      },
-      "quotaUser": {
-        "description": "Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.",
-        "in": "query",
-        "name": "quotaUser",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "uploadType": {
-        "description": "Legacy upload protocol for media (e.g. \"media\", \"multipart\").",
-        "in": "query",
-        "name": "uploadType",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "upload_protocol": {
-        "description": "Upload protocol for media (e.g. \"raw\", \"multipart\").",
-        "in": "query",
-        "name": "upload_protocol",
-        "schema": {
-          "type": "string"
-        }
       }
     },
     "schemas": {

package/src/providers/google/specs/drive.v3.json

@@ -1236,38 +1236,6 @@
           "type": "string"
         }
       },
-      "key": {
-        "description": "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.",
-        "in": "query",
-        "name": "key",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "oauth_token": {
-        "description": "OAuth 2.0 token for the current user.",
-        "in": "query",
-        "name": "oauth_token",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "prettyPrint": {
-        "description": "Returns response with indentations and line breaks.",
-        "in": "query",
-        "name": "prettyPrint",
-        "schema": {
-          "type": "boolean"
-        }
-      },
-      "quotaUser": {
-        "description": "An opaque string that represents a user for quota purposes. Must not exceed 40 characters.",
-        "in": "query",
-        "name": "quotaUser",
-        "schema": {
-          "type": "string"
-        }
-      },
       "userIp": {
         "description": "Deprecated. Please use quotaUser instead.",
         "in": "query",

package/src/providers/google/specs/gmail.v1.json

@@ -2057,26 +2057,6 @@
   },
   "components": {
     "parameters": {
-      "_.xgafv": {
-        "description": "V1 error format.",
-        "in": "query",
-        "name": "$.xgafv",
-        "schema": {
-          "enum": [
-            "1",
-            "2"
-          ],
-          "type": "string"
-        }
-      },
-      "access_token": {
-        "description": "OAuth access token.",
-        "in": "query",
-        "name": "access_token",
-        "schema": {
-          "type": "string"
-        }
-      },
       "alt": {
         "description": "Data format for response.",
         "in": "query",
@@ -2090,14 +2070,6 @@
           "type": "string"
         }
       },
-      "callback": {
-        "description": "JSONP",
-        "in": "query",
-        "name": "callback",
-        "schema": {
-          "type": "string"
-        }
-      },
       "fields": {
         "description": "Selector specifying which fields to include in a partial response.",
         "in": "query",
@@ -2105,54 +2077,6 @@
         "schema": {
           "type": "string"
         }
-      },
-      "key": {
-        "description": "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.",
-        "in": "query",
-        "name": "key",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "oauth_token": {
-        "description": "OAuth 2.0 token for the current user.",
-        "in": "query",
-        "name": "oauth_token",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "prettyPrint": {
-        "description": "Returns response with indentations and line breaks.",
-        "in": "query",
-        "name": "prettyPrint",
-        "schema": {
-          "type": "boolean"
-        }
-      },
-      "quotaUser": {
-        "description": "Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.",
-        "in": "query",
-        "name": "quotaUser",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "uploadType": {
-        "description": "Legacy upload protocol for media (e.g. \"media\", \"multipart\").",
-        "in": "query",
-        "name": "uploadType",
-        "schema": {
-          "type": "string"
-        }
-      },
-      "upload_protocol": {
-        "description": "Upload protocol for media (e.g. \"raw\", \"multipart\").",
-        "in": "query",
-        "name": "upload_protocol",
-        "schema": {
-          "type": "string"
-        }
       }
     },
     "schemas": {