@howlil/ez-agents 3.5.0 → 4.0.0

package/bin/lib/template.cjs

@@ -0,0 +1,223 @@
+/**
+ * Template — Template selection and fill operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { normalizePhaseName, findPhaseInternal, generateSlugInternal, toPosixPath, output, error } = require('./core.cjs');
+const { reconstructFrontmatter } = require('./frontmatter.cjs');
+const { safePlanningWriteSync } = require('./planning-write.cjs');
+
+function cmdTemplateSelect(cwd, planPath, raw) {
+  if (!planPath) {
+    error('plan-path required');
+  }
+
+  try {
+    const fullPath = path.join(cwd, planPath);
+    const content = fs.readFileSync(fullPath, 'utf-8');
+
+    // Simple heuristics
+    const taskMatch = content.match(/###\s*Task\s*\d+/g) || [];
+    const taskCount = taskMatch.length;
+
+    const decisionMatch = content.match(/decision/gi) || [];
+    const hasDecisions = decisionMatch.length > 0;
+
+    // Count file mentions
+    const fileMentions = new Set();
+    const filePattern = /`([^`]+\.[a-zA-Z]+)`/g;
+    let m;
+    while ((m = filePattern.exec(content)) !== null) {
+      if (m[1].includes('/') && !m[1].startsWith('http')) {
+        fileMentions.add(m[1]);
+      }
+    }
+    const fileCount = fileMentions.size;
+
+    let template = 'templates/summary-standard.md';
+    let type = 'standard';
+
+    if (taskCount <= 2 && fileCount <= 3 && !hasDecisions) {
+      template = 'templates/summary-minimal.md';
+      type = 'minimal';
+    } else if (hasDecisions || fileCount > 6 || taskCount > 5) {
+      template = 'templates/summary-complex.md';
+      type = 'complex';
+    }
+
+    const result = { template, type, taskCount, fileCount, hasDecisions };
+    output(result, raw, template);
+  } catch (e) {
+    // Fallback to standard
+    output({ template: 'templates/summary-standard.md', type: 'standard', error: e.message }, raw, 'templates/summary-standard.md');
+  }
+}
+
+function cmdTemplateFill(cwd, templateType, options, raw) {
+  if (!templateType) { error('template type required: summary, plan, or verification'); }
+  if (!options.phase) { error('--phase required'); }
+
+  const phaseInfo = findPhaseInternal(cwd, options.phase);
+  if (!phaseInfo || !phaseInfo.found) { output({ error: 'Phase not found', phase: options.phase }, raw); return; }
+
+  const padded = normalizePhaseName(options.phase);
+  const today = new Date().toISOString().split('T')[0];
+  const phaseName = options.name || phaseInfo.phase_name || 'Unnamed';
+  const phaseSlug = phaseInfo.phase_slug || generateSlugInternal(phaseName);
+  const phaseId = `${padded}-${phaseSlug}`;
+  const planNum = (options.plan || '01').padStart(2, '0');
+  const fields = options.fields || {};
+
+  let frontmatter, body, fileName;
+
+  switch (templateType) {
+    case 'summary': {
+      frontmatter = {
+        phase: phaseId,
+        plan: planNum,
+        subsystem: '[primary category]',
+        tags: [],
+        provides: [],
+        affects: [],
+        'tech-stack': { added: [], patterns: [] },
+        'key-files': { created: [], modified: [] },
+        'key-decisions': [],
+        'patterns-established': [],
+        duration: '[X]min',
+        completed: today,
+        ...fields,
+      };
+      body = [
+        `# Phase ${options.phase}: ${phaseName} Summary`,
+        '',
+        '**[Substantive one-liner describing outcome]**',
+        '',
+        '## Performance',
+        '- **Duration:** [time]',
+        '- **Tasks:** [count completed]',
+        '- **Files modified:** [count]',
+        '',
+        '## Accomplishments',
+        '- [Key outcome 1]',
+        '- [Key outcome 2]',
+        '',
+        '## Task Commits',
+        '1. **Task 1: [task name]** - `hash`',
+        '',
+        '## Files Created/Modified',
+        '- `path/to/file.ts` - What it does',
+        '',
+        '## Decisions & Deviations',
+        '[Key decisions or "None - followed plan as specified"]',
+        '',
+        '## Next Phase Readiness',
+        '[What\'s ready for next phase]',
+      ].join('\n');
+      fileName = `${padded}-${planNum}-SUMMARY.md`;
+      break;
+    }
+    case 'plan': {
+      const planType = options.type || 'execute';
+      const wave = parseInt(options.wave) || 1;
+      frontmatter = {
+        phase: phaseId,
+        plan: planNum,
+        type: planType,
+        wave,
+        depends_on: [],
+        files_modified: [],
+        autonomous: true,
+        user_setup: [],
+        must_haves: { truths: [], artifacts: [], key_links: [] },
+        ...fields,
+      };
+      body = [
+        `# Phase ${options.phase} Plan ${planNum}: [Title]`,
+        '',
+        '## Objective',
+        '- **What:** [What this plan builds]',
+        '- **Why:** [Why it matters for the phase goal]',
+        '- **Output:** [Concrete deliverable]',
+        '',
+        '## Context',
+        '@.planning/PROJECT.md',
+        '@.planning/ROADMAP.md',
+        '@.planning/STATE.md',
+        '',
+        '## Tasks',
+        '',
+        '<task type="code">',
+        '  <name>[Task name]</name>',
+        '  <files>[file paths]</files>',
+        '  <action>[What to do]</action>',
+        '  <verify>[How to verify]</verify>',
+        '  <done>[Definition of done]</done>',
+        '</task>',
+        '',
+        '## Verification',
+        '[How to verify this plan achieved its objective]',
+        '',
+        '## Success Criteria',
+        '- [ ] [Criterion 1]',
+        '- [ ] [Criterion 2]',
+      ].join('\n');
+      fileName = `${padded}-${planNum}-PLAN.md`;
+      break;
+    }
+    case 'verification': {
+      frontmatter = {
+        phase: phaseId,
+        verified: new Date().toISOString(),
+        status: 'pending',
+        score: '0/0 must-haves verified',
+        ...fields,
+      };
+      body = [
+        `# Phase ${options.phase}: ${phaseName} — Verification`,
+        '',
+        '## Observable Truths',
+        '| # | Truth | Status | Evidence |',
+        '|---|-------|--------|----------|',
+        '| 1 | [Truth] | pending | |',
+        '',
+        '## Required Artifacts',
+        '| Artifact | Expected | Status | Details |',
+        '|----------|----------|--------|---------|',
+        '| [path] | [what] | pending | |',
+        '',
+        '## Key Link Verification',
+        '| From | To | Via | Status | Details |',
+        '|------|----|----|--------|---------|',
+        '| [source] | [target] | [connection] | pending | |',
+        '',
+        '## Requirements Coverage',
+        '| Requirement | Status | Blocking Issue |',
+        '|-------------|--------|----------------|',
+        '| [req] | pending | |',
+        '',
+        '## Result',
+        '[Pending verification]',
+      ].join('\n');
+      fileName = `${padded}-VERIFICATION.md`;
+      break;
+    }
+    default:
+      error(`Unknown template type: ${templateType}. Available: summary, plan, verification`);
+      return;
+  }
+
+  const fullContent = `---\n${reconstructFrontmatter(frontmatter)}\n---\n\n${body}\n`;
+  const outPath = path.join(cwd, phaseInfo.directory, fileName);
+
+  if (fs.existsSync(outPath)) {
+    output({ error: 'File already exists', path: toPosixPath(path.relative(cwd, outPath)) }, raw);
+    return;
+  }
+
+  safePlanningWriteSync(outPath, fullContent);
+  const relPath = toPosixPath(path.relative(cwd, outPath));
+  output({ created: true, path: relPath, template: templateType }, raw, relPath);
+}
+
+module.exports = { cmdTemplateSelect, cmdTemplateFill };

package/bin/lib/test-file-lock.cjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for EZ File Lock
+ * Run: node ez-agents/bin/lib/test-file-lock.cjs
+ */
+
+const { withLock, isLocked, ifUnlocked } = require('./file-lock.cjs');
+const fs = require('fs');
+const path = require('path');
+
+const testFile = path.join(__dirname, 'test-lock-target.txt');
+
+async function testBasicLock() {
+  console.log('\n=== Test 1: Basic Lock ===');
+  
+  await withLock(testFile, async () => {
+    console.log('Lock acquired, writing to file...');
+    fs.writeFileSync(testFile, 'Test content', 'utf-8');
+    console.log('File written');
+  });
+  
+  console.log('Lock released');
+  console.log('File content:', fs.readFileSync(testFile, 'utf-8'));
+  console.log('✓ Basic lock test passed');
+}
+
+async function testIsLocked() {
+  console.log('\n=== Test 2: Check Lock Status ===');
+  
+  const beforeLock = await isLocked(testFile);
+  console.log('Locked before:', beforeLock);
+  
+  const lockPromise = withLock(testFile, async () => {
+    console.log('Lock held for 1 second...');
+    await new Promise(r => setTimeout(r, 1000));
+  });
+  
+  // Wait for lock to be acquired
+  await new Promise(r => setTimeout(r, 100));
+  
+  const duringLock = await isLocked(testFile);
+  console.log('Locked during:', duringLock);
+  
+  await lockPromise;
+  
+  await new Promise(r => setTimeout(r, 100));
+  const afterLock = await isLocked(testFile);
+  console.log('Locked after:', afterLock);
+  
+  if (!beforeLock && duringLock && !afterLock) {
+    console.log('✓ Lock status test passed');
+  } else {
+    console.log('✗ Lock status test failed');
+  }
+}
+
+async function testIfUnlocked() {
+  console.log('\n=== Test 3: If Unlocked Pattern ===');
+  
+  // First call should succeed (file not locked)
+  const result1 = await ifUnlocked(testFile, async () => {
+    console.log('File was unlocked, writing...');
+    fs.writeFileSync(testFile, 'Written by ifUnlocked', 'utf-8');
+    return 'success';
+  }, 'fallback');
+  
+  console.log('Result 1:', result1);
+  
+  // Lock the file and try again
+  const lockPromise = withLock(testFile, async () => {
+    await new Promise(r => setTimeout(r, 500));
+  });
+  
+  await new Promise(r => setTimeout(r, 50));
+  
+  const result2 = await ifUnlocked(testFile, async () => {
+    return 'should-not-reach';
+  }, 'fallback-value');
+  
+  console.log('Result 2 (while locked):', result2);
+  
+  await lockPromise;
+  
+  if (result1 === 'success' && result2 === 'fallback-value') {
+    console.log('✓ IfUnlocked test passed');
+  } else {
+    console.log('✗ IfUnlocked test failed');
+  }
+}
+
+async function runTests() {
+  try {
+    await testBasicLock();
+    await testIsLocked();
+    await testIfUnlocked();
+    
+    console.log('\n' + '='.repeat(50));
+    console.log('File Lock test COMPLETE ✓');
+    console.log('='.repeat(50));
+  } catch (err) {
+    console.error('Test failed:', err);
+    process.exit(1);
+  } finally {
+    // Cleanup
+    if (fs.existsSync(testFile)) {
+      fs.unlinkSync(testFile);
+    }
+  }
+}
+
+runTests();

