archal 0.9.8 → 0.9.9

package/README.md

@@ -1,38 +1,155 @@
 # archal
 
-Pre-deployment testing for AI agents via Archal's hosted digital twins.
+Pre-deployment testing for AI agents via Archal's hosted digital twins,
+including route-mode twins for Discord, GitHub, Slack, Stripe, Linear, Jira,
+Ramp, Supabase, and Google Workspace.
+
+## Early access — expect rough edges
+
+`archal@0.9.x` is early access. The CLI and twins work, but the surface is
+still being polished:
+
+- `npm install -g archal` prints a handful of peer-dependency warnings
+  from the vendored CLI runtime. They are safe to ignore; nothing is
+  missing at runtime.
+- A few commands still print one or two help lines to `stderr` instead of
+  `stdout`. Scripts that redirect streams will mostly see what they expect,
+  but be aware of it.
+- The `vitest` integration under `archal/vitest` depends on `vitest@^2.1.0`.
+  If your project is on vitest 3, the shared helper may resolve the wrong
+  copy. Pinning a workspace to vitest 2 for your Archal tests fixes it.
+
+We're shipping `0.9.x` so that early users can start running the CLI against
+hosted twins. File anything surprising at
+<https://github.com/Archal-Labs/archal/issues>.
 
 ## Install
 
 ```bash
-npm install --save-dev archal
+npm install -g archal
 ```
 
 Then authenticate:
 
 ```bash
-npx archal login
+archal login
 ```
 
-## Vitest Integration (primary use case)
+This writes credentials to `~/.archal/credentials.json`. You can also set
+`ARCHAL_TOKEN` directly in CI.
+
+## CLI — 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.
+The CLI is the primary way to use Archal today. `archal run` executes a
+scenario (a markdown file describing a task, the expected behavior, and
+success criteria) against a hosted twin session and reports a satisfaction
+score.
 
-### Quick start — single `vitest.config.ts`
+### Quick start
+
+```bash
+# 1. Log in
+archal login
+
+# 2. Browse the twin catalog
+archal twin
+
+# 3. Start a persistent session with one or more twins
+archal twin start github stripe
+
+# 4. Run a scenario from .archal.json in the current directory
+archal run
+
+# 5. When you're done
+archal twin stop
+```
+
+`archal run` auto-discovers an `.archal.json` at the project root. A
+minimal config looks like this:
+
+```json
+{
+  "scenarios": "./scenarios",
+  "twins": ["github", "stripe"],
+  "runs": 1
+}
+```
+
+### Supported twins
+
+`archal twin` lists the nine twins available today:
+
+| Twin | Notes |
+|---|---|
+| Discord | Guilds, channels, messages, members |
+| GitHub | Repos, issues, PRs, labels, reviews |
+| Slack | Channels, messages, users, reactions |
+| Stripe | Customers, subscriptions, invoices, products |
+| Linear | Teams, issues, projects, cycles |
+| Jira | Projects, issues, workflows, components |
+| Ramp | Cards, transactions, reimbursements, users |
+| Supabase | Auth, Postgres, storage, edge functions |
+| Google Workspace | Gmail, Drive, Calendar, Docs, People |
+
+### Command reference
+
+| Command | What it does |
+|---|---|
+| `archal login` | Authenticate with Archal |
+| `archal logout` | Remove stored credentials |
+| `archal twin` | Browse the twin catalog |
+| `archal twin start [twins...]` | Start a hosted twin session |
+| `archal twin status` | Inspect the active session |
+| `archal twin stop` | Stop the active session |
+| `archal twin list` | List all your active sessions |
+| `archal twin attach <uuid>` | Reattach to a session by id |
+| `archal twin renew <seconds>` | Extend the session lifetime |
+| `archal twin reset` | Reset twin state without tearing down the session |
+| `archal twin seed <twin> <name>` | Load a named seed into a running twin |
+| `archal run [.archal.json]` | Run scenarios from a config file |
+| `archal scenario list` | Browse local and hosted scenarios |
+| `archal seed list [twin]` | List prebuilt twin seeds |
+| `archal trace` | View recent scenario traces |
+| `archal trace <name>` | View trace details for a run |
+| `archal usage` | Check session minutes and plan |
+
+Run `archal <command> --help` for flag details.
+
+## Vitest integration (secondary use case)
+
+You can also import `archal/vitest` to route SDK traffic from a vitest
+suite through a hosted twin, with no code changes to your production
+code. This is useful if you want to test the HTTP side of an integration
+without hitting real provider APIs.
+
+> Note: the vitest helper is still evolving. If you're just getting
+> started with Archal, prefer the CLI flow above — it's the best-tested
+> path today.
+
+### Minimal config
 
 ```ts
 import { defineConfig } from 'vitest/config';
-import { archalVitestConfig } from 'archal/vitest';
+import { withArchal } from 'archal/vitest';
 
 export default defineConfig({
-  test: archalVitestConfig({
-    services: {
-      stripe: { mode: 'route', seed: 'small-business' },
+  test: withArchal(
+    {
+      // everything you already had in test:, unchanged
+      globals: true,
+      coverage: { provider: 'v8' },
     },
-  }),
+    {
+      services: {
+        stripe: { mode: 'route', seed: 'small-business' },
+      },
+    },
+  ),
 });
 ```
 
