@jaimevalasek/aioson 1.7.2 → 1.9.0

package/src/sub-task-state.js

@@ -0,0 +1,152 @@
+'use strict';
+
+// Sub-Task Scout — state file management
+//
+// `.aioson/runtime/scouts/.state.json` tracks per-session cap usage and
+// per-scout retry counters. Acquired via `.state.json.lock` (PID + ISO
+// timestamp; stale after 30s — single-user / single-machine V1).
+//
+// Pure helpers. CLI commands compose these around the engine's `enforceCaps`.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STATE_FILE_REL_DEFAULT = '.aioson/runtime/scouts/.state.json';
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_MS = 100;
+const LOCK_TIMEOUT_MS = 30_000;
+
+function statePath(rootDir, scoutDir) {
+  if (scoutDir) return path.join(rootDir, scoutDir, '.state.json');
+  return path.join(rootDir, STATE_FILE_REL_DEFAULT);
+}
+
+function lockPath(stateFilePath) {
+  return `${stateFilePath}.lock`;
+}
+
+function emptyState() {
+  return { schema_version: 1, sessions: {} };
+}
+
+function readState(stateFilePath) {
+  try {
+    const raw = fs.readFileSync(stateFilePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null) return emptyState();
+    if (!parsed.sessions || typeof parsed.sessions !== 'object') parsed.sessions = {};
+    return parsed;
+  } catch (err) {
+    if (err.code === 'ENOENT') return emptyState();
+    // Corrupt state — start fresh; CLI surface logs the issue.
+    return emptyState();
+  }
+}
+
+function writeState(stateFilePath, state) {
+  fs.mkdirSync(path.dirname(stateFilePath), { recursive: true });
+  fs.writeFileSync(stateFilePath, JSON.stringify(state, null, 2), 'utf8');
+}
+
+function isStale(lockContent) {
+  try {
+    const data = JSON.parse(lockContent);
+    if (typeof data.started_at !== 'string') return true;
+    const age = Date.now() - Date.parse(data.started_at);
+    return Number.isFinite(age) && age > LOCK_STALE_MS;
+  } catch {
+    return true; // unparseable lock → reclaim
+  }
+}
+
+function tryAcquire(lockFilePath) {
+  try {
+    const fd = fs.openSync(lockFilePath, 'wx');
+    fs.writeSync(fd, JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }));
+    fs.closeSync(fd);
+    return true;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    return false;
+  }
+}
+
+function reclaimIfStale(lockFilePath) {
+  let content;
+  try {
+    content = fs.readFileSync(lockFilePath, 'utf8');
+  } catch {
+    return false;
+  }
+  if (isStale(content)) {
+    try { fs.unlinkSync(lockFilePath); } catch { /* race lost — caller retries */ }
+    return true;
+  }
+  return false;
+}
+
+function sleepSync(ms) {
+  // crude busy-wait to keep the CLI surface synchronous; only used in lock
+  // contention which is rare (single-user). Bounded by LOCK_TIMEOUT_MS.
+  const end = Date.now() + ms;
+  while (Date.now() < end) { /* spin */ }
+}
+
+function acquireLock(stateFilePath) {
+  fs.mkdirSync(path.dirname(stateFilePath), { recursive: true });
+  const lock = lockPath(stateFilePath);
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (tryAcquire(lock)) return lock;
+    reclaimIfStale(lock);
+    sleepSync(LOCK_RETRY_MS);
+  }
+  const e = new Error(`scout state lock timeout (>${LOCK_TIMEOUT_MS}ms): ${lock}`);
+  e.code = 'lock_timeout';
+  throw e;
+}
+
+function releaseLock(lockFilePath) {
+  try { fs.unlinkSync(lockFilePath); } catch { /* lock may have been reclaimed */ }
+}
+
+// withLock: acquire → run sync mutator → write state → release. Returns the
+// mutator's return value. Callers stay short and obvious.
+function withLock(rootDir, scoutDir, mutator) {
+  const sf = statePath(rootDir, scoutDir);
+  const lock = acquireLock(sf);
+  try {
+    const state = readState(sf);
+    pruneOldSessions(state);
+    const result = mutator(state);
+    writeState(sf, state);
+    return result;
+  } finally {
+    releaseLock(lock);
+  }
+}
+
+function pruneOldSessions(state) {
+  const cutoff = Date.now() - 24 * 60 * 60 * 1000; // 24h
+  for (const [sid, session] of Object.entries(state.sessions || {})) {
+    const inFlight = (session.scouts_in_session || 0) > 0;
+    const startedAt = session.started_at ? Date.parse(session.started_at) : NaN;
+    if (!inFlight && Number.isFinite(startedAt) && startedAt < cutoff) {
+      delete state.sessions[sid];
+    }
+  }
+}
+
+module.exports = {
+  STATE_FILE_REL_DEFAULT,
+  LOCK_STALE_MS,
+  statePath,
+  lockPath,
+  emptyState,
+  readState,
+  writeState,
+  acquireLock,
+  releaseLock,
+  withLock,
+  pruneOldSessions
+};

