@howlil/ez-agents 2.0.0

package/get-shit-done/bin/lib/temp-file.cjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+/**
+ * GSD Temp File — Secure temporary file handler
+ * 
+ * Creates secure temp files with fs.mkdtemp(), automatic cleanup on exit,
+ * and path validation to prevent traversal attacks.
+ * 
+ * Usage:
+ *   const { createTempFile, cleanupAll } = require('./temp-file.cjs');
+ *   const tempFile = await createTempFile('prefix-');
+ *   // ... use temp file ...
+ *   // Automatically cleaned up on process exit
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const Logger = require('./logger.cjs');
+const logger = new Logger();
+
+// Track all created temp resources for cleanup
+const tempResources = new Set();
+let cleanupRegistered = false;
+
+/**
+ * Generate a secure random suffix for temp names
+ * @returns {string} - Random hex string
+ */
+function generateSecureSuffix() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+/**
+ * Validate that a path is safe (no traversal attacks)
+ * @param {string} basePath - Base directory
+ * @param {string} targetPath - Target path to validate
+ * @returns {boolean} - True if safe
+ */
+function isPathSafe(basePath, targetPath) {
+  const resolvedBase = path.resolve(basePath);
+  const resolvedTarget = path.resolve(targetPath);
+  
+  // Ensure target starts with base (is inside base)
+  const normalizedBase = resolvedBase + path.sep;
+  return resolvedTarget === resolvedBase || 
+         resolvedTarget.startsWith(normalizedBase);
+}
+
+/**
+ * Create a secure temporary directory
+ * @param {string} prefix - Prefix for temp directory name
+ * @param {string} customBase - Custom base directory (default: os.tmpdir())
+ * @returns {Promise<string>} - Path to created temp directory
+ */
+async function createTempDir(prefix = 'gsd-', customBase = null) {
+  const baseDir = customBase || os.tmpdir();
+  const tempPath = await fs.promises.mkdtemp(path.join(baseDir, prefix));
+  
+  logger.debug(`Created temp directory: ${tempPath}`);
+  tempResources.add({ type: 'dir', path: tempPath });
+  
+  registerCleanup();
+  
+  return tempPath;
+}
+
+/**
+ * Create a secure temporary file
+ * @param {string} prefix - Prefix for temp file name
+ * @param {string} customBase - Custom base directory (default: os.tmpdir())
+ * @param {string} content - Optional initial content
+ * @returns {Promise<string>} - Path to created temp file
+ */
+async function createTempFile(prefix = 'gsd-', customBase = null, content = '') {
+  const baseDir = customBase || os.tmpdir();
+  const fileName = `${prefix}${generateSecureSuffix()}`;
+  const tempPath = path.join(baseDir, fileName);
+  
+  await fs.promises.writeFile(tempPath, content, 'utf-8');
+  
+  logger.debug(`Created temp file: ${tempPath}`);
+  tempResources.add({ type: 'file', path: tempPath });
+  
+  registerCleanup();
+  
+  return tempPath;
+}
+
+/**
+ * Write content to a temp file safely
+ * @param {string} tempPath - Path to temp file
+ * @param {string} content - Content to write
+ * @param {Object} options - Write options
+ */
+async function writeToTemp(tempPath, content, options = {}) {
+  const { validateBase = os.tmpdir() } = options;
+  
+  if (!isPathSafe(validateBase, tempPath)) {
+    throw new Error(`Path traversal detected: ${tempPath}`);
+  }
+  
+  await fs.promises.writeFile(tempPath, content, 'utf-8');
+  logger.debug(`Written to temp file: ${tempPath}`);
+}
+
+/**
+ * Read content from a temp file safely
+ * @param {string} tempPath - Path to temp file
+ * @param {Object} options - Read options
+ * @returns {Promise<string>} - File content
+ */
+async function readFromTemp(tempPath, options = {}) {
+  const { validateBase = os.tmpdir() } = options;
+  
+  if (!isPathSafe(validateBase, tempPath)) {
+    throw new Error(`Path traversal detected: ${tempPath}`);
+  }
+  
+  const content = await fs.promises.readFile(tempPath, 'utf-8');
+  logger.debug(`Read from temp file: ${tempPath}`);
+  
+  return content;
+}
+
+/**
+ * Clean up a specific temp resource
+ * @param {string} tempPath - Path to temp file or directory
+ */
+async function cleanupTemp(tempPath) {
+  const resolvedPath = path.resolve(tempPath);
+  
+  for (const resource of tempResources) {
+    if (path.resolve(resource.path) === resolvedPath) {
+      try {
+        if (resource.type === 'dir') {
+          await fs.promises.rm(resolvedPath, { recursive: true, force: true });
+          logger.debug(`Cleaned up temp directory: ${resolvedPath}`);
+        } else {
+          await fs.promises.unlink(resolvedPath);
+          logger.debug(`Cleaned up temp file: ${resolvedPath}`);
+        }
+        tempResources.delete(resource);
+      } catch (err) {
+        logger.warn(`Failed to cleanup temp: ${resolvedPath}`, { 
+          error: err.message 
+        });
+      }
+      break;
+    }
+  }
+}
+
+/**
+ * Clean up all tracked temp resources
+ */
+async function cleanupAll() {
+  logger.info(`Cleaning up ${tempResources.size} temp resources...`);
+  
+  const cleanupPromises = [];
+  for (const resource of tempResources) {
+    cleanupPromises.push(
+      cleanupTemp(resource.path).catch(err => {
+        logger.warn(`Cleanup failed for ${resource.path}: ${err.message}`);
+      })
+    );
+  }
+  
+  await Promise.all(cleanupPromises);
+  logger.info('Temp cleanup complete');
+}
+
+/**
+ * Register cleanup handlers (called automatically)
+ */
+function registerCleanup() {
+  if (cleanupRegistered) return;
+  cleanupRegistered = true;
+  
+  const cleanupHandler = async () => {
+    if (tempResources.size > 0) {
+      await cleanupAll();
+    }
+  };
+  
+  // Register for various exit scenarios
+  process.on('exit', () => {
+    // Synchronous cleanup for exit event
+    if (tempResources.size > 0) {
+      logger.debug('Synchronous temp cleanup on exit');
+    }
+  });
+  
+  process.on('SIGINT', async () => {
+    await cleanupHandler();
+    process.exit(130);
+  });
+  
+  process.on('SIGTERM', async () => {
+    await cleanupHandler();
+    process.exit(143);
+  });
+  
+  process.on('beforeExit', async () => {
+    await cleanupHandler();
+  });
+  
+  // Handle uncaught errors
+  process.on('uncaughtException', async (err) => {
+    logger.error('Uncaught exception, cleaning up temps...', { 
+      error: err.message 
+    });
+    await cleanupHandler();
+    process.exit(1);
+  });
+  
+  logger.debug('Temp cleanup handlers registered');
+}
+
+/**
+ * Get list of tracked temp resources
+ * @returns {Array} - Array of {type, path} objects
+ */
+function getTrackedTemps() {
+  return Array.from(tempResources);
+}
+
+module.exports = {
+  createTempDir,
+  createTempFile,
+  writeToTemp,
+  readFromTemp,
+  cleanupTemp,
+  cleanupAll,
+  getTrackedTemps,
+  isPathSafe,
+  generateSecureSuffix
+};

package/get-shit-done/bin/lib/template.cjs

@@ -0,0 +1,222 @@
+/**
+ * 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');
+
+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;
+  }
+
+  fs.writeFileSync(outPath, fullContent, 'utf-8');
+  const relPath = toPosixPath(path.relative(cwd, outPath));
+  output({ created: true, path: relPath, template: templateType }, raw, relPath);
+}
+
+module.exports = { cmdTemplateSelect, cmdTemplateFill };

package/get-shit-done/bin/lib/test-file-lock.cjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for GSD File Lock
+ * Run: node get-shit-done/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/get-shit-done/bin/lib/test-graceful.cjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for GSD Health Check and Timeout Exec
+ * Run: node get-shit-done/bin/lib/test-graceful.cjs
+ */
+
+const HealthCheck = require('./health-check.cjs');
+const { execWithTimeout } = require('./timeout-exec.cjs');
+
+console.log('='.repeat(50));
+console.log('Testing GSD 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));
+})();