@samebase/alchemy-convex 0.1.0

package/src/DefaultEnvironmentVariable.ts

@@ -0,0 +1,165 @@
+// 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.
+import { Resource } from "alchemy";
+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 { absentAsUndefined, ManagementApi, type ManagementApiService } 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)));
+
+/**
+ * Sets one default, or removes it when `value` is null. Convex answers 200
+ * with an empty body, so this reads no response data.
+ */
+export const updateDefault = (
+  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,
+          },
+        ],
+      },
+    }),
+  );
+
+/**
+ * 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",
+);
+
+export const DefaultEnvironmentVariableProvider = () =>
+  Provider.effect(
+    DefaultEnvironmentVariable,
+    Effect.gen(function* () {
+      const api = yield* ManagementApi;
+
+      return {
+        stables: ["projectId", "name", "deploymentType"],
+
+        diff: ({ olds, news }) => {
+          if (!isResolved(news)) return Effect.succeed(undefined);
+          // Otherwise undefined: the engine updates when any prop changed and
+          // compares a Redacted value by content.
+          return Effect.succeed(
+            olds.projectId !== news.projectId ||
+              olds.name !== news.name ||
+              olds.deploymentType !== news.deploymentType
+              ? ({ action: "replace" } as const)
+              : undefined,
+          );
+        },
+
+        read: Effect.fn(function* ({ olds }) {
+          // 404 ProjectNotFound: the project no longer exists, so neither does the default.
+          const list = yield* absentAsUndefined(
+            listDefaults(api, olds.projectId, olds.name, olds.deploymentType),
+          );
+          if (list === undefined) return undefined;
+          return findDefault(list, olds.projectId, olds.name, olds.deploymentType);
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          yield* updateDefault(api, news.projectId, news.name, news.deploymentType, news.value);
+          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

@@ -0,0 +1,171 @@
+// 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 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.
+   * @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;
+
+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;
+          if (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* Effect.die(
+              new Error(
+                `Convex.Deploy argument "${spaced}" contains whitespace; Alchemy splits commands on whitespace`,
+              ),
+            );
+          }
+          // 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 tail = stripVTControlCharacters(output)
+              .split(/\r?\n|\r/)
+              .filter((line) => line.trim() !== "")
+              .slice(-OUTPUT_TAIL_LINES)
+              .join("\n");
+            return yield* Effect.die(
+              new Error(
+                `npx convex deploy exited 0 but printed no "Deployed Convex functions to <url>" line. Last output:\n${tail}`,
+              ),
+            );
+          }
+          return { ...deployed, hash: yield* hashOf(news) };
+        }),
+
+        // The deployment belongs to the project; its functions stay deployed.
+        delete: () => Effect.void,
+      };
+    }),
+  );

package/src/DeployKey.ts

@@ -0,0 +1,171 @@
+// Convex.DeployKey: a deploy key for one deployment, such as the key
+// `npx convex deploy` reads from CONVEX_DEPLOY_KEY.
+//
+// Convex returns the secret only once, from create_deploy_key. The listing
+// shows each key under a unique name, the requested name plus a short id
+// suffix such as "my-key (0e71106d)", and delete_deploy_key accepts that
+// unique name. A key cannot be changed after creation, so every property
+// change is a replacement.
+import { Resource } from "alchemy";
+import { havePropsChanged, 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 { absentAsUndefined, ManagementApi } from "./ManagementApi.ts";
+import type { Providers } from "./Providers.ts";
+
+/** Actions a deploy key can be limited to, from the generated schema. */
+export type DeployKeyAction = NonNullable<
+  components["schemas"]["PlatformCreateDeployKeyArgs"]["allowedActions"]
+>[number];
+
+/**
+ * True when `listedName` is how Convex lists a key created as `name`: the
+ * requested name, a space, and one parenthesized id without spaces. The id
+ * check keeps `my-key` from matching a key created as `my-key (old)`.
+ */
+const isListedAs = (listedName: string, name: string) => {
+  const prefix = `${name} (`;
+  return listedName.startsWith(prefix) && /^[^\s()]+\)$/.test(listedName.slice(prefix.length));
+};
+
+/**
+ * The listed key that a create call for `name` just made. The newest match
+ * wins: an earlier attempt that failed before Alchemy saved state can leave
+ * another key with the same requested name, and its secret is lost.
+ */
+export const selectCreatedKey = (
+  entries: ReadonlyArray<typeof ListedKey.Type>,
+  name: string,
+): typeof ListedKey.Type | undefined =>
+  entries
+    .filter((entry) => isListedAs(entry.name, name))
+    .reduce<typeof ListedKey.Type | undefined>(
+      (newest, entry) =>
+        newest === undefined || entry.creationTime > newest.creationTime ? entry : newest,
+      undefined,
+    );
+
+/** One row of list_deploy_keys and list_preview_deploy_keys. Only the fields the providers use. */
+export const ListedKey = Schema.Struct({
+  name: Schema.String,
+  creationTime: Schema.Number,
+});
+
+/** GET /deployments/{deployment_name}/list_deploy_keys */
+export const DeployKeyList = Schema.Array(ListedKey);
+
+/** POST /deployments/{deployment_name}/create_deploy_key */
+export const CreatedDeployKey = Schema.Struct({ deployKey: Schema.String });
+
+export interface DeployKeyProps {
+  /** Deployment name, such as `project.prodDeploymentName`. */
+  readonly deployment: string;
+  /** Requested key name. Convex appends a short id to make it unique. */
+  readonly name: string;
+  /** Limits the key to these actions. Convex grants every deployment action when omitted. */
+  readonly allowedActions?: readonly DeployKeyAction[];
+}
+
+export interface DeployKeyAttributes {
+  /** The name Convex lists the key under, such as "my-key (0e71106d)". */
+  readonly uniqueName: string;
+  readonly deployment: string;
+  /** The secret, such as `prod:<deployment>|<token>`. Convex returns it only at creation. */
+  readonly deployKey: Redacted.Redacted<string>;
+}
+
+export type DeployKey = Resource<
+  "Convex.DeployKey",
+  DeployKeyProps,
+  DeployKeyAttributes,
+  never,
+  Providers
+>;
+export const DeployKey = Resource<DeployKey>("Convex.DeployKey");
+
+export const DeployKeyProvider = () =>
+  Provider.effect(
+    DeployKey,
+    Effect.gen(function* () {
+      const api = yield* ManagementApi;
+
+      const listKeys = (deployment: string) =>
+        api
+          .request("list deploy keys", (client) =>
+            client.GET("/deployments/{deployment_name}/list_deploy_keys", {
+              params: { path: { deployment_name: deployment } },
+            }),
+          )
+          .pipe(Effect.map((body) => Schema.decodeUnknownSync(DeployKeyList)(body)));
+
+      return {
+        stables: ["uniqueName", "deployment"],
+
+        diff: ({ olds, news, output }) => {
+          if (!isResolved(news)) return Effect.succeed(undefined);
+          // State written without the secret cannot hand a key to dependents,
+          // and Convex cannot return it again, so only a new key helps.
+          return Effect.succeed(
+            (output !== undefined && output.deployKey === undefined) || havePropsChanged(olds, news)
+              ? ({ action: "replace" } as const)
+              : ({ action: "noop" } as const),
+          );
+        },
+
+        read: Effect.fn(function* ({ output }) {
+          // A key that is not in state has no known secret, so it is never adopted.
+          if (output === undefined) return undefined;
+          const entries = yield* absentAsUndefined(listKeys(output.deployment));
+          return entries?.some((entry) => entry.name === output.uniqueName) ? output : undefined;
+        }),
+
+        reconcile: Effect.fn(function* ({ news, output }) {
+          if (output !== undefined) {
+            // The secret cannot be read back. A key that still exists keeps the one in state.
+            const entries = yield* listKeys(news.deployment);
+            if (entries.some((entry) => entry.name === output.uniqueName)) return output;
+          }
+          const created = yield* api.request("create deploy key", (client) =>
+            client.POST("/deployments/{deployment_name}/create_deploy_key", {
+              params: { path: { deployment_name: news.deployment } },
+              body: {
+                name: news.name,
+                ...(news.allowedActions === undefined
+                  ? {}
+                  : { allowedActions: [...news.allowedActions] }),
+              },
+            }),
+          );
+          const { deployKey } = Schema.decodeUnknownSync(CreatedDeployKey)(created);
+          const listed = selectCreatedKey(yield* listKeys(news.deployment), news.name);
+          if (listed === undefined) {
+            return yield* Effect.die(
+              new Error(
+                `Convex created deploy key "${news.name}" on ${news.deployment} but does not list it`,
+              ),
+            );
+          }
+          return {
+            uniqueName: listed.name,
+            deployment: news.deployment,
+            deployKey: Redacted.make(deployKey),
+          };
+        }),
+
+        delete: Effect.fn(function* ({ output }) {
+          // 404 DeployKeyNotFound: an earlier attempt or someone else deleted it.
+          yield* absentAsUndefined(
+            api.requestVoid("delete deploy key", (client) =>
+              client.POST("/deployments/{deployment_name}/delete_deploy_key", {
+                params: { path: { deployment_name: output.deployment } },
+                body: { id: output.uniqueName },
+              }),
+            ),
+          );
+        }),
+      };
+    }),
+  );

