@lanes-sh/link 0.7.2 → 0.8.0

package/src/cli/commands/connect/options.ts

@@ -0,0 +1,83 @@
+import type { GlobalFlags } from '../../runtime.ts';
+
+/**
+ * What `lanes link connect` accepts, and what it hands back.
+ *
+ * Split out of `index.ts` so that file stays inside the size budget. The seam is
+ * the one the command already has: this is the shape of the request, and that is
+ * the six steps that carry it out.
+ */
+
+/**
+ * `lanes link connect <provider>` — the one command that adds an account.
+ *
+ * The same command regardless of connectivity. A local provider declares a
+ * connection and stops; an MCP provider authorises, asks the upstream server
+ * what it exposes, and grants it. Core learns nothing about any vendor: the
+ * manifest says how to reach them and what to ask the operator for.
+ *
+ * The five numbered steps below are the whole command, and each one that grew
+ * past a paragraph moved out: `authorise.ts` gets the token, `setup.ts` asks the
+ * operator for what the vendor's console produced, `settle.ts` works out whose
+ * account it was, and `accounts.ts` knows which connections are siblings.
+ */
+
+export interface ConnectOptions extends GlobalFlags {
+  readonly id?: string | undefined;
+  readonly displayName?: string | undefined;
+  /** `--set key=value`, repeatable: where this connection's service is. */
+  readonly set?: readonly string[] | string | undefined;
+  /**
+   * `--label`: what to call this connection, instead of being asked.
+   *
+   * Distinct from `--display-name`, which answers *whose account this is* for a
+   * provider that cannot report it. This one never touches the identity, so it
+   * is safe to pass anything a person would say out loud.
+   */
+  readonly label?: string | undefined;
+  /** Ask for the stored credential again — a key rotated, or a password revoked. */
+  readonly replace?: boolean | undefined;
+  /**
+   * Answer nothing from a terminal: resolve every declared value from the
+   * credential store, and refuse with instructions where one is missing.
+   */
+  readonly nonInteractive?: boolean | undefined;
+  /** The operator has already agreed to scopes broader than the provider needs. */
+  readonly acceptBroadScopes?: boolean | undefined;
+  /**
+   * Register an OAuth client of your own rather than using a hosted one.
+   *
+   * Sticky by consequence rather than by flag: it writes the `oauth_apps` entry,
+   * and a profile that declares one is never moved off it. So this is typed once
+   * and then forgotten, which is the right shape for a decision about a client
+   * that is shared by every connection of that vendor.
+   */
+  /**
+   * `--own-client`, the older spelling of one of the routes `--auth` now names.
+   *
+   * Kept because it is in scripts and in a year of documentation, and because
+   * it still says something true. It resolves to `--auth own_client`.
+   */
+  readonly ownClient?: boolean | undefined;
+  /**
+   * `--auth <method>`: which way in, for a provider that offers more than one.
+   *
+   * Unset means ask, where there is somebody to ask and something to ask
+   * about. It is not sticky the way `--own-client` is: `--own-client` writes an
+   * `oauth_apps` entry that every connection of the vendor then reads, whereas
+   * this decides one connection's credential and is recorded by that credential
+   * existing. Two accounts on the same profile may honestly differ.
+   */
+  readonly auth?: string | undefined;
+  /** Injected for tests. The broker is the only thing `connect` fetches. */
+  readonly fetch?: typeof globalThis.fetch | undefined;
+  readonly json?: boolean | undefined;
+}
+
+
+/**
+ * The connection id used before the provider has said whose account this is.
+ *
+ * It is a placeholder rather than a name, and `setup.ts` reads it as one: a
+ * credential filed under it belongs to a `connect` that did not finish.
+ */

package/src/cli/commands/connect/registration.ts

@@ -0,0 +1,50 @@
+import type { ProviderManifest } from '#connectivity';
+
+/**
+ * Turn a refused registration into something an operator can act on.
+ *
+ * A provider declaring `registration: 'dynamic'` is promising that its
+ * authorization server will register a client on demand — that is the whole
+ * reason those providers need no setup. When the server refuses, the SDK throws
+ * the status and nothing else, and "Dynamic Client Registration rejected (HTTP
+ * 403): Forbidden" tells the reader neither what was being attempted nor that
+ * there is nothing wrong with their machine.
+ *
+ * It is a real state rather than a bug: a server may advertise a registration
+ * endpoint and gate it behind a plan, an allowlist, or a signed-in session.
+ * Figma's does, which is how this was found. What the operator needs to know is
+ * that the refusal came from the provider, that we sent nothing wrong, and
+ * where the answer lives — which is the provider's own documentation, because
+ * whatever unlocks it is theirs to state.
+ */
+export async function registering<T>(
+  manifest: ProviderManifest,
+  serverUrl: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  if (manifest.auth.kind !== 'oauth' || manifest.auth.registration !== 'dynamic') return run();
+
+  try {
+    return await run();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!/registration/i.test(message)) throw error;
+
+    const host = new URL(serverUrl).host;
+    throw new Error(
+      `${manifest.name} refused to register this machine as a client.\n` +
+        `  ${message}\n` +
+        '\n' +
+        `  Nothing was written, and nothing about your setup is wrong: ${host}\n` +
+        '  advertises registration and then declined it. That is usually a plan, an\n' +
+        '  allowlist, or an account that has to be signed in first.\n' +
+        `  What unlocks it is theirs to say: ${docsFor(manifest) ?? host}`,
+    );
+  }
+}
+
+/** Where the provider tells you what it wants, when the manifest names it. */
+function docsFor(manifest: ProviderManifest): string | undefined {
+  const setup = (manifest as { setup?: { docs_url?: unknown } }).setup;
+  return typeof setup?.docs_url === 'string' ? setup.docs_url : undefined;
+}

