thevoidforge 21.0.11 → 21.0.13

package/dist/docs/patterns/component.tsx

@@ -0,0 +1,262 @@
+/**
+ * Pattern: React Component with All States
+ *
+ * Key principles:
+ * - Every component handles: loading, empty, error, and success states
+ * - Keyboard accessible — interactive elements focusable, no mouse-only actions
+ * - Semantic HTML — use the right element, not div-with-onClick
+ * - Loading states prevent layout shift (skeleton matches content shape)
+ * - Error states are actionable — tell the user what to do
+ * - Empty states guide — never just show blank space
+ *
+ * Agents: Legolas (code), Samwise (a11y), Bilbo (copy), Gimli (performance)
+ *
+ * Framework adaptations:
+ *   Next.js/React: This file (JSX, hooks, 'use client')
+ *   Vue: Same 4-state pattern with v-if/v-else, <template> blocks
+ *   Svelte: Same pattern with {#if}/{:else} blocks
+ *   Django templates: Conditional blocks for each state, HTMX for loading
+ *   Rails: Turbo Frames for loading states, partials for each state
+ *
+ * === Django Templates + HTMX Deep Dive ===
+ *
+ *   {# templates/projects/list.html — same 4-state pattern, no JS framework #}
+ *   {% if loading %}
+ *     <div role="status" aria-label="Loading projects">
+ *       {% for _ in "123" %}<div class="skeleton h-16 rounded-lg bg-gray-100 animate-pulse"></div>{% endfor %}
+ *     </div>
+ *   {% elif error %}
+ *     <div role="alert" class="border border-red-200 bg-red-50 p-4">
+ *       <p>Couldn't load projects: {{ error }}</p>
+ *       <button hx-get="{% url 'project-list' %}" hx-target="#project-list">Try again</button>
+ *     </div>
+ *   {% elif not projects %}
+ *     <div class="border-dashed p-8 text-center">No projects yet.</div>
+ *   {% else %}
+ *     {% for project in projects %}{% include "projects/_card.html" %}{% endfor %}
+ *   {% endif %}
+ *
+ *   {# HTMX: loading states via hx-indicator, partial swaps via hx-target #}
+ *   {# Keyboard: ensure HTMX-swapped content gets focus management via hx-on::after-swap #}
+ *
+ * === FastAPI + Jinja2 + HTMX Deep Dive ===
+ *
+ *   Same template pattern as Django. FastAPI serves templates via:
+ *     from fastapi.templating import Jinja2Templates
+ *     templates = Jinja2Templates(directory="templates")
+ *
+ *   For SPA frontends: FastAPI serves JSON API, React/Vue/Svelte handles the 4 states.
+ *   For HTMX: same pattern as Django templates above, endpoint returns HTML fragments.
+ *
+ * The framework changes, the principle doesn't:
+ * EVERY data-driven component handles loading, empty, error, and success.
+ *
+ * === useEffect + Store Interaction Rules ===
+ *
+ * ANTI-PATTERN: useEffect that depends on a store value it indirectly modifies
+ *   useEffect(() => {
+ *     loadData(id); // calls store.set() which changes currentData
+ *   }, [currentData]); // currentData changes → effect fires → infinite loop
+ *
+ * CORRECT: depend on the primitive trigger, not the store result
+ *   useEffect(() => {
+ *     if (id) loadData(id);
+ *   }, [id]); // URL param triggers load, not the store value
+ *
+ * CORRECT: ref guard for load-once effects
+ *   const loaded = useRef(false);
+ *   useEffect(() => {
+ *     if (loaded.current) return;
+ *     loaded.current = true;
+ *     loadData(id);
+ *   }, []);
+ *
+ * RULE: For every useEffect with store values in its dependency array,
+ * verify the effect body does NOT trigger a store update that changes
+ * those same dependencies. If it does → infinite render loop.
+ *
+ * RULE: Never call panelRef.current?.focus() in a useEffect without a
+ * ref guard. Arrow function callbacks in parent components change identity
+ * on every render, causing the effect to re-run and steal focus.
+ *
+ * === Collapsible / Accordion Pattern ===
+ *
+ * When building any expand/collapse UI (accordions, dropdowns, FAQ sections,
+ * expandable cards), this ARIA checklist is required:
+ *
+ *   <button
+ *     type="button"                    // Not "submit" — prevents form submission
+ *     aria-expanded={isOpen}           // Announces open/closed state
+ *     aria-controls={contentId}        // Links trigger to content panel
+ *     className="focus-visible:ring-2" // Keyboard focus indicator
+ *     onClick={() => setIsOpen(!isOpen)}
+ *   >
+ *     Section Title
+ *   </button>
+ *   {isOpen && (
+ *     <div id={contentId}>            // Must match aria-controls value
+ *       Panel content
+ *     </div>
+ *   )}
+ *
+ * Use useId() (React 18+) or a stable ID generator for contentId.
+ * Keyboard: Enter/Space toggles. This is automatic with <button>.
+ *
+ * Common mistake: adding aria-expanded but forgetting aria-controls + id.
+ * The three are a unit — aria-expanded alone tells screen readers the
+ * state but not WHAT content it controls.
+ * (Field report #43: custom accordions had aria-expanded but no
+ * aria-controls or content id — a11y violation caught in review.)
+ */
+
+// ── Portal Pattern (iframe-safe overlays) ────────────
+// Any dropdown, popover, modal, or tooltip that must render ABOVE an iframe
+// MUST use createPortal to document.body.
+//
+// Why: Iframes with allow-same-origin create impenetrable stacking contexts.
+// z-index alone will NOT work — the iframe's stacking context always wins.
+//
+// import { createPortal } from 'react-dom';
+//
+// function Dropdown({ children, isOpen }: { children: React.ReactNode; isOpen: boolean }) {
+//   if (!isOpen) return null;
+//   return createPortal(
+//     <div style={{ position: 'fixed', zIndex: 9999 }}>{children}</div>,
+//     document.body
+//   );
+// }
+//
+// Django/HTMX equivalent: render the overlay in a top-level <div> outside the iframe container.
+// (Field report #79: iframe stacking context defeated z-index on map overlay)
+
+'use client'
+
+import { useState } from 'react'
+
+// --- Types co-located with component ---
+interface Project {
+  id: string
+  name: string
+  description: string | null
+  createdAt: string
+}
+
+interface ProjectListProps {
+  projects: Project[]
+  isLoading: boolean
+  error: string | null
+  onDelete: (id: string) => void
+  onRetry: () => void
+}
+
+// --- Main component ---
+export function ProjectList({
+  projects,
+  isLoading,
+  error,
+  onDelete,
+  onRetry,
+}: ProjectListProps) {
+  // Loading state — skeleton matches content shape (Gimli — no layout shift)
+  if (isLoading) {
+    return (
+      <div role="status" aria-label="Loading projects">
+        <ul className="space-y-3">
+          {Array.from({ length: 3 }).map((_, i) => (
+            <li key={i} className="h-16 rounded-lg bg-gray-100 animate-pulse" />
+          ))}
+        </ul>
+        <span className="sr-only">Loading projects...</span>
+      </div>
+    )
+  }
+
+  // Error state — actionable, not just "something went wrong" (Bilbo — clear copy)
+  if (error) {
+    return (
+      <div role="alert" className="rounded-lg border border-red-200 bg-red-50 p-4">
+        <p className="font-medium text-red-800">Couldn't load your projects</p>
+        <p className="mt-1 text-sm text-red-600">{error}</p>
+        <button
+          onClick={onRetry}
+          className="mt-3 text-sm font-medium text-red-700 underline hover:text-red-800"
+        >
+          Try again
+        </button>
+      </div>
+    )
+  }
+
+  // Empty state — guide the user, don't show blank (Bilbo — helpful copy)
+  if (projects.length === 0) {
+    return (
+      <div className="rounded-lg border border-dashed border-gray-300 p-8 text-center">
+        <p className="font-medium text-gray-900">No projects yet</p>
+        <p className="mt-1 text-sm text-gray-500">
+          Create your first project to get started.
+        </p>
+      </div>
+    )
+  }
+
+  // Success state
+  return (
+    <ul className="space-y-3" role="list">
+      {projects.map((project) => (
+        <ProjectCard key={project.id} project={project} onDelete={onDelete} />
+      ))}
+    </ul>
+  )
+}
+
+// --- Sub-component ---
+function ProjectCard({
+  project,
+  onDelete,
+}: {
+  project: Project
+  onDelete: (id: string) => void
+}) {
+  const [confirmDelete, setConfirmDelete] = useState(false)
+
+  return (
+    <li className="flex items-center justify-between rounded-lg border p-4">
+      <div>
+        <h3 className="font-medium text-gray-900">{project.name}</h3>
+        {project.description && (
+          <p className="mt-0.5 text-sm text-gray-500">{project.description}</p>
+        )}
+      </div>
+
+      {/* Dangerous action requires confirmation (Radagast — safety) */}
+      {confirmDelete ? (
+        <div className="flex gap-2" role="group" aria-label="Confirm deletion">
+          <button
+            onClick={() => {
+              onDelete(project.id)
+              setConfirmDelete(false)
+            }}
+            className="rounded bg-red-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-red-700"
+            aria-label={`Confirm delete ${project.name}`}
+          >
+            Delete
+          </button>
+          <button
+            onClick={() => setConfirmDelete(false)}
+            className="rounded border px-3 py-1.5 text-sm font-medium text-gray-700 hover:bg-gray-50"
+          >
+            Cancel
+          </button>
+        </div>
+      ) : (
+        <button
+          onClick={() => setConfirmDelete(true)}
+          className="rounded border px-3 py-1.5 text-sm font-medium text-gray-700 hover:bg-gray-50"
+          aria-label={`Delete ${project.name}`}
+        >
+          Delete
+        </button>
+      )}
+    </li>
+  )
+}