package/src/EnvironmentVariable.ts

@@ -0,0 +1,129 @@
+// Convex.EnvironmentVariable: one environment variable on one deployment.
+//
+// Environment variables live on the deployment API
+// (https://<deployment>.convex.cloud/api/v1), which authenticates with a
+// deploy key, not with the Management API token. Setting a variable and
+// removing it are the same call: update_environment_variables with
+// `value: null` removes the variable.
+import { createDeploymentClient } from "@convex-dev/platform";
+import { Resource } from "alchemy";
+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 { absentAsUndefined, ManagementApi, settleVoid } from "./ManagementApi.ts";
+import type { Providers } from "./Providers.ts";
+
+/**
+ * Attributes when the listing has `name`. Own keys only: a valid variable
+ * name such as `toString` must not match the object prototype.
+ */
+export const findVariable = (
+  list: typeof EnvironmentVariableList.Type,
+  deployment: string,
+  name: string,
+): EnvironmentVariableAttributes | undefined =>
+  Object.hasOwn(list.environmentVariables, name) ? { deployment, name } : undefined;
+
+/**
+ * Sets one variable, or removes it when `value` is null. The deployment
+ * answers 200 with an empty body, so this reads no response data.
+ */
+export const updateVariable = (
+  deployment: string,
+  deployKey: Redacted.Redacted<string>,
+  name: string,
+  value: string | Redacted.Redacted<string> | null,
+) =>
+  settleVoid("update environment variables", () =>
+    createDeploymentClient(deployment, Redacted.value(deployKey)).POST(
+      "/update_environment_variables",
+      {
+        body: {
+          changes: [{ name, value: Redacted.isRedacted(value) ? Redacted.value(value) : value }],
+        },
+      },
+    ),
+  );
+
+/** GET https://<deployment>.convex.cloud/api/v1/list_environment_variables */
+export const EnvironmentVariableList = Schema.Struct({
+  environmentVariables: Schema.Record(Schema.String, Schema.String),
+});
+
+export interface EnvironmentVariableProps {
+  /** Deployment name, or its URL for deployments outside US East. */
+  readonly deployment: string;
+  /** Deploy key for `deployment`, such as `deployKey.deployKey`. */
+  readonly deployKey: Redacted.Redacted<string>;
+  readonly name: string;
+  readonly value: string | Redacted.Redacted<string>;
+}
+
+export interface EnvironmentVariableAttributes {
+  readonly deployment: string;
+  readonly name: string;
+}
+
+export type EnvironmentVariable = Resource<
+  "Convex.EnvironmentVariable",
+  EnvironmentVariableProps,
+  EnvironmentVariableAttributes,
+  never,
+  Providers
+>;
+export const EnvironmentVariable = Resource<EnvironmentVariable>("Convex.EnvironmentVariable");
+
+export const EnvironmentVariableProvider = () =>
+  Provider.effect(
+    EnvironmentVariable,
+    Effect.gen(function* () {
+      const api = yield* ManagementApi;
+
+      return {
+        stables: ["deployment", "name"],
+
+        diff: ({ olds, news }) => {
+          if (!isResolved(news)) return Effect.succeed(undefined);
+          // Otherwise undefined: the engine updates when any prop changed and
+          // compares Redacted values, such as the value and the deploy key, by content.
+          return Effect.succeed(
+            olds.deployment !== news.deployment || olds.name !== news.name
+              ? ({ action: "replace" } as const)
+              : undefined,
+          );
+        },
+
+        read: Effect.fn(function* ({ olds }) {
+          // 404: the deployment no longer exists, so neither does the variable.
+          const body = yield* absentAsUndefined(
+            api.deploymentRequest(
+              "list environment variables",
+              olds.deployment,
+              olds.deployKey,
+              (client) => client.GET("/list_environment_variables"),
+            ),
+          );
+          if (body === undefined) return undefined;
+          return findVariable(
+            Schema.decodeUnknownSync(EnvironmentVariableList)(body),
+            olds.deployment,
+            olds.name,
+          );
+        }),
+
+        reconcile: Effect.fn(function* ({ news }) {
+          yield* updateVariable(news.deployment, news.deployKey, news.name, news.value);
+          return { deployment: news.deployment, name: news.name };
+        }),
+
+        delete: Effect.fn(function* ({ olds, output }) {
+          // Removing an absent variable succeeds; 404 means the deployment is gone.
+          yield* absentAsUndefined(
+            updateVariable(output.deployment, olds.deployKey, output.name, null),
+          );
+        }),
+      };
+    }),
+  );