@samebase/alchemy-convex 0.25.0 → 0.26.0

package/src/SharedHubClient.ts

@@ -8,6 +8,11 @@
 // later deploy reads the client on the hub with that token (RFC 7592). The hub keeps only hashes, so
 // the state is the only record of the secret and the token.
 //
+// The answer to a production registration also holds the app's initial access token (RFC 7591
+// section 1.2) and the repository id. The state of stage `prod` keeps them. On a laptop,
+// `alchemy-convex hub-client --shared` reads that row with the Convex login of the team and asks the
+// hub for a development client with the token: see `registerSharedDevelopmentClient`.
+//
 // A push removes a variable that a deploy stops passing, so a failure here must not drop working
 // variables or stop the deploy. A renewal that fails keeps the saved values. Only a client that
 // cannot work asks for a new one: it is gone, or it has another return address. If that request
@@ -16,18 +21,37 @@
 // and the app hides the button for this client ID.
 //
 // No text in this file quotes an answer or a fetch error, so no log line can hold a secret.
+import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { Resource } from "alchemy";
 import { isResolved } from "alchemy/Diff";
 import * as Provider from "alchemy/Provider";
+import { reviveState } from "alchemy/State";
+import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
+import { DeploymentRow } from "./Deployment.ts";
+import { ManagementApi, type ManagementApiService } from "./ManagementApi.ts";
+import { findProjectByName, getProjectById, prodDeploymentOf } from "./Project.ts";
 import type { Providers } from "./Providers.ts";
+import { withPushKey } from "./Push.ts";
+import { makeFunctionApi, STORE_PROJECT_NAME } from "./State.ts";
 
 /** A hung service must not hold a deploy: the time limit of one request. */
 const REQUEST_TIMEOUT_MS = 30_000;
 
+/** The variables of a deployment without a hub client, as the starter writes them. */
+const OFF_VALUES = { issuer: "http://127.0.0.1:1", clientId: "no-hub", clientSecret: "no-hub" };
+
+/** The hub that a run asks, which is also its issuer. */
+const hubUrl = () => process.env["HUB_URL"] ?? "https://auth.samebase.com";
+
+/** Where a run asks for a new client. */
+const hubClientsUrl = () => `${hubUrl()}/hub-clients`;
+
 export interface SharedHubClientProps {
   /** The stable name of the app, set once in the stack. */
   readonly app: string;
@@ -56,6 +80,14 @@ export interface SharedHubClientAttributes {
   readonly deploymentType: "production" | "preview";
   /** The return address that the client serves. Empty for the off values. */
   readonly redirectUri: string;
+  /**
+   * Returned only at a production registration (RFC 7591 section 1.2). It registers development
+   * clients of this app, such as `alchemy-convex hub-client --shared` on a laptop. Empty for a
+   * preview and for the off values.
+   */
+  readonly initialAccessToken: Redacted.Redacted<string>;
+  /** The numeric GitHub id of the repository, with the initial access token. Empty without it. */
+  readonly repository: string;
 }
 
 export type SharedHubClient = Resource<
@@ -85,6 +117,9 @@ const NewClient = Schema.Struct({
   redirect_uri: Schema.NonEmptyString,
   /** The terms of the shared sign-in service, which the log shows once, for the new client. */
   terms: Schema.NonEmptyString,
+  /** Only in the answer to a production registration with the GitHub token. */
+  initial_access_token: Schema.optionalKey(Schema.NonEmptyString),
+  repository: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^\d+$/))),
 });
 
 /** The other answers of `POST /hub-clients`, by status. */
@@ -113,6 +148,7 @@ const NOT_ALLOWED = new Map([
   ],
   ["verification_file_invalid", "/samebase-verification.json on the host holds no repository id"],
   ["repository_mismatch", "/samebase-verification.json on the host names another repository"],
+  ["app_mismatch", "the initial access token belongs to another app on the identity hub"],
 ]);
 
 /** The windows of a 429, by the name that the answer gives. */