package/src/cli/commands/connect/requirements.ts

@@ -102,7 +102,7 @@ export async function preflight(input: {
 }): Promise<Blocked | null> {
   const { manifest, connectionId, profile, target, spec } = input;
   const method = input.method ?? 'oauth';
-  const rerun = `lanes link connect ${spec} --profile ${profile} --target ${target}`;
+  const rerun = `lanes link connect ${spec} --profile ${profile} --workspace ${target}`;
   const assertion = manifest.auth.kind === 'oauth' ? manifest.auth.assertion : undefined;
 
   if (method === 'assertion' && assertion) {

package/src/cli/commands/connect/settle.ts

@@ -1,7 +1,7 @@
 import { createMcpConnector } from '#connectivity/transports';
 import { bearerTokenAsStored } from '#connectivity/auth/index.ts';
 import type { SecretStore } from '#secrets';
-import type { Config } from '#profile';
+import type { ConnectionConfig, Config } from '#profile';
 import type { AnyConnector, ProviderManifest } from '#connectivity';
 import { idFromAccount, resolveAccount } from '../../identity.ts';
 import { style } from '../../output.ts';
@@ -38,6 +38,8 @@ export async function settleIdentity(input: {
   label?: string | undefined;
   runtime: {
     config: Config;
+    /** Every account the workspace holds, for sibling matching (ADR-057). */
+    workspaceConnections: readonly ConnectionConfig[];
     credentials: SecretStore;
     registry: { manifest(id: string): ProviderManifest | undefined };
     connectorFor(providerId: string, connectionId: string): AnyConnector | undefined;
@@ -51,7 +53,7 @@ export async function settleIdentity(input: {
   // Siblings across the whole vendor account, not just this provider — so
   // connecting iCloud Calendar after iCloud Mail lands on the same id, and
   // therefore the same credential, rather than a second `will2`.
-  const siblings = accountSiblings(manifest, runtime.config, runtime.registry);
+  const siblings = accountSiblings(manifest, runtime.workspaceConnections, runtime.registry);
 
   let account = input.account ?? null;
 

package/src/cli/commands/connect/target-note.ts

@@ -1,5 +1,5 @@
 import type { Resolution } from '#profile';
-import { announce } from '../../output.ts';
+import { announce, announceWorkspace } from '../../output.ts';
 
 /**
  * The line `connect` prints before it acts.
@@ -23,6 +23,7 @@ import { announce } from '../../output.ts';
 export function announceConnectTarget(
   runtime: { readonly resolution: Resolution },
   json?: boolean | undefined,
+  granting = true,
 ): void {
   // `emit`'s early return only protects lines printed *at* the emit, and this
   // one has to precede the browser — so it carries its own guard, the one
@@ -30,5 +31,9 @@ export function announceConnectTarget(
   // beside `emit`: a line of prose in front of a JSON document corrupts it.
   if (json === true) return;
 
-  announce(runtime.resolution);
+  // Without `--profile` this connects into the workspace and edits no profile,
+  // so naming the one a runtime happened to resolve would report a subject the
+  // command does not have.
+  if (granting) announce(runtime.resolution);
+  else announceWorkspace(runtime.resolution);
 }

package/src/cli/commands/connect/unknown.ts

@@ -28,7 +28,7 @@ export function unknownProvider(input: {
   const yours = available.filter((c) => c.origin === 'workspace').map((c) => c.manifest.id);
 
   const selection = `--profile ${input.profile} --target ${input.target}`;
-  const directory = `${input.workspaceRoot}/${layout.providers(input.profile)}`;
+  const directory = `${input.workspaceRoot}/${layout.providers()}`;
 
   return new Error(
     `Unknown provider "${input.providerId}".\n` +

package/src/cli/commands/connect/variables.ts

@@ -161,7 +161,8 @@ export async function resolveConnectionAddress(input: {
   readonly runtime: {
     readonly registry: ProviderRegistry;
     readonly credentials: SecretStore;
-    readonly config: { readonly connections: readonly ConnectionRow[] };
+    /** Every account the workspace holds, for the address a sibling already gave (ADR-057). */
+    readonly workspaceConnections: readonly ConnectionRow[];
     connectorFor(providerId: string, connectionId: string): AnyConnector | undefined;
   };
 }): Promise<ResolvedAddress> {
@@ -178,7 +179,7 @@ export async function resolveConnectionAddress(input: {
     // the id is not settled yet, and a second Nextcloud on a *different* host is
     // rarer than reconnecting the one there is. It is offered, not imposed —
     // pressing Enter accepts it and typing replaces it.
-    existing: previousAddress(runtime.config.connections, input.providerId, manifest),
+    existing: previousAddress(runtime.workspaceConnections, input.providerId, manifest),
     interactive: input.interactive,
     supplied: parseSet(input.set),
   });

package/src/cli/commands/connection-list.ts

@@ -0,0 +1,116 @@
+import { RESERVED_PROVIDER_IDS } from '#connectivity';
+import {
+  connectionRefOf,
+  listProfiles,
+  loadProfileConfig,
+  readConnections,
+  resolveTargetWorkspace,
+  resolveWorkspaceRoot,
+} from '#profile';
+import { emit, heading, print, style, table } from '../output.ts';
+import type { GlobalFlags } from '../runtime.ts';
+
+/**
+ * `lanes link connection list` — every account this workspace holds, and which
+ * profiles reach each.
+ *
+ * The listing that had nowhere to live under contract 2, because there was no
+ * such thing as "the workspace's connections": each profile had its own list
+ * and `status` printed one profile's. A connection belongs to the workspace now
+ * (ADR-057), so the question "what have I authorised" has one answer.
+ *
+ * **The profiles column is the useful half.** An account granted to nobody is
+ * connected and unreachable, which looks identical to a working one from
+ * anywhere else — and an account granted to more profiles than the operator
+ * remembers is how a disconnect surprises somebody. Both are visible here and
+ * nowhere else.
+ *
+ * Workspace-scoped, so it takes no `--profile`. Passing one would narrow the
+ * column rather than the rows, which is a different command.
+ */
+
+export interface ConnectionSummary {
+  readonly key: string;
+  readonly provider: string;
+  readonly account: string;
+  readonly label: string | null;
+  /** Whether this is part of the owner layer rather than somebody's account. */
+  readonly builtIn: boolean;
+  /** Every profile in the workspace whose grants name it. */
+  readonly grantedTo: readonly string[];
+}
+
+export async function connectionList(flags: GlobalFlags & { json?: boolean }): Promise<void> {
+  const local = resolveWorkspaceRoot();
+  const root = await resolveTargetWorkspace(local, flags.target ?? 'local');
+
+  const held = (await readConnections(root)).connections;
+
+  // Read once, ahead of the loop. The alternative is a file read per connection
+  // per profile, which on a workspace with fifteen accounts and three profiles
+  // is forty-five reads of five files.
+  const grants = new Map<string, string[]>();
+  for (const name of await listProfiles(root)) {
+    try {
+      const { config } = await loadProfileConfig(root, name);
+      for (const grant of config.grants) {
+        grants.set(grant.connection, [...(grants.get(grant.connection) ?? []), name]);
+      }
+    } catch {
+      // A profile that will not load is `check`'s to report. Dropping it here
+      // makes this listing answer for the ones that do rather than failing
+      // wholesale on one broken file.
+    }
+  }
+
+  const summaries: ConnectionSummary[] = held.map((connection) => {
+    const key = connectionRefOf(connection);
+    return {
+      key,
+      provider: connection.provider,
+      account: connection.account,
+      label: connection.label ?? null,
+      builtIn: RESERVED_PROVIDER_IDS.includes(connection.provider),
+      grantedTo: grants.get(key) ?? [],
+    };
+  });
+
+  return emit(flags.json, { workspace: flags.target ?? 'local', connections: summaries }, () => {
+    print(style.dim(`workspace ${style.bold(flags.target ?? 'local')}  ${root}`));
+
+    const accounts = summaries.filter((one) => !one.builtIn);
+    const builtIns = summaries.filter((one) => one.builtIn);
+
+    if (accounts.length === 0) {
+      print('');
+      print(style.dim('No accounts connected yet. Connect one with: lanes link connect <provider>'));
+    } else {
+      heading(`Accounts (${accounts.length})`);
+      table(accounts.map(row));
+    }
+
+    if (builtIns.length > 0) {
+      heading(`Your own material (${builtIns.length})`);
+      table(builtIns.map(row));
+    }
+
+    print('');
+    print(
+      style.dim(
+        'A connection reaches a profile only where that profile grants it:\n' +
+          '  lanes link grant <provider>.<id> --profile <name>',
+      ),
+    );
+  });
+}
+
+function row(one: ConnectionSummary): string[] {
+  // "granted to nobody" is said rather than left blank, because a blank column
+  // reads as "not loaded yet" and this is a fact about the config.
+  const reach =
+    one.grantedTo.length === 0
+      ? style.dim('no profile grants it')
+      : one.grantedTo.join(', ');
+
+  return [`  ${style.bold(one.key)}`, one.label ?? one.account, reach];
+}