@really-knows-ai/foundry 3.3.9 → 3.5.1

package/dist/scripts/lib/validation.js

@@ -0,0 +1,244 @@
+/**
+ * Shared validation utilities extracted from the plugin's validate-tools.
+ *
+ * These functions run deterministic validator commands (no LLM involvement)
+ * and return structured results consumed by the quench module and the
+ * plugin's `foundry_validate_run` tool.
+ */
+
+import { execSync } from 'child_process';
+import { readdir } from 'fs/promises';
+import { join, relative, dirname, sep } from 'path';
+import { minimatch } from 'minimatch';
+import { getLawsForQuench, getArtefactType } from './config.js';
+import { parseValidatorJsonl } from './validator-jsonl.js';
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+function shellQuote(value) {
+  return "'" + String(value).replace(/'/g, "'\\''") + "'";
+}
+
+function validatePatterns(patterns, typeId) {
+  if (!Array.isArray(patterns) || patterns.length === 0) {
+    return { ok: false, error: `Artefact type ${typeId} has no file-patterns` };
+  }
+  return null;
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git']);
+
+function toPosix(p) {
+  return sep === '/' ? p : p.split(sep).join('/');
+}
+
+async function readdirSafe(dir) {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+async function* walkFiles(root, dir) {
+  for (const entry of await readdirSafe(dir)) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+      yield* walkFiles(root, full);
+    } else if (entry.isFile()) {
+      yield toPosix(relative(root, full));
+    }
+  }
+}
+
+function fileMatchesAnyPattern(rel, patterns) {
+  for (const pattern of patterns) {
+    if (minimatch(rel, pattern)) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Exported functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Read file-patterns for an artefact type from its definition.
+ */
+export async function getValidationPatterns(foundryDir, typeId, io) {
+  const artType = await getArtefactType(foundryDir, typeId, io);
+  return artType.frontmatter['file-patterns'] || [];
+}
+
+/**
+ * Run validation commands for an artefact type deterministically.
+ *
+ * Accepts an IO interface and foundryDir directly (no plugin context
+ * dependency). When `artefacts` is provided, the `{files}` substitution
+ * uses non-deleted files from the artefact list instead of expanding
+ * patterns across the worktree.
+ *
+ * @param {{ typeId: string, io: object, foundryDir: string, artefacts?: Array<{file: string, state: string}> }} params
+ * @returns {Promise<{ ok: boolean, validatorsRun: number, items: Array, errors: Array }>}
+ */
+export async function performValidation({ typeId, io, foundryDir, artefacts }) {
+  let patterns;
+  try {
+    patterns = await getValidationPatterns(foundryDir, typeId, io);
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+
+  const validationErr = validatePatterns(patterns, typeId);
+  if (validationErr) return validationErr;
+
+  const laws = await getLawsForQuench(foundryDir, io, { typeId });
+  if (!laws?.length) {
+    return { ok: true, validatorsRun: 0, items: [], errors: [] };
+  }
+  return runValidatorsAndReport(laws, patterns, foundryDir, artefacts);
+}
+
+/**
+ * Run validators for a set of laws and build the aggregated result.
+ *
+ * When `artefacts` is provided, the `{files}` substitution uses non-deleted
+ * files from the artefact list. Otherwise patterns are expanded across the
+ * worktree (backwards compatibility for callers like `foundry_validate_run`).
+ */
+export async function runValidatorsAndReport(laws, patterns, foundryDir, artefacts) {
+  const worktree = dirname(foundryDir);
+  let expandedFiles;
+  if (artefacts) {
+    expandedFiles = artefacts
+      .filter(({ state }) => state !== 'deleted')
+      .map(({ file }) => file)
+      .sort();
+  } else {
+    expandedFiles = await expandPatterns(patterns, worktree);
+  }
+  const substitutions = {
+    pattern: patterns.map(shellQuote).join(' '),
+    files: expandedFiles.map(shellQuote).join(' '),
+  };
+  const results = await runValidators(laws, patterns, substitutions, worktree);
+
+  return {
+    ok: results.errors.length === 0,
+    validatorsRun: results.validatorsRun,
+    items: results.items,
+    errors: results.errors,
+  };
+}
+
+/**
+ * Expand glob patterns to actual file paths in the worktree.
+ *
+ * Uses readdir + minimatch for Node 20 compatibility (glob added in Node 22).
+ */
+export async function expandPatterns(patterns, worktree) {
+  const files = new Set();
+  for await (const rel of walkFiles(worktree, worktree)) {
+    if (fileMatchesAnyPattern(rel, patterns)) {
+      files.add(rel);
+    }
+  }
+  return Array.from(files).sort();
+}
+
+/**
+ * Run all validators across a list of laws and collect results.
+ */
+export async function runValidators(laws, patterns, substitutions, worktree) {
+  const results = {
+    validatorsRun: 0,
+    items: [],
+    errors: [],
+  };
+
+  for (const law of laws) {
+    if (!law.validators || law.validators.length === 0) continue;
+    await runLawValidators(law, patterns, substitutions, worktree, results);
+  }
+
+  return results;
+}
+
+/**
+ * Run validators for a single law.
+ */
+export async function runLawValidators(law, patterns, substitutions, worktree, results) {
+  for (const validator of law.validators) {
+    // Skip commands that require {files} when there are no matching files
+    if (substitutions.files === '' && /(?:^|\s)\{files\}(?=\s|$)/.test(validator.command)) {
+      continue;
+    }
+    results.validatorsRun++;
+    const expanded = expandValidatorCommand(validator.command, substitutions);
+    const parseResult = await executeValidator(expanded, worktree, patterns);
+    collectValidatorResult(parseResult, law.id, validator.id, results);
+  }
+}
+
+/**
+ * Fold a single validator's parse result into the aggregate results.
+ */
+export function collectValidatorResult(parseResult, lawId, validatorId, results) {
+  for (const item of parseResult.items) {
+    results.items.push({ lawId, validatorId, ...item });
+  }
+  for (const message of parseResult.parseErrors) {
+    results.errors.push({ lawId, validatorId, type: 'parse', message });
+  }
+  for (const message of parseResult.patternErrors) {
+    results.errors.push({ lawId, validatorId, type: 'pattern-mismatch', message });
+  }
+}
+
+/**
+ * Execute a validator command and parse its JSONL output.
+ */
+export async function executeValidator(expanded, worktree, patterns) {
+  try {
+    const output = execSync(expanded, {
+      cwd: worktree,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const { Readable } = await import('stream');
+    const stream = Readable.from([output]);
+    return await parseValidatorJsonl(stream, patterns);
+  } catch (err) {
+    // Validator command failed — prefer stdout for JSONL
+    // (tools like rg exit 1 with results on stdout)
+    const output = (err.stdout || err.stderr || err.message || '').trim();
+    const { Readable } = await import('stream');
+    const stream = Readable.from([output]);
+    return await parseValidatorJsonl(stream, patterns);
+  }
+}
+
+/**
+ * Expand validator command placeholders {pattern} and {files}.
+ *
+ * Both placeholders are recognised only as standalone tokens bounded by
+ * whitespace or start/end of string. Surrounding single or double quotes
+ * around the placeholder are stripped first.
+ */
+export function expandValidatorCommand(command, { pattern, files }) {
+  let cmd = command
+    .replace(/"\{pattern\}"/g, '{pattern}')
+    .replace(/'\{pattern\}'/g, '{pattern}')
+    .replace(/"\{files\}"/g, '{files}')
+    .replace(/'\{files\}'/g, '{files}');
+
+  cmd = cmd.replace(/(?:^|\s)\{pattern\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? pattern : ' ' + pattern);
+
+  cmd = cmd.replace(/(?:^|\s)\{files\}(?=\s|$)/g, (match) =>
+    match.startsWith('{') ? files : ' ' + files);
+
+  return cmd;
+}

package/dist/scripts/lib/workfile.js

@@ -127,8 +127,5 @@ export function createWorkfile(frontmatter, goal) {
 # Goal
 
 ${goal}
-
-| File | Type | Cycle | Status |
-|------|------|-------|--------|
 `;
 }

package/dist/scripts/orchestrate-cycle.js

@@ -5,21 +5,12 @@ import {
   getCycleDefinition,
   getArtefactType,
 } from './lib/config.js';
-import { parseArtefactsTable, setArtefactStatus } from './lib/artefacts.js';
 import { openFeedbackStore } from './lib/feedback-store.js';
 
 // ---------------------------------------------------------------------------
 // Public helpers (re-exported by orchestrate.js for tests).
 // ---------------------------------------------------------------------------
 
-export function findCycleOutputArtefact(cycleId, io) {
-  if (!io.exists('WORK.md')) return null;
-  const content = io.readFile('WORK.md');
-  const rows = parseArtefactsTable(content);
-  const match = rows.find(r => r.cycle === cycleId);
-  return match ? { file: match.file, type: match.type, status: match.status } : null;
-}
-
 export async function readCycleTargets(cycleId, io) {
   try {
     const cd = await getCycleDefinition('foundry', cycleId, io);
@@ -47,7 +38,11 @@ export async function readForgeFilePatterns(cycleId, io) {
   }
   const output = extractOutputType(cd);
   if (!output) return null;
-  return fetchFilePatterns(output, io);
+  try {
+    return await fetchFilePatterns(output, io);
+  } catch {
+    return null;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -148,31 +143,7 @@ export function tryCommit(git, message, allowedPatterns, phase) {
   }
 }
 
-function findCycleRow(cycleId, rows) {
-  return rows.find(r => r.cycle === cycleId);
-}
 
-function writeBlockedStatus(content, row, io) {
-  try {
-    io.writeFile('WORK.md', setArtefactStatus(content, row.file, 'blocked'));
-    return { ok: true };
-  } catch (e) {
-    return { ok: false, error: e?.message || String(e) };
-  }
-}
-
-export function markArtefactBlocked(cycleId, io) {
-  if (!io.exists('WORK.md')) return { ok: true };
-  const content = io.readFile('WORK.md');
-  const rows = parseArtefactsTable(content);
-  const row = findCycleRow(cycleId, rows);
-  if (!row) return { ok: true };
-  return writeBlockedStatus(content, row, io);
-}
-
-export function formatBlockNote(blockResult) {
-  return blockResult.ok ? '' : ` (also: failed to mark artefact blocked: ${blockResult.error})`;
-}
 
 // ---------------------------------------------------------------------------
 // Stage synthesis (pure utility, used by setupWorkfile and exported publicly).
@@ -188,6 +159,71 @@ export function synthesizeStages({ cycleId, hasValidation, humanAppraise, assay
   return stages;
 }
 
+// ---------------------------------------------------------------------------
+// Dispatch-multi action constants and validators.
+// ---------------------------------------------------------------------------
+
+export const DISPATCH_MULTI_ACTION = 'dispatch_multi';
+
+/**
+ * Validate a dispatch_multi action object.
+ *
+ * Checks action type, tasks array shape, and each task's required fields.
+ * Returns undefined on success, a violation object on failure.
+ */
+function validString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function checkActionType(action) {
+  if (!action || action.action !== DISPATCH_MULTI_ACTION) {
+    return violation(`action must be "${DISPATCH_MULTI_ACTION}"`, []);
+  }
+  return undefined;
+}
+
+function validateAllTasks(tasks) {
+  for (let i = 0; i < tasks.length; i++) {
+    const err = checkDispatchTask(tasks[i], i);
+    if (err) return err;
+  }
+  return undefined;
+}
+
+export function validateDispatchMulti(action) {
+  const typeErr = checkActionType(action);
+  if (typeErr) return typeErr;
+  if (!Array.isArray(action.tasks)) {
+    return violation('dispatch_multi tasks must be an array', []);
+  }
+  return validateAllTasks(action.tasks);
+}
+
+function checkDispatchTask(task, index) {
+  if (!validString(task.subagent_type)) {
+    return violation(`dispatch_multi tasks[${index}]: subagent_type must be a non-empty string`, []);
+  }
+  if (!validString(task.prompt)) {
+    return violation(`dispatch_multi tasks[${index}]: prompt must be a non-empty string`, []);
+  }
+  return undefined;
+}
+
+/**
+ * Build a dispatch_multi response object.
+ *
+ * Pure utility for constructing the action envelope expected by the
+ * orchestrate skill's LLM loop.
+ */
+export function buildDispatchMultiResponse(tasks, stage, cycle) {
+  return {
+    action: DISPATCH_MULTI_ACTION,
+    tasks,
+    stage,
+    cycle,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Dispatch prompt rendering (pure utility, used by handleSortResult and exported publicly).
 // ---------------------------------------------------------------------------

package/dist/scripts/orchestrate-phases.js

@@ -13,38 +13,62 @@ import { stageBaseOf } from './lib/stage-guard.js';
 import { allowedPatternsForStage } from './lib/git-policy.js';
 import { loadExtractor } from './lib/assay/loader.js';
 import { checkExtractorAgainstCycle } from './lib/assay/permissions.js';
+import { getArtefactFiles } from './lib/artefacts.js';
 import {
-  findCycleOutputArtefact,
   readCycleTargets,
   readForgeFilePatterns,
   readRecentFeedback,
   computeOpenFeedback,
   violation,
   tryCommit,
-  markArtefactBlocked,
-  formatBlockNote,
   synthesizeStages,
   renderDispatchPrompt,
 } from './orchestrate-cycle.js';
 
-async function doneAction(cycleId, io) {
-  const art = findCycleOutputArtefact(cycleId, io);
-  return { action: 'done', cycle: cycleId, artefact_file: art?.file ?? null, next_cycles: await readCycleTargets(cycleId, io) };
+async function findOutputArtefacts(cfm, io, foundryDir, baseBranch) {
+  const outputType = cfm ? cfm['output-type'] : undefined;
+  if (!outputType) return null;
+  const artefacts = await getArtefactFiles(foundryDir, outputType, io, { baseBranch });
+  return artefacts.find(a => a.state !== 'deleted') || null;
 }
 
-function blockedAction(cycleId, io, details) {
-  const art = findCycleOutputArtefact(cycleId, io);
-  return { action: 'blocked', cycle: cycleId, artefact_file: art?.file ?? null, reason: details ?? 'iteration limit reached with unresolved feedback' };
+async function doneAction(cycleId, io, foundryDir, baseBranch) {
+  const fd = foundryDir || 'foundry';
+  const base = baseBranch || 'main';
+  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
+  const artefact = await findOutputArtefacts(cfm, io, fd, base);
+  const artefactFile = artefact ? artefact.file : null;
+  return { action: 'done', cycle: cycleId, artefact_file: artefactFile, next_cycles: await readCycleTargets(cycleId, io) };
 }
 
-function humanAppraiseAction(route, token, cycleId, io) {
-  const art = findCycleOutputArtefact(cycleId, io);
-  return { action: 'human_appraise', stage: route, token, context: { cycle: cycleId, artefact_file: art?.file ?? null, recent_feedback: readRecentFeedback(io) } };
+async function blockedAction(cycleId, io, details, foundryDir, baseBranch) {
+  const fd = foundryDir || 'foundry';
+  const base = baseBranch || 'main';
+  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
+  const artefact = await findOutputArtefacts(cfm, io, fd, base);
+  const artefactFile = artefact ? artefact.file : null;
+  const reason = details || 'iteration limit reached with unresolved feedback';
+  return { action: 'blocked', cycle: cycleId, artefact_file: artefactFile, reason };
 }
 
-function missingModelViolation(cycleId, route, io) {
-  const art = findCycleOutputArtefact(cycleId, io);
-  return violation(`cycle ${cycleId} stage ${route} has no model declared in cycle definition`, [art?.file].filter(Boolean));
+async function humanAppraiseAction(route, token, ctx) {
+  const { cycleId, io, baseBranch } = ctx;
+  const fd = ctx.foundryDir || 'foundry';
+  const base = baseBranch || 'main';
+  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
+  const artefact = await findOutputArtefacts(cfm, io, fd, base);
+  const artefactFile = artefact ? artefact.file : null;
+  return { action: 'human_appraise', stage: route, token, context: { cycle: cycleId, artefact_file: artefactFile, recent_feedback: readRecentFeedback(io) } };
+}
+
+async function missingModelViolation(cycleId, route, io, foundryDir, baseBranch) {
+  const fd = foundryDir || 'foundry';
+  const base = baseBranch || 'main';
+  const cfm = (await getCycleDefinition(fd, cycleId, io)).frontmatter;
+  const outputType = cfm ? cfm['output-type'] : undefined;
+  const artefacts = outputType ? await getArtefactFiles(fd, outputType, io, { baseBranch: base }) : [];
+  const affectedFiles = artefacts.filter(a => a.state !== 'deleted').map(a => a.file);
+  return violation(`cycle ${cycleId} stage ${route} has no model declared in cycle definition`, affectedFiles);
 }
 
 function makeDispatchPayload(route, cycleId, token, cwd, filePatterns) {
@@ -52,30 +76,38 @@ function makeDispatchPayload(route, cycleId, token, cwd, filePatterns) {
 }
 
 async function buildDispatchAction(route, model, token, ctx) {
-  if (!model) return missingModelViolation(ctx.cycleId, route, ctx.io);
+  if (!model) return missingModelViolation(ctx.cycleId, route, ctx.io, ctx.foundryDir, ctx.baseBranch ?? 'main');
   const base = route.split(':')[0];
   const filePatterns = base === 'forge' ? await readForgeFilePatterns(ctx.cycleId, ctx.io) : null;
   return { action: 'dispatch', stage: route, subagent_type: model, prompt: renderDispatchPrompt(makeDispatchPayload(route, ctx.cycleId, token, ctx.cwd, filePatterns)) };
 }
 
-function routeDispatch(route) {
+export function routeDispatch(route) {
   return typeof route === 'string' ? route.split(':')[0] : '';
 }
 
 async function handleTerminalRoute(route, sortResult, ctx) {
-  if (route === 'done') return doneAction(ctx.cycleId, ctx.io);
-  if (route === 'blocked') return blockedAction(ctx.cycleId, ctx.io, sortResult.details);
-  return violation(sortResult.details ?? 'sort returned violation');
+  const baseBranch = ctx.baseBranch || 'main';
+  if (route === 'done') return doneAction(ctx.cycleId, ctx.io, ctx.foundryDir, baseBranch);
+  if (route === 'blocked') return blockedAction(ctx.cycleId, ctx.io, sortResult.details, ctx.foundryDir, baseBranch);
+  const details = sortResult.details || 'sort returned violation';
+  return violation(details);
+}
+
+function isTerminalRoute(route) {
+  return route === 'done' || route === 'blocked' || route === 'violation';
+}
+
+function getRouteBase(route) {
+  return routeDispatch(route);
 }
 
 export async function handleSortResult(sortResult, ctx) {
   const { route, model, token } = sortResult;
-  if (route === 'done' || route === 'blocked' || route === 'violation') {
-    return handleTerminalRoute(route, sortResult, ctx);
-  }
-  if (routeDispatch(route) === 'human-appraise') {
-    return humanAppraiseAction(route, token, ctx.cycleId, ctx.io);
-  }
+  const routeBase = getRouteBase(route);
+  if (isTerminalRoute(route)) return handleTerminalRoute(route, sortResult, ctx);
+  if (routeBase === 'quench' || routeBase === 'appraise') return violation(routeBase + ' route reached handleSortResult');
+  if (routeBase === 'human-appraise') return humanAppraiseAction(route, token, ctx);
   return buildDispatchAction(route, model, token, ctx);
 }
 
@@ -236,12 +268,11 @@ function readOriginalState(io) {
   return { workMd: io.readFile('WORK.md'), history: io.exists('WORK.history.yaml') ? io.readFile('WORK.history.yaml') : null };
 }
 
-function buildFinalizeViolation(finalizeResult, blockResult) {
-  const blockNote = formatBlockNote(blockResult);
+function buildFinalizeViolation(finalizeResult) {
   if (finalizeResult.error === 'unexpected_files') {
-    return violation(`unexpected files written by subagent: ${(finalizeResult.files || []).join(', ')}${blockNote}`, finalizeResult.files || []);
+    return violation(`unexpected files written by subagent: ${(finalizeResult.files || []).join(', ')}`, finalizeResult.files || []);
   }
-  return violation(`stage_finalize error: ${finalizeResult.error}${blockNote}`, []);
+  return violation(`stage_finalize error: ${finalizeResult.error}`, []);
 }
 
 function writeHistoryEntries(ctx) {
@@ -284,9 +315,8 @@ export async function finaliseStage(args) {
   }
   const finalizeResult = await finalize({ cycleId, stage: lastStage.stage, baseSha: lastStage.baseSha, io });
   if (!finalizeResult.ok) {
-    const blockResult = markArtefactBlocked(cycleId, io);
     clearStageState(activeStage, null, io);
-    return buildFinalizeViolation(finalizeResult, blockResult);
+    return buildFinalizeViolation(finalizeResult);
   }
   const historyPath = 'WORK.history.yaml';
   const iteration = getIteration(historyPath, cycleId, io);
@@ -303,12 +333,12 @@ export async function finaliseStage(args) {
 }
 
 export function handleViolation(args) {
-  const { lastResult, activeStage, lastStage, cycleId, io } = args;
+  const { lastResult, activeStage, lastStage } = args;
   const failedStage = activeStage || lastStage;
   if (!failedStage) { return violation('lastResult.ok=false but no stage recorded — orphaned state'); }
-  const blockResult = markArtefactBlocked(cycleId, io);
-  clearStageState(activeStage, lastStage, io);
-  const art = findCycleOutputArtefact(cycleId, io);
-  const blockNote = formatBlockNote(blockResult);
-  return violation(`subagent dispatch failed: ${lastResult.error || 'unknown error'}${blockNote}`, [art?.file].filter(Boolean));
+  clearStageState(activeStage, lastStage, args.io);
+  return violation(
+    `subagent dispatch failed: ${lastResult.error || 'unknown error'}`,
+    lastResult.affected_files || [],
+  );
 }