@lanes-sh/link 0.2.2 → 0.3.0

package/src/cli/dashboard-page.ts

@@ -0,0 +1,284 @@
+import { PROVIDER_MANIFESTS } from '#providers/index.ts';
+import { planAll, type ProviderPlan } from '#providers/setup/plan.ts';
+import { PROVIDER_MARKS } from './provider-marks.ts';
+import { escapeHtml } from './brand.ts';
+import { shell } from './dashboard-shell.ts';
+
+/**
+ * The dashboard — one page answering what `status`, `setup plan` and
+ * `target list` answer between them.
+ *
+ * It renders and it does not act. Every state-changing thing on it is a command
+ * to paste, for two reasons that are not the same. Connecting is ADR-005: the
+ * consent belongs to whoever owns the browser, and the loopback listener that
+ * receives the code is the CLI's. Everything else is ADR-007: config is written
+ * from the control plane, and a page served by the endpoint is not it.
+ *
+ * So this is a reader, and the honest shape of a reader is a page that tells you
+ * the line to run. What it saves is not typing — it is knowing which line.
+ *
+ * The design is `callback-page.ts`'s, because that is the product's page and
+ * this is the same product: nothing painted (`color-scheme: light dark` over a
+ * transparent background, correct in either mode with no theme switch), Lora on
+ * the heading, and colour reserved for status rather than spent on emphasis.
+ * What differs is the width — a card centred at 460px is right for one sentence
+ * and wrong for four sections.
+ */
+
+export interface DashboardConnection {
+  /** `provider.id`, the key everything else addresses this by. */
+  readonly key: string;
+  readonly provider: string;
+  readonly account: string;
+  /** `active`, `unauthorized`, `disabled`, or `not reconciled`. */
+  readonly state: string;
+}
+
+export interface DashboardView {
+  /** The profile being rendered, which `?profile=` may have chosen. */
+  readonly profile: string;
+  /** Every profile this endpoint serves, for the switcher. */
+  readonly profiles: readonly string[];
+  /** The target whose adapters are open. */
+  readonly target: string;
+  /** Every target the profile declares, live or not. */
+  readonly targets: readonly string[];
+  readonly connections: readonly DashboardConnection[];
+  /** `oauth_apps` keys, so a profile with its own client is described as having one. */
+  readonly ownClients: readonly string[];
+}
+
+/**
+ * Every command this page renders, built in one place.
+ *
+ * `--profile` and `--target` on all of them, unconditionally. The shell a line
+ * is pasted into resolves both for itself — from `LANES_LINK_PROFILE` and
+ * `LANES_LINK_TARGET`, or from the workspace default — and a page that shows
+ * you one profile while handing you a command that silently acts on another is
+ * worse than one that shows nothing. It is also the rule `resolveSelection`
+ * already follows by refusing to guess.
+ */
+function command(view: DashboardView, rest: string): string {
+  return `lanes link ${rest} --profile ${view.profile} --target ${view.target}`;
+}
+
+/**
+ * A command, shown in full.
+ *
+ * Kept for the two places where the command *is* the label — the sign-in page
+ * and the footer — because there is no provider name to carry it. Everywhere
+ * else the line is on the button, not on the page; see `copyButton`.
+ */
+function commandLine(line: string): string {
+  const text = escapeHtml(line);
+  return (
+    `<div class="cmd"><code>${text}</code>` +
+    `<button class="btn copy" type="button" data-copy="${text}" aria-label="Copy command">copy</button></div>`
+  );
+}
+
+/**
+ * The command, on the button rather than beside it.
+ *
+ * What this trades away is worth naming: the line is no longer selectable by
+ * hand, so a browser with no clipboard API leaves no way to get it. That is
+ * narrower than it sounds — `navigator.clipboard` needs a secure context, and
+ * `http://127.0.0.1` is one by definition, which is the only address this page
+ * is ever served on. The `title` carries the text for anyone who wants to read
+ * before pasting, and `lanes link setup plan` prints the same lines.
+ */
+function copyButton(line: string, label: string): string {
+  const text = escapeHtml(line);
+  return (
+    `<button class="btn copy" type="button" data-copy="${text}" title="${text}" ` +
+    `aria-label="Copy the command that connects ${escapeHtml(label)}">copy</button>`
+  );
+}
+
+/**
+ * The provider's mark, or letters standing in for one.
+ *
+ * `aria-hidden` on both: every caller puts the name beside it, and a screen
+ * reader announcing "GitHub, GitHub" is worse than one announcing it once.
+ *
+ * The fallback takes the first letter of the family and two of the member,
+ * because the plain two collapse a catalogue holding four `icloud_*` entries
+ * and two `*_mcp` ones into a handful of identical marks — `ICA` and `ICO`
+ * rather than `IC` twice.
+ */
+function mark(id: string): string {
+  const path = PROVIDER_MARKS[id];
+  if (path) {
+    return (
+      '<svg class="glyph" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">' +
+      `<path d="${path}"/></svg>`
+    );
+  }
+
+  const [family, member] = id.split('_');
+  const letters = member ? `${family![0]}${member.slice(0, 2)}` : id.slice(0, 2);
+  return `<span class="glyph letters" aria-hidden="true">${escapeHtml(letters.toUpperCase())}</span>`;
+}
+
+/**
+ * The state, as one of the design system's badge variants.
+ *
+ * "Gold for positive, neutral tokens otherwise" — so `active` is the only gold
+ * one, and `unauthorized` is *neutral* rather than red. It is not an error: the
+ * credential is absent from this target's store, which is a thing to do, and
+ * `--destructive` is reserved for something having gone wrong. `disabled` is
+ * quieter still, being a row that config no longer declares.
+ */
+function statusPill(state: string): string {
+  const kind = state === 'active' ? 'positive' : state === 'disabled' ? 'quiet' : 'neutral';
+  return `<span class="pill ${kind}">${escapeHtml(state)}</span>`;
+}
+
+function connectionsSection(view: DashboardView): string {
+  if (view.connections.length === 0) {
+    return '<p class="empty">Nothing connected in this profile yet. Pick one below.</p>';
+  }
+
+  const rows = view.connections
+    .map((connection) => {
+      // A connection that is not active is one the reader can act on, and the
+      // action is the same `connect` that made it — re-running against an
+      // existing key repairs it rather than adding a second account. An active
+      // one has nothing to do, so it carries no button.
+      const repair =
+        connection.state === 'active'
+          ? ''
+          : copyButton(command(view, `connect ${connection.key}`), connection.key);
+
+      return (
+        '<div class="row">' +
+        mark(connection.provider) +
+        `<code class="key">${escapeHtml(connection.key)}</code>` +
+        statusPill(connection.state) +
+        `<span class="account">${escapeHtml(connection.account)}</span>` +
+        repair +
+        '</div>'
+      );
+    })
+    .join('\n');
+
+  return `<div class="rows">${rows}</div>`;
+}
+
+/**
+ * One provider, one line: what it is called and the line that connects it.
+ *
+ * Everything else a card used to carry is gone — the description, whether it
+ * opens a browser, who operates its OAuth client. None of it is lost: it is all
+ * in `lanes link setup plan` and in the `setup_provider` capability, both of
+ * which exist to answer "what does connecting this involve" at the length that
+ * question deserves. This page answers a different one — what is there, and
+ * what would I paste — and a paragraph per provider buried it.
+ *
+ * `plan.command` is built by the same `planFor` those two render, so the line
+ * copied here and the line an agent suggests cannot drift.
+ */
+function providerCard(plan: ProviderPlan): string {
+  return (
+    '<div class="row">' +
+    mark(plan.id) +
+    `<span class="name">${escapeHtml(plan.name)}</span>` +
+    copyButton(plan.command, plan.name) +
+    '</div>'
+  );
+}
+
+function catalogue(view: DashboardView): { available: string; another: string } {
+  const plans = planAll(PROVIDER_MANIFESTS, {
+    profile: view.profile,
+    connections: view.connections.map((connection) => connection.key),
+    ownClients: view.ownClients,
+    target: view.target,
+  });
+
+  // The same split `setup_overview` makes: never connected is an invitation,
+  // and already connected is only an invitation when a second account means
+  // something (ADR — `multiAccount` is the credential test, not a preference).
+  const available = plans.filter((plan) => plan.connected.length === 0);
+  const more = plans.filter((plan) => plan.connected.length > 0 && plan.multiAccount);
+
+  return {
+    available: available.map(providerCard).join('\n'),
+    another: more.map(providerCard).join('\n'),
+  };
+}
+
+function switcher(view: DashboardView): string {
+  // Links, not a form: choosing a profile here changes what this page shows and
+  // nothing else. The workspace default is config, and config is written from
+  // the CLI.
+  const profiles = view.profiles
+    .map((name) => {
+      const current = name === view.profile;
+      const label = escapeHtml(name);
+      return current
+        ? `<span class="chip on">${label}</span>`
+        : `<a class="chip" href="?profile=${encodeURIComponent(name)}">${label}</a>`;
+    })
+    .join('');
+
+  // Every declared target, with the one whose adapters are actually open marked.
+  // The others are real — they are where `--target` would write — but nothing on
+  // this page is reading from them.
+  const targets = view.targets
+    .map((name) =>
+      name === view.target
+        ? `<span class="chip on">${escapeHtml(name)}</span>`
+        : `<span class="chip off" title="declared, but not the one this endpoint opened">${escapeHtml(name)}</span>`,
+    )
+    .join('');
+
+  return (
+    '<div class="switch">' +
+    `<div class="group"><span class="eyebrow">profile</span>${profiles}</div>` +
+    `<div class="group"><span class="eyebrow">target</span>${targets}</div>` +
+    '</div>'
+  );
+}
+
+export function dashboardPage(view: DashboardView): Response {
+  const { available, another } = catalogue(view);
+
+  const body =
+    `<h1>Lanes Link</h1>${switcher(view)}` +
+    `<h2 class="eyebrow">Connections</h2>${connectionsSection(view)}` +
+    (available ? `<h2 class="eyebrow">Available</h2><div class="rows">${available}</div>` : '') +
+    (another ? `<h2 class="eyebrow">Connect another account</h2><div class="rows">${another}</div>` : '') +
+    '<h2 class="eyebrow">Elsewhere</h2>' +
+    '<p class="empty">What is reachable, and what is wrong with it:</p>' +
+    commandLine(command(view, 'status')) +
+    commandLine(command(view, 'doctor'));
+
+  return shell(body, 'Lanes Link', 200);
+}
+
+/**
+ * What an unauthenticated browser gets.
+ *
+ * The narrow card rather than the wide page, because it is one sentence — and
+ * it names the command instead of asking for the token, since the command is
+ * what puts the token in the URL in the first place. A password field here
+ * would be a second way in to guard for no benefit: whoever can run the command
+ * is already whoever the token would prove them to be.
+ *
+ * The one command on this page carries neither `--profile` nor `--target`,
+ * against the rule every other command here follows. Both are names, and this
+ * page answers before authentication — ADR-018 stopped `/health` naming
+ * profiles to an anonymous caller for exactly that reason, and a 401 that
+ * recites the workspace's profile list would put it back.
+ */
+export function dashboardSignInPage(status: number): Response {
+  return shell(
+    '<div class="narrow"><h1>Not signed in</h1>' +
+      '<p class="desc">This page opens from the terminal that is serving it.</p>' +
+      commandLine('lanes link dashboard') +
+      '</div>',
+    'Lanes Link',
+    status,
+  );
+}

