archal 0.9.2 → 0.9.4

package/README.md

@@ -0,0 +1,215 @@
+# archal
+
+Pre-deployment testing for AI agents via Archal's hosted digital twins.
+
+## Install
+
+```bash
+npm install --save-dev archal
+```
+
+Then authenticate:
+
+```bash
+npx archal login
+```
+
+## Vitest Integration (primary use case)
+
+Test your code against hosted GitHub / Stripe / Slack / Jira / Supabase / Google Workspace twins without hitting real APIs. Your SDKs work unchanged — `archal/vitest` transparently routes their traffic to the twin.
+
+### Quick start — single `vitest.config.ts`
+
+```ts
+import { defineConfig } from 'vitest/config';
+import { archalVitestConfig } from 'archal/vitest';
+
+export default defineConfig({
+  test: archalVitestConfig({
+    services: {
+      stripe: { mode: 'route', seed: 'small-business' },
+    },
+  }),
+});
+```
+
+Your existing tests work unchanged:
+
+```ts
+import { it, expect } from 'vitest';
+import Stripe from 'stripe';
+
+it('creates a customer', async () => {
+  const stripe = new Stripe('sk_test_fake');        // fake key is fine
+  const customer = await stripe.customers.create({  // goes to twin, not real Stripe
+    email: 'test@example.com',
+  });
+  expect(customer.id).toMatch(/^cus_/);
+});
+```
+
+### Multi-project monorepos — `vitest.workspace.ts`
+
+```ts
+import { archalVitestProject } from 'archal/vitest';
+
+export default [
+  archalVitestProject({
+    name: 'stripe-integration-tests',
+    services: {
+      stripe: { mode: 'route', seed: 'small-business' },
+      slack: { mode: 'route' },
+    },
+  }),
+];
+```
+
+### Per-test state isolation
+
+```ts
+import { beforeEach } from 'vitest';
+import { resetArchalTwins } from 'archal/vitest';
+
+beforeEach(async () => {
+  await resetArchalTwins();
+});
+```
+
+### Webhook testing
+
+Test your webhook handlers against the twins' queued events. The hosted twin
+runs in AWS ECS so it can't POST to your localhost — instead, your test pulls
+queued deliveries with `waitForArchalWebhook()` and invokes your handler
+directly with the exact payload the twin would have sent.
+
+```ts
+import { it, expect } from 'vitest';
+import Stripe from 'stripe';
+import { waitForArchalWebhook } from 'archal/vitest';
+import { handleStripeWebhook } from './src/webhooks';
+
+const stripe = new Stripe('sk_test_fake');
+
+it('records a subscription when customer.subscription.created fires', async () => {
+  // 1. Register a webhook endpoint — the twin needs to know what events to queue
+  await stripe.webhookEndpoints.create({
+    url: 'http://test.local/stripe-wh',
+    enabled_events: ['customer.subscription.created'],
+  });
+
+  // 2. Trigger the event
+  const customer = await stripe.customers.create({ email: 'wh@x.com' });
+  const sub = await stripe.subscriptions.create({
+    customer: customer.id,
+    items: [{ price: 'price_existing_in_seed' }],
+  });
+
+  // 3. Pull the queued delivery
+  const event = await waitForArchalWebhook('stripe', 'customer.subscription.created');
+  expect(event.payload.data.object.id).toBe(sub.id);
+
+  // 4. Invoke your handler with the exact payload
+  await handleStripeWebhook(event.body, event.headers['Stripe-Signature'], process.env.STRIPE_WEBHOOK_SECRET);
+
+  // 5. Assert your handler did the right thing
+  // expect(await db.subscriptions.count()).toBe(1);
+});
+```
+
+**Important**: register the webhook endpoint on the twin *before* firing the
+event. If no endpoint is registered, the twin has nothing to queue and
+`waitForArchalWebhook()` will time out.
+
+**Signature verification**: `event.body` is the raw JSON string the twin
+would have POSTed. Pass it and `event.headers['Stripe-Signature']` directly
+to `stripe.webhooks.constructEvent(body, sig, secret)` — the signature is
+HMAC-computed against the body bytes, so re-serializing `event.payload`
+would break verification. Use the secret from the endpoint you registered.
+
+**Supported services**:
+
+| Service | Support | Notes |
+|---|---|---|
+| Stripe | ✅ | |
+| GitHub | ✅ | |
+| Slack | ✅ | Receiver-side signature only — see Slack caveat below |
+| Jira | ✅ | Delivered via history buffer (also POSTed to registered URLs) |
+| Linear | ✅ | Delivered via history buffer (also POSTed to registered URLs) |
+| Supabase | ❌ | Supabase webhooks are database-triggered; test against real Postgres or `supabase_functions.pg_net` directly |
+| Google Workspace | ❌ | No webhook API — uses GCP Pub/Sub push notifications |
+
+**Parallel workers caveat**: `waitForArchalWebhook()` consumes deliveries
+from a shared queue by default. When vitest runs test files in parallel
+across workers, worker A can swallow worker B's event. If your tests
+depend on webhook events, set `testIsolation: 'serial'` in your config.
+Alternatively, pass `consume: false` to leave the queue intact after a
+match and use `listArchalWebhooks('stripe')` for sequence assertions.
+
+**Slack caveat**: Slack verifies webhook signatures at the receiver using
+the timestamp header + signing secret, not a sender-side signature header.
+Archal's Slack twin does not add a `X-Slack-Signature` header to queued
+deliveries. If your handler verifies signatures, stub that verification
+in tests or compute the header yourself from `delivery.body`.
+
+### Test isolation across parallel workers
+
+Each vitest worker is automatically routed to its own per-worker state on the twin — parallel tests across workers don't see each other's writes. This is transparent: the integration reads `VITEST_WORKER_ID` in each worker process and tags every outbound SDK request with an `X-Archal-Worker-Id` header. The twin maintains a separate `StateEngine` per worker id, seeded from the baseline on first request.
+
+```ts
+// Test A, in worker 1
+const customer = await stripe.customers.create({ email: 'a@x.com' });
+// Test B, in worker 2 (running in parallel, same twin session)
+const list = await stripe.customers.list();
+// list does NOT include a@x.com — each worker's state is isolated
+```
+
+**Currently isolation-enabled twins**: Stripe, GitHub, Slack, Jira, Linear.
+
+**Twins without isolation** (Supabase, Google Workspace, Telegram, Ramp, Browser) fall back to shared state — the worker header is sent but the twin ignores it. Writes from all workers land in the same baseline state. If your tests depend on global assertions against these twins, use `testIsolation: 'serial'` (see below).
+
+**Memory note**: per-worker state costs N × baseline size per twin process. For 4 workers × 50 KB seed, that's ~200 KB per twin. Not a concern in practice.
+
+#### Forcing serial tests
+
+If your test suite needs full serialization (for example, it asserts on global counts across tests, or you're hitting one of the non-isolated twins), opt in to `testIsolation: 'serial'`:
+
+```ts
+archalVitestConfig({
+  services: { stripe: { mode: 'route' } },
+  testIsolation: 'serial',  // maxWorkers: 1, fileParallelism: false
+})
+```
+
+## What you see in the terminal
+
+On the first `vitest run`, session provisioning takes about 30 seconds (ECS Fargate cold start). The integration prints a progress line every few seconds so the wait is visible:
+
+```
+[archal] provisioning stripe twin... 5s
+[archal] provisioning stripe twins... 10s
+...
+```
+
+Subsequent runs with the same configuration reuse the warm session (~2 seconds).
+
+At the end of every run, the estimated twin-minute usage is printed:
+
+```
+[archal] ~2 twin-minutes for this run (38.5s × 1 twin: stripe)
+```
+
+Silence these outputs with `ARCHAL_VITEST_QUIET_PROGRESS=1` and `ARCHAL_VITEST_QUIET_USAGE=1`.
+
+## Authentication
+
+In priority order:
+
+1. `ARCHAL_VITEST_TOKEN` env var
+2. `ARCHAL_TOKEN` env var
+3. Stored credentials from `archal login` in `~/.archal/credentials.json`
+
+## Docs
+
+Full documentation: https://archal.ai/docs
+
+Full `@archal/vitest` reference: https://github.com/Archal-Labs/archal/tree/main/packages/vitest/README.md

package/dist/vitest.d.ts

@@ -1 +1 @@
-export { ArchalVitestProjectOptions, ArchalVitestProjectTestOptions, archalVitestProject, bootstrapArchalVitestRouting, getInstalledArchalVitestRuntime, getInstalledArchalVitestSession } from '@archal/vitest';
+export { ArchalVitestBuiltTestConfig, ArchalVitestProjectOptions, ArchalVitestProjectTestOptions, ArchalVitestPublicSessionSnapshot, ArchalWebhookDelivery, WaitForWebhookOptions, archalVitestConfig, archalVitestProject, bootstrapArchalVitestRouting, clearArchalWebhooks, getInstalledArchalVitestRuntime, getInstalledArchalVitestSession, listArchalWebhooks, resetArchalTwins, waitForArchalWebhook } from '@archal/vitest';

package/dist/vitest.js

@@ -1,13 +1,23 @@
 // src/vitest.ts
 import {
+  archalVitestConfig,
   archalVitestProject,
   bootstrapArchalVitestRouting,
+  clearArchalWebhooks,
   getInstalledArchalVitestRuntime,
-  getInstalledArchalVitestSession
+  getInstalledArchalVitestSession,
+  listArchalWebhooks,
+  resetArchalTwins,
+  waitForArchalWebhook
 } from "@archal/vitest";
 export {
+  archalVitestConfig,
   archalVitestProject,
   bootstrapArchalVitestRouting,
+  clearArchalWebhooks,
   getInstalledArchalVitestRuntime,
-  getInstalledArchalVitestSession
+  getInstalledArchalVitestSession,
+  listArchalWebhooks,
+  resetArchalTwins,
+  waitForArchalWebhook
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archal",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Pre-deployment testing for AI agents",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "prepare": "node scripts/prepare.cjs",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {