@samebase/alchemy-convex 0.2.0 → 0.4.0

package/src/index.ts

@@ -1,46 +1,21 @@
-// @samebase/alchemy-convex: Convex resources for Alchemy v2.
+// @samebase/alchemy-convex: the Convex plane for Alchemy v2.
 export {
   ACCESS_TOKEN_ENV,
   Credentials,
   CredentialsError,
+  DEPLOY_KEY_ENV,
   fromConfig,
-  fromToken,
+  fromValues,
 } from "./Credentials.ts";
 export {
-  DefaultEnvironmentVariable,
-  type DefaultEnvironmentVariableAttributes,
-  type DefaultEnvironmentVariableProps,
-  type DeploymentType,
-} from "./DefaultEnvironmentVariable.ts";
-export {
-  Deploy,
-  DeployArgumentError,
-  type DeployAttributes,
-  deployArgs,
-  DeployOutputError,
-  type DeployProps,
-  parseDeployOutput,
-} from "./Deploy.ts";
-export {
-  DeployKey,
-  type DeployKeyAction,
-  type DeployKeyAttributes,
-  DeployKeyIsCredential,
-  type DeployKeyProps,
-  DeployKeyRecoveryRequired,
-} from "./DeployKey.ts";
-export {
-  EnvironmentVariable,
-  type EnvironmentVariableAttributes,
-  type EnvironmentVariableProps,
-  VariableIdentityChange,
-} from "./EnvironmentVariable.ts";
+  AmbiguousDeployment,
+  Deployment,
+  type DeploymentAttributes,
+  DeploymentIdentityChange,
+  type DeploymentProps,
+  ProductionDeploymentNotFound,
+} from "./Deployment.ts";
 export { ConvexApiError, ManagementApi } from "./ManagementApi.ts";
