alchemy 2.0.0-beta.65 → 2.0.0-beta.67

package/src/Command/Dev.ts

@@ -1,19 +1,17 @@
 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 LocalProvider from "../Local/LocalProvider.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,
+  makeCommandError,
   type CommandProps,
 } from "./Command.ts";
+import { makeCommandRedactor } from "./Redaction.ts";
 
 export interface DevProps extends CommandProps {}
 
@@ -90,7 +88,7 @@ export interface Dev extends Resource<
 export const Dev = Resource<Dev>("Command.Dev");
 
 export const DevProvider = () =>
-  ProviderLayer.select({
+  ProviderLayer.dual(Dev, {
     live: DevProviderLive,
     local: DevProviderLocal,
   });
@@ -104,7 +102,7 @@ export const DevProviderLive = () =>
   });
 
 export const DevProviderLocal = () =>
-  RpcProvider.effect(
+  LocalProvider.make(
     Dev,
     import.meta.resolve(
       import.meta.url.endsWith(".ts") ? "./Local.ts" : "./Local.js",
@@ -112,112 +110,86 @@ export const DevProviderLocal = () =>
     ),
     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 = "";
-        // A non-local URL seen so far (docs link, error page, update notice,
-        // …). Held as a fallback so that if the dev server never prints a
-        // localhost/IP URL we still surface something, but a localhost URL
-        // always wins if one shows up. See issue #695.
-        let fallbackUrl: string | undefined;
-        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) return;
-                if (isLocalUrl(url)) {
-                  // The dev server's own address — resolve immediately.
-                  Deferred.doneUnsafe(deferred, Effect.succeed(url));
-                } else {
-                  // Keep scanning: a localhost/IP URL may still appear.
-                  fallbackUrl = url;
-                }
-              }),
-            ),
-            Stream.runDrain,
-            Effect.forkScoped,
-          );
 
