@really-knows-ai/foundry 2.3.1 → 3.0.0

package/dist/scripts/lib/sort-routing.js

@@ -0,0 +1,101 @@
+/**
+ * Sort routing helpers — pure functions that decide the next stage given
+ * the current stage list, history, feedback, and iteration counters.
+ *
+ * Extracted from `src/scripts/sort.js` to keep that file under the
+ * configured `max-lines` limit and to lower per-function complexity.
+ */
+
+// Spec §6.1: an item is "open" (still in flight) when its head state is
+// 'open', 'actioned', 'rejected', or 'wont-fix' — equivalently, when the
+// state is neither 'resolved' nor 'deadlocked'.
+const isOpenItem = (f) => f.state !== 'resolved' && f.state !== 'deadlocked';
+
+export function baseStage(stage) {
+  return stage.split(':')[0];
+}
+
+export function findFirst(stages, base) {
+  for (const s of stages) {
+    if (baseStage(s) === base) return s;
+  }
+  return null;
+}
+
+export function nextInRoute(stages, current) {
+  const idx = stages.indexOf(current);
+  if (idx !== -1 && idx + 1 < stages.length) {
+    return stages[idx + 1];
+  }
+  return null;
+}
+
+function hasItemsNeedingForge(openItems) {
+  return openItems.some(f => f.state === 'open' || f.state === 'rejected');
+}
+
+function hasItemsPendingApproval(openItems) {
+  return openItems.some(f => f.state === 'actioned' || f.state === 'wont-fix');
+}
+
+function routeForgeIfNeeded(stages, forgeCount, maxIterations) {
+  if (forgeCount >= maxIterations) return 'blocked';
+  return findFirst(stages, 'forge') ?? 'blocked';
+}
+
+function appraiseForgeOrApproval(stages, openItems, forgeCount, maxIterations) {
+  if (hasItemsNeedingForge(openItems)) {
+    return routeForgeIfNeeded(stages, forgeCount, maxIterations);
+  }
+  if (hasItemsPendingApproval(openItems)) {
+    return findFirst(stages, 'appraise') ?? 'blocked';
+  }
+  return null;
+}
+
+export function nextAfterAppraise({ stages, current, feedback, forgeCount, maxIterations }) {
+  // Note: deadlock detection is handled by runDeadlockPass at the top of
+  // runSort (spec §6.1). This helper assumes routing has already been allowed
+  // to fall through (i.e., no item qualifies as deadlocked).
+  const openItems = feedback.filter(isOpenItem);
+  const decided = appraiseForgeOrApproval(stages, openItems, forgeCount, maxIterations);
+  if (decided !== null) return decided;
+  return nextInRoute(stages, current) ?? 'done';
+}
+
+export function nextAfterQuench(stages, current, feedback, forgeCount, maxIterations) {
+  const openItems = feedback.filter(isOpenItem);
+  const needsForge = openItems.some(f => f.state === 'open' || f.state === 'rejected');
+  if (needsForge) return routeForgeIfNeeded(stages, forgeCount, maxIterations);
+  return nextInRoute(stages, current) ?? 'done';
+}
+
+function lastNonSortStage(history) {
+  const nonSort = history.filter(e => baseStage(e.stage || '') !== 'sort');
+  if (nonSort.length === 0) return null;
+  return nonSort[nonSort.length - 1].stage;
+}
+
+function buildRouteHandlers({ stages, lastEntry, feedback, forgeCount, maxIterations }) {
+  const appraiseRoute = () => nextAfterAppraise({
+    stages, current: lastEntry, feedback, forgeCount, maxIterations,
+  });
+  return {
+    'assay': () => findFirst(stages, 'forge') ?? 'blocked',
+    'forge': () => nextInRoute(stages, lastEntry) ?? 'done',
+    'quench': () => nextAfterQuench(stages, lastEntry, feedback, forgeCount, maxIterations),
+    'appraise': appraiseRoute,
+    'human-appraise': appraiseRoute,
+  };
+}
+
+export function determineRoute(stages, history, feedback, maxIterations) {
+  const forgeCount = history.filter(e => baseStage(e.stage || '') === 'forge').length;
+  const lastEntry = lastNonSortStage(history);
+  if (lastEntry === null) return stages[0];
+  const handlers = buildRouteHandlers({
+    stages, lastEntry, feedback, forgeCount, maxIterations,
+  });
+  const handler = handlers[baseStage(lastEntry)];
+  return handler ? handler() : 'blocked';
+}

