archal 0.9.13 → 0.9.15

package/dist/vitest/index.d.ts

@@ -1,4 +1,3 @@
-import { defineWorkspace } from 'vitest/config';
 import { Reporter } from 'vitest/reporters';
 import { Vitest } from 'vitest/node';
 
@@ -70,7 +69,7 @@ interface PublicSessionSnapshot {
     resolvedRuntime: ResolvedRuntime;
 }
 
-declare function resetArchalTwins(): Promise<void>;
+declare function resetArchalClones(): Promise<void>;
 declare function bootstrapArchalVitestRouting(): Promise<ArchalRuntime>;
 declare function getInstalledArchalVitestRuntime(): ArchalRuntime | undefined;
 declare function getInstalledArchalVitestSession(): PublicSessionSnapshot | undefined;
@@ -91,24 +90,24 @@ type SeedClassification = {
 declare function classifySeed(value: string): SeedClassification;
 
 /**
- * A webhook delivery that the twin has queued but has NOT POSTed to the
- * developer's endpoint. The hosted twin runs in AWS ECS and can't reach
- * the developer's localhost, so tests pull queued deliveries from the twin
+ * A webhook delivery that the clone has queued but has NOT POSTed to the
+ * developer's endpoint. The hosted clone runs in AWS ECS and can't reach
+ * the developer's localhost, so tests pull queued deliveries from the clone
  * and invoke the user's handler directly with the payload.
  */
 interface ArchalWebhookDelivery {
     /** The Archal service that queued the delivery — `'stripe'`, `'github'`, etc. */
     service: string;
-    /** The event type as emitted by the twin (e.g. `"customer.subscription.created"`). */
+    /** The event type as emitted by the clone (e.g. `"customer.subscription.created"`). */
     eventType: string;
     /** The parsed webhook payload. Shape matches the real service (Stripe Event, GitHub hook payload, etc.). */
     payload: unknown;
-    /** The serialized JSON body the twin would have POSTed. Use this for signature verification —
+    /** The serialized JSON body the clone would have POSTed. Use this for signature verification —
      *  re-serializing `payload` can produce different byte order and break HMAC checks. */
     body: string;
-    /** Headers the twin would have POSTed with — includes the signature header (e.g. `Stripe-Signature`). */
+    /** Headers the clone would have POSTed with - includes the signature header (e.g. `Stripe-Signature`). */
     headers: Record<string, string>;
-    /** The endpoint URL as registered by the user in the twin's state. */
+    /** The endpoint URL as registered by the user in the clone's state. */
     url: string;
     /** Epoch milliseconds when the delivery was queued. */
     queuedAt: number;
@@ -143,24 +142,24 @@ interface WaitForWebhookOptions {
     consume?: boolean;
 }
 /**
- * Return the current pending webhook deliveries queued by the named twin.
+ * Return the current pending webhook deliveries queued by the named clone.
  *
- * Each twin's `WebhookDeliveryEngine` appends a delivery whenever an event
- * matches a webhook endpoint the user has registered. The hosted twin
+ * Each clone's `WebhookDeliveryEngine` appends a delivery whenever an event
+ * matches a webhook endpoint the user has registered. The hosted clone
  * never POSTs these out in route-mode (it can't reach the user's
  * localhost), so this helper is the way tests observe them.
  */
 declare function listArchalWebhooks(serviceName: string): Promise<ArchalWebhookDelivery[]>;
 /**
- * Drop all pending webhook deliveries queued by the named twin.
+ * Drop all pending webhook deliveries queued by the named clone.
  *
- * Called automatically by `resetArchalTwins()` so each test starts with
+ * Called automatically by `resetArchalClones()` so each test starts with
  * an empty queue, and invoked internally by `waitForArchalWebhook()` when
  * `consume: true`.
  */
 declare function clearArchalWebhooks(serviceName: string): Promise<void>;
 /**
- * Poll the named twin's pending-webhook queue until a matching delivery
+ * Poll the named clone's pending-webhook queue until a matching delivery
  * appears or the timeout elapses. Returns the first match.
  *
  * ```ts
@@ -170,7 +169,7 @@ declare function clearArchalWebhooks(serviceName: string): Promise<void>;
  * ```
  *
  * **Parallel-worker caveat**: this helper consumes pending deliveries
- * from a shared twin queue. When vitest runs test files in parallel
+ * from a shared clone queue. When vitest runs test files in parallel
  * (the default) across workers, worker A can consume worker B's
  * deliveries. Use `testIsolation: 'serial'` in `withArchal` or
  * `archalVitestProject` if your tests depend on webhook events.
@@ -194,7 +193,26 @@ declare class ArchalReporter implements Reporter {
     private lifecycleMarkerPath;
     private workspaceReporterMarkerPath;
     private projects;
+    /**
+     * In-flight upload promise for the current run. Vitest v3+ fires both
+     * `onFinished` and `onTestRunEnd` in parallel via `Promise.all` (see
+     * vitest@3.x packages/vitest/src/node/test-run.ts), so without this guard
+     * the reporter uploads results twice and the dashboard shows duplicate
+     * rows. Reset at the start of each run (onTestRunStart / onWatcherRerun)
+     * so watch-mode reruns still upload.
+     */
+    private activeUpload;
     onInit(ctx: Vitest): void;
+    /**
+     * v3+ canonical start-of-run hook. Resetting the upload guard here lets
+     * watch-mode reruns upload their own results.
+     */
+    onTestRunStart(_specifications?: unknown[]): void;
+    /**
+     * v2 watch-mode start-of-rerun hook. Same purpose as onTestRunStart for
+     * v3+. Vitest v2 has no onTestRunStart, so we reset here instead.
+     */
+    onWatcherRerun(_files?: string[], _trigger?: string): void;
     private decodeConfig;
     private buildProjectContext;
     private resolveProjects;
@@ -205,10 +223,21 @@ declare class ArchalReporter implements Reporter {
      */
     onFinished(files?: unknown[], _errors?: unknown[]): Promise<void>;
     /**
-     * vitest v4 calls onTestRunEnd (not onFinished) for custom reporters.
-     * The argument is an array of test modules, each with nested children.
+     * vitest v3+ calls onTestRunEnd alongside onFinished (in parallel via
+     * Promise.all). v4 drops onFinished entirely. The argument is an array of
+     * test modules, each with nested children.
      */
     onTestRunEnd(testModules?: unknown[]): Promise<void>;
+    /**
+     * Dedupe upload work when Vitest fires multiple end-of-run hooks. In
+     * Vitest v3+ both `onFinished` and `onTestRunEnd` fire from the same
+     * `Promise.all` in TestRun.end(); the first hook to enter wins and the
+     * second awaits the same in-flight upload instead of POSTing a duplicate
+     * row to /api/test-results. The resolved promise is kept on the instance
+     * so any late hook still no-ops — the guard is only cleared at the start
+     * of a new run (onTestRunStart / onWatcherRerun).
+     */
+    private runUploadOnce;
     private collectAndReport;
     /**
      * vitest v2: File extends Suite { tasks: Task[] }.
@@ -230,7 +259,7 @@ interface ArchalVitestProjectOptions {
     name?: string;
     services: Record<string, ServiceConfig>;
     /**
-     * Controls how twin state is isolated across vitest workers.
+     * Controls how clone state is isolated across vitest workers.
      *
      * - `'shared'` (default): one hosted session is shared across all workers.
      *   Cheapest and fastest, but state from one test is visible to tests in
@@ -270,12 +299,18 @@ interface ArchalVitestBuiltTestConfig {
     fileParallelism?: boolean;
 }
 interface ArchalVitestWorkspaceProjectConfig {
-    test?: ArchalVitestBuiltTestConfig;
+    test?: Record<string, unknown> & {
+        env?: Record<string, string>;
+        fileParallelism?: boolean;
+        maxWorkers?: number | string;
+        name?: string;
+    };
     [key: string]: unknown;
 }
-type ArchalVitestWorkspaceProject = string | ArchalVitestWorkspaceProjectConfig;
+type ArchalVitestWorkspaceProject = string | ArchalVitestWorkspaceProjectConfig | (() => ArchalVitestWorkspaceProjectConfig | Promise<ArchalVitestWorkspaceProjectConfig>);
+type ArchalVitestWorkspaceInput = readonly ArchalVitestWorkspaceProject[];
 /**
- * Create a vitest workspace project that routes requests to Archal hosted twins.
+ * Create a vitest workspace project that routes requests to Archal hosted clones.
  *
  * Use this from `vitest.workspace.ts`:
  * ```ts
@@ -323,13 +358,13 @@ declare function archalVitestRootConfig(): {
     };
 };
 /**
- * Compose Archal's hosted-twin routing into a user's existing vitest `test`
+ * Compose Archal's hosted-clone routing into a user's existing vitest `test`
  * config, preserving every field they set (including ones Archal's options
  * surface doesn't cover — `coverage`, `alias`, `globalSetup`, `poolOptions`,
  * custom `reporters`, etc.).
  *
  * Use this when the project already has a `vitest.config.ts` and the user
- * wants every test in it to route to twins:
+ * wants every test in it to route to clones:
  *
  * ```ts
  * import { defineConfig } from 'vitest/config';
@@ -388,11 +423,10 @@ declare function withArchal<T extends Record<string, unknown>>(existingTest: T,
  * ]);
  * ```
  *
- * Accepts anything `defineWorkspace` accepts — archal-project results, plain
+ * Accepts Vitest workspace entries: archal-project results, plain
  * `defineProject({...})` configs, glob-pattern strings, or function-based
  * project factories.
  */
-type ArchalVitestWorkspaceInput = Parameters<typeof defineWorkspace>[0];
 declare function archalVitestWorkspace<T extends ArchalVitestWorkspaceInput>(projects: T): T;
 
-export { ArchalReporter, type ArchalVitestBuiltTestConfig, type ArchalVitestProjectOptions, type ArchalVitestProjectTestOptions, type PublicSessionSnapshot as ArchalVitestPublicSessionSnapshot, type ArchalVitestWorkspaceProject, type ArchalVitestWorkspaceProjectConfig, type ArchalWebhookDelivery, type WaitForWebhookOptions, archalVitestConfig, archalVitestProject, archalVitestRootConfig, archalVitestWorkspace, bootstrapArchalVitestRouting, classifySeed, clearArchalWebhooks, getInstalledArchalVitestRuntime, getInstalledArchalVitestSession, listArchalWebhooks, resetArchalTwins, waitForArchalWebhook, withArchal };
+export { ArchalReporter, type ArchalVitestBuiltTestConfig, type ArchalVitestProjectOptions, type ArchalVitestProjectTestOptions, type PublicSessionSnapshot as ArchalVitestPublicSessionSnapshot, type ArchalVitestWorkspaceInput, type ArchalVitestWorkspaceProject, type ArchalVitestWorkspaceProjectConfig, type ArchalWebhookDelivery, type WaitForWebhookOptions, archalVitestConfig, archalVitestProject, archalVitestRootConfig, archalVitestWorkspace, bootstrapArchalVitestRouting, classifySeed, clearArchalWebhooks, getInstalledArchalVitestRuntime, getInstalledArchalVitestSession, listArchalWebhooks, resetArchalClones, waitForArchalWebhook, withArchal };