@lanes-sh/link 0.1.0

package/src/deployments/deploy.ts

@@ -0,0 +1,290 @@
+import { ConfigError, resolveDeployTarget, type DeployConfig } from '#profile';
+import { announce, fail, heading, ok, print, style, warn } from '#cli/output.ts';
+import { confirm, isInteractive } from '#cli/prompt.ts';
+import { openSecretStoreFor, resolveProfile, type GlobalFlags } from '#cli/runtime.ts';
+import { resolveTarget, vaultEnv } from './bootstrap.ts';
+import { printSteps, runSteps } from './steps.ts';
+import { driverFor } from './drivers.ts';
+import { prepareSecrets, readableRefs, rotatableRefs } from './prepare.ts';
+import { deployedWorkspace, repairSetupSurface, uploadWorkspace } from './upload.ts';
+
+/**
+ * `lanes link deploy` — set up what is missing, build the image, roll a revision,
+ * print the URL.
+ *
+ * A thin wrapper, deliberately. `docs/detailed/init.md` is explicit that this must not
+ * grow plan-and-apply state files, deploy leases, drift reconciliation, or a
+ * rollback manifest: revisions already are the rollback, and that machinery
+ * belongs to a multi-target org deployment tool rather than to a single-user
+ * instance. What is here is the ordered list of things that have to happen, the
+ * questions whose answers it cannot derive, and refusals early enough to be
+ * cheap.
+ *
+ * It knows no vendor. Which platform a target deploys to is a field in its
+ * config, and everything vendor-shaped behind `driverFor`.
+ */
+
+export interface DeployFlags extends GlobalFlags {
+  /** Print the commands and the checks without running any of them. */
+  readonly dryRun?: boolean | undefined;
+  /** Override the declared `access` for this run. */
+  readonly access?: string | undefined;
+  readonly serviceAccount?: string | undefined;
+  readonly tag?: string | undefined;
+  /** Skip the confirm before creating cloud resources. */
+  readonly yes?: boolean | undefined;
+  /**
+   * Never prompt: take the setup answers from the config and assume the confirm.
+   *
+   * Implied when stdin is not a terminal, so a scripted deploy needs no flag —
+   * this is for a terminal attached to a job nobody is watching.
+   */
+  readonly nonInteractive?: boolean | undefined;
+}
+
+export async function deploy(flags: DeployFlags): Promise<void> {
+  // The one command allowed to name a target that does not exist yet: creating
+  // it is what a first deploy is for.
+  const { resolution, config } = await resolveProfile(flags, { allowUndeclaredTarget: true });
+
+  // And the one command that can work out which target it meant. `resolveProfile`
+  // falls back to `instance.default_target`, which is the target commands *run*
+  // against — `local`, and never the answer to "deploy what".
+  const { target, source } = resolveDeployTarget(config, flags.target);
+  announce({ ...resolution, target, targetSource: source });
+
+  // `check` before anything external, per the gate order: a config that will be
+  // rejected on boot should be rejected here, not after a five-minute build.
+  print(ok(`${resolution.profilePath} is valid`));
+
+  const declared = await resolveTarget({
+    config,
+    profilePath: resolution.profilePath,
+    workspaceRoot: resolution.workspaceRoot,
+    profile: resolution.profile,
+    target,
+    flags,
+  });
+
+  const deployConfig = declared.deploy!;
+  const driver = await driverFor(deployConfig.platform);
+
+  const tag = flags.tag ?? new Date().toISOString().replace(/[^0-9]/g, '').slice(0, 14);
+
+  // Which credentials the revision will rewrite, so the steps below can grant
+  // each one. Scoped by `flags.profile` exactly as the upload and the repair
+  // below are, and read from config and manifests before anything opens a
+  // store — `--dry-run` must reach the printed step list without touching a
+  // credential.
+  const rotatable = await rotatableRefs(resolution.workspaceRoot, flags.profile);
+  const readable = await readableRefs(resolution.workspaceRoot, flags.profile, declared);
+  const provision = await driver.provision({
+    deploy: deployConfig,
+    declared,
+    target,
+    rotatable,
+    readable,
+  });
+
+  // Where the running instance will read its config. The bucket the target
+  // already declares for everything else — the workspace is not baked into the
+  // image any more (ADR-023), so this has to be passed at rollout.
+  const workspace = deployedWorkspace(declared);
+  const secretEnv = vaultEnv(declared);
+
+  const rollout = driver.plan({
+    deploy: deployConfig,
+    tag,
+    target,
+    ...(flags.profile !== undefined ? { profile: flags.profile } : {}),
+    ...(workspace !== undefined ? { workspace } : {}),
+    ...(secretEnv ? { secretEnv } : {}),
+  });
+
+  heading(
+    `Deploying ${style.bold(deployConfig.service)} to ${deployConfig.region}` +
+      (deployConfig.project ? ` (${deployConfig.project})` : ''),
+  );
+  print(style.dim(`  platform: ${deployConfig.platform}`));
+  print(reachability(deployConfig.access));
+
+  if (flags.dryRun) {
+    printSteps(driver, [...provision, ...rollout]);
+    print('');
+    if (workspace) print(style.dim(`  the workspace would be uploaded to ${workspace}`));
+    print(style.dim('  --dry-run: nothing was run, and no credential was read or written.'));
+    return;
+  }
+
+  const missing = driver.preflight();
+  if (missing) throw new ConfigError(missing);
+
+  // First, and before anything reaches for what they create.
+  //
+  // These used to run after the credential check and the workspace upload,
+  // which meant a genuinely first deploy asked Secret Manager for a token in a
+  // project where that API was not enabled yet, and wrote config into a bucket
+  // that did not exist — failing, both times, several steps before the step
+  // that would have fixed it. The ordering was invisible because the second
+  // deploy onwards finds everything present and works.
+  if (provision.length > 0) {
+    heading(`First-run setup (${provision.length} steps)`);
+    printSteps(driver, provision);
+    print('');
+    print(
+      style.dim(
+        '  Each of these already existing is the expected case on every deploy after\n' +
+          '  the first, and is not treated as a failure.',
+      ),
+    );
+    // `--non-interactive` assumes it: a confirm nobody can answer is a hang, and
+    // the same run already took its setup answers from the config rather than
+    // asking. `--yes` remains the way to skip it with a terminal attached.
+    const assumed = flags.yes === true || flags.nonInteractive === true || !isInteractive();
+    if (!assumed && !(await confirm('  Create these now?'))) {
+      throw new ConfigError('Stopped before creating anything. Nothing was changed.');
+    }
+    await runSteps(driver, provision);
+  }
+
+  const credentials = await openSecretStoreFor(config, resolution.workspaceRoot, target);
+  const prepared = await prepareSecrets({
+    config,
+    credentials,
+    root: resolution.workspaceRoot,
+    target,
+    readOnly: false,
+  });
+
+  if (prepared.blocking.length > 0) {
+    heading('Still missing');
+    for (const problem of prepared.blocking) print(fail(problem));
+    throw new ConfigError(
+      'The deployed instance cannot start without these. Store them with ' +
+        `lanes link secrets set <ref> --target ${target}, or copy a local setup with ` +
+        `lanes link secrets push --from local --to ${target}.`,
+    );
+  }
+
+  // Repair the local config before it is copied up, not the copy in the bucket.
+  //
+  // The bucket copy is the wrong end: config flows one way, local CLI to remote
+  // instance (ADR-023), and the deployed revision holds `objectViewer` on
+  // `profiles/` so it cannot write there anyway. Fixing the local file keeps
+  // the two agreeing, which is the property that makes the one-way flow safe.
+  //
+  // This is also the only place the gap gets noticed. `doctor` reports a
+  // profile with no `setup` connection, but the operator of a deployed endpoint
+  // has no reason to run it — and the symptom appears in a chat client, days
+  // later, as an agent guessing at a command that does not exist.
+  // Behind the same guard as the upload, and reading the same scope.
+  //
+  // The guard because a target with no bucket uploads nothing: repairing for it
+  // would rewrite the operator's config as a side effect of a command that
+  // copied their config nowhere. The shared scope because a profile that gets
+  // uploaded is a profile that gets served, and repairing a narrower set than
+  // the upload sends would leave a served profile without the surface — this
+  // bug again, one profile over.
+  if (workspace) {
+    await repairSetupSurface(resolution.workspaceRoot, flags.profile);
+
+    // Before the rollout, so the revision that comes up finds a config to read.
+    // Uploading after would leave a window where the service is serving and the
+    // workspace it was told to read is not there yet.
+    await uploadWorkspace(resolution.workspaceRoot, workspace, flags.profile);
+  }
+
+  heading('Rolling out');
+  await runSteps(driver, rollout);
+
+  const url = await driver.url(deployConfig);
+  if (!url) {
+    print(
+      warn(
+        `deployed, but the platform reported no URL yet — run: lanes link outputs --target ${target}`,
+      ),
+    );
+    return;
+  }
+
+  heading('Endpoint');
+  print(`  ${url}/mcp`);
+  print(await healthLine(url));
+  print('');
+  print(style.dim(`  Register it with: lanes link outputs --target ${target}`));
+
+  reportUnauthorised(prepared.warnings, target);
+}
+
+/**
+ * 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).
+ */
+function reportUnauthorised(warnings: readonly 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> --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.
+ */
+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. */
+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` 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/driver.ts

@@ -0,0 +1,157 @@
+import type { DeployConfig, TargetConfig } from '#profile';
+
+/**
+ * What a deployment has to be able to do to be rolled out.
+ *
+ * `lanes link deploy` used to *be* the Cloud Run driver — the CLI imported it by
+ * path, so the command's grammar was generic while its behaviour was one
+ * vendor's. This interface is the seam that makes the README's existing claim
+ * true: adding a host is a folder here and a case in `drivers.ts`, and nothing
+ * else in the codebase learns about it.
+ *
+ * Everything a driver produces is **data**, not effects. `plan` and `provision`
+ * return steps rather than running them, which is what lets `--dry-run` show a
+ * deploy exactly as it will happen, and what lets the argv be asserted in a test
+ * with no cloud project anywhere near it. `run` is the only method that touches
+ * the world, and it takes one already-built step.
+ */
+
+export interface CommandResult {
+  readonly ok: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export interface DeployStep {
+  readonly title: string;
+  /**
+   * Arguments to the driver's own tool, one element each.
+   *
+   * Never a shell string. A service name carrying whitespace and a flag has to
+   * arrive as one argument the tool rejects, not as an extra option it obeys.
+   */
+  readonly argv: readonly string[];
+  /** A step whose failure is expected when the thing already exists. */
+  readonly tolerateFailure?: boolean;
+}
+
+export interface PlanInput {
+  readonly deploy: DeployConfig;
+  readonly tag: string;
+  readonly target: string;
+  readonly profile?: string | undefined;
+  /**
+   * Where the running instance reads its config, as a store URL.
+   *
+   * Passed at rollout rather than baked into the image, because the bucket
+   * belongs to the operator and the image is meant to serve any workspace
+   * (ADR-023). Absent for a target that keeps its workspace on a filesystem,
+   * which no deployment does.
+   */
+  readonly workspace?: string | undefined;
+  /**
+   * Environment the revision must read from its own credential store, as
+   * variable name → credential reference.
+   *
+   * A reference rather than a value, and never a value: this argv is printed by
+   * `--dry-run`, echoed by the platform, and kept in a revision's description
+   * forever. The driver turns a reference into whatever its host calls a secret
+   * mount — which for Cloud Run means knowing the id encoding, and is why that
+   * translation lives behind this interface rather than in the generic command.
+   */
+  readonly secretEnv?: Readonly<Record<string, string>> | undefined;
+}
+
+export interface ProvisionInput {
+  readonly deploy: DeployConfig;
+  /** The whole target, because what needs creating follows from its adapters. */
+  readonly declared: TargetConfig;
+  readonly target: string;
+  /**
+   * Credential references the running revision rewrites, so provision can grant
+   * each one and leave the rest of the store read-only.
+   *
+   * Passed in rather than derived here: it comes from the profile's connections
+   * and their manifests, which `deployments` cannot reach on its own — see
+   * `rotatableRefs` in `./prepare.ts`.
+   */
+  readonly rotatable?: readonly string[];
+  /**
+   * Credential references the running revision reads, so provision can bind
+   * read on each one rather than across the whole project.
+   *
+   * Same provenance as `rotatable` and for the same reason — see `readableRefs`
+   * in `./prepare.ts`. Empty or absent means the project-wide fallback, which is
+   * what a target with no profile to walk still needs.
+   */
+  readonly readable?: readonly string[];
+}
+
+export interface SurveyInput {
+  /** Whatever the config already says, so a re-run confirms rather than re-asks. */
+  readonly current: Partial<DeployConfig>;
+  readonly profile: string;
+  /**
+   * Whether this profile gates requests itself.
+   *
+   * It decides which `access` to propose: a profile with its own gate wants the
+   * platform door open, because platform IAM in front of it admits only callers
+   * that can mint the host's identity token — which no agent harness can.
+   */
+  readonly gated: boolean;
+  /**
+   * Whether the target exists at all, or only its `deploy` block is missing.
+   *
+   * A target that is already declared has its adapters chosen; asking again
+   * would be offering to overwrite them. A target that does not exist needs all
+   * of it, and every answer but the bucket name follows from the platform.
+   */
+  readonly adapters: boolean;
+}
+
+/**
+ * A surveyed target, plus the profile-level settings its answers imply.
+ *
+ * `authorization` is separate because it does not live under `targets:` — it is
+ * `auth.authorization`, and it applies to every target. It comes back from here
+ * anyway because the question that decides it is a deployment question: whether
+ * a remote client has to reach this endpoint. Nothing else in the config knows
+ * to ask, which is why an endpoint that could not be added to a phone was the
+ * default outcome of a first deploy.
+ */
+export interface SurveyResult {
+  readonly target: TargetConfig;
+  readonly authorization?: { readonly mode: 'self' } | undefined;
+}
+
+export interface DeployDriver {
+  readonly platform: DeployConfig['platform'];
+  /** The command line this driver shells out to, for printing a plan. */
+  readonly tool: string;
+
+  /** What is missing before this driver can run anything, or null. */
+  preflight(): string | null;
+
+  /** Ask for what the config does not say yet. Interactive. */
+  survey(input: SurveyInput): Promise<SurveyResult>;
+
+  /** Resources this driver can create for itself, in the order they must happen. */
+  provision(input: ProvisionInput): Promise<DeployStep[]>;
+
+  /** The rollout itself. */
+  plan(input: PlanInput): DeployStep[];
+
+  /** The public URL, or null if the service has none yet. */
+  url(deploy: DeployConfig): Promise<string | null>;
+
+  /**
+   * Run one step's argv.
+   *
+   * Streamed by default, because a build takes minutes and silence for the
+   * duration is indistinguishable from a hang. `quiet` captures instead, for the
+   * short steps whose output is a wall of IAM policy nobody reads and whose
+   * failure is usually "already there" — the caller decides what to say about
+   * those rather than letting the tool say it.
+   */
+  run(argv: readonly string[], options?: { quiet?: boolean }): Promise<CommandResult>;
+}

package/src/deployments/drivers.ts

@@ -0,0 +1,35 @@
+import { ConfigError, type DeployConfig } from '#profile';
+import type { DeployDriver } from './driver.ts';
+
+/**
+ * Turning a declared platform into the driver that rolls it out.
+ *
+ * **This is the only place the mapping exists**, exactly as `target.ts` is the
+ * only place an adapter name becomes an open backend. Before this, the mapping
+ * was two static imports in the CLI — `#deployments/gcp/deploy.ts` in `main.ts`
+ * and `#deployments/gcp/gcloud.ts` in `outputs.ts` — which meant the CLI knew
+ * what Cloud Run was and a second host would have had to be threaded through
+ * both.
+ *
+ * The driver is imported *inside* its branch, for the same reason the cloud
+ * adapters are: a `lanes link outputs` against a local target must not load a
+ * cloud SDK, and a missing cloud credential must not fail a command that was
+ * never going to talk to that cloud.
+ */
+export async function driverFor(platform: DeployConfig['platform']): Promise<DeployDriver> {
+  switch (platform) {
+    case 'cloudrun': {
+      const { cloudRunDriver } = await import('./gcp/driver.ts');
+      return cloudRunDriver;
+    }
+  }
+
+  // Unreachable while `platform` is a closed enum, and kept anyway: the enum
+  // and this switch are edited by different hands at different times, and a
+  // platform that parses but does not dispatch should say so rather than
+  // return undefined into a call chain.
+  throw new ConfigError(
+    `No deployment driver for platform "${platform as string}". ` +
+      'Declare one of: cloudrun.',
+  );
+}

package/src/deployments/gcp/Dockerfile

@@ -0,0 +1,70 @@
+# syntax=docker/dockerfile:1
+#
+# The deployed target's image. Built from the repository root:
+#
+#   docker build -f src/deployments/gcp/Dockerfile -t lanes-link .
+#
+# `lanes link deploy` runs the equivalent through Cloud Build. See
+# docs/deployment-cloudrun.md for the whole loop, and for why the config is
+# baked in rather than mounted.
+#
+# There is no build step: Bun runs TypeScript directly, so the image holds
+# source, and `bun install` only fetches the third-party dependencies.
+
+FROM oven/bun:1.3.11-slim
+
+WORKDIR /app
+
+# The manifest first, so a source-only change reuses the install layer. One
+# package now, rather than fifteen manifests copied ahead of the install to
+# satisfy workspace resolution.
+COPY package.json bun.lock bunfig.toml ./
+
+RUN bun install --frozen-lockfile
+
+COPY src/ src/
+
+# The workspace is NOT copied in.
+#
+# It used to be: `COPY lanes-link.yaml` and `COPY profiles/`, on the reasoning
+# that the image *is* the config, so a revision fully described what it served
+# and rollback was a revision switch. The cost was a rebuild per config change,
+# which the comment here called "the tradeoff docs/init.md accepts until it
+# becomes annoying".
+#
+# It became annoying, and it had a second cost that was easier to miss: those
+# paths are gitignored, so the image could not be built from a clean checkout
+# at all. That is what stopped there ever being one image that serves any
+# workspace.
+#
+# Config now lives wherever LANES_LINK_HOME points — a bucket, for a
+# deployment — and `lanes link deploy` uploads it there. See ADR-023 for what
+# that gives up and how the guarantee it kept is kept.
+#
+# What must still NOT arrive here is `data/`: the encrypted credential store
+# and its key live there, and the deployed target reads credentials from Secret
+# Manager instead. The root `.dockerignore` excludes it, and that exclusion is
+# load bearing rather than an optimisation.
+
+# Set at deploy time, not here: a bucket URL is the operator's, not the image's.
+# `lanes link deploy` passes it as `LANES_LINK_HOME=gs://<bucket>`. Left unset,
+# `resolveWorkspaceRoot` would walk ancestors for `lanes-link.yaml` and fall
+# back to `~/.lanes-link`, which in a container is a directory nobody wrote —
+# so the endpoint refuses rather than serving an empty workspace.
+# Which adapter set to open. The whole point of the milestone is that this is
+# the only thing that differs from a local run.
+ENV LANES_LINK_TARGET=cloud
+# Cloud Run injects its own PORT; this is the default it also uses, so the
+# image is runnable unchanged with `docker run -p 8080:8080`.
+ENV PORT=8080
+
+# No `data/` directory: the container writes nothing to its own filesystem.
+# State, the log, memory, skills and attachments are all objects in the bucket,
+# and credentials come from Secret Manager. The image can run read-only.
+
+USER bun
+EXPOSE 8080
+
+# Not `lanes link start`: that command is a terminal UI that mints a token when
+# none exists. See the note at the top of src/server/container.ts.
+CMD ["bun", "run", "src/server/container.ts"]

package/src/deployments/gcp/cloudbuild.yaml

@@ -0,0 +1,31 @@
+# Cloud Build config for the deployed target's image.
+#
+# It exists so `gcloud builds submit` can name a Dockerfile that is not at the
+# context root — `--tag` alone always builds `./Dockerfile`, and moving the
+# Dockerfile to the repository root to satisfy that would put deployment
+# machinery in front of everyone who only ever runs locally.
+#
+# Invoked by `lanes link deploy`, which supplies _IMAGE:
+#
+#   gcloud builds submit \
+#     --config src/deployments/gcp/cloudbuild.yaml \
+#     --substitutions _IMAGE=<region>-docker.pkg.dev/<project>/lanes-link/<service>:<tag> .
+#
+# The build context is the repository root, and `.dockerignore` there decides
+# what reaches the builder. `data/` must not — see the note in that file.
+
+steps:
+  - name: gcr.io/cloud-builders/docker
+    args:
+      - build
+      - --file
+      - src/deployments/gcp/Dockerfile
+      - --tag
+      - ${_IMAGE}
+      - .
+
+images:
+  - ${_IMAGE}
+
+options:
+  logging: CLOUD_LOGGING_ONLY