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

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/bin/alchemy-test.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli.ts";

package/lib/Alchemy.d.ts

@@ -0,0 +1,78 @@
+/** @effect-diagnostics anyUnknownInErrorContext:off */
+import type { StackDefinition } from "alchemy/Stack";
+import * as Effect from "effect/Effect";
+import * as Core from "./Core.ts";
+/**
+ * Test adapter for the `alchemy-test` runner (see `packages/alchemy-test`).
+ *
+ * Same shape as {@link "./Vitest.ts"} / {@link "./Bun.ts"}, but registers
+ * tests as raw Effects with the alchemy-test harness so the single-process
+ * runner can inject a buffering Logger/Console per test and manage
+ * concurrency + timeouts itself.
+ */
+import { type TestOptions } from "./index.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 declare const ALCHEMY_TEST_DEV: import("effect/Config").Config<import("effect/Option").Option<boolean>>;
+export declare const resolveDev: typeof Core.resolveDev;
+export declare const defaultStage: typeof Core.defaultStage;
+export declare const resolveStage: typeof Core.resolveStage;
+export declare const captureResourceLog: typeof Core.captureResourceLog;
+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;
+    todo: (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>;
+}
+/**
+ * Build the per-file test API. Configure providers / state once at the top of
+ * the test file:
+ *
+ * ```ts
+ * import * as Test from "@alchemy.run/test/Alchemy";
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ *
+ * const { test, deploy, destroy, beforeAll, afterAll } = Test.make({
+ *   providers: Cloudflare.providers(),
+ *   state: Cloudflare.state(),
+ * });
+ * ```
+ */
+export declare const make: <ROut = any>(options: MakeOptions<ROut>) => TestApi;
+//# sourceMappingURL=Alchemy.d.ts.map

package/lib/Alchemy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Alchemy.d.ts","sourceRoot":"","sources":["../src/Alchemy.ts"],"names":[],"mappings":"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"}

package/lib/Alchemy.js

