brain-dev 1.1.0 → 1.2.0

package/README.md

@@ -185,6 +185,16 @@ pending → discussing → discussed → planning → executing → executed →
 
 Every command knows what comes next. `brain-dev progress` always tells you the right next step.
 
+## Auto Update Notification
+
+Brain checks for newer versions on session start (background, non-blocking). If an update is available, the statusline shows:
+
+```
+⬆ /brain:upgrade | brain | [########--] 78% | P2: executing
+```
+
+Type `/brain:upgrade` to see the upgrade command and clear the notification.
+
 ## Zero Dependencies
 
 Brain is a single npm package with zero runtime dependencies. Just Node.js 22+.

package/bin/brain-tools.cjs

@@ -178,6 +178,12 @@ async function main() {
       await require('./lib/commands/update.cjs').run(args.slice(1));
       break;
 
+    case 'upgrade':
+      await require('./lib/commands/upgrade.cjs').run(args.slice(1), {
+        brainDir: path.join(process.cwd(), '.brain')
+      });
+      break;
+
     case 'health':
       await require('./lib/commands/health.cjs').run(args.slice(1));
       break;

package/bin/lib/commands/quick.cjs

@@ -165,7 +165,7 @@ function handleInit(args, brainDir, state) {
     output_dir: taskDir,
     phase_number_padded: String(nextNum).padStart(3, '0'),
     phase_slug: slug,
-    stack_expertise: generateExpertise(brainDir, 'executor')
+    stack_expertise: generateExpertise(brainDir, 'planner')
   });
 
   const quickConstraints = [

package/bin/lib/commands/upgrade.cjs

@@ -0,0 +1,48 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { output, prefix } = require('../core.cjs');
+
+async function run(args = [], opts = {}) {
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+
+  // Read cache
+  const cachePath = path.join(brainDir, '.update-check.json');
+  let cache = null;
+  try {
+    cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+  } catch {}
+
+  if (!cache || !cache.update_available) {
+    const lines = [
+      prefix('You are on the latest version.'),
+      prefix(`Installed: ${cache?.installed || 'unknown'}`)
+    ];
+    output({ action: 'up-to-date', installed: cache?.installed || 'unknown' }, lines.join('\n'));
+    return { action: 'up-to-date' };
+  }
+
+  // Show upgrade info
+  const lines = [
+    prefix(`Update available: ${cache.installed} → ${cache.latest}`),
+    '',
+    prefix('To upgrade, run:'),
+    prefix(`  npx brain-dev@${cache.latest} update`),
+    '',
+    prefix('Or update globally:'),
+    prefix('  npm install -g brain-dev@latest'),
+    '',
+    prefix('After updating, restart Claude Code to pick up new features.')
+  ];
+
+  output({
+    action: 'upgrade-available',
+    installed: cache.installed,
+    latest: cache.latest,
+    command: `npx brain-dev@${cache.latest} update`
+  }, lines.join('\n'));
+
+  return { action: 'upgrade-available', installed: cache.installed, latest: cache.latest };
+}
+
+module.exports = { run };

package/bin/lib/commands/verify.cjs

@@ -10,6 +10,7 @@ const { output, error, success } = require('../core.cjs');
 const antiPatterns = require('../anti-patterns.cjs');
 const { buildDebuggerSpawnInstructions } = require('./execute.cjs');
 const { isPathWithinRoot } = require('../security.cjs');
+const { generateExpertise } = require('../stack-expert.cjs');
 
 /**
  * Find a phase directory under .brain/phases/ matching a phase number.
@@ -271,7 +272,8 @@ async function run(args = [], opts = {}) {
     must_haves: mustHavesFormatted,
     output_path: outputPath,
     anti_pattern_results: formatAntiPatternResults(apResults),
-    nyquist_section: nyquistSection
+    nyquist_section: nyquistSection,
+    stack_expertise: generateExpertise(brainDir, 'verifier')
   });
 
   // Read depth config from state (defaults to 'deep' for backward compatibility)

package/bin/lib/commands.cjs

@@ -234,6 +234,15 @@ const COMMANDS = [
     needsState: false,
     args: '  --fix    Enable aggressive repair of hooks and templates\n  --quick  Run safe checks only (used by bootstrap)\n  --json   Force JSON output'
   },
+  {
+    name: 'upgrade',
+    description: 'Check and apply Brain updates',
+    usage: 'brain-dev upgrade',
+    group: 'Meta',
+    implemented: true,
+    needsState: false,
+    args: ''
+  },
   {
     name: 'version',
     description: 'Show brain-dev version',

package/bin/lib/init.cjs

@@ -249,10 +249,18 @@ async function run(args = []) {
     fs.chmodSync(path.join(brainDir, 'hooks', 'post-tool-use.sh'), 0o755);
   }
 
+  // Copy update check hook
+  const checkUpdateSrc = packagePath('hooks', 'check-update.sh');
+  if (fs.existsSync(checkUpdateSrc)) {
+    fs.copyFileSync(checkUpdateSrc, path.join(brainDir, 'hooks', 'check-update.sh'));
+    fs.chmodSync(path.join(brainDir, 'hooks', 'check-update.sh'), 0o755);
+  }
+
   // Write .gitignore
   const gitignoreContent = [
     '*.tmp',
     '*.lock',
+    '.update-check.json',
     'storm/fragments/',
     'storm/events.jsonl',
     ''

package/bin/lib/stack-expert.cjs

@@ -201,22 +201,27 @@ function generateExpertise(brainDir, role = 'general') {
       const conventions = fs.readFileSync(conventionsPath, 'utf8');
       const excerpt = conventions.slice(0, 2000); // Keep concise
       sections.push('### Project-Specific Conventions (from codebase analysis)');
+      sections.push('```conventions');
       sections.push(excerpt);
+      sections.push('```');
       sections.push('');
     }
 
-    if (role === 'planner' && fs.existsSync(stackPath)) {
+    if ((role === 'planner' || role === 'executor') && fs.existsSync(stackPath)) {
       const stackAnalysis = fs.readFileSync(stackPath, 'utf8');
       const excerpt = stackAnalysis.slice(0, 1500);
       sections.push('### Existing Stack Details');
+      sections.push('```stack');
       sections.push(excerpt);
+      sections.push('```');
       sections.push('');
     }
   }
 
   // LAYER 3: Context7 live documentation queries
   if (framework || lang) {
-    sections.push(generateContext7Queries(brainDir));
+    const ctx7 = generateContext7Queries(detection);
+    if (ctx7) sections.push(ctx7);
   }
 
   // Unknown framework: Context7 becomes PRIMARY (not fallback)
@@ -262,10 +267,15 @@ function generateExpertise(brainDir, role = 'general') {
  * @returns {object|null} Framework pattern object or null
  */
 function findFrameworkPattern(name) {
-  // Case-insensitive, partial match
+  if (!name) return null;
+  const lower = name.toLowerCase();
+  // Exact match first
   for (const [key, value] of Object.entries(STACK_PATTERNS.frameworks)) {
-    if (key.toLowerCase() === name.toLowerCase() ||
-        name.toLowerCase().includes(key.toLowerCase())) {
+    if (key.toLowerCase() === lower) return value;
+  }
+  // startsWith match (e.g., "Next.js 15" matches "Next.js")
+  for (const [key, value] of Object.entries(STACK_PATTERNS.frameworks)) {
+    if (lower.startsWith(key.toLowerCase()) || key.toLowerCase().startsWith(lower)) {
       return value;
     }
   }
@@ -274,11 +284,13 @@ function findFrameworkPattern(name) {
 
 /**
  * Generate Context7 lookup instructions for the detected stack.
- * @param {string} brainDir
+ * @param {object|string} detectionOrBrainDir - Parsed detection object or brainDir path
  * @returns {string} Context7 query instructions
  */
-function generateContext7Queries(brainDir) {
-  const detection = readDetection(brainDir);
+function generateContext7Queries(detectionOrBrainDir) {
+  const detection = typeof detectionOrBrainDir === 'string'
+    ? readDetection(detectionOrBrainDir)
+    : detectionOrBrainDir;
   if (!detection) return '';
 
   const framework = detection.stack?.framework || detection.stack?.primary?.framework;

package/commands/brain/upgrade.md

@@ -0,0 +1,20 @@
+---
+name: brain:upgrade
+description: Check for and apply Brain updates
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Check if a newer version of brain-dev is available and show upgrade instructions.
+</objective>
+
+<process>
+1. Run: `npx brain-dev upgrade`
+2. Brain will:
+   - Check the cached update status from `.brain/.update-check.json`
+   - Show current vs latest version if an update is available
+   - Provide the exact command to run for upgrading
+   - Clear the update notification from the statusline
+3. If already up to date, confirms the current version.
+</process>

package/hooks/bootstrap.sh

@@ -48,7 +48,7 @@ try {
     'Phase: ' + (data.phase && data.phase.current || 0) + ' (' + (data.phase && data.phase.status || 'initialized') + ')',
     'Next: ' + (data.nextAction || '/brain:new-project'),
     '',
-    'Commands: /brain:new-project, /brain:story, /brain:discuss, /brain:plan, /brain:execute, /brain:verify, /brain:complete, /brain:quick, /brain:new-task, /brain:progress, /brain:pause, /brain:resume, /brain:help, /brain:health, /brain:update, /brain:storm, /brain:adr, /brain:phase, /brain:config, /brain:map, /brain:recover, /brain:dashboard, /brain:auto (or execute --auto)',
+    'Commands: /brain:new-project, /brain:story, /brain:discuss, /brain:plan, /brain:execute, /brain:verify, /brain:complete, /brain:quick, /brain:new-task, /brain:progress, /brain:pause, /brain:resume, /brain:help, /brain:health, /brain:update, /brain:upgrade, /brain:storm, /brain:adr, /brain:phase, /brain:config, /brain:map, /brain:recover, /brain:dashboard, /brain:auto (or execute --auto)',
     '',
     'Instructions for Claude:',
     '- When user types /brain:<command>, run: npx brain-dev <command> [args]',
@@ -66,3 +66,8 @@ try {
 if [ -f "$BRAIN_DIR/brain.json" ]; then
   npx brain-dev health --quick 2>/dev/null
 fi
+
+# Background update check (non-blocking)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bash "$SCRIPT_DIR/check-update.sh" "$BRAIN_DIR" &>/dev/null &
+disown

package/hooks/check-update.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# Background npm version check — writes result to .brain/.update-check.json
+# Called by bootstrap.sh with & (background, non-blocking)
+
+BRAIN_DIR="${1:-.brain}"
+CACHE_FILE="$BRAIN_DIR/.update-check.json"
+
+# Read installed version from package
+INSTALLED=$(node -e "try{console.log(require('brain-dev/package.json').version)}catch{console.log('unknown')}" 2>/dev/null)
+if [ "$INSTALLED" = "unknown" ] || [ -z "$INSTALLED" ]; then
+  INSTALLED=$(npx brain-dev version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+fi
+
+# Query npm for latest (10 second timeout)
+LATEST=$(timeout 10 npm view brain-dev version 2>/dev/null)
+
+if [ -z "$LATEST" ]; then
+  # npm unavailable or timeout — skip silently
+  exit 0
+fi
+
+# Trim whitespace to prevent false positives
+INSTALLED=$(echo "$INSTALLED" | tr -d '[:space:]')
+LATEST=$(echo "$LATEST" | tr -d '[:space:]')
+
+# Write cache safely using node (prevents JSON injection from malformed version strings)
+node -e "
+  const fs = require('fs');
+  const installed = process.argv[1];
+  const latest = process.argv[2];
+  fs.writeFileSync(process.argv[3], JSON.stringify({
+    update_available: installed !== latest,
+    installed: installed,
+    latest: latest,
+    checked: Math.floor(Date.now() / 1000)
+  }));
+" "$INSTALLED" "$LATEST" "$CACHE_FILE"

package/hooks/statusline.sh

@@ -125,6 +125,18 @@ node -e "
     phaseDisplay = ' | P' + phaseCurrent + (phaseStatus ? ': ' + phaseStatus : '');
   }
 
+  // Read update cache for upgrade notification
+  let updatePrefix = '';
+  try {
+    const cachePath = '$BRAIN_DIR/.update-check.json';
+    if (fs.existsSync(cachePath)) {
+      const cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+      if (cache.update_available === true) {
+        updatePrefix = '\x1b[33m\u2B06 /brain:upgrade\x1b[0m | ';
+      }
+    }
+  } catch {}
+
   // Output status line to stdout
-  process.stdout.write(projectName + phaseDisplay + ' | ' + bar);
+  process.stdout.write(updatePrefix + projectName + phaseDisplay + ' | ' + bar);
 " "$input" 2>/dev/null || echo "brain | ---"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brain-dev",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "AI-powered development workflow orchestrator",
   "author": "halilcosdu",
   "license": "MIT",