@jaimevalasek/aioson 1.5.1 → 1.7.0

package/src/squad/verify-gate.js

@@ -0,0 +1,303 @@
+'use strict';
+
+/**
+ * Squad 4-tier verification gate
+ *
+ * Verifies task deliverables beyond pass/fail:
+ *
+ *   Tier 1 — Exists:       File/path exists on disk
+ *   Tier 2 — Substantive:  Not a stub/placeholder (min lines + anti-pattern scan)
+ *   Tier 3 — Wired:        Referenced/imported in expected target location
+ *   Tier 4 — Functional:   Smoke command returns expected output (opt-in, expensive)
+ *
+ * Used by reflection.js when a task has a `must_haves` contract.
+ */
+
+const fs = require('node:fs/promises');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execFileAsync = promisify(execFile);
+
+// Patterns that indicate a file is a stub, not real implementation
+const ANTI_PATTERNS = [
+  { pattern: /\bTODO\b/,                              label: 'TODO marker'           },
+  { pattern: /\bFIXME\b/,                             label: 'FIXME marker'          },
+  { pattern: /\bplaceholder\b/i,                      label: 'placeholder text'      },
+  { pattern: /not\s+implemented/i,                    label: '"not implemented"'     },
+  { pattern: /return\s+null;\s*\n?\s*\}/m,            label: 'empty return null'     },
+  { pattern: /throw\s+new\s+Error\s*\(['"]not\s+impl/i, label: 'NotImplemented throw' },
+  { pattern: /^\s*pass\s*$/m,                         label: 'Python stub (pass)'    },
+  { pattern: /^\s*\.\.\.\s*$/m,                       label: 'ellipsis stub'         }
+];
+
+// ─── Artifact string parser ───────────────────────────────────────────────────
+
+/**
+ * Parse an artifact descriptor string into structured fields.
+ *
+ * Examples:
+ *   "src/routes/auth.ts"
+ *   "src/routes/auth.ts (>50 lines)"
+ *   "src/routes/auth.ts (>50 lines, exports router)"
+ *
+ * Returns: { filePath, minLines, wiredPattern }
+ */
+function parseArtifact(str, projectDir) {
+  const s = String(str).trim();
+
+  // Extract optional annotations in parentheses
+  const parenMatch = s.match(/^(.+?)\s*\(([^)]*)\)\s*$/);
+  const rawPath = parenMatch ? parenMatch[1].trim() : s;
+  const annotations = parenMatch ? parenMatch[2] : '';
+
+  // Build absolute path (relative to projectDir if given)
+  const filePath = projectDir
+    ? require('node:path').resolve(projectDir, rawPath)
+    : rawPath;
+
+  // Parse min lines: ">50 lines" or "50 lines"
+  const linesMatch = annotations.match(/>?\s*(\d+)\s+lines?/i);
+  const minLines = linesMatch ? parseInt(linesMatch[1], 10) : 5;
+
+  // Parse wired pattern: any text after "exports" or "imports" or "registers"
+  const wiredMatch = annotations.match(/(?:exports?|imports?|registers?)\s+(.+)/i);
+  const wiredPattern = wiredMatch ? wiredMatch[1].trim() : null;
+
+  return { filePath, rawPath, minLines, wiredPattern };
+}
+
+/**
+ * Parse a key_link descriptor string.
+ *
+ * Example: "auth router registered in src/app.ts"
+ * Returns: { pattern, inFile }
+ *
+ * Pattern is extracted heuristically from the string.
+ */
+function parseKeyLink(str, projectDir) {
+  const path = require('node:path');
+  const s = String(str).trim();
+
+  // Pattern: "<thing> in <filepath>" or "<thing> registered/imported/used in <filepath>"
+  const inMatch = s.match(/^(.+?)\s+(?:in|from|inside)\s+(\S+\.(?:ts|js|tsx|jsx|py|rb|go|java|php|vue|svelte))\s*$/i);
+  if (inMatch) {
+    const rawFile = inMatch[2].trim();
+    const inFile = projectDir ? path.resolve(projectDir, rawFile) : rawFile;
+
+    // Extract meaningful keywords from the pattern part (first 3 significant words)
+    const patternWords = inMatch[1]
+      .replace(/\b(?:registered|imported|used|exported|referenced|wired|connected|added)\b/gi, '')
+      .trim()
+      .split(/\s+/)
+      .filter((w) => w.length > 2)
+      .slice(0, 3);
+
+    return { pattern: patternWords.join('|'), inFile, rawFile };
+  }
+
+  return null;
+}
+
+// ─── Tier implementations ─────────────────────────────────────────────────────
+
+/** Tier 1: file exists on disk */
+async function verifyExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return { passed: true, tier: 1, file: filePath };
+  } catch {
+    return { passed: false, tier: 1, file: filePath, reason: 'file does not exist' };
+  }
+}
+
+/** Tier 2: file is substantive (not a stub) */
+async function verifySubstantive(filePath, minLines = 5) {
+  let content;
+  try {
+    content = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return { passed: false, tier: 2, file: filePath, reason: 'cannot read file' };
+  }
+
+  const nonEmptyLines = content.split('\n').filter((l) => l.trim().length > 0).length;
+  if (nonEmptyLines < minLines) {
+    return {
+      passed: false, tier: 2, file: filePath,
+      reason: `only ${nonEmptyLines} non-empty lines (min: ${minLines})`
+    };
+  }
+
+  for (const { pattern, label } of ANTI_PATTERNS) {
+    if (pattern.test(content)) {
+      return { passed: false, tier: 2, file: filePath, reason: `contains ${label}` };
+    }
+  }
+
+  return { passed: true, tier: 2, file: filePath, lines: nonEmptyLines };
+}
+
+/** Tier 3: pattern found in a target file (wired/imported/registered) */
+async function verifyWired(pattern, inFile) {
+  if (!pattern || !inFile) {
+    return { passed: true, tier: 3, skipped: true, reason: 'no wired constraint to check' };
+  }
+
+  let content;
+  try {
+    content = await fs.readFile(inFile, 'utf8');
+  } catch {
+    return { passed: false, tier: 3, file: inFile, reason: `cannot read target file: ${inFile}` };
+  }
+
+  const regex = typeof pattern === 'string'
+    ? new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')
+    : pattern;
+
+  if (regex.test(content)) {
+    return { passed: true, tier: 3, pattern, inFile };
+  }
+
+  return {
+    passed: false, tier: 3, pattern, inFile,
+    reason: `pattern "${pattern}" not found in ${inFile}`
+  };
+}
+
+/** Tier 4: smoke command returns expected output (optional, expensive) */
+async function verifyFunctional(command, args = [], expectedPattern = null, timeoutMs = 10_000) {
+  try {
+    const { stdout, stderr } = await execFileAsync(command, args, {
+      timeout: timeoutMs,
+      shell: false
+    });
+    const output = stdout + stderr;
+
+    if (expectedPattern) {
+      const regex = typeof expectedPattern === 'string'
+        ? new RegExp(expectedPattern, 'i')
+        : expectedPattern;
+      if (!regex.test(output)) {
+        return {
+          passed: false, tier: 4, command,
+          reason: `expected pattern "${expectedPattern}" not found in command output`
+        };
+      }
+    }
+
+    return { passed: true, tier: 4, command, output: output.slice(0, 300) };
+  } catch (err) {
+    return { passed: false, tier: 4, command, reason: err.message.slice(0, 200) };
+  }
+}
+
+// ─── must_haves checker ───────────────────────────────────────────────────────
+
+/**
+ * Run must_haves verification against a task's contract.
+ *
+ * @param {object} mustHaves   — { truths?, artifacts?, key_links? }
+ * @param {string} output      — Task output text (used for truths checks)
+ * @param {string} projectDir
+ * @returns {Promise<MustHavesResult>}
+ *
+ * MustHavesResult:
+ *   {
+ *     passed: boolean,
+ *     failures: string[],
+ *     warnings: string[],
+ *     details: object[]
+ *   }
+ */
+async function checkMustHaves(mustHaves, output, projectDir) {
+  if (!mustHaves) return { passed: true, failures: [], warnings: [], details: [] };
+
+  const failures = [];
+  const warnings = [];
+  const details = [];
+  const outputText = String(output || '').toLowerCase();
+
+  // ── Truths: heuristic — check if output mentions the expected state ──────
+  for (const truth of (mustHaves.truths || [])) {
+    // Extract key nouns/verbs from truth statement and check they appear in output
+    const keywords = String(truth)
+      .replace(/\b(?:the|a|an|is|are|can|will|should|must|to|of|in|and|or|that)\b/gi, '')
+      .split(/\s+/)
+      .filter((w) => w.length > 3)
+      .slice(0, 4);
+
+    const found = keywords.some((kw) => outputText.includes(kw.toLowerCase()));
+    const result = { type: 'truth', statement: truth, passed: found };
+    details.push(result);
+
+    if (!found) {
+      warnings.push(`Truth not evident in output: "${truth.slice(0, 80)}"`);
+    }
+  }
+
+  // ── Artifacts: Tier 1 + Tier 2 checks ────────────────────────────────────
+  for (const artifactStr of (mustHaves.artifacts || [])) {
+    const { filePath, rawPath, minLines, wiredPattern } = parseArtifact(artifactStr, projectDir);
+
+    const t1 = await verifyExists(filePath);
+    details.push({ type: 'artifact', descriptor: artifactStr, ...t1 });
+
+    if (!t1.passed) {
+      failures.push(`Artifact missing: ${rawPath}`);
+      continue;
+    }
+
+    const t2 = await verifySubstantive(filePath, minLines);
+    details.push({ type: 'artifact_substantive', descriptor: artifactStr, ...t2 });
+
+    if (!t2.passed) {
+      failures.push(`Artifact is a stub: ${rawPath} — ${t2.reason}`);
+      continue;
+    }
+
+    // If wired pattern specified, verify it exists in the same file
+    if (wiredPattern) {
+      const t3 = await verifyWired(wiredPattern, filePath);
+      details.push({ type: 'artifact_wired', descriptor: artifactStr, ...t3 });
+      if (!t3.passed) {
+        warnings.push(`Artifact wiring issue: ${rawPath} — ${t3.reason}`);
+      }
+    }
+  }
+
+  // ── Key links: Tier 3 checks ──────────────────────────────────────────────
+  for (const keyLink of (mustHaves.key_links || [])) {
+    const parsed = parseKeyLink(keyLink, projectDir);
+
+    if (!parsed) {
+      // Cannot parse — skip silently (heuristic limitation)
+      details.push({ type: 'key_link', descriptor: keyLink, passed: true, skipped: true });
+      continue;
+    }
+
+    const t3 = await verifyWired(parsed.pattern, parsed.inFile);
+    details.push({ type: 'key_link', descriptor: keyLink, ...t3 });
+
+    if (!t3.passed) {
+      warnings.push(`Key link not wired: "${keyLink.slice(0, 80)}" — ${t3.reason}`);
+    }
+  }
+
+  return {
+    passed: failures.length === 0,
+    failures,
+    warnings,
+    details
+  };
+}
+
+module.exports = {
+  verifyExists,
+  verifySubstantive,
+  verifyWired,
+  verifyFunctional,
+  checkMustHaves,
+  parseArtifact,
+  parseKeyLink,
+  ANTI_PATTERNS
+};