package/dist/docs/patterns/daemon-process.ts

@@ -0,0 +1,338 @@
+/**
+ * Pattern: Daemon Process (Heartbeat)
+ *
+ * Key principles:
+ * - PID file with flock to prevent concurrent instances
+ * - Unix domain socket for IPC (ADR-1: single writer)
+ * - Session token auth (rotated every 24 hours)
+ * - Graceful shutdown on SIGTERM (10s deadline)
+ * - Sleep/wake recovery with tiered catch-up
+ * - Core dumps disabled for processes holding vault keys
+ * - Log rotation: daily or at 10MB, retain 7 days
+ * - macOS: F_FULLFSYNC for financial files
+ *
+ * Agents: Dockson (treasury), Heartbeat daemon
+ *
+ * PRD Reference: §9.7, §9.18, §9.19.2, §9.20.11
+ */
+
+import { createServer } from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { writeFile, readFile, unlink, mkdir, open, rename } from 'node:fs/promises';
+import { existsSync, createWriteStream } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+
+const VOIDFORGE_DIR = join(homedir(), '.voidforge');
+const RUN_DIR = join(VOIDFORGE_DIR, 'run');
+const PID_FILE = join(RUN_DIR, 'heartbeat.pid');
+const SOCKET_PATH = join(RUN_DIR, 'heartbeat.sock');
+const TOKEN_FILE = join(VOIDFORGE_DIR, 'heartbeat.token');
+const STATE_FILE = join(VOIDFORGE_DIR, 'heartbeat.json');
+const LOG_FILE = join(VOIDFORGE_DIR, 'heartbeat.log');
+
+type DaemonState = 'starting' | 'healthy' | 'degraded' | 'recovering' | 'recovery_failed' | 'shutting_down' | 'stopped';
+
+interface HeartbeatState {
+  pid: number;
+  state: DaemonState;
+  startedAt: string;
+  lastHeartbeat: string;
+  lastEventId: number;
+  cultivationState: string;
+  activePlatforms: string[];
+  activeCampaigns: number;
+  todaySpend: number;      // Cents
+  dailyBudget: number;     // Cents
+  alerts: string[];
+  tokenHealth: Record<string, { status: string; expiresAt: string }>;
+  lastAgentMessage?: { agent: string; text: string; timestamp: string };
+  // Treasury state (v19.0 — present when stablecoin funding is configured)
+  stablecoinBalanceCents?: number;
+  bankBalanceCents?: number;
+  runwayDays?: number;
+  fundingFrozen?: boolean;
+  pendingTransferCount?: number;
+}
+
+// ── PID Management ────────────────────────────────────
+
+async function writePidFile(): Promise<void> {
+  await mkdir(RUN_DIR, { recursive: true, mode: 0o700 });
+  const fh = await open(PID_FILE, 'w', 0o600);
+  try {
+    await fh.writeFile(String(process.pid));
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+}
+
+async function checkStalePid(): Promise<boolean> {
+  if (!existsSync(PID_FILE)) return false;
+  try {
+    const pid = parseInt(await readFile(PID_FILE, 'utf-8'));
+    process.kill(pid, 0); // Check if process exists (throws if not)
+    return true; // Another daemon is alive
+  } catch {
+    await unlink(PID_FILE).catch(() => {});
+    return false; // Stale PID — cleaned up
+  }
+}
+
+async function removePidFile(): Promise<void> {
+  await unlink(PID_FILE).catch(() => {});
+}
+
+// ── Session Token ─────────────────────────────────────
+// Rotated every 24 hours (§9.19.15)
+
+async function generateSessionToken(): Promise<string> {
+  const token = randomBytes(32).toString('hex');
+  await mkdir(RUN_DIR, { recursive: true, mode: 0o700 });
+  const tmpPath = TOKEN_FILE + '.tmp.' + process.pid;
+  const fh = await open(tmpPath, 'w', 0o600);
+  try {
+    await fh.writeFile(token);
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await rename(tmpPath, TOKEN_FILE);
+  return token;
+}
+
+function validateToken(provided: string, expected: string): boolean {
+  if (provided.length !== expected.length) return false;
+  const a = Buffer.from(provided);
+  const b = Buffer.from(expected);
+  const { timingSafeEqual } = require('node:crypto');
+  return timingSafeEqual(a, b);
+}
+
+// ── Socket Server ─────────────────────────────────────
+// JSON-over-HTTP on Unix domain socket (§9.20.11)
+
+function createSocketServer(
+  sessionToken: string,
+  handleRequest: (method: string, path: string, body: unknown, auth: { hasToken: boolean; vaultPassword: string; totpCode: string }) => Promise<{ status: number; body: unknown }>
+): ReturnType<typeof createServer> {
+  const MAX_REQUEST_SIZE = 1024 * 1024; // 1MB — R2-NIGHTWING-003: enforce during streaming
+
+  const server = createServer(async (conn) => {
+    let data = '';
+    let rejected = false;
+    conn.on('data', (chunk) => {
+      data += chunk.toString();
+      if (data.length > MAX_REQUEST_SIZE && !rejected) {
+        rejected = true;
+        conn.write('HTTP/1.1 413 Payload Too Large\r\nContent-Type: application/json\r\n\r\n{"ok":false,"error":"Request too large"}');
+        conn.end();
+      }
+    });
+    conn.on('end', async () => {
+      try {
+        // Parse HTTP-like request from the socket
+        const lines = data.split('\r\n');
+        const [method, path] = (lines[0] || 'GET /').split(' ');
+
+        // Extract auth headers — pass VALUES, not just presence (SEC-001 fix)
+        const authHeader = lines.find(l => l.toLowerCase().startsWith('authorization:'));
+        const token = authHeader ? authHeader.split(' ').pop() || '' : '';
+        const hasToken = validateToken(token, sessionToken);
+
+        const vaultHeader = lines.find(l => l.toLowerCase().startsWith('x-vault-password:'));
+        const vaultPassword = vaultHeader ? vaultHeader.substring(vaultHeader.indexOf(':') + 1).trim() : '';
+
+        const totpHeader = lines.find(l => l.toLowerCase().startsWith('x-totp-code:'));
+        const totpCode = totpHeader ? totpHeader.substring(totpHeader.indexOf(':') + 1).trim() : '';
+
+        // Parse body (after blank line)
+        const bodyStart = data.indexOf('\r\n\r\n');
+
+        if (rejected) return; // Already rejected during streaming
+
+        const body = bodyStart >= 0 ? JSON.parse(data.substring(bodyStart + 4) || '{}') : {};
+
+        const result = await handleRequest(method, path, body, {
+          hasToken,
+          vaultPassword,  // Actual value for verification by handler
+          totpCode,       // Actual value for verification by handler
+        });
+
+        conn.write(`HTTP/1.1 ${result.status} OK\r\nContent-Type: application/json\r\n\r\n${JSON.stringify(result.body)}`);
+      } catch (err) {
+        conn.write(`HTTP/1.1 500 Error\r\nContent-Type: application/json\r\n\r\n${JSON.stringify({ ok: false, error: 'Internal error' })}`);
+      }
+      conn.end();
+    });
+  });
+
+  return server;
+}
+
+async function startSocketServer(server: ReturnType<typeof createServer>): Promise<void> {
+  // Clean up stale socket
+  if (existsSync(SOCKET_PATH)) {
+    try {
+      const { connect } = require('node:net');
+      const testConn = connect(SOCKET_PATH);
+      await new Promise<void>((resolve, reject) => {
+        testConn.on('connect', () => { testConn.destroy(); reject(new Error('Another daemon is running')); });
+        testConn.on('error', () => { resolve(); }); // ECONNREFUSED = stale socket
+      });
+      await unlink(SOCKET_PATH);
+    } catch (err) {
+      if ((err as Error).message === 'Another daemon is running') throw err;
+    }
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    server.listen(SOCKET_PATH, () => {
+      // Set socket permissions (§9.18)
+      require('node:fs').chmodSync(SOCKET_PATH, 0o600);
+      resolve();
+    });
+    server.on('error', reject);
+  });
+}
+
+// ── State File ────────────────────────────────────────
+
+async function writeState(state: HeartbeatState): Promise<void> {
+  const tmpPath = STATE_FILE + '.tmp.' + process.pid;
+  const fh = await open(tmpPath, 'w');
+  try {
+    await fh.writeFile(JSON.stringify(state, null, 2));
+    if (platform() === 'darwin') {
+      await fh.datasync(); // Best-effort on macOS; see §9.18 F_FULLFSYNC caveat
+    } else {
+      await fh.sync();
+    }
+  } finally {
+    await fh.close();
+  }
+  await rename(tmpPath, STATE_FILE);
+}
+
+// ── Signal Handling ───────────────────────────────────
+
+function setupSignalHandlers(
+  cleanup: () => Promise<void>,
+  server: ReturnType<typeof createServer>
+): void {
+  let shuttingDown = false;
+
+  async function shutdown(signal: string): Promise<void> {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    // 10-second deadline for in-flight requests
+    const deadline = setTimeout(() => {
+      process.exit(1);
+    }, 10000);
+
+    try {
+      server.close();
+      await cleanup();
+      await removePidFile();
+      await unlink(SOCKET_PATH).catch(() => {});
+      clearTimeout(deadline);
+      process.exit(0);
+    } catch {
+      clearTimeout(deadline);
+      process.exit(1);
+    }
+  }
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+
+  // Disable core dumps — vault key in memory (§9.18)
+  try {
+    // @ts-expect-error — setrlimit not in Node.js types
+    if (process.setrlimit) process.setrlimit('core', { soft: 0, hard: 0 });
+  } catch { /* not available on all platforms */ }
+}
+
+// ── Job Scheduler ─────────────────────────────────────
+
+interface ScheduledJob {
+  name: string;
+  intervalMs: number;
+  handler: () => Promise<void>;
+  lastRun: number;
+}
+
+class JobScheduler {
+  private jobs: ScheduledJob[] = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private lastTick: number = Date.now();
+
+  add(name: string, intervalMs: number, handler: () => Promise<void>): void {
+    this.jobs.push({ name, intervalMs, handler, lastRun: 0 });
+  }
+
+  start(): void {
+    this.lastTick = Date.now();
+    this.timer = setInterval(() => this.tick(), 1000);
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+  }
+
+  private async tick(): Promise<void> {
+    const now = Date.now();
+    const delta = now - this.lastTick;
+    this.lastTick = now;
+
+    // Sleep/wake detection (§9.18): if delta > 2x expected (2s), catch-up mode
+    if (delta > 2000) {
+      // Stagger overdue jobs over 5 minutes, prioritize token refresh
+      const overdue = this.jobs.filter(j => now - j.lastRun > j.intervalMs);
+      const sorted = overdue.sort((a, b) => {
+        if (a.name.includes('token')) return -1;
+        if (b.name.includes('token')) return 1;
+        return 0;
+      });
+      for (const job of sorted) {
+        try { await job.handler(); } catch { /* logged by handler */ }
+        job.lastRun = now;
+      }
+      return;
+    }
+
+    // Normal tick: run due jobs
+    for (const job of this.jobs) {
+      if (now - job.lastRun >= job.intervalMs) {
+        try { await job.handler(); } catch { /* logged by handler */ }
+        job.lastRun = now;
+      }
+    }
+  }
+}
+
+// ── Log Rotation ──────────────────────────────────────
+
+function createLogger(logPath: string): { log: (msg: string) => void; close: () => void } {
+  let stream = createWriteStream(logPath, { flags: 'a' });
+  return {
+    log(msg: string) {
+      stream.write(JSON.stringify({ ts: new Date().toISOString(), msg }) + '\n');
+    },
+    close() { stream.end(); }
+  };
+}
+
+export {
+  writePidFile, checkStalePid, removePidFile,
+  generateSessionToken, validateToken,
+  createSocketServer, startSocketServer,
+  writeState,
+  setupSignalHandlers,
+  JobScheduler,
+  createLogger,
+  PID_FILE, SOCKET_PATH, TOKEN_FILE, STATE_FILE, LOG_FILE,
+};
+export type { DaemonState, HeartbeatState, ScheduledJob };