package/{scripts → dist/scripts}/lib/stage-guard.js

@@ -12,14 +12,20 @@ export function requireNoActiveStage(io) {
   return { ok: false, error: `tool requires no active stage; current: ${a.stage}` };
 }
 
+function stageMismatchError(active, stageBase, cycle) {
+  if (stageBase && stageBaseOf(active.stage) !== stageBase) {
+    return `tool requires active ${stageBase} stage; current: ${active.stage}`;
+  }
+  if (cycle && active.cycle !== cycle) {
+    return `tool requires active stage in cycle ${cycle}; current cycle: ${active.cycle}`;
+  }
+  return null;
+}
+
 export function requireActiveStage(io, { stageBase, cycle } = {}) {
   const a = readActiveStage(io);
   if (!a) return { ok: false, error: `tool requires active stage; current: none` };
-  if (stageBase && stageBaseOf(a.stage) !== stageBase) {
-    return { ok: false, error: `tool requires active ${stageBase} stage; current: ${a.stage}` };
-  }
-  if (cycle && a.cycle !== cycle) {
-    return { ok: false, error: `tool requires active stage in cycle ${cycle}; current cycle: ${a.cycle}` };
-  }
+  const mismatch = stageMismatchError(a, stageBase, cycle);
+  if (mismatch) return { ok: false, error: mismatch };
   return { ok: true, active: a };
 }

package/{scripts → dist/scripts}/lib/state.js

@@ -29,3 +29,7 @@ export function writeLastStage(io, payload) {
   ensureFoundryDir(io);
   io.writeFile(LAST, JSON.stringify(payload, null, 2));
 }
+
+export function clearLastStage(io) {
+  io.unlink(LAST);
+}

package/dist/scripts/lib/token.js

@@ -0,0 +1,57 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export function signToken(payload, secret) {
+  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const mac = createHmac('sha256', secret).update(body).digest('base64url');
+  return `${body}.${mac}`;
+}
+
+function splitToken(token) {
+  if (typeof token !== 'string' || !token.includes('.')) return null;
+  const [body, mac] = token.split('.');
+  if (!body || !mac) return null;
+  return { body, mac };
+}
+
+function decodeMac(mac) {
+  try { return Buffer.from(mac, 'base64url'); }
+  catch { return null; }
+}
+
+function decodePayload(body) {
+  try { return JSON.parse(Buffer.from(body, 'base64url').toString()); }
+  catch { return null; }
+}
+
+function checkSignature(body, mac, secret) {
+  const expected = createHmac('sha256', secret).update(body).digest();
+  const given = decodeMac(mac);
+  if (!given) return { ok: false, reason: 'malformed' };
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+    return { ok: false, reason: 'bad_signature' };
+  }
+  return { ok: true };
+}
+
+function checkExpiry(payload) {
+  if (typeof payload.exp !== 'number' || payload.exp < Date.now()) {
+    return { ok: false, reason: 'expired' };
+  }
+  return { ok: true };
+}
+
+export function verifyToken(token, secret) {
+  const parts = splitToken(token);
+  if (!parts) return { ok: false, reason: 'malformed' };
+
+  const sigCheck = checkSignature(parts.body, parts.mac, secret);
+  if (!sigCheck.ok) return sigCheck;
+
+  const payload = decodePayload(parts.body);
+  if (!payload) return { ok: false, reason: 'malformed' };
+
+  const expiryCheck = checkExpiry(payload);
+  if (!expiryCheck.ok) return expiryCheck;
+
+  return { ok: true, payload };
+}

package/dist/scripts/lib/tracing.js

