@donotdev/cli 0.0.19 → 0.0.21

package/templates/app-dndev/terminal-sidecar.cjs.example

@@ -0,0 +1,341 @@
+/**
+ * @fileoverview Terminal sidecar — real PTY via node-pty + WebSocket.
+ * Runs under Node (not Bun) to guarantee node-pty native addon works.
+ *
+ * @description Self-contained process: owns a WebSocket server + PTY lifecycle.
+ * Spawned by DndevPlugin.js with: spawn('node', [thisFile], { cwd: appRoot })
+ *
+ * Protocol (JSON over WebSocket):
+ *   Client → Server: start, input, resize, kill
+ *   Server → Client: started, output, exit, error
+ *
+ * @env {string} TERMINAL_PORT - WebSocket port (default: 24681)
+ * @env {string} TERMINAL_CWD  - Working directory for shells (default: process.cwd())
+ * @env {string} TERMINAL_SHELL - Override shell binary (e.g. 'pwsh.exe', 'zsh')
+ */
+
+'use strict';
+
+const path = require('path');
+const { createRequire } = require('module');
+
+const appRequire = createRequire(path.join(__dirname, 'package.json'));
+const pty = appRequire('node-pty');
+const { WebSocketServer } = appRequire('ws');
+
+// ============================================================================
+// SHELL CONFIG — override via env TERMINAL_SHELL or edit defaults below
+// ============================================================================
+
+/**
+ * Resolve the shell binary to spawn.
+ * Priority: TERMINAL_SHELL env > platform default
+ *
+ * Platform defaults:
+ *   Windows → wsl.exe (Linux shell inside Windows via WSL)
+ *   macOS   → zsh
+ *   Linux   → $SHELL or bash
+ * @returns {string} Shell binary path or name
+ */
+function resolveShell() {
+  if (process.env.TERMINAL_SHELL) return process.env.TERMINAL_SHELL;
+
+  if (process.platform === 'win32') {
+    // Default: WSL (Linux shell inside Windows)
+    // To use PowerShell instead, uncomment ONE of:
+    //   return 'pwsh.exe';           // PowerShell 7+ (recommended)
+    //   return 'powershell.exe';     // Windows PowerShell 5.1 (legacy)
+    return 'wsl.exe';
+  }
+
+  return process.env.SHELL || '/bin/bash';
+}
+
+/**
+ * Build a clean env for the child shell.
+ * Strips node/bun/turbo internals. On Windows, ensures HOME/SHELL aren't 'undefined'.
+ * @returns {Record<string, string>}
+ */
+function buildCleanEnv() {
+  const cleanEnv = Object.fromEntries(
+    Object.entries(process.env).filter(([k, v]) =>
+      v !== undefined &&
+      !k.startsWith('NODE_CHANNEL') &&
+      !k.startsWith('TURBO_') &&
+      !k.startsWith('BUN_') &&
+      k !== 'NODE_OPTIONS' &&
+      k !== 'FORCE_COLOR'
+    )
+  );
+  cleanEnv.FORCE_COLOR = '1';
+  cleanEnv.TERM = 'xterm-256color';
+
+  // Windows: HOME and SHELL don't exist natively — set sane defaults
+  if (process.platform === 'win32') {
+    if (!cleanEnv.HOME) cleanEnv.HOME = cleanEnv.USERPROFILE || '';
+    if (!cleanEnv.SHELL) delete cleanEnv.SHELL;
+  }
+
+  return cleanEnv;
+}
+
+/**
+ * Resolve cwd for the shell.
+ * IMPORTANT: cwd is passed to node-pty's spawn(), which runs on the host OS.
+ * On Windows, this MUST be a native Windows path (e.g. C:\ws\dndev).
+ * WSL automatically maps the Windows cwd to /mnt/c/... inside the Linux shell.
+ * @returns {string} Working directory path (native OS path)
+ */
+function resolveCwd() {
+  const cwd = process.env.TERMINAL_CWD;
+  if (!cwd) {
+    throw new Error('TERMINAL_CWD env is required — set it in DndevPlugin.js');
+  }
+  return cwd;
+}
+
+/**
+ * Validate a tab name — prevents log injection and memory abuse.
+ * @param {unknown} tab
+ * @returns {boolean}
+ */
+function isValidTab(tab) {
+  return typeof tab === 'string' && tab.length > 0 && tab.length <= 64 && /^[\w-]+$/.test(tab);
+}
+
+/**
+ * Clamp cols/rows to safe integer ranges for node-pty.
+ * @param {unknown} value
+ * @param {number} fallback
+ * @param {number} [min=1]
+ * @param {number} [max=500]
+ * @returns {number}
+ */
+function clampDimension(value, fallback, min = 1, max = 500) {
+  const n = typeof value === 'number' ? Math.floor(value) : fallback;
+  return Math.max(min, Math.min(max, n));
+}
+
+// ============================================================================
+// CRASH GUARD — auto-respawn on immediate PTY death (ConPTY race condition)
+// ============================================================================
+
+/** @type {number} If PTY dies within this window, treat as crash */
+const CRASH_THRESHOLD_MS = 3000;
+/** @type {number} Max auto-respawn retries per tab */
+const MAX_RETRIES = 2;
+/** @type {Map<string, { count: number }>} Track crash retries per tab */
+const spawnAttempts = new Map();
+/** @type {Set<string>} Tabs killed intentionally — suppress duplicate onExit broadcast */
+const killedTabs = new Set();
+/** @type {Set<string>} Tabs with a pending crash-guard respawn timer */
+const pendingRespawns = new Set();
+
+// ============================================================================
+// INIT
+// ============================================================================
+
+// Guard: node-pty requires real Node, not Bun
+if (typeof globalThis.Bun !== 'undefined') {
+  console.error('[sidecar] FATAL: running under Bun — node-pty requires real Node. execPath=' + process.execPath);
+  process.exit(1);
+}
+
+const PORT = parseInt(process.env.TERMINAL_PORT || '24681', 10);
+if (!Number.isFinite(PORT) || PORT < 1 || PORT > 65535) {
+  console.error(`[sidecar] FATAL: invalid TERMINAL_PORT: ${process.env.TERMINAL_PORT}`);
+  process.exit(1);
+}
+
+console.error('[sidecar] Node ' + process.version + ' pid=' + process.pid);
+
+/** @type {Map<string, import('node-pty').IPty>} Active PTY processes by tab id */
+const ptys = new Map();
+const wss = new WebSocketServer({ port: PORT });
+
+/**
+ * Broadcast a JSON message to all connected WebSocket clients.
+ * @param {Record<string, unknown>} msg
+ */
+function broadcast(msg) {
+  const data = JSON.stringify(msg);
+  for (const client of wss.clients) {
+    if (client.readyState === 1) client.send(data);
+  }
+}
+
+/**
+ * Spawn a PTY for the given tab. Handles crash-respawn internally.
+ * Wrapped in try/catch so failures in the setTimeout retry path don't crash the sidecar.
+ * @param {string} tab - Tab identifier
+ * @param {number} cols - Terminal columns
+ * @param {number} rows - Terminal rows
+ */
+function spawnPty(tab, cols, rows) {
+  try {
+    const shell = resolveShell();
+    const cleanEnv = buildCleanEnv();
+    const cwd = resolveCwd();
+    const safeCols = clampDimension(cols, 120);
+    const safeRows = clampDimension(rows, 30);
+
+    console.error(`[sidecar] spawning: ${shell} cwd=${cwd} cols=${safeCols} rows=${safeRows}`);
+
+    const p = pty.spawn(shell, [], {
+      name: 'xterm-256color',
+      cols: safeCols,
+      rows: safeRows,
+      cwd,
+      env: cleanEnv,
+    });
+
+    const spawnedAt = Date.now();
+    console.error(`[sidecar] PTY "${tab}" spawned: pid=${p.pid}`);
+    ptys.set(tab, p);
+    broadcast({ type: 'started', tab });
+
+    p.onData((data) => {
+      broadcast({ type: 'output', tab, data });
+    });
+
+    p.onExit(({ exitCode, signal }) => {
+      console.error(`[sidecar] PTY "${tab}" exited: code=${exitCode} signal=${signal} pid=${p.pid}`);
+      ptys.delete(tab);
+
+      // If killed intentionally via 'kill' command, the handler already broadcast 'exit'
+      if (killedTabs.has(tab)) {
+        killedTabs.delete(tab);
+        return;
+      }
+
+      const livedMs = Date.now() - spawnedAt;
+
+      // Crash guard: if the PTY died almost instantly, auto-respawn
+      if (livedMs < CRASH_THRESHOLD_MS && exitCode !== 0) {
+        const attempts = spawnAttempts.get(tab) || { count: 0 };
+        attempts.count++;
+        spawnAttempts.set(tab, attempts);
+
+        if (attempts.count <= MAX_RETRIES) {
+          console.error(`[sidecar] PTY "${tab}" crashed after ${livedMs}ms — auto-respawn ${attempts.count}/${MAX_RETRIES}`);
+          pendingRespawns.add(tab);
+          setTimeout(() => {
+            pendingRespawns.delete(tab);
+            // If client already reconnected during the delay, skip
+            if (ptys.has(tab)) return;
+            spawnPty(tab, safeCols, safeRows);
+          }, 300);
+          return;
+        }
+        console.error(`[sidecar] PTY "${tab}" exhausted ${MAX_RETRIES} retries — giving up`);
+      }
+
+      // Normal exit or retries exhausted — notify client
+      spawnAttempts.delete(tab);
+      broadcast({ type: 'exit', tab, code: exitCode });
+    });
+  } catch (err) {
+    console.error(`[sidecar] PTY "${tab}" spawn failed:`, err.message);
+    ptys.delete(tab);
+    spawnAttempts.delete(tab);
+    broadcast({ type: 'error', tab, message: `Spawn failed: ${err.message}` });
+  }
+}
+
+// ============================================================================
+// WEBSOCKET SERVER
+// ============================================================================
+
+wss.on('connection', (ws) => {
+  // Tell new client about already-running tabs
+  for (const tab of ptys.keys()) {
+    ws.send(JSON.stringify({ type: 'started', tab }));
+  }
+
+  ws.on('message', (raw) => {
+    try {
+      const msg = JSON.parse(raw.toString());
+
+      // Validate tab name on all messages that carry one
+      if (msg.tab !== undefined && !isValidTab(msg.tab)) return;
+
+      switch (msg.type) {
+        case 'start': {
+          if (ptys.has(msg.tab)) {
+            ws.send(JSON.stringify({ type: 'started', tab: msg.tab }));
+            return;
+          }
+          // If crash guard is about to respawn, let client take over instead
+          if (pendingRespawns.has(msg.tab)) {
+            pendingRespawns.delete(msg.tab);
+          }
+          spawnAttempts.delete(msg.tab);
+          spawnPty(
+            msg.tab,
+            clampDimension(msg.cols, 120),
+            clampDimension(msg.rows, 30),
+          );
+          break;
+        }
+        case 'input':
+          ptys.get(msg.tab)?.write(msg.data);
+          break;
+        case 'resize': {
+          const p = ptys.get(msg.tab);
+          if (p) {
+            p.resize(
+              clampDimension(msg.cols, 80),
+              clampDimension(msg.rows, 24),
+            );
+          }
+          break;
+        }
+        case 'kill': {
+          const p = ptys.get(msg.tab);
+          if (p) {
+            killedTabs.add(msg.tab);
+            p.kill();
+            ptys.delete(msg.tab);
+          }
+          spawnAttempts.delete(msg.tab);
+          broadcast({ type: 'exit', tab: msg.tab, code: -1 });
+          break;
+        }
+      }
+    } catch (err) {
+      console.error('[sidecar] message error:', err.message);
+    }
+  });
+});
+
+wss.on('listening', () => {
+  const msg = `[dndev] terminal ready on ws://localhost:${PORT}`;
+  console.log(msg);
+  if (process.send) process.send({ type: 'ready', port: PORT });
+});
+
+wss.on('error', (err) => {
+  console.error('[sidecar] ws server error:', err.message);
+  if (err.code === 'EADDRINUSE') {
+    console.error(`[sidecar] port ${PORT} in use — exiting (DndevPlugin will retry)`);
+    process.exit(1);
+  }
+});
+
+// ============================================================================
+// CLEANUP
+// ============================================================================
+
+function cleanup() {
+  for (const [, p] of ptys) {
+    try { p.kill(); } catch { /* already dead */ }
+  }
+  ptys.clear();
+  wss.close(() => process.exit(0));
+  // Fallback if wss.close hangs
+  setTimeout(() => process.exit(0), 1000);
+}
+
+process.on('SIGTERM', cleanup);
+process.on('SIGINT', cleanup);
+process.on('disconnect', cleanup);

