@lanes-sh/link 0.7.2 → 0.9.0

package/src/cli/commands/mcp/onboarding.ts

@@ -0,0 +1,86 @@
+import { print } from '../../output.ts';
+
+/**
+ * `lanes link mcp install-instructions` — the block a client should be told once.
+ *
+ * A registration points a client at this endpoint. It does not tell the *model*
+ * anything, and the model is what decides whether to look here at all. The
+ * common failure is not a client that cannot reach the endpoint; it is one that
+ * can and answers from nothing anyway, because reaching for a tool is a habit
+ * and no habit is installed by adding a server to a config file.
+ *
+ * So this prints a short block for a person to paste into whatever their client
+ * treats as durable instruction — a project file, a custom instruction, a
+ * memory. It says where things are and what to read first, and nothing else:
+ * the full account lives at `lanes://instructions` and is served by the
+ * endpoint, so it can be corrected without anybody pasting anything again.
+ *
+ * **Printed rather than written.** Every client keeps this somewhere different
+ * and several keep it somewhere a person curates by hand. Writing into one of
+ * those is the class of thing ADR-016 puts on the other side of the line from
+ * `mcp add`: delegate where the harness owns a command, write the file only
+ * where it does not, and where neither is true, hand over the text.
+ */
+
+/** What each client calls the place this belongs, so the hint is actionable. */
+const WHERE: Record<string, string> = {
+  claude: 'CLAUDE.md in your project, or ~/.claude/CLAUDE.md for every project',
+  chatgpt: "Settings → Personalization → Custom instructions, under 'anything else'",
+  codex: 'AGENTS.md in your project, or ~/.codex/AGENTS.md',
+  cursor: '.cursor/rules/ in your project',
+};
+
+export interface InstallInstructionsFlags {
+  readonly client?: string | undefined;
+}
+
+export function installInstructions(flags: InstallInstructionsFlags = {}): void {
+  const client = flags.client?.toLowerCase();
+
+  if (client !== undefined && !(client in WHERE)) {
+    throw new Error(
+      `Unknown client "${client}". Known: ${Object.keys(WHERE).join(', ')}.\n` +
+        '  Omit --client for the block on its own.',
+    );
+  }
+
+  if (client !== undefined) {
+    // To stderr, so the block on stdout stays pasteable. Somebody piping this
+    // into a file wants the text and not the advice about where to put it.
+    process.stderr.write(`Paste this into ${WHERE[client]}:\n\n`);
+  }
+
+  print(BLOCK);
+}
+
+/**
+ * The block itself.
+ *
+ * Deliberately short and deliberately not a copy of the endpoint's own
+ * instructions. It exists to establish one habit — look here before answering
+ * from nothing — and to name the document that carries the rest. A longer block
+ * pasted into a project file is one that goes stale in a place nobody will
+ * think to update.
+ *
+ * No vendor names and no account details, for the same reason nothing under
+ * `server/` may carry one: what the owner connected is theirs.
+ */
+const BLOCK = `## Lanes Link
+
+Lanes Link is the route to my accounts, my memory, my notes, my saved procedures
+and my contacts. It is an MCP endpoint, and it is already connected.
+
+- Before saying you do not know something about me or my work, search memory.
+- Before using anyone's address or handle, look them up in entities. It returns
+  every match and never picks one; if there is more than one, ask me.
+- A thing for me to do is a task, not a memory. Tasks have a status.
+- If I have a saved procedure for something, tell me it exists and let me run it
+  rather than improvising your own version.
+- Before telling me something cannot be reached or that an account is missing,
+  ask the setup surface. It reports what exists and gives the exact command for
+  what does not. Run nothing yourself: every change here is mine to make.
+- Read \`lanes://instructions\` before your first call for the full account of
+  how routing, profiles and refusals work.
+
+Every tool takes a profile. A profile is how I keep things apart, so when it is
+ambiguous which one I mean, ask rather than picking the first.`;

package/src/cli/commands/mcp/register.ts