-        yield* mirror("stdout");
-        yield* mirror("stderr");
-        yield* Effect.raceAllFirst([
-          Deferred.await(deferred).pipe(
-            Effect.timeoutOrElse({
-              duration: "5 seconds",
-              // No localhost/IP URL appeared in time — fall back to any other
-              // URL we saw (or `undefined` if the process stayed silent).
-              orElse: () => Effect.succeed(fallbackUrl),
-            }),
-          ),
-          child.exitCode.pipe(
-            Effect.mapError(
-              (error) =>
-                new CommandError({
-                  command: props.command,
-                  reason: error.reason,
+      return {
+        // The dev process is spawned into the instance scope the helper
+        // provides: it keeps running after `start` returns (readiness) and
+        // is killed when the helper closes the scope on restart/delete.
+        start: Effect.fn(function* ({ news: props, invalidate }) {
+          const child = yield* spawn(props);
+          const redactor = makeCommandRedactor(props.env);
+
+          let buffer = "";
+          // A non-local URL seen so far (docs link, error page, update notice,
+          // …). Held as a fallback so that if the dev server never prints a
+          // localhost/IP URL we still surface something, but a localhost URL
+          // always wins if one shows up. See issue #695.
+          let fallbackUrl: string | undefined;
+          const deferred = yield* Deferred.make<string>();
+
+          const mirror = (sink: "stdout" | "stderr") =>
+            child[sink].pipe(
+              Stream.decodeText,
+              redactor.stream,
+              Stream.tap((text) =>
+                Effect.sync(() => process[sink].write(text)),
+              ),
+              Stream.tap((text) =>
+                Effect.sync(() => {
+                  if (Deferred.isDoneUnsafe(deferred)) return;
+                  buffer += text;
+                  const url = extractUrl(buffer);
+                  if (!url) return;
+                  if (isLocalUrl(url)) {
+                    // The dev server's own address — resolve immediately.
+                    Deferred.doneUnsafe(deferred, Effect.succeed(url));
+                  } else {
+                    // Keep scanning: a localhost/IP URL may still appear.
+                    fallbackUrl = url;
+                  }
                 }),
+              ),
+              Stream.runDrain,
+              Effect.forkScoped,
+            );
+
+          yield* mirror("stdout");
+          yield* mirror("stderr");
+
+          // Readiness: a URL appears (or the 5s budget elapses), unless the
+          // process exits first — an exit before readiness is a failure.
+          const url = yield* Effect.raceAllFirst([
+            Deferred.await(deferred).pipe(
+              Effect.timeoutOrElse({
+                duration: "5 seconds",
+                // No localhost/IP URL appeared in time — fall back to any
+                // other URL we saw (or `undefined` if it stayed silent).
+                orElse: () => Effect.succeed(fallbackUrl),
+              }),
             ),
-            Effect.flatMap(
-              (exitCode) =>
-                new CommandError({
-                  command: props.command,
-                  reason: new UnexpectedExit({ exitCode, stderr: buffer }),
-                }),
+            child.exitCode.pipe(
+              Effect.mapError((error) => makeCommandError(props, error.reason)),
+              Effect.flatMap((exitCode) =>
+                makeCommandError(
+                  props,
+                  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 },
+          ]);
+
+          // The process may die on its own after readiness (crash, manual
+          // kill). Drop it from the running registry so the next plan
+          // reports `update` and restarts it.
+          yield* child.exitCode.pipe(
+            Effect.exit,
+            Effect.flatMap(() => invalidate),
+            Effect.forkScoped,
           );
-          return { url: yield* Deferred.await(deferred) };
-        }),
-        delete: Effect.fn(function* ({ instanceId }) {
-          yield* FiberMap.remove(map, instanceId);
-          hashes.delete(instanceId);
+
+          return { url };
         }),
-      };
+      } satisfies LocalProvider.LocalProviderSpec<Dev>;
     }),
   );
 

package/src/Command/Exec.ts

@@ -2,10 +2,10 @@ 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 { CommandExecutor, type CommandRunProps } from "./Command.ts";
 import { hashDirectory, type MemoOptions } from "./Memo.ts";
 
-export interface ExecProps extends CommandProps {
+export interface ExecProps extends CommandRunProps {
   /**
    * 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
@@ -72,6 +72,15 @@ export interface Exec extends Resource<
  *   memo: { include: ["schema/**"] },
  * });
  * ```
+ *
+ * @section Bounding Command Runtime
+ * @example Time Out a Migration
+ * ```typescript
+ * yield* Exec("migrate", {
+ *   command: "npm run db:migrate",
+ *   timeout: "5 minutes",
+ * });
+ * ```
  */
 export const Exec = Resource<Exec>("Command.Exec");
 

package/src/Command/Memo.ts

@@ -16,10 +16,18 @@ import { sha256, sha256Object } from "../Util/sha256.ts";
  */
 export interface MemoOptions {
   /**
-   * Glob patterns of files to hash. Paths are relative to the working directory.
+   * Glob patterns of files to hash. Paths are relative to the working
+   * directory and may reach outside it with `../` segments — useful in a
+   * monorepo where the build consumes sibling workspace packages that the
+   * default (files under the working directory) does not cover.
+   *
+   * Note: providing `include` (or `exclude`) flips the {@link lockfile}
+   * default to `false` — pair it with `lockfile: true` to keep rebuilding
+   * when dependencies change.
    *
    * @default ["**\/*"] (all files, filtered by `exclude`)
    * @example ["src/**", "package.json", "tsconfig.json"]
+   * @example ["**\/*", "../env/src/**"] (also rebuild when a sibling workspace package changes)
    */
   include?: string[];
   /**
@@ -98,7 +106,16 @@ const Memo = Effect.gen(function* () {
     const resolvedCwd = cwd ? path.resolve(cwd) : process.cwd();
     return {
       cwd: resolvedCwd,
-      include: options.include ?? ["**/*"],
+      // Rewrite absolute include patterns to cwd-relative ones: fast-glob
+      // silently drops an absolute pattern's matches when the same call also
+      // contains relative patterns, and relative patterns keep the matched
+      // keys (and therefore the memo hash) free of machine-specific path
+      // prefixes.
+      include: (options.include ?? ["**/*"]).map((pattern) =>
+        path.isAbsolute(pattern)
+          ? path.relative(resolvedCwd, pattern).replaceAll("\\", "/")
+          : pattern,
+      ),
       exclude:
         options.exclude ??
         (yield* readGitIgnoreRules(resolvedCwd).pipe(
@@ -141,7 +158,14 @@ const Memo = Effect.gen(function* () {
     if (lockfile && !files.includes(lockfile)) {
       files.push(lockfile);
     }
-    return files.sort();
+    // Absolute include patterns produce absolute matches; normalize them to
+    // cwd-relative (like the lockfile above) so `hashFiles` resolves them
+    // correctly and machine-specific path prefixes never leak into the hash.
+    return files
+      .map((file) =>
+        path.isAbsolute(file) ? path.relative(options.cwd, file) : file,
+      )
+      .sort();
   });
 
   const hashFiles = Effect.fn(function* (

package/src/Command/Redaction.ts

@@ -0,0 +1,181 @@
+import * as Redacted from "effect/Redacted";
+import * as Stream from "effect/Stream";
+import { BadArgument, SystemError } from "effect/PlatformError";
+import type { CommandProps } from "./Command.ts";
+
+const DEFAULT_REDACTION_MARKER = "[REDACTED]";
+
+export interface CommandRedactor {
+  readonly redact: (value: string) => string;
+  readonly stream: <E, R>(
+    stream: Stream.Stream<string, E, R>,
+  ) => Stream.Stream<string, E, R>;
+}
+
+const redactedValues = (env: CommandProps["env"]): ReadonlyArray<string> =>
+  [
+    ...new Set(
+      Object.values(env ?? {})
+        .filter((value): value is Redacted.Redacted<string> =>
+          Redacted.isRedacted(value),
+        )
+        .map(Redacted.value)
+        .filter((value) => value.length > 0),
+    ),
+  ].sort((left, right) => right.length - left.length);
+
+const redactionMarker = (secrets: ReadonlyArray<string>): string => {
+  if (!secrets.some((secret) => DEFAULT_REDACTION_MARKER.includes(secret))) {
+    return DEFAULT_REDACTION_MARKER;
+  }
+
+  // The usual marker can itself be a secret (or contain a very short secret).
+  // Pick a single private-use character absent from every secret so replacing
+  // a value can never reproduce that exact value in output.
+  for (let codePoint = 0xe000; codePoint <= 0xf8ff; codePoint++) {
+    const candidate = String.fromCodePoint(codePoint);
+    if (secrets.every((secret) => !secret.includes(candidate))) {
+      return candidate;
+    }
+  }
+
+  // An env value containing the entire private-use block is pathological, but
+  // a supplementary private-use code point still gives us a safe marker.
+  for (let codePoint = 0xf0000; codePoint <= 0xffffd; codePoint++) {
+    const candidate = String.fromCodePoint(codePoint);
+    if (secrets.every((secret) => !secret.includes(candidate))) {
+      return candidate;
+    }
+  }
+
+  // This requires a secret larger than the full private-use character space.
+  // Keeping an empty replacement is safer than reproducing any part of it.
+  return "";
+};
+
+const redact = (
+  value: string,
+  secrets: ReadonlyArray<string>,
+  marker: string,
+): string =>
+  secrets.reduce((safe, secret) => safe.split(secret).join(marker), value);
+
+/**
+ * Redact a text stream without leaking secrets split across chunk boundaries.
+ * The pending suffix is always the longest suffix that could still grow into
+ * one of the configured secrets. Complete matches are replaced before any
+ * text is emitted.
+ */
+const redactStream = <E, R>(
+  stream: Stream.Stream<string, E, R>,
+  secrets: ReadonlyArray<string>,
+  marker: string,
+): Stream.Stream<string, E, R> => {
+  if (secrets.length === 0) return stream;
+
+  return stream.pipe(
+    Stream.mapAccum(
+      () => "",
+      (pending, chunk) => {
+        let remaining = pending + chunk;
+        let output = "";
+
+        while (remaining.length > 0) {
+          let matchIndex = -1;
+          let match: string | undefined;
+          for (const secret of secrets) {
+            const index = remaining.indexOf(secret);
+            if (
+              index >= 0 &&
+              (matchIndex < 0 ||
+                index < matchIndex ||
+                (index === matchIndex && secret.length > (match?.length ?? 0)))
+            ) {
+              matchIndex = index;
+              match = secret;
+            }
+          }
+
+          if (match !== undefined) {
+            output += remaining.slice(0, matchIndex) + marker;
+            remaining = remaining.slice(matchIndex + match.length);
+            continue;
+          }
+
+          let suffixLength = 0;
+          for (const secret of secrets) {
+            const candidateLength = Math.min(
+              secret.length - 1,
+              remaining.length,
+            );
+            for (
+              let length = candidateLength;
+              length > suffixLength;
+              length--
+            ) {
+              if (secret.startsWith(remaining.slice(-length))) {
+                suffixLength = length;
+                break;
+              }
+            }
+          }
+
+          output += remaining.slice(0, remaining.length - suffixLength);
+          remaining = remaining.slice(remaining.length - suffixLength);
+          break;
+        }
+
+        return [remaining, output.length === 0 ? [] : [output]] as const;
+      },
+      {
+        onHalt: (pending) =>
+          pending.length === 0 ? [] : [redact(pending, secrets, marker)],
+      },
+    ),
+  );
+};
+
+export const makeCommandRedactor = (
+  env: CommandProps["env"],
+): CommandRedactor => {
+  const secrets = redactedValues(env);
+  const marker = redactionMarker(secrets);
+  return {
+    redact: (value) => redact(value, secrets, marker),
+    stream: (stream) => redactStream(stream, secrets, marker),
+  };
+};
+
+export const redactPlatformReason = (
+  reason: BadArgument | SystemError,
+  redactor: CommandRedactor,
+): BadArgument | SystemError => {
+  if (reason instanceof BadArgument) {
+    return new BadArgument({
+      module: redactor.redact(reason.module),
+      method: redactor.redact(reason.method),
+      description:
+        reason.description === undefined
+          ? undefined
+          : redactor.redact(reason.description),
+    });
+  }
+
+  return new SystemError({
+    _tag: reason._tag,
+    module: redactor.redact(reason.module),
+    method: redactor.redact(reason.method),
+    description:
+      reason.description === undefined
+        ? undefined
+        : redactor.redact(reason.description),
+    syscall:
+      reason.syscall === undefined
+        ? undefined
+        : redactor.redact(reason.syscall),
+    pathOrDescriptor:
+      typeof reason.pathOrDescriptor === "string"
+        ? redactor.redact(reason.pathOrDescriptor)
+        : reason.pathOrDescriptor,
+  });
+};

package/src/Destroy.ts

@@ -22,15 +22,6 @@ export const destroy = ({
 }) =>
   evalStack(
     stack,
-    (stack) =>
-      Plan.make({
-        ...stack,
-        // zero these out (destroy will treat all as orphans)
-        // TODO(sam): probably better to have Plan.destroy and Plan.update
-        resources: {},
-        bindings: {},
-        actions: {},
-        output: {},
-      }).pipe(Effect.flatMap(Apply.apply)),
+    (stack) => Plan.destroy(stack).pipe(Effect.flatMap(Apply.apply)),
     { stage, dev, scope },
   );

package/src/Docker/Container.ts

@@ -9,12 +9,14 @@ import * as Provider from "../Provider.ts";
 import { Resource } from "../Resource.ts";
 import { createInternalTags, hasAlchemyTags } from "../Tags.ts";
 import { toSeconds } from "../Util/Duration.ts";
-import { Docker, dockerPhysicalName } from "./Docker.ts";
+import { Docker, dockerContextName, dockerPhysicalName } from "./Docker.ts";
 import type { Providers } from "./Providers.ts";
 
 export interface ContainerProps {
   /** Image reference or Docker image resource. */
   image: Container.Image;
+  /** Docker context name or context resource. */
+  context?: Docker.ContextRef;
   /**
    * Container name.
    *
@@ -187,6 +189,18 @@ export interface Container extends Resource<
  *   stopTimeout: "30 seconds",
  *   start: true,
  * });
+ *
+ * @example Use a Docker.Context resource
+ * ```typescript
+ * const remote = yield* Docker.Context("remote", {
+ *   name: "remote-build",
+ *   docker: "host=ssh://docker@example.com",
+ * });
+ *
+ * const api = yield* Docker.Container("api", {
+ *   image: "nginx:alpine",
+ *   context: remote,
+ * });
  * ```
  */
 export const Container = Resource<Container>("Docker.Container");
@@ -199,9 +213,12 @@ export const Container = Resource<Container>("Docker.Container");
  */
 export const inspectContainer = (
   name: string,
+  context?: Docker.ContextRef,
 ): Effect.Effect<Container["Attributes"], PlatformError, Docker> =>
   Docker.pipe(
-    Effect.flatMap((docker) => docker.container.inspect(name)),
+    Effect.flatMap((docker) =>
+      docker.container.inspect(name, dockerContextName(context)),
+    ),
     Effect.map((container) =>
       toContainerAttributes(container, container.Config.Image),
     ),
@@ -217,6 +234,7 @@ export const ContainerProvider = () =>
         live: Docker.Container,
         news: ContainerProps,
       ) {
+        const context = dockerContextName(news.context);
         const connect = new Map<string, Container.NetworkMapping>();
         const disconnect = new Set<string>();
         const noop = new Set<string>();
@@ -241,7 +259,7 @@ export const ContainerProvider = () =>
         yield* Effect.forEach(
           disconnect,
           (network) =>
-            docker.network.disconnect({ network, container: live.Id }),
+            docker.network.disconnect({ network, container: live.Id, context }),
           { concurrency: "unbounded" },
         );
         yield* Effect.forEach(
@@ -251,6 +269,7 @@ export const ContainerProvider = () =>
               network: network.name,
               container: live.Id,
               alias: network.aliases,
+              context,
             }),
           { concurrency: "unbounded" },
         );
@@ -259,9 +278,10 @@ export const ContainerProvider = () =>
       return Container.Provider.of({
         list: () => Effect.succeed([]),
         read: Effect.fn(function* ({ id, instanceId, olds, output }) {
+          const context = dockerContextName(olds.context);
           const name = yield* dockerPhysicalName(id, olds, instanceId);
           const info = yield* docker.container
-            .inspect(name)
+            .inspect(name, context)
             .pipe(
               Effect.catchReason(
                 "PlatformError",
@@ -294,6 +314,11 @@ export const ContainerProvider = () =>
           // round-trip (it deserializes as `undefined`) — without comparable
           // prior create args, let the engine apply its default update logic.
           if (olds.image === undefined) return undefined;
+          if (
+            dockerContextName(olds.context) !== dockerContextName(news.context)
+          ) {
+            return { action: "replace" as const, deleteFirst: true };
+          }
           const oldArgs = yield* makeCreateArgs(id, olds, instanceId);
           const newArgs = yield* makeCreateArgs(id, news, instanceId);
           if (!Equal.equals(oldArgs, newArgs)) {
@@ -307,9 +332,10 @@ export const ContainerProvider = () =>
           }
         }),
         reconcile: Effect.fn(function* ({ id, instanceId, news }) {
+          const context = dockerContextName(news.context);
           const args = yield* makeCreateArgs(id, news, instanceId);
           const live = yield* docker.container
-            .inspect(args.name)
+            .inspect(args.name, context)
             .pipe(
               Effect.catchReason(
                 "PlatformError",
@@ -321,12 +347,12 @@ export const ContainerProvider = () =>
           if (live) {
             yield* reconcileNetworks(live, news);
             if (news.start && live.State.Status !== "running") {
-              yield* docker.container.start(live.Id);
+              yield* docker.container.start(live.Id, context);
             } else if (!news.start && live.State.Status === "running") {
-              yield* docker.container.stop(live.Id);
+              yield* docker.container.stop(live.Id, context);
             }
             return yield* docker.container
-              .inspect(live.Id)
+              .inspect(live.Id, context)
               .pipe(
                 Effect.map((info) => toContainerAttributes(info, args.image)),
               );
@@ -335,6 +361,7 @@ export const ContainerProvider = () =>
           const internalTags = yield* createInternalTags(id);
           const { stdout: containerId } = yield* docker.container.create({
             ...args,
+            context,
             label: { ...args.label, ...internalTags },
           });
           yield* Effect.forEach(
@@ -344,20 +371,33 @@ export const ContainerProvider = () =>
                 network: network.name,
                 container: containerId,
                 alias: network.aliases,
+                context,
               }),
             { concurrency: "unbounded" },
           );
           if (news.start) {
-            yield* docker.container.start(containerId);
+            yield* docker.container.start(containerId, context);
           }
-          const info = yield* docker.container.inspect(containerId);
+          const info = yield* docker.container.inspect(containerId, context);
           return toContainerAttributes(info, args.image);
         }),
-        delete: Effect.fn(({ output }) =>
-          docker.container.stop(output.name).pipe(
-            Effect.andThen(docker.container.remove(output.name, true)),
-            Effect.catchReason("PlatformError", "NotFound", () => Effect.void),
-          ),
+        delete: Effect.fn(({ olds, output }) =>
+          docker.container
+            .stop(output.name, dockerContextName(olds.context))
+            .pipe(
+              Effect.andThen(
+                docker.container.remove(
+                  output.name,
+                  true,
+                  dockerContextName(olds.context),
+                ),
+              ),
+              Effect.catchReason(
+                "PlatformError",
+                "NotFound",
+                () => Effect.void,
+              ),
+            ),
         ),
       });
     }),