@lanes-sh/link 0.1.0

package/src/deployments/gcp/driver.ts

@@ -0,0 +1,175 @@
+import type {
+  CommandResult,
+  DeployDriver,
+  DeployStep,
+  PlanInput,
+  ProvisionInput,
+  SurveyInput,
+  SurveyResult,
+} from '../driver.ts';
+import type { DeployConfig } from '#profile';
+import { encodeRef } from '../adapters/gcp-secret-manager.ts';
+import {
+  captureGcloud,
+  gcloudPath,
+  requireProject,
+  runGcloud,
+  serviceUrl,
+  type CloudRunTarget,
+} from './gcloud.ts';
+import { provisionSteps } from './provision.ts';
+import { surveyCloudRun } from './survey.ts';
+
+/**
+ * Cloud Run.
+ *
+ * Everything Google-specific about deploying lives behind this object: the argv
+ * `gcloud` wants, the shape of an Artifact Registry reference, and the fact that
+ * a Cloud Run URL has to be asked for rather than constructed. The generic
+ * command in `../deploy.ts` knows none of it.
+ *
+ * Config travels one way — from the CLI into an image — and a deployed instance
+ * never mutates its own configuration and exposes no admin API. That is ADR-007
+ * extended to the deployment, and it is why this builds an image rather than
+ * pushing config to a running service.
+ */
+
+/** Where the image lives. Artifact Registry, one repository per project. */
+export function imageReference(cloudrun: CloudRunTarget, tag: string): string {
+  return `${cloudrun.region}-docker.pkg.dev/${cloudrun.project}/lanes-link/${cloudrun.service}:${tag}`;
+}
+
+/**
+ * The commands a deploy runs, as data.
+ *
+ * Separated from running them so `--dry-run` shows exactly what will happen and
+ * so the argv construction is testable without a Google Cloud project. Every
+ * value is a separate argv element; nothing is interpolated into a shell.
+ */
+export function deployPlan(input: PlanInput): DeployStep[] {
+  const cloudrun = requireProject(input.deploy, input.target);
+  const image = imageReference(cloudrun, input.tag);
+  const scope = ['--project', cloudrun.project, '--region', cloudrun.region];
+
+  return [
+    {
+      title: 'ensure the Artifact Registry repository exists',
+      argv: [
+        'artifacts',
+        'repositories',
+        'create',
+        'lanes-link',
+        '--repository-format',
+        'docker',
+        '--location',
+        cloudrun.region,
+        '--project',
+        cloudrun.project,
+        '--description',
+        'Lanes Link images',
+      ],
+      // Second and subsequent deploys: already there, and that is the success
+      // case rather than a failure worth stopping for.
+      tolerateFailure: true,
+    },
+    {
+      title: 'build and push the image',
+      argv: [
+        'builds',
+        'submit',
+        '--project',
+        cloudrun.project,
+        '--config',
+        'src/deployments/gcp/cloudbuild.yaml',
+        '--substitutions',
+        `_IMAGE=${image}`,
+        '.',
+      ],
+    },
+    {
+      title: 'roll a revision',
+      argv: [
+        'run',
+        'deploy',
+        cloudrun.service,
+        ...scope,
+        '--image',
+        image,
+        '--platform',
+        'managed',
+        '--port',
+        '8080',
+        // The container reads these; everything else it needs is baked in.
+        '--set-env-vars',
+        [
+          `LANES_LINK_TARGET=${input.target}`,
+          ...(input.profile ? [`LANES_LINK_PROFILE=${input.profile}`] : []),
+          ...(input.workspace ? [`LANES_LINK_HOME=${input.workspace}`] : []),
+        ].join(','),
+        ...secretMounts(input.secretEnv),
+        ...(cloudrun.service_account ? ['--service-account', cloudrun.service_account] : []),
+        // `iam` is Cloud Run's own identity check, which admits only a caller
+        // holding a Google-signed identity token for this service. No agent
+        // harness can mint one — so a target reached by a remote MCP client
+        // declares `public` and gates the request in the application instead.
+        cloudrun.access === 'iam' ? '--no-allow-unauthenticated' : '--allow-unauthenticated',
+      ],
+    },
+  ];
+}
+
+/**
+ * Environment the revision reads out of Secret Manager, as `--set-secrets`.
+ *
+ * The value never travels: Cloud Run is told a secret id and resolves it at
+ * instance start, as the runtime service account, so the key stays out of the
+ * argv this prints, out of the revision's stored description, and out of
+ * anything `gcloud run services describe` returns.
+ *
+ * The `/` → `__` encoding is the credential adapter's, applied here rather than
+ * duplicated: `vault/key` is the secret `vault__key`, and a driver that spelled
+ * that itself would drift from the store that writes it.
+ */
+function secretMounts(secretEnv: PlanInput['secretEnv']): string[] {
+  const entries = Object.entries(secretEnv ?? {});
+  if (entries.length === 0) return [];
+
+  return [
+    '--set-secrets',
+    entries.map(([variable, ref]) => `${variable}=${encodeRef(ref)}:latest`).join(','),
+  ];
+}
+
+export const cloudRunDriver: DeployDriver = {
+  platform: 'cloudrun',
+  tool: 'gcloud',
+
+  preflight() {
+    // A property of *this* deployment, not of deployments generally — which is
+    // why it is asked here rather than by the generic command.
+    return gcloudPath()
+      ? null
+      : 'gcloud is not on your PATH. Install the Google Cloud CLI, run `gcloud auth login`, ' +
+          'and try again — or use --dry-run to see the commands and run them yourself.';
+  },
+
+  survey(input: SurveyInput): Promise<SurveyResult> {
+    return surveyCloudRun(input);
+  },
+
+  provision(input: ProvisionInput): Promise<DeployStep[]> {
+    return provisionSteps(input);
+  },
+
+  plan: deployPlan,
+
+  url(deploy: DeployConfig): Promise<string | null> {
+    // `outputs` calls this for any deployable target and must degrade rather
+    // than throw: gcloud may be absent and the service may not exist yet.
+    return deploy.project ? serviceUrl(deploy as CloudRunTarget) : Promise.resolve(null);
+  },
+
+  run(argv: readonly string[], options?: { quiet?: boolean }): Promise<CommandResult> {
+    return options?.quiet === true ? captureGcloud(argv) : runGcloud(argv);
+  },
+};