@@ -32,6 +32,17 @@ export interface McpAddOptions extends GlobalFlags {
   readonly force?: boolean | undefined;
   /** Register only; leave the skill and the agent alone. */
   readonly noSkill?: boolean | undefined;
+  /**
+   * Write the endpoint token into the registration, for a machine with no browser.
+   *
+   * The ordinary path registers a bare URL and the client authorises itself
+   * against lanes.sh (ADR-062), which is both safer and less to get wrong. This
+   * is the CI escape hatch, and it is a flag rather than a fallback because the
+   * difference has to be a decision somebody made: a registration that quietly
+   * embedded a credential when a browser was unavailable is one nobody would
+   * notice had done so.
+   */
+  readonly headless?: boolean | undefined;
 }
 
 export async function mcpAdd(target: string | undefined, options: McpAddOptions): Promise<void> {
@@ -71,17 +82,20 @@ export async function mcpAdd(target: string | undefined, options: McpAddOptions)
   const runtime = await openRuntime(options);
 
   try {
+    // Minted either way. The endpoint needs one to serve at all, and `outputs`
+    // prints it; what `--headless` decides is whether it is written into
+    // somebody's agent config.
     const { token } = await ensureProfileToken(runtime.credentials, runtime.config.auth.token_ref);
 
     // The target's own address, not the local one. This built
-    // `http://<host>:<port>/mcp` unconditionally, so `mcp add --target cloud`
+    // `http://<host>:<port>/mcp` unconditionally, so `mcp add --workspace cloud`
     // registered loopback with the agent: a registration that reports success,
     // names the right server, and points at a port with nothing behind it.
     const url = await endpointUrl(runtime.config, runtime.declared);
     const input: AddInput = {
       name,
       url,
-      token,
+      ...(options.headless === true ? { token } : {}),
       tokenEnv,
       scope,
       profile: runtime.resolution.profile,

package/src/cli/commands/mcp.ts

@@ -20,3 +20,4 @@ export { harnessCommands } from './mcp/harnesses.ts';
 export { mcpList } from './mcp/list.ts';
 export { mcpAdd, type McpAddOptions } from './mcp/register.ts';
 export { mcpStdio } from './mcp/stdio.ts';
+export { installInstructions, type InstallInstructionsFlags } from './mcp/onboarding.ts';

package/src/cli/commands/members.ts

@@ -0,0 +1,288 @@
+import { readSession } from '#auth/lanes/session.ts';
+import { recordConfigChange } from '../audit-change.ts';
+import {
+  ConfigError,
+  readRegistry,
+  resolveTargetWorkspace,
+  resolveWorkspaceRoot,
+} from '#profile';
+import { ConfigDocument } from '../config-edit.ts';
+import { describeMember, workspaceMembers } from '#auth/lanes/members.ts';
+import { announce, emit, heading, ok, print, style, table, warn } from '../output.ts';
+import { nextAfterEdit, publishProfileEdit } from '../publish.ts';
+import { resolveProfile, type GlobalFlags } from '../runtime.ts';
+
+/**
+ * `lanes link profile members` — who may consume a profile (ADR-060).
+ *
+ * CLI-only, like everything that authorises future agent behaviour (ADR-007),
+ * and for the sharpest version of that argument: an agent able to edit this
+ * could add itself.
+ *
+ * **This is a selection from the Lanes workspace, not a list beside it.**
+ * Membership is managed on the dashboard — invited, accepted, given a role,
+ * removed — and a workspace bound with `lanes_workspace:` is asked who it holds.
+ * Somebody added there shows up here the moment they accept, and granting them a
+ * profile is a local edit naming a subject the server already vouches for.
+ *
+ * For `local` there is no such list, so the only subject accepted is the
+ * signed-in one — a local workspace delegating to a stranger is a typo, not a
+ * use case.
+ */
+
+export interface MemberRow {
+  readonly subject: string;
+  readonly role: 'owner' | 'member';
+  /** Whether this is the identity running the command. */
+  readonly you: boolean;
+}
+
+export async function membersList(flags: GlobalFlags & { json?: boolean }): Promise<void> {
+  const { resolution, config, target } = await resolveProfile(flags);
+  const session = await readSession();
+
+  const rows: MemberRow[] = config.members.map((member) => ({
+    subject: member.subject,
+    role: member.role,
+    you: member.subject === session?.subject,
+  }));
+
+  // The workspace's own people, so this listing answers both halves of the
+  // question: who may use this profile, and who *could* be given it. Without
+  // the second, adding somebody means going to the dashboard to copy a subject
+  // out of it.
+  const held = await workspaceMembers(await boundWorkspace(target));
+  const granted = new Set(rows.map((row) => row.subject));
+  const available = held.members.filter(
+    (member) => member.subject === null || !granted.has(member.subject),
+  );
+
+  return emit(
+    flags.json,
+    { profile: resolution.profile, members: rows, available: available },
+    () => {
+      announce(resolution);
+
+      if (rows.length === 0) {
+        // Empty is nobody, and saying so matters: the natural reading of a blank
+        // list is "no restriction", which is the opposite of what it means.
+        print(style.dim('No members. Nobody may consume this profile.'));
+        print(style.dim('  Add yourself with: lanes link profile members add --me'));
+      } else {
+        heading(`May consume ${resolution.profile} (${rows.length})`);
+        table(
+          rows.map((row) => [
+            `  ${style.bold(row.subject)}`,
+            row.role,
+            row.you ? style.dim('you') : '',
+          ]),
+        );
+      }
+
+      if (available.length > 0) {
+        heading(`In the workspace, not granted (${available.length})`);
+        table(
+          available.map((member) => [
+            `  ${style.bold(describeMember(member))}`,
+            member.role,
+            member.status === 'pending'
+              ? style.dim('invitation not accepted')
+              : style.dim(member.subject ?? ''),
+          ]),
+        );
+      }
+
+      if (held.unavailable !== null && held.unavailable !== 'this workspace is not bound to a Lanes workspace') {
+        print('');
+        print(style.dim(`Could not list the workspace's members: ${held.unavailable}`));
+      }
+    },
+  );
+}
+
+/** The Lanes workspace this one is bound to, if any. */
+async function boundWorkspace(target: string): Promise<string | undefined> {
+  // **The workspace that declares the target, which is not this machine once it
+  // is deployed.** `lanes_workspace` is a declaration field, and
+  // `recordDeployment` writes the declaration into the bucket while leaving
+  // this machine a pointer carrying only `at`, `primary` and the deploy stamps.
+  // So reading it here found nothing the moment a target was deployed: binding
+  // a workspace stopped taking effect, `members add` refused everyone but the
+  // person at the keyboard, and the remedy it printed — add `lanes_workspace:`
+  // under `workspaces.<target>` — named the pointer entry, which the next
+  // deploy overwrites. A declaration resolves back to this root unchanged.
+  const local = resolveWorkspaceRoot();
+  const registry = await readRegistry(await resolveTargetWorkspace(local, target).catch(() => local));
+  return registry[target]?.lanes_workspace;
+}
+
+export interface MembersFlags extends GlobalFlags {
+  readonly json?: boolean | undefined;
+  /** Add the signed-in subject, rather than one typed out. */
+  readonly me?: boolean | undefined;
+  readonly role?: string | undefined;
+}
+
+export async function membersAdd(
+  subject: string | undefined,
+  flags: MembersFlags,
+): Promise<void> {
+  const { resolution, config, target } = await resolveProfile(flags);
+  const session = await readSession();
+
+  const wanted = flags.me === true ? session?.subject : subject;
+
+  if (wanted === undefined) {
+    throw new ConfigError(
+      flags.me === true
+        ? 'Not signed in, so there is no "me" to add. Run: lanes auth login'
+        : 'Which subject? Run: lanes link profile members add <subject> --profile <name>\n' +
+          '  Or add yourself: lanes link profile members add --me --profile <name>',
+    );
+  }
+
+  const role = flags.role === 'owner' ? 'owner' : 'member';
+
+  if (config.members.some((member) => member.subject === wanted)) {
+    print(style.dim(`${resolution.profile} already lists ${wanted}.`));
+    return;
+  }
+
+  await assertDelegatable(wanted, target, session?.subject);
+
+  const document = await ConfigDocument.open(resolution.workspaceRoot, resolution.profile);
+  document.addTo(['members'], { subject: wanted, role }, { inline: true });
+  await document.save();
+
+  await recordConfigChange(
+    config,
+    resolution.workspaceRoot,
+    target,
+    {
+      capability: 'config.member.add',
+      scope: resolution.profile,
+      arguments: { subject: wanted, role },
+    },
+    (note) => print(warn(note)),
+  );
+
+  const published = nextAfterEdit(await publishProfileEdit({ resolution, config, target }));
+
+  return emit(flags.json, { profile: resolution.profile, subject: wanted, role }, () => {
+    announce(resolution);
+    print(ok(`${wanted} may now consume ${style.bold(resolution.profile)} as ${role}`));
+    print(style.dim('      They reach exactly what this profile grants, and nothing else.'));
+    if (published) print(style.dim(`      ${published}`));
+  });
+}
+
+export async function membersRemove(
+  subject: string | undefined,
+  flags: MembersFlags,
+): Promise<void> {
+  const { resolution, config, target } = await resolveProfile(flags);
+  if (!subject) throw new ConfigError('Which subject? Run: lanes link profile members list');
+
+  const at = config.members.findIndex((member) => member.subject === subject);
+  if (at === -1) {
+    print(style.dim(`${resolution.profile} does not list ${subject}.`));
+    return;
+  }
+
+  const document = await ConfigDocument.open(resolution.workspaceRoot, resolution.profile);
+  document.removeFrom(['members'], at);
+  await document.save();
+
+  await recordConfigChange(
+    config,
+    resolution.workspaceRoot,
+    target,
+    { capability: 'config.member.remove', scope: resolution.profile, arguments: { subject } },
+    (note) => print(warn(note)),
+  );
+
+  const published = nextAfterEdit(await publishProfileEdit({ resolution, config, target }));
+
+  return emit(flags.json, { profile: resolution.profile, subject }, () => {
+    announce(resolution);
+    print(ok(`${subject} may no longer consume ${style.bold(resolution.profile)}`));
+
+    // The half that is not obvious, and is the difference between this and a
+    // session manager. A token already issued keeps working until it expires:
+    // membership is read when one is minted, not on every call (ADR-060).
+    print(
+      style.dim(
+        '      A token they already hold keeps working until it expires.\n' +
+          `      To close that window now: lanes link token rotate --workspace ${target}`,
+      ),
+    );
+    if (published) print(style.dim(`      ${published}`));
+  });
+}
+
+/**
+ * Whether this workspace may delegate to that subject.
+ *
+ * The check exists because the alternative is a profile listing a subject
+ * nobody can produce a token for — which reads exactly like a working
+ * delegation until the person tries to use it.
+ *
+ * Bound to a Lanes workspace, the answer is the workspace's own member list:
+ * somebody added on the dashboard is delegatable here, and nobody else is.
+ * Unbound, there is no list to ask, so the only verifiable subject is the one at
+ * the keyboard.
+ */
+async function assertDelegatable(
+  subject: string,
+  target: string,
+  signedIn: string | undefined,
+): Promise<void> {
+  const bound = await boundWorkspace(target);
+
+  if (bound === undefined) {
+    if (subject === signedIn) return;
+
+    throw new ConfigError(
+      `Workspace "${target}" is not bound to a Lanes workspace, so it can only delegate to you.\n` +
+        '  Add yourself with: lanes link profile members add --me\n' +
+        '  To delegate to somebody else, bind the workspace:\n' +
+        `    lanes_workspace: <id>   # in lanes-link.yaml, under workspaces.${target}\n` +
+        '  Run "lanes auth workspaces" for the ids you belong to.',
+    );
+  }
+
+  const held = await workspaceMembers(bound);
+
+  // Unreachable rather than empty. Refusing on a network failure would make a
+  // local edit depend on our uptime, and the endpoint verifies the subject when
+  // it mints a token regardless — so this warns and proceeds.
+  if (held.unavailable !== null) {
+    print(
+      style.dim(
+        `  Could not check the workspace's members (${held.unavailable}), so this was not verified.`,
+      ),
+    );
+    return;
+  }
+
+  const match = held.members.find((member) => member.subject === subject);
+  if (match !== undefined) return;
+
+  // A pending invitation is the interesting refusal: the person exists, the
+  // operator can see them on the dashboard, and there is still no subject to
+  // write down. Saying "not a member" would send them to add somebody who is
+  // already there.
+  const pending = held.members.filter((member) => member.status === 'pending');
+
+  throw new ConfigError(
+    `${subject} is not a member of the Lanes workspace behind "${target}".\n` +
+      (held.members.length > 0
+        ? `  It holds: ${held.members.map(describeMember).join(', ')}\n`
+        : '  It holds nobody yet.\n') +
+      (pending.length > 0
+        ? `  ${pending.map(describeMember).join(', ')} ${pending.length === 1 ? 'has' : 'have'} not ` +
+          'accepted the invitation yet, so there is no subject for them to be granted.\n'
+        : '') +
+      '  Invite them on the dashboard first: https://lanes.sh/dashboard/settings/members',
+  );
+}

package/src/cli/commands/operate/attach.ts

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { ownerPrincipal } from '#auth';
 import { announce, print, style } from '../../output.ts';
-import { openRuntime, type GlobalFlags } from '../../runtime.ts';
+import { grantedConnections, openRuntime, type GlobalFlags } from '../../runtime.ts';
 
 /**
  * `lanes link attach <file> --connection <provider>.<account>`
@@ -44,11 +44,11 @@ export async function attachFile(
 
     // Checked against config rather than trusted, so a typo names the mistake
     // instead of staging into a namespace nothing will ever read.
-    const known = runtime.config.connections.some(
+    const known = grantedConnections(runtime).some(
       (connection) => connection.provider === providerId && connection.id === connectionId,
     );
     if (!known) {
-      const have = runtime.config.connections.map((c) => `${c.provider}.${c.id}`);
+      const have = grantedConnections(runtime).map((c) => `${c.provider}.${c.id}`);
       throw new Error(
         `No connection "${flags.connection}" in this profile. Configured: ${have.join(', ') || 'none'}.`,
       );

package/src/cli/commands/operate/audit.ts

@@ -1,5 +1,5 @@
-import { announce, print, style, table } from '../../output.ts';
-import { openRuntime, type GlobalFlags } from '../../runtime.ts';
+import { announceWorkspace, print, style, table } from '../../output.ts';
+import { openWorkspaceRuntime, type GlobalFlags } from '../../runtime.ts';
 
 /** `lanes link audit tail` — the log the dispatcher writes, rendered for a terminal. */
 
@@ -15,11 +15,11 @@ export async function auditTail(
   }
   const markdown = flags.format === 'md';
 
-  const runtime = await openRuntime(flags);
+  const runtime = await openWorkspaceRuntime(flags);
   try {
     // The banner is chrome around a table; in Markdown it is a stray line in
     // the middle of a document someone is pasting somewhere.
-    if (!markdown) announce(runtime.resolution);
+    if (!markdown) announceWorkspace(runtime.resolution);
 
     const events = await runtime.audit.tail({
       limit: flags.limit ?? 25,
@@ -35,7 +35,11 @@ export async function auditTail(
       // The log lives in the database; this is a rendering of it, not a second
       // copy of it. See ADR-013 — storage format and display format are not the
       // same decision.
-      print(`# Audit — ${runtime.resolution.profile}\n`);
+      // The workspace, not the profile. Contract 3 gave the workspace one
+      // chain covering every profile in it, and a heading naming whichever
+      // profile happened to open the store described a log that does not
+      // exist. Each row carries its own profile.
+      print(`# Audit — ${runtime.resolution.target}\n`);
       print('| Time | Result | Capability | Connection | Duration | Arguments |');
       print('|---|---|---|---|---|---|');
       for (const event of events) {
@@ -81,9 +85,9 @@ export async function auditTail(
  * can see how much was looked at.
  */
 export async function auditVerify(flags: GlobalFlags): Promise<void> {
-  const runtime = await openRuntime(flags);
+  const runtime = await openWorkspaceRuntime(flags);
   try {
-    announce(runtime.resolution);
+    announceWorkspace(runtime.resolution);
     const report = await runtime.audit.verify();
 
     const scope = `${report.events} event${report.events === 1 ? '' : 's'} across ${report.runs} run${report.runs === 1 ? '' : 's'}`;

package/src/cli/commands/operate/auth.ts

@@ -1,8 +1,15 @@
+import type { ConnectionConfig } from '#profile';
 import { credentialResolver, ReauthRequired } from '#connectivity/auth/index.ts';
 import type { ResolvedCredential } from '#connectivity/auth/credential.ts';
 import { credentialRefFor } from '#registry';
-import { announce, emit, fail, ok, print, warn } from '../../output.ts';
-import { openRuntime, type GlobalFlags, type Runtime } from '../../runtime.ts';
+import { announceWorkspace, emit, fail, ok, print, warn } from '../../output.ts';
+import { readConnections } from '#profile';
+import {
+  grantedConnections,
+  openWorkspaceRuntime,
+  type GlobalFlags,
+  type Runtime,
+} from '../../runtime.ts';
 
 /**
  * Whether each connection could still authenticate, asked rather than guessed.
@@ -146,13 +153,13 @@ export interface AuthFlags extends GlobalFlags {
  */
 export async function probeConnections(
   runtime: Runtime,
-  connections: readonly Runtime['config']['connections'][number][],
+  connections: readonly ConnectionConfig[],
   forSelection: (command: string) => string,
 ): Promise<ConnectionAuth[]> {
   const resolve = credentialResolver(runtime.registry, runtime.credentials);
 
   const probe = async (
-    connection: Runtime['config']['connections'][number],
+    connection: ConnectionConfig,
   ): Promise<ConnectionAuth> => {
     const key = `${connection.provider}.${connection.id}`;
     const manifest = runtime.manifestFor(connection.provider);
@@ -245,20 +252,30 @@ export async function probeConnections(
 }
 
 export async function auth(flags: AuthFlags): Promise<void> {
-  const runtime = await openRuntime(flags);
+  const runtime = await openWorkspaceRuntime(flags);
 
   try {
     const { profile, target } = runtime.resolution;
-    const forSelection = (command: string) => `${command} --profile ${profile} --target ${target}`;
+    const forSelection = (command: string) => `${command} --workspace ${target}`;
+
+    // Every connection the workspace holds, not the ones one profile grants.
+    // Whether an account can still authenticate is a fact about the account
+    // (ADR-057), and scoping it to a profile's grants meant an account that had
+    // just been connected could not be checked until somebody granted it —
+    // which is exactly the moment you want to check.
+    //
+    // `--profile` narrows to what that profile can reach, because "can the
+    // things this profile uses still sign in" is also a real question.
+    const all = flags.profile === undefined
+      ? (await readConnections(runtime.resolution.workspaceRoot)).connections
+      : grantedConnections(runtime);
 
     const wanted = flags.connection;
-    const connections = wanted
-      ? runtime.config.connections.filter((c) => `${c.provider}.${c.id}` === wanted)
-      : runtime.config.connections;
+    const connections = wanted ? all.filter((c) => `${c.provider}.${c.id}` === wanted) : all;
 
     if (wanted && connections.length === 0) {
       throw new Error(
-        `No connection "${wanted}" in profile ${profile}. Run: ${forSelection('lanes link status')}`,
+        `No connection "${wanted}" in workspace ${target}. Run: ${forSelection('lanes link connection list')}`,
       );
     }
 
@@ -270,7 +287,7 @@ export async function auth(flags: AuthFlags): Promise<void> {
     // why it cannot read `doctor`. A connection needing a person is the answer
     // this command was asked for, not a failure to produce one.
     return emit(flags.json, { profile, target, ok: needsSomeone.length === 0, connections: results }, () => {
-      announce(runtime.resolution);
+      announceWorkspace(runtime.resolution);
 
       for (const result of results) {
         const line = `${result.key} — ${describe(result.verdict)}`;

package/src/cli/commands/operate/findings.ts

@@ -1,3 +1,4 @@
+import { grantedConnections } from '../../runtime.ts';
 import { ownerPrincipal } from '#auth';
 import type { DiscoveredCapability } from '#connectivity';
 import { allowedConnections } from '#policy';
@@ -49,7 +50,7 @@ export async function reportCapabilityDrift(
   const principal = ownerPrincipal(runtime.config.instance.profile).id;
 
   for (const entry of runtime.registry.list()) {
-    const connection = runtime.config.connections.find((c) => c.provider === entry.manifest.id);
+    const connection = grantedConnections(runtime).find((c) => c.provider === entry.manifest.id);
     if (!connection) continue;
 
     const connector = runtime.connectorFor(entry.manifest.id, connection.id);