@@ -0,0 +1,59 @@
+/**
+ * JSONL trace appender for dry-run branches.
+ *
+ * Trace files live under `.foundry/trace/<branchSlug>.jsonl`, one JSON
+ * record per line. The IO contract is async and minimal so the module
+ * stays testable with in-memory mocks.
+ */
+
+const TRACE_DIR = '.foundry/trace';
+
+/**
+ * Convert a git branch name to a filesystem-safe slug by replacing every
+ * `/` with `-`. Pure string transform — no validation, since callers pass
+ * already-validated branch names.
+ */
+export function branchSlug(branch) {
+  return branch.replace(/\//g, '-');
+}
+
+function tracePath(branch) {
+  return `${TRACE_DIR}/${branchSlug(branch)}.jsonl`;
+}
+
+/**
+ * Append a single JSONL record to the trace file for `branch`.
+ *
+ * Ensures the trace directory exists before writing. Uses `io.appendFile`
+ * when present, otherwise falls back to read-then-write concatenation
+ * (treating ENOENT as empty).
+ */
+export async function appendTraceRecord({ branch, record, io }) {
+  const path = tracePath(branch);
+  const line = JSON.stringify(record) + '\n';
+
+  await io.mkdirp(TRACE_DIR);
+
+  if (typeof io.appendFile === 'function') {
+    await io.appendFile(path, line);
+    return;
+  }
+
+  let existing = '';
+  try {
+    existing = await io.readFile(path);
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') throw err;
+  }
+  await io.writeFile(path, existing + line);
+}
+
+/**
+ * Truncate the trace file for `branch` to empty. No-op when the file
+ * does not exist.
+ */
+export async function truncateTrace({ branch, io }) {
+  const path = tracePath(branch);
+  if (!(await io.exists(path))) return;
+  await io.writeFile(path, '');
+}

package/dist/scripts/lib/ulid.js

@@ -0,0 +1,100 @@
+// scripts/lib/ulid.js
+import { randomBytes } from 'node:crypto';
+
+// Crockford's base32 alphabet (excludes I, L, O, U).
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+// ULID spec: 10 chars of timestamp (48-bit ms since epoch) + 16 chars of randomness (80 bits).
+// We make the randomness monotonic within the same millisecond by incrementing the previous
+// random component by 1 whenever the timestamp hasn't advanced.
+
+function encodeTime(ms) {
+  let out = '';
+  let remaining = ms;
+  for (let i = 9; i >= 0; i--) {
+    out = ALPHABET[remaining % 32] + out;
+    remaining = Math.floor(remaining / 32);
+  }
+  return out;
+}
+
+function randomIndexes() {
+  const bytes = randomBytes(10); // 80 bits
+  const out = new Array(16);
+  // Pack 80 bits into 16 5-bit groups.
+  let bitBuffer = 0;
+  let bits = 0;
+  let j = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    bitBuffer = bitBuffer * 256 + bytes[i];
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out[j++] = Math.floor(bitBuffer / Math.pow(2, bits)) % 32;
+    }
+  }
+  return out;
+}
+
+function incrementRandom(arr) {
+  // Increment as a base-32 little-endian-ish counter from the right.
+  const next = arr.slice();
+  for (let i = next.length - 1; i >= 0; i--) {
+    if (next[i] < 31) { next[i] += 1; return next; }
+    next[i] = 0;
+  }
+  // Overflow across all 80 bits: re-seed. Extraordinarily unlikely.
+  return randomIndexes();
+}
+
+/**
+ * Creates an independent ULID generator with its own monotonicity state.
+ *
+ * Monotonicity state (lastTime, lastRandom) is kept in closure, not module
+ * scope, so tests can instantiate isolated generators and production code
+ * can import a single shared instance without cross-test contamination.
+ *
+ * @returns {(now?: number) => string} generator function
+ */
+export function createUlidGenerator() {
+  let lastTime = 0;
+  let lastRandom = null; // array of 16 base32 char indexes
+
+  return function ulid(now = Date.now()) {
+    let randArr;
+    if (now === lastTime && lastRandom) {
+      randArr = incrementRandom(lastRandom);
+    } else {
+      randArr = randomIndexes();
+    }
+    lastTime = now;
+    lastRandom = randArr;
+    const rand = randArr.map(i => ALPHABET[i]).join('');
+    return encodeTime(now) + rand;
+  };
+}
+
+// Default shared generator — preserves ergonomic `import { ulid }` usage.
+// Tests that need deterministic, isolated state should call createUlidGenerator().
+export const ulid = createUlidGenerator();
+
+/**
+ * Reverses encodeTime — first 10 chars of a ULID encode 48-bit ms since epoch.
+ * Returns the integer ms. Throws if any of the first 10 chars is not in the
+ * Crockford alphabet.
+ *
+ * @param {string} id ULID string (only first 10 chars are inspected).
+ * @returns {number} milliseconds since epoch.
+ */
+export function decodeUlidTime(id) {
+  let time = 0;
+  for (let i = 0; i < 10; i++) {
+    const ch = id[i];
+    const idx = ALPHABET.indexOf(ch);
+    if (idx === -1) {
+      throw new Error(`decodeUlidTime: invalid Crockford base32 char '${ch}' at position ${i}`);
+    }
+    time = time * 32 + idx;
+  }
+  return time;
+}

package/dist/scripts/lib/validator-jsonl.js

@@ -0,0 +1,162 @@
+import readline from 'readline';
+import { minimatch } from 'minimatch';
+
+/**
+ * Parse JSONL output from a validator, validating each line against patterns.
+ *
+ * Processes one JSON object per line. Each line must have:
+ * - file (REQUIRED): matches at least one pattern from patterns array
+ * - text (REQUIRED): feedback text
+ * - location (OPTIONAL): "line:col" format, prepended to text if present
+ * - severity (OPTIONAL): "error", "warning", etc., prepended to text if present
+ *
+ * If location and/or severity present, they are prepended to text as:
+ *   [severity] file:location — <text>
+ * If only severity: [severity] file — <text>
+ * If only location: file:location — <text>
+ *
+ * Successfully parsed and pattern-matched lines flow into `items`.
+ * Errors are split into two categories so callers can distinguish them:
+ * - `parseErrors`: malformed JSON or missing required fields
+ * - `patternErrors`: file did not match any artefact-type file-pattern
+ *
+ * `ok` is true only when both error arrays are empty. Items are always
+ * returned regardless of `ok`, so a validator producing a mix of valid
+ * items and errors surfaces both.
+ *
+ * @param {Stream} stream - readable stream of JSONL lines
+ * @param {string[]} patterns - array of glob patterns for file matching
+ * @returns {Promise<{ok: boolean, items: object[], parseErrors: string[], patternErrors: string[]}>}
+ */
+export async function parseValidatorJsonl(stream, patterns) {
+  const items = [];
+  const parseErrors = [];
+  const patternErrors = [];
+
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: stream,
+      crlfDelay: Infinity,
+    });
+
+    let lineNum = 0;
+
+    rl.on('line', (line) => {
+      lineNum++;
+      processLine(line, lineNum, patterns, items, { parseErrors, patternErrors });
+    });
+
+    rl.on('close', () => {
+      resolve(buildResult(items, parseErrors, patternErrors));
+    });
+
+    rl.on('error', (err) => {
+      parseErrors.push(`Stream error: ${err.message}`);
+      resolve(buildResult(items, parseErrors, patternErrors));
+    });
+  });
+}
+
+/**
+ * Build the final parse result with `ok` reflecting whether any errors occurred.
+ */
+function buildResult(items, parseErrors, patternErrors) {
+  const ok = parseErrors.length === 0 && patternErrors.length === 0;
+  return { ok, items, parseErrors, patternErrors };
+}
+
+/**
+ * Process a single JSONL line.
+ *
+ * `errors` bundles `parseErrors` and `patternErrors` so this function stays
+ * within the project's max-params lint budget.
+ */
+function processLine(line, lineNum, patterns, items, errors) {
+  const { parseErrors, patternErrors } = errors;
+  const trimmed = line.trim();
+
+  // Skip empty lines
+  if (!trimmed) return;
+
+  // Parse JSON
+  let obj;
+  try {
+    obj = JSON.parse(trimmed);
+  } catch (err) {
+    parseErrors.push(`Line ${lineNum}: Invalid JSON: ${err.message}`);
+    return;
+  }
+
+  // Validate required fields
+  const validation = validateRequired(obj, lineNum);
+  if (validation.error) {
+    parseErrors.push(validation.error);
+    return;
+  }
+
+  // Validate file matches pattern
+  if (!fileMatchesPattern(obj.file, patterns)) {
+    patternErrors.push(`Line ${lineNum}: File '${obj.file}' does not match any pattern: ${patterns.join(', ')}`);
+    return;
+  }
+
+  // Build final item with location/severity prepended if present
+  const finalItem = buildFinalItem(obj);
+  items.push(finalItem);
+}
+
+/**
+ * Validate required fields in parsed line.
+ */
+function validateRequired(obj, lineNum) {
+  if (typeof obj.file !== 'string' || obj.file.length === 0) {
+    return { error: `Line ${lineNum}: Missing required field 'file'` };
+  }
+  if (typeof obj.text !== 'string' || obj.text.length === 0) {
+    return { error: `Line ${lineNum}: Missing or empty required field 'text'` };
+  }
+  return { error: null };
+}
+
+/**
+ * Check if a file path matches at least one pattern.
+ */
+function fileMatchesPattern(file, patterns) {
+  return patterns.some(pattern => minimatch(file, pattern));
+}
+
+/**
+ * Build final item with location/severity prepended to text if present.
+ */
+function buildFinalItem(obj) {
+  const { file, text, location, severity, ...extra } = obj;
+  const finalText = prependLocationSeverity(text, file, location, severity);
+
+  // Return all fields including extra ones
+  const result = { file, text: finalText, ...extra };
+  if (location) result.location = location;
+  if (severity) result.severity = severity;
+
+  return result;
+}
+
+/**
+ * Prepend location and/or severity to text.
+ */
+function prependLocationSeverity(text, file, location, severity) {
+  if (!severity && !location) {
+    return text;
+  }
+
+  let prefix = '';
+  if (severity) {
+    prefix += `[${severity}] `;
+  }
+  prefix += file;
+  if (location) {
+    prefix += `:${location}`;
+  }
+  prefix += ' — ';
+
+  return prefix + text;
+}