package/src/deployments/gcp/gcloud.ts

@@ -0,0 +1,178 @@
+import { ConfigError, type DeployConfig } from '#profile';
+import type { CommandResult } from '../driver.ts';
+
+/**
+ * Shelling out to `gcloud`.
+ *
+ * `lanes link deploy` is a thin wrapper, not a deployment engine (`docs/detailed/init.md`), and
+ * the thinnest correct wrapper drives the tool the operator already has
+ * authenticated. Reimplementing Cloud Build and the Cloud Run Admin API over
+ * REST would mean owning an OAuth flow, a long-running-operation poller, and a
+ * revision spec — for a command whose entire job is "build this, roll that".
+ *
+ * The commands are constructed as argv arrays and never as shell strings, so a
+ * project or service name cannot become an argument to something else.
+ */
+
+export function gcloudPath(): string | null {
+  return Bun.which('gcloud');
+}
+
+/**
+ * Run a `gcloud` invocation, streaming its output to the terminal.
+ *
+ * Streamed rather than captured because a build takes minutes and silence for
+ * the duration is indistinguishable from a hang.
+ *
+ * stderr is streamed *and* kept. It used to be inherited outright, which meant
+ * a failed step reached the caller as a bare exit code — and "should this be
+ * retried" is a question about the message, not the code. A freshly enabled API
+ * and a genuinely missing permission both exit 1 and say different things.
+ *
+ * Only the tail is kept. A build streams its entire log here, and no amount of
+ * it beyond the end explains an exit code.
+ */
+const KEPT_STDERR = 8192;
+
+export async function runGcloud(argv: readonly string[]): Promise<CommandResult> {
+  const gcloud = gcloudPath();
+  if (!gcloud) {
+    return {
+      ok: false,
+      stdout: '',
+      stderr:
+        'gcloud is not on your PATH. Install the Google Cloud CLI and run `gcloud auth login`.',
+    };
+  }
+
+  const child = Bun.spawn([gcloud, ...argv], { stdout: 'inherit', stderr: 'pipe' });
+
+  let captured = '';
+  const decoder = new TextDecoder();
+  const reader = (child.stderr as ReadableStream<Uint8Array>).getReader();
+
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    // Written through as it arrives, so a long build reads exactly as it did
+    // when this was inherited.
+    const text = decoder.decode(value, { stream: true });
+    process.stderr.write(text);
+    captured = (captured + text).slice(-KEPT_STDERR);
+  }
+
+  const code = await child.exited;
+  return { ok: code === 0, stdout: '', stderr: captured };
+}
+
+/** Run a `gcloud` invocation for its output, without printing it. */
+export async function captureGcloud(argv: readonly string[]): Promise<CommandResult> {
+  const gcloud = gcloudPath();
+  if (!gcloud) {
+    return { ok: false, stdout: '', stderr: 'gcloud is not on your PATH.' };
+  }
+
+  const child = Bun.spawn([gcloud, ...argv], { stdout: 'pipe', stderr: 'pipe' });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  return { ok: code === 0, stdout: stdout.trim(), stderr: stderr.trim() };
+}
+
+/**
+ * A deploy block that has the field Cloud Run cannot do without.
+ *
+ * `project` is optional in the schema because it means nothing to a platform
+ * without projects, on the same reasoning as `credentials.project` — so the
+ * driver that needs it is the thing that refuses without it, and says which
+ * platform is asking.
+ */
+export interface CloudRunTarget extends DeployConfig {
+  readonly project: string;
+}
+
+export function requireProject(deploy: DeployConfig, target: string): CloudRunTarget {
+  if (!deploy.project) {
+    throw new ConfigError(
+      `targets.${target}.deploy.project is required for the cloudrun platform — ` +
+        'a Cloud Run service is addressed by project, region, and name.',
+    );
+  }
+  return { ...deploy, project: deploy.project };
+}
+
+/**
+ * The public URL Cloud Run assigned this service, or null if it has none yet.
+ *
+ * The URL is not derivable from the service name — Cloud Run mixes in a
+ * project-specific hash — so it has to be asked for rather than constructed.
+ */
+export async function serviceUrl(target: CloudRunTarget): Promise<string | null> {
+  const result = await captureGcloud([
+    'run',
+    'services',
+    'describe',
+    target.service,
+    '--project',
+    target.project,
+    '--region',
+    target.region,
+    '--format',
+    'value(status.url)',
+  ]);
+
+  return result.ok && result.stdout ? result.stdout : null;
+}
+
+/** The project `gcloud` is currently pointed at, if any — a survey default. */
+export async function activeProject(): Promise<string | null> {
+  const result = await captureGcloud(['config', 'get-value', 'project']);
+  const value = result.stdout.trim();
+  return result.ok && value && value !== '(unset)' ? value : null;
+}
+
+/**
+ * Whether a project id is already somebody's.
+ *
+ * Asked so the survey knows whether it is naming an existing project or one it
+ * has to create — which decides whether it needs a billing account at all.
+ * A project id that exists but belongs to someone else answers the same as one
+ * of yours, which is the right answer here: either way this deploy will not be
+ * creating it.
+ */
+export async function projectExists(project: string): Promise<boolean> {
+  const result = await captureGcloud(['projects', 'describe', project, '--format', 'value(projectId)']);
+  return result.ok && result.stdout.trim() === project;
+}
+
+/**
+ * Billing accounts this login can attach a project to.
+ *
+ * Only open ones: a closed account lists, links, and then fails every API
+ * enable behind it with a message about the API rather than about billing.
+ */
+export async function openBillingAccounts(): Promise<{ id: string; name: string }[]> {
+  const result = await captureGcloud([
+    'billing',
+    'accounts',
+    'list',
+    '--filter',
+    'open=true',
+    '--format',
+    'value(name,displayName)',
+  ]);
+  if (!result.ok) return [];
+
+  return result.stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [id = '', ...rest] = line.split(/\s+/);
+      return { id: id.replace(/^billingAccounts\//, ''), name: rest.join(' ') || id };
+    })
+    .filter((account) => account.id.length > 0);
+}

