@lanes-sh/link 0.3.0 → 0.3.2

package/src/deployments/discover.ts

@@ -0,0 +1,103 @@
+import { readWorkspaceFile, workspaceFiles, WORKSPACE_FILE } from '#profile';
+import { captureGcloud } from './gcp/gcloud.ts';
+
+/**
+ * Finding a deployment nothing in the workspace mentions any more.
+ *
+ * The last resort, and the one that works from nothing. A profile that lost its
+ * target block and a workspace with no index between them leave no local record
+ * that a deployment ever existed — but the deployment is still there, still
+ * answering, and still holding the config it was given. Asking the platform is
+ * the only way back from that state.
+ *
+ * Deliberately opt-in. It is a `gcloud` call per project and there may be
+ * dozens, so a command that did this on every run would be one nobody waits
+ * for. Everything cheaper is tried first.
+ */
+
+export interface Candidate {
+  readonly project: string;
+  readonly region: string;
+  readonly service: string;
+  /** The bucket holding a workspace, when one was found beside the service. */
+  readonly workspace: string | undefined;
+}
+
+/**
+ * Cloud Run services across every project this login can see.
+ *
+ * Not filtered by name. A service is a candidate because a bucket beside it
+ * holds a workspace, not because of what it is called — the operator may have
+ * named it anything, and a name filter would hide exactly the deployment whose
+ * naming convention nobody remembers.
+ */
+export async function discoverDeployments(
+  onProgress?: (project: string) => void,
+): Promise<Candidate[]> {
+  const projects = await captureGcloud(['projects', 'list', '--format', 'value(projectId)']);
+  if (!projects.ok) return [];
+
+  const found: Candidate[] = [];
+
+  for (const project of projects.stdout.split('\n').map((line) => line.trim()).filter(Boolean)) {
+    onProgress?.(project);
+
+    const services = await captureGcloud([
+      'run',
+      'services',
+      'list',
+      '--project',
+      project,
+      '--format',
+      'value(metadata.name,metadata.labels."cloud.googleapis.com/location")',
+    ]);
+    if (!services.ok || !services.stdout) continue;
+
+    for (const line of services.stdout.split('\n').map((entry) => entry.trim()).filter(Boolean)) {
+      const [service = '', region = ''] = line.split(/\s+/);
+      if (!service || !region) continue;
+
+      found.push({ project, region, service, workspace: await workspaceBeside(project) });
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Whether a project holds a bucket with a workspace in it.
+ *
+ * The survey names the bucket after the project, so that is checked first and
+ * is almost always the answer. Falling back to listing every bucket costs a
+ * second call and covers a workspace whose bucket was named by hand.
+ */
+async function workspaceBeside(project: string): Promise<string | undefined> {
+  if (await holdsWorkspace(`gs://${project}`)) return `gs://${project}`;
+
+  const buckets = await captureGcloud([
+    'storage',
+    'buckets',
+    'list',
+    '--project',
+    project,
+    '--format',
+    'value(name)',
+  ]);
+  if (!buckets.ok) return undefined;
+
+  for (const name of buckets.stdout.split('\n').map((line) => line.trim()).filter(Boolean)) {
+    if (name === project) continue;
+    if (await holdsWorkspace(`gs://${name}`)) return `gs://${name}`;
+  }
+
+  return undefined;
+}
+
+/** A bucket is a workspace when it has the file that says so. Never throws. */
+export async function holdsWorkspace(url: string): Promise<boolean> {
+  try {
+    return (await readWorkspaceFile(workspaceFiles(url), WORKSPACE_FILE)) !== null;
+  } catch {
+    return false;
+  }
+}

package/src/deployments/prepare.ts

@@ -61,11 +61,15 @@ export interface PrepareResult {
  * Called before `provision`, which is before any store is opened — so it reads
  * config and manifests only, and touches no credential.
  */
-export async function rotatableRefs(root: string, profile: string | undefined): Promise<string[]> {
+export async function rotatableRefs(
+  root: string,
+  profiles: readonly string[] | undefined,
+): Promise<string[]> {
   const refs = new Set<string>();
+  const wanted = profiles === undefined ? undefined : new Set(profiles);
 
   for (const name of await listProfiles(root)) {
-    if (profile !== undefined && name !== profile) continue;
+    if (wanted !== undefined && !wanted.has(name)) continue;
 
     let config: Config;
     try {
@@ -121,7 +125,7 @@ export async function rotatableRefs(root: string, profile: string | undefined):
  */
 export async function readableRefs(
   root: string,
-  profile: string | undefined,
+  profiles: readonly string[] | undefined,
   declared: TargetConfig | undefined,
 ): Promise<string[]> {
   const refs = new Set<string>();
@@ -134,8 +138,10 @@ export async function readableRefs(
     refs.add(VAULT_KEY_REF);
   }
 
+  const wanted = profiles === undefined ? undefined : new Set(profiles);
+
   for (const name of await listProfiles(root)) {
-    if (profile !== undefined && name !== profile) continue;
+    if (wanted !== undefined && !wanted.has(name)) continue;
 
     let config: Config;
     try {

package/src/deployments/report.ts

@@ -0,0 +1,117 @@
+import type { DeployConfig } from '#profile';
+import { heading, ok, print, style, warn } from '#cli/output.ts';
+
+/**
+ * What a deploy tells the operator, as against what it does.
+ *
+ * Split out of `deploy.ts` because that file is the ordered list of things that
+ * have to happen to roll a revision, and this is none of them: which door the
+ * platform left open, whether the endpoint came up, how to register it, and
+ * which credentials the revision will find missing. Every one of these runs
+ * before or after the rollout and changes nothing about it.
+ *
+ * They are worth keeping together. Each is a sentence someone acts on — two of
+ * them are commands to paste — and the failure they exist against is a deploy
+ * that succeeds and leaves the operator with a URL and no idea what to do next.
+ */
+
+/**
+ * How to register the endpoint, and when.
+ *
+ * The ordering is the whole point of the second half. A client captures
+ * `tools/list` when it connects and keeps it: this endpoint is stateless, so
+ * there is no stream on which to send `notifications/tools/list_changed`, and
+ * `buildMcpServer` no longer pretends otherwise. A first deploy necessarily
+ * publishes a profile whose only connection is `setup.main` — the accounts come
+ * after — so a connector registered in that window captures a two-tool surface
+ * and holds it. The endpoint is right, every reload lands, and the client shows
+ * two tools until someone removes and re-adds it.
+ *
+ * Unconditional, and that is the correction that matters. This was gated on
+ * `prepared.warnings.length`, which is zero in precisely the case it describes:
+ * a fresh profile declares only `setup.main`, `setup` is a local provider with
+ * no credential, so `prepareSecrets` has nothing to warn about. The advice
+ * appeared only on a later re-deploy, by which point the connector is usually
+ * registered and the ordering is no longer available to get right.
+ */
+export function registerLine(profile: string, target: string): string {
+  return style.dim(
+    `  Connect your accounts first, then register with:\n` +
+      `    lanes link outputs --profile ${profile} --target ${target}\n` +
+      '  A client keeps the tool list it fetched when it connected, so one registered\n' +
+      '  before the accounts holds a surface without them until it is re-added.',
+  );
+}
+
+/**
+ * The accounts a browser still has to authorise, and the step after them.
+ *
+ * Printed last rather than before the build, because this is the only thing
+ * left to do and a list eight steps up the scrollback is a list nobody reads.
+ *
+ * There is no second deploy at the end of it any more, and the reason the old
+ * one existed is worth keeping. Connection *credentials* are read live on every
+ * call, so a fresh `connect` looked like it should be picked up — but whether a
+ * connection was usable at all was decided by a reconcile that ran once per
+ * process, so a revision that came up with an account unauthorised went on
+ * refusing it, naming the connection rather than the staleness. Reconcile now
+ * runs again on every reload, and `connect` asks for one (ADR-029).
+ */
+export function reportUnauthorised(warnings: readonly string[], profile: string, target: string): void {
+  if (warnings.length === 0) return;
+
+  heading('Not authorised yet');
+  for (const problem of warnings) print(warn(problem));
+  print('');
+  print(
+    style.dim(
+      '  A browser consent per account is the one step this cannot take for you:\n' +
+        `    lanes link connect <provider> --profile ${profile} --target ${target}\n` +
+        '  Each is served as soon as it is authorised. There is no second deploy —\n' +
+        '  deploying is how code gets here, and authorising an account changes none.',
+    ),
+  );
+}
+
+/**
+ * Who can reach the service once this lands.
+ *
+ * Printed on every deploy rather than only when it changes, because it is the
+ * one property of a deployment that is invisible from the outside until someone
+ * either cannot get in or should not have been able to.
+ */
+export function reachability(access: DeployConfig['access']): string {
+  return access === 'iam'
+    ? style.dim(
+        '  access:   iam — the platform admits only callers holding its own identity\n' +
+          '            token. No agent harness can mint one; use --access public with an\n' +
+          '            authorization block if a remote MCP client has to reach this.',
+      )
+    : style.dim(
+        '  access:   public — the platform lets requests through and this endpoint\n' +
+          '            authenticates them. The bearer token is what protects it.',
+      );
+}
+
+/** Ask the deployed endpoint whether it came up. */
+export async function healthLine(url: string): Promise<string> {
+  try {
+    const response = await fetch(`${url}/health`, { signal: AbortSignal.timeout(10_000) });
+    if (!response.ok) return warn(`the endpoint answered /health with ${response.status}`);
+
+    // Asked anonymously, so it reports that the revision is up and nothing
+    // about what it serves — the profile list is behind the token now.
+    // `lanes link outputs` holds one and prints the rest.
+    const body = (await response.json()) as { profiles?: string[] };
+    return ok(
+      body.profiles
+        ? `healthy — serving ${body.profiles.join(', ')}`
+        : 'healthy — run `lanes link outputs` with this profile and target for what it serves',
+    );
+  } catch {
+    // A cold start plus a database connect can outrun a short probe, and
+    // `access: iam` makes /health unreachable from here by design. Neither is a
+    // failed deploy.
+    return warn('could not reach /health from here — with access: iam that is expected');
+  }
+}

package/src/deployments/servable.ts

@@ -42,13 +42,14 @@ export interface Unservable {
  */
 export async function unservableProfiles(input: {
   readonly workspaceRoot: string;
-  readonly profile: string | undefined;
+  readonly profiles: readonly string[] | undefined;
   readonly target: string;
 }): Promise<Unservable[]> {
   const found: Unservable[] = [];
+  const wanted = input.profiles === undefined ? undefined : new Set(input.profiles);
 
   for (const name of await listProfiles(input.workspaceRoot)) {
-    if (input.profile !== undefined && name !== input.profile) continue;
+    if (wanted !== undefined && !wanted.has(name)) continue;
 
     let declared: string[];
     try {

package/src/deployments/serving.ts

@@ -0,0 +1,165 @@
+import {
+  ConfigError,
+  findDeployment,
+  loadWorkspaceProfiles,
+  type WorkspaceProfiles,
+} from '#profile';
+import { rotatableCredentialRefsFor } from '#registry';
+import { buildRegistryWithWorkspace } from '#cli/runtime.ts';
+
+/**
+ * Which profiles a deploy sends, and whether they can share one place.
+ *
+ * `deploy` used to send the profile it was told and no other. That reads as the
+ * safe default and is not what the thing being deployed does: one endpoint
+ * serves *every* profile in the bucket (ADR-009), so a workspace with two
+ * profiles needed two deploys, and the second one had to be told a target the
+ * profile did not declare yet — which the survey then offered to create
+ * somewhere new. The way to deploy both was to know that already.
+ *
+ * The set is derived rather than guessed: it is every profile declaring the
+ * target, which is exactly the set the endpoint will try to open. `--profile`
+ * narrows it, and naming one is still how a first deploy works, because a
+ * target nothing declares has no set to derive (ADR-043).
+ */
+
+export interface Serving {
+  /** Every profile this deploy will upload. Never empty. */
+  readonly profiles: string[];
+  /** Whose token opens the endpoint, and what the revision is told it is. */
+  readonly primary: string;
+}
+
+export async function servingProfiles(input: {
+  readonly workspaceRoot: string;
+  readonly target: string;
+  /** What `--profile` named, in order. Empty when it named nothing. */
+  readonly named: readonly string[];
+}): Promise<Serving> {
+  const { workspaceRoot, target, named } = input;
+
+  if (named.length > 0) {
+    return { profiles: [...named], primary: named[0]! };
+  }
+
+  const workspace = await loadWorkspaceProfiles(workspaceRoot);
+  const declaring = workspace.loaded
+    .filter((entry) => target in entry.config.targets)
+    .map((entry) => entry.profile);
+
+  if (declaring.length === 0) {
+    throw new ConfigError(
+      `No profile declares "${target}", so there is no set to deploy.\n` +
+        '  A first deploy creates the target, and has to be told which profile\n' +
+        '  it belongs to:\n' +
+        `    lanes link deploy --target ${target} --profile <name>\n\n` +
+        `  If "${target}" was deployed before and the declaration was lost:\n` +
+        `    lanes link sync targets --target ${target} --discover`,
+    );
+  }
+
+  return { profiles: declaring, primary: await choosePrimary(workspaceRoot, target, declaring) };
+}
+
+/**
+ * Whose bearer token opens the endpoint.
+ *
+ * One endpoint, one token, every profile behind it (ADR-009) — so this decides
+ * who gets in, and it is the one thing about a deployment that must not be
+ * inferred from whatever happens to sort first. Recorded by the last deploy
+ * when there was one; otherwise there has to be exactly one candidate, or the
+ * operator is asked.
+ */
+async function choosePrimary(
+  workspaceRoot: string,
+  target: string,
+  declaring: readonly string[],
+): Promise<string> {
+  const recorded = (await findDeployment(workspaceRoot, target))?.primary;
+  if (recorded !== undefined && declaring.includes(recorded)) return recorded;
+
+  if (declaring.length === 1) return declaring[0]!;
+
+  throw new ConfigError(
+    `${declaring.length} profiles declare "${target}", and nothing records which\n` +
+      "of them owns the endpoint's token. One token opens the endpoint and\n" +
+      'reaches every profile behind it, so this cannot be picked for you.\n\n' +
+      `  Name it once and it is remembered:\n` +
+      `    lanes link deploy --target ${target} --profile ${declaring[0]!}` +
+      declaring
+        .slice(1)
+        .map((name) => ` --profile ${name}`)
+        .join(''),
+  );
+}
+
+/**
+ * A credential reference two profiles would both write, in one store.
+ *
+ * References are flat — `gmail/main`, not `personal/gmail/main` — and a target
+ * has one credential store, so two profiles deployed to the same project share
+ * a namespace. `docs/detailed/configuration.md` admits this in an aside about
+ * removing a profile; deploying both at once is where it stops being an aside.
+ *
+ * The failure is silent and it is the bad kind: `personal`'s Gmail refresh
+ * token is overwritten by `work`'s, both profiles go on listing their own
+ * account in config, and the first symptom is one of them reading the other's
+ * mailbox. Nothing downstream can catch it, because by then there is one
+ * credential and it is valid.
+ *
+ * `profile/token` is deliberately not a collision. Every profile defaults to
+ * that ref and the endpoint has exactly one token by design — sharing it is
+ * what ADR-009 says happens, rather than an accident.
+ */
+export interface Collision {
+  readonly ref: string;
+  readonly profiles: string[];
+}
+
+export async function collidingRefs(
+  workspaceRoot: string,
+  profiles: readonly string[],
+  workspace?: WorkspaceProfiles,
+): Promise<Collision[]> {
+  const loaded = (workspace ?? (await loadWorkspaceProfiles(workspaceRoot))).loaded.filter(
+    (entry) => profiles.includes(entry.profile),
+  );
+
+  const owners = new Map<string, string[]>();
+
+  for (const entry of loaded) {
+    const registry = await buildRegistryWithWorkspace(workspaceRoot, entry.profile);
+    const refs = new Set<string>();
+
+    for (const connection of entry.config.connections) {
+      const manifest = registry.manifest(connection.provider);
+      for (const ref of rotatableCredentialRefsFor(connection, manifest)) refs.add(ref);
+      if (connection.credential_ref) refs.add(connection.credential_ref);
+    }
+
+    for (const ref of refs) {
+      if (ref === entry.config.auth.token_ref) continue;
+      owners.set(ref, [...(owners.get(ref) ?? []), entry.profile]);
+    }
+  }
+
+  return [...owners.entries()]
+    .filter(([, names]) => names.length > 1)
+    .map(([ref, names]) => ({ ref, profiles: names.sort() }))
+    .sort((a, b) => a.ref.localeCompare(b.ref));
+}
+
+/** The refusal, as a block, so the wording is testable without a deploy. */
+export function collisionRefusal(found: readonly Collision[], target: string): string {
+  const rows = found.map((one) => `    ${one.ref}   ${one.profiles.join(', ')}`).join('\n');
+
+  return (
+    `${found.length} credential reference(s) would be written by more than one\n` +
+    `profile into the one credential store "${target}" has:\n\n${rows}\n\n` +
+    '  References are flat, so these are the same secret and the last deploy\n' +
+    '  wins — after which one profile is reading the other\'s account, and\n' +
+    '  both still name their own in config.\n\n' +
+    '  Give the connections different ids, or deploy the profiles to targets\n' +
+    '  in separate projects.'
+  );
+}