@lanes-sh/link 0.1.0

package/src/cli/prompt.ts

@@ -0,0 +1,180 @@
+import { createInterface } from 'node:readline';
+import { style } from './output.ts';
+
+/**
+ * Interactive input.
+ *
+ * Secrets are read without echoing. That is not theatre: a client secret typed
+ * into a terminal ends up in scrollback, in a screen recording, and in whatever
+ * the terminal emulator persists between sessions.
+ */
+
+export class PromptCancelled extends Error {
+  constructor() {
+    super('Cancelled.');
+    this.name = 'PromptCancelled';
+  }
+}
+
+/**
+ * Whether there is anyone to answer.
+ *
+ * Exported so a command can *decide* rather than discover: `deploy` asks its
+ * setup questions every run, which is only the right default when a person is
+ * there. Piped into a script, the same run has to fall back to what the config
+ * already says instead of throwing at the first prompt.
+ */
+export function isInteractive(): boolean {
+  return process.stdin.isTTY === true;
+}
+
+function assertInteractive(): void {
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      'This command needs an interactive terminal to collect credentials. ' +
+        'For scripted setup, write the credentials to the store first and re-run.',
+    );
+  }
+}
+
+export async function ask(question: string): Promise<string> {
+  assertInteractive();
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise<string>((resolve, reject) => {
+      rl.question(`${question}: `, resolve);
+      rl.once('SIGINT', () => reject(new PromptCancelled()));
+    });
+    return answer.trim();
+  } finally {
+    rl.close();
+    // `close()` releases the interface but leaves stdin resumed and referenced,
+    // which keeps the event loop alive: the command finishes, prints, and then
+    // sits there until Ctrl-C. `askSecret` already pauses; this is the same
+    // cleanup for the same reason.
+    process.stdin.pause();
+  }
+}
+
+/**
+ * Read a line without echoing it.
+ *
+ * Raw mode rather than a muted writable stream: muting the output still lets
+ * the terminal's own line editing echo, which defeats the point on some
+ * emulators. Reading keystrokes directly is the only way to be sure nothing
+ * reaches the screen.
+ */
+export async function askSecret(question: string): Promise<string> {
+  assertInteractive();
+
+  process.stdout.write(`${question}: `);
+
+  const stdin = process.stdin;
+  const wasRaw = stdin.isRaw === true;
+  stdin.setRawMode(true);
+  stdin.resume();
+  stdin.setEncoding('utf8');
+
+  return new Promise<string>((resolve, reject) => {
+    let value = '';
+
+    const cleanup = (): void => {
+      stdin.removeListener('data', onData);
+      stdin.setRawMode(wasRaw);
+      stdin.pause();
+      process.stdout.write('\n');
+    };
+
+    const onData = (chunk: string): void => {
+      for (const char of chunk) {
+        switch (char) {
+          case '\r':
+          case '\n':
+            cleanup();
+            resolve(value.trim());
+            return;
+          case '': // Ctrl-C
+            cleanup();
+            reject(new PromptCancelled());
+            return;
+          case '': // backspace
+          case '\b':
+            value = value.slice(0, -1);
+            break;
+          default:
+            // Ignore other control characters rather than storing them.
+            if (char >= ' ') value += char;
+        }
+      }
+    };
+
+    stdin.on('data', onData);
+  });
+}
+
+export async function confirm(question: string, defaultYes = true): Promise<boolean> {
+  const answer = await ask(`${question} ${style.dim(defaultYes ? '[Y/n]' : '[y/N]')}`);
+  if (answer.length === 0) return defaultYes;
+  return /^y(es)?$/i.test(answer);
+}
+
+/**
+ * Where a command collects an answer from.
+ *
+ * The same seam as `EndpointReporter`, for the same reason: `connect` had one
+ * caller, a terminal, and the terminal was reached directly. An agent driving
+ * the CLI is a second caller, and it cannot answer a prompt — so the choice of
+ * where answers come from has to be the caller's rather than a module-level
+ * import of `process.stdin`.
+ *
+ * `interactive` is on the interface rather than inferred by callers, because
+ * the useful refusal message differs per question. A missing credential points
+ * at `secrets set`; a broad scope points at `--accept-broad-scopes`. Only the
+ * caller knows which, and a prompter that threw a generic error would bury it.
+ */
+export interface Prompter {
+  readonly interactive: boolean;
+  ask(question: string): Promise<string>;
+  askSecret(question: string): Promise<string>;
+  confirm(question: string, defaultYes?: boolean): Promise<boolean>;
+}
+
+/** Today's behaviour: a real terminal, refusing when there is not one. */
+export const terminalPrompter: Prompter = {
+  interactive: true,
+  ask,
+  askSecret,
+  confirm,
+};
+
+/**
+ * A prompter that answers nothing, and says what to do instead.
+ *
+ * It deliberately does not read flags, environment variables, or a file. A
+ * credential passed as an argument is in the shell history, in `ps` output
+ * while the process runs, and in any transcript of the session — which is why
+ * `secrets set` already refuses argv and reads stdin. Adding a second, weaker
+ * path here would contradict that rule one directory away, and an agent-typed
+ * flag lands in a transcript too.
+ *
+ * Reaching this at all means the preflight missed something: a non-interactive
+ * `connect` resolves every declared value before it starts. So the message
+ * names the command that lists them rather than guessing at the one value.
+ */
+export function nonInteractivePrompter(planCommand: string): Prompter {
+  const refuse = (question: string): never => {
+    throw new Error(
+      `Cannot ask for "${question.trim()}" — this run is non-interactive.\n` +
+        `  Store what this provider needs first, then re-run. To list it:\n` +
+        `    ${planCommand}`,
+    );
+  };
+
+  return {
+    interactive: false,
+    ask: async (question) => refuse(question),
+    askSecret: async (question) => refuse(question),
+    confirm: async (question) => refuse(question),
+  };
+}

