@itz4blitz/agentful 1.2.0 → 1.3.0

package/bin/hooks/block-file-creation.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+
+/**
+ * Block File Creation Hook
+ *
+ * Prevents creation of arbitrary files outside of permitted directories and types.
+ * Stops agents from littering the codebase with random JSON, TXT, LOG files.
+ *
+ * Allowed file creation:
+ * - Source code files (.js, .ts, .jsx, .tsx, .py, .go, .rs, .java, .c, .cpp, .h, .cs, .rb, .php, etc.)
+ * - Config files in project root (package.json, tsconfig.json, vite.config.js, etc.)
+ * - Test files in test directories
+ * - Documentation in approved locations (see block-random-docs hook)
+ *
+ * Blocked:
+ * - Random .json files outside of root config
+ * - Random .txt, .log, .tmp files anywhere
+ * - State snapshots outside .agentful/
+ * - Arbitrary data files in src/, lib/, test/ directories
+ *
+ * Permitted directories for non-code artifacts:
+ * - .agentful/ - Runtime state (with validation)
+ * - fixtures/ - Test fixtures
+ * - mocks/ - Test mocks
+ * - public/assets/ - Static assets
+ * - docs/ - Documentation (if directory exists)
+ */
+
+import path from 'path';
+import fs from 'fs';
+
+// Get file path from environment (set by Claude Code hooks)
+const filePath = process.env.FILE || '';
+const toolName = process.env.TOOL_NAME || '';
+
+// Only intercept Write tool calls
+if (toolName !== 'Write') {
+  process.exit(0);
+}
+
+// Normalize path
+const normalizedPath = path.normalize(filePath);
+
+// Source code extensions (always allowed)
+const SOURCE_CODE_EXTENSIONS = [
+  '.js', '.mjs', '.cjs',
+  '.ts', '.mts', '.cts',
+  '.jsx', '.tsx',
+  '.py', '.pyi',
+  '.go',
+  '.rs',
+  '.java',
+  '.c', '.cpp', '.cc', '.cxx', '.h', '.hpp',
+  '.cs',
+  '.rb',
+  '.php',
+  '.swift',
+  '.kt', '.kts',
+  '.scala',
+  '.ex', '.exs',
+  '.clj', '.cljs',
+  '.sh', '.bash',
+  '.sql',
+  '.graphql', '.gql',
+  '.proto',
+  '.vue', '.svelte',
+  '.css', '.scss', '.sass', '.less',
+  '.html', '.htm',
+  '.xml', '.yaml', '.yml',
+  '.toml', '.ini', '.env.example',
+  '.gitignore', '.dockerignore', '.eslintignore'
+];
+
+// Check if file is source code
+const ext = path.extname(normalizedPath);
+if (SOURCE_CODE_EXTENSIONS.includes(ext)) {
+  process.exit(0);
+}
+
+// Markdown files are handled by block-random-docs hook
+if (ext === '.md' || ext === '.mdx') {
+  process.exit(0);
+}
+
+// Root-level config files (explicitly allowed)
+const ROOT_CONFIG_FILES = [
+  'package.json',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'bun.lockb',
+  'tsconfig.json',
+  'jsconfig.json',
+  'vite.config.js',
+  'vite.config.ts',
+  'vitest.config.js',
+  'vitest.config.ts',
+  'vitest.setup.js',
+  'vitest.setup.ts',
+  'vitest.global-teardown.js',
+  'jest.config.js',
+  'jest.config.ts',
+  'next.config.js',
+  'next.config.mjs',
+  'nuxt.config.js',
+  'nuxt.config.ts',
+  'svelte.config.js',
+  'astro.config.mjs',
+  'tailwind.config.js',
+  'tailwind.config.ts',
+  'postcss.config.js',
+  'eslint.config.js',
+  '.eslintrc.json',
+  '.eslintrc.js',
+  '.prettierrc',
+  '.prettierrc.json',
+  'prettier.config.js',
+  'turbo.json',
+  'nx.json',
+  'lerna.json',
+  'Dockerfile',
+  'docker-compose.yml',
+  'docker-compose.yaml',
+  '.dockerignore',
+  '.gitignore',
+  '.env.example',
+  'vercel.json',
+  'railway.json',
+  'render.yaml',
+  'fly.toml'
+];
+
+// Check if file is a root config file
+const fileName = path.basename(normalizedPath);
+if (ROOT_CONFIG_FILES.includes(fileName) && !normalizedPath.includes('/')) {
+  process.exit(0);
+}
+
+// Allowed directory patterns for non-code files
+const ALLOWED_DIRECTORY_PATTERNS = [
+  /^\.agentful\//,                       // Runtime state
+  /^\.claude\//,                         // Claude configuration
+  /^fixtures\//,                         // Test fixtures
+  /^test\/fixtures\//,
+  /^tests\/fixtures\//,
+  /^__fixtures__\//,
+  /^mocks\//,                           // Test mocks
+  /^test\/mocks\//,
+  /^tests\/mocks\//,
+  /^__mocks__\//,
+  /^public\/assets\//,                  // Static assets
+  /^public\/data\//,
+  /^static\/assets\//,
+  /^static\/data\//,
+  /^docs\/assets\//,                    // Documentation assets
+  /^\.github\//,                        // GitHub config
+  /^\.vscode\//,                        // VSCode config
+  /^config\//,                          // Config directory
+  /^\.config\//,
+  /^dist\//,                            // Build output (warn but allow)
+  /^build\//,
+  /^out\//
+];
+
+// Check if file is in allowed directory
+const isInAllowedDir = ALLOWED_DIRECTORY_PATTERNS.some(pattern => pattern.test(normalizedPath));
+
+if (isInAllowedDir) {
+  // Additional validation for .agentful/ files
+  if (normalizedPath.startsWith('.agentful/')) {
+    const agentfulFiles = [
+      '.agentful/state.json',
+      '.agentful/completion.json',
+      '.agentful/decisions.json',
+      '.agentful/architecture.json',
+      '.agentful/conversation-state.json',
+      '.agentful/conversation-history.json',
+      '.agentful/agent-metrics.json',
+      '.agentful/metadata.json'
+    ];
+
+    if (agentfulFiles.includes(normalizedPath)) {
+      process.exit(0);
+    }
+
+    // Block random files in .agentful/
+    console.error(`
+❌ BLOCKED: Arbitrary file creation in .agentful/
+
+File: ${filePath}
+
+Allowed .agentful/ files:
+  - state.json (current work phase)
+  - completion.json (feature progress)
+  - decisions.json (pending decisions)
+  - architecture.json (tech stack)
+  - conversation-state.json (conversation context)
+  - conversation-history.json (message history)
+  - agent-metrics.json (agent lifecycle hooks)
+  - metadata.json (version tracking)
+
+Do NOT create random state snapshots or debug files in .agentful/.
+`);
+    process.exit(1);
+  }
+
+  // Allow other permitted directories
+  process.exit(0);
+}
+
+// Risky file extensions (almost never allowed outside approved directories)
+const RISKY_EXTENSIONS = [
+  '.json',
+  '.txt',
+  '.log',
+  '.tmp',
+  '.temp',
+  '.bak',
+  '.backup',
+  '.old',
+  '.data',
+  '.dat',
+  '.bin',
+  '.dump',
+  '.out'
+];
+
+if (RISKY_EXTENSIONS.includes(ext)) {
+  console.error(`
+❌ BLOCKED: Random file creation
+
+File: ${filePath}
+Type: ${ext} file
+
+This file type is not allowed outside of approved directories.
+
+Allowed locations for ${ext} files:
+  ${ext === '.json' ? '- Project root (config files like package.json, tsconfig.json)' : ''}
+  - .agentful/ (runtime state, validation required)
+  - fixtures/ (test fixtures)
+  - mocks/ (test mocks)
+  - public/assets/ (static assets)
+  ${ext === '.json' ? '- test/**/fixtures/ (test data)' : ''}
+
+Source code files (.js, .ts, .py, etc.) can be created anywhere.
+
+Instead of creating random ${ext} files:
+  1. Use proper source code files
+  2. Store test data in fixtures/
+  3. Store config in root (package.json, tsconfig.json)
+  4. Store runtime state in .agentful/ (validated files only)
+
+Do NOT litter the codebase with arbitrary data files.
+`);
+  process.exit(1);
+}
+
+// Unknown file type - warn but allow (might be a legitimate file)
+console.warn(`
+⚠️  WARNING: Creating file with uncommon extension
+
+File: ${filePath}
+Extension: ${ext || '(no extension)'}
+
+This file type is not explicitly allowed or blocked.
+If this is a legitimate file, you can proceed.
+If this is a random artifact, please reconsider.
+`);
+
+// Allow with warning
+process.exit(0);

