docguard-cli 0.18.1 → 0.21.0

package/templates/demo-fixture/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+> Note: This demo CHANGELOG is intentionally missing an `[Unreleased]` section
+> so DocGuard's Changelog validator has something to flag.
+
+## [1.4.0] - 2026-04-12
+
+- Add scheduled retry for failed charges
+- Bump Stripe SDK to v15
+
+## [1.3.0] - 2026-03-28
+
+- Initial public release

package/templates/demo-fixture/DRIFT-LOG.md

@@ -0,0 +1,3 @@
+# DRIFT-LOG
+
+> Track intentional deviations from `docs-canonical/`. Every `// DRIFT:` comment in code needs a row here.

package/templates/demo-fixture/README.md

@@ -0,0 +1,17 @@
+# Acme Payments
+
+A payments microservice. Handles charges, refunds, balance lookups.
+
+## Stack
+- Node.js (ES modules)
+- PostgreSQL
+- Stripe for card processing
+
+## Quick start
+
+```bash
+npm install
+npm start
+```
+
+See `docs-canonical/` for the system specs.

package/templates/demo-fixture/docs-canonical/API-REFERENCE.md

@@ -0,0 +1,36 @@
+# API Reference
+
+> All requests require `Authorization: Bearer <jwt>` unless noted.
+
+## Charges
+
+### POST /charge
+Create a new charge.
+
+**Request body**
+```json
+{ "amount_cents": 1000, "currency": "USD", "customer_id": "cus_..." }
+```
+
+**Response** — `201 Created` with the charge object.
+
+### POST /refund
+Refund a previous charge.
+
+**Request body**
+```json
+{ "charge_id": "ch_...", "amount_cents": 1000 }
+```
+
+## Balance
+
+### GET /balance/:customer_id
+Look up a customer's current balance.
+
+**Response**
+```json
+{ "customer_id": "cus_...", "available_cents": 12345 }
+```
+
+<!-- Demo drift: code also exposes POST /webhooks (Stripe callbacks) but it's
+     missing from this reference. DocGuard's API-Surface validator catches it. -->

package/templates/demo-fixture/docs-canonical/ARCHITECTURE.md

@@ -0,0 +1,30 @@
+# ARCHITECTURE — Acme Payments
+
+> The system has **3 services**. (Demo drift: code actually has 4 — see `src/`.)
+
+## Components
+
+```
+┌───────────┐   queue   ┌──────────┐   cron   ┌────────────┐
+│   API     │ ────────> │  Worker  │ <─────── │ Scheduler  │
+│ (HTTP)    │           │ (jobs)   │          │ (timers)   │
+└───────────┘           └──────────┘          └────────────┘
+```
+
+### API
+Handles HTTP requests. Routes live in `src/api.mjs`.
+
+### Worker
+Consumes the job queue. Long-running tasks (capture, refund settlement).
+
+### Scheduler
+Cron-style triggers for retries and reconciliation.
+
+## Data flow
+1. Client POSTs to `/charge` → API validates → enqueues `process_charge` job
+2. Worker dequeues → calls Stripe → writes result to DB
+3. Scheduler reruns failed charges hourly
+
+## See also
+- `DATA-MODEL.md` for the persistence layer
+- `SECURITY.md` for auth + secrets handling

package/templates/demo-fixture/docs-canonical/DATA-MODEL.md

@@ -0,0 +1,30 @@
+# Data Model
+
+## charges
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `id` | `uuid` (PK) | |
+| `customer_id` | `text` | |
+| `amount_cents` | `bigint` | |
+| `currency` | `text` | ISO-4217 |
+| `status` | `text` | `pending` / `succeeded` / `failed` |
+| `stripe_id` | `text` | nullable |
+| `created_at` | `timestamptz` | default now() |
+
+## refunds
+
+| Column | Type |
+|--------|------|
+| `id` | `uuid` (PK) |
+| `charge_id` | `uuid` (FK → charges) |
+| `amount_cents` | `bigint` |
+| `created_at` | `timestamptz` |
+
+## customers
+
+| Column | Type |
+|--------|------|
+| `id` | `text` (PK, `cus_...`) |
+| `email` | `text` |
+| `created_at` | `timestamptz` |

package/templates/demo-fixture/docs-canonical/ENVIRONMENT.md