package/src/cli/dashboard-shell.ts

@@ -0,0 +1,125 @@
+import { escapeHtml, FONTS, FOOTER, PAGE_CSP, PAGE_HEADERS, TOKENS } from './brand.ts';
+
+/**
+ * The dashboard's chrome: its layout, its one listener, and the document they
+ * hang in.
+ *
+ * Split from `dashboard-page.ts` because the two answer different questions —
+ * that file decides what a row says, this one decides what a row looks like and
+ * what the response is allowed to load. Everything shared with the two
+ * authorization pages, which is every colour and every face, is in `brand.ts`;
+ * what is left here is the one thing this surface does not share with them, a
+ * wide list rather than a centred card.
+ */
+
+const STYLE = `
+body { padding: 40px 24px; }
+.wrap { width: 100%; max-width: 620px; margin: 0 auto; }
+.narrow { text-align: center; padding: 32px 0; }
+h1 { margin: 0 0 20px; }
+h2 { margin: 30px 0 8px; }
+.desc { margin: 0 0 12px; font-size: 14px; line-height: 1.6; color: var(--muted-foreground); }
+.empty { margin: 0 0 12px; font-size: 14px; line-height: 1.6; color: var(--muted-foreground);
+         opacity: 0.8; }
+
+/* Profile and target selectors. The current one is not gold: gold says a thing
+   is good, and which profile you are looking at is not a verdict. */
+.switch { display: flex; flex-wrap: wrap; gap: 20px; padding-bottom: 4px; }
+.group { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+.chip { display: inline-block; padding: 3px 10px; font-size: 13px; border-radius: 999px;
+        border: 1px solid var(--border); color: var(--muted-foreground); text-decoration: none; }
+.chip:hover { color: var(--foreground); background: var(--muted); }
+.chip.on { color: var(--foreground); background: var(--muted); font-weight: 500; }
+.chip.off { border-style: dashed; opacity: 0.5; }
+
+/* One line per item: mark, name, whatever qualifies it, then the button hard
+   right. \`min-width: 0\` on the row lets the name ellipsize rather than push
+   the button off the end. */
+.rows { display: flex; flex-direction: column; }
+.row { display: flex; align-items: center; gap: 10px; min-width: 0;
+       padding: 7px 10px 7px 4px; border-radius: 6px; }
+.row:hover { background: var(--muted); }
+.glyph { flex: none; display: inline-flex; align-items: center; justify-content: center;
+         width: 17px; height: 17px; margin: 0 3px; opacity: 0.85; }
+/* The stand-in wants the box the real marks do not: bare letters read as a mark
+   that failed to load, where a brand mark reads as itself. */
+.glyph.letters { width: 23px; height: 23px; margin: 0; border-radius: 6px; font-size: 8.5px;
+                 font-weight: 500; letter-spacing: 0.02em; color: var(--muted-foreground);
+                 border: 1px solid var(--border); opacity: 1; }
+.name, .key { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.name { font-size: 14px; }
+.key { font-family: var(--mono); font-size: 13px; }
+.account { font-size: 12.5px; color: var(--muted-foreground); opacity: 0.8; min-width: 0;
+           overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+/* Always visible, never revealed on hover: the button is the only way to get the
+   command now that the line itself is not on the page, and an affordance you
+   have to find by sweeping the mouse is one most readers never find. */
+.copy { margin-left: auto; opacity: 0.6; }
+.row:hover .copy { opacity: 1; }
+.copy:hover, .copy:focus-visible { opacity: 1; }
+
+/* The two places the command is still the label, so it stays visible. */
+.cmd { display: flex; align-items: center; gap: 8px; margin-top: 8px; padding: 8px 10px;
+       background: var(--card); border: 1px dashed var(--border); border-radius: 10px; }
+.cmd code { flex: 1; font-size: 12.5px; line-height: 1.5; word-break: break-all; }
+.cmd .copy { opacity: 0.8; margin-left: 0; }
+`.trim();
+
+/**
+ * The copy button, and nothing else.
+ *
+ * Inline because a separate file would be the first static asset this
+ * repository serves, and one listener is not worth that. It reads the command
+ * from a data attribute rather than from the DOM text so that what is copied is
+ * exactly what was rendered, whitespace included.
+ */
+const SCRIPT = `
+document.addEventListener('click', function (event) {
+  var button = event.target.closest('.copy');
+  if (!button || !navigator.clipboard) return;
+  navigator.clipboard.writeText(button.dataset.copy).then(function () {
+    button.textContent = 'copied';
+    setTimeout(function () { button.textContent = 'copy'; }, 1200);
+  });
+});
+`.trim();
+
+export function shell(inner: string, title: string, status: number): Response {
+  return new Response(
+    `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+${FONTS}
+<title>${escapeHtml(title)}</title>
+<style>
+${TOKENS}
+${STYLE}
+</style>
+</head>
+<body>
+<div class="wrap">
+${inner}
+${FOOTER}
+</div>
+<script>
+${SCRIPT}
+</script>
+</body>
+</html>`,
+    {
+      status,
+      headers: {
+        ...PAGE_HEADERS,
+        // The shared policy plus the one thing this page has that the others do
+        // not: an inline listener, for the copy button.
+        'content-security-policy': `${PAGE_CSP}; script-src 'unsafe-inline'`,
+        // Connection keys and account names are not something to leave in a
+        // shared browser's back-forward cache.
+        'cache-control': 'no-store',
+      },
+    },
+  );
+}

