@lanes-sh/link 0.2.2 → 0.3.1

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/driver.ts

@@ -39,7 +39,14 @@ export interface PlanInput {
   readonly deploy: DeployConfig;
   readonly tag: string;
   readonly target: string;
-  readonly profile?: string | undefined;
+  /**
+   * The primary profile this revision serves.
+   *
+   * Required rather than optional: `deploy` names it (ADR-037), and a revision
+   * that boots without `LANES_LINK_PROFILE` refuses. Leaving it optional here is
+   * what let deployments ship without the variable at all.
+   */
+  readonly profile: string;
   /**
    * Where the running instance reads its config, as a store URL.
    *

package/src/deployments/gcp/driver.ts

@@ -103,7 +103,9 @@ export function deployPlan(input: PlanInput): DeployStep[] {
         '--set-env-vars',
         [
           `LANES_LINK_TARGET=${input.target}`,
-          ...(input.profile ? [`LANES_LINK_PROFILE=${input.profile}`] : []),
+          // Unconditional: `deploy` requires --profile (ADR-037), so this is
+          // always known, and a revision without it refuses at boot.
+          `LANES_LINK_PROFILE=${input.profile}`,
           ...(input.workspace ? [`LANES_LINK_HOME=${input.workspace}`] : []),
         ].join(','),
         ...secretMounts(input.secretEnv),

package/src/deployments/knowledge.ts

@@ -0,0 +1,119 @@
+import type { SecretStore } from '#secrets';
+import type { BlobStore } from '#stores/blobs';
+import { knowledgeRoot, type KnowledgeConfig } from '#profile';
+import { requireSecret, type TargetInput } from './target.ts';
+import type { FetchLike } from './adapters/github-api.ts';
+// Type-only, so a target with no `knowledge` block never loads the adapter.
+// The same rule `target.ts` follows for the cloud adapters, kept here by the
+// fact that a type import is erased entirely.
+import type { GithubRepository } from './adapters/github-repo.ts';
+// Re-exported so a caller that wants to replace the transport does not have to
+// reach past this module into an adapter. It is narrower than
+// `typeof globalThis.fetch`, which under Bun's types carries a `preconnect` a
+// test double would otherwise have to stub.
+export type { FetchLike } from './adapters/github-api.ts';
+
+/**
+ * Opening the place a profile keeps its memory and its skills, when that is not
+ * the place it keeps everything else.
+ *
+ * Its own file rather than a fifth case in `target.ts`, because it is not the
+ * same kind of decision. `target.ts` answers "where does this target run" —
+ * credentials here, bytes there — and every consumer of a `BlobStore` rides
+ * that one answer. This answers a narrower one: two directories of documents
+ * the owner wrote have somewhere else to be, and nothing else moves with them.
+ *
+ * ADR-041 has the argument. `src/profile/knowledge.ts` has the contract, and
+ * the reason there is no field here that could name the credential store or the
+ * vault.
+ */
+
+/**
+ * One repository client, two stores.
+ *
+ * Memory and skills are two directories in one repository, and pointing both at
+ * one client means one branch head, one tree, and one blob cache between them —
+ * so the endpoint's two-second skill poll keeps memory's view current for free.
+ * Two clients would each poll, each cache, and could disagree about which
+ * commit is current.
+ */
+export interface KnowledgeStores {
+  readonly repository: GithubRepository;
+  readonly skills: BlobStore;
+  /** Rooted at the repository's memory directory; keys are `<connection>/<id>.md`. */
+  readonly memory: BlobStore;
+  /** One line for `target show` and `doctor`, so the config file is not the only witness. */
+  readonly describe: string;
+}
+
+/**
+ * `undefined` when the target declares no `knowledge` block — which is every
+ * profile written before it existed, so the caller's fallback is the path that
+ * has always run rather than a special case.
+ */
+export async function openKnowledge(
+  input: TargetInput,
+  secrets: SecretStore,
+  /** Injected for tests. The repository is the only thing these stores reach. */
+  call?: FetchLike,
+): Promise<KnowledgeStores | undefined> {
+  const { declared, target } = input;
+  const knowledge = declared.knowledge;
+  if (!knowledge) return undefined;
+
+  const token = await requireSecret(
+    secrets,
+    knowledge.token_ref,
+    `targets.${target}.knowledge.token_ref`,
+    target,
+    'the github adapter',
+  );
+
+  const { GithubRepository } = await import('./adapters/github-repo.ts');
+  const repository = new GithubRepository({
+    repo: knowledge.repo,
+    token,
+    ...(knowledge.branch !== undefined ? { branch: knowledge.branch } : {}),
+    ...(call ? { fetch: call } : {}),
+  });
+
+  return {
+    repository,
+    ...(await knowledgeStores(repository, knowledge)),
+    describe: describeKnowledge(knowledge),
+  };
+}
+
+/**
+ * The two stores a knowledge repository holds.
+ *
+ * Separate from `openKnowledge` because `lanes link knowledge use` builds these
+ * against a repository it is still probing — before any of it has been written
+ * into the config `openKnowledge` reads. Two spellings of one layout is how a
+ * migration comes to write where nothing later looks.
+ */
+export async function knowledgeStores(
+  repository: GithubRepository,
+  knowledge: KnowledgeConfig,
+): Promise<{ skills: BlobStore; memory: BlobStore }> {
+  const { createGithubBlobStore } = await import('./adapters/github.ts');
+
+  const build = (area: 'memory' | 'skills'): BlobStore =>
+    createGithubBlobStore({
+      repository,
+      root: knowledgeRoot(knowledge, area),
+      // What the commit says it did. Named per area rather than left to the
+      // adapter's default, because "Store main/note.md" in a repository holding
+      // both is a line that does not say which of them changed.
+      message: (operation, key) =>
+        `${operation === 'store' ? 'Store' : 'Remove'} ${area === 'skills' ? 'skill' : 'memory'} ${key}`,
+    });
+
+  return { skills: build('skills'), memory: build('memory') };
+}
+
+/** `github:owner/name#branch/path`, in one place so every reader agrees. */
+export function describeKnowledge(knowledge: KnowledgeConfig): string {
+  const branch = knowledge.branch ? `#${knowledge.branch}` : '';
+  return `github:${knowledge.repo}${branch}${knowledge.path ? `/${knowledge.path}` : ''}`;
+}

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 {
@@ -188,7 +194,7 @@ export async function prepareSecrets(input: PrepareInput): Promise<PrepareResult
     if (!ref || (await credentials.has(ref))) continue;
     warnings.push(
       `${connection.provider}.${connection.id} is not authorised yet — no credential at "${ref}"\n` +
-        `    lanes link connect ${connection.provider} --target ${target} --id ${connection.id}`,
+        `    lanes link connect ${connection.provider} --profile ${input.config.instance.profile} --target ${target} --id ${connection.id}`,
     );
   }
 
@@ -252,6 +258,6 @@ async function seedProfileToken(input: {
   }
 
   const { created } = await ensureProfileToken(input.credentials, ref);
-  if (created) print(ok(`minted an endpoint token at "${ref}" — read it with: lanes link token show`));
+  if (created) print(ok(`minted an endpoint token at "${ref}" — read it with lanes link token show`));
 }
 

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

@@ -0,0 +1,82 @@
+import { listProfiles, loadProfileConfig } from '#profile';
+
+/**
+ * Whether every profile a deploy sends can actually run on the target it sends them to.
+ *
+ * A deploy uploads config for a set of profiles and rolls a revision baked with
+ * one `LANES_LINK_TARGET`. The endpoint then opens *every* profile it finds in
+ * the bucket against that one target — see `openReconciled` — and a profile that
+ * does not declare it throws on the way up. The catch there closes the runtimes
+ * and rethrows, so the container exits and the revision never goes healthy.
+ *
+ * That is the whole failure, and its shape is what makes it worth a pre-flight:
+ * the profile at fault is usually the one just scaffolded, the operator was not
+ * thinking about the deployment when they made it, and the symptom is a revision
+ * that will not start — which reads as a problem with the deploy, the image, or
+ * the platform. Nothing points at the new profile. Refusing here costs one file
+ * read per profile and names it.
+ *
+ * Its own file, not a private function in `deploy.ts`, for the reason
+ * `handoff.ts` gives: `deploy.test.ts` does not import `deploy.ts`, and making
+ * it do so would pull the whole CLI runtime into a unit test.
+ */
+
+export interface Unservable {
+  readonly profile: string;
+  /** What it does declare, so the refusal says how far off it is. */
+  readonly declares: readonly string[];
+}
+
+/**
+ * The profiles this deploy would send that the revision could not open.
+ *
+ * Scoped exactly as `uploadWorkspace` and `repairSetupSurface` are — by the
+ * `--profile` flag, absent meaning the whole workspace — because the set that
+ * gets uploaded is the set that gets served, and checking a different one would
+ * be checking the wrong question.
+ *
+ * A profile that cannot be parsed is not reported here. It is already fatal
+ * further along, with a better message than this could give, and a YAML error
+ * dressed up as "cannot run on cloud" would send someone looking at their
+ * targets instead of their syntax.
+ */
+export async function unservableProfiles(input: {
+  readonly workspaceRoot: string;
+  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 (wanted !== undefined && !wanted.has(name)) continue;
+
+    let declared: string[];
+    try {
+      const { config } = await loadProfileConfig(input.workspaceRoot, name);
+      declared = Object.keys(config.targets);
+    } catch {
+      continue;
+    }
+
+    if (!declared.includes(input.target)) found.push({ profile: name, declares: declared });
+  }
+
+  return found;
+}
+
+/** The refusal, as a block, so the wording is testable without a deploy. */
+export function unservableRefusal(found: readonly Unservable[], target: string): string {
+  const rows = found
+    .map((one) => `        ${one.profile}   declares: ${one.declares.join(', ') || 'nothing'}`)
+    .join('\n');
+
+  return (
+    `${found.length} profile${found.length === 1 ? '' : 's'} would be uploaded that cannot run on "${target}":\n` +
+    `${rows}\n\n` +
+    '      The endpoint opens every profile in the bucket with this target, so the\n' +
+    '      revision would come up and refuse to start.\n' +
+    `        lanes link profile add <name> --target ${target}   declares it on a new one\n` +
+    '        --profile <name>                          deploys just the one'
+  );
+}

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.'
+  );
+}