archal 0.9.8 → 0.9.9

package/dist/vitest/index.d.ts

@@ -0,0 +1,398 @@
+import { defineWorkspace } from 'vitest/config';
+import { Reporter } from 'vitest/reporters';
+import { Vitest } from 'vitest/node';
+
+interface ServiceConfig {
+    mode: 'route';
+    seed?: string;
+}
+type SeedFormat = 'json' | 'markdown';
+interface ResolvedRuntime {
+    resolvedServices: string[];
+    resolvedSeeds: Record<string, string>;
+    manifestVersions: Record<string, string>;
+    capabilityVersion?: string;
+    runtimeVersion?: string;
+}
+type RuntimeEvent = {
+    type: 'runtime_started' | 'runtime_reset' | 'runtime_stopped' | 'routing_installed' | 'routing_uninstalled';
+    timestamp: string;
+} | {
+    type: 'request_routed';
+    timestamp: string;
+    service: string;
+    sourceUrl: string;
+    targetUrl: string;
+} | {
+    type: 'request_blocked';
+    timestamp: string;
+    service: string;
+    code: 'ARCHAL_UNDECLARED_SERVICE' | 'ARCHAL_DECLARED_SERVICE_ESCAPE';
+    url: string;
+    message: string;
+} | {
+    type: 'request_warning';
+    timestamp: string;
+    service: string;
+    url: string;
+    message: string;
+};
+interface ArchalRuntime {
+    start(): Promise<void>;
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+    installRouting(): void;
+    uninstallRouting(): void;
+    getEvents(): RuntimeEvent[];
+}
+/**
+ * Public, redacted view of the session intended for userland introspection.
+ *
+ * The full `StartedSession` contains `routedRequestHeaders()`
+ * functions that return the raw Archal account JWT. That token has
+ * full account scope (not session-scoped) and a 30-day expiry, so any
+ * code that can read it (a test dependency, a snapshot matcher, etc.)
+ * can impersonate the developer for the life of the token.
+ *
+ * Userland should never need the auth header — the route-mode runtime
+ * injects it directly into outbound twin requests without routing through
+ * userland code. The redacted snapshot exposes just the metadata tests
+ * legitimately need: session id, service names, base URLs, resolved seeds,
+ * manifest versions.
+ */
+interface PublicSessionSnapshot {
+    sessionId: string;
+    services: {
+        name: string;
+        mode: 'route';
+        baseUrl: string;
+    }[];
+    resolvedRuntime: ResolvedRuntime;
+}
+
+declare function resetArchalTwins(): Promise<void>;
+declare function bootstrapArchalVitestRouting(): Promise<ArchalRuntime>;
+declare function getInstalledArchalVitestRuntime(): ArchalRuntime | undefined;
+declare function getInstalledArchalVitestSession(): PublicSessionSnapshot | undefined;
+
+type SeedClassification = {
+    type: 'named';
+    name: string;
+} | {
+    type: 'file';
+    path: string;
+    format: SeedFormat;
+};
+/**
+ * Determine whether a seed value is a prebuilt named seed or a developer-
+ * provided file path. File paths start with `./', `../`, `/`, or end with
+ * `.json` / `.md`.
+ */
+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
+ * 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"`). */
+    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 —
+     *  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: Record<string, string>;
+    /** The endpoint URL as registered by the user in the twin's state. */
+    url: string;
+    /** Epoch milliseconds when the delivery was queued. */
+    queuedAt: number;
+}
+interface WaitForWebhookOptions {
+    /** Match on exact event type. Combine with `where` for narrower matches. */
+    eventType?: string;
+    /** Predicate to filter matching deliveries. Applied after `eventType` if both are set. */
+    where?: (delivery: ArchalWebhookDelivery) => boolean;
+    /** Max wait time in milliseconds. Defaults to 2000. */
+    timeout?: number;
+    /**
+     * When `true`, clears the service's entire pending queue after finding a
+     * match. This prevents the same delivery from being returned by a later
+     * `waitForArchalWebhook()` call.
+     *
+     * **Defaults to `false`** because `consume: true` deletes ALL queued
+     * deliveries (the server has no delete-by-ID endpoint), which silently
+     * discards unmatched events. Tests that wait for multiple sequential
+     * events would lose deliveries if this were `true` by default:
+     *
+     * ```ts
+     * // With consume: true, the first wait deletes customer.created too
+     * const sub  = await waitForArchalWebhook('stripe', 'customer.subscription.created', { consume: true });
+     * const cust = await waitForArchalWebhook('stripe', 'customer.created'); // would time out
+     * ```
+     *
+     * Use `consume: true` only when you know the test produces exactly one
+     * webhook event, or call `clearArchalWebhooks()` explicitly after
+     * consuming all expected events.
+     */
+    consume?: boolean;
+}
+/**
+ * Return the current pending webhook deliveries queued by the named twin.
+ *
+ * Each twin's `WebhookDeliveryEngine` appends a delivery whenever an event
+ * matches a webhook endpoint the user has registered. The hosted twin
+ * 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.
+ *
+ * Called automatically by `resetArchalTwins()` 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
+ * appears or the timeout elapses. Returns the first match.
+ *
+ * ```ts
+ * await stripe.subscriptions.create({ customer: c.id, items: [...] });
+ * const event = await waitForArchalWebhook('stripe', 'customer.subscription.created');
+ * await myWebhookHandler(event);   // invoke your handler directly with the payload
+ * ```
+ *
+ * **Parallel-worker caveat**: this helper consumes pending deliveries
+ * from a shared twin 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.
+ */
+declare function waitForArchalWebhook(serviceName: string, matcher: string | WaitForWebhookOptions, options?: WaitForWebhookOptions): Promise<ArchalWebhookDelivery>;
+
+/**
+ * Archal Vitest Reporter — sends test results to the Archal dashboard.
+ *
+ * `withArchal()` and `archalVitestProject()` already install this reporter
+ * automatically; you only need to reference it manually if you're composing
+ * a fully custom vitest config outside those helpers.
+ *
+ * After each test run, results are POSTed to /api/test-results so they
+ * appear in the Archal dashboard alongside scenario traces.
+ */
+
+declare class ArchalReporter implements Reporter {
+    private startTime;
+    private ctx;
+    private lifecycleMarkerPath;
+    private workspaceReporterMarkerPath;
+    private projects;
+    onInit(ctx: Vitest): void;
+    private decodeConfig;
+    private buildProjectContext;
+    private resolveProjects;
+    /**
+     * vitest v2 calls onFinished with an array of File objects (from @vitest/runner).
+     * Each File extends Suite which has `tasks: Task[]`, and each Task has
+     * `.type` ('test' | 'suite'), `.name`, `.result?.state`, `.result?.duration`.
+     */
+    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.
+     */
+    onTestRunEnd(testModules?: unknown[]): Promise<void>;
+    private collectAndReport;
+    /**
+     * vitest v2: File extends Suite { tasks: Task[] }.
+     * Task.type is 'test' | 'suite' | 'custom'. Suite tasks recurse.
+     */
+    private collectV2Files;
+    /**
+     * vitest v4: TestModule.children() → TestSuite[].children() → TestCase[]
+     * All accessors are methods (not properties) in v4.
+     */
+    private collectV4Modules;
+    private resolveProjectForFile;
+    private partitionResults;
+    private sendResults;
+    private readSessionId;
+}
+
+interface ArchalVitestProjectOptions {
+    name?: string;
+    services: Record<string, ServiceConfig>;
+    /**
+     * Controls how twin 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
+     *   parallel test files. Safe if tests use unique IDs (UUID-prefixed
+     *   emails, etc.) and don't assert on global counts/ordering.
+     *
+     * - `'serial'`: automatically sets `maxWorkers: 1` and `fileParallelism:
+     *   false`, running test files one at a time. Guarantees isolation at the
+     *   cost of parallelism — use this if your tests assert on global state
+     *   (e.g. `list.length === 1`) and you don't want to rewrite them.
+     */
+    testIsolation?: 'shared' | 'serial';
+}
+interface ArchalVitestProjectTestOptions {
+    include?: string[];
+    exclude?: string[];
+    env?: Record<string, string>;
+    globals?: boolean;
+    pool?: string;
+    hookTimeout?: number;
+    testTimeout?: number;
+    maxWorkers?: number | string;
+    fileParallelism?: boolean;
+}
+interface ArchalVitestBuiltTestConfig {
+    name: string;
+    exclude: string[];
+    hookTimeout: number;
+    testTimeout: number;
+    env: Record<string, string>;
+    setupFiles: string[];
+    reporters?: unknown[];
+    include?: string[];
+    globals?: boolean;
+    pool?: string;
+    maxWorkers?: number | string;
+    fileParallelism?: boolean;
+}
+interface ArchalVitestWorkspaceProjectConfig {
+    test?: ArchalVitestBuiltTestConfig;
+    [key: string]: unknown;
+}
+type ArchalVitestWorkspaceProject = string | ArchalVitestWorkspaceProjectConfig;
+/**
+ * Create a vitest workspace project that routes requests to Archal hosted twins.
+ *
+ * Use this from `vitest.workspace.ts`:
+ * ```ts
+ * import { archalVitestProject } from 'archal/vitest';
+ * export default [
+ *   archalVitestProject({ services: { stripe: { mode: 'route' } } }),
+ * ];
+ * ```
+ *
+ * ⚠️ DO NOT wrap the return value in `defineConfig({ test: archalVitestProject(...) })`.
+ * The return value is a workspace project, not a test config. If you want a
+ * single `vitest.config.ts`, use `withArchal()` instead.
+ */
+declare function archalVitestProject(options: ArchalVitestProjectOptions, testOptions?: ArchalVitestProjectTestOptions): ArchalVitestWorkspaceProjectConfig;
+/**
+ * @deprecated Use {@link withArchal} instead. `archalVitestConfig({ services })`
+ * is equivalent to `withArchal({}, { services })`, and `withArchal` additionally
+ * preserves any existing `test` block fields (coverage, alias, globalSetup,
+ * poolOptions, custom reporters, etc.) — which `archalVitestConfig` cannot
+ * accept. This export will remain for a deprecation window; new code should
+ * use `withArchal`.
+ *
+ * Migration:
+ * ```ts
+ * // before
+ * test: archalVitestConfig({ services: { stripe: { mode: 'route' } } })
+ * // after
+ * test: withArchal({}, { services: { stripe: { mode: 'route' } } })
+ * ```
+ *
+ * For `vitest.workspace.ts` usage, continue to use `archalVitestProject()`.
+ */
+declare function archalVitestConfig(options: ArchalVitestProjectOptions, testOptions?: ArchalVitestProjectTestOptions): ArchalVitestBuiltTestConfig;
+/**
+ * Root-level Vitest config for workspace users.
+ *
+ * Vitest only honors reporters from the root config, not from individual
+ * workspace projects. Pair this with `vitest.workspace.ts` when using
+ * `archalVitestProject()` / `archalVitestWorkspace()` so dashboard upload
+ * remains enabled.
+ */
+declare function archalVitestRootConfig(): {
+    test: {
+        reporters: string[];
+    };
+};
+/**
+ * Compose Archal's hosted-twin 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:
+ *
+ * ```ts
+ * import { defineConfig } from 'vitest/config';
+ * import { withArchal } from 'archal/vitest';
+ *
+ * export default defineConfig({
+ *   test: withArchal(
+ *     {
+ *       globals: true,
+ *       setupFiles: ['./test/my-setup.ts'],
+ *       coverage: { provider: 'v8' },
+ *     },
+ *     { services: { stripe: { mode: 'route' } } },
+ *   ),
+ * });
+ * ```
+ *
+ * Merge behavior:
+ *   - `setupFiles` and `reporters`: existing entries are preserved and Archal's
+ *     entries are appended. ArchalReporter is appended only when the user's
+ *     reporter list doesn't already contain an ArchalReporter instance — so a
+ *     config carried over from an older helper or hand-rolled setup doesn't
+ *     end up with two reporters double-uploading to `/dashboard/tests`.
+ *     Vitest's `'default'` reporter is only inserted when the user didn't
+ *     specify any reporters of their own.
+ *   - `env`: user keys preserved; Archal's required session-config keys added.
+ *   - `exclude`, `hookTimeout`, `testTimeout`, `maxWorkers`, `fileParallelism`:
+ *     user values win if set; Archal defaults otherwise.
+ *   - All other fields: passed through untouched.
+ *
+ * For a workspace (`vitest.workspace.ts`) layout, use `archalVitestProject`.
+ */
+declare function withArchal<T extends Record<string, unknown>>(existingTest: T, options: ArchalVitestProjectOptions): T & ArchalVitestBuiltTestConfig;
+/**
+ * Wrap an array of workspace projects for `vitest.workspace.ts`.
+ *
+ * This is a thin identity helper over the array export that vitest already
+ * accepts in `vitest.workspace.ts`. It exists so the workspace pattern has a
+ * clearly named, discoverable entry point that pairs with
+ * `archalVitestProject()` — making it harder to accidentally reach for
+ * `defineConfig({ test: archalVitestProject(...) })`, which silently drops
+ * setup files (see `installMisuseDetector`).
+ *
+ * ```ts
+ * import { archalVitestProject, archalVitestWorkspace } from 'archal/vitest';
+ *
+ * export default archalVitestWorkspace([
+ *   archalVitestProject(
+ *     { name: 'github-hosted-live', services: { github: { mode: 'route' } } },
+ *     { include: ['__tests__/github-live.test.ts'] },
+ *   ),
+ *   archalVitestProject(
+ *     { name: 'stripe-hosted-live', services: { stripe: { mode: 'route' } } },
+ *     { include: ['__tests__/stripe-live.test.ts'] },
+ *   ),
+ * ]);
+ * ```
+ *
+ * Accepts anything `defineWorkspace` accepts — 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 };