@@ -0,0 +1,20 @@
+# Environment
+
+Required environment variables.
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` | Yes | Postgres connection string |
+| `STRIPE_SECRET_KEY` | Yes | Stripe API key (server-side) |
+| `REDIS_URL` | Yes | Redis URL for the job queue |
+
+<!-- Demo drift: REDIS_URL is documented here but missing from .env.example.
+     Also, JWT_SECRET is in .env.example + used in code, but not listed here.
+     DocGuard's Environment validator catches both. -->
+
+## Local development
+
+```bash
+cp .env.example .env
+# Fill in the values above
+```

package/templates/demo-fixture/docs-canonical/SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+## Authentication
+HTTP API requires `Authorization: Bearer <jwt>`. Tokens are signed with `JWT_SECRET`.
+
+## Secrets
+- `STRIPE_SECRET_KEY` — never logged
+- `JWT_SECRET` — rotated quarterly
+
+## Threat model
+- Card data is never stored locally — Stripe-tokenized only
+- `JWT_SECRET` rotation invalidates outstanding sessions (acceptable for an internal API)
+
+## Audit log
+Every charge / refund writes to the `audit_events` table.

package/templates/demo-fixture/docs-canonical/TEST-SPEC.md

@@ -0,0 +1,10 @@
+# Test Spec
+
+## Coverage rules
+- Every route in `src/api.mjs` must have an integration test in `tests/api/`
+- Every worker job must have a unit test in `tests/worker/`
+
+## Layers
+- **Unit** — pure logic, no I/O
+- **Integration** — hits a local Postgres + Stripe in test mode
+- **E2E** — against a staging stack (rare; only for release candidates)

package/templates/demo-fixture/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "acme-payments",
+  "version": "1.4.0",
+  "description": "Demo project for DocGuard — a 4-service payments API with intentional doc drift.",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node src/api.mjs"
+  }
+}

package/templates/demo-fixture/src/api.mjs

@@ -0,0 +1,18 @@
+// API service — handles HTTP routes.
+import { createServer } from 'node:http';
+
+// Routes intentionally include /webhooks (not in API-REFERENCE.md — demo drift)
+const ROUTES = {
+  'POST /charge':            createCharge,
+  'POST /refund':            createRefund,
+  'GET /balance/:customer':  getBalance,
+  'POST /webhooks':          handleStripeWebhook,   // ← undocumented
+};
+
+async function createCharge(req)  { /* ... */ }
+async function createRefund(req)  { /* ... */ }
+async function getBalance(req)    { /* ... */ }
+async function handleStripeWebhook(req) { /* ... */ }
+
+const PORT = process.env.PORT || 3000;
+createServer((req, res) => { /* router */ }).listen(PORT);

package/templates/demo-fixture/src/notifier.mjs

@@ -0,0 +1,23 @@
+// Notifier service — emails / Slack alerts on big charges or failures.
+// ⚠️ Demo drift: ARCHITECTURE.md only mentions 3 services (API, Worker, Scheduler).
+//    This fourth one (Notifier) is in code but missing from the architecture doc.
+//    DocGuard's Docs-Diff + Docs-Coverage validators surface this.
+
+import { Stripe } from './lib/stripe.mjs';
+
+export async function notifyLargeCharge(charge) {
+  if (charge.amount_cents > 100000) {
+    await sendSlack(`💰 Large charge: $${charge.amount_cents / 100}`);
+  }
+}
+
+export async function notifyFailure(charge, error) {
+  await sendEmail({
+    to: 'oncall@acme.dev',
+    subject: `Charge failed: ${charge.id}`,
+    body: error.message,
+  });
+}
+
+async function sendSlack(text) { /* ... */ }
+async function sendEmail(opts) { /* ... */ }

package/templates/demo-fixture/src/scheduler.mjs

@@ -0,0 +1,8 @@
+// Scheduler service — cron-style triggers.
+import { enqueue } from './queue.mjs';
+
+// Retry failed charges hourly
+setInterval(async () => {
+  const failed = await db.query('SELECT id FROM charges WHERE status = $1', ['failed']);
+  for (const row of failed.rows) await enqueue({ type: 'process_charge', charge_id: row.id });
+}, 60 * 60 * 1000);

package/templates/demo-fixture/src/worker.mjs

@@ -0,0 +1,15 @@
+// Worker service — consumes job queue.
+import { connect } from './queue.mjs';
+
+const handlers = {
+  process_charge: async (job)   => { /* call Stripe */ },
+  process_refund: async (job)   => { /* call Stripe refund API */ },
+  settle_refund:  async (job)   => { /* mark refund as settled */ },
+};
+
+const queue = await connect(process.env.REDIS_URL);
+queue.consume(async (job) => {
+  const handler = handlers[job.type];
+  if (!handler) throw new Error(`Unknown job: ${job.type}`);
+  await handler(job);
+});