package/src/tool-executor.js

@@ -0,0 +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 };

package/src/updater.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const path = require('node:path');
-const { detectExistingInstall, installTemplate } = require('./installer');
+const { detectExistingInstall, installTemplate, readInstallProfile } = require('./installer');
 
 async function updateInstallation(targetDir, options = {}) {
   const installed = await detectExistingInstall(targetDir);
@@ -13,17 +13,24 @@ async function updateInstallation(targetDir, options = {}) {
     };
   }
 
+  const savedProfile = await readInstallProfile(targetDir);
+
+  // Default: only update files already present in the target (selective update).
+  // With --all: install every file from the template, including new ones not yet installed.
   const result = await installTemplate(targetDir, {
     overwrite: true,
     dryRun: Boolean(options.dryRun),
     mode: 'update',
     backupOnOverwrite: true,
-    frameworkDetection: options.frameworkDetection || null
+    frameworkDetection: options.frameworkDetection || null,
+    installProfile: null,
+    selectiveUpdate: !options.all
   });
 
   return {
     ok: true,
-    ...result
+    ...result,
+    savedProfile
   };
 }
 

package/src/worker-runner.js

@@ -123,12 +123,188 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// ─── Research Worker ──────────────────────────────────────────────────────────
+
+/**
+ * Handle a `type: 'research'` worker.
+ *
+ * Checks the researchs/ cache first (7-day default TTL), falls back to
+ * scraping declared URLs or the topic keyword via web.js fetchPage.
+ *
+ * Cache location: researchs/{topic}/summary.md
+ */
+async function runResearchWorker(projectDir, config, inputPayload) {
+  const { fetchPage } = require('./web');
+  const research = config.research || {};
+  const topic = String(research.topic || inputPayload?.topic || 'general').replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+  const cacheHours = Number(research.cache_hours || 168); // 7 days default
+  const cacheDir = path.join(projectDir, research.cache_dir || 'researchs', topic);
+  const summaryPath = path.join(cacheDir, 'summary.md');
+
+  // ── Cache check ────────────────────────────────────────────────────────────
+  try {
+    const stat = await fs.stat(summaryPath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    const ageHours = ageMs / (1000 * 60 * 60);
+    if (ageHours < cacheHours) {
+      const cached = await fs.readFile(summaryPath, 'utf8');
+      return {
+        ok: true,
+        output: { topic, summary: cached, cached: true, cache_age_hours: Math.round(ageHours) },
+        attempt: 1
+      };
+    }
+  } catch { /* no cache yet */ }
+
+  // ── Scrape sources ─────────────────────────────────────────────────────────
+  const urls = research.urls || inputPayload?.urls || [];
+  const maxSources = Number(research.max_sources || 5);
+  const pages = [];
+
+  for (const url of urls.slice(0, maxSources)) {
+    try {
+      const result = await fetchPage(url, { timeoutMs: 15000, extractLinks: false });
+      if (result.ok && result.text) {
+        pages.push({ url, content: result.text.slice(0, 3000) });
+      }
+    } catch { /* skip unreachable sources */ }
+  }
+
+  if (pages.length === 0) {
+    return {
+      ok: false,
+      error: `Research worker "${topic}": no URLs declared and no cached summary. Add "research.urls" to worker.json or provide ?topic= with cached data.`,
+      attempts: 1
+    };
+  }
+
+  // ── Build summary ──────────────────────────────────────────────────────────
+  const ts = new Date().toISOString();
+  const summary = [
+    `# Research: ${topic}`,
+    `_Generated: ${ts} · Sources: ${pages.length}_`,
+    '',
+    ...pages.map((p, i) => [
+      `## Source ${i + 1}: ${p.url}`,
+      '',
+      p.content.slice(0, 2000),
+      ''
+    ].join('\n'))
+  ].join('\n');
+
+  await fs.mkdir(cacheDir, { recursive: true });
+  await fs.writeFile(summaryPath, summary, 'utf8');
+
+  return {
+    ok: true,
+    output: { topic, summary, cached: false, sources: pages.length, generated_at: ts },
+    attempt: 1
+  };
+}
+
+// ─── Skill Worker (Plan 81 §2.2) ─────────────────────────────────────────────
+
+/**
+ * Handle a `type: 'skill'` worker.
+ * Resolves an external Agent Skills Standard skill and executes it.
+ *
+ * Skill sources:
+ *   - Local path: ./skills/my-skill/ or .claude/skills/my-skill/
+ *   - NPM package: npm:@org/skill-name (resolved from node_modules)
+ */
+async function runSkillWorker(projectDir, config, inputPayload) {
+  const skillRef = config.skill || config.source || '';
+  let skillDir;
+
+  if (skillRef.startsWith('npm:')) {
+    // Resolve from node_modules
+    const pkgName = skillRef.slice(4);
+    skillDir = path.join(projectDir, 'node_modules', pkgName);
+  } else {
+    // Local path
+    skillDir = path.resolve(projectDir, skillRef);
+  }
+
+  // Check SKILL.md exists
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  if (!(await pathExists(skillMdPath))) {
+    return {
+      ok: false,
+      error: `Skill not found: ${skillRef} (expected SKILL.md at ${skillMdPath})`,
+      attempts: 0
+    };
+  }
+
+  // Check for executable scripts
+  const scriptsDir = path.join(skillDir, 'scripts');
+  const runScript = path.join(scriptsDir, 'run.js');
+  const runPyScript = path.join(scriptsDir, 'run.py');
+
+  if (await pathExists(runScript)) {
+    return spawnWorker(runScript, inputPayload || {}, {}, config.timeout_ms || DEFAULT_TIMEOUT);
+  }
+
+  if (await pathExists(runPyScript)) {
+    return spawnWorker(runPyScript, inputPayload || {}, {}, config.timeout_ms || DEFAULT_TIMEOUT);
+  }
+
+  // No executable script — return skill content for LLM-based execution
+  const skillContent = await fs.readFile(skillMdPath, 'utf8');
+  return {
+    ok: true,
+    output: {
+      type: 'skill-prompt',
+      skillPath: skillMdPath,
+      content: skillContent.slice(0, 4000),
+      message: `Skill "${skillRef}" loaded. No run script found — use skill content as agent instructions.`
+    },
+    attempt: 1
+  };
+}
+
+// ─── Agent Memory Loader (Plan 81 §Sprint 4) ────────────────────────────────
+
+/**
+ * Load per-agent persistent memory if it exists.
+ * Returns memory content or null.
+ */
+async function loadAgentMemory(projectDir, squadSlug, executorSlug) {
+  const memoryPath = path.join(
+    projectDir, SQUADS_DIR, squadSlug, 'agent-memory', `${executorSlug}.md`
+  );
+  try {
+    return await fs.readFile(memoryPath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
 async function runWorker(projectDir, squadSlug, workerSlug, inputPayload, options = {}) {
   const config = await loadWorkerConfig(projectDir, squadSlug, workerSlug);
   if (!config) {
     return { ok: false, error: `Worker config not found: ${workerSlug}`, attempts: 0 };
   }
 
+  // Skill worker — external skill execution (Plan 81 §2.2)
+  if (config.type === 'skill') {
+    return runSkillWorker(projectDir, config, inputPayload || {});
+  }
+
+  // Research worker — special handler (4.1)
+  if (config.type === 'research') {
+    return runResearchWorker(projectDir, config, inputPayload || {});
+  }
+
+  // Load per-agent persistent memory (Plan 81 §Sprint 4)
+  const agentMemory = await loadAgentMemory(projectDir, squadSlug, workerSlug);
+  if (agentMemory && inputPayload) {
+    // Inject into _agent_memory field (readable by Node.js workers via process.argv[2])
+    inputPayload._agent_memory = agentMemory;
+    // Prefix into context so LLM-based workers receive it as part of their task context
+    const existingContext = inputPayload.context || '';
+    inputPayload.context = `## Your accumulated knowledge:\n${agentMemory}\n\n---\n\n${existingContext}`.trimEnd();
+  }
+
   // Validate inputs
   const validation = validateInputs(inputPayload || {}, config.inputs);
   if (!validation.valid) {
@@ -149,6 +325,13 @@ async function runWorker(projectDir, squadSlug, workerSlug, inputPayload, option
   // Resolve env vars
   const env = resolveEnvVars(config.env);
 
+  // Expose agent memory path as env var so workers can read it directly
+  const memoryFilePath = path.join(projectDir, SQUADS_DIR, squadSlug, 'agent-memory', `${workerSlug}.md`);
+  try {
+    await fs.access(memoryFilePath);
+    env.AIOSON_AGENT_MEMORY_PATH = memoryFilePath;
+  } catch { /* no memory file yet — env var omitted */ }
+
   // Resolve MCP env vars if worker declares uses_mcp
   if (config.uses_mcp && config.uses_mcp.length > 0) {
     try {
@@ -335,5 +518,7 @@ module.exports = {
   generateRunJs,
   generateWorkerReadme,
   validateInputs,
-  resolveEnvVars
+  resolveEnvVars,
+  runSkillWorker,
+  loadAgentMemory
 };