vanara 0.1.0 → 0.3.0

package/catalog/skills/refactoring-patterns/scripts/detect-smells.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// detect-smells.mjs — a tiny, dependency-free heuristic scanner that flags two
+// structural smells in a code string: long functions and deep nesting. It is a
+// teaching aid, not a real linter — it works on brace/indent heuristics, so it
+// is intentionally conservative.
+//
+// Usage:
+//   node detect-smells.mjs '<code string>'        # scan a literal string
+//   echo '<code>' | node detect-smells.mjs        # scan from stdin
+//   node detect-smells.mjs --selftest             # run built-in cases (exit 0/1)
+//
+// Thresholds (tunable):
+const MAX_FUNCTION_LINES = 25; // longer than this -> "long function"
+const MAX_NESTING_DEPTH = 4;   // deeper brace nesting than this -> "deep nesting"
+
+// Scan a code string and return an array of { type, message, line } findings.
+export function detectSmells(code, {
+  maxFunctionLines = MAX_FUNCTION_LINES,
+  maxNestingDepth = MAX_NESTING_DEPTH,
+} = {}) {
+  const lines = code.split(/\r?\n/);
+  const findings = [];
+
+  // --- deep nesting: track running brace depth ---
+  let depth = 0;
+  let maxSeenDepth = 0;
+  let deepLine = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const ch of line) {
+      if (ch === "{") {
+        depth++;
+        if (depth > maxSeenDepth) { maxSeenDepth = depth; deepLine = i + 1; }
+      } else if (ch === "}") {
+        depth = Math.max(0, depth - 1);
+      }
+    }
+  }
+  if (maxSeenDepth > maxNestingDepth) {
+    findings.push({
+      type: "deep-nesting",
+      message: `nesting depth ${maxSeenDepth} exceeds ${maxNestingDepth} (consider guard clauses)`,
+      line: deepLine,
+    });
+  }
+
+  // --- long function: brace-counted spans from a function header ---
+  const fnHeader = /\b(function\b|=>\s*\{|\)\s*\{)/;
+  for (let i = 0; i < lines.length; i++) {
+    if (!fnHeader.test(lines[i]) || !lines[i].includes("{")) continue;
+    let d = 0, started = false, span = 0, startLine = i + 1;
+    for (let j = i; j < lines.length; j++) {
+      for (const ch of lines[j]) {
+        if (ch === "{") { d++; started = true; }
+        else if (ch === "}") d--;
+      }
+      if (started) { span++; if (d <= 0) break; }
+    }
+    if (span > maxFunctionLines) {
+      findings.push({
+        type: "long-function",
+        message: `function spanning ${span} lines exceeds ${maxFunctionLines} (consider Extract Function)`,
+        line: startLine,
+      });
+    }
+  }
+
+  return findings;
+}
+
+function report(label, code) {
+  const findings = detectSmells(code);
+  if (findings.length === 0) {
+    console.log(`✓ ${label}: no smells detected`);
+    return true;
+  }
+  console.error(`✗ ${label}: ${findings.length} smell(s)`);
+  for (const f of findings) console.error(`    - [${f.type}] line ${f.line}: ${f.message}`);
+  return false;
+}
+
+function selftest() {
+  const clean = `
+function add(a, b) {
+  return a + b;
+}`;
+
+  const smelly = `
+function process(x) {
+  if (x) {
+    if (x.a) {
+      if (x.b) {
+        if (x.c) {
+          if (x.d) {
+            return x.a + x.b + x.c + x.d;
+          }
+        }
+      }
+    }
+  }
+  return 0;
+}`;
+
+  const longFn =
+    "function big() {\n" +
+    Array.from({ length: 30 }, (_, i) => `  const v${i} = ${i};`).join("\n") +
+    "\n  return 0;\n}";
+
+  const cases = [
+    { name: "clean (no smells)", code: clean, expectSmells: false },
+    { name: "deeply nested", code: smelly, expectSmells: true },
+    { name: "long function", code: longFn, expectSmells: true },
+  ];
+
+  let allOk = true;
+  for (const c of cases) {
+    const found = detectSmells(c.code);
+    const hasSmells = found.length > 0;
+    const ok = hasSmells === c.expectSmells;
+    allOk = allOk && ok;
+    console.log(
+      `${ok ? "✓" : "✗"} selftest ${c.name}: ${hasSmells ? `${found.length} smell(s)` : "clean"} ` +
+      `(expected ${c.expectSmells ? "smells" : "clean"})`
+    );
+    if (!ok) for (const f of found) console.log(`      [${f.type}] line ${f.line}: ${f.message}`);
+  }
+  process.exit(allOk ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === "--selftest") selftest();
+else if (arg) process.exit(report("code", arg) ? 0 : 1);
+else {
+  let buf = "";
+  process.stdin.on("data", (c) => (buf += c));
+  process.stdin.on("end", () => process.exit(report("stdin", buf) ? 0 : 1));
+}

package/catalog/skills/rest-api-design/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: rest-api-design
+description: Conventions for designing clean, consistent, evolvable REST APIs — resource modeling, HTTP semantics, status codes, pagination, filtering, error envelopes, versioning, idempotency, and security. A deep reference with worked examples and runnable checks.
+type: skill
+version: 2.0.0
+updated: 2026-06-28
+---
+# REST API Design
+
+A good REST API is **guessable**: once a consumer learns one endpoint, they can predict the rest. This
+skill is the deep reference for designing one — the principles, the decisions, the trade-offs, and the
+mistakes to avoid. Heavy detail lives in `references/`; copy-paste material in `examples/`; a runnable
+contract check in `scripts/`.
+
+## Mental model
+
+Design the API around **resources** (nouns) and use HTTP **verbs** to act on them. The protocol already
+gives you a rich vocabulary — methods, status codes, headers, caching — so lean on it instead of
+inventing your own conventions on top.
+
+| Concern | REST answer |
+|---|---|
+| What | a resource, named as a plural noun (`/orders`) |
+| Action | the HTTP method (GET/POST/PUT/PATCH/DELETE) |
+| Outcome | the status code (200/201/404/409…) |
+| Shape | a consistent response envelope |
+| Change | an explicit versioning strategy |
+
+## 1. Resource modeling
+
+1. Name collections as **plural nouns**: `/users`, `/orders`. Never verbs in the path (`/getUsers` is wrong — the verb is `GET`).
+2. Nest to show ownership, but only **one level deep**: `/users/{id}/orders` is fine; `/users/{id}/orders/{id}/items/{id}/...` is a smell — link instead.
+3. Model real-world actions that aren't CRUD as sub-resources or controller endpoints: `POST /orders/{id}/refunds` rather than `POST /refundOrder`.
+4. Keep identifiers stable and opaque to clients; don't leak DB internals (prefer UUIDs/ULIDs over auto-increment IDs where enumeration is a risk).
+
+## 2. HTTP method semantics
+
+| Method | Use | Safe | Idempotent |
+|---|---|---|---|
+| GET | read | yes | yes |
+| POST | create / non-idempotent action | no | no |
+| PUT | full replace | no | yes |
+| PATCH | partial update | no | no* |
+| DELETE | remove | no | yes |
+
+Respect these contracts — clients, proxies, and caches rely on them. A `GET` must never mutate state.
+See `references/status-codes.md` for the full status-code decision guide.
+
+## 3. Status codes
+
+Return the **accurate** code; never `200 OK` with an error body (it breaks every client's error handling).
+
+```http
+201 Created        Location: /orders/101      # after a successful POST
+204 No Content                                  # successful DELETE, no body
+400 Bad Request                                 # malformed/invalid input
+401 Unauthorized   # not authenticated      403 Forbidden  # authenticated, not allowed
+404 Not Found      409 Conflict   422 Unprocessable Entity   429 Too Many Requests
+```
+
+Full guidance and edge cases (404 vs 403 to avoid leaking existence, 409 vs 422) live in
+`references/status-codes.md`.
+
+## 4. The response envelope
+
+Standardize one shape across **every** endpoint so clients parse uniformly. See
+`examples/error-envelope.json` and validate any payload with `scripts/check-envelope.mjs`.
+
+```json
+{
+  "data": [ { "id": 101, "status": "open" } ],
+  "meta": { "nextCursor": "eyJpZCI6MTIwfQ", "limit": 20 },
+  "error": null
+}
+```
+
+On error, the same shape with `data: null` and a populated `error` (see §6).
+
+## 5. Pagination, filtering, sorting
+
+Every collection endpoint **must** paginate — an unbounded list is a latent outage. Prefer **cursor**
+pagination for large or frequently-changing data (offset pagination scans and skips rows, getting slower
+the deeper you go, and double-counts when rows are inserted mid-scan).
+
+```http
+GET /v1/orders?status=open&sort=-created_at&limit=20&cursor=eyJpZCI6MTAwfQ
+```
+
+The full comparison, cursor encoding, and pitfalls are in `references/pagination.md`.
+
+## 6. Error model
+
+One error shape, everywhere. A machine-readable `code`, a human `message`, and optional field-level
+`details`:
+
+```json
+{ "data": null, "error": {
+    "code": "validation_failed",
+    "message": "The request was invalid.",
+    "details": [ { "field": "email", "issue": "must be a valid email" } ]
+} }
+```
+
+Rules and the full catalogue of codes are in `references/error-handling.md`.
+
+## 7. Versioning & evolution
+
+APIs are forever once published. Version explicitly (`/v1/...` in the path is the most operationally
+clear) and treat additive changes as backward-compatible; breaking changes require a new version.
+Strategy and a deprecation playbook: `references/versioning.md`.
+
+## 8. Idempotency, concurrency, security
+
+- **Idempotency:** accept an `Idempotency-Key` header on `POST` so client retries don't double-create
+  (the server stores key → result and replays it). Essential for payments.
+- **Concurrency:** use `ETag` + `If-Match` for optimistic locking on updates to prevent lost writes.
+- **Security:** authenticate every request, authorize every action server-side (guard against IDOR by
+  checking ownership, not just authentication), rate-limit (return `429` + `Retry-After`), and validate
+  all input. Pairs with the `security-auditor` agent and the `owasp-top10` skill.
+
+## Common pitfalls (anti-patterns)
+
+- **`200 OK` with `{"success": false}`** — breaks HTTP error handling; use real status codes.
+- **Verbs in URLs** (`/createUser`) — the method is the verb.
+- **Unbounded list endpoints** — always paginate; a `/users` that returns 2M rows is a DoS on yourself.
+- **Inconsistent shapes** — one endpoint returns an array, another an object; clients can't generalize.
+- **Leaking existence** via 404-vs-403 to unauthorized users — be deliberate (see status-codes ref).
+- **Breaking changes without a version bump** — renaming/removing a field silently breaks consumers.
+
+## When NOT to use REST
+
+REST isn't always the right tool. Prefer **GraphQL** when clients need flexible, nested selections and
+you want to avoid over/under-fetching; prefer **gRPC** for low-latency internal service-to-service
+calls; prefer **webhooks/event streams** for server-push. REST shines for resource-oriented public
+HTTP APIs where cacheability and ubiquity matter.
+
+## Files in this package
+
+- `references/status-codes.md` — full status-code decision guide + edge cases
+- `references/pagination.md` — cursor vs offset, encoding, pitfalls
+- `references/versioning.md` — versioning strategies + deprecation playbook
+- `references/error-handling.md` — error shape, codes, validation details
+- `examples/orders-api.openapi.yaml` — a complete OpenAPI snippet
+- `examples/error-envelope.json` — canonical success/error payloads
+- `scripts/check-envelope.mjs` — runnable Node check that a payload matches the envelope
+
+Pairs with the `api-designer` agent, the `api-documenter` agent, and the `webhook-design` skill.

package/catalog/skills/rest-api-design/examples/error-envelope.json

@@ -0,0 +1,26 @@
+{
+  "success_list": {
+    "data": [
+      { "id": "101", "status": "open", "total": 49.0, "created_at": "2026-06-28T10:00:00Z" }
+    ],
+    "meta": { "nextCursor": "eyJpZCI6MTAxfQ", "limit": 20, "hasMore": true },
+    "error": null
+  },
+  "success_single": {
+    "data": { "id": "101", "status": "open", "total": 49.0 },
+    "error": null
+  },
+  "error_validation": {
+    "data": null,
+    "error": {
+      "code": "validation_failed",
+      "message": "The request was invalid.",
+      "details": [{ "field": "items", "issue": "must contain at least one item" }],
+      "requestId": "req_01HX2K"
+    }
+  },
+  "error_not_found": {
+    "data": null,
+    "error": { "code": "not_found", "message": "Order 999 not found.", "requestId": "req_01HX2M" }
+  }
+}

package/catalog/skills/rest-api-design/examples/orders-api.openapi.yaml

@@ -0,0 +1,106 @@
+openapi: 3.1.0
+info:
+  title: Orders API
+  version: "1.0.0"
+  description: Example of the conventions in this skill — plural nouns, accurate status codes, cursor pagination, consistent envelope.
+servers:
+  - url: https://api.example.com/v1
+paths:
+  /orders:
+    get:
+      summary: List orders
+      parameters:
+        - { name: status, in: query, schema: { type: string, enum: [open, paid, refunded] } }
+        - { name: sort, in: query, schema: { type: string, example: "-created_at" } }
+        - { name: limit, in: query, schema: { type: integer, default: 20, maximum: 100 } }
+        - { name: cursor, in: query, schema: { type: string } }
+      responses:
+        "200":
+          description: A page of orders
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OrderList" }
+        "401": { $ref: "#/components/responses/Error" }
+    post:
+      summary: Create an order
+      parameters:
+        - name: Idempotency-Key
+          in: header
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/OrderInput" }
+      responses:
+        "201":
+          description: Created
+          headers:
+            Location: { schema: { type: string }, description: URL of the new order }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OrderEnvelope" }
+        "422": { $ref: "#/components/responses/Error" }
+  /orders/{id}:
+    get:
+      summary: Get one order
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: The order
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OrderEnvelope" }
+        "404": { $ref: "#/components/responses/Error" }
+components:
+  responses:
+    Error:
+      description: Standard error envelope
+      content:
+        application/json:
+          schema: { $ref: "#/components/schemas/ErrorEnvelope" }
+  schemas:
+    Order:
+      type: object
+      properties:
+        id: { type: string }
+        status: { type: string, enum: [open, paid, refunded] }
+        total: { type: number }
+        created_at: { type: string, format: date-time }
+    OrderInput:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: { type: object, properties: { product_id: { type: string }, quantity: { type: integer } } }
+    Meta:
+      type: object
+      properties:
+        nextCursor: { type: string, nullable: true }
+        limit: { type: integer }
+        hasMore: { type: boolean }
+    OrderList:
+      type: object
+      properties:
+        data: { type: array, items: { $ref: "#/components/schemas/Order" } }
+        meta: { $ref: "#/components/schemas/Meta" }
+        error: { type: object, nullable: true }
+    OrderEnvelope:
+      type: object
+      properties:
+        data: { $ref: "#/components/schemas/Order" }
+        error: { type: object, nullable: true }
+    ErrorEnvelope:
+      type: object
+      properties:
+        data: { nullable: true }
+        error:
+          type: object
+          properties:
+            code: { type: string }
+            message: { type: string }
+            details: { type: array, items: { type: object } }
+            requestId: { type: string }

package/catalog/skills/rest-api-design/references/error-handling.md

@@ -0,0 +1,43 @@
+# Error Handling
+
+One error shape across every endpoint, with machine-readable codes and human-readable messages.
+
+## The shape
+```json
+{
+  "data": null,
+  "error": {
+    "code": "validation_failed",
+    "message": "The request was invalid.",
+    "details": [
+      { "field": "email", "issue": "must be a valid email" },
+      { "field": "age", "issue": "must be >= 18" }
+    ],
+    "requestId": "req_01HX..."
+  }
+}
+```
+
+## Rules
+- `code` is a **stable, machine-readable** string (clients branch on it) — e.g. `not_found`,
+  `validation_failed`, `rate_limited`, `conflict`. Don't change codes once published.
+- `message` is for humans/logs; never put sensitive data or stack traces in it.
+- `details` is optional, used for field-level validation errors.
+- Include a `requestId` so support can correlate a client report with server logs.
+- The HTTP status code and the `error.code` must agree (a `404` carries `not_found`).
+
+## Common codes ↔ status
+| code | status |
+|---|---|
+| `validation_failed` | 422 |
+| `not_found` | 404 |
+| `unauthorized` | 401 |
+| `forbidden` | 403 |
+| `conflict` | 409 |
+| `rate_limited` | 429 |
+| `internal_error` | 500 |
+
+## Don'ts
+- Don't return `200` with an error body.
+- Don't expose internal exception messages, SQL, or stack traces.
+- Don't use free-form, ever-changing error strings as the thing clients match on — that's what `code` is for.

package/catalog/skills/rest-api-design/references/pagination.md

@@ -0,0 +1,41 @@
+# Pagination — Cursor vs Offset
+
+Every collection endpoint must paginate. Choosing the wrong style causes slow queries and inconsistent
+results at scale.
+
+## Offset/limit
+```http
+GET /orders?limit=20&offset=40
+```
+- **Pros:** simple, allows jumping to an arbitrary page.
+- **Cons:** the database must scan and discard `offset` rows — page 10,000 is slow. Worse, if rows are
+  inserted/deleted while a client paginates, items get **skipped or duplicated** across pages.
+- **Use when:** datasets are small, or users genuinely need page numbers.
+
+## Cursor (keyset) pagination
+```http
+GET /orders?limit=20&cursor=eyJpZCI6MTAwfQ
+```
+- The cursor encodes the position (e.g. the last seen sort key), so the DB query is
+  `WHERE (created_at, id) < (:lastCreated, :lastId) ORDER BY created_at DESC, id DESC LIMIT :limit`.
+- **Pros:** O(limit) regardless of depth; stable under concurrent inserts/deletes.
+- **Cons:** no arbitrary page jumps; requires a stable, unique sort key (add a tiebreaker like `id`).
+- **Use when:** large, growing, or real-time data — the default for most production APIs.
+
+## Cursor encoding
+Encode the cursor opaquely (base64 of the sort key) so clients treat it as a token, not a number to
+manipulate:
+```
+cursor = base64({"created_at":"2026-06-28T10:00:00Z","id":100})
+```
+
+## Response shape
+```json
+{ "data": [ /* ... */ ], "meta": { "nextCursor": "eyJ...", "limit": 20, "hasMore": true } }
+```
+
+## Pitfalls
+- Always include a **unique tiebreaker** in the sort (e.g. `id`); sorting by a non-unique column alone
+  drops or repeats rows at page boundaries.
+- Cap `limit` server-side (e.g. max 100) so a client can't request a million rows.
+- Don't mix offset and cursor on the same endpoint — pick one.

package/catalog/skills/rest-api-design/references/status-codes.md

@@ -0,0 +1,32 @@
+# Status Codes — Decision Guide
+
+Return the most specific accurate code. Clients, proxies, and caches all key off the status line.
+
+## Success
+- `200 OK` — successful GET/PUT/PATCH with a body.
+- `201 Created` — successful POST that created a resource. Include a `Location` header pointing to it.
+- `202 Accepted` — accepted for async processing; not done yet (return a status URL).
+- `204 No Content` — success with no body (typical for DELETE).
+
+## Client errors
+- `400 Bad Request` — malformed syntax / unparseable.
+- `401 Unauthorized` — not authenticated (no/invalid credentials). Add `WWW-Authenticate`.
+- `403 Forbidden` — authenticated but not allowed.
+- `404 Not Found` — resource doesn't exist (or you're hiding its existence — see below).
+- `405 Method Not Allowed` — wrong verb for the resource. Include an `Allow` header.
+- `409 Conflict` — state conflict (e.g. duplicate, version mismatch on PUT).
+- `422 Unprocessable Entity` — syntactically valid but semantically invalid (failed validation).
+- `429 Too Many Requests` — rate limited. Include `Retry-After`.
+
+## Server errors
+- `500 Internal Server Error` — unexpected fault. Never leak stack traces to clients.
+- `503 Service Unavailable` — overloaded/down for maintenance. Include `Retry-After`.
+
+## Edge cases & judgement calls
+- **404 vs 403 (existence leakage):** if telling an unauthorized user a resource exists is itself a leak
+  (e.g. `/users/{id}` in a multi-tenant app), return `404` instead of `403` so attackers can't enumerate.
+- **400 vs 422:** use `400` for unparseable requests; `422` for well-formed requests that fail business
+  validation. Pick one convention and apply it consistently.
+- **409 vs 422 on conflict:** `409` for a conflict with current resource state (stale version, duplicate
+  unique key); `422` for input that can't be processed regardless of state.
+- **PUT semantics:** `200`/`204` if it replaced an existing resource; `201` if PUT created one.

package/catalog/skills/rest-api-design/references/versioning.md

@@ -0,0 +1,31 @@
+# Versioning & Evolution
+
+Once an API is public, other people's software depends on it. Plan to evolve without breaking them.
+
+## What is a breaking change?
+**Breaking** (needs a new version): removing/renaming a field or endpoint, changing a type, adding a
+required request field, changing status-code or error semantics, tightening validation.
+
+**Non-breaking** (safe in place): adding a new endpoint, adding an **optional** request field, adding a
+new field to a response (clients must ignore unknown fields — document this expectation).
+
+## Strategies
+| Strategy | Example | Notes |
+|---|---|---|
+| URI path | `/v1/orders` | Most operationally clear; easy routing, caching, logs. Most common. |
+| Header | `Accept: application/vnd.api.v1+json` | Cleaner URLs, harder to test/debug. |
+| Query param | `/orders?version=1` | Simple but easy to omit; weakest. |
+
+Recommendation: **URI path versioning** for public APIs — explicit and unambiguous.
+
+## Deprecation playbook
+1. Announce the new version and a deprecation date for the old one.
+2. Add a `Deprecation` (and optional `Sunset`) header to old-version responses.
+3. Maintain both versions during a published overlap window.
+4. Monitor old-version usage; reach out to remaining consumers.
+5. Remove only after usage approaches zero and the sunset date passes.
+
+## Tips
+- Avoid versioning as long as possible by making additive changes.
+- Never silently change behavior within a version — that's a breaking change in disguise.
+- Document unknown-field tolerance so adding fields stays non-breaking.

package/catalog/skills/rest-api-design/scripts/check-envelope.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Runnable check: validates that a JSON payload matches the standard response
+// envelope from this skill. Demonstrates an *executed*, verifiable example asset.
+//
+// Usage:
+//   node check-envelope.mjs '<json>'      # check a literal JSON string
+//   echo '<json>' | node check-envelope.mjs   # check from stdin
+//   node check-envelope.mjs --selftest    # run built-in test cases
+
+const RULES = [
+  ['has "data" key (may be null)', (o) => 'data' in o],
+  ['has "error" key', (o) => 'error' in o],
+  ['error is null OR an object with a string code', (o) =>
+    o.error === null || (typeof o.error === 'object' && typeof o.error.code === 'string')],
+  ['on error, data is null', (o) => o.error === null || o.data === null],
+  ['list responses include meta.limit', (o) =>
+    !Array.isArray(o.data) || (o.meta && typeof o.meta.limit === 'number')],
+];
+
+export function validateEnvelope(obj) {
+  const failures = RULES.filter(([, fn]) => !safe(fn, obj)).map(([msg]) => msg);
+  return { ok: failures.length === 0, failures };
+}
+
+function safe(fn, o) { try { return fn(o); } catch { return false; } }
+
+function check(label, json) {
+  let obj;
+  try { obj = typeof json === 'string' ? JSON.parse(json) : json; }
+  catch { console.error(`✗ ${label}: invalid JSON`); return false; }
+  const { ok, failures } = validateEnvelope(obj);
+  if (ok) console.log(`✓ ${label}: valid envelope`);
+  else { console.error(`✗ ${label}:`); failures.forEach((f) => console.error(`    - ${f}`)); }
+  return ok;
+}
+
+function selftest() {
+  const cases = {
+    valid_list: { data: [{ id: '1' }], meta: { limit: 20 }, error: null },
+    valid_error: { data: null, error: { code: 'not_found', message: 'x' } },
+    bad_200_error: { data: { id: '1' }, error: { code: 'oops' } }, // data not null on error -> fail
+    bad_list_no_meta: { data: [{ id: '1' }], error: null },        // list without meta.limit -> fail
+  };
+  let allExpected = true;
+  for (const [name, payload] of Object.entries(cases)) {
+    const { ok } = validateEnvelope(payload);
+    const shouldPass = name.startsWith('valid');
+    const correct = ok === shouldPass;
+    allExpected &&= correct;
+    console.log(`${correct ? '✓' : '✗'} selftest ${name}: ${ok ? 'valid' : 'invalid'} (expected ${shouldPass ? 'valid' : 'invalid'})`);
+  }
+  process.exit(allExpected ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) process.exit(check('payload', arg) ? 0 : 1);
+else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(check('stdin', buf) ? 0 : 1));
+}