alchemy 2.0.0-beta.57 → 2.0.0-beta.58

package/src/Command/Dev.ts

@@ -0,0 +1,219 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as FiberMap from "effect/FiberMap";
+import * as Hash from "effect/Hash";
+import * as Stream from "effect/Stream";
+import { isResolved } from "../Diff.ts";
+import * as ProviderLayer from "../Local/ProviderLayer.ts";
+import * as RpcProvider from "../Local/RpcProvider.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import {
+  CommandError,
+  CommandExecutor,
+  UnexpectedExit,
+  type CommandProps,
+} from "./Command.ts";
+
+export interface DevProps extends CommandProps {}
+
+export interface Dev extends Resource<
+  "Command.Dev",
+  DevProps,
+  {
+    /**
+     * URL extracted from the first matching stdout/stderr line. Best-effort:
+     * `undefined` if no URL appears within 5 seconds.
+     */
+    url: string | undefined;
+  }
+> {}
+
+/**
+ * A long-lived shell process scoped to a stack instance, started during
+ * `alchemy dev` and restarted when its inputs change. During `alchemy deploy`
+ * this is a no-op — `Dev` resources only run in dev mode.
+ *
+ * The child process runs inside the dev sidecar (see `Command/Local.ts`) so it
+ * survives user-code HMR — Alchemy's user process can restart without killing
+ * your `npm run dev` server. Its stdout/stderr are mirrored to the terminal
+ * (preserving colored output) and each line is scanned for the first
+ * `http(s)://…` URL, which is exposed as the `url` output attribute — useful
+ * for surfacing a dev server's local URL back out to whatever resource
+ * declared this `Dev`.
+ *
+ * @resource
+ *
+ * @section Basic Usage
+ * Pass a shell command that starts a long-lived dev server. Alchemy
+ * runs it in the background and extracts the first URL it prints.
+ *
+ * @example Start a Vite dev server
+ * ```typescript
+ * const dev = yield* Dev("Frontend", {
+ *   command: "npm run dev",
+ * });
+ * yield* Console.log(dev.url); // e.g. "http://localhost:5173"
+ * ```
+ *
+ * @section Working Directory
+ * Use `cwd` to run the command in a subdirectory — useful in
+ * monorepos where each package has its own dev server.
+ *
+ * @example Monorepo package
+ * ```typescript
+ * const dev = yield* Dev("Web", {
+ *   command: "npm run dev",
+ *   cwd: "apps/web",
+ * });
+ * ```
+ *
+ * @section Environment Variables
+ * Extra environment variables are merged on top of `process.env`.
+ * Sensitive values can be wrapped in `Redacted` to keep them out
+ * of logs and state files.
+ *
+ * @example Custom port and env
+ * ```typescript
+ * const dev = yield* Dev("Api", {
+ *   command: "npm run dev",
+ *   env: {
+ *     PORT: "4000",
+ *     DATABASE_URL: Redacted.make("postgres://..."),
+ *   },
+ * });
+ * ```
+ */
+export const Dev = Resource<Dev>("Command.Dev");
+
+export const DevProvider = () =>
+  ProviderLayer.select({
+    live: DevProviderLive,
+    local: DevProviderLocal,
+  });
+
+export const DevProviderLive = () =>
+  Provider.succeed(Dev, {
+    list: () => Effect.succeed([]),
+    diff: () => Effect.succeed({ action: "noop" }),
+    reconcile: () => Effect.succeed({ url: undefined }),
+    delete: () => Effect.void,
+  });
+
+export const DevProviderLocal = () =>
+  RpcProvider.effect(
+    Dev,
+    import.meta.resolve(
+      import.meta.url.endsWith(".ts") ? "./Local.ts" : "./Local.js",
+      import.meta.url,
+    ),
+    Effect.gen(function* () {
+      const { spawn } = yield* CommandExecutor;
+      const map = yield* FiberMap.make();
+      const hashes = new Map<string, number>();
+
+      const spawnAndExtractResult = Effect.fn(function* (
+        props: DevProps,
+        urlDeferred: Deferred.Deferred<string | undefined, CommandError>,
+      ) {
+        const child = yield* spawn(props);
+
+        let buffer = "";
+        const deferred = yield* Deferred.make<string>();
+
+        const mirror = (sink: "stdout" | "stderr") =>
+          child[sink].pipe(
+            Stream.tap((chunk) =>
+              Effect.sync(() => process[sink].write(chunk)),
+            ),
+            Stream.decodeText,
+            Stream.tap((text) =>
+              Effect.sync(() => {
+                if (Deferred.isDoneUnsafe(deferred)) return;
+                buffer += text;
+                const url = extractUrl(buffer);
+                if (url) {
+                  Deferred.doneUnsafe(deferred, Effect.succeed(url));
+                }
+              }),
+            ),
+            Stream.runDrain,
+            Effect.forkScoped,
+          );
+
+        yield* mirror("stdout");
+        yield* mirror("stderr");
+        yield* Effect.raceAllFirst([
+          Deferred.await(deferred).pipe(
+            Effect.timeoutOrElse({
+              duration: "5 seconds",
+              orElse: () => Effect.undefined,
+            }),
+          ),
+          child.exitCode.pipe(
+            Effect.mapError(
+              (error) =>
+                new CommandError({
+                  command: props.command,
+                  reason: error.reason,
+                }),
+            ),
+            Effect.flatMap(
+              (exitCode) =>
+                new CommandError({
+                  command: props.command,
+                  reason: new UnexpectedExit({ exitCode, stderr: buffer }),
+                }),
+            ),
+          ),
+        ]).pipe(Deferred.into(urlDeferred));
+        return yield* child.exitCode;
+      }, Effect.scoped);
+
+      return {
+        list: () => Effect.succeed([]),
+        diff: Effect.fn(function* ({ instanceId, news }) {
+          if (!isResolved(news)) return undefined;
+          const hash = Hash.structure(news);
+          if (
+            hashes.get(instanceId) === hash &&
+            (yield* FiberMap.has(map, instanceId))
+          ) {
+            return { action: "noop" };
+          }
+          return { action: "update" };
+        }),
+        reconcile: Effect.fn(function* ({ instanceId, news }) {
+          const hash = Hash.structure(news);
+          hashes.set(instanceId, hash);
+          const deferred = yield* Deferred.make<
+            string | undefined,
+            CommandError
+          >();
+          yield* FiberMap.run(
+            map,
+            instanceId,
+            spawnAndExtractResult(news, deferred),
+            { propagateInterruption: true },
+          );
+          return { url: yield* Deferred.await(deferred) };
+        }),
+        delete: Effect.fn(function* ({ instanceId }) {
+          yield* FiberMap.remove(map, instanceId);
+          hashes.delete(instanceId);
+        }),
+      };
+    }),
+  );
+
+// Matches the first plain http(s) URL. Stops at whitespace and at a small
+// set of punctuation typically used to wrap URLs in log output.
+const URL_REGEX = /https?:\/\/[^\s)\],"'`]+/;
+
+// ECMA-262 ANSI/VT100 escape sequences — `Vite`, `Next`, etc. surround the
+// URL with color codes that would otherwise be eaten by the URL regex.
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /\x1b\[[0-9;]*m/g;
+
+const extractUrl = (text: string) =>
+  text.replaceAll(ANSI_REGEX, "").match(URL_REGEX)?.[0];

package/src/Command/Exec.ts

@@ -0,0 +1,121 @@
+import * as Effect from "effect/Effect";
+import { havePropsChanged, isResolved } from "../Diff.ts";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import { CommandExecutor, type CommandProps } from "./Command.ts";
+import { hashDirectory, type MemoOptions } from "./Memo.ts";
+
+export interface ExecProps extends CommandProps {
+  /**
+   * Controls which files are hashed to decide whether the command should
+   * re-run. By default every non-gitignored file in `cwd` is hashed, plus the
+   * nearest lockfile. Provide explicit globs to narrow the scope, or set
+   * `false` to disable memoization and re-run on every deploy.
+   *
+   * @see {@link MemoOptions}
+   * @default true
+   */
+  memo?: MemoOptions | boolean;
+}
+
+export interface Exec extends Resource<
+  "Command.Exec",
+  ExecProps,
+  {
+    /**
+     * Hash of the input files for this command, if memoization is enabled.
+     */
+    hash: {
+      input: string | undefined;
+    };
+  }
+> {}
+
+/**
+ * An `Exec` runs a shell command purely for its side effects — it has no
+ * output contract. Unlike `Build`, it does not produce or track an output
+ * asset; `reconcile` runs the command and the resource succeeds as long as the
+ * command exits with code `0` (a non-zero exit fails with a `CommandError`).
+ *
+ * Use it for one-off setup steps — running migrations, seeding data, code
+ * generation, or any command whose result lives outside Alchemy's state. By
+ * default the input files are content-hashed so the command only re-runs when
+ * its inputs (or `command`/`cwd`/`env`) change; set `memo: false` to re-run on
+ * every deploy.
+ *
+ * @resource
+ * @section Running a Command
+ * @example Run a One-Off Command
+ * ```typescript
+ * yield* Exec("codegen", {
+ *   command: "npm run codegen",
+ *   cwd: "./packages/api",
+ * });
+ * ```
+ *
+ * @section Running with Custom Environment
+ * @example Run Database Migrations
+ * ```typescript
+ * yield* Exec("migrate", {
+ *   command: "npm run db:migrate",
+ *   env: {
+ *     DATABASE_URL: Redacted.make("postgres://..."),
+ *   },
+ * });
+ * ```
+ *
+ * @section Memoizing Re-Runs
+ * @example Only Re-Run When Inputs Change
+ * ```typescript
+ * yield* Exec("codegen", {
+ *   command: "npm run codegen",
+ *   memo: { include: ["schema/**"] },
+ * });
+ * ```
+ */
+export const Exec = Resource<Exec>("Command.Exec");
+
+export const ExecProvider = () =>
+  Provider.effect(
+    Exec,
+    Effect.gen(function* () {
+      const { run } = yield* CommandExecutor;
+
+      return {
+        list: () => Effect.succeed([]),
+        diff: Effect.fn(function* ({ olds, news, output }) {
+          if (!output || !isResolved(news)) return undefined;
+
+          // Always update if memoization is disabled or input hash is not available.
+          if (news.memo === false || !output.hash.input)
+            return { action: "update" };
+
+          // Optimization: short-circuit if props have changed to avoid unnecessary file system operations.
+          if (havePropsChanged(olds, news)) return { action: "update" };
+
+          const newHash = yield* hashDirectory({
+            cwd: news.cwd,
+            memo: news.memo === true ? {} : news.memo,
+          });
+          return {
+            action: newHash === output.hash.input ? "noop" : "update",
+          };
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+          yield* run(news, session);
+          return {
+            hash: {
+              input:
+                news.memo === false
+                  ? undefined
+                  : yield* hashDirectory({
+                      cwd: news.cwd,
+                      memo: news.memo === true ? {} : news.memo,
+                    }),
+            },
+          };
+        }),
+        delete: () => Effect.void,
+      };
+    }),
+  );

package/src/Command/Local.ts

@@ -0,0 +1,6 @@
+import * as Layer from "effect/Layer";
+import * as RpcServer from "../Local/RpcServer.ts";
+import { CommandExecutorLive } from "./Command.ts";
+import { DevProviderLocal } from "./Dev.ts";
+
+DevProviderLocal().pipe(Layer.provide(CommandExecutorLive()), RpcServer.launch);

package/src/{Build → Command}/Memo.ts

@@ -54,7 +54,7 @@ const Memo = Effect.gen(function* () {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
 
-  const findUp = Effect.fnUntraced(function* (
+  const findUp = Effect.fn(function* (
     cwd: string,
     filenames: string[],
   ): Effect.fn.Return<string | undefined, PlatformError> {
@@ -73,7 +73,7 @@ const Memo = Effect.gen(function* () {
     return yield* findUp(parent, filenames);
   });
 
-  const readGitIgnoreRules = Effect.fnUntraced(function* (
+  const readGitIgnoreRules = Effect.fn(function* (
     cwd: string,
   ): Effect.fn.Return<string[], PlatformError> {
     const rules = yield* fs.readFileString(path.join(cwd, ".gitignore")).pipe(
@@ -91,7 +91,7 @@ const Memo = Effect.gen(function* () {
     return [...(yield* readGitIgnoreRules(parent)), ...rules];
   });
 
-  const resolveMemoOptions = Effect.fnUntraced(function* (
+  const resolveMemoOptions = Effect.fn(function* (
     cwd: string | undefined,
     options: MemoOptions,
   ): Effect.fn.Return<ResolvedMemoOptions, PlatformError> {
@@ -109,7 +109,7 @@ const Memo = Effect.gen(function* () {
     };
   });
 
-  const listFiles = Effect.fnUntraced(function* (
+  const listFiles = Effect.fn(function* (
     options: ResolvedMemoOptions,
   ): Effect.fn.Return<string[], PlatformError> {
     const [files, lockfile] = yield* Effect.all(
@@ -144,7 +144,7 @@ const Memo = Effect.gen(function* () {
     return files.sort();
   });
 
-  const hashFiles = Effect.fnUntraced(function* (
+  const hashFiles = Effect.fn(function* (
     cwd: string,
     files: string[],
   ): Effect.fn.Return<string, PlatformError> {

package/src/Command/Providers.ts

@@ -0,0 +1,41 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Provider from "../Provider.ts";
+import { Resource } from "../Resource.ts";
+import { BuildProvider } from "./Build.ts";
+import { CommandExecutorLive } from "./Command.ts";
+import { DevProvider } from "./Dev.ts";
+import { ExecProvider } from "./Exec.ts";
+
+export const providers = () =>
+  Layer.mergeAll(
+    BuildProvider(),
+    DevProvider(),
+    ExecProvider(),
+    // TODO: Remove before v2.0.0 stable release.
+    Renamed({ from: "Build.Command", to: "Command.Build" }),
+    Renamed({ from: "Build.DevServer", to: "Command.Dev" }),
+  ).pipe(Layer.provide(CommandExecutorLive()));
+
+/**
+ * Constructs a no-op provider for a resource that has been renamed.
+ * This prevents errors when attempting to tear down the old resource.
+ * The type is Layer.Layer<never> to avoid polluting the type signature.
+ */
+const Renamed = (input: { from: string; to: string }) => {
+  const message = (id: string) =>
+    `The "${input.from}" resource has been renamed to "${input.to}". Please update "${id}" to use the new resource.`;
+
+  return Provider.succeed(Resource(input.from), {
+    // The only one of these methods that would be called normally is `delete`, if you have an old version in state that needs to be removed.
+    // The other methods are defensive to prevent undefined behavior.
+    // You'll only end up calling these if you're using a `Build` resource manually;
+    // if you're using a `StaticSite` resource, the Alchemy engine migrates the old resource automatically.
+    diff: ({ id }) =>
+      Effect.logWarning(message(id)).pipe(Effect.as({ action: "noop" })),
+    precreate: ({ id }) => Effect.die(message(id)),
+    reconcile: ({ id }) => Effect.die(message(id)),
+    delete: () => Effect.void,
+    list: () => Effect.succeed([]),
+  }) as Layer.Layer<never>;
+};

package/src/Command/index.ts

@@ -0,0 +1,5 @@
+export * from "./Build.ts";
+export * from "./Command.ts";
+export * from "./Dev.ts";
+export * from "./Exec.ts";
+export * from "./Providers.ts";