@grainulation/wheat 1.0.0

package/lib/install-prompt.js

@@ -0,0 +1,186 @@
+/**
+ * install-prompt.js — Track npx usage and suggest global/local install
+ *
+ * Two exports:
+ *   track(command)       — Increment invocation count (sync, <5ms)
+ *   maybePrompt(command) — Print install suggestion if thresholds met
+ *
+ * Usage data stored in ~/.grainulation/usage.json
+ * Respects --quiet flag, WHEAT_NO_INSTALL_PROMPT=1 env var.
+ * Fails silently on any I/O error — never blocks the CLI.
+ *
+ * Based on research claim r129: no existing CLI tool does npx-to-install
+ * nudging. This is an unclaimed UX innovation.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import path from 'path';
+import { homedir } from 'os';
+
+const USAGE_DIR = path.join(homedir(), '.grainulation');
+const USAGE_FILE = path.join(USAGE_DIR, 'usage.json');
+
+const THRESHOLDS = {
+  suggest_global: 3,
+  suggest_local: 5,
+  prominent: 10,
+};
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+function readUsage() {
+  try {
+    return JSON.parse(readFileSync(USAGE_FILE, 'utf8'));
+  } catch {
+    return { commands: {}, prompted: false, installed: false };
+  }
+}
+
+function writeUsage(data) {
+  try {
+    mkdirSync(USAGE_DIR, { recursive: true });
+    writeFileSync(USAGE_FILE, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  } catch {
+    // fail silently
+  }
+}
+
+/**
+ * Detect whether wheat was invoked via npx.
+ * npx stores executables in a temporary _npx cache directory.
+ */
+function isNpxInvocation() {
+  const execPath = process.argv[1] || '';
+  return execPath.includes('_npx');
+}
+
+/**
+ * Detect if wheat is installed globally or locally (not via npx).
+ *
+ * Local install: process.argv[1] contains node_modules
+ * Global install: process.argv[1] is in a known global bin path
+ *   (no _npx, no node_modules — resolves to /usr/local/bin, nvm, volta, etc.)
+ *
+ * We intentionally do NOT detect "running from source" (node bin/wheat.js)
+ * as installed, since that's a dev workflow where the prompt is also irrelevant
+ * (isNpxInvocation returns false, so prompts are already suppressed).
+ */
+function isInstalled() {
+  const execPath = process.argv[1] || '';
+
+  // Local install: running from node_modules
+  if (execPath.includes('node_modules') && !execPath.includes('_npx')) {
+    return true;
+  }
+
+  // Global install: binary is in a well-known global prefix
+  // (not npx, not node_modules — must be a permanent install)
+  if (!execPath.includes('_npx') && !execPath.includes('node_modules')) {
+    const knownGlobalDirs = [
+      '/usr/local/bin',
+      '/usr/bin',
+      path.join(homedir(), '.npm-global'),
+      path.join(homedir(), '.nvm'),
+      path.join(homedir(), '.volta'),
+      path.join(homedir(), '.local', 'bin'),
+    ];
+    for (const prefix of knownGlobalDirs) {
+      if (execPath.startsWith(prefix)) return true;
+    }
+  }
+
+  return false;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Track an npx invocation of the given command.
+ * No-op if already installed or not running via npx.
+ * Designed to add <5ms overhead — all sync I/O on a small JSON file.
+ */
+export function track(command) {
+  try {
+    if (!command) return;
+
+    // If user has permanently installed wheat, record that and stop
+    if (isInstalled()) {
+      const data = readUsage();
+      if (!data.installed) {
+        data.installed = true;
+        writeUsage(data);
+      }
+      return;
+    }
+
+    // Only count npx invocations
+    if (!isNpxInvocation()) return;
+
+    const data = readUsage();
+    if (data.installed) return;
+
+    if (!data.commands) data.commands = {};
+    data.commands[command] = (data.commands[command] || 0) + 1;
+    writeUsage(data);
+  } catch {
+    // fail silently — never interfere with the command
+  }
+}
+
+/**
+ * Print an install suggestion if usage thresholds are met.
+ * No-op if:
+ *   - Already installed (globally or locally)
+ *   - --quiet flag is present
+ *   - WHEAT_NO_INSTALL_PROMPT=1 env var is set
+ *   - Not running via npx
+ *   - Below threshold
+ *
+ * Messages go to stderr so they don't pollute stdout (piped output stays clean).
+ * Never blocks, never prompts interactively, never forces.
+ */
+export function maybePrompt(command) {
+  try {
+    if (process.env.WHEAT_NO_INSTALL_PROMPT === '1') return;
+    if (process.argv.includes('--quiet')) return;
+    if (isInstalled()) return;
+    if (!isNpxInvocation()) return;
+    if (!command) return;
+
+    const data = readUsage();
+    if (data.installed) return;
+
+    const count = (data.commands && data.commands[command]) || 0;
+    const total = Object.values(data.commands || {}).reduce((a, b) => a + b, 0);
+
+    // Use the higher of per-command and total count for threshold comparison.
+    // A user who runs 2x init + 2x compile = 4 total should start seeing prompts
+    // even though neither command alone hit 3.
+    const effective = Math.max(count, total);
+
+    if (effective >= THRESHOLDS.prominent) {
+      // 10+ invocations: more visible, but still non-blocking
+      process.stderr.write(
+        `\n  wheat: You've used npx ${total} times (${command}: ${count}).` +
+        `\n         Install for instant startup and offline use:` +
+        `\n           npm i -g @grainulation/wheat    (global)` +
+        `\n           npm i -D @grainulation/wheat    (project dev dep)\n\n`
+      );
+    } else if (effective >= THRESHOLDS.suggest_local) {
+      // 5-9 invocations: suggest both global and local
+      process.stderr.write(
+        `  wheat: You've run wheat via npx ${total} times. ` +
+        `For instant startup: npm i -g @grainulation/wheat\n` +
+        `  Or add to this project: npm i -D @grainulation/wheat\n`
+      );
+    } else if (effective >= THRESHOLDS.suggest_global) {
+      // 3-4 invocations: one-liner, suggest global only
+      process.stderr.write(
+        `  wheat: You've run wheat via npx ${count} times. ` +
+        `For instant startup: npm i -g @grainulation/wheat\n`
+      );
+    }
+  } catch {
+    // fail silently
+  }
+}

package/lib/quickstart.js

@@ -0,0 +1,276 @@
+/**
+ * wheat quickstart — zero-to-dashboard in under 90 seconds
+ *
+ * Creates a demo sprint with pre-seeded research claims,
+ * compiles them, and opens the dashboard. Designed to show
+ * wheat's value in the shortest possible time.
+ *
+ * Usage:
+ *   wheat quickstart [--dir <path>] [--no-open] [--port 9092]
+ *
+ * Zero npm dependencies.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execFileSync, execFile } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function target(dir, ...segments) {
+  return path.join(dir, ...segments);
+}
+
+function packageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+// ── Demo sprint data ────────────────────────────────────────────────────────
+
+const DEMO_QUESTION = 'Should we migrate our REST API to GraphQL?';
+const DEMO_AUDIENCE = ['backend team', 'frontend team', 'CTO'];
+const DEMO_CONSTRAINTS = [
+  'Must maintain backward compatibility with existing REST clients for 6 months',
+  'Team has 3 backend engineers, none with production GraphQL experience',
+  'Current API serves 200 req/s peak, 50ms p95 latency — cannot regress',
+];
+const DEMO_DONE = 'A recommendation with evidence: migrate, don\'t migrate, or hybrid approach, with risk assessment and migration timeline.';
+
+const DEMO_CLAIMS = [
+  {
+    id: 'd001', type: 'constraint', topic: 'backward-compatibility',
+    content: 'Must maintain backward compatibility with existing REST clients for 6 months.',
+    source: { origin: 'stakeholder', artifact: null, connector: null },
+    evidence: 'stated', status: 'active', phase_added: 'define',
+    tags: ['api', 'constraint'],
+  },
+  {
+    id: 'd002', type: 'constraint', topic: 'team-experience',
+    content: 'Team has 3 backend engineers, none with production GraphQL experience.',
+    source: { origin: 'stakeholder', artifact: null, connector: null },
+    evidence: 'stated', status: 'active', phase_added: 'define',
+    tags: ['team', 'constraint'],
+  },
+  {
+    id: 'd003', type: 'constraint', topic: 'performance-baseline',
+    content: 'Current API serves 200 req/s peak, 50ms p95 latency — cannot regress.',
+    source: { origin: 'stakeholder', artifact: null, connector: null },
+    evidence: 'stated', status: 'active', phase_added: 'define',
+    tags: ['performance', 'constraint'],
+  },
+  {
+    id: 'd004', type: 'constraint', topic: 'done-criteria',
+    content: 'Done looks like: A recommendation with evidence — migrate, don\'t migrate, or hybrid approach, with risk assessment and migration timeline.',
+    source: { origin: 'stakeholder', artifact: null, connector: null },
+    evidence: 'stated', status: 'active', phase_added: 'define',
+    tags: ['done-criteria'],
+  },
+  {
+    id: 'r001', type: 'factual', topic: 'graphql-adoption-2026',
+    content: 'GraphQL adoption in production backends reached 29% in 2025 (Postman State of APIs). However, 67% of teams that adopted GraphQL still maintain parallel REST endpoints for backward compatibility.',
+    source: { origin: 'research', artifact: 'research/graphql-landscape.md', connector: null },
+    evidence: 'web', status: 'active', phase_added: 'research',
+    tags: ['graphql', 'adoption', 'industry'],
+  },
+  {
+    id: 'r002', type: 'factual', topic: 'graphql-performance',
+    content: 'GraphQL resolvers add 2-8ms overhead per request compared to direct REST handlers in Node.js benchmarks. For nested queries with N+1 patterns, latency can spike to 200-500ms without DataLoader batching. With DataLoader, overhead drops to 5-15ms for complex queries.',
+    source: { origin: 'research', artifact: 'research/graphql-landscape.md', connector: null },
+    evidence: 'web', status: 'active', phase_added: 'research',
+    tags: ['graphql', 'performance', 'latency'],
+  },
+  {
+    id: 'r003', type: 'risk', topic: 'learning-curve',
+    content: 'Teams without GraphQL experience report 3-6 month ramp-up period before achieving parity with REST productivity. Schema design mistakes in the first 2 months often require breaking changes later.',
+    source: { origin: 'research', artifact: 'research/graphql-landscape.md', connector: null },
+    evidence: 'web', status: 'active', phase_added: 'research',
+    tags: ['graphql', 'risk', 'team'],
+  },
+  {
+    id: 'r004', type: 'recommendation', topic: 'hybrid-approach',
+    content: 'A hybrid approach (GraphQL gateway over existing REST services) provides incremental adoption without rewriting the backend. Apollo Federation and GraphQL Mesh both support this pattern. The frontend gets GraphQL benefits while the backend stays REST until individual services are ready to migrate.',
+    source: { origin: 'research', artifact: 'research/graphql-landscape.md', connector: null },
+    evidence: 'web', status: 'active', phase_added: 'research',
+    tags: ['graphql', 'recommendation', 'architecture'],
+  },
+  {
+    id: 'r005', type: 'estimate', topic: 'migration-timeline',
+    content: 'Estimated timeline for full GraphQL migration with 3 engineers: 2-3 months for schema design + gateway setup, 4-6 months for service-by-service migration, 2 months for REST deprecation. Total: 8-11 months. Hybrid approach can start delivering value in month 2.',
+    source: { origin: 'research', artifact: 'research/graphql-landscape.md', connector: null },
+    evidence: 'web', status: 'active', phase_added: 'research',
+    tags: ['graphql', 'estimate', 'timeline'],
+  },
+  {
+    id: 'r006', type: 'factual', topic: 'graphql-tooling',
+    content: 'Apollo Server v4 is the most adopted GraphQL server (62% market share among Node.js GraphQL users). Alternatives: Mercurius (Fastify-native, 30% faster in benchmarks), GraphQL Yoga (from The Guild, best DX), Pothos (code-first schema builder).',
+    source: { origin: 'research', artifact: 'research/graphql-landscape.md', connector: null },
+    evidence: 'web', status: 'active', phase_added: 'research',
+    tags: ['graphql', 'tooling', 'ecosystem'],
+  },
+  {
+    id: 'x001', type: 'factual', topic: 'graphql-performance',
+    content: 'The 2-8ms overhead claim (r002) understates the real-world impact. In production, GraphQL query parsing, validation, and execution planning add consistent 10-20ms overhead for medium-complexity queries. This matters when the p95 budget is 50ms.',
+    source: { origin: 'challenge', artifact: null, connector: null },
+    evidence: 'web', status: 'active', phase_added: 'research',
+    conflicts_with: ['r002'],
+    tags: ['graphql', 'performance', 'challenge'],
+  },
+];
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+export async function run(dir, args) {
+  const startTime = Date.now();
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--no-open') flags.noOpen = true;
+    else if (args[i] === '--port' && args[i + 1]) { flags.port = args[++i]; }
+  }
+
+  const claimsPath = target(dir, 'claims.json');
+  if (fs.existsSync(claimsPath) && !args.includes('--force')) {
+    console.log();
+    console.log('  A sprint already exists here. Use --force to overwrite.');
+    console.log();
+    process.exit(1);
+  }
+
+  console.log();
+  console.log('  \x1b[1m\x1b[33mwheat quickstart\x1b[0m — zero to dashboard');
+  console.log('  ─────────────────────────────────────────');
+  console.log();
+
+  // Step 1: Create claims.json with demo data
+  const timestamp = now();
+  const claimsData = {
+    meta: {
+      question: DEMO_QUESTION,
+      initiated: new Date().toISOString().split('T')[0],
+      audience: DEMO_AUDIENCE,
+      phase: 'research',
+      connectors: [],
+      dismissed_blind_spots: [],
+      merged_from: [],
+    },
+    claims: DEMO_CLAIMS.map(c => ({
+      ...c,
+      timestamp,
+      conflicts_with: c.conflicts_with || [],
+      resolved_by: c.resolved_by || null,
+    })),
+  };
+
+  fs.writeFileSync(claimsPath, JSON.stringify(claimsData, null, 2) + '\n');
+  const elapsed1 = Date.now() - startTime;
+  console.log(`  \x1b[32m+\x1b[0m claims.json (${claimsData.claims.length} claims seeded)  \x1b[2m${elapsed1}ms\x1b[0m`);
+
+  // Step 2: Create CLAUDE.md
+  const templatePath = path.join(packageRoot(), 'templates', 'claude.md');
+  let claudeMd;
+  try {
+    claudeMd = fs.readFileSync(templatePath, 'utf8')
+      .replace(/\{\{QUESTION\}\}/g, DEMO_QUESTION)
+      .replace(/\{\{AUDIENCE\}\}/g, DEMO_AUDIENCE.join(', '))
+      .replace(/\{\{CONSTRAINTS\}\}/g, DEMO_CONSTRAINTS.map(c => `- ${c}`).join('\n'))
+      .replace(/\{\{DONE_CRITERIA\}\}/g, DEMO_DONE);
+  } catch {
+    claudeMd = `# Wheat Sprint\n\n**Question:** ${DEMO_QUESTION}\n`;
+  }
+  fs.writeFileSync(target(dir, 'CLAUDE.md'), claudeMd);
+  console.log(`  \x1b[32m+\x1b[0m CLAUDE.md`);
+
+  // Step 3: Copy slash commands
+  const srcDir = path.join(packageRoot(), 'templates', 'commands');
+  const destDir = target(dir, '.claude', 'commands');
+  fs.mkdirSync(destDir, { recursive: true });
+  let copied = 0;
+  try {
+    for (const file of fs.readdirSync(srcDir)) {
+      if (!file.endsWith('.md')) continue;
+      fs.copyFileSync(path.join(srcDir, file), path.join(destDir, file));
+      copied++;
+    }
+  } catch { /* commands dir may not exist in dev */ }
+  console.log(`  \x1b[32m+\x1b[0m .claude/commands/ (${copied} commands)`);
+
+  // Step 4: Create directories
+  for (const d of ['output', 'research', 'prototypes', 'evidence']) {
+    const dirPath = target(dir, d);
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+      fs.writeFileSync(path.join(dirPath, '.gitkeep'), '');
+    }
+  }
+  console.log('  \x1b[32m+\x1b[0m output/, research/, prototypes/, evidence/');
+
+  // Step 5: Run the compiler
+  console.log();
+  console.log('  \x1b[1mCompiling...\x1b[0m');
+  try {
+    const compilerPath = path.join(packageRoot(), 'lib', 'compiler.js');
+    const compilerModule = await import(compilerPath);
+    if (typeof compilerModule.compile === 'function') {
+      await compilerModule.compile(dir, ['--summary']);
+    } else if (typeof compilerModule.run === 'function') {
+      await compilerModule.run(dir, ['--summary']);
+    }
+  } catch (err) {
+    // Fallback: try running as subprocess
+    try {
+      const output = execFileSync('node', [
+        path.join(packageRoot(), 'bin', 'wheat.js'), 'compile', '--summary', '--dir', dir
+      ], { timeout: 15000, stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+      process.stdout.write(output);
+    } catch (e) {
+      console.log(`  \x1b[33m!\x1b[0m Compilation skipped: ${e.message}`);
+    }
+  }
+
+  const elapsed5 = Date.now() - startTime;
+  console.log();
+  console.log(`  \x1b[32mCompiled in ${elapsed5}ms.\x1b[0m`);
+
+  // Step 6: Start the dashboard
+  const port = flags.port || '9092';
+  console.log();
+  console.log(`  \x1b[1mStarting dashboard on port ${port}...\x1b[0m`);
+
+  // Import and start the server
+  try {
+    const serverModule = await import(path.join(packageRoot(), 'lib', 'server.js'));
+    // The server module's run() starts listening — we call it and let it run
+    // It will keep the process alive
+    const serverArgs = ['--port', port, '--dir', dir];
+    if (flags.noOpen) serverArgs.push('--no-open');
+
+    console.log();
+    console.log('  ─────────────────────────────────────────');
+    const totalTime = ((Date.now() - startTime) / 1000).toFixed(1);
+    console.log(`  \x1b[1m\x1b[33mQuickstart complete.\x1b[0m  ${totalTime}s total`);
+    console.log();
+    console.log(`  Sprint:     ${DEMO_QUESTION}`);
+    console.log(`  Claims:     ${claimsData.claims.length} (${DEMO_CLAIMS.filter(c => c.id.startsWith('d')).length} constraints + ${DEMO_CLAIMS.filter(c => c.id.startsWith('r')).length} research + ${DEMO_CLAIMS.filter(c => c.id.startsWith('x')).length} challenge)`);
+    console.log(`  Conflicts:  1 (r002 vs x001 — performance overhead)`);
+    console.log(`  Dashboard:  http://localhost:${port}`);
+    console.log();
+    console.log('  What to do now:');
+    console.log('    1. Explore the dashboard — click topics, claims, see the conflict');
+    console.log('    2. Open Claude Code here and try: /research "GraphQL security"');
+    console.log('    3. Or start YOUR sprint: wheat init');
+    console.log();
+
+    // Start server (this blocks — keeps process alive)
+    await serverModule.run(dir, serverArgs);
+  } catch (err) {
+    // If server fails, still show the summary
+    console.log(`  \x1b[33m!\x1b[0m Dashboard failed to start: ${err.message}`);
+    console.log(`  Run manually: wheat serve --dir ${dir}`);
+    console.log();
+  }
+}