+`withArchal(existingTest, { services })` wraps an existing `vitest.config.ts`'s `test:` block, preserving every field you already had. Pass `{}` as the first argument if you're starting from scratch.
+
 Your existing tests work unchanged:
 
 ```ts
@@ -48,22 +165,6 @@ it('creates a customer', async () => {
 });
 ```
 
-### 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
@@ -77,10 +178,10 @@ beforeEach(async () => {
 
 ### 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.
+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';
@@ -110,87 +211,68 @@ it('records a subscription when customer.subscription.created fires', async () =
 
   // 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**:
+**Webhook coverage**:
 
 | Service | Support | Notes |
 |---|---|---|
 | Stripe | ✅ | |
 | GitHub | ✅ | |
-| Slack | ✅ | Receiver-side signature only — see Slack caveat below |
+| Slack | ✅ | Receiver-side signature only |
 | 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 |
+| Supabase | ❌ | Database-triggered — test against real Postgres |
+| Google Workspace | ❌ | GCP Pub/Sub push notifications, not webhooks |
 
 **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.
+Each vitest worker is routed to its own per-worker state on the twin —
+parallel tests across workers don't see each other's writes. 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 state engine 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
-```
+**Isolation-enabled twins**: Stripe, GitHub, Slack, Jira, Linear.
 
-**Currently isolation-enabled twins**: Stripe, GitHub, Slack, Jira, Linear.
+**Twins without isolation** (Supabase, Google Workspace, Ramp) fall back
+to shared state. If your tests depend on global assertions against those
+twins, set `testIsolation: 'serial'`.
 
-**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.
+## Authentication
 
-#### Forcing serial tests
+In priority order:
 
-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'`:
+1. `ARCHAL_TOKEN` env var
+2. Stored credentials from `archal login` in `~/.archal/credentials.json`
 
-```ts
-archalVitestConfig({
-  services: { stripe: { mode: 'route' } },
-  testIsolation: 'serial',  // maxWorkers: 1, fileParallelism: false
-})
-```
+This auth is only for Archal's hosted session provisioning. Your app's
+provider credentials do not need to be real when traffic is routed through
+a twin — use placeholder tokens that satisfy the SDK's local validation
+rules, such as `sk_test_fake`, `ghp_fake_token_for_twin`, or a dummy
+Google bearer token.
 
-## What you see in the terminal
+## What you'll 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:
+On the first `archal run`, session provisioning takes about 30 seconds
+(ECS Fargate cold start). A progress line prints every few seconds so
+the wait is visible:
 
 ```
 [archal] provisioning stripe twin... 5s
-[archal] provisioning stripe twins... 10s
+[archal] provisioning stripe twin... 10s
 ...
 ```
 
-Subsequent runs with the same configuration reuse the warm session (~2 seconds).
+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:
 
@@ -198,18 +280,6 @@ 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
+Full documentation: <https://docs.archal.ai>

package/bin/archal.cjs

@@ -3,12 +3,12 @@
 const { existsSync } = require("node:fs");
 const { join } = require("node:path");
 
-// Try the co-located CLI bundle first (when installed as dependency),
-// then fall back to resolving @archal/cli directly.
 const localDist = join(__dirname, "..", "dist", "index.cjs");
 
 if (existsSync(localDist)) {
   require(localDist);
 } else {
-  require("@archal/cli");
+  throw new Error(
+    'The archal package is missing its bundled CLI payload. Use the published npm package, or build from the Archal repo root with `pnpm run build:archal`.',
+  );
 }