package/bin/lib/test-graceful.cjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for EZ Health Check and Timeout Exec
+ * Run: node ez-agents/bin/lib/test-graceful.cjs
+ */
+
+const HealthCheck = require('./health-check.cjs');
+const { execWithTimeout } = require('./timeout-exec.cjs');
+
+console.log('='.repeat(50));
+console.log('Testing EZ Graceful Degradation...');
+console.log('='.repeat(50));
+
+// Test 1: Health Check
+console.log('\n--- Test 1: Health Check ---\n');
+
+const health = new HealthCheck();
+const result = health.runAll();
+
+console.log('Health Status:', result.status.toUpperCase());
+console.log('Node Version:', result.node_version);
+console.log('Timestamp:', result.timestamp);
+
+if (result.warnings.length > 0) {
+  console.log('\nWarnings:');
+  result.warnings.forEach(w => console.log(`  ⚠ ${w}`));
+}
+
+if (result.issues.length > 0) {
+  console.log('\nIssues:');
+  result.issues.forEach(i => console.log(`  ✗ ${i}`));
+}
+
+console.log('\nChecks:');
+Object.entries(result.checks).forEach(([key, value]) => {
+  const icon = value ? '✓' : '✗';
+  console.log(`  ${icon} ${key}: ${value ? 'pass' : 'fail'}`);
+});
+
+// Test 2: Timeout Exec - Success case
+console.log('\n--- Test 2: Timeout Exec (Success) ---\n');
+
+(async () => {
+  try {
+    const output = await execWithTimeout('node', ['--version']);
+    console.log('Node version command:', output);
+    console.log('✓ Command executed successfully');
+  } catch (err) {
+    console.error('✗ Command failed:', err.message);
+  }
+
+  // Test 3: Timeout Exec - With fallback
+  console.log('\n--- Test 3: Timeout Exec (With Fallback) ---\n');
+
+  try {
+    // This should fail (nonexistent command) but return fallback
+    const output = await execWithTimeout('nonexistent-command', [], { 
+      fallback: 'fallback-value' 
+    });
+    console.log('Result with fallback:', output);
+    console.log('✓ Fallback returned successfully');
+  } catch (err) {
+    console.error('✗ Command failed without fallback:', err.message);
+  }
+
+  // Test 4: Timeout Exec - Timeout scenario
+  console.log('\n--- Test 4: Timeout Exec (Timeout Test) ---\n');
+
+  try {
+    // Create a script that takes too long
+    const { writeFileSync } = require('fs');
+    const { join } = require('path');
+    const tempScript = join(__dirname, 'temp-sleep.js');
+    writeFileSync(tempScript, 'setTimeout(() => console.log("done"), 3000);');
+    
+    const output = await execWithTimeout('node', [tempScript], { 
+      timeout: 1000,
+      fallback: 'timed-out-fallback'
+    });
+    console.log('Result after timeout:', output);
+    console.log('✓ Timeout handled with fallback');
+    
+    // Cleanup
+    require('fs').unlinkSync(tempScript);
+  } catch (err) {
+    console.error('Timeout test error:', err.message);
+  }
+
+  console.log('\n' + '='.repeat(50));
+  console.log('Graceful Degradation test COMPLETE ✓');
+  console.log('='.repeat(50));
+})();