-export {
-  PreviewDeployKey,
-  type PreviewDeployKeyAttributes,
-  type PreviewDeployKeyProps,
-} from "./PreviewDeployKey.ts";
 export {
   AmbiguousProject,
   CreatedProjectNotFound,
@@ -48,7 +23,19 @@ export {
   Project,
   ProjectDeploymentChange,
   type ProjectAttributes,
+  ProjectNotFound,
   type ProjectProps,
   ProjectTeamChange,
 } from "./Project.ts";
 export { Providers, providers } from "./Providers.ts";
+export {
+  CodePushFailed,
+  ConvexAppNotFound,
+  ConvexCliNotFound,
+  EnvironmentNeedsDeployKey,
+  type EnvValue,
+  parseDeployOutput,
+  PushTargetMismatch,
+  type Source,
+  VariablesOwnedBySomeoneElse,
+} from "./Push.ts";

package/src/DefaultEnvironmentVariable.ts

@@ -1,263 +0,0 @@
-// Convex.DefaultEnvironmentVariable: a project default environment variable
-// for one deployment type. Convex sets it on each new deployment of that type,
-// such as auth keys that every pull request preview deployment needs.
-//
-// Defaults live on the Management API and authenticate with the team
-// credential, not with a deploy key. Setting a default and removing it are the
-// same call: update_default_environment_variables with `value: null` removes
-// the default, and removing an absent default also answers 200.
-//
-// A default that exists but is not in state belongs to someone else: its old
-// value is lost when this resource writes it. Alchemy takes it over only with
-// --adopt.
-//
-// The default's project, name, and deployment type cannot change. A change
-// fails with VariableIdentityChange: use a new resource with a new logical
-// id. Read and delete use the identity in the attributes: after a refused
-// change, the props name the refused one.
-import { Resource } from "alchemy";
-import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
-import { isResolved } from "alchemy/Diff";
-import * as Provider from "alchemy/Provider";
-import * as Effect from "effect/Effect";
-import * as Redacted from "effect/Redacted";
-import * as Schema from "effect/Schema";
-import type { components } from "@convex-dev/platform/managementApi";
-import { shouldAdopt } from "./Adoption.ts";
-import { VariableIdentityChange } from "./EnvironmentVariable.ts";
-import {
-  absentAsUndefined,
-  ManagementApi,
-  type ManagementApiService,
-  retryIdempotentWrite,
-} from "./ManagementApi.ts";
-import type { Providers } from "./Providers.ts";
-
-/** Deployment types a default can target, from the generated schema. */
-export type DeploymentType = components["schemas"]["DeploymentType"];
-
-/**
- * Attributes when the listing has `name` for `deploymentType`. An unfiltered
- * listing merges the deployment types that share one value into one row, so
- * the match checks membership in `deploymentTypes`.
- */
-export const findDefault = (
-  list: typeof DefaultEnvironmentVariableList.Type,
-  projectId: number,
-  name: string,
-  deploymentType: DeploymentType,
-): DefaultEnvironmentVariableAttributes | undefined =>
-  list.items.some((item) => item.name === name && item.deploymentTypes.includes(deploymentType))
-    ? { projectId, name, deploymentType }
-    : undefined;
-
-/**
- * Lists the defaults named `name` for `deploymentType`. Convex filters on
- * both, so the listing has at most one row and needs no pagination.
- */
-export const listDefaults = (
-  api: ManagementApiService,
-  projectId: number,
-  name: string,
-  deploymentType: DeploymentType,
-) =>
-  api
-    .request("list default environment variables", (client) =>
-      client.GET("/projects/{project_id}/list_default_environment_variables", {
-        params: { path: { project_id: projectId }, query: { name, deploymentType } },
-      }),
-    )
-    .pipe(Effect.map((body) => Schema.decodeUnknownSync(DefaultEnvironmentVariableList)(body)));
-
-/** One attempt to set one default, or to remove it when `value` is null. */
-const writeDefault = (
-  api: ManagementApiService,
-  projectId: number,
-  name: string,
-  deploymentType: DeploymentType,
-  value: string | Redacted.Redacted<string> | null,
-) =>
-  api.requestVoid("update default environment variables", (client) =>
-    client.POST("/projects/{project_id}/update_default_environment_variables", {
-      params: { path: { project_id: projectId } },
-      body: {
-        changes: [
-          {
-            name,
-            deploymentType,
-            value: Redacted.isRedacted(value) ? Redacted.value(value) : value,
-          },
-        ],
-      },
-    }),
-  );
-
-/**
- * Sets one default, or removes it when `value` is null. Convex answers 200
- * with an empty body, so this reads no response data. The call sets a value,
- * so it runs again after a write conflict or a 5xx answer, for example when
- * another resource writes a default of the same project at the same time.
- */
-export const updateDefault = (
-  api: ManagementApiService,
-  projectId: number,
-  name: string,
-  deploymentType: DeploymentType,
-  value: string | Redacted.Redacted<string> | null,
-) => retryIdempotentWrite(writeDefault(api, projectId, name, deploymentType, value));
-
-/** The default's identity, or undefined when the default or the project is absent. */
-const readDefault = (
-  api: ManagementApiService,
-  projectId: number,
-  name: string,
-  deploymentType: DeploymentType,
-) =>
-  // 404 ProjectNotFound: the project no longer exists, so neither does the default.
-  absentAsUndefined(listDefaults(api, projectId, name, deploymentType)).pipe(
-    Effect.map((list) =>
-      list === undefined ? undefined : findDefault(list, projectId, name, deploymentType),
-    ),
-  );
-
-/**
- * GET /projects/{project_id}/list_default_environment_variables. Only the
- * fields the provider uses: the row's `value` is the secret in plain text.
- */
-export const DefaultEnvironmentVariableList = Schema.Struct({
-  items: Schema.Array(
-    Schema.Struct({ name: Schema.String, deploymentTypes: Schema.Array(Schema.String) }),
-  ),
-});
-
-export interface DefaultEnvironmentVariableProps {
-  /** Numeric project id, such as `project.projectId`. */
-  readonly projectId: number;
-  readonly name: string;
-  readonly value: string | Redacted.Redacted<string>;
-  /** Deployments of this type that Convex creates from now on get the variable. */
-  readonly deploymentType: DeploymentType;
-}
-
-export interface DefaultEnvironmentVariableAttributes {
-  readonly projectId: number;
-  readonly name: string;
-  readonly deploymentType: DeploymentType;
-}
-
-export type DefaultEnvironmentVariable = Resource<
-  "Convex.DefaultEnvironmentVariable",
-  DefaultEnvironmentVariableProps,
-  DefaultEnvironmentVariableAttributes,
-  never,
-  Providers
->;
-export const DefaultEnvironmentVariable = Resource<DefaultEnvironmentVariable>(
-  "Convex.DefaultEnvironmentVariable",
-);
-
-/** Fails with VariableIdentityChange when the props name another default than the one in state. */
-const checkIdentity = (
-  output: DefaultEnvironmentVariableAttributes,
-  news: DefaultEnvironmentVariableProps,
-) => {
-  const changed =
-    output.projectId !== news.projectId
-      ? ({
-          field: "projectId",
-          current: `${output.projectId}`,
-          requested: `${news.projectId}`,
-        } as const)
-      : output.name !== news.name
-        ? ({ field: "name", current: output.name, requested: news.name } as const)
-        : output.deploymentType !== news.deploymentType
-          ? ({
-              field: "deploymentType",
-              current: output.deploymentType,
-              requested: news.deploymentType,
-            } as const)
-          : undefined;
-  return changed === undefined
-    ? Effect.void
-    : Effect.fail(
-        new VariableIdentityChange({ resourceType: DefaultEnvironmentVariable.Type, ...changed }),
-      );
-};
-
-export const DefaultEnvironmentVariableProvider = () =>
-  Provider.effect(
-    DefaultEnvironmentVariable,
-    Effect.gen(function* () {
-      const api = yield* ManagementApi;
-
-      return {
-        // Compares with the attributes: after a refused change, `olds` are
-        // the refused props. Otherwise undefined: the engine updates when any
-        // prop changed and compares a Redacted value by content.
-        diff: Effect.fn(function* ({ news, output }) {
-          if (!isResolved(news) || output === undefined) return undefined;
-          yield* checkIdentity(output, news);
-          return undefined;
-        }),
-
-        read: Effect.fn(function* ({ olds, output }) {
-          const at = output ?? olds;
-          const found = yield* readDefault(api, at.projectId, at.name, at.deploymentType);
-          if (found === undefined) return undefined;
-          // No state: the default belongs to someone else until the user passes --adopt.
-          return output ?? Unowned(found);
-        }),
-
-        reconcile: Effect.fn(function* ({ fqn, news, output }) {
-          // Also here: with an unresolved prop in plan, diff could not check.
-          if (output !== undefined) yield* checkIdentity(output, news);
-          const write = writeDefault(
-            api,
-            news.projectId,
-            news.name,
-            news.deploymentType,
-            news.value,
-          );
-          if (output !== undefined || (yield* shouldAdopt(fqn))) {
-            // In state, or adopted: the default is ours to set.
-            yield* retryIdempotentWrite(write);
-          } else {
-            // Not in state: overwriting a default that exists loses its
-            // value, so that needs adoption. Each attempt checks first, so a
-            // retry after a write conflict never overwrites a default that
-            // another writer created in the meantime.
-            yield* retryIdempotentWrite(
-              Effect.gen(function* () {
-                const existing = yield* readDefault(
-                  api,
-                  news.projectId,
-                  news.name,
-                  news.deploymentType,
-                );
-                if (existing !== undefined) {
-                  return yield* new OwnedBySomeoneElse({
-                    message: `Project ${news.projectId} already has a ${news.deploymentType} default environment variable ${news.name}. Re-run with --adopt to take it over and overwrite its value, or use a different name.`,
-                    resourceType: DefaultEnvironmentVariable.Type,
-                    physicalName: news.name,
-                  });
-                }
-                yield* write;
-              }),
-            );
-          }
-          return {
-            projectId: news.projectId,
-            name: news.name,
-            deploymentType: news.deploymentType,
-          };
-        }),
-
-        delete: Effect.fn(function* ({ output }) {
-          // Removing an absent default succeeds; 404 ProjectNotFound means the project is gone.
-          yield* absentAsUndefined(
-            updateDefault(api, output.projectId, output.name, output.deploymentType, null),
-          );
-        }),
-      };
-    }),
-  );

package/src/Deploy.ts

@@ -1,193 +0,0 @@
-// Convex.Deploy: pushes the functions in a `convex/` directory with
-// `npx convex deploy` and exposes the deployment URL for a frontend build.
-//
-// The deployment itself belongs to the project, so delete leaves the last
-// pushed functions running. The URL comes from the CLI's own output because
-// the deploy key, not this resource, decides which deployment receives the push.
-import { stripVTControlCharacters } from "node:util";
-import { Resource } from "alchemy";
-import { CommandExecutor, type CommandRunProps } from "alchemy/Command";
-import { hashDirectory, type MemoOptions } from "alchemy/Command/Memo";
-import { havePropsChanged, isResolved } from "alchemy/Diff";
-import * as Provider from "alchemy/Provider";
-import * as Effect from "effect/Effect";
-import type * as Redacted from "effect/Redacted";
-import * as Schema from "effect/Schema";
-import type { Providers } from "./Providers.ts";
-
-export interface DeployProps extends Pick<CommandRunProps, "cwd" | "env" | "timeout"> {
-  /**
-   * Deploy key that selects the target deployment: a production, development,
-   * project, or preview deploy key. The CLI receives it as `CONVEX_DEPLOY_KEY`,
-   * and Alchemy removes its value from the logged output.
-   */
-  readonly deployKey: Redacted.Redacted<string>;
-  /**
-   * Preview deployment name for a preview deploy key. The CLI reuses an
-   * existing preview deployment with this name.
-   */
-  readonly previewName?: string;
-  /**
-   * Like {@link previewName}, but the CLI deletes and recreates an existing
-   * preview deployment with this name, so every run gets a new URL.
-   */
-  readonly previewCreate?: string;
-  /**
-   * Function to run after the push, such as `init:seed`. The CLI runs it only
-   * when the push created a new preview deployment.
-   */
-  readonly previewRun?: string;
-  /**
-   * More `convex deploy` flags, added after the preview flags. Alchemy splits
-   * the command on whitespace, so an argument cannot contain whitespace: use
-   * `--typecheck=disable`, not `--typecheck disable` as one argument.
-   */
-  readonly extraArgs?: readonly string[];
-  /**
-   * Files hashed to skip an unchanged push. By default every non-gitignored
-   * file under `cwd` and the nearest lockfile. Use
-   * `{ include: ["convex/**"], lockfile: true }` to ignore frontend changes,
-   * or `false` to push on every deploy. A preview deploy (`previewName` or
-   * `previewCreate`) pushes on every deploy: Convex can delete an expired
-   * preview deployment, and the hash cannot show that.
-   * @default true
-   */
-  readonly memo?: MemoOptions | boolean;
-}
-
-export interface DeployAttributes {
-  /** Client URL of the deployment that received the push, such as `https://happy-otter-123.convex.cloud`. */
-  readonly url: string;
-  /** First label of the URL host, such as `happy-otter-123`. */
-  readonly deploymentName: string;
-  /** Hash of the memoized input files after the push, or `undefined` when `memo` is `false`. */
-  readonly hash: string | undefined;
-}
-
-export type Deploy = Resource<"Convex.Deploy", DeployProps, DeployAttributes, never, Providers>;
-export const Deploy = Resource<Deploy>("Convex.Deploy");
-
-/**
- * The CLI prints this line with `logFinishedStep` after the push succeeds, to
- * stderr (convex 1.45 `cli/lib/deploy2.js` for existing deployments,
- * `cli/deploy.js` for preview deployments). The host is
- * `<deployment>.convex.cloud` or `<deployment>.<region>.convex.cloud`.
- */
-const DEPLOYED_LINE =
-  /Deployed Convex functions to (https:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)?\.convex\.cloud)\/?(?=\s|$)/m;
-
-/** Reads the deployment URL from `convex deploy` output. ANSI escape codes are removed first. */
-export const parseDeployOutput = (
-  text: string,
-): { url: string; deploymentName: string } | undefined => {
-  const match = DEPLOYED_LINE.exec(stripVTControlCharacters(text));
-  const url = match?.[1];
-  const deploymentName = match?.[2];
-  return url === undefined || deploymentName === undefined ? undefined : { url, deploymentName };
-};
-
-/** The `convex deploy` argv, starting with `npx`. */
-export const deployArgs = (
-  props: Pick<DeployProps, "previewName" | "previewCreate" | "previewRun" | "extraArgs">,
-): readonly string[] => [
-  "npx",
-  "convex",
-  "deploy",
-  ...(props.previewName === undefined ? [] : ["--preview-name", props.previewName]),
-  ...(props.previewCreate === undefined ? [] : ["--preview-create", props.previewCreate]),
-  ...(props.previewRun === undefined ? [] : ["--preview-run", props.previewRun]),
-  ...(props.extraArgs ?? []),
-];
-
-/** Number of output lines quoted when the CLI exits 0 without the deployed line. */
-const OUTPUT_TAIL_LINES = 20;
-
-/** A `convex deploy` argument contains whitespace, which Alchemy's command runner splits on. */
-export class DeployArgumentError extends Schema.TaggedError<DeployArgumentError>()(
-  "DeployArgumentError",
-  { argument: Schema.String },
-) {
-  override get message() {
-    return `Convex.Deploy argument "${this.argument}" contains whitespace, and Alchemy splits the command on whitespace. Use the --flag=value form, such as --typecheck=disable, and names without spaces.`;
-  }
-}
-
-/** `npx convex deploy` exited 0 but did not print the deployment URL. */
-export class DeployOutputError extends Schema.TaggedError<DeployOutputError>()(
-  "DeployOutputError",
-  { outputTail: Schema.String },
-) {
-  override get message() {
-    return `npx convex deploy exited 0 but printed no "Deployed Convex functions to <url>" line, so Convex.Deploy has no deployment URL. Remove --dry-run from extraArgs if it is there, and read the CLI output. Last output:\n${this.outputTail}`;
-  }
-}
-
-export const DeployProvider = () =>
-  Provider.effect(
-    Deploy,
-    Effect.gen(function* () {
-      const { run } = yield* CommandExecutor;
-
-      const hashOf = (props: DeployProps) =>
-        props.memo === false
-          ? Effect.succeed(undefined)
-          : hashDirectory({
-              ...(props.cwd === undefined ? {} : { cwd: props.cwd }),
-              memo: props.memo === true || props.memo === undefined ? {} : props.memo,
-            });
-
-      return {
-        // No `stables`: the same deploy key can push to a different URL. A
-        // project deploy key follows the project's default production
-        // deployment, and a preview deployment can expire or be recreated
-        // under the same name.
-        diff: Effect.fn(function* ({ olds, news, output }) {
-          if (!isResolved(news)) return undefined;
-          // A preview deployment can expire. The same hash then hides a
-          // missing deployment, so a preview always pushes. The CLI reuses
-          // a live preview with the same name.
-          const preview = news.previewName !== undefined || news.previewCreate !== undefined;
-          if (
-            preview ||
-            output === undefined ||
-            output.hash === undefined ||
-            havePropsChanged(olds, news)
-          ) {
-            return { action: "update" } as const;
-          }
-          return { action: (yield* hashOf(news)) === output.hash ? "noop" : "update" } as const;
-        }),
-
-        reconcile: Effect.fn(function* ({ news, session }) {
-          const args = deployArgs(news);
-          const spaced = args.find((arg) => /\s/.test(arg));
-          if (spaced !== undefined) return yield* new DeployArgumentError({ argument: spaced });
-          // A push is idempotent: the CLI uploads the full function set every time.
-          const { stdout, stderr } = yield* run(
-            {
-              command: args.join(" "),
-              ...(news.cwd === undefined ? {} : { cwd: news.cwd }),
-              ...(news.timeout === undefined ? {} : { timeout: news.timeout }),
-              env: { ...news.env, CONVEX_DEPLOY_KEY: news.deployKey },
-            },
-            session,
-          );
-          // `run` returns output with the deploy key already replaced.
-          const output = `${stdout}\n${stderr}`;
-          const deployed = parseDeployOutput(output);
-          if (deployed === undefined) {
-            const outputTail = stripVTControlCharacters(output)
-              .split(/\r?\n|\r/)
-              .filter((line) => line.trim() !== "")
-              .slice(-OUTPUT_TAIL_LINES)
-              .join("\n");
-            return yield* new DeployOutputError({ outputTail });
-          }
-          return { ...deployed, hash: yield* hashOf(news) };
-        }),
-
-        // The deployment belongs to the project; its functions stay deployed.
-        delete: () => Effect.void,
-      };
-    }),
-  );