@lanes-sh/link 0.1.0

package/src/cli/commands/profile/remove.ts

@@ -0,0 +1,315 @@
+import type { SecretStore } from '#secrets';
+import type { BlobStore } from '#stores/blobs';
+import {
+  ConfigError,
+  WORKSPACE_FILE,
+  readWorkspace,
+  readWorkspaceFile,
+  workspaceFiles,
+  workspacePath,
+  writeWorkspaceFile,
+} from '#profile';
+import { parseDocument } from 'yaml';
+import { rm } from 'node:fs/promises';
+import { terminalPrompter, type Prompter } from '../../prompt.ts';
+import { announce, emit, fail, ok, print, style } from '../../output.ts';
+import {
+  buildRegistryWithWorkspace,
+  openBlobStoreFor,
+  openSecretStoreFor,
+  resolveProfile,
+  type GlobalFlags,
+} from '../../runtime.ts';
+import { removalPlan, renderPlan, type RemovalItem, type RemovalPlan } from './removal.ts';
+
+/**
+ * Performing a removal, and being honest about the parts that did not happen.
+ *
+ * Best effort by choice: a target whose project has been deleted must not be
+ * able to strand a profile on the machine forever, so one refusal does not stop
+ * the rest. The price is real — a deletion that fails leaves a live credential
+ * behind — and everything here exists to make that visible rather than quiet.
+ */
+
+export interface RemovalResult {
+  readonly item: RemovalItem;
+  /** `kept` is deliberate: not attempted, because something before it failed. */
+  readonly status: 'removed' | 'failed' | 'kept';
+  readonly error?: string;
+  /** The exact command that finishes this one by hand. */
+  readonly retry?: string;
+}
+
+export interface RemovalOutcome {
+  readonly profile: string;
+  readonly results: readonly RemovalResult[];
+  /** How many items are still there. Non-zero means a credential is still live. */
+  readonly survived: number;
+}
+
+export interface RunDeps {
+  openSecrets: (target: string) => Promise<SecretStore>;
+  openBlobs: (target: string, area?: string) => Promise<BlobStore>;
+  removeConfig: (path: string) => Promise<void>;
+  /** The emptied profile directory. A blob delete cannot remove a directory. */
+  removeDirectory: (path: string) => Promise<void>;
+  clearDefaultProfile: () => Promise<void>;
+  retry?: ((item: RemovalItem, cause: string) => string | undefined) | undefined;
+}
+
+const reason = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause));
+
+/** The items that only make sense once everything else is actually gone. */
+const isRecordOfWhereThingsAre = (item: RemovalItem): boolean =>
+  item.target === null && (item.kind === 'config' || item.kind === 'workspace-key');
+
+export async function executeRemoval(
+  plan: RemovalPlan,
+  deps: RunDeps,
+): Promise<RemovalOutcome> {
+  const results: RemovalResult[] = [];
+  let failed = 0;
+
+  // One store per target, however many items it holds. Opening a Secret
+  // Manager client per secret would turn a tidy removal into a rate limit.
+  const secrets = new Map<string, Promise<SecretStore>>();
+  const blobs = new Map<string, Promise<BlobStore>>();
+
+  const secretStore = (target: string): Promise<SecretStore> => {
+    const existing = secrets.get(target) ?? deps.openSecrets(target);
+    secrets.set(target, existing);
+    return existing;
+  };
+
+  const blobStore = (target: string, area?: string): Promise<BlobStore> => {
+    const key = `${target}:${area ?? ''}`;
+    const existing = blobs.get(key) ?? deps.openBlobs(target, area);
+    blobs.set(key, existing);
+    return existing;
+  };
+
+  for (const item of plan.items) {
+    // The config is the only record of where everything else lives. Deleting it
+    // after a failure would strand precisely the credential that failed: still
+    // live, and nothing left that knows where it is. Keeping it means the retry
+    // is this same command rather than a hand-assembled console session.
+    if (failed > 0 && isRecordOfWhereThingsAre(item)) {
+      results.push({ item, status: 'kept' });
+      continue;
+    }
+
+    try {
+      switch (item.kind) {
+        case 'secret':
+          await (await secretStore(item.target!)).delete(item.id);
+          break;
+
+        case 'blob':
+          await (await blobStore(item.target!)).delete(item.id);
+          break;
+
+        case 'config':
+          if (item.target === null) await deps.removeConfig(item.id);
+          else {
+            // `profiles/<name>.yaml` in the target's bucket — outside the
+            // profile's blob tree, so it needs its own area.
+            const [area, ...rest] = item.id.split('/');
+            await (await blobStore(item.target, area)).delete(rest.join('/'));
+          }
+          break;
+
+        case 'workspace-key':
+          await deps.clearDefaultProfile();
+          break;
+
+        case 'file':
+          await deps.removeDirectory(item.id);
+          break;
+      }
+
+      results.push({ item, status: 'removed' });
+    } catch (cause) {
+      const error = reason(cause);
+      const retry = deps.retry?.(item, error);
+      failed += 1;
+      results.push({ item, status: 'failed', error, ...(retry ? { retry } : {}) });
+    }
+  }
+
+  return {
+    profile: plan.profile,
+    results,
+    survived: results.filter((result) => result.status !== 'removed').length,
+  };
+}
+
+/**
+ * What happened, and what is still out there.
+ *
+ * The exit code is the load-bearing part. Best effort means the command can
+ * finish having left a live credential behind, and to a script silence is
+ * indistinguishable from success — so anything that survived makes this exit
+ * non-zero, and names itself with the command that finishes it.
+ */
+export function renderOutcome(outcome: RemovalOutcome): void {
+  const removed = outcome.results.filter((result) => result.status === 'removed');
+  const failed = outcome.results.filter((result) => result.status === 'failed');
+  const kept = outcome.results.filter((result) => result.status === 'kept');
+
+  print();
+  if (outcome.survived === 0) {
+    print(ok(`Removed profile ${style.bold(outcome.profile)} — ${removed.length} item(s).`));
+    print();
+    return;
+  }
+
+  print(
+    fail(
+      `Removed ${removed.length} item(s) of profile ${style.bold(outcome.profile)}, and ${failed.length} refused.`,
+    ),
+  );
+  print();
+
+  for (const result of failed) {
+    print(`  ${result.item.id}`);
+    if (result.error) print(style.dim(`    ${result.error}`));
+    if (result.retry) print(style.dim(`    finish it with: ${result.retry}`));
+  }
+  print();
+
+  if (kept.length > 0) {
+    // Said plainly, because the alternative reading — that the profile is
+    // half-gone and needs unpicking by hand — is the one an operator will
+    // assume from a failure report.
+    print(
+      `The profile's config was kept, so nothing is stranded: fix the above and run the same command again.`,
+    );
+    print();
+  }
+
+  // A live credential left behind must not look like success to a script.
+  process.exitCode = 1;
+}
+
+/**
+ * The confirmation, which asks for the name rather than a keystroke.
+ *
+ * A step up from `agreed()`, deliberately. That helper is `y/N` and is right
+ * for `vault remove`, which drops one item the operator can put back. This
+ * drops every live OAuth refresh token a profile holds, and putting those back
+ * means visiting each vendor again — so the gesture should be one you cannot
+ * make by leaning on the keyboard.
+ *
+ * Local rather than shared for the same reason it is not `agreed()`: the shape
+ * differs, and bending the existing helper for a single caller in another
+ * command folder would leave both worse. If a second consumer appears, promote
+ * it then.
+ */
+export async function confirmedByName(
+  profile: string,
+  options: { yes?: boolean | undefined; prompter?: Prompter | undefined },
+): Promise<boolean> {
+  if (options.yes) return true;
+
+  // A prompter that was passed in is the caller's answer to "is there anyone
+  // to ask" — the console passes one that replays a form. Only the default
+  // needs stdin consulted, and conflating the two makes an injected prompter
+  // untestable and a real terminal the only place this works.
+  const prompter = options.prompter ?? terminalPrompter;
+  const someoneToAsk = options.prompter ? prompter.interactive : process.stdin.isTTY;
+
+  if (!someoneToAsk) {
+    throw new ConfigError(
+      `Removing "${profile}" cannot be undone, and stdin is not a terminal, so there is nobody to ask. Pass --yes to proceed.`,
+    );
+  }
+
+  const typed = (await prompter.ask(`Type ${profile} to remove it, or anything else to stop: `))
+    .trim();
+
+  if (typed !== profile) {
+    print(style.dim('  cancelled — nothing was removed'));
+    return false;
+  }
+  return true;
+}
+
+export interface RemoveFlags extends GlobalFlags {
+  readonly dryRun?: boolean | undefined;
+  readonly yes?: boolean | undefined;
+  readonly json?: boolean | undefined;
+  /** Injected by a caller that has already asked — the console, and tests. */
+  readonly prompter?: Prompter | undefined;
+}
+
+/**
+ * `lanes link profile remove <name>` — the profile, and everything it owns.
+ *
+ * Deliberately not reachable from MCP. This writes credentials and mutates
+ * config, which ADR-007 keeps CLI-only, and it is the most destructive thing
+ * in the tool.
+ */
+export async function removeProfile(name: string, flags: RemoveFlags): Promise<void> {
+  const { resolution, config } = await resolveProfile({ ...flags, profile: name });
+  announce(resolution);
+
+  const root = resolution.workspaceRoot;
+  const registry = await buildRegistryWithWorkspace(root, name);
+  const files = workspaceFiles(root);
+
+  const plan = await removalPlan(config, root, name, registry, {
+    target: flags.target,
+    openSecrets: (target) => openSecretStoreFor(config, root, target),
+    openBlobs: (target, area) => openBlobStoreFor(config, root, target, area),
+    readDefaultProfile: async () => (await readWorkspace(root))?.default_profile,
+  });
+
+  renderPlan(plan);
+
+  if (flags.dryRun) {
+    print(style.dim('  --dry-run: nothing was removed, and no store was written to.'));
+    print();
+    return emit(flags.json, plan, () => {});
+  }
+
+  if (!(await confirmedByName(name, { yes: flags.yes, prompter: flags.prompter }))) return;
+
+  const outcome = await executeRemoval(plan, {
+    openSecrets: (target) => openSecretStoreFor(config, root, target),
+    openBlobs: (target, area) => openBlobStoreFor(config, root, target, area),
+    removeConfig: async (path) => await files.delete(relativeToRoot(root, path)),
+    removeDirectory: async (path) => await rm(workspacePath(root, path), { recursive: true, force: true }),
+    clearDefaultProfile: async () => await clearDefault(root),
+    retry: retryCommand,
+  });
+
+  return emit(flags.json, outcome, () => renderOutcome(outcome));
+}
+
+/** `profiles/<name>.yaml`, however the path was spelled for display. */
+function relativeToRoot(root: string, path: string): string {
+  const at = path.indexOf('profiles/');
+  return at === -1 ? path.replace(`${root}/`, '') : path.slice(at);
+}
+
+/**
+ * Clear the key, never repoint it.
+ *
+ * Choosing a new default on the operator's behalf would silently change what
+ * every other command in that workspace acts on — the one thing a removal
+ * should not decide for them.
+ */
+async function clearDefault(root: string): Promise<void> {
+  const text = await readWorkspaceFile(workspaceFiles(root), WORKSPACE_FILE);
+  if (text === null) return;
+
+  const document = parseDocument(text);
+  document.delete('default_profile');
+  await writeWorkspaceFile(workspaceFiles(root), WORKSPACE_FILE, String(document));
+}
+
+/** The command that finishes a refusal by hand, where one can be named. */
+function retryCommand(item: RemovalItem): string | undefined {
+  if (item.kind !== 'secret') return undefined;
+  return `lanes link profile remove <name> --target ${item.target} # or delete ${item.id} in that store`;
+}