@@ -0,0 +1,194 @@
+/** @effect-diagnostics anyUnknownInErrorContext:off */
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
+import * as Core from "./Core.js";
+/**
+ * Test adapter for the `alchemy-test` runner (see `packages/alchemy-test`).
+ *
+ * Same shape as {@link "./Vitest.ts"} / {@link "./Bun.ts"}, but registers
+ * tests as raw Effects with the alchemy-test harness so the single-process
+ * runner can inject a buffering Logger/Console per test and manage
+ * concurrency + timeouts itself.
+ */
+import { currentFile, exclusiveOf, registerFileCleanup, registerHook, registerTest, retryOf, tagsOf, optInTagsOf, timeoutOf, } from "./index.js";
+export { executeWhenReady, getWhenReady, guardContentType, guardedFetchLayer, rpcClientLayer, WorkerNotReady, } from "./Http.js";
+export const ALCHEMY_TEST_DEV = Core.ALCHEMY_TEST_DEV;
+export const resolveDev = Core.resolveDev;
+export const defaultStage = Core.defaultStage;
+export const resolveStage = Core.resolveStage;
+export const captureResourceLog = Core.captureResourceLog;
+const DEFAULT_TIMEOUT = 120_000;
+/**
+ * Build the per-file test API. Configure providers / state once at the top of
+ * the test file:
+ *
+ * ```ts
+ * import * as Test from "@alchemy.run/test/Alchemy";
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ *
+ * const { test, deploy, destroy, beforeAll, afterAll } = Test.make({
+ *   providers: Cloudflare.providers(),
+ *   state: Cloudflare.state(),
+ * });
+ * ```
+ */
+export const make = (options) => {
+    // Single scope shared across `beforeAll`, every `test`, and `afterAll`.
+    // Scoped resources in dev mode (the Cloudflare dev proxy and its workerd
+    // children) must outlive a single test boundary, otherwise the proxy is
+    // killed the moment `beforeAll(deploy(Stack))` resolves and every later
+    // `HttpClient.get(workerUrl)` hits a dead port. The scope is closed by
+    // `destroy(...)` (or by file cleanup below).
+    let sharedScope = Scope.makeUnsafe("sequential");
+    // Session ownership outlives a mid-file destroy, but not file cleanup.
+    let sidecar = Core.makeSidecarHandle(options);
+    const clearResults = new Set();
+    const wrap = (eff) => sharedScope === undefined
+        ? Effect.die("Test runtime is closed")
+        : Core.toEffect(eff, options, sharedScope, sidecar);
+    const addTest = (name, eff, opts, mode) => registerTest({
+        name,
+        mode,
+        exclusive: exclusiveOf(opts),
+        retry: retryOf(opts),
+        timeout: timeoutOf(opts),
+        tags: tagsOf(opts),
+        optInTags: optInTagsOf(opts),
+        body: mode === "skip" || mode === "todo" ? undefined : () => wrap(eff),
+    });
+    const test = ((name, eff, opts) => {
+        addTest(name, eff, opts, "run");
+    });
+    test.skip = (name, eff, opts) => addTest(name, eff, opts, "skip");
+    test.skipIf = (condition) => (name, eff, opts) => addTest(name, eff, opts, condition ? "skip" : "run");
+    test.only = (name, eff, opts) => addTest(name, eff, opts, "only");
+    test.todo = (name, eff, opts) => addTest(name, eff, opts, "todo");
+    // One lock per scratch stack. When an attempt times out, the runner fires
+    // an interrupt and ABANDONS the attempt's fiber after a short grace — but
+    // the fiber keeps running its teardown (`scratch.destroy()` below) in the
+    // background, e.g. a CloudFront disable-wait. Without this lock the retry
+    // starts concurrently on the SAME scratch state: the stale teardown then
+    // deletes the state rows the retry just wrote for the same logical ids,
+    // orphaning the retry's cloud resources (observed: two leaked CloudFront
+    // distributions + buckets + OACs from one retried test). Holding the lock
+    // across body + teardown makes a retry wait (on its own timeout clock)
+    // until the previous attempt's teardown has fully settled.
+    const scratchLocks = new Map();
+    const scratchLock = (name) => {
+        let lock = scratchLocks.get(name);
+        if (lock === undefined) {
+            lock = Semaphore.makeUnsafe(1);
+            scratchLocks.set(name, lock);
+        }
+        return lock;
+    };
+    const wrapProvider = (name, fn, file) => {
+        if (sharedScope === undefined)
+            return Effect.die("Test runtime is closed");
+        // Durable, file-namespaced scratch state (`.alchemy/state`). A run that
+        // dies mid-delete — e.g. the runner abandons teardown 10s after a test
+        // timeout while a CloudFront disable-wait is still in flight — leaves
+        // its `deleting` rows on disk, so the NEXT run's leading
+        // `stack.destroy()` (or the ensuring teardown below) resumes and drains
+        // them instead of planning "no changes" and silently orphaning the
+        // cloud resource.
+        const scratch = Core.scratchStack(options, name, file);
+        // Guarantee teardown. `test.provider` has no built-in cleanup, so a body
+        // that fails (assertion, API error like a 409/Unauthorized) or is
+        // interrupted (timeout) BEFORE its trailing `stack.destroy()` would
+        // otherwise leak every cloud resource it deployed.
+        // `scratch.destroy()` is idempotent — 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)), scratchLock(scratch.name).withPermits(1));
+        return Core.toEffect(body, { ...options, state: scratch.state }, sharedScope, sidecar);
+    };
+    const addProvider = (name, fn, opts, mode) => {
+        // Captured at registration (module evaluation during collection) — the
+        // collection context is gone by the time the body runs.
+        const file = currentFile();
+        registerTest({
+            name,
+            mode,
+            exclusive: exclusiveOf(opts),
+            retry: retryOf(opts),
+            timeout: timeoutOf(opts),
+            tags: tagsOf(opts),
+            optInTags: optInTagsOf(opts),
+            body: mode === "run" ? () => wrapProvider(name, fn, file) : undefined,
+        });
+    };
+    const provider = ((name, fn, opts) => {
+        addProvider(name, fn, opts, "run");
+    });
+    provider.skip = (name, fn, opts) => addProvider(name, fn, opts, "skip");
+    provider.skipIf = (condition) => (name, fn, opts) => addProvider(name, fn, opts, condition ? "skip" : "run");
+    provider.todo = (name, fn, opts) => addProvider(name, fn, opts, "todo");
+    test.provider = provider;
+    const beforeAll = (eff, hookOptions) => {
+        let result;
+        clearResults.add(() => {
+            result = undefined;
+        });
+        registerHook("beforeAll", {
+            body: () => wrap(eff).pipe(Effect.map((value) => {
+                if (sharedScope !== undefined)
+                    result = value;
+            })),
+            timeout: timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+            exclusive: exclusiveOf(hookOptions),
+        });
+        return Effect.sync(() => result);
+    };
+    const beforeEach = (eff, hookOptions) => {
+        registerHook("beforeEach", { body: () => wrap(eff), timeout: timeoutOf(hookOptions) });
+    };
+    const afterAll = ((eff, hookOptions) => {
+        registerHook("afterAll", {
+            body: () => wrap(eff),
+            timeout: timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+            exclusive: exclusiveOf(hookOptions),
+        });
+    });
+    afterAll.skipIf = (predicate) => (eff, hookOptions) => {
+        if (predicate)
+            return;
+        registerHook("afterAll", {
+            body: () => wrap(eff),
+            timeout: timeoutOf(hookOptions) ?? DEFAULT_TIMEOUT,
+            exclusive: exclusiveOf(hookOptions),
+        });
+    };
+    const afterEach = (eff, hookOptions) => {
+        registerHook("afterEach", { body: () => wrap(eff), timeout: timeoutOf(hookOptions) });
+    };
+    // `destroy(Stack)` needs the dev sidecar alive so it can call `sidecar.stop`
+    // for each worker. We close the shared scope only AFTER destroy completes.
+    // `Scope.close` on an already-closed scope is a no-op, so it's safe for both
+    // the destroy wrapper AND the fallback cleanup hook below to call it.
+    const closeScope = Effect.suspend(() => sharedScope === undefined ? Effect.void : Scope.close(sharedScope, Exit.void)).pipe(Effect.ignore);
+    // File cleanup runs after user afterAll, including skipped/failed imports.
+    // Interactive retries retain the runtime until the runner releases the file.
+    registerFileCleanup({
+        body: () => closeScope.pipe(Effect.ensuring(Effect.suspend(() => sidecar?.close ?? Effect.void)), Effect.ensuring(Effect.sync(() => {
+            sharedScope = undefined;
+            sidecar = undefined;
+            for (const clear of clearResults)
+                clear();
+            clearResults.clear();
+        }))),
+        timeout: 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)),
+    };
+};
+//# sourceMappingURL=Alchemy.js.map

