@lanes-sh/link 0.2.2 → 0.3.1

package/src/cli/main.ts

@@ -5,6 +5,7 @@ import {
   auditVerify,
   check,
   configShow,
+  dashboard,
   doctor,
   outputs,
   plan,
@@ -18,28 +19,18 @@ import {
 } from './commands/operate.ts';
 import { profileAdd, profileDefault, profileList } from './commands/profile.ts';
 import { removeProfile as profileRemove } from './commands/profile/remove.ts';
+import { syncTargets } from './commands/sync.ts';
 import { targetList, targetShow, targetUse } from './commands/target.ts';
+import { identityAdd, identityList, identityRemove } from './commands/identity.ts';
 import { setupPlan } from './commands/setup.ts';
 import { mcpAdd, mcpList, mcpStdio, skillDocument } from './commands/mcp.ts';
 import { deploy } from '#deployments/deploy.ts';
 import { secretsList, secretsPush, secretsSet } from './commands/secrets.ts';
-import {
-  memoryForget,
-  memoryGet,
-  memoryList,
-  memoryWrite,
-  skillsAdd,
-  skillsList,
-  skillsRemove,
-  skillsShow,
-  vaultGet,
-  vaultKeyGenerate,
-  vaultList,
-  vaultRemove,
-  vaultSet,
-} from './commands/owner.ts';
+import { knowledgeShow, knowledgeUse } from './commands/knowledge.ts';
+import { dispatchOwner } from './dispatch-owner.ts';
 import { update } from './commands/update.ts';
-import { globalFlags, ownerFlags, parseArgv, text } from './argv.ts';
+import { all, globalFlags, knowledgeFlags, ownerFlags, parseArgv, text } from './argv.ts';
+import { assertKnownFlags, requireSelection } from './selection.ts';
 import { PROGRAM, USAGE } from './usage.ts';
 import { version } from './version.ts';
 import { print } from './output.ts';
@@ -74,6 +65,14 @@ export async function run(argv: readonly string[]): Promise<void> {
     return;
   }
 
+  // Before the switch, so no command can be reached having been handed a flag it
+  // does not read or missing one it needs. One call site rather than a check per
+  // case: the reported bug was a single command building its own options literal
+  // and dropping `--target` into it, which is exactly what a per-case check
+  // leaves room for.
+  assertKnownFlags(first, second, flags);
+  await requireSelection(first, second, flags);
+
   switch (first) {
     case 'connect':
       if (!second) throw new Error(`Usage: ${PROGRAM} connect <provider>`);
@@ -85,6 +84,7 @@ export async function run(argv: readonly string[]): Promise<void> {
         nonInteractive: flags['non-interactive'] === true,
         acceptBroadScopes: flags['accept-broad-scopes'] === true,
         ownClient: flags['own-client'] === true,
+        auth: text(flags, 'auth'),
         json,
       });
 
@@ -97,8 +97,17 @@ export async function run(argv: readonly string[]): Promise<void> {
     case 'profile':
       switch (second) {
         case 'add':
-          if (!rest[0]) throw new Error(`Usage: ${PROGRAM} profile add <name> [--default]`);
-          return profileAdd(rest[0], { default: flags['default'] === true, json });
+          if (!rest[0]) {
+            throw new Error(`Usage: ${PROGRAM} profile add <name> --target <name> [--target <name>]`);
+          }
+          return profileAdd(rest[0], {
+            // Read from argv rather than from `flags`, because this is the one
+            // place a flag is a list: a profile declares every target it can run
+            // on, and the parser keeps only the last value of a repeated flag.
+            targets: all(argv, 'target'),
+            nonInteractive: flags['non-interactive'] === true,
+            json,
+          });
         case 'list':
         case undefined:
           return profileList({ json });
@@ -128,13 +137,35 @@ export async function run(argv: readonly string[]): Promise<void> {
           return targetList({ ...global, json, urls: flags['urls'] === true });
         case 'use':
           if (!rest[0]) throw new Error(`Usage: ${PROGRAM} target use <name>`);
-          return targetUse(rest[0], global);
+          return targetUse(rest[0]);
         case 'show':
           return targetShow(rest[0], { ...global, json });
         default:
           throw new Error(`Unknown: ${PROGRAM} target ${second}`);
       }
 
+    case 'identity': {
+      // Both subcommands take the same two positionals, so the usage line is
+      // built once rather than written twice with one of them going stale.
+      const [kind, value] = rest;
+      const usage = (form: string): string =>
+        `Usage: ${PROGRAM} identity ${form}\n  e.g. ${PROGRAM} identity add name "Your Name" --note "for open-source work"`;
+
+      switch (second) {
+        case 'add':
+          if (!kind || !value) throw new Error(usage('add <kind> <value> [--note text]'));
+          return identityAdd(kind, value, { ...global, note: text(flags, 'note'), json });
+        case 'list':
+        case undefined:
+          return identityList({ ...global, json });
+        case 'remove':
+          if (!kind || !value) throw new Error(usage('remove <kind> <value>'));
+          return identityRemove(kind, value, { ...global, json });
+        default:
+          throw new Error(`Unknown: ${PROGRAM} identity ${second}`);
+      }
+    }
+
     case 'policy':
       switch (second) {
         case 'list':
@@ -191,54 +222,26 @@ export async function run(argv: readonly string[]): Promise<void> {
       if (second !== 'show' && second !== undefined) throw new Error(`Unknown: ${PROGRAM} config ${second}`);
       return configShow(global);
 
+    // memory, skills and vault — one subject, dispatched together.
+    // `vault key generate` is synchronous, so this returns the result rather
+    // than testing it for truthiness.
     case 'memory':
-      switch (second) {
-        case 'list':
-        case undefined:
-          return memoryList(owner);
-        case 'get':
-          return memoryGet(rest[0], owner);
-        case 'write':
-          return memoryWrite(rest[0], owner);
-        case 'forget':
-          return memoryForget(rest[0], owner);
-        default:
-          throw new Error(`Unknown: ${PROGRAM} memory ${second}`);
-      }
-
     case 'skills':
-      switch (second) {
-        case 'list':
-        case undefined:
-          return skillsList(owner);
-        case 'show':
-          return skillsShow(rest[0], owner);
-        case 'add':
-          return skillsAdd(rest[0], owner);
-        case 'remove':
-          return skillsRemove(rest[0], owner);
-        default:
-          throw new Error(`Unknown: ${PROGRAM} skills ${second}`);
-      }
-
     case 'vault':
+      return dispatchOwner(first, second, rest, owner, PROGRAM);
+
+    // Beside `memory` and `skills` because it is the question they raise next:
+    // those two say what is stored, and this says where it is kept. Not one of
+    // them, though — it takes its own flags rather than the owner set.
+    case 'knowledge':
       switch (second) {
-        case 'list':
+        case 'show':
         case undefined:
-          return vaultList(owner);
-        case 'get':
-          return vaultGet(rest[0], owner);
-        case 'set':
-          return vaultSet(rest[0], owner);
-        case 'remove':
-          return vaultRemove(rest[0], owner);
-        case 'key':
-          if (rest[0] !== 'generate') {
-            throw new Error(`Usage: ${PROGRAM} vault key generate`);
-          }
-          return vaultKeyGenerate(owner);
+          return knowledgeShow(knowledgeFlags(flags));
+        case 'use':
+          return knowledgeUse(rest[0], knowledgeFlags(flags));
         default:
-          throw new Error(`Unknown: ${PROGRAM} vault ${second}`);
+          throw new Error(`Unknown: ${PROGRAM} knowledge ${second}`);
       }
 
     case 'check':
@@ -252,6 +255,13 @@ export async function run(argv: readonly string[]): Promise<void> {
     case 'outputs':
       return outputs({ ...global, show, json });
 
+    // Beside `outputs` for the same reason `tools` is: it answers the next
+    // question a person has rather than the next one an agent has. `outputs`
+    // hands a harness a URL and a token; this opens the one page a person can
+    // read, and only a local endpoint serves it.
+    case 'dashboard':
+      return dashboard({ ...global, print: flags['print'] === true });
+
     // Beside `outputs` because it answers the next question. `outputs` says
     // where the endpoint is; this says what it would hand a client that asked
     // right now — which is the only way to tell a stale client from a wrong
@@ -301,6 +311,10 @@ export async function run(argv: readonly string[]): Promise<void> {
     case 'deploy':
       return deploy({
         ...global,
+        // Repeatable, like `profile add --target`: a deploy sends every profile
+        // that declares the target, and this narrows that set rather than
+        // selecting from it. The first named is the primary (ADR-043).
+        profiles: all(argv, 'profile'),
         dryRun: flags['dry-run'] === true,
         // `--iam` was a boolean that meant "add the platform's own check on top".
         // It is now one of two values of a declared field, because the opposite
@@ -313,6 +327,21 @@ export async function run(argv: readonly string[]): Promise<void> {
         nonInteractive: flags['non-interactive'] === true,
       });
 
+    case 'sync':
+      switch (second) {
+        case undefined:
+        case 'targets':
+          return syncTargets({
+            ...global,
+            dryRun: flags['dry-run'] === true,
+            from: text(flags, 'from'),
+            discover: flags['discover'] === true,
+            prefer: text(flags, 'prefer'),
+          });
+        default:
+          throw new Error(`Unknown: ${PROGRAM} sync ${second}`);
+      }
+
     case 'secrets':
       switch (second) {
         case 'push':

package/src/cli/nearest.ts

@@ -0,0 +1,45 @@
+/**
+ * "Did you mean --profile?" — one edit away, and no further.
+ *
+ * Pulled out of `selection.ts`, which is the table of what each command needs
+ * and the checks that enforce it. Guessing at a misspelling is neither: it is
+ * string distance, it has no idea what a flag is, and the reason it lives
+ * beside that file rather than inside it is that the file kept growing every
+ * time a command was added and this never did.
+ */
+
+/**
+ * The closest accepted flag, when there is an obviously close one.
+ *
+ * One edit away, or one transposition — enough for `--porfile` and `--taget`,
+ * and short of guessing at something the operator did not mean. A wrong guess
+ * here costs more than no guess: it sends them to a flag that is not the answer.
+ */
+export function nearest(given: string, allowed: ReadonlySet<string>): string | undefined {
+  for (const candidate of allowed) {
+    if (Math.abs(candidate.length - given.length) > 1) continue;
+    if (distance(given, candidate) <= 1) return candidate;
+    if (sorted(given) === sorted(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+const sorted = (text: string): string => [...text].sort().join('');
+
+function distance(a: string, b: string): number {
+  let row = Array.from({ length: b.length + 1 }, (_, index) => index);
+
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i];
+    for (let j = 1; j <= b.length; j++) {
+      next[j] = Math.min(
+        row[j]! + 1,
+        next[j - 1]! + 1,
+        row[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    row = next;
+  }
+
+  return row[b.length]!;
+}

package/src/cli/oauth-callback.ts

@@ -0,0 +1,187 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { completionPage } from './callback-page.ts';
+import { OAuthError } from './oauth-error.ts';
+
+/**
+ * The loopback listener both OAuth paths come back to.
+ *
+ * Two callers want the same door and want it differently. `runOAuthFlow` drives
+ * the whole protocol and reads the code itself; `captureOAuthCallback` hands the
+ * protocol to the MCP SDK and supplies only somewhere for the browser to land.
+ * What they share is everything about the listener — that it binds loopback,
+ * serves exactly one callback, compares `state` in constant time, leaves a page
+ * a person can read, and drains before it closes — and holding that in one file
+ * is what stops the two drifting into disagreeing about it.
+ *
+ * Split out of `oauth.ts` when that file passed the size budget, along the seam
+ * the budget exists to find: the flow, and the door it knocks on.
+ */
+
+const base64url = (input: Buffer): string => input.toString('base64url');
+
+/** Compare the returned state in constant time — it is a CSRF defence. */
+export function stateMatches(expected: string, received: string): boolean {
+  const a = createHash('sha256').update(expected).digest();
+  const b = createHash('sha256').update(received).digest();
+  return timingSafeEqual(a, b);
+}
+
+/**
+ * What the browser is left looking at, in the two shapes it comes in.
+ *
+ * The label is what the caller knows and this file cannot: which provider the
+ * grant was for. Given one, the page names it under "Connected" the way the
+ * invite page names the workspace; without one it says only that the flow
+ * finished, which is what every path said before.
+ */
+export const connectedPage = (label?: string): Response =>
+  completionPage({
+    ...(label ? { label: 'Connected', heading: label } : { heading: 'Connected' }),
+    detail: 'You can close this tab and return to the terminal.',
+    ok: true,
+  });
+
+export const failedPage = (detail: string): Response =>
+  completionPage({ heading: 'Authorization failed', detail, ok: false });
+
+/**
+ * Close the listener without cutting off the response in flight.
+ *
+ * Forcing the socket shut the instant the code is read leaves the operator
+ * looking at a connection error on a flow that in fact succeeded. So: stop
+ * gracefully, wait for the in-flight callback to drain, and force only if
+ * graceful genuinely did not finish — a keep-alive connection must not be able
+ * to hold the CLI open forever either.
+ */
+export async function shutdown(server: { stop(force?: boolean): Promise<void> }): Promise<void> {
+  let drained = false;
+  const graceful = server.stop().then(() => {
+    drained = true;
+  });
+
+  await withTimeout(graceful, 2_000).catch(() => {});
+  if (!drained) await server.stop(true);
+}
+
+/**
+ * Race a promise against a deadline, and **clear the timer either way**.
+ *
+ * A bare `Promise.race` with `setTimeout` leaks: when the real promise wins,
+ * the timer is still pending, and a pending timer keeps the event loop alive
+ * for its full duration. With a five-minute OAuth deadline that turns a
+ * finished `connect` into a terminal that prints "Next: lanes link start" and
+ * then sits there for five minutes — which is exactly what it did.
+ *
+ * Rejects with `OAuthError(message)` if given one, otherwise resolves to
+ * undefined at the deadline, which is what the shutdown path wants.
+ */
+export async function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<T>((resolve, reject) => {
+        timer = setTimeout(
+          () => (message ? reject(new OAuthError(message)) : resolve(undefined as T)),
+          ms,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * Capture exactly one OAuth callback on loopback.
+ *
+ * Split out from `runOAuthFlow` so the SDK can drive the protocol — discovery,
+ * registration, PKCE, exchange — while we supply only the redirect target. The
+ * listener exists for the duration of one consent and no longer.
+ */
+export interface CallbackCapture {
+  readonly redirectUri: string;
+  /**
+   * The `state` this listener will accept, for the provider to put on the
+   * authorization URL. The SDK asks its provider for one and sends whatever it
+   * gets; nothing generates it for us.
+   */
+  readonly state: string;
+  wait(timeoutMs?: number): Promise<{ code: string; iss?: string }>;
+  close(): Promise<void>;
+}
+
+export function captureOAuthCallback(options: { label?: string } = {}): CallbackCapture {
+  const state = base64url(randomBytes(24));
+  let resolveCode: (value: { code: string; iss?: string }) => void;
+  let rejectCode: (error: Error) => void;
+
+  const received = new Promise<{ code: string; iss?: string }>((resolve, reject) => {
+    resolveCode = resolve;
+    rejectCode = reject;
+  });
+
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    fetch(request) {
+      const url = new URL(request.url);
+      if (url.pathname !== '/callback') return new Response('Not found', { status: 404 });
+
+      const error = url.searchParams.get('error');
+      if (error) {
+        rejectCode(
+          new OAuthError(
+            error === 'access_denied'
+              ? 'Authorization was declined in the browser.'
+              : `Authorization failed: ${error}`,
+          ),
+        );
+        return failedPage('You can close this tab.');
+      }
+
+      const code = url.searchParams.get('code');
+      if (!code) {
+        rejectCode(new OAuthError('The callback carried no authorization code.'));
+        return failedPage('No code returned.');
+      }
+
+      // Checked here because nothing else checks it. The SDK's own docs say it
+      // does not validate `state`, and it only sends one if the provider hands
+      // it over — so this listener mints the value, `CredentialOAuthProvider`
+      // returns it from `state()`, and the two are compared on the way back.
+      //
+      // Without it this resolves on the first `/callback?code=` to reach the
+      // port, whoever sent it: any local process, or a page the operator has
+      // open, can sweep loopback during the five-minute window. PKCE usually
+      // turns that into a failed exchange, but a manifest is free to name an
+      // authorization server that does not enforce it, and there the code
+      // would be redeemed and the connection bound to someone else's account.
+      const returnedState = url.searchParams.get('state');
+      if (!returnedState || !stateMatches(state, returnedState)) {
+        rejectCode(new OAuthError('State mismatch — ignoring an unexpected callback.'));
+        return failedPage('Unexpected callback.');
+      }
+
+      const iss = url.searchParams.get('iss');
+      resolveCode({ code, ...(iss ? { iss } : {}) });
+      return connectedPage(options.label);
+    },
+  });
+
+  return {
+    redirectUri: `http://127.0.0.1:${server.port}/callback`,
+    state,
+
+    async wait(timeoutMs = 5 * 60_000) {
+      return withTimeout(
+        received,
+        timeoutMs,
+        `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for the browser.`,
+      );
+    },
+
+    close: () => shutdown(server),
+  };
+}

package/src/cli/oauth-exchange.ts

@@ -13,9 +13,18 @@ import { OAuthError } from './oauth-error.ts';
  */
 
 export interface OAuthTokens {
-  readonly refreshToken: string;
+  /** Absent where the vendor issues a long-lived token and never renews it. */
+  readonly refreshToken?: string;
   readonly accessToken: string;
-  readonly expiresIn: number;
+  /**
+   * Absent where the vendor states no lifetime.
+   *
+   * Not defaulted to an hour: with no refresh token there is nothing to renew
+   * with, so a made-up expiry would have `doctor` reporting a healthy
+   * connection as stale forever and would tell the operator to re-run a command
+   * that fixes nothing.
+   */
+  readonly expiresIn?: number;
   readonly scope: string;
   /**
    * An identity assertion, present when `openid` was granted.
@@ -38,11 +47,37 @@ export interface ExchangeInput {
 
 export type ExchangeCode = (input: ExchangeInput) => Promise<OAuthTokens>;
 
+/**
+ * What a response without a refresh token means for this vendor.
+ *
+ * The two readings are opposite and neither is guessable from the response.
+ * Google omitting one means the account was already authorised and the
+ * connection will die in an hour — worth stopping for. Slack omitting one is
+ * the ordinary success: a user token is long-lived unless token rotation is
+ * switched on, so demanding one would refuse every connection that worked.
+ */
+export interface RefreshTokenPolicy {
+  readonly required: boolean;
+  /** Named in the refusal, so it is not always the vendor who first needed it. */
+  readonly vendor: string;
+  /** Where the operator withdraws the existing grant, when the manifest says. */
+  readonly revokeUrl?: string | undefined;
+}
+
 /** Straight to the vendor, signed with a client this machine holds. */
 export function directExchange(options: {
   readonly tokenUrl: string;
   readonly clientId: string;
-  readonly clientSecret: string;
+  /**
+   * Absent for a public client, where PKCE is the whole of the protection.
+   *
+   * A client id shipped in a public repository has no secret to go with it, and
+   * inventing an empty one would be sent as `client_secret=` — which some
+   * authorization servers read as a malformed confidential client rather than
+   * as a public one, and refuse for a reason that names neither.
+   */
+  readonly clientSecret?: string | undefined;
+  readonly refreshToken: RefreshTokenPolicy;
   readonly fetch?: typeof globalThis.fetch | undefined;
 }): ExchangeCode {
   return async (input) => {
@@ -56,7 +91,7 @@ export function directExchange(options: {
         code: input.code,
         redirect_uri: input.redirectUri,
         client_id: options.clientId,
-        client_secret: options.clientSecret,
+        ...(options.clientSecret ? { client_secret: options.clientSecret } : {}),
         code_verifier: input.codeVerifier,
       }),
     });
@@ -71,19 +106,23 @@ export function directExchange(options: {
       error_description?: string;
     };
 
+    // Not every vendor signals failure with a status. Slack answers a refused
+    // exchange with HTTP 200 and `{ok: false, error: ...}`, so the absent token
+    // is what has to be trusted here rather than the code.
     if (!response.ok || !body.access_token) {
       throw new OAuthError(
         `Token exchange failed: ${body.error ?? response.status} ${body.error_description ?? ''}`.trim(),
       );
     }
 
-    return settle(body, input.scopes);
+    return settle(body, input.scopes, options.refreshToken);
   };
 }
 
 /** Through a broker, which holds the secret this machine does not have. */
 export function brokerExchangeVia(options: {
   readonly url: string;
+  readonly refreshToken: RefreshTokenPolicy;
   readonly fetch?: typeof globalThis.fetch | undefined;
 }): ExchangeCode {
   return async (input) => {
@@ -110,7 +149,7 @@ export function brokerExchangeVia(options: {
       throw new OAuthError('The token exchange returned no access token.');
     }
 
-    return settle(tokens, input.scopes);
+    return settle(tokens, input.scopes, options.refreshToken);
   };
 }
 
@@ -123,23 +162,26 @@ function settle(
     scope?: string | undefined;
   },
   scopes: readonly string[],
+  refreshToken: RefreshTokenPolicy,
 ): OAuthTokens {
-  if (!body.refresh_token) {
+  if (!body.refresh_token && refreshToken.required) {
     // Without one, the connection works until the access token expires and then
-    // quietly stops. Better to fail now with the actual cause. Google is named
-    // because Google is who reaches this path: every provider that redeems a
-    // code here is a Google REST one, and the others hand the exchange to the
-    // MCP SDK. Naming the page beats describing it.
+    // quietly stops. Better to fail now with the actual cause. The vendor is
+    // named rather than assumed: this used to say "Google" on the grounds that
+    // Google was the only provider redeeming a code here, and it is not any
+    // more.
     throw new OAuthError(
-      'Google returned no refresh token. This usually means the account was already authorised ' +
-        'for this app; revoke it at https://myaccount.google.com/permissions and try again.',
+      `${refreshToken.vendor} returned no refresh token. This usually means the account was ` +
+        'already authorised for this app; revoke it' +
+        (refreshToken.revokeUrl ? ` at ${refreshToken.revokeUrl}` : '') +
+        ' and try again.',
     );
   }
 
   return {
-    refreshToken: body.refresh_token,
+    ...(body.refresh_token ? { refreshToken: body.refresh_token } : {}),
     accessToken: body.access_token!,
-    expiresIn: body.expires_in ?? 3600,
+    ...(body.expires_in !== undefined ? { expiresIn: body.expires_in } : {}),
     scope: body.scope ?? scopes.join(' '),
     ...(body.id_token ? { idToken: body.id_token } : {}),
   };