package/src/cli/commands/profile.ts

@@ -0,0 +1,156 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseDocument } from 'yaml';
+import {
+  WORKSPACE_FILE,
+  listProfiles,
+  profilePath,
+  readWorkspace,
+  resolveWorkspaceRoot,
+} from '#profile';
+import { newProfileTemplate, newWorkspaceTemplate } from '../config-edit.ts';
+import { emit, ok, print, style, table } from '../output.ts';
+
+/**
+ * Profile management.
+ *
+ * One profile = one config = one instance = one endpoint. Profiles never share
+ * a database, a credential store, or a URL, so each new one gets its own port
+ * by default — running personal and work side by side is the normal case, not
+ * an advanced one.
+ *
+ * Each command is a data function plus a printing wrapper. The split exists
+ * because `--json` needs the facts without the rendering, which is the same
+ * reason `startEndpoint` takes an `EndpointReporter` — a caller that is not a
+ * terminal should not have to parse one.
+ */
+
+const FIRST_PORT = 7337;
+
+export interface ProfileCreated {
+  readonly name: string;
+  readonly path: string;
+  readonly port: number;
+  readonly isDefault: boolean;
+}
+
+export interface ProfileListing {
+  readonly root: string;
+  readonly default: string | undefined;
+  readonly profiles: ReadonlyArray<{ readonly name: string; readonly path: string }>;
+}
+
+/** Write a new profile, and the workspace file if this is the first one. */
+export async function createProfile(
+  name: string,
+  options: { default?: boolean },
+): Promise<ProfileCreated> {
+  const root = resolveWorkspaceRoot();
+  const path = profilePath(root, name);
+
+  if (existsSync(path)) throw new Error(`Profile "${name}" already exists at ${path}`);
+
+  await mkdir(join(root, 'profiles'), { recursive: true });
+
+  // Each profile gets its own port so two can serve at once without an
+  // operator having to think about it.
+  const existing = await listProfiles(root);
+  const port = FIRST_PORT + existing.length;
+
+  const workspaceFile = join(root, WORKSPACE_FILE);
+  const isFirst = existing.length === 0;
+  const isDefault = options.default === true || isFirst;
+
+  if (!existsSync(workspaceFile)) {
+    await writeFile(workspaceFile, newWorkspaceTemplate(isDefault ? name : undefined), {
+      mode: 0o600,
+    });
+  } else if (options.default) {
+    const document = parseDocument(await Bun.file(workspaceFile).text());
+    document.set('default_profile', name);
+    await writeFile(workspaceFile, document.toString({ lineWidth: 0 }), { mode: 0o600 });
+  }
+
+  await writeFile(path, newProfileTemplate(name, port), { mode: 0o600 });
+
+  return { name, path, port, isDefault };
+}
+
+/**
+ * Every profile in the workspace, and which one is the default.
+ *
+ * Names and paths only — deliberately not each profile's port, which would mean
+ * parsing every config. One unparseable profile would then fail the command
+ * that tells you which profiles exist, and that is exactly when you need it.
+ * `status --json` reports the endpoint for a profile you have named.
+ */
+export async function readProfiles(): Promise<ProfileListing> {
+  const root = resolveWorkspaceRoot();
+  const profiles = await listProfiles(root);
+  const workspace = await readWorkspace(root);
+
+  return {
+    root,
+    default: workspace?.default_profile,
+    profiles: profiles.map((name) => ({ name, path: profilePath(root, name) })),
+  };
+}
+
+export async function profileAdd(
+  name: string,
+  options: { default?: boolean; json?: boolean },
+): Promise<void> {
+  const created = await createProfile(name, options);
+
+  return emit(options.json, created, () => {
+    print(ok(`created profile ${style.bold(created.name)}`));
+    print(`      config  ${created.path}`);
+    print(`      port    ${created.port}`);
+    if (created.isDefault) print(`      set as the workspace default`);
+    print();
+    print(
+      style.dim('Next: lanes link connect example    # add a connection, no credentials needed'),
+    );
+  });
+}
+
+export async function profileList(options: { json?: boolean } = {}): Promise<void> {
+  const listing = await readProfiles();
+
+  return emit(options.json, listing, () => {
+    if (listing.profiles.length === 0) {
+      print(style.dim(`No profiles in ${listing.root}.`));
+      print(style.dim('Create one with: lanes link profile add personal --default'));
+      return;
+    }
+
+    print(style.dim(listing.root));
+    table(
+      listing.profiles.map((profile) => [
+        profile.name === listing.default ? style.green('*') : ' ',
+        style.bold(profile.name),
+        style.dim(profile.path),
+      ]),
+    );
+  });
+}
+
+export async function profileDefault(name: string): Promise<void> {
+  const root = resolveWorkspaceRoot();
+  if (!existsSync(profilePath(root, name))) throw new Error(`Profile "${name}" does not exist`);
+
+  const workspaceFile = join(root, WORKSPACE_FILE);
+  const document = existsSync(workspaceFile)
+    ? parseDocument(await Bun.file(workspaceFile).text())
+    : parseDocument(newWorkspaceTemplate());
+
+  document.set('default_profile', name);
+  await writeFile(workspaceFile, document.toString({ lineWidth: 0 }), { mode: 0o600 });
+
+  print(ok(`default profile is now ${style.bold(name)}`));
+}
+
+// The bundled agent skill used to be printed from here, because `installRoot`
+// was already imported for it. It belongs with the other documents this CLI
+// ships to a client — see `commands/mcp/assets.ts`.