package/src/sub-task-telemetry.js

@@ -0,0 +1,69 @@
+'use strict';
+
+// Sub-Task Scout — direct telemetry helper
+//
+// Bypasses `logAgentEvent`'s session-lifecycle layer to write `event_type='sub_task'`
+// rows directly into `agent_events`. Necessary for one-shot agents like
+// `feature-close` that fire exactly one sub_task event per invocation: their
+// FIRST event would otherwise land as `event_type='start'` (lifecycle artifact)
+// with `payload_json=null`, which `collectScoutSummary` cannot match.
+//
+// Closes M-01 from QA Gate D corrections plan.
+
+const { openRuntimeDb } = require('./runtime-store');
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+// emitSubTaskEvent — telemetry-only, never throws (matches existing
+// best-effort convention in scout commands).
+//
+// Writes one row to agent_events with:
+//   event_type   = 'sub_task'
+//   message      = options.message (string)
+//   payload_json = JSON.stringify(options.payload || {})
+//   run_key      = `sub-task-${options.parent_session_id || 'orphan'}`
+//                  (sentinel; agent_events.run_key is NOT NULL but no FK)
+// Sentinel agent_run for sub-task events. agent_events has a FOREIGN KEY on
+// run_key → agent_runs(run_key); we maintain a single anchor row so direct
+// sub_task inserts don't violate the constraint without needing per-event
+// session scaffolding.
+const SUB_TASK_RUN_KEY = 'sub-task-scout-anchor';
+
+function ensureSubTaskAnchorRun(db) {
+  const now = nowIso();
+  db.prepare(`
+    INSERT OR IGNORE INTO agent_runs
+      (run_key, agent_name, agent_kind, source, status, started_at, updated_at)
+    VALUES (?, 'sub-task-scout', 'official', 'direct', 'running', ?, ?)
+  `).run(SUB_TASK_RUN_KEY, now, now);
+}
+
+async function emitSubTaskEvent(rootPath, options = {}) {
+  const message = String(options.message || '');
+  const payload = options.payload || {};
+  const createdAt = nowIso();
+
+  let handle;
+  try {
+    handle = await openRuntimeDb(rootPath);
+  } catch {
+    return; // best-effort
+  }
+  if (!handle || !handle.db) return;
+
+  try {
+    ensureSubTaskAnchorRun(handle.db);
+    handle.db.prepare(`
+      INSERT INTO agent_events (run_key, event_type, message, payload_json, created_at)
+      VALUES (?, 'sub_task', ?, ?, ?)
+    `).run(SUB_TASK_RUN_KEY, message, JSON.stringify(payload), createdAt);
+  } catch {
+    // best-effort
+  } finally {
+    try { handle.db.close(); } catch { /* ignore */ }
+  }
+}
+
+module.exports = { emitSubTaskEvent };