package/src/cli/identity.ts

@@ -58,7 +58,18 @@ export async function resolveAccount(
         headers: token ? { authorization: `Bearer ${token}` } : {},
       });
       if (!response.ok) return null;
-      return pluck(await response.json(), identity.field);
+
+      const body = await response.json();
+      const primary = pluck(body, identity.field);
+      if (!primary || !identity.qualifier) return primary;
+
+      // `alice (Acme)` rather than `alice`. The bracketed half is what makes
+      // two workspaces two accounts instead of one overwritten twice, and it
+      // survives into the connection id because `idFromAccount` slugifies the
+      // whole string when there is no `@` in it — `alice_acme`, which is a row
+      // somebody can read in `status`.
+      const qualifier = pluck(body, identity.qualifier);
+      return qualifier ? `${primary} (${qualifier})` : primary;
     }
 
     if (!probe.callTool) return null;

package/src/cli/main.ts

@@ -5,6 +5,7 @@ import {
   auditVerify,
   check,
   configShow,
+  dashboard,
   doctor,
   outputs,
   plan,
@@ -19,6 +20,7 @@ import {
 import { profileAdd, profileDefault, profileList } from './commands/profile.ts';
 import { removeProfile as profileRemove } from './commands/profile/remove.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';
@@ -38,8 +40,10 @@ import {
   vaultRemove,
   vaultSet,
 } from './commands/owner.ts';
+import { knowledgeShow, knowledgeUse } from './commands/knowledge.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 +78,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 +97,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 +110,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 +150,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':
@@ -221,6 +265,19 @@ export async function run(argv: readonly string[]): Promise<void> {
           throw new Error(`Unknown: ${PROGRAM} skills ${second}`);
       }
 
+    // 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.
+    case 'knowledge':
+      switch (second) {
+        case 'show':
+        case undefined:
+          return knowledgeShow(knowledgeFlags(flags));
+        case 'use':
+          return knowledgeUse(rest[0], knowledgeFlags(flags));
+        default:
+          throw new Error(`Unknown: ${PROGRAM} knowledge ${second}`);
+      }
+
     case 'vault':
       switch (second) {
         case 'list':
@@ -252,6 +309,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