@@ -181,19 +217,14 @@ const readOidcToken = (requestUrl: string, requestToken: string) =>
 const requestNewClient = (props: SharedHubClientProps, requestUrl: string, requestToken: string) =>
   Effect.gen(function* () {
     const token = yield* readOidcToken(requestUrl, requestToken);
-    const { body, status } = yield* send(
-      "The identity hub",
-      `${process.env["HUB_URL"] ?? "https://auth.samebase.com"}/hub-clients`,
-      token,
-      {
-        method: "POST",
-        body: JSON.stringify({
-          app: props.app,
-          redirectUri: props.redirectUri,
-          softwareVersion: props.softwareVersion ?? "unknown",
-        }),
-      },
-    );
+    const { body, status } = yield* send("The identity hub", hubClientsUrl(), token, {
+      method: "POST",
+      body: JSON.stringify({
+        app: props.app,
+        redirectUri: props.redirectUri,
+        softwareVersion: props.softwareVersion ?? "unknown",
+      }),
+    });
     if (status !== 201) {
       return yield* new SharedHubClientFailed({
         reason: `${refusalOf(status, body)} (HTTP ${status})`,
@@ -212,6 +243,8 @@ const requestNewClient = (props: SharedHubClientProps, requestUrl: string, reque
       registrationClientUri: client.registration_client_uri,
       deploymentType: props.deploymentType,
       redirectUri: client.redirect_uri,
+      initialAccessToken: Redacted.make(client.initial_access_token ?? ""),
+      repository: client.repository ?? "",
     };
   });
 
@@ -220,13 +253,15 @@ const newClient = (props: SharedHubClientProps) => {
   const label = `Convex.SharedHubClient: ${props.app} on ${props.redirectUri} deploys without the hub`;
   const off: SharedHubClientAttributes = {
     status: "off",
-    issuer: "http://127.0.0.1:1",
-    clientId: "no-hub",
-    clientSecret: Redacted.make("no-hub"),
+    issuer: OFF_VALUES.issuer,
+    clientId: OFF_VALUES.clientId,
+    clientSecret: Redacted.make(OFF_VALUES.clientSecret),
     registrationAccessToken: Redacted.make(""),
     registrationClientUri: "",
     deploymentType: props.deploymentType,
     redirectUri: "",
+    initialAccessToken: Redacted.make(""),
+    repository: "",
   };
   const requestUrl = process.env["ACTIONS_ID_TOKEN_REQUEST_URL"];
   const requestToken = process.env["ACTIONS_ID_TOKEN_REQUEST_TOKEN"];
@@ -248,9 +283,21 @@ const newClient = (props: SharedHubClientProps) => {
   );
 };
 
+/**
+ * The token fields of saved attributes. A row of 0.25 and earlier has neither, and they stay empty
+ * until the next production registration.
+ */
+const StoredToken = Schema.Struct({
+  initialAccessToken: Schema.optionalKey(Schema.Redacted(Schema.String)),
+  repository: Schema.optionalKey(Schema.String),
+});
+
 /** The client after a read on the hub, or undefined when the hub says that the client is gone. */
-const renew = (saved: SharedHubClientAttributes) =>
-  Effect.gen(function* () {
+const renew = (stored: SharedHubClientAttributes) => {
+  const { initialAccessToken = Redacted.make(""), repository = "" } =
+    Schema.decodeUnknownSync(StoredToken)(stored);
+  const saved = { ...stored, initialAccessToken, repository };
+  return Effect.gen(function* () {
     const { status } = yield* send(
       "The identity hub",
       saved.registrationClientUri,
@@ -279,6 +326,7 @@ const renew = (saved: SharedHubClientAttributes) =>
       ).pipe(Effect.as(saved)),
     ),
   );
+};
 
 export const SharedHubClientProvider = () =>
   Provider.succeed(SharedHubClient, {
@@ -321,3 +369,277 @@ export const SharedHubClientProvider = () =>
             ),
           ),
   });
+
+export interface SharedDevelopmentClientOptions {
+  /** The stack of the app, the repository `owner/name`. Its stage `prod` holds the token. */
+  readonly stack: string;
+  readonly app: string;
+  /** The path of the hub's callback after the site URL of the deployment. */
+  readonly callbackPath: string;
+  /** Prefix of the five deployment variables. */
+  readonly envPrefix?: string;
+  /** The Convex team, a slug or an id, whose state store holds the stack. */
+  readonly team?: string;
+  /** The directory of the app. */
+  readonly cwd: string;
+  /** Runs the Convex CLI on the deployment of `cwd`, and answers its output. */
+  readonly convex: (args: readonly string[], input?: string) => string;
+}
+
+/** The logical id of the client in the stack of the starter. */
+const CLIENT_FQN = "HubClient";
+
+/** The one action that `state:get` needs. */
+const READ_KEY_ACTIONS = ["deployment:functions:runInternalQueries"] as const;
+
+/** `CONVEX_DEPLOYMENT` of `.env.local` for a cloud development deployment, such as `dev:happy-otter-123`. */
+const CLOUD_DEPLOYMENT = /^CONVEX_DEPLOYMENT=(?:dev:)?([a-z0-9]+(?:-[a-z0-9]+)*)[ \t]*(?:#.*)?$/m;
+
+/** The client row of stage `prod` with a token. A row without one fails to decode. */
+const SavedToken = Schema.Struct({
+  resourceType: Schema.Literal("IdentityHub.SharedClient"),
+  attr: Schema.Struct({
+    initialAccessToken: Schema.Redacted(Schema.NonEmptyString),
+    repository: Schema.NonEmptyString,
+  }),
+});
+
+/** The part of a client's own record (RFC 7592) that a renewal compares. */
+const ClientRecord = Schema.Struct({ redirect_uris: Schema.Array(Schema.String) });
+
+/**
+ * The directory whose `.env.local` selects the cloud development deployment of `cwd`. A linked git
+ * worktree runs a local backend, so the main checkout, the parent of the common git directory,
+ * selects it.
+ */
+const selectingDirectory = (cwd: string) =>
+  Effect.try({
+    try: () =>
+      // The prefix is the path of `cwd` in the checkout, and an empty line at its root.
+      execFileSync(
+        "git",
+        ["rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir", "--show-prefix"],
+        { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+      ).split(/\r?\n/),
+    catch: () => undefined,
+  }).pipe(
+    Effect.map(([gitDir, commonDir, prefix = ""]) =>
+      gitDir === undefined || commonDir === undefined || gitDir === commonDir
+        ? cwd
+        : join(dirname(commonDir), prefix),
+    ),
+    Effect.orElseSucceed(() => cwd),
+  );
+
+/** The team of the cloud development deployment that `.env.local` selects, or undefined. */
+const teamOfSelectedDeployment = (api: ManagementApiService, cwd: string) =>
+  Effect.gen(function* () {
+    const directory = yield* selectingDirectory(cwd);
+    const text = yield* Effect.tryPromise(() =>
+      readFile(join(directory, ".env.local"), "utf8"),
+    ).pipe(Effect.orElseSucceed(() => ""));
+    const name = CLOUD_DEPLOYMENT.exec(text)?.[1];
+    if (name === undefined) return undefined;
+    const { projectId } = yield* api
+      .request("get deployment", (client) =>
+        client.GET("/deployments/{deployment_name}", {
+          params: { path: { deployment_name: name } },
+        }),
+      )
+      .pipe(Effect.flatMap(Schema.decodeUnknownEffect(DeploymentRow)));
+    return (yield* getProjectById(api, projectId))?.teamId;
+  });
+
+/**
+ * The initial access token and the repository id in the client row of stage `prod` of `stack`, or
+ * undefined. It reads the row with the store's own `state:get` and a key that runs internal queries
+ * only. It never builds `Convex.state()`, which can create or upgrade the store.
+ */
+const readSavedToken = (api: ManagementApiService, team: string | number, stack: string) =>
+  Effect.gen(function* () {
+    const project = yield* findProjectByName(
+      api,
+      yield* api.resolveTeamId(team),
+      STORE_PROJECT_NAME,
+    );
+    const deployment = project === undefined ? undefined : yield* prodDeploymentOf(api, project.id);
+    if (deployment === undefined) return undefined;
+    const reply = yield* withPushKey(api, deployment.name, READ_KEY_ACTIONS, (key) =>
+      makeFunctionApi(deployment.deploymentUrl, key).call("state:get", {
+        stack,
+        stage: "prod",
+        fqn: CLIENT_FQN,
+      }),
+    );
+    if (reply.status === "error") {
+      return yield* new SharedHubClientFailed({ reason: "the state store refused the read" });
+    }
+    const text = yield* decode(Schema.NullOr(Schema.String), "The state store")(reply.value);
+    if (text === null) return undefined;
+    const row = yield* Effect.try({
+      try: (): unknown => JSON.parse(text, reviveState),
+      catch: () => new SharedHubClientFailed({ reason: "the state store gave a bad row" }),
+    });
+    return Option.getOrUndefined(Schema.decodeUnknownOption(SavedToken)(row))?.attr;
+  });
+
+/** Replaces any failure or defect of a step with a fixed text, which quotes nothing. */
+const failsWith =
+  (reason: string) =>
+  <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+    effect.pipe(Effect.catchCause(() => Effect.fail(new SharedHubClientFailed({ reason }))));
+
+/** What the hub says about the client that the variables name. */
+const readClient = (uri: string, token: string, callbackUrl: string) =>
+  Effect.gen(function* () {
+    const { body, status } = yield* send("The identity hub", uri, token, { method: "GET" });
+    switch (status) {
+      case 200: {
+        const record = yield* decode(ClientRecord, "The identity hub")(body);
+        const [only, ...more] = record.redirect_uris;
+        return only === callbackUrl && more.length === 0 ? "renewed" : "moved";
+      }
+      case 401:
+        return "gone";
+      case 403:
+        return "stopped";
+      default:
+        return yield* new SharedHubClientFailed({
+          reason: `the identity hub answered HTTP ${status}`,
+        });
+    }
+  });
+
+/**
+ * `alchemy-convex hub-client --shared`: a development client of an app on the central identity hub,
+ * for `pnpm run dev` on a laptop, with the initial access token that the stack saved at the
+ * production registration (RFC 133). Run it after the first push of each dev start. Answers the one
+ * line to print. It fails only for a defect: a refusal, a failed request, or no token keeps the
+ * variables and answers why.
+ *
+ * 1. The team: `team`, else `CONVEX_TEAM_ID`, else the team of the selected cloud development
+ *    deployment.
+ * 2. The five variables name a client of this hub (`<prefix>_ISSUER` is `HUB_URL` or
+ *    `https://auth.samebase.com`) with a real client ID and secret: the hub renews it on a read with
+ *    its own token (RFC 7592) when its `redirect_uris` are exactly the current callback. A client on
+ *    another address, or one that the hub no longer has, gets a new client. A client that the hub
+ *    stopped gets the off values.
+ * 3. The token from the client row of stage `prod`, the repository id on an https site, and a new
+ *    client, in one `env set --force`.
+ *
+ * The secret and both tokens reach the Convex CLI on standard input, never in its arguments, and no
+ * line holds them.
+ */
+export const registerSharedDevelopmentClient = (options: SharedDevelopmentClientOptions) =>
+  Effect.gen(function* () {
+    const api = yield* ManagementApi;
+    /** One call of the Convex CLI. Its error can quote the deployment, so it gives a fixed text. */
+    const convex = (args: readonly string[], input?: string) =>
+      Effect.try({
+        try: () => options.convex(args, input),
+        catch: () =>
+          new SharedHubClientFailed({
+            reason: `\`convex ${args.slice(0, 2).join(" ")}\` failed`,
+          }),
+      });
+    const named = options.team ?? process.env["CONVEX_TEAM_ID"];
+    const team =
+      named !== undefined && named !== ""
+        ? named
+        : yield* teamOfSelectedDeployment(api, options.cwd).pipe(
+            failsWith("the Convex API could not read the selected development deployment"),
+          );
+    if (team === undefined) {
+      return "No Convex team for Google sign-in on this laptop: set CONVEX_TEAM_ID, or select a cloud development deployment.";
+    }
+
+    const prefix = options.envPrefix ?? "HUB";
+    const siteUrl = yield* decode(
+      Schema.fromJsonString(Schema.String),
+      "The deployment",
+    )(yield* convex(["run", "--inline-query", "process.env.CONVEX_SITE_URL"]));
+    const callbackUrl = `${siteUrl.replace(/\/$/, "")}${options.callbackPath}`;
+
+    const names = (yield* convex(["env", "list", "--names-only"])).split(/\r?\n/);
+    const variable = (name: string) => `${prefix}_${name}`;
+    const tokenVariable = variable("REGISTRATION_TOKEN");
+    const complete = [
+      "ISSUER",
+      "CLIENT_ID",
+      "CLIENT_SECRET",
+      "REGISTRATION_URI",
+      "REGISTRATION_TOKEN",
+    ].every((name) => names.includes(variable(name)));
+    // Only a client of the hub that this run asks, with real values, is renewed: the off values,
+    // and a client of another hub, get a new client.
+    const renewable =
+      complete &&
+      (yield* convex(["env", "get", variable("ISSUER")])) === hubUrl() &&
+      (yield* convex(["env", "get", variable("CLIENT_ID")])) !== OFF_VALUES.clientId &&
+      ![OFF_VALUES.clientSecret, ""].includes(
+        yield* convex(["env", "get", variable("CLIENT_SECRET")]),
+      );
+    if (renewable) {
+      const client = yield* readClient(
+        yield* convex(["env", "get", variable("REGISTRATION_URI")]),
+        yield* convex(["env", "get", tokenVariable]),
+        callbackUrl,
+      );
+      if (client === "renewed") return "Hub client renewed.";
+      if (client === "stopped") {
+        yield* convex(
+          ["env", "set", "--force"],
+          `${prefix}_ISSUER='${OFF_VALUES.issuer}'\n${prefix}_CLIENT_ID='${OFF_VALUES.clientId}'\n${prefix}_CLIENT_SECRET='${OFF_VALUES.clientSecret}'\n`,
+        );
+        yield* convex(["env", "remove", variable("REGISTRATION_URI")]);
+        yield* convex(["env", "remove", tokenVariable]);
+        return "The identity hub stopped the hub client of this laptop (HTTP 403), so the laptop has guest sign-in.";
+      }
+    }
+
+    const saved = yield* readSavedToken(api, team, options.stack).pipe(
+      failsWith("the state store of the team could not be read"),
+    );
+    if (saved === undefined) return "Deploy to main once for Google sign-in on this laptop.";
+    if (new URL(siteUrl).protocol === "https:") {
+      // The hub reads /samebase-verification.json of an https site, which serves this variable.
+      yield* convex(["env", "set", "SAMEBASE_REPOSITORY_ID", saved.repository]);
+    }
+    const { body, status } = yield* send(
+      "The identity hub",
+      hubClientsUrl(),
+      Redacted.value(saved.initialAccessToken),
+      {
+        method: "POST",
+        body: JSON.stringify({
+          app: options.app,
+          redirectUri: callbackUrl,
+          softwareVersion: new URL(siteUrl).host,
+        }),
+      },
+    );
+    if (status !== 201) {
+      const reason =
+        status === 401
+          ? "the identity hub refused the initial access token of the app"
+          : refusalOf(status, body);
+      return `The hub client keeps its values: ${reason} (HTTP ${status}).`;
+    }
+    const client = yield* decode(NewClient, "The identity hub")(body);
+    // One request, so that an interrupted run cannot leave half a client. `--force` replaces the
+    // values of an earlier one.
+    yield* convex(
+      ["env", "set", "--force"],
+      `${prefix}_ISSUER='${client.issuer}'\n${prefix}_CLIENT_ID='${client.client_id}'\n${prefix}_CLIENT_SECRET='${client.client_secret}'\n${prefix}_REGISTRATION_URI='${client.registration_client_uri}'\n${tokenVariable}='${client.registration_access_token}'\n`,
+    );
+    return `Hub client registered for ${callbackUrl}.`;
+  }).pipe(
+    // A dev start goes on after any failure. Each step gives a fixed text, and the text of any
+    // other failure is never shown, because it can quote an answer or a secret.
+    Effect.catchCause((cause) => {
+      const error = Cause.squash(cause);
+      const reason =
+        error instanceof SharedHubClientFailed ? error.reason : "an unexpected failure";
+      return Effect.succeed(`The hub client keeps its values: ${reason}.`);
+    }),
+  );

package/src/cli.ts

@@ -1,15 +1,19 @@
 #!/usr/bin/env node
 // The commands of the package:
 //
-//   alchemy-convex hub-client --team <team> --app <app> --callback-path <path>
+//   alchemy-convex hub-client --team <team> --app <app> --callback-path <path> [--env-prefix HUB]
+//   alchemy-convex hub-client --shared --stack <owner/name> --app <app> --callback-path <path>
+//     [--env-prefix HUB] [--team <team>]
 //   alchemy-convex stack-comment [--team <team>]
 //
 // hub-client runs in the directory of a Convex app at each dev start, and renews the client of the
 // identity hub of the team that the development deployment of that directory has, or gives it a new
-// one: see registerDevelopmentClient. stack-comment runs as a step of a pull request workflow after
-// the deploys, and keeps one comment with the stacks of the repository: see src/StackComment.ts. It
-// needs GITHUB_TOKEN and, with a team access token, no --team. Both use CONVEX_ACCESS_TOKEN or the
-// Convex CLI login.
+// one: see registerDevelopmentClient. With --shared, the client is on the central identity hub, and
+// the initial access token of the stack's production client is the proof: see
+// registerSharedDevelopmentClient. It never stops a dev start. stack-comment runs as a step of a pull
+// request workflow after the deploys, and keeps one comment with the stacks of the repository: see
+// src/StackComment.ts. It needs GITHUB_TOKEN and, with a team access token, no --team. All use
+// CONVEX_ACCESS_TOKEN or the Convex CLI login.
 import { execFileSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import * as NodeServices from "@effect/platform-node/NodeServices";
@@ -19,6 +23,7 @@ import { fromConfig } from "./Credentials.ts";
 import { registerDevelopmentClient } from "./HubClient.ts";
 import { ManagementApiLive } from "./ManagementApi.ts";
 import { installedCli } from "./Push.ts";
+import { registerSharedDevelopmentClient } from "./SharedHubClient.ts";
 import { updateStackComment } from "./StackComment.ts";
 import { state } from "./State.ts";
 
@@ -29,31 +34,60 @@ const { positionals, values } = parseArgs({
     app: { type: "string" },
     "callback-path": { type: "string" },
     "env-prefix": { type: "string" },
+    shared: { type: "boolean" },
+    stack: { type: "string" },
   },
 });
-const { team, app, "callback-path": callbackPath, "env-prefix": envPrefix } = values;
+const { team, app, "callback-path": callbackPath, "env-prefix": envPrefix, shared, stack } = values;
 const USAGE = `Usage:
   alchemy-convex hub-client --team <team> --app <app> --callback-path <path> [--env-prefix HUB]
+  alchemy-convex hub-client --shared --stack <owner/name> --app <app> --callback-path <path> [--env-prefix HUB] [--team <team>]
   alchemy-convex stack-comment [--team <team>]`;
 
-const hubClient = (hub: { team: string; app: string; callbackPath: string; envPrefix?: string }) =>
-  Effect.gen(function* () {
-    const [command, ...prefix] = yield* installedCli(process.cwd());
-    const callbackUrl = yield* registerDevelopmentClient({
-      ...hub,
-      convex: (args, input) =>
+/** The installed Convex CLI on the deployment of this directory. Secrets go on standard input. */
+const convexOfThisDirectory = installedCli(process.cwd()).pipe(
+  Effect.map(
+    ([command, ...prefix]) =>
+      (args: readonly string[], input?: string) =>
         execFileSync(command, [...prefix, ...args], {
           encoding: "utf8",
           input,
           stdio: ["pipe", "pipe", "inherit"],
         }).trim(),
+  ),
+);
+
+const managementApi = ManagementApiLive().pipe(Layer.provide(fromConfig()));
+
+const hubClient = (hub: { team: string; app: string; callbackPath: string; envPrefix?: string }) =>
+  Effect.gen(function* () {
+    const callbackUrl = yield* registerDevelopmentClient({
+      ...hub,
+      convex: yield* convexOfThisDirectory,
     });
     console.log(
       callbackUrl === undefined
         ? "Hub client renewed."
         : `Hub client registered for ${callbackUrl}.`,
     );
-  }).pipe(Effect.provide(ManagementApiLive().pipe(Layer.provide(fromConfig()))));
+  }).pipe(Effect.provide(managementApi));
+
+const sharedHubClient = (hub: {
+  stack: string;
+  app: string;
+  callbackPath: string;
+  envPrefix?: string;
+  team?: string;
+}) =>
+  convexOfThisDirectory.pipe(
+    Effect.flatMap((convex) =>
+      registerSharedDevelopmentClient({ ...hub, cwd: process.cwd(), convex }),
+    ),
+    // Without the Convex CLI, the dev start goes on too.
+    Effect.catchTag("ConvexCliNotFound", (error) => Effect.succeed(error.message)),
+    Effect.tap((line) => Effect.sync(() => console.log(line))),
+    Effect.provide(managementApi),
+  );
 
 const stackComment = (options: { team?: string }) =>
   updateStackComment.pipe(
@@ -61,16 +95,26 @@ const stackComment = (options: { team?: string }) =>
     Effect.provide(state(options).pipe(Layer.provide(NodeServices.layer))),
   );
 
+const prefix = envPrefix === undefined ? {} : { envPrefix };
 const subcommand = positionals.join(" ");
 const program: Effect.Effect<unknown, unknown> | undefined =
   subcommand === "stack-comment"
     ? stackComment(team === undefined ? {} : { team })
-    : subcommand === "hub-client" &&
-        team !== undefined &&
-        app !== undefined &&
-        callbackPath !== undefined
-      ? hubClient({ team, app, callbackPath, ...(envPrefix === undefined ? {} : { envPrefix }) })
-      : undefined;
+    : subcommand !== "hub-client" || app === undefined || callbackPath === undefined
+      ? undefined
+      : shared === true
+        ? stack === undefined
+          ? undefined
+          : sharedHubClient({
+              stack,
+              app,
+              callbackPath,
+              ...prefix,
+              ...(team === undefined ? {} : { team }),
+            })
+        : team === undefined
+          ? undefined
+          : hubClient({ team, app, callbackPath, ...prefix });
 if (program === undefined) {
   console.error(USAGE);
   process.exit(1);

package/src/store/component/runRecord.ts

@@ -12,6 +12,21 @@ export const runRecord = v.object({
   recordedAt: v.string(),
 });
 
+type RunRecord = Infer<typeof runRecord>;
+
+/**
+ * True when a write with `next` must replace `current`, the record of the stage. Records that differ
+ * only in `recordedAt`, the time of one write, name the same run. Two laptop deploys of one commit
+ * have no `runUrl`, so they are the same run too. A write without a record (`null`) clears one.
+ */
+export const runChanged = (current: RunRecord | undefined, next: RunRecord | null) => {
+  if (next === null || current === undefined) return next !== null || current !== undefined;
+  const other = new Map(Object.entries(next));
+  return Object.entries(current).some(
+    ([field, value]) => field !== "recordedAt" && other.get(field) !== value,
+  );
+};
+
 /** Whether `value` passes `validator`. Only the kinds of {@link runRecord} pass; another kind fails. */
 export const validate = <V extends GenericValidator>(
   validator: V,

package/src/store/component/state.ts

@@ -10,7 +10,7 @@ import type { MutationCtx, QueryCtx } from "./_generated/server.js";
 // oxlint-disable-next-line samebase/no-raw-public-convex-function-builders -- Store entrypoints have no app wrapper; the reader and the deploy key enforce access.
 import { mutation, query } from "./_generated/server.js";
 import { generationOf } from "./keys.ts";
-import { runRecord } from "./runRecord.ts";
+import { runChanged, runRecord } from "./runRecord.ts";
 
 const stage = { stack: v.string(), stage: v.string() };
 const resource = { ...stage, fqn: v.string() };
@@ -43,17 +43,31 @@ const outputOf = (ctx: QueryCtx, args: { stack: string; stage: string }) =>
  */
 const run = v.union(runRecord, v.null());
 
-/** A resource write and its current run become visible in one transaction. */
+/**
+ * A resource write and its current run become visible in one transaction. The output row of the
+ * stage changes only when the run changes (see `runChanged`). Alchemy writes the resources of a
+ * deploy at the same time, and a write to the one output row of the stage made all of them conflict
+ * until Convex stopped the retries. A write of the same run only reads the row, and reads do not
+ * conflict. So `recordedAt` stays the time of the first write of the run, until `setOutput` writes
+ * it again.
+ */
 const writeCurrentRun = async (
   ctx: MutationCtx,
   args: { stack: string; stage: string; run: Infer<typeof run> },
 ) => {
   const output = await outputOf(ctx, args);
+  if (output === null) {
+    if (args.run !== null)
+      await ctx.db.insert("outputs", {
+        stack: args.stack,
+        stage: args.stage,
+        currentRun: args.run,
+      });
+    return;
+  }
   // A write without a run record clears the record of the previous run.
-  if (output !== null)
+  if (runChanged(output.currentRun, args.run))
     await ctx.db.patch("outputs", output._id, { currentRun: args.run ?? undefined });
-  else if (args.run !== null)
-    await ctx.db.insert("outputs", { stack: args.stack, stage: args.stage, currentRun: args.run });
 };
 
 /** The sorted union of two lists of names. */
@@ -228,10 +242,19 @@ export const setOutput = mutation({
   returns: v.null(),
   handler: async (ctx, args) => {
     const row = await outputOf(ctx, args);
-    if (row === null)
-      await ctx.db.insert("outputs", { stack: args.stack, stage: args.stage, value: args.value });
-    else await ctx.db.patch("outputs", row._id, { value: args.value });
-    await writeCurrentRun(ctx, args);
+    // The output and the record of its run, with the time of this last write of the run.
+    if (row !== null)
+      await ctx.db.patch("outputs", row._id, {
+        value: args.value,
+        currentRun: args.run ?? undefined,
+      });
+    else
+      await ctx.db.insert("outputs", {
+        stack: args.stack,
+        stage: args.stage,
+        value: args.value,
+        ...(args.run === null ? {} : { currentRun: args.run }),
+      });
     return null;
   },
 });