alchemy 2.0.0-beta.36 → 2.0.0-beta.38

package/src/Ref.ts

@@ -22,11 +22,16 @@ export interface RefMetadata<R extends ResourceLike> {
   stage?: string;
 }
 
-export const ref = <R extends ResourceLike>({
-  stack,
-  id,
-  stage,
-}: RefMetadata<R>): Ref<R> => {
+export const ref = <R extends ResourceLike>(
+  id: string,
+  {
+    stack,
+    stage,
+  }: {
+    stack?: string;
+    stage?: string;
+  } = {},
+): Ref<R> => {
   const ref = new Proxy(
     {},
     {

package/src/Resource.ts

@@ -7,6 +7,7 @@ import type { Input, InputProps } from "./Input.ts";
 import { CurrentNamespace, type NamespaceNode } from "./Namespace.ts";
 import * as Output from "./Output.ts";
 import { Provider } from "./Provider.ts";
+import { ref as makeRef } from "./Ref.ts";
 import { RemovalPolicy } from "./RemovalPolicy.ts";
 import { Self } from "./Self.ts";
 import { Stack } from "./Stack.ts";
@@ -47,6 +48,10 @@ export type ResourceClassWithMethods<
   Effect.Effect<ResourceConstructor<R>> & {
     Self: Self<R>;
     Provider: Provider<R>;
+    ref(
+      id: string,
+      options?: { stage?: string; stack?: string },
+    ): Effect.Effect<R>;
   } & Methods;
 
 export type ResourceClass<R extends ResourceLike> = ResourceConstructor<
@@ -56,6 +61,10 @@ export type ResourceClass<R extends ResourceLike> = ResourceConstructor<
   Effect.Effect<ResourceConstructor<R>> & {
     Self: Self<R>;
     Provider: Provider<R>;
+    ref(
+      id: string,
+      options?: { stage?: string; stack?: string },
+    ): Effect.Effect<R>;
   };
 
 export type LogicalId = string;
@@ -228,29 +237,6 @@ export function Resource<R extends ResourceLike>(
         [Symbol.toPrimitive](this: typeof target, hint: string) {
           return hint === "number" ? NaN : this.toString();
         },
-        // TODO(sam): figure out a better way to log things in cloudflare, this breaks indentation and is bloated
-        // [nodeInspect](
-        //   depth: number,
-        //   options: { depth?: number | null } & Record<string, unknown>,
-        //   inspect: (value: unknown, opts?: unknown) => string,
-        // ) {
-        //   if (depth < 0) {
-        //     return target.toString();
-        //   }
-        //   const nextDepth =
-        //     options.depth == null ? null : Math.max(0, options.depth - 1);
-        //   return inspect(
-        //     {
-        //       Type: target.Type,
-        //       Namespace: target.Namespace,
-        //       FQN: target.FQN,
-        //       LogicalId: target.LogicalId,
-        //       Props: target.Props,
-        //       RemovalPolicy: target.RemovalPolicy,
-        //     },
-        //     { ...options, depth: nextDepth },
-        //   );
-        // },
       };
 
       const Resource: R = (stack.resources[fqn] = new Proxy(target, {
@@ -276,16 +262,29 @@ export function Resource<R extends ResourceLike>(
 
   const Service = {
     [Symbol.iterator]() {
-      return new SingleShotGen(this);
+      return new SingleShotGen(this.asEffect());
     },
     pipe() {
-      return pipeArguments(this.asEffect(), arguments);
+      return pipeArguments(this, arguments);
     },
     asEffect() {
       return Effect.succeed((id: string, props: R["Props"]) =>
         constructor(id, props),
       );
     },
+    /**
+     * Build a typed reference to a deployed instance of this resource
+     * — in the current stack/stage by default, or in another via
+     * `options`. Resolves to the same shape as `yield*
+     * MyResource("id", props)` so downstream code can read attributes
+     * (`ref.someAttr`) exactly the way it would for a locally-declared
+     * resource.
+     */
+    ref: (
+      id: string,
+      options?: { stage?: string; stack?: string },
+    ): Effect.Effect<R> =>
+      Effect.succeed(Output.of(makeRef<R>(id, options)) as unknown as R),
     Type: type,
     Provider: ProviderTag,
     Self: self,

package/src/Runtime.ts

@@ -0,0 +1,38 @@
+/**
+ * Runtime helpers consumed by generated bundle entrypoints (Cloudflare
+ * Workers, Cloudflare Containers, AWS Lambda, …).
+ *
+ * Anything exported here runs *inside* the deployed function — keep the
+ * surface tiny and dependency-light.
+ */
+
+import * as Layer from "effect/Layer";
+
+/**
+ * Resolve the user's default-export entrypoint into a `Layer` for the
+ * bundled runtime.
+ *
+ * `entrypoint` may be any of:
+ *   - a `Layer` factory (`{ build: (...) => ... }`) — used as-is
+ *   - an effect-class with `asEffect()` (Alchemy `Platform`/`Worker` shape)
+ *   - a plain `Effect`
+ *
+ * Centralized so the inline ternary doesn't have to be re-emitted into
+ * every bundle template (and accidentally rewritten to `x : x` by a bulk
+ * replace, which silently swaps the class in for the Effect and bricks
+ * every deployed worker/lambda).
+ */
+export const makeEntrypointLayer = (
+  tag: any,
+  entrypoint: any,
+): Layer.Layer<any> => {
+  if (typeof entrypoint?.build === "function") {
+    return entrypoint;
+  }
+  return Layer.effect(
+    tag,
+    typeof entrypoint?.asEffect === "function"
+      ? entrypoint.asEffect()
+      : entrypoint,
+  );
+};

package/src/RuntimeContext.ts

@@ -14,6 +14,7 @@ export interface BaseRuntimeContext {
   exports?: Effect.Effect<Record<string, any>>;
   serve?<Req = never>(
     handler: HttpEffect<Req>,
+    options?: { shape?: Record<string, unknown> },
   ): Effect.Effect<void, never, Req>;
 }
 

package/src/Secret.ts

@@ -0,0 +1,87 @@
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import * as Output from "./Output.ts";
+
+/**
+ * The shapes a {@link secret} can be derived from.
+ *
+ * - `string` — wrapped in `Redacted.make` and bound as a literal.
+ * - `Redacted<string>` — bound as-is.
+ * - `Effect<string | Redacted<string>>` — resolved at deploy time.
+ * - `Config<string | Redacted<string>>` — resolved against the active
+ *   `ConfigProvider` at deploy time.
+ */
+export type SecretInput<R = never> =
+  | string
+  | Redacted.Redacted<string>
+  | Effect.Effect<string | Redacted.Redacted<string>, any, R>
+  | Config.Config<string | Redacted.Redacted<string>>;
+
+/**
+ * Bind a secret value into the active {@link RuntimeContext} (e.g. a
+ * Cloudflare Worker's `env`) under the given `name` so the resource
+ * provider deploys it as a secret (e.g. `secret_text` for Cloudflare).
+ *
+ * The result is an `Output<Redacted<string>>` — `yield*`-ing it returns
+ * an `Accessor<Redacted<string>>` that resolves the value at runtime.
+ *
+ * @example One-arg shortcut — reads `Config.redacted("API_KEY")`
+ * ```ts
+ * const apiKey = yield* Alchemy.Secret("API_KEY");
+ * ```
+ *
+ * @example From a literal
+ * ```ts
+ * const apiKey = yield* Alchemy.Secret("API_KEY", "sk-123");
+ * ```
+ *
+ * @example From an Effect
+ * ```ts
+ * const apiKey = yield* Alchemy.Secret(
+ *   "API_KEY",
+ *   Effect.succeed(Redacted.make("sk-123")),
+ * );
+ * ```
+ *
+ * @example From a Config
+ * ```ts
+ * const apiKey = yield* Alchemy.Secret("API_KEY", Config.redacted("API_KEY"));
+ * ```
+ */
+export function Secret(
+  name: string,
+): Output.Output<Redacted.Redacted<string>, never>;
+export function Secret<R = never>(
+  name: string,
+  value: SecretInput<R>,
+): Output.Output<Redacted.Redacted<string>, R>;
+export function Secret<R = never>(
+  name: string,
+  value?: SecretInput<R>,
+): Output.Output<Redacted.Redacted<string>, R> {
+  const source = value ?? Config.redacted(name);
+  const base = toOutput<string | Redacted.Redacted<string>, R>(source);
+  return Output.named(
+    base.pipe(
+      Output.map((v) => (Redacted.isRedacted(v) ? v : Redacted.make(v))),
+    ) as Output.Output<Redacted.Redacted<string>, R>,
+    name,
+  );
+}
+
+/** @internal */
+export const toOutput = <T, R = never>(
+  source: T | Effect.Effect<T, any, R> | Config.Config<T> | Output.Output<T, R>,
+): Output.Output<T, R> => {
+  if (Output.isOutput(source)) {
+    return source;
+  }
+  if (Config.isConfig(source)) {
+    return Output.asOutput(source as any) as Output.Output<T, R>;
+  }
+  if (Effect.isEffect(source)) {
+    return Output.asOutput(source as any) as Output.Output<T, R>;
+  }
+  return Output.asOutput(source as T) as Output.Output<T, R>;
+};

package/src/Serverless/Function.ts

@@ -3,7 +3,16 @@ import type { HttpEffect } from "../Http.ts";
 import type { BaseRuntimeContext } from "../RuntimeContext.ts";
 
 export interface FunctionContext extends BaseRuntimeContext {
-  serve<Req = never>(handler: HttpEffect<Req>): Effect.Effect<void, never, Req>;
+  /**
+   * Register an HTTP handler. The optional `shape` payload is the user's
+   * full default-export shape — Cloudflare Workers use it to expose
+   * non-handler methods (e.g. `greet`) as RPC methods on the deployed
+   * `WorkerEntrypoint`. Other platforms (Lambda, etc.) ignore it.
+   */
+  serve<Req = never>(
+    handler: HttpEffect<Req>,
+    options?: { shape?: Record<string, unknown> },
+  ): Effect.Effect<void, never, Req>;
   listen<A, Req = never>(
     handler: FunctionListener<A, Req>,
   ): Effect.Effect<void, never, Req>;

package/src/Stack.ts

@@ -6,7 +6,7 @@ import * as Layer from "effect/Layer";
 import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
 import { Path } from "effect/Path";
-import type { Scope } from "effect/Scope";
+import * as Scope from "effect/Scope";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 import type { HttpClient } from "effect/unstable/http/HttpClient";
 import type { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
@@ -18,19 +18,19 @@ import { Profile, ProfileLive } from "./Auth/Profile.ts";
 import { Cli } from "./Cli/Cli.ts";
 import type { Input, InputProps } from "./Input.ts";
 import * as Output from "./Output.ts";
-import { ref } from "./Ref.ts";
 import type { ResourceBinding, ResourceLike } from "./Resource.ts";
 import { Stage } from "./Stage.ts";
+import type { ActionLike } from "./Action.ts";
 import type { State } from "./State/State.ts";
 import { loadConfigProvider } from "./Util/ConfigProvider.ts";
-import { taggedFunction } from "./Util/effect.ts";
+import { effectClass, taggedFunction } from "./Util/effect.ts";
 import { fileLogger } from "./Util/FileLogger.ts";
 import { PlatformServices } from "./Util/PlatformServices.ts";
 
 export type StackServices =
   | Stack
   | Stage
-  | Scope
+  | Scope.Scope
   | FileSystem
   | Path
   | AlchemyContext
@@ -46,7 +46,7 @@ export type StackEffect<A, Err = never, Req = never> = Effect.Effect<
   Err,
   | PlatformServices
   | HttpClient
-  | Scope
+  | Scope.Scope
   | AuthProviders
   | AlchemyContext
   | Cli
@@ -98,6 +98,7 @@ export const Stack: Context.ServiceClass<
     (stackName: string): Effect.Effect<Self> & {
       new (_: never): Output.ToOutput<Shape>;
       make: <A, Req>(
+        options: StackProps<NoInfer<Req>>,
         effect: Effect.Effect<A, never, Req>,
       ) => Effect.Effect<CompiledStack<A>>;
       stage: {
@@ -114,36 +115,46 @@ export const Stack: Context.ServiceClass<
   taggedFunction(
     Context.Service<Stack, Omit<StackSpec, "output">>()("Stack"),
     <A, Req>(
-      stackName: string,
-      options: {
-        providers: Layer.Layer<NoInfer<Req>, never, StackServices>;
-        state: Layer.Layer<State, never, StackServices>;
-      },
-      eff: Effect.Effect<A, never, Req>,
-    ) =>
-      eff.pipe(
+      stackName?: string,
+      options?: StackProps<NoInfer<Req>>,
+      eff?: Effect.Effect<A, never, Req>,
+    ) => {
+      if (!stackName) {
+        return (stackName: string) =>
+          Object.assign(
+            // by default, reference the stack at the "current" stage of the importer
+            Output.stackRef<A>(stackName).pipe(effectClass),
+            {
+              stage: createStageProxy(stackName),
+              make: <Req = never>(
+                options: StackProps<NoInfer<Req>>,
+                eff: Effect.Effect<A, never, Req>,
+              ) => Stack(stackName, options, eff),
+            },
+          );
+      }
+      return eff!.pipe(
         make({
           name: stackName,
-          ...options,
+          ...options!,
         }),
         (eff) =>
           Object.assign(eff, {
-            stage: new Proxy(
-              {},
-              {
-                get: (_, stage: string) =>
-                  ref({
-                    stack: stackName,
-                    stage,
-                    id: stackName,
-                  }),
-              },
-            ),
+            stage: createStageProxy(stackName),
           }),
-      ),
+      );
+    },
   ),
 ) as any;
 
+const createStageProxy = (stackName: string) =>
+  new Proxy(
+    {},
+    {
+      get: (_, stage: string) => Output.stackRef(stackName, { stage }),
+    },
+  );
+
 export interface StackSpec<Output = any> {
   name: string;
   stage: string;
@@ -154,6 +165,10 @@ export interface StackSpec<Output = any> {
   bindings: {
     [logicalId: string]: ResourceBinding[];
   };
+  /** Tasks registered on the stack, keyed by FQN. */
+  actions: {
+    [logicalId: string]: ActionLike;
+  };
   output: Output;
 }
 
@@ -211,7 +226,7 @@ export const make =
           Layer.provideMerge(
             Layer.effect(
               Stack,
-              Stage.asEffect().pipe(
+              Stage.pipe(
                 Effect.map(
                   (stage) =>
                     options.stack ?? {
@@ -219,6 +234,7 @@ export const make =
                       stage,
                       resources: {},
                       bindings: {},
+                      actions: {},
                     },
                 ),
               ),
@@ -230,7 +246,7 @@ export const make =
       Effect.flatMap((context) =>
         Effect.all([
           effect,
-          Stack.asEffect(),
+          Stack,
           Effect.context<ROut | StackServices>(),
         ]).pipe(
           Effect.map(
@@ -249,7 +265,7 @@ export const make =
     );
 
 export const CurrentStack = Effect.serviceOption(Stack)
-  .asEffect()
+
   .pipe(Effect.map(Option.getOrUndefined));
 
 const platform = Layer.mergeAll(
@@ -268,9 +284,7 @@ const alchemy = (overrides?: { dev?: boolean }) =>
       ? Layer.provide(
           Layer.effect(
             AlchemyContext,
-            AlchemyContext.asEffect().pipe(
-              Effect.map((ctx) => ({ ...ctx, dev: overrides.dev! })),
-            ),
+            AlchemyContext.useSync((ctx) => ({ ...ctx, dev: overrides.dev! })),
           ),
           AlchemyContextLive,
         )
@@ -283,9 +297,18 @@ export const evalStack = <A, B, Err, Req>(
   options: {
     stage: string;
     dev?: boolean;
+    /**
+     * Optional caller-supplied scope. When provided, scoped resources
+     * (e.g. the dev sidecar process) live until the caller closes this
+     * scope instead of being torn down when `evalStack` resolves. Used
+     * by the test harness so the sidecar survives across `beforeAll`,
+     * tests, and `afterAll`. When omitted, behaves as before with a
+     * private scope closed on completion.
+     */
+    scope?: Scope.Scope;
   },
-) =>
-  Effect.gen(function* () {
+) => {
+  const body = Effect.gen(function* () {
     const stack = yield* effect;
     const configProvider = yield* loadConfigProvider(Option.none());
 
@@ -305,5 +328,9 @@ export const evalStack = <A, B, Err, Req>(
     ),
     Effect.provide(Layer.succeed(Stage, options.stage)),
     Effect.provide(Layer.provideMerge(alchemy({ dev: options.dev }), platform)),
-    Effect.scoped,
   );
+
+  return options.scope === undefined
+    ? Effect.scoped(body)
+    : Scope.provide(body, options.scope);
+};

package/src/State/ActionState.ts

@@ -0,0 +1,51 @@
+import type { NamespaceNode } from "../Namespace.ts";
+
+/**
+ * Persisted state for an {@link Action}. Actions share the same FQN
+ * namespace as resources but are discriminated by `kind: "action"`. The
+ * engine keys action state in the {@link State} store under the same `fqn`
+ * field as resources.
+ */
+export type ActionState = RunningActionState | RanActionState;
+
+export type ActionStatus = ActionState["status"];
+
+interface BaseActionState {
+  readonly kind: "action";
+  /** Type of the Action (e.g. "NightlySync"). Mirrors `resourceType` for resources. */
+  actionType: string;
+  /** Namespace of the Action. */
+  namespace: NamespaceNode | undefined;
+  /** Fully qualified name (namespace + logical id). */
+  fqn: string;
+  /** Logical id of the Action (stable across runs). */
+  logicalId: string;
+  /** Current status. */
+  status: ActionStatus;
+  /** FQNs of nodes that depend on this Action's output. */
+  downstream: string[];
+  /** Hash of the resolved input, used to skip noop runs. */
+  inputHash: string;
+  /** Resolved input snapshot from the most recent attempt. */
+  input: unknown;
+}
+
+/**
+ * The Action body has started but persistence after success has not yet
+ * occurred. On resume the engine treats this as "should run" since the
+ * effect may have completed but the output wasn't durably recorded.
+ */
+export interface RunningActionState extends BaseActionState {
+  status: "running";
+}
+
+/**
+ * The Action body completed and its output is durably persisted. Future
+ * plans skip the body when `inputHash` matches the new resolved input
+ * (unless `--force` is set).
+ */
+export interface RanActionState extends BaseActionState {
+  status: "ran";
+  /** Materialized output value returned by the Action body. */
+  output: unknown;
+}

package/src/State/HttpStateApi.ts

@@ -155,6 +155,25 @@ export const GetReplacedResources = HttpApiEndpoint.get(
   },
 );
 
+export const GetStackOutput = HttpApiEndpoint.get(
+  "getStackOutput",
+  "/state/stacks/:stack/stages/:stage/output",
+  {
+    params: StackStage,
+    success: Schema.UndefinedOr(ResourceStateSchema),
+  },
+);
+
+export const SetStackOutput = HttpApiEndpoint.put(
+  "setStackOutput",
+  "/state/stacks/:stack/stages/:stage/output",
+  {
+    params: StackStage,
+    payload: ResourceStateSchema,
+    success: ResourceStateSchema,
+  },
+);
+
 /** Response shape for the unauthenticated `/version` probe. */
 export const VersionResponse = Schema.Struct({
   version: Schema.Number,
@@ -179,6 +198,8 @@ export class StateGroup extends HttpApiGroup.make("state")
   .add(DeleteState)
   .add(GetReplacedResources)
   .add(DeleteStack)
+  .add(GetStackOutput)
+  .add(SetStackOutput)
   .middleware(StateAuth) {}
 
 export class VersionGroup extends HttpApiGroup.make("version").add(

package/src/State/HttpStateStore.ts

@@ -7,7 +7,11 @@ import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
 import { StateApi } from "./HttpStateApi.ts";
 
 import type { ReplacedResourceState, ResourceState } from "./ResourceState.ts";
-import { StateStoreError, type StateService } from "./State.ts";
+import {
+  StateStoreError,
+  type StateService,
+  type PersistedState,
+} from "./State.ts";
 import { encodeState, reviveStateRecursive } from "./StateEncoding.ts";
 
 /**
@@ -90,7 +94,7 @@ export const makeHttpStateStore = ({
           ),
           mapStateStoreError,
         ),
-      set: <V extends ResourceState>(request: {
+      set: <V extends PersistedState>(request: {
         stack: string;
         stage: string;
         fqn: string;
@@ -129,6 +133,27 @@ export const makeHttpStateStore = ({
             query: request.stage === undefined ? {} : { stage: request.stage },
           })
           .pipe(Effect.asVoid, mapStateStoreError),
+      getOutput: (request) =>
+        state
+          .getStackOutput({
+            params: { stack: request.stack, stage: request.stage },
+          })
+          .pipe(
+            Effect.map((s) =>
+              s == null ? undefined : reviveStateRecursive(s),
+            ),
+            mapStateStoreError,
+          ),
+      setOutput: (request) =>
+        state
+          .setStackOutput({
+            params: { stack: request.stack, stage: request.stage },
+            payload: encodeState(request.value as any),
+          })
+          .pipe(
+            Effect.map(() => request.value),
+            mapStateStoreError,
+          ),
     };
     return service;
   });