package/src/test-briefing.js

@@ -0,0 +1,226 @@
+'use strict';
+
+/**
+ * test-briefing — auto-generate test context for @qa and @tester agents.
+ *
+ * Reduces friction from:
+ *   - wrong UI text assertions (mock strings, button labels)
+ *   - mock ordering bugs
+ *   - incorrect test patterns
+ *
+ * Scans the project for:
+ *   - existing test helpers / mock factories
+ *   - recent test files to use as templates
+ *   - UI text strings from components referenced in the spec
+ */
+
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const { readFileSafe, fileExists } = require('./preflight-engine');
+
+const MAX_MOCK_FILES = 5;
+const MAX_COMPONENT_FILES = 8;
+const MAX_TEST_FILES = 4;
+
+async function findFiles(targetDir, patterns, maxDepth = 4) {
+  const found = [];
+  async function walk(dir, depth) {
+    if (depth > maxDepth || found.length >= patterns.max) return;
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build' || entry.name === '.aioson') continue;
+        await walk(full, depth + 1);
+      } else if (patterns.test(entry.name)) {
+        found.push(full);
+        if (found.length >= patterns.max) return;
+      }
+    }
+  }
+  await walk(targetDir, 0);
+  return found;
+}
+
+async function findMockHelpers(targetDir) {
+  // Look for common mock/helper patterns
+  const candidates = [
+    path.join(targetDir, 'tests', 'helpers', 'mocks.ts'),
+    path.join(targetDir, 'tests', 'helpers', 'mocks.js'),
+    path.join(targetDir, 'test', 'helpers', 'mocks.ts'),
+    path.join(targetDir, 'test', 'helpers', 'mocks.js'),
+    path.join(targetDir, 'src', '__mocks__', 'index.ts'),
+    path.join(targetDir, 'src', '__mocks__', 'index.js'),
+    path.join(targetDir, '__mocks__', 'index.ts'),
+    path.join(targetDir, '__mocks__', 'index.js'),
+  ];
+  const found = [];
+  for (const p of candidates) {
+    if (await fileExists(p)) found.push(p);
+  }
+  return found;
+}
+
+async function findRecentTestFiles(targetDir) {
+  const files = await findFiles(targetDir, {
+    test: (name) => /\.(test|spec)\.(js|jsx|ts|tsx)$/.test(name),
+    max: 20
+  });
+  // Sort by mtime descending, keep top N
+  const withStat = [];
+  for (const f of files) {
+    try {
+      const stat = await fs.stat(f);
+      withStat.push({ path: f, mtime: stat.mtime });
+    } catch { /* ignore */ }
+  }
+  withStat.sort((a, b) => b.mtime - a.mtime);
+  return withStat.slice(0, MAX_TEST_FILES).map((x) => x.path);
+}
+
+async function findComponentFiles(targetDir) {
+  // Heuristic: look in src/ for .tsx/.jsx files that are not tests
+  const files = await findFiles(path.join(targetDir, 'src'), {
+    test: (name) => /\.(tsx|jsx)$/.test(name) && !/(test|spec)\./.test(name),
+    max: 30
+  });
+  // Prefer files modified recently (likely part of the current feature)
+  const withStat = [];
+  for (const f of files) {
+    try {
+      const stat = await fs.stat(f);
+      withStat.push({ path: f, mtime: stat.mtime });
+    } catch { /* ignore */ }
+  }
+  withStat.sort((a, b) => b.mtime - a.mtime);
+  return withStat.slice(0, MAX_COMPONENT_FILES).map((x) => x.path);
+}
+
+function extractUiStrings(content) {
+  // Extract text inside JSX/TSX that looks user-facing
+  // Pattern 1: string literals inside tags > "text" or {'text'}
+  const strings = [];
+  const tagTextRe = />([^<>{}]{2,80})</g;
+  let m;
+  while ((m = tagTextRe.exec(content)) !== null) {
+    const text = m[1].trim();
+    if (text && !text.startsWith('{') && !text.endsWith('}')) {
+      strings.push(text);
+    }
+  }
+  // Pattern 2: placeholder="..." label="..." title="..." aria-label="..."
+  const attrRe = /(?:placeholder|label|title|aria-label|aria-labelledby|alt|helperText|errorText)\s*=\s*["']([^"']{1,80})["']/g;
+  while ((m = attrRe.exec(content)) !== null) {
+    strings.push(m[1].trim());
+  }
+  // Deduplicate and limit
+  return [...new Set(strings)].slice(0, 40);
+}
+
+function extractMockPatterns(content) {
+  const patterns = [];
+  // Look for vi.mock / vi.fn / jest.mock / jest.fn patterns
+  const mockRe = /^(?:\s*)(vi|jest)\.(mock|fn)\s*\(/gm;
+  let m;
+  while ((m = mockRe.exec(content)) !== null) {
+    const lineStart = content.lastIndexOf('\n', m.index) + 1;
+    const lineEnd = content.indexOf('\n', m.index);
+    const line = content.slice(lineStart, lineEnd === -1 ? undefined : lineEnd).trim();
+    patterns.push(line);
+  }
+  return patterns.slice(0, 20);
+}
+
+async function buildTestBriefing(targetDir) {
+  const lines = [];
+  lines.push('## Auto-generated Test Context (motor do AIOSON)');
+  lines.push('');
+
+  // 1. Mock helpers
+  const mockHelpers = await findMockHelpers(targetDir);
+  if (mockHelpers.length > 0) {
+    lines.push('### Shared mock helpers found');
+    for (const p of mockHelpers) {
+      const rel = path.relative(targetDir, p);
+      lines.push(`- ${rel}`);
+    }
+    lines.push('> Use these helpers instead of writing ad-hoc mocks. This prevents ordering bugs.');
+    lines.push('');
+  }
+
+  // 2. Recent test templates
+  const recentTests = await findRecentTestFiles(targetDir);
+  if (recentTests.length > 0) {
+    lines.push('### Recent test files (use as templates for patterns)');
+    for (const p of recentTests) {
+      const rel = path.relative(targetDir, p);
+      lines.push(`- ${rel}`);
+    }
+    lines.push('> Reference these files for mock ordering, assertion style, and helpers before writing new tests.');
+    lines.push('');
+  }
+
+  // 3. Mock patterns from recent tests
+  if (recentTests.length > 0) {
+    const mockPatterns = [];
+    for (const p of recentTests.slice(0, 2)) {
+      const content = await readFileSafe(p);
+      if (content) {
+        mockPatterns.push(...extractMockPatterns(content));
+      }
+    }
+    if (mockPatterns.length > 0) {
+      lines.push('### Common mock patterns in this project');
+      for (const pat of [...new Set(mockPatterns)].slice(0, 10)) {
+        lines.push(`- \`${pat}\``);
+      }
+      lines.push('');
+    }
+  }
+
+  // 4. UI text strings from recent components
+  const components = await findComponentFiles(targetDir);
+  if (components.length > 0) {
+    const allStrings = [];
+    for (const p of components) {
+      const content = await readFileSafe(p);
+      if (content) {
+        const strings = extractUiStrings(content);
+        if (strings.length > 0) {
+          allStrings.push({ file: path.relative(targetDir, p), strings });
+        }
+      }
+    }
+    if (allStrings.length > 0) {
+      lines.push('### UI text strings from recent components');
+      lines.push('> Verify exact strings before using them in assertions. Prefer `getByRole` over `getByText` when possible.');
+      for (const item of allStrings.slice(0, MAX_COMPONENT_FILES)) {
+        lines.push(`\n**${item.file}:**`);
+        for (const s of item.strings.slice(0, 12)) {
+          lines.push(`- "${s}"`);
+        }
+      }
+      lines.push('');
+    }
+  }
+
+  // 5. Testing conventions reminder
+  lines.push('### Testing conventions');
+  lines.push('- Verify exact UI text strings against component source before using them in assertions.');
+  lines.push('- Use `getByRole` over `getByText` when possible.');
+  lines.push('- If using `vi.mock`, ensure deterministic ordering (mock factories > mock implementations).');
+  lines.push('- Reference existing test files as templates for assertion style and helper usage.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  buildTestBriefing
+};

package/src/tool-executor.js

@@ -1,94 +1,94 @@
-'use strict';
-
-const { spawnSync } = require('node:child_process');
-const path = require('node:path');
-
-const SAFE_ENV_KEYS = new Set(['PATH', 'HOME', 'LANG', 'TERM', 'USER', 'SHELL', 'TMPDIR', 'TMP', 'TEMP']);
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-function buildSafeEnv(inputJson) {
-  const safe = {};
-  for (const key of SAFE_ENV_KEYS) {
-    if (process.env[key] !== undefined) {
-      safe[key] = process.env[key];
-    }
-  }
-  safe.TOOL_INPUT = typeof inputJson === 'string' ? inputJson : JSON.stringify(inputJson ?? {});
-  return safe;
-}
-
-/**
- * Executa uma dynamic tool de forma segura via subprocess.
- * @param {object} toolDef - Registro da tool (da tabela dynamic_tools)
- * @param {object|string} inputJson - Input para a tool
- * @param {object} opts
- * @param {string} [opts.projectDir] - Diretório do projeto (para resolver caminhos relativos)
- * @param {number} [opts.timeoutMs] - Timeout em ms (default: 30s)
- * @returns {{ ok: boolean, stdout: string, stderr: string, exitCode: number, error?: string }}
- */
-function executeTool(toolDef, inputJson, opts = {}) {
-  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
-  const projectDir = opts.projectDir || process.cwd();
-  const safeEnv = buildSafeEnv(inputJson);
-
-  let result;
-
-  if (toolDef.handler_type === 'shell') {
-    if (!toolDef.handler_code) {
-      return { ok: false, stdout: '', stderr: '', exitCode: 1, error: 'handler_code is required for shell tools' };
-    }
-    result = spawnSync('bash', ['-c', toolDef.handler_code], {
-      env: safeEnv,
-      encoding: 'utf8',
-      timeout: timeoutMs,
-      maxBuffer: 1024 * 1024
-    });
-  } else if (toolDef.handler_type === 'script') {
-    if (!toolDef.handler_path) {
-      return { ok: false, stdout: '', stderr: '', exitCode: 1, error: 'handler_path is required for script tools' };
-    }
-    const scriptPath = path.isAbsolute(toolDef.handler_path)
-      ? toolDef.handler_path
-      : path.resolve(projectDir, toolDef.handler_path);
-
-    result = spawnSync('node', ['--env-file=', scriptPath], {
-      env: safeEnv,
-      encoding: 'utf8',
-      timeout: timeoutMs,
-      maxBuffer: 1024 * 1024,
-      input: safeEnv.TOOL_INPUT
-    });
-
-    // Fallback: node sem --env-file= (versões antigas do Node não suportam)
-    if (result.error && result.error.code === 'ERR_INVALID_ARG_VALUE') {
-      result = spawnSync('node', [scriptPath], {
-        env: safeEnv,
-        encoding: 'utf8',
-        timeout: timeoutMs,
-        maxBuffer: 1024 * 1024,
-        input: safeEnv.TOOL_INPUT
-      });
-    }
-  } else {
-    return { ok: false, stdout: '', stderr: '', exitCode: 1, error: `Unknown handler_type: ${toolDef.handler_type}` };
-  }
-
-  const stdout = String(result.stdout || '').trim();
-  const stderr = String(result.stderr || '').trim();
-  const exitCode = result.status ?? 1;
-
-  if (result.error) {
-    const isTimeout = result.error.code === 'ETIMEDOUT' || result.error.killed;
-    return {
-      ok: false,
-      stdout,
-      stderr,
-      exitCode,
-      error: isTimeout ? `Tool timed out after ${timeoutMs}ms` : result.error.message
-    };
-  }
-
-  return { ok: exitCode === 0, stdout, stderr, exitCode };
-}
-
-module.exports = { executeTool, buildSafeEnv };
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const SAFE_ENV_KEYS = new Set(['PATH', 'HOME', 'LANG', 'TERM', 'USER', 'SHELL', 'TMPDIR', 'TMP', 'TEMP']);
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+function buildSafeEnv(inputJson) {
+  const safe = {};
+  for (const key of SAFE_ENV_KEYS) {
+    if (process.env[key] !== undefined) {
+      safe[key] = process.env[key];
+    }
+  }
+  safe.TOOL_INPUT = typeof inputJson === 'string' ? inputJson : JSON.stringify(inputJson ?? {});
+  return safe;
+}
+
+/**
+ * Executa uma dynamic tool de forma segura via subprocess.
+ * @param {object} toolDef - Registro da tool (da tabela dynamic_tools)
+ * @param {object|string} inputJson - Input para a tool
+ * @param {object} opts
+ * @param {string} [opts.projectDir] - Diretório do projeto (para resolver caminhos relativos)
+ * @param {number} [opts.timeoutMs] - Timeout em ms (default: 30s)
+ * @returns {{ ok: boolean, stdout: string, stderr: string, exitCode: number, error?: string }}
+ */
+function executeTool(toolDef, inputJson, opts = {}) {
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const projectDir = opts.projectDir || process.cwd();
+  const safeEnv = buildSafeEnv(inputJson);
+
+  let result;
+
+  if (toolDef.handler_type === 'shell') {
+    if (!toolDef.handler_code) {
+      return { ok: false, stdout: '', stderr: '', exitCode: 1, error: 'handler_code is required for shell tools' };
+    }
+    result = spawnSync('bash', ['-c', toolDef.handler_code], {
+      env: safeEnv,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer: 1024 * 1024
+    });
+  } else if (toolDef.handler_type === 'script') {
+    if (!toolDef.handler_path) {
+      return { ok: false, stdout: '', stderr: '', exitCode: 1, error: 'handler_path is required for script tools' };
+    }
+    const scriptPath = path.isAbsolute(toolDef.handler_path)
+      ? toolDef.handler_path
+      : path.resolve(projectDir, toolDef.handler_path);
+
+    result = spawnSync('node', ['--env-file=', scriptPath], {
+      env: safeEnv,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer: 1024 * 1024,
+      input: safeEnv.TOOL_INPUT
+    });
+
+    // Fallback: node sem --env-file= (versões antigas do Node não suportam)
+    if (result.error && result.error.code === 'ERR_INVALID_ARG_VALUE') {
+      result = spawnSync('node', [scriptPath], {
+        env: safeEnv,
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        maxBuffer: 1024 * 1024,
+        input: safeEnv.TOOL_INPUT
+      });
+    }
+  } else {
+    return { ok: false, stdout: '', stderr: '', exitCode: 1, error: `Unknown handler_type: ${toolDef.handler_type}` };
+  }
+
+  const stdout = String(result.stdout || '').trim();
+  const stderr = String(result.stderr || '').trim();
+  const exitCode = result.status ?? 1;
+
+  if (result.error) {
+    const isTimeout = result.error.code === 'ETIMEDOUT' || result.error.killed;
+    return {
+      ok: false,
+      stdout,
+      stderr,
+      exitCode,
+      error: isTimeout ? `Tool timed out after ${timeoutMs}ms` : result.error.message
+    };
+  }
+
+  return { ok: exitCode === 0, stdout, stderr, exitCode };
+}
+
+module.exports = { executeTool, buildSafeEnv };