package/bin/lib/test-logger.cjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for EZ Logger
+ * Run: node ez-agents/bin/lib/test-logger.cjs
+ */
+
+const Logger = require('./logger.cjs');
+const path = require('path');
+
+console.log('='.repeat(50));
+console.log('Testing EZ Logger...');
+console.log('='.repeat(50));
+
+const logger = new Logger();
+
+console.log('\nLog file:', logger.getLogFile());
+console.log('\nRunning test logs...\n');
+
+// Test all log levels
+logger.debug('Debug message', { test: 'debug', timestamp: Date.now() });
+console.log('✓ Debug logged');
+
+logger.info('Info message', { test: 'info', component: 'test-logger' });
+console.log('✓ Info logged');
+
+logger.warn('Warning message', { test: 'warn', action: 'testing' });
+console.log('✓ Warning logged');
+
+logger.error('Error message', { test: 'error', code: 'TEST_ERROR' });
+console.log('✓ Error logged (check console output above)');
+
+// Verify log file was created
+const logFile = logger.getLogFile();
+if (require('fs').existsSync(logFile)) {
+  console.log('\n✓ Log file created:', logFile);
+  
+  // Read and parse log entries
+  const content = require('fs').readFileSync(logFile, 'utf-8');
+  const lines = content.trim().split('\n');
+  console.log(`✓ Log file contains ${lines.length} entries`);
+  
+  // Validate each entry
+  console.log('\nLog entries:');
+  lines.forEach((line, i) => {
+    try {
+      const entry = JSON.parse(line);
+      console.log(`  ${i + 1}. [${entry.level}] ${entry.message}`);
+    } catch (err) {
+      console.log(`  ${i + 1}. (parse error: ${err.message})`);
+    }
+  });
+  
+  console.log('\n' + '='.repeat(50));
+  console.log('Logger test PASSED ✓');
+  console.log('='.repeat(50));
+} else {
+  console.error('\n✗ Log file was not created');
+  process.exit(1);
+}