package/src/cli/publish.ts

@@ -0,0 +1,185 @@
+import type { SecretStore } from '#secrets';
+import type { Config } from '#profile';
+import { publishWorkspace } from '#deployments/upload.ts';
+import { openSecretStoreFor, type Runtime } from './runtime.ts';
+import { endpointUrl } from './endpoint-url.ts';
+
+/**
+ * Getting an edit to the endpoint that has to serve it.
+ *
+ * A config edit used to reach a deployed endpoint by exactly one route: roll a
+ * new revision. That put "which accounts can this reach" on the same command as
+ * "what code does this run", and made connecting an account cost a Docker
+ * build. ADR-029 separates them — an edit publishes itself and says so, and
+ * `deploy` goes back to being about code.
+ *
+ * Two steps, and the second is allowed to fail. Publishing is what makes the
+ * change *durable* for the next instance to boot; notifying is what makes it
+ * visible to the one already running. An endpoint that is not up yet, is
+ * scaled to zero, or sits behind a network this machine cannot cross is not a
+ * failed edit — it will read the published config when it next starts. So a
+ * notify that cannot land is reported, never thrown.
+ */
+
+/** How long to wait for a running endpoint to answer. */
+const NOTIFY_TIMEOUT_MS = 10_000;
+
+export interface PublishOutcome {
+  /** Where the config was copied, when the target reads from a store. */
+  readonly published?: string;
+  /** Whether a running endpoint confirmed it is now serving the edit. */
+  readonly served: boolean;
+  /** The endpoint that was told, or would have been. */
+  readonly url?: string;
+  /** Why it is not being served yet, in a form fit to print. */
+  readonly reason?: string;
+}
+
+/**
+ * Copy the config where this target reads it, then tell it to re-read.
+ *
+ * The order is load-bearing: an endpoint told to reload before the config it
+ * should read has landed would reload the previous config and report success.
+ */
+export async function publishAndNotify(input: {
+  readonly config: Config;
+  readonly workspaceRoot: string;
+  readonly target: string;
+  readonly profile: string;
+  readonly credentials: SecretStore;
+}): Promise<PublishOutcome> {
+  let published: string | null = null;
+
+  try {
+    published = await publishWorkspace(input);
+  } catch (error) {
+    // The local edit already succeeded and is already on disk. What failed is
+    // getting it to the bucket, which means the *next* revision would not see
+    // it either — worth saying loudly, and not worth undoing the edit for.
+    return {
+      served: false,
+      reason: `could not publish the config to this target: ${message(error)}`,
+    };
+  }
+
+  const notified = await notifyReload(input);
+  return { ...(published ? { published } : {}), ...notified };
+}
+
+/** The same thing, for a command that already holds an open runtime. */
+export function publishRuntimeEdit(runtime: Runtime): Promise<PublishOutcome> {
+  return publishAndNotify({
+    config: runtime.config,
+    workspaceRoot: runtime.resolution.workspaceRoot,
+    target: runtime.target,
+    profile: runtime.resolution.profile,
+    credentials: runtime.credentials,
+  });
+}
+
+/**
+ * The same thing for a command that resolved a profile but opened no runtime.
+ *
+ * `policy allow` and `policy deny` edit the config without needing a registry,
+ * a dispatcher or a state handle — and a deny that a deployed endpoint has not
+ * heard about is the one kind of staleness worth being strict about, so they
+ * still have to publish. `openSecretStoreFor` is the cheap half of a runtime:
+ * the credential store alone, which is all the notify needs to authenticate.
+ */
+export async function publishProfileEdit(input: {
+  readonly resolution: { readonly workspaceRoot: string; readonly profile: string };
+  readonly config: Config;
+  readonly target: string;
+}): Promise<PublishOutcome> {
+  const credentials = await openSecretStoreFor(
+    input.config,
+    input.resolution.workspaceRoot,
+    input.target,
+  );
+
+  return publishAndNotify({
+    config: input.config,
+    workspaceRoot: input.resolution.workspaceRoot,
+    target: input.target,
+    profile: input.resolution.profile,
+    credentials,
+  });
+}
+
+/** Ask a running endpoint to re-read its config. Never throws. */
+async function notifyReload(input: {
+  readonly config: Config;
+  readonly target: string;
+  readonly credentials: SecretStore;
+}): Promise<PublishOutcome> {
+  let url: string;
+  try {
+    // Answers for a deployed target as well as a local one — a loopback URL
+    // sent to a deployment reaches a port with nothing behind it, which is the
+    // bug this function's own doc comment records.
+    url = (await endpointUrl(input.config, input.target)).replace(/\/mcp$/, '/reload');
+  } catch (error) {
+    return { served: false, reason: `could not work out where the endpoint is: ${message(error)}` };
+  }
+
+  const token = await input.credentials.get(input.config.auth.token_ref);
+  if (!token) {
+    return {
+      served: false,
+      url,
+      reason: `no profile token at "${input.config.auth.token_ref}" to authenticate with`,
+    };
+  }
+
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(NOTIFY_TIMEOUT_MS),
+    });
+
+    if (!response.ok) {
+      return { served: false, url, reason: `the endpoint answered ${response.status}` };
+    }
+
+    const body = (await response.json()) as { reloaded?: unknown; reason?: unknown };
+    if (body.reloaded !== true) {
+      return {
+        served: false,
+        url,
+        reason:
+          typeof body.reason === 'string'
+            ? `the endpoint could not reload: ${body.reason}`
+            : 'the endpoint did not reload',
+      };
+    }
+
+    return { served: true, url };
+  } catch {
+    // Nothing listening, scaled to zero, or unreachable from here — all of
+    // which resolve themselves the next time the endpoint starts, because the
+    // config it reads on the way up is the one just published.
+    return { served: false, url, reason: 'no endpoint answered' };
+  }
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? (error.message.split('\n')[0] ?? error.message) : String(error);
+}
+
+/**
+ * The line `connect` and friends print last.
+ *
+ * It used to be a guess derived from whether the target was deployable —
+ * "restart it" or "roll a revision" — because there was no way to know. There
+ * is now: the endpoint either answered or it did not.
+ */
+export function nextAfterEdit(outcome: PublishOutcome): string {
+  if (outcome.served) return 'Serving it now — the endpoint has re-read its config.';
+
+  // Naming the URL, because the likeliest reason nothing answered is that the
+  // endpoint is somewhere else: `lanes link start --port` moves the socket
+  // without moving `instance.port`, which is where this address comes from.
+  const where = outcome.url ? ` at ${outcome.url}` : '';
+  return `${outcome.reason ?? 'no endpoint answered'}${where} — saved, and the endpoint will serve this when it next starts.`;
+}