package/src/deployments/gcp/provision.ts

@@ -0,0 +1,290 @@
+import { VAULT_DOCUMENT_REF } from '#secrets';
+import type { DeployStep, ProvisionInput } from '../driver.ts';
+import { encodeRef } from '../adapters/gcp-secret-manager.ts';
+import { requireProject } from './gcloud.ts';
+
+/**
+ * The project-level things a Cloud Run deploy needs to already exist.
+ *
+ * These used to be a numbered list in `docs/detailed/deployment-cloudrun.md` that the
+ * operator worked through by hand before their first deploy could get past its
+ * first step. Everything here is derivable from what the target already
+ * declares, so asking someone to transcribe it into a console was work with no
+ * decision in it.
+ *
+ * Returned as steps rather than run, like the rollout itself, so `--dry-run`
+ * shows the whole first-run sequence and so this is testable without a project.
+ * Every one tolerates failure: the second deploy finds all of them present, and
+ * `ALREADY_EXISTS` is the success case.
+ */
+
+/**
+ * Enabled together, in one call.
+ *
+ * Cloud Build is not optional even though nothing here names it after the build
+ * step: `gcloud builds submit` fails with a permission error rather than a
+ * "not enabled" one, which reads as a broken account.
+ *
+ * The last two are for the steps *below this one*, and they were missing. Every
+ * step here tolerates failure, so `iam.service-accounts create` and
+ * `projects add-iam-policy-binding` against a project without them failed
+ * silently — the deploy carried on, rolled a revision with no service account
+ * and no binding, and the first symptom was the revision failing to read a
+ * secret several minutes later. An API a later step needs belongs in the call
+ * that enables APIs.
+ */
+const REQUIRED_SERVICES = [
+  'run.googleapis.com',
+  'cloudbuild.googleapis.com',
+  'artifactregistry.googleapis.com',
+  'secretmanager.googleapis.com',
+  'storage.googleapis.com',
+  'iam.googleapis.com',
+  'cloudresourcemanager.googleapis.com',
+];
+
+export function provisionSteps(input: ProvisionInput): Promise<DeployStep[]> {
+  const cloudrun = requireProject(input.deploy, input.target);
+  const { project, region, service_account: serviceAccount } = cloudrun;
+  const steps: DeployStep[] = [];
+
+  // Before everything, when the survey found no project by this name.
+  //
+  // `billing_account` is only written for a project that did not exist, so its
+  // presence is the record of "this deploy owns creating it". Linking billing is
+  // not optional and not deferrable: a project without it enables no API, and
+  // every step below would fail describing the API rather than the billing.
+  if (cloudrun.billing_account) {
+    steps.push({
+      title: `create the project ${project}`,
+      argv: ['projects', 'create', project],
+      tolerateFailure: true,
+    });
+
+    steps.push({
+      title: `attach it to billing account ${cloudrun.billing_account}`,
+      argv: [
+        'billing',
+        'projects',
+        'link',
+        project,
+        '--billing-account',
+        cloudrun.billing_account,
+      ],
+      tolerateFailure: true,
+    });
+  }
+
+  steps.push({
+    title: `enable the APIs this deploy uses (${REQUIRED_SERVICES.length})`,
+    argv: ['services', 'enable', ...REQUIRED_SERVICES, '--project', project],
+    tolerateFailure: true,
+  });
+
+  if (serviceAccount) {
+    // The local part of the address is the account id gcloud wants; passing the
+    // whole address creates `foo@bar.iam...@project.iam...`, which then fails
+    // every binding below with a name that looks almost right.
+    const accountId = serviceAccount.split('@')[0] || `${cloudrun.service}-run`;
+
+    steps.push({
+      title: `create the runtime service account ${accountId}`,
+      argv: [
+        'iam',
+        'service-accounts',
+        'create',
+        accountId,
+        '--project',
+        project,
+        '--display-name',
+        `Lanes Link (${cloudrun.service})`,
+      ],
+      tolerateFailure: true,
+    });
+
+    // Read, named one secret at a time, for the same reason the write side is:
+    // a resource-level grant needs no condition to be scoped.
+    //
+    // This was a project-wide `secretAccessor`. The adapter argued for it and
+    // the argument was half right — the line worth defending really is
+    // `secrets.create`, which stays with the operator — but project-wide read
+    // is broader than a revision ever uses, and `askProject` is happy to point
+    // a deploy at a project that already holds other things. An SSRF in the
+    // endpoint should reach this profile's credentials, not everything sharing
+    // a project with it.
+    //
+    // Affordable because the serving path reads by explicit ref: `list()` is a
+    // CLI call, and `secretAccessor` never carried `secrets.list` anyway.
+    // `readableRefs` derives the set from config and manifests at deploy time.
+    for (const ref of input.readable ?? []) {
+      steps.push({
+        title: `let the revision read ${ref}`,
+        argv: [
+          'secrets',
+          'add-iam-policy-binding',
+          encodeRef(ref),
+          '--project',
+          project,
+          '--member',
+          `serviceAccount:${serviceAccount}`,
+          '--role',
+          'roles/secretmanager.secretAccessor',
+          // Bindings are printed as the whole policy otherwise, which is pages
+          // of YAML per deploy and buries everything after it.
+          '--condition',
+          'None',
+        ],
+        tolerateFailure: true,
+      });
+    }
+  }
+
+  // What a revision rewrites in its own credential store, named one secret at a
+  // time. Two kinds, and they arrive from different places:
+  //
+  //   - the vault document, because `vault.put` is a capability an agent may
+  //     hold under policy (ADR-022);
+  //   - each connection's OAuth token, because a refresh persists and serving a
+  //     request is what triggers it (ADR-026).
+  //
+  // The second was missing, and the shape of the miss is worth keeping in mind:
+  // nothing here was wrong, it was incomplete, and being incomplete looked
+  // exactly like being finished. Reading mail 403'd an hour after every deploy.
+  //
+  // Two steps each, and the first is what keeps the second narrow: the secret is
+  // created here so the revision only ever needs to *add a version*, never
+  // `secrets.create`, which is a project-level permission that would let it mint
+  // credential refs of its own. The binding is on the one secret, so it needs no
+  // condition to be scoped — a resource-level grant already is.
+  const writable = serviceAccount
+    ? [
+        ...(input.declared.vault?.adapter === 'secret'
+          ? [input.declared.vault.ref ?? VAULT_DOCUMENT_REF]
+          : []),
+        ...(input.rotatable ?? []),
+      ]
+    : [];
+
+  for (const ref of writable) {
+    const id = encodeRef(ref);
+
+    steps.push({
+      title: `create the secret ${id}, so the revision never needs secrets.create`,
+      argv: ['secrets', 'create', id, '--project', project, '--replication-policy', 'automatic'],
+      tolerateFailure: true,
+    });
+
+    steps.push({
+      title: `let the revision rewrite ${ref}, and nothing else in the store`,
+      argv: [
+        'secrets',
+        'add-iam-policy-binding',
+        id,
+        '--project',
+        project,
+        '--member',
+        `serviceAccount:${serviceAccount}`,
+        '--role',
+        'roles/secretmanager.secretVersionAdder',
+        '--condition',
+        'None',
+      ],
+      tolerateFailure: true,
+    });
+  }
+
+  // Any target that addresses a bucket, which deployed means all of them:
+  // config, state, the log, memory, skills and attachments are all objects in
+  // it, and it is the only stateful thing a deployment has besides Secret
+  // Manager. A target on the filesystem adapter has no bucket, and creating
+  // one it will never open would be a resource nobody asked for and nobody
+  // deletes.
+  const usesBucket =
+    input.declared.storage.adapter === 'gcs' || input.declared.storage.adapter === 's3';
+  const bucket = usesBucket ? input.declared.storage.bucket : undefined;
+  if (bucket) {
+    steps.push({
+      title: `create the bucket gs://${bucket}`,
+      argv: [
+        'storage',
+        'buckets',
+        'create',
+        `gs://${bucket}`,
+        '--project',
+        project,
+        '--location',
+        region,
+        // Blobs here are read and written by one instance at a time and never
+        // served publicly; uniform access removes per-object ACLs as a way to
+        // get that wrong.
+        '--uniform-bucket-level-access',
+      ],
+      tolerateFailure: true,
+    });
+
+    if (serviceAccount) {
+      // Two conditioned bindings rather than one blanket objectAdmin, because
+      // the bucket now holds the config as well as the data.
+      //
+      // ADR-007 says a deployed instance never mutates its own configuration.
+      // That used to be enforced by the image being read-only, which stopped
+      // being true when the workspace moved into the bucket (ADR-023). This is
+      // where the guarantee went: the revision may write what it owns and may
+      // only read what declares what it is.
+      const objectsUnder = (path: string): string =>
+        `resource.name.startsWith("projects/_/buckets/${bucket}/objects/${path}")`;
+      const objectIs = (path: string): string =>
+        `resource.name == "projects/_/buckets/${bucket}/objects/${path}"`;
+
+      // A provider manifest is configuration that happens to live inside the
+      // profile's directory (ADR-030), so `data/` alone no longer separates
+      // what the revision owns from what declares what it is. Anchored to the
+      // profile segment rather than matched loosely: `contains("/providers.d/")`
+      // would also catch a blob whose own key happened to spell it.
+      const providerManifests =
+        `resource.name.matches("^projects/_/buckets/${bucket}/objects/data/[^/]+/providers\\.d/")`;
+
+      steps.push({
+        title: 'let the revision write its own data, but not the manifests in it',
+        argv: [
+          'storage',
+          'buckets',
+          'add-iam-policy-binding',
+          `gs://${bucket}`,
+          '--member',
+          `serviceAccount:${serviceAccount}`,
+          // objectAdmin, not objectViewer: state, the log, attachments, memory
+          // and skills are all written by the running endpoint.
+          '--role',
+          'roles/storage.objectAdmin',
+          '--condition',
+          `title=owns-its-data,expression=${objectsUnder('data/')} && !${providerManifests}`,
+        ],
+        tolerateFailure: true,
+      });
+
+      steps.push({
+        title: 'let the revision read its config, and only read it',
+        argv: [
+          'storage',
+          'buckets',
+          'add-iam-policy-binding',
+          `gs://${bucket}`,
+          '--member',
+          `serviceAccount:${serviceAccount}`,
+          '--role',
+          'roles/storage.objectViewer',
+          // `expression=true` was here, which is every object in the bucket —
+          // the step title and ADR-023 both claim a narrowing this did not do.
+          // The config the revision reads is the workspace file, the profiles
+          // beside it, and each profile's own manifests, so name exactly those.
+          '--condition',
+          `title=reads-its-config,expression=${objectsUnder('profiles/')} || ${objectIs('lanes-link.yaml')} || ${providerManifests}`,
+        ],
+        tolerateFailure: true,
+      });
+    }
+  }
+
+  return Promise.resolve(steps);
+}