package/bin/lib/test-safe-exec.cjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+const { safeExec, safeExecJSON, ALLOWED_COMMANDS } = require('./safe-exec.cjs');
+
+async function runTests() {
+  console.log('=== Testing safe-exec.cjs ===\n');
+  
+  // Test 1: Allowed command
+  console.log('Test 1: Allowed command (node --version)');
+  try {
+    const version = await safeExec('node', ['--version']);
+    console.log('✓ Result:', version);
+  } catch (err) { console.error('✗ Failed:', err.message); }
+  
+  // Test 2: Disallowed command
+  console.log('\nTest 2: Disallowed command (rm -rf /)');
+  try {
+    await safeExec('rm', ['-rf', '/']);
+    console.error('✗ Should have thrown error');
+  } catch (err) { console.log('✓ Blocked:', err.message); }
+  
+  // Test 3: Dangerous argument
+  console.log('\nTest 3: Dangerous argument (injection attempt)');
+  try {
+    await safeExec('echo', ['hello; rm -rf /']);
+    console.error('✗ Should have thrown error');
+  } catch (err) { console.log('✓ Blocked:', err.message); }
+  
+  // Test 4: Git command
+  console.log('\nTest 4: Git command (git --version)');
+  try {
+    const gitVersion = await safeExec('git', ['--version']);
+    console.log('✓ Result:', gitVersion);
+  } catch (err) { console.error('✗ Failed:', err.message); }
+  
+  console.log('\n=== Tests Complete ===');
+}
+
+runTests().catch(console.error);

