@samebase/alchemy-convex 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samebase/alchemy-convex",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The Convex plane for Alchemy v2: projects, deployments, environment variables, and the push of the functions",
   "keywords": [
     "alchemy",

package/src/Deployment.ts

@@ -2,8 +2,14 @@
 // variables, and its functions, with the URLs that a frontend or a Worker
 // needs. This is the Convex plane of a stack: no deploy key leaves it.
 //
-// - `source` is the Convex functions directory, such as `./convex`. The
-//   update pushes it with the Convex CLI that the app installed (Push.ts).
+// - `rootDir` is the app directory, relative to the directory where the
+//   deploy runs (the directory of the stack file), such as `apps/web`, and
+//   "." by default. The push runs in it, and `source` is relative to it.
+//   The constructor writes it into the props, "." included, so that a reader
+//   of the state row finds the app directory of every deployment.
+// - `source` is the Convex functions directory relative to `rootDir`, such
+//   as `./convex`. The update pushes it with the Convex CLI that the app
+//   installed (Push.ts).
 //   The content identity of the push is a hash of the source files, the
 //   app's package.json, convex.json, and lockfile, the deployment name, and
 //   `env`. The same hash is a no-op. The hash is taken again after the push,
@@ -45,9 +51,11 @@
 //
 // Patterns from Confect `packages/alchemy/src/Deployment.ts`
 // (https://github.com/rjdellecese/confect, ISC license, see NOTICE).
+import { posix, win32 } from "node:path";
 import { Resource } from "alchemy";
 import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy";
 import { isResolved } from "alchemy/Diff";
+import type { InputProps } from "alchemy/Input";
 import * as Provider from "alchemy/Provider";
 import * as Effect from "effect/Effect";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
@@ -79,10 +87,16 @@ interface DeploymentInputs {
   /** The project: a Convex.Project resource, or `{ projectId }`. Cannot change. */
   readonly project: { readonly projectId: number };
   /**
-   * The Convex functions directory, such as `./convex`, or that directory
-   * with a push command and more hashed files. The push runs in the nearest
-   * directory above it with a package.json. Without `source`, the resource
-   * pushes nothing.
+   * The app directory, relative to the directory where the deploy runs (the
+   * directory of the stack file), such as `apps/web`. Default ".". It must
+   * have a package.json. The push runs in it, and `source` is relative to
+   * it. State from 0.7 has no `rootDir`.
+   */
+  readonly rootDir?: string;
+  /**
+   * The Convex functions directory relative to `rootDir`, such as
+   * `./convex`, or that directory with a push command and more hashed
+   * files. Without `source`, the resource pushes nothing.
    */
   readonly source?: Source;
   /** Environment variables to set on the deployment before the push. */
@@ -134,10 +148,61 @@ export type Deployment = Resource<
   never,
   Providers
 >;
-export const Deployment = Resource<Deployment>("Convex.Deployment", {
+/** The resource class. Stacks call {@link Deployment}, which writes `rootDir` into the props. */
+export const DeploymentResource = Resource<Deployment>("Convex.Deployment", {
   defaultRemovalPolicy: "retain",
 });
 
+/** The props of a `Convex.Deployment` call: Alchemy inputs, with `rootDir` a plain string. */
+export type DeploymentInput = DeploymentProps extends infer P
+  ? P extends DeploymentProps
+    ? InputProps<P, "rootDir">
+    : never
+  : never;
+
+/** `rootDir` in POSIX form, without "./" and a trailing slash, such as `apps/web` or ".". */
+const normalizeRootDir = (rootDir: string) => {
+  const normalized = posix.normalize(rootDir.replaceAll("\\", "/"));
+  return normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+};
+
+/** `rootDir` is an absolute path. The declaration stops with it as a defect, before the plan. */
+export class AbsoluteRootDir extends Schema.TaggedError<AbsoluteRootDir>()("AbsoluteRootDir", {
+  rootDir: Schema.String,
+}) {
+  override get message() {
+    return `Convex.Deployment rootDir ${this.rootDir} is an absolute path. State keeps rootDir for every machine that runs the stack, so set it relative to the directory where the deploy runs, such as "apps/web".`;
+  }
+}
+
+/**
+ * `Convex.Deployment("id", props)`. The props go to state with `rootDir` in
+ * POSIX form, and with "." when it is not set, so that every row names the
+ * app directory of its deployment. An absolute `rootDir` stops the
+ * declaration, so it never reaches the plan or state. The check dies,
+ * because the program of `Alchemy.Stack` can fail only with a ConfigError.
+ * `win32.isAbsolute` also answers true for a POSIX absolute path. The other
+ * fields keep it usable where Alchemy takes a resource class, such as
+ * `Provider.collection`.
+ */
+export const Deployment = Object.assign(
+  (id: string, props: DeploymentInput) => {
+    const rootDir = props.rootDir ?? ".";
+    return win32.isAbsolute(rootDir)
+      ? Effect.die(new AbsoluteRootDir({ rootDir }))
+      : DeploymentResource(id, { ...props, rootDir: normalizeRootDir(rootDir) });
+  },
+  {
+    Type: DeploymentResource.Type,
+    Props: DeploymentResource.Props,
+    Self: DeploymentResource.Self,
+    Provider: DeploymentResource.Provider,
+    Aliases: DeploymentResource.Aliases,
+    ref: (id: string, options?: { stage?: string; stack?: string }) =>
+      DeploymentResource.ref(id, options),
+  },
+);
+
 /** The props name another deployment than the one in state. */
 export class DeploymentIdentityChange extends Schema.TaggedError<DeploymentIdentityChange>()(
   "DeploymentIdentityChange",
@@ -336,7 +401,7 @@ const isRefused = (error: ConvexApiError) =>
 
 export const DeploymentProvider = () =>
   Provider.effect(
-    Deployment,
+    DeploymentResource,
     Effect.gen(function* () {
       const api = yield* ManagementApi;
       const credentials = yield* Credentials;
@@ -517,10 +582,10 @@ export const DeploymentProvider = () =>
         });
 
       /** The content identity of `source` and `env` on a deployment, or undefined when there is nothing to push. */
-      const wantedHash = (news: DeploymentProps, deployment: string) =>
+      const wantedHash = (news: DeploymentProps, rootDir: string, deployment: string) =>
         news.source === undefined && Object.keys(news.env ?? {}).length === 0
           ? Effect.succeed(undefined)
-          : pushHash({ source: news.source, deployment, env: news.env ?? {} });
+          : pushHash({ rootDir, source: news.source, deployment, env: news.env ?? {} });
 
       return {
         // `name`, `reference`, and the URLs change when an expired preview is
@@ -529,10 +594,21 @@ export const DeploymentProvider = () =>
         stables: ["projectId", "type", "previewName"],
 
         // Compares with the attributes: after a refused change, `olds` are
-        // the refused props.
-        diff: Effect.fn(function* ({ news, output }) {
+        // the refused props. Only `rootDir` compares with `olds`, because it
+        // is in the props only. A refused update leaves the row `updating`,
+        // and the next plan updates it again anyway.
+        diff: Effect.fn(function* ({ news, olds, output }) {
           if (!isResolved(news) || output === undefined) return undefined;
           yield* checkIdentity(output, news);
+          // State from 0.7 has no rootDir; the constructor always writes it.
+          const rootDir = news.rootDir ?? ".";
+          // Also here, so that a wrong rootDir stops the plan before Apply
+          // writes the new props to the row.
+          if (news.source !== undefined) yield* checkSource(rootDir, news.source);
+          // State from 0.7 has no rootDir, and another rootDir is another
+          // app directory. The update writes the props to state; it pushes
+          // only when the hash changed.
+          if (olds.rootDir !== rootDir) return { action: "update" } as const;
           const access = yield* accessFor(addressOf(news), changesEnv(news, output));
           // A preview expires, anyone can delete a deployment, and another
           // production deployment can become the default. Reconcile then
@@ -540,7 +616,7 @@ export const DeploymentProvider = () =>
           // URL of a deployment that is gone.
           const current = yield* live(access, output);
           if (current?.name !== output.name) return { action: "update" } as const;
-          const hash = yield* wantedHash(news, output.name);
+          const hash = yield* wantedHash(news, rootDir, output.name);
           return hash === output.hash
             ? ({ action: "noop" } as const)
             : ({ action: "update" } as const);
@@ -581,8 +657,10 @@ export const DeploymentProvider = () =>
         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);
-          // The functions directory and the program, before any change.
-          if (news.source !== undefined) yield* checkSource(news.source);
+          // The app directory, the functions directory, and the program,
+          // before any change.
+          const rootDir = news.rootDir ?? ".";
+          if (news.source !== undefined) yield* checkSource(rootDir, news.source);
           const address = addressOf(news);
           const access = yield* accessFor(address, changesEnv(news, output));
           const env = news.env ?? {};
@@ -597,7 +675,7 @@ export const DeploymentProvider = () =>
           const refuse = (name: string) =>
             new OwnedBySomeoneElse({
               message: `Project ${address.projectId} already has ${news.type} deployment ${name}${news.type === "prod" ? " with code" : ` named "${news.name}"`}. Re-run with --adopt to take it over${news.type === "prod" ? "" : ", or use another name"}.`,
-              resourceType: Deployment.Type,
+              resourceType: DeploymentResource.Type,
               physicalName: name,
             });
 
@@ -662,7 +740,7 @@ export const DeploymentProvider = () =>
           // Variables set on another deployment stay there: they are not ours
           // on this one.
           const previousEnvNames = output?.name === target.name ? envNamesOf(output) : [];
-          const before = yield* wantedHash(news, target.name);
+          const before = yield* wantedHash(news, rootDir, target.name);
           if (before === undefined && previousEnvNames.length === 0) {
             return { ...target, hash: undefined, envNames: [] };
           }
@@ -672,6 +750,7 @@ export const DeploymentProvider = () =>
           const options = {
             deployment: target.name,
             url: target.url,
+            rootDir,
             source: news.source,
             env,
             previousEnvNames,
@@ -719,7 +798,7 @@ export const DeploymentProvider = () =>
           // such as convex/_generated, are part of the identity.
           return {
             ...target,
-            hash: yield* wantedHash(news, target.name),
+            hash: yield* wantedHash(news, rootDir, target.name),
             envNames: Object.keys(env).sort(),
           };
         }),

package/src/Providers.ts

@@ -3,7 +3,7 @@
 import * as Provider from "alchemy/Provider";
 import * as Layer from "effect/Layer";
 import { type Credentials, fromConfig } from "./Credentials.ts";
-import { Deployment, DeploymentProvider } from "./Deployment.ts";
+import { DeploymentProvider, DeploymentResource } from "./Deployment.ts";
 import { ManagementApiLive } from "./ManagementApi.ts";
 import { Project, ProjectProvider } from "./Project.ts";
 
@@ -15,7 +15,7 @@ export class Providers extends Provider.ProviderCollection<Providers>()("Convex"
  * `CONVEX_DEPLOY_KEY`).
  */
 export const providers = (credentials: Layer.Layer<Credentials> = fromConfig()) =>
-  Layer.effect(Providers, Provider.collection([Project, Deployment])).pipe(
+  Layer.effect(Providers, Provider.collection([Project, DeploymentResource])).pipe(
     Layer.provide(Layer.mergeAll(ProjectProvider(), DeploymentProvider())),
     Layer.provide(ManagementApiLive()),
     Layer.provide(credentials),

package/src/Push.ts

@@ -48,13 +48,14 @@ import {
 export type EnvValue = string | Redacted.Redacted<string>;
 
 /**
- * The `source` prop: the Convex functions directory, such as `./convex`, or
- * that directory with a push command and more files for the content identity.
+ * The `source` prop: the Convex functions directory relative to the app
+ * directory (`rootDir`), such as `./convex`, or that directory with a push
+ * command and more files for the content identity.
  */
 export type Source =
   | string
   | {
-      /** The Convex functions directory, such as `./convex`. */
+      /** The Convex functions directory relative to the app directory, such as `./convex`. */
       readonly path: string;
       /**
        * Replaces `convex deploy`: a program and its arguments, run in the app
@@ -109,17 +110,20 @@ export class ConvexCliNotFound extends Schema.TaggedError<ConvexCliNotFound>()(
   { cwd: Schema.String },
 ) {
   override get message() {
-    return `Convex.Deployment found no installed convex package from ${this.cwd}, and it does not download one. Install convex in the app (npm install convex), or set source to the functions directory of the app.`;
+    return `Convex.Deployment found no installed convex package from ${this.cwd}, and it does not download one. Install convex in the app (npm install convex), or set rootDir to the directory of the app.`;
   }
 }
 
-/** No directory at or above the parent of `source` has a package.json. */
+/** The app directory (`rootDir`) has no package.json. */
 export class ConvexAppNotFound extends Schema.TaggedError<ConvexAppNotFound>()(
   "ConvexAppNotFound",
-  { source: Schema.String },
+  {
+    /** The app directory, resolved against the working directory of the deploy. */
+    rootDir: Schema.String,
+  },
 ) {
   override get message() {
-    return `Convex.Deployment found no package.json at or above the parent of ${this.source}. Set source to the functions directory of a Convex app, such as "./convex".`;
+    return `Convex.Deployment found no package.json in ${this.rootDir}. Set rootDir to the directory of the Convex app, relative to the directory where the deploy runs, such as "apps/web".`;
   }
 }
 
@@ -227,32 +231,27 @@ const outputTail = (text: string, secrets: readonly string[]) =>
 
 const valueOf = (value: EnvValue) => (Redacted.isRedacted(value) ? Redacted.value(value) : value);
 
-/** The app directory: the nearest directory at or above the parent of `source` with a package.json. */
-const appDirectoryOf = (source: string) =>
-  Effect.tryPromise({
-    try: async () => {
-      let directory = dirname(resolve(source));
-      while (true) {
-        try {
-          await access(join(directory, "package.json"));
-          return directory;
-        } catch {
-          const parent = dirname(directory);
-          if (parent === directory) throw new Error("no package.json");
-          directory = parent;
-        }
-      }
-    },
-    catch: () => new ConvexAppNotFound({ source }),
+/**
+ * The app directory: `rootDir` resolved against the working directory of the
+ * deploy. It must have a package.json. There is no search above it.
+ */
+const appDirectoryOf = (rootDir: string) => {
+  const directory = resolve(rootDir);
+  return Effect.tryPromise({
+    try: () => access(join(directory, "package.json")).then(() => directory),
+    catch: () => new ConvexAppNotFound({ rootDir: directory }),
   });
+};
 
-/** `source` is not the functions directory that the Convex CLI pushes from this app. */
+/** `source` is not the functions directory that the Convex CLI pushes from the app directory. */
 export class SourceMismatch extends Schema.TaggedError<SourceMismatch>()("SourceMismatch", {
+  /** The app directory, resolved. */
+  rootDir: Schema.String,
   source: Schema.String,
   functions: Schema.String,
 }) {
   override get message() {
-    return `Convex.Deployment source is ${this.source}, but the Convex CLI pushes ${this.functions} in this app (the "functions" field of convex.json, or convex/ by default). Set source to ${this.functions}.`;
+    return `Convex.Deployment source is ${this.source}, but the Convex CLI pushes ${this.functions} from the app directory ${this.rootDir} (the "functions" field of convex.json, or convex/ by default). Set rootDir to the directory of the Convex app, and source to its functions directory relative to rootDir, such as "./convex".`;
   }
 }
 
@@ -269,8 +268,8 @@ const checkFunctionsDirectory = (cwd: string, path: string) =>
         ? undefined
         : Schema.decodeUnknownSync(Schema.fromJsonString(ConvexJson))(text).functions;
     const functions = resolve(cwd, configured ?? "convex");
-    if (functions !== resolve(path)) {
-      return yield* new SourceMismatch({ source: resolve(path), functions });
+    if (functions !== path) {
+      return yield* new SourceMismatch({ rootDir: cwd, source: path, functions });
     }
   });
 
@@ -300,6 +299,8 @@ export const installedCli = (cwd: string) =>
  * A change in a workspace package outside the app directory is not seen.
  */
 export const pushHash = (options: {
+  /** The app directory, relative to the working directory of the deploy or absolute. */
+  readonly rootDir: string;
   readonly source: Source | undefined;
   readonly deployment: string;
   readonly env: Readonly<Record<string, EnvValue>>;
@@ -309,28 +310,32 @@ export const pushHash = (options: {
     const files =
       source === undefined
         ? undefined
-        : yield* appDirectoryOf(source.path).pipe(
-            Effect.flatMap((cwd) =>
-              hashDirectory({
+        : yield* appDirectoryOf(options.rootDir).pipe(
+            Effect.flatMap((cwd) => {
+              const functions = relative(cwd, resolve(cwd, source.path)).split("\\").join("/");
+              return hashDirectory({
                 cwd,
                 // By default every file of the app that git does not ignore,
-                // such as a module outside `source` that a function imports.
-                // `include` narrows it to the functions, the manifests, and
-                // the listed globs.
+                // such as a module outside `source` that a function imports,
+                // and the functions when convex.json puts them outside
+                // rootDir. `include` narrows it to the functions, the
+                // manifests, and the listed globs.
                 memo:
-                  source.include === undefined
-                    ? {}
-                    : {
+                  source.include !== undefined
+                    ? {
                         include: [
-                          `${relative(cwd, resolve(source.path)).split("\\").join("/")}/**`,
+                          `${functions}/**`,
                           "package.json",
                           "convex.json",
                           ...source.include,
                         ],
                         lockfile: true,
-                      },
-              }),
-            ),
+                      }
+                    : functions === ".." || functions.startsWith("../")
+                      ? { include: ["**/*", `${functions}/**`], lockfile: true }
+                      : {},
+              });
+            }),
           );
     const env = Object.entries(options.env)
       .map(([name, value]): readonly [string, string] => [name, valueOf(value)])
@@ -469,7 +474,9 @@ export interface PushOptions {
   readonly deployment: string;
   /** Client URL of the deployment. */
   readonly url: string;
-  /** The functions directory, or it with a push command. Without it, only the variables change. */
+  /** The app directory, relative to the working directory of the deploy or absolute. The push runs in it. */
+  readonly rootDir: string;
+  /** The functions directory relative to `rootDir`, or it with a push command. Without it, only the variables change. */
   readonly source: Source | undefined;
   readonly env: Readonly<Record<string, EnvValue>>;
   /** Names that an earlier push set on this deployment. Names that left `env` are removed. */
@@ -485,14 +492,14 @@ export interface PushOptions {
 
 /**
  * The app directory and the program of a push. Fails before any change when
- * `source` is not the functions directory of the app, or when the app has no
- * installed Convex CLI and no push command.
+ * `rootDir` has no package.json, when `source` is not the functions directory
+ * of the app, or when the app has no installed Convex CLI and no push command.
  */
-export const checkSource = (input: Source) =>
+export const checkSource = (rootDir: string, input: Source) =>
   Effect.gen(function* () {
     const source = sourceOf(input);
-    const cwd = yield* appDirectoryOf(source.path);
-    yield* checkFunctionsDirectory(cwd, source.path);
+    const cwd = yield* appDirectoryOf(rootDir);
+    yield* checkFunctionsDirectory(cwd, resolve(cwd, source.path));
     const program = source.command ?? (yield* installedCli(cwd));
     return { cwd, program };
   });
@@ -510,7 +517,10 @@ export const push = (
 ) =>
   Effect.gen(function* () {
     const source = options.source === undefined ? undefined : sourceOf(options.source);
-    const resolved = options.source === undefined ? undefined : yield* checkSource(options.source);
+    const resolved =
+      options.source === undefined
+        ? undefined
+        : yield* checkSource(options.rootDir, options.source);
     const cwd = resolved?.cwd;
     const program = resolved?.program;
     const env = Object.entries(options.env).sort(([a], [b]) => (a < b ? -1 : 1));

package/src/State.ts

@@ -270,6 +270,7 @@ const pushStore = (
       push(options.spawner, key, {
         deployment: deployment.name,
         url: deployment.deploymentUrl,
+        rootDir: join(options.store, ".."),
         source: {
           path: options.store,
           command: [...cli, "deploy", "--typecheck", "disable", "--codegen", "disable"],

package/src/index.ts

@@ -8,10 +8,12 @@ export {
   fromValues,
 } from "./Credentials.ts";
 export {
+  AbsoluteRootDir,
   AmbiguousDeployment,
   Deployment,
   type DeploymentAttributes,
   DeploymentIdentityChange,
+  type DeploymentInput,
   type DeploymentProps,
   ProductionDeploymentNotFound,
 } from "./Deployment.ts";