@alchemy.run/test 0.0.0-stage → 2.0.0-beta.85

package/src/Vitest.ts

@@ -0,0 +1,239 @@
+/** @effect-diagnostics anyUnknownInErrorContext:off */
+import { it } from "@effect/vitest";
+import type { AlchemyContext } from "alchemy/AlchemyContext";
+import type { CompiledStack, StackDefinition } from "alchemy/Stack";
+import type { Stage } from "alchemy/Stage";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import {
+  afterAll as vitestAfterAll,
+  afterEach as vitestAfterEach,
+  beforeAll as vitestBeforeAll,
+  beforeEach as vitestBeforeEach,
+} from "vitest";
+import * as Core from "./Core.ts";
+
+export {
+  executeWhenReady,
+  getWhenReady,
+  guardContentType,
+  guardedFetchLayer,
+  rpcClientLayer,
+  WorkerNotReady,
+  type EdgeGuardOptions,
+  type WhenReadyOptions,
+} from "./Http.ts";
+
+export type MakeOptions<ROut = any> = Core.MakeOptions<ROut>;
+export type ScratchStack = Core.ScratchStack;
+export type TestEffect<A, R = never> = Core.TestEffect<A, R>;
+export const defaultStage = Core.defaultStage;
+export const resolveStage = Core.resolveStage;
+
+type TestOptions = number | { timeout?: number };
+
+const timeoutOf = (opts: TestOptions | undefined): number | undefined =>
+  typeof opts === "number" ? opts : opts?.timeout;
+
+interface TestFn {
+  (name: string, eff: TestEffect<void>, options?: TestOptions): void;
+  skip: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  skipIf: (
+    condition: boolean,
+  ) => (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  only: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  todo: (name: string, eff: TestEffect<void>, options?: TestOptions) => void;
+  provider: ProviderFn;
+}
+
+interface ProviderFn {
+  (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ): void;
+  skip: (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ) => void;
+  skipIf: (
+    condition: boolean,
+  ) => (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+    options?: TestOptions,
+  ) => void;
+}
+
+interface BeforeAllFn {
+  <A>(eff: TestEffect<A>, options?: TestOptions): Effect.Effect<A>;
+}
+
+interface BeforeEachFn {
+  (eff: TestEffect<void>, options?: TestOptions): void;
+}
+
+interface AfterAllFn {
+  (eff: TestEffect<any>, options?: TestOptions): void;
+  skipIf: (predicate: boolean) => (eff: TestEffect<any>, options?: TestOptions) => void;
+}
+
+interface AfterEachFn {
+  (eff: TestEffect<void>, options?: TestOptions): void;
+}
+
+export interface TestApi {
+  test: TestFn;
+  beforeAll: BeforeAllFn;
+  beforeEach: BeforeEachFn;
+  afterAll: AfterAllFn;
+  afterEach: AfterEachFn;
+  deploy: Core.Deploy;
+  destroy: <ROut>(
+    stack: StackDefinition<ROut>,
+    options?: { stage?: string; include?: never; exclude?: never },
+  ) => ReturnType<typeof Core.destroy>;
+}
+
+const DEFAULT_TIMEOUT = 120_000;
+
+/**
+ * Build the per-file test API. See {@link "./Bun.ts"} for the same shape
+ * over `bun:test`. Vitest variant uses `@effect/vitest`'s `it.live` so
+ * Effect-aware tests stay first-class.
+ */
+export const make = <ROut = any>(options: MakeOptions<ROut>): TestApi => {
+  // See `Test/Bun.ts` for the rationale: the dev sidecar must outlive a
+  // single `runPromise` boundary, so all hooks share one scope that's only
+  // closed after `destroy(...)` runs.
+  const sharedScope = Scope.makeUnsafe("sequential");
+  // In dev mode, run local providers behind one file-scoped RPC sidecar
+  // (the `alchemy dev` topology). Lives in its own scope — NOT sharedScope,
+  // which `destroy(Stack)` closes mid-file in self-contained tests — and is
+  // closed by the fallback afterAll below.
+  const sidecar = Core.makeSidecarHandle(options);
+  const wrap = <A>(eff: TestEffect<A>) => Core.toEffect(eff, options, sharedScope, sidecar);
+  const runEff = <A>(eff: TestEffect<A>) => Core.run(eff, options, sharedScope, sidecar);
+
+  const test = ((name, eff, opts) => {
+    it.live(name, () => wrap(eff), timeoutOf(opts));
+  }) as TestFn;
+
+  test.skip = (name, _eff, opts) => {
+    it.skip(name, () => {}, timeoutOf(opts));
+  };
+  test.skipIf = (condition) => (name, eff, opts) => {
+    if (condition) {
+      it.skip(name, () => {}, timeoutOf(opts));
+    } else {
+      it.live(name, () => wrap(eff), timeoutOf(opts));
+    }
+  };
+  test.only = (name, eff, opts) => {
+    it.live.only(name, () => wrap(eff), timeoutOf(opts));
+  };
+  test.todo = (name, _eff, _opts) => {
+    it.todo(name);
+  };
+
+  const wrapProvider = (
+    name: string,
+    fn: (stack: ScratchStack) => Effect.Effect<void, any, any>,
+  ) => {
+    const scratch = Core.scratchStack(options, name);
+    // Guarantee teardown. `test.provider` has no built-in cleanup, so a body
+    // that fails (assertion, API error like a 409/Unauthorized) or is
+    // interrupted (vitest timeout) BEFORE its trailing `stack.destroy()` would
+    // otherwise leak every cloud resource it deployed: the scratch's in-memory
+    // state is discarded with the process, so no later run can reclaim the
+    // orphan (only an account-wide `nuke` can). `scratch.destroy()` is
+    // idempotent (empty-plan apply against the shared scratch state) — a no-op
+    // when the body already destroyed, and it reclaims the orphans otherwise.
+    // `Effect.ensuring` runs the finalizer on success, failure, AND interruption.
+    const body = Core.withProviders(fn(scratch), options, scratch.name).pipe(
+      Effect.ensuring(scratch.destroy().pipe(Effect.ignore)),
+    );
+    return Core.toEffect(body, { ...options, state: scratch.state }, sharedScope, sidecar);
+  };
+
+  const provider = ((name, fn, opts) => {
+    it.live(name, () => wrapProvider(name, fn), timeoutOf(opts));
+  }) as ProviderFn;
+  provider.skip = (name, _fn, opts) => {
+    it.skip(name, () => {}, timeoutOf(opts));
+  };
+  provider.skipIf = (condition) => (name, fn, opts) => {
+    if (condition) {
+      it.skip(name, () => {}, timeoutOf(opts));
+    } else {
+      it.live(name, () => wrapProvider(name, fn), timeoutOf(opts));
+    }
+  };
+  test.provider = provider;
+
+  const beforeAll: BeforeAllFn = <A>(eff: TestEffect<A>, hookOptions?: TestOptions) => {
+    let result: A;
+    vitestBeforeAll(
+      () => runEff(eff).then((v) => (result = v)),
+      timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+    );
+    return Effect.sync(() => result);
+  };
+
+  const beforeEach: BeforeEachFn = (eff, hookOptions) => {
+    vitestBeforeEach(() => runEff(eff), timeoutOf(hookOptions));
+  };
+
+  const afterAll = ((eff, hookOptions) => {
+    vitestAfterAll(() => runEff(eff), timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT);
+  }) as AfterAllFn;
+  afterAll.skipIf = (predicate) => (eff, hookOptions) => {
+    if (predicate) return;
+    vitestAfterAll(() => runEff(eff), timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT);
+  };
+
+  const afterEach: AfterEachFn = (eff, hookOptions) => {
+    vitestAfterEach(() => runEff(eff), timeoutOf(hookOptions));
+  };
+
+  // `destroy(Stack)` needs the dev sidecar alive so it can call `sidecar.stop`.
+  // `Scope.close` on an already-closed scope is a no-op, so the destroy
+  // wrapper AND the fallback cleanup hook below can both call it safely.
+  const closeScope = Effect.suspend(() => Scope.close(sharedScope, Exit.void)).pipe(Effect.ignore);
+
+  // Fallback cleanup: if the user never calls `destroy(Stack)` (e.g.
+  // `NO_DESTROY=1`), nothing else closes the shared scope and the sidecar
+  // child process leaks past the test process. The RPC sidecar lives in its
+  // own scope so that mid-file `destroy(Stack)` calls can't kill it for later
+  // tests.
+  //
+  // The cleanup must run after every user `afterAll` (including
+  // `destroy(Stack)`, which needs the sidecar). Vitest's default
+  // `sequence.hooks: "stack"` runs `afterAll` hooks in reverse registration
+  // order and `"list"` runs them in registration order, so register the
+  // cleanup both before (now) and after (next microtask) the file's
+  // `afterAll` calls, and only close on the second invocation: whichever
+  // order is configured, that one runs last.
+  const closeAll = sidecar ? Effect.andThen(closeScope, sidecar.close) : closeScope;
+  let cleanupCalls = 0;
+  const cleanup = () => (++cleanupCalls === 2 ? Effect.runPromise(closeAll) : undefined);
+  vitestAfterAll(cleanup, DEFAULT_TIMEOUT);
+  queueMicrotask(() => {
+    vitestAfterAll(cleanup, DEFAULT_TIMEOUT);
+  });
+
+  return {
+    test,
+    beforeAll,
+    beforeEach,
+    afterAll,
+    afterEach,
+    deploy: Core.makeDeploy(options, sharedScope),
+    destroy: (stack, callOpts) =>
+      Core.destroy(options, stack, { ...callOpts, scope: sharedScope }).pipe(
+        Effect.ensuring(closeScope),
+      ),
+  };
+};

package/src/WorktreeStage.ts

@@ -0,0 +1,45 @@
+import { userStage } from "alchemy/Cli/commands/flags";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+
+/**
+ * The name of the linked git worktree containing `cwd`, or `undefined` in a
+ * main checkout (or outside git). A linked worktree's `.git` is a file
+ * pointing at `<common>/.git/worktrees/<name>`; a submodule's points at
+ * `.git/modules/<name>` and doesn't count.
+ */
+export const worktreeName = Effect.fn(function* (cwd: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  let dir = cwd;
+  while (true) {
+    const dotGit = path.join(dir, ".git");
+    if (yield* fs.exists(dotGit)) {
+      const info = yield* fs.stat(dotGit);
+      if (info.type !== "File") return undefined;
+      const gitdir = /^gitdir:\s*(.+)$/m.exec(yield* fs.readFileString(dotGit))?.[1]?.trim();
+      const parts = gitdir?.split(/[\\/]+/).filter(Boolean) ?? [];
+      return parts.at(-2) === "worktrees" ? parts.at(-1) : undefined;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+});
+
+/**
+ * The default test stage for a linked worktree: `test_$USER_<worktree>`, so
+ * concurrent runs from two worktrees of one developer never share
+ * deployments. `undefined` in a main checkout, which keeps `test_$USER`.
+ */
+export const worktreeStage = Effect.fn(function* (cwd: string) {
+  const name = yield* worktreeName(cwd).pipe(Effect.orElseSucceed(() => undefined));
+  if (name === undefined) return undefined;
+  const safe = name
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (safe === "") return undefined;
+  return `${yield* userStage("test")}_${safe}`;
+});

package/src/cli.ts

@@ -0,0 +1,330 @@
+/**
+ * The `alchemy-test` CLI.
+ *
+ * ```sh
+ * alchemy-test [paths...] [-t pattern] [--exclude path]... [--timeout ms]
+ *              [--retry n] [--concurrency n] [--sequential] [--tui]
+ *              [--profile name] [--stage name] [--fast]
+ *              [--tags 'unit || (e2e && !live)']
+ * ```
+ *
+ * Runs every `*.test.ts` under the given paths (default `./test`) in a single
+ * bun process. Interactive terminals get the opentui view; otherwise tests
+ * are logged line-by-line and failures are dumped at the end.
+ */
+// The runner executes every test file's effects on ONE event loop, so any
+// fiber touching a relative path can race a transient process-wide chdir.
+// cross-spawn (bundled in vite/build tools the tests exercise) chdirs the
+// whole process to resolve a spawn's binary; `process.chdir.disabled` is
+// its own escape hatch (built for worker threads) — with it set, commands
+// still resolve via PATH and absolutize against the spawn's `cwd`.
+(process.chdir as { disabled?: boolean }).disabled = true;
+
+import * as BunRuntime from "@effect/platform-bun/BunRuntime";
+import * as BunServices from "@effect/platform-bun/BunServices";
+import * as Argument from "effect/cli/Argument";
+import * as Command from "effect/cli/Command";
+import * as Flag from "effect/cli/Flag";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Runtime from "effect/Runtime";
+import * as Schema from "effect/Schema";
+import packageJson from "../package.json" with { type: "json" };
+import { PlainReporterLive, printSummary } from "./PlainReporter.ts";
+import { parsePlan } from "./Plan.ts";
+import { Reporter } from "./Reporter.ts";
+import { run, type RunOptions } from "./Runner.ts";
+import { captureStrayOutput } from "./StrayOutput.ts";
+import { worktreeStage } from "./WorktreeStage.ts";
+
+const paths = Argument.String("paths").pipe(
+  Argument.withDescription("Test files or directories (default: ./test)"),
+  Argument.variadic(),
+);
+
+const testNamePattern = Flag.String("test-name-pattern").pipe(
+  Flag.withAlias("t"),
+  Flag.withDescription("Only run tests whose title matches this regex"),
+  Flag.optional,
+);
+
+const exclude = Flag.String("exclude").pipe(
+  Flag.withDescription(
+    "Skip test files under this path (repeatable). Existing files/directories exclude by prefix; anything else is a case-insensitive substring filter. Explicitly passing an excluded path as a positional argument overrides the exclusion.",
+  ),
+  Flag.atLeast(0),
+);
+
+const tagsFilter = Flag.String("tags").pipe(
+  Flag.withDescription(
+    'Select tags using &&, ||, !, parentheses and * wildcards (e.g. "e2e && provider:aws && !slow"). Repeated filters are ANDed.',
+  ),
+  Flag.atLeast(0),
+);
+
+const plan = Flag.String("plan").pipe(
+  Flag.withDescription(
+    "JSON array of sequential phases; nested arrays run branches in parallel. Each branch has tags (ANDed expressions) and optional file concurrency. First match wins; shared hooks live until the file's final phase.",
+  ),
+  Flag.optional,
+);
+
+const dryRun = Flag.Boolean("dry-run").pipe(
+  Flag.withDescription("Collect tests and show the execution plan without running tests or hooks"),
+  Flag.withDefault(false),
+);
+
+const timeout = Flag.Int("timeout").pipe(
+  Flag.withDescription("Default per-test timeout in milliseconds"),
+  Flag.withDefault(120_000),
+);
+
+const retry = Flag.Int("retry").pipe(
+  Flag.withDescription("Times a failing test is retried before failing the run"),
+  Flag.withDefault(2),
+);
+
+const concurrency = Flag.String("concurrency").pipe(
+  Flag.withAlias("c"),
+  Flag.withDescription(
+    'Maximum number of files running concurrently: a number (default 32) or "unbounded". Unbounded runs of large suites saturate the event loop and drown real failures in spurious 0ms beforeAll timeouts.',
+  ),
+  Flag.withDefault("32"),
+);
+
+const toConcurrency = (value: string): number | "unbounded" => {
+  if (value === "unbounded") return "unbounded";
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    throw new Error(`--concurrency must be a positive integer or "unbounded", got: ${value}`);
+  }
+  return parsed;
+};
+
+/** `--tui` was requested but the optional `@opentui/core` peer isn't installed. */
+class TuiUnavailable extends Data.TaggedError("TuiUnavailable")<{
+  readonly message: string;
+  readonly cause: unknown;
+}> {}
+
+// The TUI's renderer (`@opentui/core`) is an optional peer, so it loads only
+// when `--tui` asks for it.
+const tuiReporter = (logFile: string) =>
+  Layer.unwrap(
+    Effect.tryPromise({
+      try: () => import("./Tui.ts"),
+      catch: (cause) =>
+        new TuiUnavailable({
+          message: "--tui needs @opentui/core. Install it with `bun add -d @opentui/core`.",
+          cause,
+        }),
+    }).pipe(Effect.map(({ TuiReporter }) => TuiReporter(logFile))),
+  );
+
+const sequential = Flag.Boolean("sequential").pipe(
+  Flag.withDescription("Run tests within each file sequentially"),
+  Flag.withDefault(false),
+);
+
+const tui = Flag.Boolean("tui").pipe(
+  Flag.withDescription("Opt in to the interactive TUI (default is plain line output)"),
+  Flag.withDefault(false),
+);
+
+const profile = Flag.String("profile").pipe(
+  Flag.withDescription(
+    'Set ALCHEMY_PROFILE for the run (e.g. "testing") before any test module is imported',
+  ),
+  Flag.optional,
+);
+
+const stage = Flag.String("stage").pipe(
+  Flag.withSchema(Schema.String.check(Schema.isPattern(/^[a-z0-9]+([-_a-z0-9]+)*$/i))),
+  Flag.withDescription(
+    'Set ALCHEMY_TEST_STAGE for the run (e.g. "test_sam_feat-x") before any test module is imported',
+  ),
+  Flag.optional,
+);
+
+const fast = Flag.Boolean("fast").pipe(
+  Flag.withDescription(
+    "Set FAST=1 — suites skip their slow tests (long-provisioning resources, smoke tests)",
+  ),
+  Flag.withDefault(false),
+);
+
+/**
+ * Build the `-t` matcher — bun/vitest semantics: the pattern is a regex
+ * tested against the full nested title (`file > describe chain > name`).
+ * A syntactically INVALID regex (e.g. `-t "[worker"`) degrades to a literal
+ * substring match instead of erroring.
+ */
+const toFilter = (pattern: Option.Option<string>): ((fullTitle: string) => boolean) | undefined =>
+  Option.match(pattern, {
+    onNone: () => undefined,
+    onSome: (source) => {
+      let regex: RegExp;
+      try {
+        regex = new RegExp(source);
+      } catch {
+        // Not a valid regex — treat it as a literal substring.
+        regex = new RegExp(source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+      }
+      return (fullTitle) => regex.test(fullTitle);
+    },
+  });
+
+const rootCommand = Command.make(
+  "alchemy-test",
+  {
+    paths,
+    testNamePattern,
+    tagsFilter,
+    plan,
+    dryRun,
+    exclude,
+    timeout,
+    retry,
+    concurrency,
+    sequential,
+    tui,
+    profile,
+    stage,
+    fast,
+  },
+  Effect.fn(function* (args) {
+    // Environment knobs — set BEFORE any test module is imported (imports
+    // happen inside `run` during collection), so `skipIf(process.env.FAST)`
+    // gates and profile-dependent layers see the final values.
+    // Inherit CI from the caller: setting it here also disables local auth
+    // profiles, even when the caller explicitly selected one.
+    yield* Effect.sync(() => {
+      if (Option.isSome(args.profile)) {
+        process.env.ALCHEMY_PROFILE = args.profile.value;
+      }
+      if (Option.isSome(args.stage)) {
+        process.env.ALCHEMY_TEST_STAGE = args.stage.value;
+      }
+      if (args.fast) {
+        process.env.FAST = "1";
+      }
+      // The runner owns the terminal: stdout belongs to the reporter (or
+      // the TUI) and stdin carries TUI keystrokes. Code under test must see
+      // the same non-interactive, colorless process CI gives it, regardless
+      // of the terminal this run was launched from — otherwise assertions
+      // on CLI output and on interactive-vs-plain copy depend on whether a
+      // human or a pipeline started the run. Sigil's detection honors
+      // FORCE_COLOR over everything else, so pin it rather than NO_COLOR.
+      process.env.ALCHEMY_NO_TUI = "1";
+      process.env.NO_COLOR = "1";
+      process.env.FORCE_COLOR = "0";
+    });
+    // A linked git worktree defaults to its own stage, so two worktrees of
+    // one developer running the same suite never share deployments. An
+    // explicit `--stage` or ALCHEMY_TEST_STAGE wins.
+    if (Option.isNone(args.stage) && !process.env.ALCHEMY_TEST_STAGE) {
+      const stage = yield* worktreeStage(yield* Effect.sync(() => process.cwd()));
+      if (stage !== undefined) {
+        yield* Effect.sync(() => {
+          process.env.ALCHEMY_TEST_STAGE = stage;
+        });
+      }
+    }
+
+    // Plain line output by default; the TUI is opt-in (`--tui`) and requires
+    // an interactive terminal.
+    const interactive = !args.dryRun && args.tui && process.stdout.isTTY === true;
+    const path = yield* Path.Path;
+    const root = process.cwd();
+    // Per-run log file (timestamp + pid) so concurrent runs in different
+    // terminals never trample each other's logs.
+    const timestamp = new Date().toISOString().slice(0, 19).replaceAll(":", "-");
+    const logFile = path.resolve(
+      root,
+      ".alchemy",
+      "log",
+      "test",
+      `${timestamp}-pid${process.pid}.log`,
+    );
+
+    const options: RunOptions = {
+      root,
+      paths: args.paths,
+      exclude: args.exclude,
+      filter: toFilter(args.testNamePattern),
+      tagsFilter: args.tagsFilter,
+      dryRun: args.dryRun,
+      plan: Option.isSome(args.plan) ? parsePlan(args.plan.value) : undefined,
+      timeout: args.timeout,
+      retry: args.retry,
+      concurrency: toConcurrency(args.concurrency),
+      sequential: args.sequential,
+      logFile,
+    };
+
+    // In plain mode, divert stray JS-level stdout/stderr writes into the
+    // run log for the duration of the run (the reporter writes through the
+    // real stream); the TUI installs its own diversion after the renderer
+    // is created.
+    const restoreStrayCapture = interactive ? undefined : captureStrayOutput(logFile);
+
+    const summary = yield* Effect.gen(function* () {
+      const reporter = yield* Reporter;
+      const summary = yield* run(options);
+      yield* reporter.waitForExit(summary);
+      return summary;
+    }).pipe(
+      Effect.provide(interactive ? tuiReporter(logFile) : PlainReporterLive),
+      Effect.scoped,
+      Effect.onExit(() => Effect.sync(() => restoreStrayCapture?.())),
+    );
+
+    // After the TUI tears down, leave a plain record in the terminal.
+    if (interactive) {
+      yield* printSummary(summary);
+    }
+
+    // Point agents/tooling at the full run log, with its size so the reader
+    // knows what they're getting into before opening it.
+    yield* Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const stats = yield* fs.stat(logFile).pipe(Effect.orElseSucceed(() => undefined));
+      const kb = stats === undefined ? 0 : Number(stats.size) / 1024;
+      yield* Effect.sync(() => {
+        process.stdout.write(`\nFull log: ${logFile} (${kb.toFixed(1)} KB)\n`);
+      });
+    });
+
+    if (summary.failed > 0) {
+      yield* Effect.sync(() => {
+        process.exitCode = 1;
+      });
+    }
+  }),
+);
+
+const cli = Command.run(rootCommand, {
+  version: packageJson.version,
+});
+
+cli.pipe(Effect.provide(Layer.mergeAll(BunServices.layer)), Effect.scoped, (effect) =>
+  BunRuntime.runMain(effect as Effect.Effect<void>, {
+    // ALWAYS exit once the main effect completes. runMain's default only
+    // force-exits on failure/signal — but tests can leak live handles
+    // (vite watchers, workerd sidecar sockets, keep-alive agents) that
+    // keep bun's event loop alive forever after a green run. Everything
+    // is already flushed by now (summary + log written in the main
+    // effect); the macrotask hop lets any buffered stdout drain.
+    teardown: (exit, onExit) => {
+      Runtime.defaultTeardown(exit, (code) => {
+        const finalCode = code !== 0 ? code : Number(process.exitCode ?? 0) || 0;
+        setTimeout(() => process.exit(finalCode), 0);
+        onExit(finalCode);
+      });
+    },
+  }),
+);

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * alchemy-test — a minimal, Effect-native, vitest-compatible test harness.
+ *
+ * This entrypoint is safe to import from anywhere (including code that gets
+ * bundled into Workers): it only contains the registration API and the
+ * assertion library. The runner, CLI and TUI live in separate modules that
+ * are only loaded by the `alchemy-test` binary.
+ */
+export {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  exclusiveOf,
+  it,
+  layer,
+  registerFileCleanup,
+  registerHook,
+  registerTest,
+  retryOf,
+  test,
+  tagsOf,
+  optInTagsOf,
+  timeoutOf,
+  type DescribeFn,
+  type DescribeOptions,
+  type HookKind,
+  type LayerMethods,
+  type RegisterTestOptions,
+  type TestContext,
+  type Tester,
+  type TestFn,
+  type TestOptions,
+} from "./Api.ts";
+export {
+  assert,
+  AssertionError,
+  equals,
+  expect,
+  stringify,
+  type Assert,
+  type Expect,
+  type Matchers,
+} from "./Expect.ts";
+export { currentFile } from "./Registry.ts";
+export type { Tags, TestTag, TestTags } from "./Tags.ts";
+export type {
+  Exclusive,
+  FileSuite,
+  Hook,
+  LogEntry,
+  Mode,
+  Suite,
+  TestBody,
+  TestCase,
+} from "./Model.ts";

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.