package/src/cli/runtime/discovery.ts

@@ -0,0 +1,123 @@
+import type { AnyConnector, DiscoveredCapability, ProviderManifest } from '#connectivity';
+import { createHttpConnector } from '#connectivity/transports';
+
+/**
+ * What it costs to ask a provider what it can do.
+ *
+ * Discovery is not one thing. For an `http` connector it is a pure function of
+ * an OpenAPI document committed to this repository — no token, no socket, and
+ * measured at 15ms for all seven Google providers together. For `mcp` it is a
+ * request. For `imap` and `dav` it is a TLS handshake and a login against a
+ * server that throttles exactly that.
+ *
+ * Startup re-derives the free ones and `doctor` reports on the rest, and both
+ * ask this module which is which. Two callers guessing separately at what a
+ * probe costs is how they drift — which is the bug this file exists to fix, one
+ * level up: `connect` was the only writer of the discovery cache, so a spec
+ * change landed in the repository and never reached the endpoint.
+ */
+
+export type ProbeCost =
+  /** Reads a committed document. Safe on the boot path. */
+  | 'offline'
+  /** One HTTP request to the upstream. */
+  | 'network'
+  /** Opens an authenticated session. Never on the boot path. */
+  | 'session';
+
+export interface DiscoveryProbe {
+  readonly cost: ProbeCost;
+  run(): Promise<readonly DiscoveredCapability[]>;
+}
+
+/**
+ * An `openapi` that names a document we ship, rather than one we fetch.
+ *
+ * Load-bearing, and the reason this is a check rather than an assumption about
+ * `kind === 'http'`: `providers/custom/template.ts` documents that a custom
+ * provider may point `openapi` at a URL. Re-deriving that at startup would put
+ * a network fetch on the boot path of every command, so those keep the cache.
+ */
+function isLocalDocument(openapi: string): boolean {
+  return !/^https?:\/\//i.test(openapi);
+}
+
+/**
+ * How to re-discover this provider, or `undefined` if it cannot be discovered.
+ *
+ * `connector` is only consulted for the kinds that need one — an `http`
+ * provider is probed straight from its manifest, so it does not need a
+ * connection to exist. That is what lets startup re-derive before any
+ * connection is read, and what makes the probe work when a token has expired.
+ */
+export function discoveryProbe(
+  manifest: ProviderManifest,
+  connector?: AnyConnector | undefined,
+): DiscoveryProbe | undefined {
+  const declared = manifest.connector;
+
+  // Authored capabilities are not discovered — they are the definition.
+  if (declared.kind === 'local') return undefined;
+
+  if (declared.kind === 'http' && isLocalDocument(declared.openapi)) {
+    return {
+      cost: 'offline',
+      run: () =>
+        createHttpConnector({
+          baseUrl: declared.base_url,
+          openapi: declared.openapi,
+          ...(declared.operations?.include?.length
+            ? { include: declared.operations.include }
+            : {}),
+          ...(declared.operations?.exclude?.length
+            ? { exclude: declared.operations.exclude }
+            : {}),
+        }).discover({ manifest }),
+    };
+  }
+
+  if (!connector) return undefined;
+
+  const cost: ProbeCost = declared.kind === 'imap' || declared.kind === 'dav' ? 'session' : 'network';
+  return { cost, run: () => connector.discover({ manifest }) };
+}
+
+/**
+ * One capability set against another, by name.
+ *
+ * `changed` is the case ADR-017 said `plan` structurally could not report — "it
+ * diffs capability names, and what changed here is a schema". A description or
+ * an input schema moving is exactly what a hint or a re-vendor does, and an
+ * operator who cannot see it has no way to know a restart is owed.
+ */
+export interface CapabilityDiff {
+  readonly added: readonly string[];
+  readonly removed: readonly string[];
+  readonly changed: readonly string[];
+}
+
+export function capabilityDiff(
+  before: readonly DiscoveredCapability[],
+  after: readonly DiscoveredCapability[],
+): CapabilityDiff {
+  const previous = new Map(before.map((capability) => [capability.name, capability]));
+  const next = new Map(after.map((capability) => [capability.name, capability]));
+
+  const added = [...next.keys()].filter((name) => !previous.has(name));
+  const removed = [...previous.keys()].filter((name) => !next.has(name));
+  const changed = [...next.keys()].filter((name) => {
+    const was = previous.get(name);
+    if (!was) return false;
+    const is = next.get(name)!;
+    return (
+      was.description !== is.description ||
+      JSON.stringify(was.inputSchema) !== JSON.stringify(is.inputSchema)
+    );
+  });
+
+  return { added, removed, changed };
+}
+
+export function isEmptyDiff(diff: CapabilityDiff): boolean {
+  return diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0;
+}