package/lib/Alchemy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Alchemy.js","sourceRoot":"","sources":["../src/Alchemy.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAKvD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC;;;;;;;GAOG;AACH,OAAO,EACL,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,MAAM,EACN,WAAW,EACX,SAAS,GAEV,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,cAAc,GAGf,MAAM,WAAW,CAAC;AAKnB,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC;AACtD,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;AAC9C,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;AAC9C,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,kBAAkB,CAAC;AAoE1D,MAAM,eAAe,GAAG,OAAO,CAAC;AAEhC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAa,OAA0B,EAAW,EAAE;IACtE,wEAAwE;IACxE,yEAAyE;IACzE,wEAAwE;IACxE,wEAAwE;IACxE,uEAAuE;IACvE,6CAA6C;IAC7C,IAAI,WAAW,GAAgC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC9E,uEAAuE;IACvE,IAAI,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAG,IAAI,GAAG,EAAc,CAAC;IAC3C,MAAM,IAAI,GAAG,CAAI,GAAkB,EAAE,EAAE,CACrC,WAAW,KAAK,SAAS;QACvB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC;QACtC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAExD,MAAM,OAAO,GAAG,CACd,IAAY,EACZ,GAAqB,EACrB,IAA6B,EAC7B,IAAsC,EACtC,EAAE,CACF,YAAY,CAAC;QACX,IAAI;QACJ,IAAI;QACJ,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC;QAC5B,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC;QACpB,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC;QAClB,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC;QAC5B,IAAI,EAAE,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;KACvE,CAAC,CAAC;IAEL,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAChC,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC,CAAW,CAAC;IAEb,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAClE,IAAI,CAAC,MAAM,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAC/C,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACvD,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAClE,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAElE,0EAA0E;IAC1E,0EAA0E;IAC1E,0EAA0E;IAC1E,0EAA0E;IAC1E,yEAAyE;IACzE,wEAAwE;IACxE,yEAAyE;IACzE,0EAA0E;IAC1E,uEAAuE;IACvE,2DAA2D;IAC3D,MAAM,YAAY,GAAG,IAAI,GAAG,EAA+B,CAAC;IAC5D,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,EAAE;QACnC,IAAI,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAC/B,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,CACnB,IAAY,EACZ,EAA0D,EAC1D,IAAwB,EACxB,EAAE;QACF,IAAI,WAAW,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;QAC3E,wEAAwE;QACxE,uEAAuE;QACvE,sEAAsE;QACtE,yDAAyD;QACzD,wEAAwE;QACxE,mEAAmE;QACnE,kBAAkB;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACvD,yEAAyE;QACzE,kEAAkE;QAClE,oEAAoE;QACpE,mDAAmD;QACnD,oEAAoE;QACpE,sEAAsE;QACtE,4DAA4D;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CACtE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EACtD,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CACzC,CAAC;QACF,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IACzF,CAAC,CAAC;IAEF,MAAM,WAAW,GAAG,CAClB,IAAY,EACZ,EAA0D,EAC1D,IAA6B,EAC7B,IAA6B,EAC7B,EAAE;QACF,uEAAuE;QACvE,wDAAwD;QACxD,MAAM,IAAI,GAAG,WAAW,EAAE,CAAC;QAC3B,YAAY,CAAC;YACX,IAAI;YACJ,IAAI;YACJ,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC;YAC5B,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC;YACpB,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC;YACxB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC;YAClB,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC;YAC5B,IAAI,EAAE,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SACtE,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QACnC,WAAW,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC,CAAe,CAAC;IACjB,QAAQ,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,QAAQ,CAAC,MAAM,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAClD,WAAW,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC1D,QAAQ,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAEzB,MAAM,SAAS,GAAgB,CAAI,GAAkB,EAAE,WAAyB,EAAE,EAAE;QAClF,IAAI,MAAqB,CAAC;QAC1B,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE;YACpB,MAAM,GAAG,SAAS,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,YAAY,CAAC,WAAW,EAAE;YACxB,IAAI,EAAE,GAAG,EAAE,CACT,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CACZ,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;gBACnB,IAAI,WAAW,KAAK,SAAS;oBAAE,MAAM,GAAG,KAAK,CAAC;YAChD,CAAC,CAAC,CACH;YACH,OAAO,EAAE,SAAS,CAAC,WAAW,CAAC,IAAI,eAAe;YAClD,SAAS,EAAE,WAAW,CAAC,WAAW,CAAC;SACpC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAW,CAAC,CAAC;IACxC,CAAC,CAAC;IAEF,MAAM,UAAU,GAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE;QACpD,YAAY,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE;QACrC,YAAY,CAAC,UAAU,EAAE;YACvB,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;YACrB,OAAO,EAAE,SAAS,CAAC,WAAW,CAAC,IAAI,eAAe;YAClD,SAAS,EAAE,WAAW,CAAC,WAAW,CAAC;SACpC,CAAC,CAAC;IACL,CAAC,CAAe,CAAC;IACjB,QAAQ,CAAC,MAAM,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE;QACpD,IAAI,SAAS;YAAE,OAAO;QACtB,YAAY,CAAC,UAAU,EAAE;YACvB,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;YACrB,OAAO,EAAE,SAAS,CAAC,WAAW,CAAC,IAAI,eAAe;YAClD,SAAS,EAAE,WAAW,CAAC,WAAW,CAAC;SACpC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,SAAS,GAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE;QAClD,YAAY,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC,CAAC;IAEF,6EAA6E;IAC7E,2EAA2E;IAC3E,6EAA6E;IAC7E,sEAAsE;IACtE,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CACrC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,CAC9E,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEtB,2EAA2E;IAC3E,6EAA6E;IAC7E,mBAAmB,CAAC;QAClB,IAAI,EAAE,GAAG,EAAE,CACT,UAAU,CAAC,IAAI,CACb,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,EACpE,MAAM,CAAC,QAAQ,CACb,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;YACf,WAAW,GAAG,SAAS,CAAC;YACxB,OAAO,GAAG,SAAS,CAAC;YACpB,KAAK,MAAM,KAAK,IAAI,YAAY;gBAAE,KAAK,EAAE,CAAC;YAC1C,YAAY,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC,CAAC,CACH,CACF;QACH,OAAO,EAAE,eAAe;KACzB,CAAC,CAAC;IAEH,OAAO;QACL,IAAI;QACJ,SAAS;QACT,UAAU;QACV,QAAQ;QACR,SAAS;QACT,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,WAAW,CAAC;QAC7C,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CAC3B,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,IAAI,CACpE,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAC5B;KACJ,CAAC;AACJ,CAAC,CAAC"}