package/templates/app-dndev/tsconfig.json.example

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src/**/*", "vite.config.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/app-dndev/vite.config.ts.example

@@ -0,0 +1,24 @@
+import { defineViteConfig } from '@donotdev/core/vite';
+import { appConfig } from './src/config/app';
+
+export default defineViteConfig({
+  appConfig,
+  dndev: true,
+  debug: false,
+  optimizeDeps: {
+    include: [
+      '@dnd-kit/core',
+      '@dnd-kit/sortable',
+      '@dnd-kit/utilities',
+      'react-markdown',
+      'remark-gfm'
+    ],
+  },
+  server: {
+    port: 3174,
+    https: false,
+    watch: {
+      ignored: ['**/.dndev/**'],
+    },
+  },
+});

package/templates/app-vite/index.html.example

@@ -43,7 +43,7 @@
       box-sizing: border-box;
     }
     body { 
-      font-family: 'Inter', var(--font-family, ui-sans-serif, system-ui, -apple-system, sans-serif);
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Helvetica Neue', Arial, sans-serif;
       line-height: 1.5;
       -webkit-font-smoothing: antialiased;
       -moz-osx-font-smoothing: grayscale;

package/templates/functions-supabase/supabase/functions/.env.example

@@ -4,10 +4,8 @@
 # Get these from: https://supabase.com/dashboard > your project > Settings
 #
 # Secret key: Settings > API > service_role key (or "Secret key" on new projects)
-# DB URL:     Settings > Database > Connection string > URI
 #
 # These are SERVER-SIDE ONLY. Never expose in client code.
 # =============================================================================
 
 SUPABASE_SECRET_KEY=
-SUPABASE_DB_URL=

package/templates/root-consumer/.claude/commands/grill.md.example

@@ -16,15 +16,93 @@ Evaluate for:
 - Missing or incorrect TypeScript types
 - @donotdev component usage without `lookup_symbol` verification
 
-Output format — structured critique, one item per line:
-```
-[BLOCKER] <file>:<line> — <problem>
-[WARN]    <file>:<line> — <problem>
-[NOTE]    <file>:<line> — <problem>
-```
-
 Rules:
 - NEVER suggest fixes. Report problems only.
 - NEVER skip BLOCKER items to be polite.
 - If there are no issues at a severity level, omit that level entirely.
-- End with a one-line verdict: SHIP / DO NOT SHIP.
+- **Quality > quantity. 15 real issues >>> 60 padded items.**
+
+## Output — 3-step lifecycle
+
+The grill report is a **living queue**. Each run cleans up resolved items, archives them, then appends new findings.
+
+### Step 1 — Clean up + archive
+
+Read existing `.dndev/grill-report.json`. If it exists and has items:
+
+1. Separate items into **resolved** (`status` = `fixed`, `resolved`, or `rejected`) and **surviving** (`pending`, `fixing`, or any other status).
+2. Append a history entry to `.dndev/grill-history.json` (read existing array or start with `[]`):
+```json
+{
+  "date": "<now ISO>",
+  "gitSha": "<short git HEAD>",
+  "target": "<previous report target>",
+  "verdict": "<previous report verdict>",
+  "blockers": <previous blocker count>,
+  "warnings": <previous warning count>,
+  "notes": <previous note count>,
+  "total": <previous items.length>,
+  "resolved": <resolved count>,
+  "carried": <surviving count>
+}
+```
+3. Keep the surviving items — they carry over into the updated report.
+
+If no existing report or no items, skip this step.
+
+### Step 2 — Scan
+
+Produce new findings from the target files. **Deduplicate** against surviving items from Step 1: if a new finding matches an existing item on `file` + `line` + `issue` (fuzzy match on issue text), skip it.
+
+### Step 3 — Write report
+
+Merge surviving items from Step 1 + new findings from Step 2. Re-number `id` fields sequentially starting at 1. Write to `.dndev/grill-report.json`:
+
+```json
+{
+  "generated": "<now ISO>",
+  "gitSha": "<short git HEAD>",
+  "target": "<description of what was reviewed>",
+  "verdict": "SHIP" | "DO NOT SHIP",
+  "items": [
+    {
+      "id": 1,
+      "severity": "blocker" | "warn" | "note",
+      "file": "src/pages/Foo.tsx",
+      "line": 42,
+      "issue": "Short description of the problem",
+      "context": "Optional: why this matters, what could go wrong",
+      "category": "security" | "architecture" | "edge-case" | "types" | "dead-code" | "consistency" | "dx" | "docs" | "performance",
+      "status": "pending",
+      "verified": true
+    }
+  ]
+}
+```
+
+Verdict is based on the **merged** items (carried + new). If any blocker exists → DO NOT SHIP.
+
+### Field rules
+
+- `gitSha` — Run `git rev-parse --short HEAD`. Required.
+- `verified` — Always `true` in final output.
+- New items always get `status: "pending"`. Carried items keep their existing status.
+
+### Fixing findings
+
+When asked to fix grill findings (not during a scan — during a separate fix request):
+
+1. Apply the code fix.
+2. Update `.dndev/grill-report.json`: set `status: "fixed"` on each resolved item.
+3. Set `lastReviewed` to current ISO timestamp.
+
+This ensures the report reflects reality. Next grill run archives fixed items to history.
+
+### General rules
+
+- NEVER suggest fixes. Report problems only — during a scan.
+- NEVER skip BLOCKER items.
+- **Quality > quantity. 15 real issues >>> 60 padded items** (for new findings — carried items don't count toward this cap).
+- Group by file, sort by line number.
+- After writing, print: `Cleaned N resolved items → history. Carried M items. Added K new findings. Total: T items.`
+- Print verdict: SHIP / DO NOT SHIP.

package/templates/root-consumer/.dndev.secrets.example

@@ -0,0 +1,32 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# .dndev.secrets — All secret keys in one place
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# This file is gitignored. Copy from .dndev.secrets.example and fill in values.
+# Resolution order: process.env (CI) → .dndev.secrets (local) → legacy paths
+#
+# For public config (VITE_*, NEXT_PUBLIC_*), use apps/<app>/.env instead.
+# For Firebase service account, keep service-account-key.json as-is.
+#
+
+{{#vercel}}
+# ── Vercel ──────────────────────────────────────────────────────────────────
+# Get from: https://vercel.com/account/tokens
+VERCEL_TOKEN=
+
+{{/vercel}}
+{{#supabase}}
+# ── Supabase ────────────────────────────────────────────────────────────────
+# Secret key: https://supabase.com/dashboard → Settings → API → service_role key
+# Access token: https://supabase.com/dashboard/account/tokens (needed for DB migrations)
+SUPABASE_SECRET_KEY=
+SUPABASE_ACCESS_TOKEN=
+
+{{/supabase}}
+{{#stripe}}
+# ── Stripe ──────────────────────────────────────────────────────────────────
+# Get from: https://dashboard.stripe.com/apikeys (secret key)
+#           https://dashboard.stripe.com/webhooks (webhook secret)
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+{{/stripe}}

package/templates/root-consumer/.gitignore.example

@@ -20,6 +20,9 @@ stats.html
 # Note: .env.local and .env.*.local are gitignored (local overrides)
 # .env.production.local is gitignored (production secrets)
 
+# Centralized secrets file (all secret keys in one place)
+.dndev.secrets
+
 # IDE files
 .vscode/*
 !.vscode/extensions.json

package/templates/root-consumer/AI.md.example

@@ -88,6 +88,10 @@ Run `dndev --help` for the full command list.
 - **RTL safe** — use `start`/`end`, never `left`/`right`
 - **Import order** — React → vendors → @donotdev → relative
 - **Import convention** — always `@donotdev/<pkg>` top-level, never sub-paths
+- **NO native HTML elements** — never use `<div>`, `<span>`, `<p>`, `<h1-6>`, `<button>`, `<a>`, `<input>`, `<textarea>`, `<select>`, `<form>`, `<table>`, `<ul>`, `<ol>`, `<li>`, `<img>`, `<section>`, `<nav>`, `<header>`, `<footer>` in @donotdev files. Use framework components: Stack, Card, Text, Button, Link, TextInput, Select, Form, DataTable, List, Image, Section, Navigation, Header, Footer. See `get_guide("COMPONENTS_ATOMIC")`
+- **NO custom CSS** — never create `.css`, `.module.css`, `.scss`, `.sass`, or `.less` files. All styling is done through framework component props, variant tokens, and theme configuration
+- **NO custom components** — never create files in `components/`. Compose pages using framework components only. If a component is missing, say what you need and STOP
+- **NO inventing props** — only use props returned by `lookup_symbol()`. Common hallucination traps that DO NOT exist: `size`, `tone`, `color`, `padding`, `margin`, `spacing`, `columns`, `background`, `fields`
 - **Framework-first** — if something's missing, say what and stop
 - **No .md file creation** — never create documentation/analysis/summary .md files unless explicitly asked. Session notes go in `.dndev/`
 - **Follow existing patterns** — the scaffolded files ARE your documentation

package/templates/root-consumer/entities/index.ts.example

@@ -2,17 +2,14 @@
  * @fileoverview Entity Exports
  *
  * Export all your entities from here for easy importing.
+ * See entities/examples/ for reference entity definitions.
  *
  * USAGE:
  * ```tsx
- * import { contactEntity, productEntity } from '../entities';
+ * import { customerEntity } from '../entities';
  * ```
  */
 
-// Scaffolded examples — rename or replace with your own entities:
-export { contactEntity } from './Contact';
-export { productEntity } from './ExampleEntity';
-
 // Add your entities:
 // export { customerEntity } from './Customer';
 // export { orderEntity } from './Order';

package/templates/root-consumer/guides/dndev/COMPONENTS_ATOMIC.md.example

@@ -38,6 +38,7 @@ These are the only ways one should handle layout to get to quick results functio
 - **ActionButton** - Button with async action handling and loading states.
 - **FileButton** - Button that triggers file input selection.
 - **PortalButton** - Button that opens content in a portal overlay.
+- **ButtonGroup** - Visual grouping of buttons with joined borders. Supports horizontal/vertical orientation, variant propagation, and items-based API.
 
 ---
 
@@ -53,6 +54,7 @@ These are the only ways one should handle layout to get to quick results functio
 - **Combobox** - Searchable combobox with autocomplete functionality.
 - **Switch** - Toggle switch component.
 - **Slider** - Range slider for numeric input.
+- **ColorPicker** - Color selection with preset swatch grid, native color input, and ARIA radiogroup pattern. Built-in palettes: basic, material, pastel.
 
 ---
 
@@ -76,6 +78,7 @@ These are the only ways one should handle layout to get to quick results functio
 - **Pagination** - Accessible pagination with page number generation and ellipsis.
 - **Command** - Command palette component for keyboard navigation and search.
 - **CommandDialog** - Command palette dialog optimized for Cmd+K navigation.
+- **TreeView** - Hierarchical tree component with WAI-ARIA TreeView pattern. Supports expand/collapse, single/multi selection, keyboard navigation, type-ahead search, and connector lines.
 
 ---
 
@@ -110,6 +113,7 @@ These are the only ways one should handle layout to get to quick results functio
 - **Portal** - Portal component for rendering outside DOM hierarchy.
 - **VisuallyHidden** - Screen reader-only content component.
 - **Slot** - Slot component for composition patterns.
+- **SkipLink** - Accessibility skip-to-content links, visible only on keyboard focus. Supports multiple targets with smooth scroll and focus management.
 
 ---