package/bin/lib/test-safe-path.cjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+const path = require('path');
+const { normalizePath, isPathSafe, validatePathExists, safeReadFile } = require('./safe-path.cjs');
+
+const testBase = __dirname;
+
+async function runTests() {
+  console.log('=== Testing safe-path.cjs ===\n');
+  
+  // Test 1: Safe path
+  console.log('Test 1: Safe path (logger.cjs)');
+  try {
+    const safe = normalizePath(testBase, 'logger.cjs');
+    console.log('✓ Normalized:', safe);
+  } catch (err) { console.error('✗ Failed:', err.message); }
+  
+  // Test 2: Path traversal
+  console.log('\nTest 2: Path traversal (../../../etc/passwd)');
+  try {
+    normalizePath(testBase, '../../../etc/passwd');
+    console.error('✗ Should have thrown error');
+  } catch (err) { console.log('✓ Blocked:', err.message); }
+  
+  // Test 3: isPathSafe
+  console.log('\nTest 3: isPathSafe boolean check');
+  console.log('  Safe (logger.cjs):', isPathSafe(testBase, 'logger.cjs'));
+  console.log('  Unsafe (../..):', isPathSafe(testBase, '../..'));
+  console.log('✓ Boolean checks working');
+  
+  console.log('\n=== Tests Complete ===');
+}
+
+runTests().catch(console.error);