package/{scripts → dist/scripts}/lib/workfile.js

@@ -8,8 +8,14 @@ import yaml from 'js-yaml';
 // Frontmatter parsing
 // ---------------------------------------------------------------------------
 
+/**
+ * Parse YAML frontmatter from a markdown document.
+ * NOTE: Intentionally duplicates logic from memory/frontmatter.js for
+ * different use cases. See memory/frontmatter.js for the canonical version
+ * with full error handling and line-ending normalisation.
+ */
 export function parseFrontmatter(text) {
-  const match = text.match(/^---\n(.+?)\n---/s);
+  const match = text.match(/^---\r?\n(.+?)\r?\n---/s);
   if (!match) return {};
   const fm = yaml.load(match[1]) || {};
   // Normalize: on-disk canonical key is `max-iterations` (kebab).
@@ -24,7 +30,7 @@ export function parseFrontmatter(text) {
 }
 
 export function writeFrontmatter(fields) {
-  const body = yaml.dump(fields, { lineWidth: -1 }).trimEnd();
+  const body = yaml.dump(fields, { lineWidth: -1, sortKeys: false }).trimEnd();
   return `---\n${body}\n---`;
 }
 
@@ -33,15 +39,21 @@ export function getFrontmatterField(text, key) {
   return fm[key];
 }
 
+/**
+ * Update a frontmatter field.
+ * 
+ * Note: This function preserves key order but does not preserve YAML comments.
+ * If the frontmatter contains comments, they will be lost during rewrite.
+ */
 export function setFrontmatterField(text, key, value) {
   // Coerce legacy camelCase key to canonical kebab form on write.
-  if (key === 'maxIterations') key = 'max-iterations';
+  const normalisedKey = key === 'maxIterations' ? 'max-iterations' : key;
   const fm = parseFrontmatter(text);
-  fm[key] = value;
+  fm[normalisedKey] = value;
   const fmBlock = writeFrontmatter(fm);
 
   // Strip existing frontmatter (if any) and prepend new one
-  const body = text.replace(/^---\n.+?\n---\n?/s, '');
+  const body = text.replace(/^---\r?\n.+?\r?\n---\r?\n?/s, '');
   return body ? `${fmBlock}\n${body}` : fmBlock;
 }
 
@@ -73,19 +85,7 @@ export function parseStagesValue(raw) {
   return raw.split(',').map(s => s.trim()).filter(Boolean);
 }
 
-/**
- * Parse a models value from tool input.
- * Accepts JSON object string or "key: value, key: value" string.
- * Always returns an object mapping stage base names to model IDs.
- */
-export function parseModelsValue(raw) {
-  if (!raw || !raw.trim()) return {};
-  // Try JSON first
-  try {
-    const parsed = JSON.parse(raw);
-    if (typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
-  } catch { /* not JSON */ }
-  // Fall back to "key: value, key: value" format
+function parseKvPairs(raw) {
   const result = {};
   for (const part of raw.split(',')) {
     const colonIdx = part.indexOf(':');
@@ -97,6 +97,26 @@ export function parseModelsValue(raw) {
   return result;
 }
 
+function tryParseJsonObject(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+  } catch { /* not JSON */ }
+  return null;
+}
+
+/**
+ * Parse a models value from tool input.
+ * Accepts JSON object string or "key: value, key: value" string.
+ * Always returns an object mapping stage base names to model IDs.
+ */
+export function parseModelsValue(raw) {
+  if (!raw || !raw.trim()) return {};
+  const jsonResult = tryParseJsonObject(raw);
+  if (jsonResult) return jsonResult;
+  return parseKvPairs(raw);
+}
+
 // ---------------------------------------------------------------------------
 // Workfile creation
 // ---------------------------------------------------------------------------
@@ -110,7 +130,5 @@ ${goal}
 
 | File | Type | Cycle | Status |
 |------|------|-------|--------|
-
-## Feedback
 `;
 }