package/src/cli/commands/secrets.ts

@@ -0,0 +1,176 @@
+import { ConfigError } from '#profile';
+import { assertValidSecretRef } from '#secrets';
+import { announce, heading, ok, print, style } from '../output.ts';
+import { openSecretStoreFor, resolveProfile, type GlobalFlags } from '../runtime.ts';
+
+/**
+ * `lanes link secrets` — moving credential values between a profile's targets.
+ *
+ * Credentials follow the target, because each target has its own credential
+ * store: `lanes link connect gmail.side --target cloud` writes the refresh token into
+ * Secret Manager, and the same command with `--target local` writes it into
+ * the encrypted file. That is the right default and it leaves one gap, which
+ * this command fills — a setup built locally first, and now wanted in the
+ * cloud, without re-running every OAuth flow.
+ *
+ * Every operation here is control plane: it writes credential values, so it is
+ * CLI-only by design and has no MCP surface (ADR-007). Values are never
+ * printed, never passed on argv where they would land in shell history, and
+ * never logged — only reference names appear.
+ */
+
+export interface SecretsFlags extends GlobalFlags {
+  readonly from?: string | undefined;
+  readonly to?: string | undefined;
+  /** Replace a reference that already exists in the destination. */
+  readonly overwrite?: boolean | undefined;
+  readonly dryRun?: boolean | undefined;
+}
+
+export async function secretsPush(flags: SecretsFlags): Promise<void> {
+  if (!flags.from || !flags.to) {
+    throw new ConfigError('Usage: lanes link secrets push --from <target> --to <target>');
+  }
+  if (flags.from === flags.to) {
+    throw new ConfigError(`--from and --to are both "${flags.from}"; there is nothing to copy.`);
+  }
+
+  const { resolution, config } = await resolveProfile(flags);
+  announce(resolution);
+
+  const source = await openSecretStoreFor(config, resolution.workspaceRoot, flags.from);
+  const destination = await openSecretStoreFor(config, resolution.workspaceRoot, flags.to);
+
+  const refs = await source.list();
+  if (refs.length === 0) {
+    print(style.dim(`No credentials in target "${flags.from}".`));
+    return;
+  }
+
+  heading(`${flags.from} → ${flags.to}`);
+
+  // Only asked when it can change the answer: against Secret Manager each of
+  // these is an API call, and `--overwrite` ignores the result anyway.
+  const existing = new Set<string>();
+  if (!flags.overwrite) {
+    for (const ref of refs) if (await destination.has(ref)) existing.add(ref);
+  }
+
+  const { copy, skip } = pushDecision({ refs, existing, overwrite: flags.overwrite === true });
+  const copied: string[] = [];
+  const skipped = [...skip];
+
+  for (const ref of copy) {
+    if (!flags.dryRun) {
+      const value = await source.get(ref);
+      // A ref that lists but does not read means the store changed underneath
+      // us. Skipping beats writing an empty string over a live credential.
+      if (value === null) {
+        skipped.push(ref);
+        continue;
+      }
+      await destination.set(ref, value);
+    }
+    copied.push(ref);
+  }
+
+  // Copy, never move. `connect` has a copy-then-delete helper for renaming a
+  // connection within one store; across targets both copies are wanted — the
+  // local one is what `lanes link start` still runs on.
+  for (const ref of copied) print(`  ${style.green('+')} ${ref}`);
+  for (const ref of skipped) print(`  ${style.dim('=')} ${style.dim(`${ref}  already present`)}`);
+
+  print('');
+  if (flags.dryRun) {
+    print(style.dim(`  --dry-run: ${copied.length} would be copied, ${skipped.length} skipped.`));
+    return;
+  }
+  print(ok(`copied ${copied.length}, skipped ${skipped.length}`));
+  if (skipped.length > 0 && !flags.overwrite) {
+    print(style.dim('  --overwrite replaces what is already there.'));
+  }
+  print(style.dim(`  The source target keeps its copy; nothing was deleted from "${flags.from}".`));
+}
+
+/**
+ * Store one value, read from stdin.
+ *
+ * Never from argv: an argument is in the shell history, in `ps` output while
+ * the process runs, and in any transcript of the session. The Postgres
+ * connection string is the reason this exists — the cloud target names it with
+ * `database.url_ref`, and it has to get into the store somehow.
+ */
+export async function secretsSet(ref: string | undefined, flags: GlobalFlags): Promise<void> {
+  if (!ref) {
+    throw new ConfigError(
+      'Usage: lanes link secrets set <ref>   (the value is read from stdin)\n' +
+        '  e.g. printf %s "$DATABASE_URL" | lanes link secrets set cloud/database_url --target cloud',
+    );
+  }
+  assertValidSecretRef(ref);
+
+  // Without this the command waits on a terminal that will never send
+  // anything, with no output to explain why — a hang, not an error.
+  if (process.stdin.isTTY) {
+    throw new ConfigError(
+      `lanes link secrets set reads the value from stdin, and stdin is a terminal.\n` +
+        `  printf %s "<value>" | lanes link secrets set ${ref}\n` +
+        '  Pass it this way rather than as an argument: an argument is in your shell history.',
+    );
+  }
+
+  const { resolution, config, target } = await resolveProfile(flags);
+  announce(resolution);
+
+  const value = (await Bun.stdin.text()).replace(/\n$/, '');
+  if (!value) {
+    throw new ConfigError(
+      `No value on stdin. Pipe one in: printf %s "<value>" | lanes link secrets set ${ref}`,
+    );
+  }
+
+  const credentials = await openSecretStoreFor(config, resolution.workspaceRoot, target);
+  const replacing = await credentials.has(ref);
+  await credentials.set(ref, value);
+
+  print(ok(`${replacing ? 'replaced' : 'stored'} ${style.bold(ref)} in target ${target}`));
+  if (replacing) {
+    print(style.dim('  Anything still using the old value will start failing.'));
+  }
+}
+
+export async function secretsList(flags: GlobalFlags): Promise<void> {
+  const { resolution, config, target } = await resolveProfile(flags);
+  announce(resolution);
+
+  const credentials = await openSecretStoreFor(config, resolution.workspaceRoot, target);
+  const refs = await credentials.list();
+
+  heading(`Credential references in target ${target} (${refs.length})`);
+  if (refs.length === 0) {
+    print(style.dim('  none'));
+  } else {
+    for (const ref of refs) print(`  ${ref}`);
+  }
+
+  // The interface has no operation that enumerates values, and this command is
+  // not going to become the first one.
+  print('');
+  print(style.dim('  Names only. There is no command that prints a stored credential value.'));
+}
+
+/** Which references a push copies and which it leaves alone. */
+export function pushDecision(input: {
+  readonly refs: readonly string[];
+  readonly existing: ReadonlySet<string>;
+  readonly overwrite: boolean;
+}): { copy: string[]; skip: string[] } {
+  const copy: string[] = [];
+  const skip: string[] = [];
+
+  for (const ref of input.refs) {
+    if (!input.overwrite && input.existing.has(ref)) skip.push(ref);
+    else copy.push(ref);
+  }
+  return { copy, skip };
+}