package/bin/lib/test-temp-file.cjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for EZ Temp File Handler
+ * Run: node ez-agents/bin/lib/test-temp-file.cjs
+ */
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+const {
+  createTempDir,
+  createTempFile,
+  writeToTemp,
+  readFromTemp,
+  cleanupTemp,
+  cleanupAll,
+  getTrackedTemps,
+  isPathSafe
+} = require('./temp-file.cjs');
+
+async function testCreateTempDir() {
+  console.log('\n=== Test 1: Create Temp Directory ===');
+  
+  const tempDir = await createTempDir('ez-test-');
+  console.log('Created temp dir:', tempDir);
+  
+  const exists = require('fs').existsSync(tempDir);
+  console.log('Directory exists:', exists);
+  
+  if (!exists) throw new Error('Temp dir was not created');
+  console.log('✓ Temp directory created successfully');
+  
+  return tempDir;
+}
+
+async function testCreateTempFile(tempDir) {
+  console.log('\n=== Test 2: Create Temp File ===');
+  
+  const tempFile = await createTempFile('test-', tempDir, 'Initial content');
+  console.log('Created temp file:', tempFile);
+  
+  const content = await readFromTemp(tempFile, { validateBase: tempDir });
+  console.log('File content:', content);
+  
+  if (content !== 'Initial content') {
+    throw new Error('File content mismatch');
+  }
+  console.log('✓ Temp file created and read successfully');
+  
+  return tempFile;
+}
+
+async function testWriteToTemp(tempFile, tempDir) {
+  console.log('\n=== Test 3: Write to Temp File ===');
+  
+  await writeToTemp(tempFile, 'Updated content', { validateBase: tempDir });
+  const content = await readFromTemp(tempFile, { validateBase: tempDir });
+  
+  console.log('Updated content:', content);
+  
+  if (content !== 'Updated content') {
+    throw new Error('Write failed');
+  }
+  console.log('✓ Temp file write successful');
+}
+
+async function testPathSafety() {
+  console.log('\n=== Test 4: Path Safety Validation ===');
+  
+  const baseDir = os.tmpdir();
+  
+  // Safe paths
+  console.log('Safe path (same dir):', isPathSafe(baseDir, path.join(baseDir, 'file.txt')));
+  console.log('Safe path (subdir):', isPathSafe(baseDir, path.join(baseDir, 'sub', 'file.txt')));
+  
+  // Unsafe paths (should be false)
+  const unsafePath = path.resolve(baseDir, '..', '..', 'etc', 'passwd');
+  console.log('Unsafe path (/etc/passwd):', isPathSafe(baseDir, unsafePath));
+  
+  console.log('✓ Path safety validation working');
+}
+
+async function testCleanup(tempFile, tempDir) {
+  console.log('\n=== Test 5: Cleanup ===');
+  
+  console.log('Tracked temps before cleanup:', getTrackedTemps().length);
+  
+  await cleanupTemp(tempFile);
+  console.log('Cleaned up temp file');
+  
+  const fileExists = require('fs').existsSync(tempFile);
+  console.log('Temp file exists after cleanup:', fileExists);
+  
+  await cleanupAll();
+  console.log('Cleaned up all temps');
+  
+  const dirExists = require('fs').existsSync(tempDir);
+  console.log('Temp dir exists after cleanup:', dirExists);
+  
+  console.log('✓ Cleanup successful');
+}
+
+async function runTests() {
+  const os = require('os');
+  const path = require('path');
+  
+  try {
+    const tempDir = await testCreateTempDir();
+    const tempFile = await testCreateTempFile(tempDir);
+    await testWriteToTemp(tempFile, tempDir);
+    await testPathSafety();
+    await testCleanup(tempFile, tempDir);
+    
+    console.log('\n' + '='.repeat(50));
+    console.log('Temp File Handler test COMPLETE ✓');
+    console.log('='.repeat(50));
+  } catch (err) {
+    console.error('Test failed:', err);
+    process.exit(1);
+  }
+}
+
+runTests();