package/bin/hooks/product-spec-watcher.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+/**
+ * Product Spec Watcher Hook
+ *
+ * Triggered on Write/Edit of .claude/product/ markdown files
+ * Auto-triggers /agentful-generate when product spec is updated
+ *
+ * Use case:
+ * 1. User runs /agentful-init → creates .claude/product/index.md
+ * 2. This hook detects the file creation
+ * 3. Checks if from /agentful-init flow
+ * 4. Auto-triggers agent generation with BOTH tech stack + requirements
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+// Get tool use metadata from environment
+const toolUseEnv = process.env.CLAUDE_TOOL_USE || '{}';
+let toolUse;
+
+try {
+  toolUse = JSON.parse(toolUseEnv);
+} catch (error) {
+  // Invalid JSON - exit silently
+  process.exit(0);
+}
+
+// Get the file path that was written/edited
+const filePath = toolUse.parameters?.file_path || '';
+
+// Only trigger on product spec files
+if (!filePath.includes('.claude/product/')) {
+  process.exit(0);
+}
+
+// Get the root directory
+const getRepoRoot = () => {
+  try {
+    return execSync('git rev-parse --show-toplevel', {
+      encoding: 'utf8'
+    }).trim();
+  } catch {
+    // Not a git repo - use cwd
+    return process.cwd();
+  }
+};
+
+const repoRoot = getRepoRoot();
+const setupProgressPath = path.join(repoRoot, '.agentful', 'setup-progress.json');
+const architecturePath = path.join(repoRoot, '.agentful', 'architecture.json');
+
+// Check if this is from /agentful-init flow
+let isFromInit = false;
+let setupProgress = null;
+
+if (fs.existsSync(setupProgressPath)) {
+  try {
+    setupProgress = JSON.parse(fs.readFileSync(setupProgressPath, 'utf8'));
+
+    // Check if setup just completed but agents not yet generated
+    isFromInit = setupProgress.completed &&
+                 !setupProgress.agents_generated &&
+                 // Must be recent (within last 5 minutes)
+                 (Date.now() - new Date(setupProgress.timestamp).getTime()) < 5 * 60 * 1000;
+  } catch (error) {
+    // Ignore JSON parse errors
+  }
+}
+
+// Check if agents already exist
+const hasExistingAgents = fs.existsSync(architecturePath);
+
+if (isFromInit && !hasExistingAgents) {
+  console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Product Specification Updated
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+File: ${path.relative(repoRoot, filePath)}
+
+Auto-triggering agent generation with:
+  ✓ Tech stack (detected)
+  ✓ Product requirements (from /agentful-init)
+
+This ensures specialized agents are tailored to your product.
+
+Starting analysis...
+`);
+
+  // Mark that we're about to generate agents
+  if (setupProgress) {
+    setupProgress.agents_generation_triggered = true;
+    setupProgress.agents_generation_timestamp = new Date().toISOString();
+
+    try {
+      fs.writeFileSync(setupProgressPath, JSON.stringify(setupProgress, null, 2));
+    } catch (error) {
+      // Non-fatal - continue anyway
+    }
+  }
+
+  // NOTE: The actual triggering of /agentful-generate would happen here
+  // This depends on Claude Code's slash command triggering system
+  // For now, we just notify the user
+
+  console.log(`
+⏭️  Next: Agent generation will continue automatically.
+
+If it doesn't start automatically, run:
+  /agentful-generate
+`);
+
+} else if (!isFromInit && !hasExistingAgents) {
+  // Manual edit of product spec, but no agents yet
+  console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Product Specification Updated
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+File: ${path.relative(repoRoot, filePath)}
+
+To generate specialized agents based on your product spec:
+  /agentful-generate
+
+Or to use the guided setup:
+  /agentful-init
+`);
+
+} else if (hasExistingAgents) {
+  // Agents already exist - notify about regeneration
+  console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Product Specification Updated
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+File: ${path.relative(repoRoot, filePath)}
+
+Your product spec changed, but agents already exist.
+
+To regenerate agents with updated requirements:
+  /agentful-generate
+
+Or continue with existing agents:
+  /agentful-start
+`);
+}
+
+process.exit(0);

package/lib/index.js

@@ -12,10 +12,6 @@ export { initProject, copyDirectory, isInitialized, getState } from './init.js';
 // Export pipeline orchestration system
 export * from './pipeline/index.js';
 
-// Export codebase analyzer
-export * from './core/analyzer.js';
-export * from './core/detectors/index.js';
-
 // Export Claude Code executor abstraction
 export {
   ClaudeExecutor,
@@ -26,13 +22,6 @@ export {
   executeAgent
 } from './core/claude-executor.js';
 
-// Export output parser for agent responses
-export * from './core/output-parser.js';
-
-// Export safe agent execution (prevents runaway agents)
-export { SafeAgentExecutor, executeAgentSafely } from './safe-agent-executor.js';
-export { ParallelAgentOrchestrator, spawnAgentsSafely } from './orchestrator-safe-spawn.js';
-
 // Export CI integration for claude-code-action
 export * from './ci/index.js';
 

package/lib/init.js

@@ -1,11 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import {
-  initializeMetadata,
-  recordFileMetadata,
-  computeFileHash
-} from './update-helpers.js';
 import { generateHooksConfig } from './presets.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -32,14 +27,11 @@ export async function initProject(targetDir, config = null) {
     // Ensure target directory exists
     await fs.access(targetDir);
 
-    // Read package version for metadata tracking
+    // Read package version
     const packageJsonPath = path.join(PACKAGE_ROOT, 'package.json');
     const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'));
     const version = packageJson.version;
 
-    // Initialize metadata tracking
-    await initializeMetadata(targetDir, version);
-
     // 1. Copy .claude/ directory (agents, skills, commands) from template
     const claudeTargetDir = path.join(targetDir, '.claude');
 
@@ -77,9 +69,7 @@ export async function initProject(targetDir, config = null) {
       await fs.access(claudeMdSource);
       await fs.copyFile(claudeMdSource, claudeMdTarget);
 
-      // Track CLAUDE.md
-      const hash = await computeFileHash(claudeMdTarget);
-      await recordFileMetadata(targetDir, 'CLAUDE.md', hash, version);
+      // CLAUDE.md copied
 
       createdFiles.push('CLAUDE.md');
     } catch {
@@ -473,8 +463,6 @@ async function copySelectiveComponents(src, dest, targetDir, config, version) {
 
     try {
       await fs.copyFile(sourcePath, targetPath);
-      const hash = await computeFileHash(targetPath);
-      await recordFileMetadata(targetDir, `.claude/agents/${agentFile}`, hash, version);
     } catch (error) {
       console.warn(`Warning: Agent ${agentName} not found, skipping`);
     }
@@ -539,8 +527,6 @@ async function copySelectiveComponents(src, dest, targetDir, config, version) {
   };
 
   await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
-  const hash = await computeFileHash(settingsPath);
-  await recordFileMetadata(targetDir, '.claude/settings.json', hash, version);
 
   // 5. Create product directory (always included)
   const productDir = path.join(dest, 'product');
@@ -599,11 +585,6 @@ export async function copyDirectoryWithTracking(src, dest, targetDir, baseRelati
     } else {
       // Copy file
       await fs.copyFile(srcPath, destPath);
-
-      // Compute hash and track file
-      const relativePath = path.join(baseRelativePath, entry.name);
-      const hash = await computeFileHash(destPath);
-      await recordFileMetadata(targetDir, relativePath, hash, version);
     }
   }
 }