voidforge-build 23.10.0 → 23.11.1

package/dist/docs/patterns/multi-tenant-property-test.ts

@@ -0,0 +1,127 @@
+/**
+ * Pattern: Multi-Tenant Property Test
+ *
+ * Source: Field report #315 M4 (Caroline first-user-test, 2026-03-31).
+ * Caroline found 10 multi-tenant bugs that prior gauntlets missed because
+ * regression tests lock known cases — they don't test the underlying
+ * property: "for any two orgs A and B, A's writes never appear in B's reads."
+ *
+ * This pattern provides the property-based test that closes the gap. Use it
+ * on every project with org_id (or tenant_id, workspace_id) scoping.
+ *
+ * The TS version below is illustrative (vitest + fast-check). Python
+ * (Hypothesis) and Go variants follow the same shape — generate random
+ * org pairs and write payloads, assert no cross-tenant leak.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import fc from 'fast-check';
+
+// ── Test harness contract ────────────────────────────────────────────────
+//
+// The harness must provide:
+//   - createOrg() → { id, apiKey, userId }      (fresh tenant per call)
+//   - writeAsOrg(org, endpoint, payload)        (authenticated POST/PUT)
+//   - readAsOrg(org, endpoint)                  (authenticated GET, paginated)
+//   - listAllReadEndpoints() → string[]         (every GET that returns rows)
+//   - listAllWriteEndpoints() → string[]        (every POST/PUT/DELETE)
+//   - resetDb()                                  (drop + reseed schema)
+
+declare const harness: {
+  createOrg(): Promise<{ id: number; apiKey: string; userId: string }>;
+  writeAsOrg(org: { apiKey: string }, endpoint: string, payload: unknown): Promise<{ id: string }>;
+  readAsOrg(org: { apiKey: string }, endpoint: string): Promise<Array<{ id: string; org_id?: number }>>;
+  listAllReadEndpoints(): string[];
+  listAllWriteEndpoints(): string[];
+  resetDb(): Promise<void>;
+};
+
+// ── The Property ─────────────────────────────────────────────────────────
+
+describe('multi-tenant isolation property', () => {
+  beforeEach(async () => harness.resetDb());
+
+  test('writes by org A never appear in reads by org B', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        // Random pair of orgs (always distinct)
+        fc.tuple(fc.constant(null), fc.constant(null)),
+        // Random write endpoint
+        fc.constantFrom(...harness.listAllWriteEndpoints()),
+        // Random payload — your codebase's payload generator goes here
+        randomPayload(),
+        async (_pair, writeEndpoint, payload) => {
+          const orgA = await harness.createOrg();
+          const orgB = await harness.createOrg();
+
+          // 1. Org A writes
+          const written = await harness.writeAsOrg(orgA, writeEndpoint, payload);
+
+          // 2. Every read endpoint, queried as Org B, must NOT contain the write
+          for (const readEndpoint of harness.listAllReadEndpoints()) {
+            const rowsB = await harness.readAsOrg(orgB, readEndpoint);
+            const leaked = rowsB.find((row) => row.id === written.id);
+            if (leaked) {
+              throw new Error(
+                `LEAK: ${writeEndpoint} write by org ${orgA.id} surfaced in ` +
+                `${readEndpoint} read by org ${orgB.id}. Row: ${JSON.stringify(leaked)}`,
+              );
+            }
+          }
+        },
+      ),
+      { numRuns: 100, timeout: 60_000 },
+    );
+  });
+
+  test('superuser/admin pool acquisition does NOT bypass per-org reads', async () => {
+    // Companion property: admin-pool callers (cross-tenant by design) must
+    // still respect org_id when calling tenant endpoints. Field report #318
+    // §5: SUPERUSER + BYPASSRLS=t hides policy bugs. Test under non-owner role.
+    const orgA = await harness.createOrg();
+    const orgB = await harness.createOrg();
+
+    await harness.writeAsOrg(orgA, '/api/people', { name: 'A1' });
+    const rowsB = await harness.readAsOrg(orgB, '/api/people');
+    expect(rowsB.find((r) => r.org_id === orgA.id)).toBeUndefined();
+  });
+});
+
+function randomPayload(): fc.Arbitrary<unknown> {
+  // Generic structure — narrow per-endpoint in real implementations.
+  return fc.record({
+    name: fc.string({ minLength: 1, maxLength: 50 }),
+    note: fc.option(fc.string({ maxLength: 200 })),
+    tags: fc.array(fc.string(), { maxLength: 5 }),
+  });
+}
+
+// ── Python (Hypothesis) sketch ───────────────────────────────────────────
+//
+// from hypothesis import given, strategies as st, settings
+//
+// @given(write_endpoint=st.sampled_from(WRITE_ENDPOINTS),
+//        payload=payload_strategy())
+// @settings(max_examples=100, deadline=None)
+// def test_no_cross_tenant_leak(write_endpoint, payload):
+//     reset_db()
+//     org_a, org_b = create_org(), create_org()
+//     written = write_as_org(org_a, write_endpoint, payload)
+//     for read_endpoint in READ_ENDPOINTS:
+//         rows_b = read_as_org(org_b, read_endpoint)
+//         assert not any(r['id'] == written['id'] for r in rows_b), \
+//             f"LEAK: {write_endpoint} -> {read_endpoint}"
+//
+// ── Anti-patterns ────────────────────────────────────────────────────────
+//
+// 1. Testing isolation only on known endpoints. The bug is in the endpoint
+//    you forgot. Property tests enumerate the full surface.
+// 2. Using SUPERUSER fixtures. They silently bypass FORCE RLS at the engine
+//    level. Use the runtime non-owner role (`{project}_app`, BYPASSRLS=f).
+//    See /docs/patterns/rls-test-fixture.py.
+// 3. Locking the property to "100% pass" without expanding the endpoint
+//    list as the codebase grows. listAll{Read,Write}Endpoints() must be
+//    derived dynamically (route enumeration, not hardcoded).
+// 4. Testing only "row id leaks." Add field-level checks for any column
+//    holding semi-sensitive data (emails, internal notes) — leaks of
+//    *content* without row visibility are equally bad.

package/dist/docs/patterns/refactor-extraction.md

@@ -0,0 +1,96 @@
+# Pattern: Large-Refactor Extraction (8-commit per-entity)
+
+**When to use:** A 1,000+ LOC router/service/handler file needs splitting and the project has an existing exit gate (e.g., max-LOC-per-file). Single-commit refactors of files this size cause review fatigue, hide bugs in the diff noise, and are nearly impossible to revert surgically.
+
+**Source:** Field report #320 §1. M-10 (Union Station): `routers/crm.py` 1,861 → 597 LOC across 8 commits. 0 regressions. Test count grew 2,099 → 2,246 (+147). Exit gate met with 78 LOC of headroom. The 5th commit's IDOR matrix surfaced a route-shadow bug that had made `PATCH /people/batch-update` unreachable in production for an unknown duration.
+
+This is the cleanest large-refactor template I've documented. Use it.
+
+## Architecture-Quick (Picard)
+
+Before any commit, write a 1-2 page architecture doc to `logs/reviews/<topic>-architecture.md`:
+
+```markdown
+# Refactor: <topic> — extraction plan
+
+## Current state
+- Source file: <path> at <LOC>
+- Exit gate: <LOC limit>
+- LOC delta needed: <gate - current>
+
+## Entity inventory
+| Entity | Endpoints | Estimated LOC delta |
+|---|---|---|
+| people | 7 | -167 |
+| companies | 10 | -345 |
+| ... | ... | ... |
+| | **Total** | **−1264** |
+
+## Commit plan (one per entity + scaffold + cleanup)
+| # | Commit | Adds | Removes | Cumulative LOC |
+|---|---|---|---|---|
+| 1 | scaffold (service base, error types, shared helpers) | services/_base.py | — | 1861 |
+| 2 | extract people | services/people_service.py | router code | 1694 |
+| ... | ... | ... | ... | ... |
+| 8 | cleanup (lift duplicated helpers, prune imports, lint) | — | router cleanup | 597 |
+
+## Function-signature contract (per service)
+- org_id: int (first), user_id: str (second)
+- Returns plain dict (no FastAPI Response wrappers)
+- Raises ApiError (no HTTPException — service knows nothing of HTTP)
+- No FastAPI imports in service modules
+
+## Roles
+- Strange — lead, owns sequencing
+- Stark — router-side rewrites (thin wrappers calling service)
+- Batgirl — IDOR matrix tests per entity
+- Coulson — version + commit per step
+
+## IDOR contract
+- Pattern A (primary): every service method takes org_id as first param,
+  every query is scoped, every test in matrix asserts cross-org denial
+- Pattern B (fallback): if a method legitimately spans tenants, document
+  the policy and test cross-tenant authorization explicitly
+```
+
+## Per-Commit Shape
+
+Each entity commit follows the same shape. Keep them mechanically uniform:
+
+1. **Extract** to `services/<entity>_service.py` — pure business logic, no FastAPI imports
+2. **Rewrite** the router file as thin wrappers: validate → call service → format response
+3. **Add** IDOR matrix tests for parametric paths AND fixed-suffix paths under same entity prefix (see `/docs/methods/SECURITY_AUDITOR.md` IDOR Matrix section)
+4. **Verify** LOC trajectory: `git diff --stat HEAD~1 -- routers/<file>.py` shows monotonic decrease; service module count grows by 1
+5. **Run targeted pytest** on touched files only (`pytest tests/services/test_<entity>_service.py tests/routers/test_<entity>.py`) — full suite is the orchestrator's gate, not the agent's
+6. **Commit** with a "Deviations from Contract" section in the build report (see SUB_AGENTS.md)
+
+## Final Cleanup Commit
+
+Commit 8 (or N for an N-entity refactor) is non-obvious and load-bearing:
+
+- Lift duplicated helpers that emerged across entities into a shared module
+- Prune unused imports in the router file (extraction leaves behind imports the wrappers no longer need)
+- Add lint scaffold if missing (LOC limit, signature-contract assertion)
+- Verify no test files were dropped (mock paths often need updating to follow the extracted code)
+- Confirm exit gate met with documented headroom: `wc -l routers/<file>.py`
+
+## What This Pattern Caught
+
+The IDOR matrix test in commit 5 (M-10 batch.py) surfaced that `/people/{person_id}` was shadowing `/people/batch-update`. FastAPI dispatches first-matching-route; a parametric path declared first eats subsequent fixed-suffix paths. The fix is path-converter type hints (`{person_id:int}`), restricting the parametric route to integer paths.
+
+This bug had been latent in production. No unit test exercised it. No previous Gauntlet caught it. Without the IDOR matrix discipline this pattern bakes in, it would still be unreachable. (Field report #320 §1.)
+
+## Anti-Patterns
+
+- **Single-commit refactor** for files >1,000 LOC. Review fatigue + impossible to revert surgically.
+- **No architecture-quick.** Without Picard's plan, the LOC trajectory drifts and entities get extracted in dependency-violating order.
+- **No IDOR matrix.** Refactoring multi-tenant code without cross-tenant denial tests is just rearranging the leak surface.
+- **Mixing entity extractions in one commit.** Each commit must remain shippable independently with green tests. One commit per entity, no exceptions.
+- **Skipping the final cleanup commit.** Duplicated helpers that emerged across entities don't lift themselves; pruning matters.
+- **Running full pytest as the agent's last step.** See SUB_AGENTS.md "Build-Agent Pytest Sequencing" — agent response window truncates mid-suite, orchestrator has to reconstruct.
+
+## When NOT to Use
+
+- File is under ~600 LOC. Just split it in one commit; the overhead isn't worth it.
+- The file is genuinely cohesive (state machine, single algorithm, generated code). Extraction would fragment what should stay together.
+- The exit gate isn't binding — if there's no LOC limit and no clear quality reason to split, the refactor is yak-shaving.

package/dist/wizard/lib/project-init.js

@@ -113,8 +113,65 @@ async function copyMethodology(methodologyRoot, projectDir, core) {
     if (existsSync(thumperSrc)) {
         count += await copyDir(thumperSrc, join(projectDir, 'scripts', 'thumper'));
     }
+    // Surfer-gate scripts (ADR-051 enforcement — closes #317).
+    // Ship the gate to every new project so the hook can mechanically enforce
+    // CLAUDE.md's Silver Surfer procedure. Without this the prose-backstop is
+    // the only thing holding the line in consumer installs.
+    const surferGateSrc = join(methodologyRoot, 'scripts', 'surfer-gate');
+    if (existsSync(surferGateSrc)) {
+        count += await copyDir(surferGateSrc, join(projectDir, 'scripts', 'surfer-gate'));
+        await chmodShellScripts(join(projectDir, 'scripts', 'surfer-gate'));
+        await mergeSettingsHook(projectDir);
+    }
     return count;
 }
+async function chmodShellScripts(dir) {
+    if (!existsSync(dir))
+        return;
+    const { chmod } = await import('node:fs/promises');
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith('.sh')) {
+            await chmod(join(dir, entry.name), 0o755);
+        }
+    }
+}
+async function mergeSettingsHook(projectDir) {
+    const snippetPath = join(projectDir, 'scripts', 'surfer-gate', 'settings-snippet.json');
+    const settingsPath = join(projectDir, '.claude', 'settings.json');
+    if (!existsSync(snippetPath))
+        return;
+    const snippet = JSON.parse(await readFile(snippetPath, 'utf-8'));
+    const productionHook = snippet?.production_hook;
+    if (!productionHook?.PreToolUse)
+        return;
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+        }
+        catch {
+            // Existing settings.json is unreadable — leave it alone.
+            return;
+        }
+    }
+    else {
+        await mkdir(join(projectDir, '.claude'), { recursive: true });
+    }
+    const existingHooks = (settings.hooks ?? {});
+    const existingPreTool = (existingHooks.PreToolUse ?? []);
+    const alreadyHasGate = existingPreTool.some((entry) => {
+        const hooks = (entry?.hooks ?? []);
+        return hooks.some((h) => typeof h?.command === 'string' && h.command.includes('surfer-gate/check.sh'));
+    });
+    if (alreadyHasGate)
+        return;
+    settings.hooks = {
+        ...existingHooks,
+        PreToolUse: [...existingPreTool, ...productionHook.PreToolUse],
+    };
+    await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
 // ── Identity Injection ───────────────────────────────────
 async function injectIdentity(projectDir, config) {
     const claudePath = join(projectDir, 'CLAUDE.md');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voidforge-build",
-  "version": "23.10.0",
+  "version": "23.11.1",
   "description": "From nothing, everything. A methodology framework for building with Claude Code.",
   "type": "module",
   "engines": {