chore: crush git history - reborn from consolidation on 2026-03-10

2026-03-10 00:00:00 -07:00
commit d278c4b105
313 changed files with 87549 additions and 0 deletions
@@ -0,0 +1,210 @@
+# Getting Started with APOPHIS
+
+Get from install to your first behavioral bug in 10 minutes.
+
+## Prerequisites
+
+- Node.js 20.x or 22.x
+- A Fastify app with `@fastify/swagger` registered
+
+## Step 1: Install
+
+```bash
+npm install apophis-fastify fastify @fastify/swagger
+```
+
+## Step 2: Scaffold
+
+```bash
+apophis init --preset safe-ci
+```
+
+This creates:
+
+- `apophis.config.js` — config with a `quick` profile
+- `APOPHIS.md` — preset-specific guidance
+- Package script: `npm run apophis:verify`
+
+## Step 3: Add One Behavioral Contract
+
+Pick one important route. Add an `x-ensures` clause that checks behavior across operations:
+
+```javascript
+app.post('/users', {
+  schema: {
+    'x-category': 'constructor',
+    'x-ensures': [
+      // BEHAVIORAL: Creating a user must make it retrievable
+      'response_code(GET /users/{response_body(this).id}) == 200'
+    ]
+  }
+}, async (request, reply) => {
+  const { name } = request.body;
+  const id = `usr-${Date.now()}`;
+  reply.status(201);
+  return { id, name };
+});
+```
+
+## Step 4: Run Verify
+
+```bash
+apophis verify --profile quick --routes "POST /users"
+```
+
+APOPHIS will:
+
+1. Discover routes from your Fastify app
+2. Filter to `POST /users`
+3. Generate test data from the schema
+4. Execute the route
+5. Check the behavioral contract
+6. Print pass/fail, seed, and replay command
+
+## Example Failure
+
+If your `GET /users/:id` handler has a bug (always returns 404), APOPHIS catches it:
+
+```text
+Contract violation
+POST /users
+Profile: quick
+Seed: 42
+
+Expected
+  response_code(GET /users/{response_body(this).id}) == 200
+
+Observed
+  GET /users/usr-123 returned 404
+
+Why this matters
+  The resource created by POST /users is not retrievable.
+
+Replay
+  apophis replay --artifact reports/apophis/failure-2026-04-28T12-30-22Z.json
+
+Next
+  Check the create/read consistency for POST /users and GET /users/{id}.
+```
+
+## Step 5: Replay and Fix
+
+Copy the replay command and run it:
+
+```bash
+apophis replay --artifact reports/apophis/failure-2026-04-28T12-30-22Z.json
+```
+
+Fix the bug in your handler. Re-run verify. The failure should now pass.
+
+## Next Steps
+
+- Add more routes to your profile: `apophis verify --profile quick --routes "POST /users,PUT /users/:id"`
+- Run all routes: `apophis verify --profile quick`
+- Run only changed routes in CI: `apophis verify --profile ci --changed`
+- Add observe mode for runtime drift detection: see [docs/observe.md](docs/observe.md)
+- Add qualify mode for scenario, stateful, and chaos checks: see [docs/qualify.md](docs/qualify.md)
+
+## Config Reference
+
+```javascript
+// apophis.config.js
+export default {
+  mode: 'verify',
+  profile: 'quick',
+  profiles: {
+    quick: {
+      name: 'quick',
+      mode: 'verify',
+      preset: 'safe-ci',
+      routes: ['POST /users']
+    },
+    ci: {
+      name: 'ci',
+      mode: 'verify',
+      preset: 'safe-ci',
+      routes: []
+    }
+  },
+  presets: {
+    'safe-ci': {
+      name: 'safe-ci',
+      depth: 'quick',
+      timeout: 5000,
+      parallel: false,
+      chaos: false,
+      observe: false
+    }
+  },
+  environments: {
+    local: {
+      name: 'local',
+      allowVerify: true,
+      allowObserve: true,
+      allowQualify: false,
+      allowChaos: false,
+      allowBlocking: true,
+      requireSink: false
+    }
+  }
+};
+```
+
+## Monorepo Workspaces
+
+APOPHIS supports workspace-wide operations with the `--workspace` flag.
+
+### Root package.json scripts
+
+```json
+{
+  "scripts": {
+    "apophis:verify": "apophis verify --workspace --profile quick",
+    "apophis:doctor": "apophis doctor --workspace",
+    "apophis:qualify": "apophis qualify --workspace --profile ci"
+  }
+}
+```
+
+### Workspace fan-out
+
+Run verify across all packages:
+
+```bash
+apophis verify --workspace --profile quick --format json
+```
+
+Output is package-attributed:
+
+```json
+{
+  "exitCode": 0,
+  "runs": [
+    {
+      "package": "api",
+      "cwd": "/repo/packages/api",
+      "artifact": { ... }
+    },
+    {
+      "package": "web",
+      "cwd": "/repo/packages/web",
+      "artifact": { ... }
+    }
+  ]
+}
+```
+
+### Supported commands
+
+- `apophis verify --workspace`
+- `apophis doctor --workspace`
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Behavioral / qualification failure |
+| 2 | Usage, config, or environment safety violation |
+| 3 | Internal APOPHIS error |
+| 130 | Interrupted (SIGINT) |