Deploy option to enable continuous deployment

docs/deploying.md

@@ -36,19 +36,21 @@ npm run deploy -- --help
 
 </div>
 
-## Automated deploys
+## Continuous deployment
 
-After deploying an app manually at least once, Observable can handle subsequent deploys for you automatically. You can automate deploys both [on commit](https://observablehq.com/documentation/data-apps/github) (whenever you push a new commit to your project’s default branch) and [on schedule](https://observablehq.com/documentation/data-apps/schedules) (such as daily or weekly).
+### Cloud builds
 
-Automatic deploys — also called _continuous deployment_ or _CD_ — ensure that your data is always up to date, and that any changes you make to your app are immediately reflected in the deployed version.
+Connect your app to Observable to handle deploys automatically. You can automate deploys both [on commit](https://observablehq.com/documentation/data-apps/github) (whenever you push a new commit to your project’s default branch) and [on schedule](https://observablehq.com/documentation/data-apps/schedules) (such as daily or weekly).
+
+Continuous deployment (for short, _CD_) ensures that your data is always up to date, and that any changes you make to your app are immediately reflected in the deployed version.
 
 On your app settings page on Observable, open the **Build settings** tab to set up a link to a GitHub repository hosting your project’s files. Observable will then listen for changes in the repo and deploy the app automatically.
 
-The settings page also allows you to trigger a manual deploy on Observable Cloud, add secrets (for data loaders to use private APIs and passwords), view logs, configure sharing, _etc._ For details, see the [Building & deploying](https://observablehq.com/documentation/data-apps/deploys) documentation.
+The settings page also allows you to trigger a manual deploy, add secrets for data loaders to use private APIs and passwords, view logs, configure sharing, _etc._ For details, see the [Building & deploying](https://observablehq.com/documentation/data-apps/deploys) documentation.
 
-## GitHub Actions
+### GitHub Actions
 
-As an alternative to building on Observable Cloud, you can use [GitHub Actions](https://github.com/features/actions) and have GitHub build a new version of your app and deploy it to Observable. In your git repository, create and commit a file at `.github/workflows/deploy.yml`. Here is a starting example:
+Alternatively, you can use [GitHub Actions](https://github.com/features/actions) to have GitHub build a new version of your app and deploy it to Observable. In your git repository, create and commit a file at `.github/workflows/deploy.yml`. Here is a starting example:
 
 ```yaml
 name: Deploy
@@ -88,7 +90,7 @@ To create an API key:
 
 1. Open the [API Key settings](https://observablehq.com/select-workspace?next=api-keys-settings) for your Observable workspace.
 2. Click **New API Key**.
-3. Check the **Deploy new versions of projects** checkbox. <!-- TODO apps -->
+3. Check the **Deploy new versions of data apps** checkbox.
 4. Give your key a description, such as “Deploy via GitHub Actions”.
 5. Click **Create API Key**.
 
@@ -137,6 +139,8 @@ This uses one cache per calendar day (in the `America/Los_Angeles` time zone). I
 
 <div class="note">You’ll need to edit the paths above if you’ve configured a source root other than <code>src</code>.</div>
 
+<div class="tip">Caching is limited for now to manual builds and GitHub Actions. In the future, it will be available as a configuration option for Observable Cloud builds.</div>
+
 ## Deploy configuration
 
 The deploy command creates a file at <code>.observablehq/deploy.json</code> under the source root (typically <code>src</code>) with information on where to deploy the app. This file allows you to re-deploy an app without having to repeat where you want the app to live on Observable.
@@ -147,7 +151,8 @@ The contents of the deploy config file look like this:
 {
   "projectId": "0123456789abcdef",
   "projectSlug": "hello-framework",
-  "workspaceLogin": "acme"
+  "workspaceLogin": "acme",
+  "continuousDeployment": true
 }
 ```
 

src/deploy.ts

@@ -1,7 +1,10 @@
+import {exec} from "node:child_process";
 import {createHash} from "node:crypto";
 import type {Stats} from "node:fs";
+import {existsSync} from "node:fs";
 import {readFile, stat} from "node:fs/promises";
 import {join} from "node:path/posix";
+import {promisify} from "node:util";
 import slugify from "@sindresorhus/slugify";
 import wrapAnsi from "wrap-ansi";
 import type {BuildEffects, BuildManifest, BuildOptions} from "./build.js";
@@ -15,7 +18,7 @@ import {visitFiles} from "./files.js";
 import type {Logger} from "./logger.js";
 import type {AuthEffects} from "./observableApiAuth.js";
 import {defaultEffects as defaultAuthEffects, formatUser, loginInner, validWorkspaces} from "./observableApiAuth.js";
-import {ObservableApiClient} from "./observableApiClient.js";
+import {ObservableApiClient, getObservableUiOrigin} from "./observableApiClient.js";
 import type {
   DeployManifestFile,
   GetCurrentUserResponse,
@@ -33,6 +36,26 @@ const DEPLOY_POLL_MAX_MS = 1000 * 60 * 5;
 const DEPLOY_POLL_INTERVAL_MS = 1000 * 5;
 const BUILD_AGE_WARNING_MS = 1000 * 60 * 5;
 
+const OBSERVABLE_UI_ORIGIN = getObservableUiOrigin();
+
+function settingsUrl(deployTarget: DeployTargetInfo) {
+  if (deployTarget.create) throw new Error("Incorrect deploy target state");
+  return `${OBSERVABLE_UI_ORIGIN}projects/@${deployTarget.workspace.login}/${deployTarget.project.slug}`;
+}
+
+/**
+ * Returns the ownerName and repoName of the first GitHub remote (HTTPS or SSH)
+ * on the current repository. Supports both https and ssh URLs:
+ * - https://github.com/observablehq/framework.git
+ * - git@github.com:observablehq/framework.git
+ */
+async function getGitHubRemote(): Promise<{ownerName: string; repoName: string} | undefined> {
+  const firstRemote = (await promisify(exec)("git remote -v")).stdout.match(
+    /^\S+\s(https:\/\/github.com\/|git@github.com:)(?<ownerName>[^/]+)\/(?<repoName>[^/]*?)(\.git)?\s/m
+  );
+  return firstRemote?.groups as {ownerName: string; repoName: string} | undefined;
+}
+
 export interface DeployOptions {
   config: Config;
   deployConfigPath: string | undefined;
@@ -84,7 +107,7 @@ type DeployTargetInfo =
   | {create: true; workspace: {id: string; login: string}; projectSlug: string; title: string; accessLevel: string}
   | {create: false; workspace: {id: string; login: string}; project: GetProjectResponse};
 
-/** Deploy a project to ObservableHQ */
+/** Deploy a project to Observable */
 export async function deploy(deployOptions: DeployOptions, effects = defaultEffects): Promise<void> {
   Telemetry.record({event: "deploy", step: "start", force: deployOptions.force});
   effects.clack.intro(`${inverse(" observable deploy ")} ${faint(`v${process.env.npm_package_version}`)}`);
@@ -180,24 +203,145 @@ class Deployer {
     const {deployId} = this.deployOptions;
     if (!deployId) throw new Error("invalid deploy options");
     await this.checkDeployCreated(deployId);
+    await this.uploadFiles(deployId, await this.getBuildFilePaths());
+    await this.markDeployUploaded(deployId);
+    return await this.pollForProcessingCompletion(deployId);
+  }
 
-    const buildFilePaths = await this.getBuildFilePaths();
+  private async cloudBuild(deployTarget: DeployTargetInfo) {
+    if (deployTarget.create) throw new Error("Incorrect deploy target state");
+    const {deployPollInterval: pollInterval = DEPLOY_POLL_INTERVAL_MS} = this.deployOptions;
+    await this.apiClient.postProjectBuild(deployTarget.project.id);
+    const spinner = this.effects.clack.spinner();
+    spinner.start("Requesting deploy");
+    const pollExpiration = Date.now() + DEPLOY_POLL_MAX_MS;
+    while (true) {
+      if (Date.now() > pollExpiration) {
+        spinner.stop("Requesting deploy timed out.");
+        throw new CliError("Requesting deploy failed");
+      }
+      const {latestCreatedDeployId} = await this.apiClient.getProject({
+        workspaceLogin: deployTarget.workspace.login,
+        projectSlug: deployTarget.project.slug
+      });
+      if (latestCreatedDeployId !== deployTarget.project.latestCreatedDeployId) {
+        spinner.stop(
+          `Deploy started. Watch logs: ${link(`${settingsUrl(deployTarget)}/deploys/${latestCreatedDeployId}`)}`
+        );
+        // latestCreatedDeployId is initially null for a new project, but once
+        // it changes to a string it can never change back; since we know it has
+        // changed, we assert here that it’s not null
+        return latestCreatedDeployId!;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+  }
 
-    await this.uploadFiles(deployId, buildFilePaths);
-    await this.markDeployUploaded(deployId);
-    const deployInfo = await this.pollForProcessingCompletion(deployId);
+  // Throws error if local and remote GitHub repos don’t match or are invalid.
+  // Ignores this.deployOptions.config.root as we only support cloud builds from
+  // the root directory.
+  private async validateGitHubLink(deployTarget: DeployTargetInfo): Promise<void> {
+    if (deployTarget.create) throw new Error("Incorrect deploy target state");
+    if (!deployTarget.project.build_environment_id) throw new CliError("No build environment configured.");
+    if (!existsSync(".git")) throw new CliError("Not at root of a git repository.");
+    const remote = await getGitHubRemote();
+    if (!remote) throw new CliError("No GitHub remote found.");
+    const branch = (await promisify(exec)("git rev-parse --abbrev-ref HEAD")).stdout.trim();
+    if (!branch) throw new Error("Branch not found.");
+
+    // If a source repository has already been configured, check that it’s
+    // accessible and matches the linked repository and branch. TODO: validate
+    // local/remote refs match, "Your branch is up to date", and "nothing to
+    // commit, working tree clean".
+    const {source} = deployTarget.project;
+    if (source) {
+      const linkedRepo = await this.apiClient.getGitHubRepository(remote);
+      if (linkedRepo) {
+        if (source.provider_id !== linkedRepo.provider_id) {
+          throw new CliError(
+            `Configured repository does not match local repository; check build settings on ${link(
+              `${settingsUrl(deployTarget)}/settings`
+            )}`
+          );
+        }
+        if (source.branch !== branch) {
+          // TODO: If source.branch is empty, it'll use the default repository
+          // branch (usually main or master), which we don't know from our current
+          // getGitHubRepository response, and thus can't check here.
+          throw new CliError(
+            `Configured branch ${source.branch} does not match local branch ${branch}; check build settings on ${link(
+              `${settingsUrl(deployTarget)}/settings`
+            )}`
+          );
+        }
+      }
 
-    return deployInfo;
+      if (!(await this.apiClient.getGitHubRepository({providerId: source.provider_id}))) {
+        // TODO: This could poll for auth too, but is a distinct case because it
+        // means the repo was linked at one point and then something went wrong
+        throw new CliError(
+          `Cannot access configured repository; check build settings on ${link(
+            `${settingsUrl(deployTarget)}/settings`
+          )}`
+        );
+      }
+
+      // Configured repo is OK; proceed
+      return;
+    }
+
+    // If the source has not been configured, first check that the remote repo
+    // is linked in CD settings. If not, prompt the user to auth & link.
+    let linkedRepo = await this.apiClient.getGitHubRepository(remote);
+    if (!linkedRepo) {
+      if (!this.effects.isTty)
+        throw new CliError(
+          "Cannot access repository for continuous deployment and cannot request access in non-interactive mode"
+        );
+
+      // Repo is not authorized; link to auth page and poll for auth
+      const authUrl = new URL("/auth-github", OBSERVABLE_UI_ORIGIN);
+      authUrl.searchParams.set("owner", remote.ownerName);
+      authUrl.searchParams.set("repo", remote.repoName);
+      this.effects.clack.log.info(
+        `Authorize Observable to access the ${bold(remote.repoName)} repository: ${link(authUrl)}`
+      );
+
+      const spinner = this.effects.clack.spinner();
+      spinner.start("Waiting for authorization");
+      const {deployPollInterval: pollInterval = DEPLOY_POLL_INTERVAL_MS} = this.deployOptions;
+      const pollExpiration = Date.now() + DEPLOY_POLL_MAX_MS;
+      do {
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        if (Date.now() > pollExpiration) {
+          spinner.stop("Authorization timed out.");
+          throw new CliError("Repository authorization failed");
+        }
+      } while (!(linkedRepo = await this.apiClient.getGitHubRepository(remote)));
+      spinner.stop("Repository authorized.");
+    }
+
+    // Save the linked repo as the configured source.
+    const {provider, provider_id, url} = linkedRepo;
+    await this.apiClient
+      .postProjectEnvironment(deployTarget.project.id, {source: {provider, provider_id, url, branch}})
+      .catch((error) => {
+        throw new CliError("Setting source repository for continuous deployment failed", {cause: error});
+      });
   }
 
   private async startNewDeploy(): Promise<GetDeployResponse> {
-    const deployConfig = await this.getUpdatedDeployConfig();
-    const deployTarget = await this.getDeployTarget(deployConfig);
-    const buildFilePaths = await this.getBuildFilePaths();
-    const deployId = await this.createNewDeploy(deployTarget);
-
-    await this.uploadFiles(deployId, buildFilePaths);
-    await this.markDeployUploaded(deployId);
+    const {deployConfig, deployTarget} = await this.getDeployTarget(await this.getUpdatedDeployConfig());
+    let deployId: string;
+    if (deployConfig.continuousDeployment) {
+      await this.validateGitHubLink(deployTarget);
+      deployId = await this.cloudBuild(deployTarget);
+    } else {
+      const buildFilePaths = await this.getBuildFilePaths();
+      deployId = await this.createNewDeploy(deployTarget);
+      await this.uploadFiles(deployId, buildFilePaths);
+      await this.markDeployUploaded(deployId);
+    }
     return await this.pollForProcessingCompletion(deployId);
   }
 
@@ -210,11 +354,7 @@ class Deployer {
       }
       return deployInfo;
     } catch (error) {
-      if (isHttpError(error)) {
-        throw new CliError(`Deploy ${deployId} not found.`, {
-          cause: error
-        });
-      }
+      if (isHttpError(error)) throw new CliError(`Deploy ${deployId} not found.`, {cause: error});
       throw error;
     }
   }
@@ -274,7 +414,9 @@ class Deployer {
   }
 
   // Get the deploy target, prompting the user as needed.
-  private async getDeployTarget(deployConfig: DeployConfig): Promise<DeployTargetInfo> {
+  private async getDeployTarget(
+    deployConfig: DeployConfig
+  ): Promise<{deployTarget: DeployTargetInfo; deployConfig: DeployConfig}> {
     let deployTarget: DeployTargetInfo;
     if (deployConfig.workspaceLogin && deployConfig.projectSlug) {
       try {
@@ -384,18 +526,37 @@ class Deployer {
       }
     }
 
+    let {continuousDeployment} = deployConfig;
+    if (continuousDeployment === null) {
+      const enable = await this.effects.clack.confirm({
+        message: wrapAnsi(
+          `Do you want to enable continuous deployment? ${faint(
+            "Given a GitHub repository, this builds in the cloud and redeploys whenever you push to the current branch."
+          )}`,
+          this.effects.outputColumns
+        ),
+        active: "Yes, enable and build in cloud",
+        inactive: "No, build locally"
+      });
+      if (this.effects.clack.isCancel(enable)) throw new CliError("User canceled deploy", {print: false, exitCode: 0});
+      continuousDeployment = enable;
+    }
+
+    deployConfig = {
+      projectId: deployTarget.project.id,
+      projectSlug: deployTarget.project.slug,
+      workspaceLogin: deployTarget.workspace.login,
+      continuousDeployment
+    };
+
     await this.effects.setDeployConfig(
       this.deployOptions.config.root,
       this.deployOptions.deployConfigPath,
-      {
-        projectId: deployTarget.project.id,
-        projectSlug: deployTarget.project.slug,
-        workspaceLogin: deployTarget.workspace.login
-      },
+      deployConfig,
       this.effects
     );
 
-    return deployTarget;
+    return {deployConfig, deployTarget};
   }
 
   // Create the new deploy on the server.