package/lib/Api.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The vitest-compatible registration API: `describe`, `it`/`test`, hooks and
+ * `layer`. Registration builds the {@link Model} tree; execution is the
+ * runner's job. Everything is Effect-first — plain-function tests are wrapped
+ * into Effects at registration time.
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Scope from "effect/Scope";
+import * as TestClock from "effect/testing/TestClock";
+import * as TestConsole from "effect/testing/TestConsole";
+import type { Exclusive, Hook, Mode, TestBody } from "./Model.ts";
+import { type Tags } from "./Tags.ts";
+export type TestOptions = number | {
+    /** Labels added to the tags inherited from enclosing suites. */
+    readonly tags?: Tags;
+    /** Tags that must each be explicitly named in the filter to enable this test or suite. */
+    readonly optInTags?: Tags;
+    readonly timeout?: number;
+    readonly retry?: number;
+    readonly repeats?: number;
+    /**
+     * `true` runs this test with the whole-process write lock — no other
+     * test in the run executes concurrently with it. Use for tests that
+     * mutate process-global state (e.g. `process.env.PATH`): the runner
+     * executes everything in ONE bun process, so such mutations are
+     * visible to every other running test.
+     *
+     * A label (e.g. `"hetzner"`) only serializes the test with others
+     * holding the same label, so unrelated tests keep running. Use it for
+     * a shared cloud quota.
+     */
+    readonly exclusive?: Exclusive;
+};
+export declare const timeoutOf: (options?: TestOptions) => number | undefined;
+export declare const retryOf: (options?: TestOptions) => number | undefined;
+export declare const exclusiveOf: (options?: TestOptions) => Exclusive;
+export declare const tagsOf: (options?: TestOptions) => Tags | undefined;
+export declare const optInTagsOf: (options?: TestOptions) => Tags | undefined;
+type DescribeBody = (() => void) | undefined;
+export interface DescribeOptions {
+    /** Labels inherited by every nested suite and test. */
+    readonly tags?: Tags;
+    /** Tags that must each be explicitly named in the filter to enable this test or suite. */
+    readonly optInTags?: Tags;
+    readonly concurrent?: boolean;
+    readonly sequential?: boolean;
+    readonly timeout?: number;
+}
+export interface DescribeFn {
+    (name: string | (() => void), body?: DescribeBody | DescribeOptions | number, bodyOrTimeout?: DescribeBody | number): void;
+    readonly sequential: DescribeFn;
+    readonly concurrent: DescribeFn;
+    readonly skip: DescribeFn;
+    readonly only: DescribeFn;
+    readonly todo: DescribeFn;
+    skipIf(condition: unknown): DescribeFn;
+    runIf(condition: unknown): DescribeFn;
+    each<T>(cases: ReadonlyArray<T>): (name: string, fn: (args: T) => void, options?: TestOptions) => void;
+}
+export declare const describe: DescribeFn;
+export interface RegisterTestOptions {
+    readonly tags?: Tags;
+    /** Tags that must each be explicitly named in the filter to enable this test or suite. */
+    readonly optInTags?: Tags;
+    readonly name: string;
+    readonly mode: Mode;
+    readonly fails?: boolean;
+    readonly exclusive?: Exclusive;
+    readonly retry?: number | undefined;
+    readonly timeout?: number | undefined;
+    readonly body: TestBody | undefined;
+}
+/** Low-level test registration — used by adapters (e.g. alchemy Test.make). */
+export declare const registerTest: (options: RegisterTestOptions) => void;
+/** Minimal stand-in for vitest's TestContext (rarely used by our tests). */
+export interface TestContext {
+    readonly signal?: AbortSignal;
+}
+export type EffectTestFunction<R> = (ctx: TestContext) => Effect.Effect<unknown, unknown, R>;
+export interface Tester<R> {
+    (name: string, self: EffectTestFunction<R>, options?: TestOptions): void;
+    skip(name: string, self: EffectTestFunction<R>, options?: TestOptions): void;
+    skipIf(condition: unknown): (name: string, self: EffectTestFunction<R>, options?: TestOptions) => void;
+    runIf(condition: unknown): (name: string, self: EffectTestFunction<R>, options?: TestOptions) => void;
+    only(name: string, self: EffectTestFunction<R>, options?: TestOptions): void;
+    fails(name: string, self: EffectTestFunction<R>, options?: TestOptions): void;
+    each<T>(cases: ReadonlyArray<T>): (name: string, self: (args: T) => Effect.Effect<unknown, unknown, R>, options?: TestOptions) => void;
+}
+export declare const makeTester: <R>(mapEffect: (self: Effect.Effect<unknown, unknown, R>) => Effect.Effect<unknown, unknown, never>) => Tester<R>;
+export interface TestFn {
+    (name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
+    skip(name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
+    only(name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
+    todo(name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
+    fails(name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions): void;
+    skipIf(condition: unknown): (name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions) => void;
+    runIf(condition: unknown): (name: string, fn?: (ctx: TestContext) => unknown, options?: TestOptions) => void;
+    each<T>(cases: ReadonlyArray<T>): (name: string, fn: (args: T) => unknown, options?: TestOptions) => void;
+    /** Effect tester with TestClock + TestConsole (matches @effect/vitest). */
+    readonly effect: Tester<Scope.Scope | TestClock.TestClock | TestConsole.TestConsole>;
+    /** Effect tester against the live environment (scope only). */
+    readonly live: Tester<Scope.Scope>;
+}
+export declare const it: TestFn;
+export declare const test: TestFn;
+export type HookKind = "beforeAll" | "afterAll" | "beforeEach" | "afterEach";
+/** Framework cleanup after user teardown, including files with no runnable tests. */
+export declare const registerFileCleanup: (hook: Hook) => void;
+/** Low-level hook registration with an Effect body — used by adapters. */
+export declare const registerHook: (kind: HookKind, hook: Hook) => void;
+export declare const beforeAll: (fn: () => unknown, timeout?: number) => void;
+export declare const afterAll: (fn: () => unknown, timeout?: number) => void;
+export declare const beforeEach: (fn: () => unknown, timeout?: number) => void;
+export declare const afterEach: (fn: () => unknown, timeout?: number) => void;
+export interface LayerMethods<R> {
+    effect: Tester<R | Scope.Scope | TestClock.TestClock | TestConsole.TestConsole>;
+    layer<R2, E2>(nested: Layer.Layer<R2, E2, R>, options?: {
+        readonly timeout?: number;
+    }): {
+        (f: (it: LayerMethods<R | R2>) => void): void;
+        (name: string, f: (it: LayerMethods<R | R2>) => void): void;
+    };
+}
+export declare const layer: <R, E>(layer_: Layer.Layer<R, E>, options?: {
+    readonly memoMap?: Layer.MemoMap;
+    readonly timeout?: number;
+    readonly excludeTestServices?: boolean;
+}) => {
+    (f: (it: LayerMethods<R>) => void): void;
+    (name: string, f: (it: LayerMethods<R>) => void): void;
+};
+export {};
+//# sourceMappingURL=Api.d.ts.map

package/lib/Api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Api.d.ts","sourceRoot":"","sources":["../src/Api.ts"],"names":[],"mappings":"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"}