@jaimevalasek/aioson 1.7.2 → 1.9.0

package/src/dossier/lock.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const LOCK_FILENAME = '.dossier.lock';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_POLL_INTERVAL_MS = 200;
+const DEFAULT_STALE_TTL_MS = 60_000;
+
+function defaultIsAlive(pid) {
+  if (typeof pid !== 'number' || !Number.isFinite(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isStaleLock(payload, { staleTtlMs, now, isAlive }) {
+  if (!payload || typeof payload !== 'object') return true;
+  const acquiredMs = Date.parse(payload.acquired_at);
+  if (!Number.isFinite(acquiredMs)) return true;
+  if (now() - acquiredMs >= staleTtlMs) return true;
+  if (typeof payload.pid !== 'number' || !isAlive(payload.pid)) return true;
+  return false;
+}
+
+async function acquireLock(lockDir, section, opts = {}) {
+  if (typeof lockDir !== 'string' || !lockDir) {
+    throw new TypeError('acquireLock: lockDir must be a non-empty string');
+  }
+  if (typeof section !== 'string' || !section) {
+    throw new TypeError('acquireLock: section must be a non-empty string');
+  }
+
+  const {
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    pollIntervalMs = DEFAULT_POLL_INTERVAL_MS,
+    staleTtlMs = DEFAULT_STALE_TTL_MS,
+    now = Date.now,
+    pid = process.pid,
+    isAlive = defaultIsAlive,
+    onWarn = (msg) => process.emitWarning(msg, 'DossierLockStale'),
+    sleepFn = sleep
+  } = opts;
+
+  const lockPath = path.join(lockDir, LOCK_FILENAME);
+  const start = now();
+
+  await fs.mkdir(lockDir, { recursive: true });
+
+  while (true) {
+    try {
+      const payload = {
+        pid,
+        section,
+        acquired_at: new Date(now()).toISOString()
+      };
+      const fh = await fs.open(lockPath, 'wx');
+      try {
+        await fh.writeFile(JSON.stringify(payload));
+      } finally {
+        await fh.close();
+      }
+
+      let released = false;
+      return async function release() {
+        if (released) return;
+        released = true;
+        try {
+          await fs.unlink(lockPath);
+        } catch (err) {
+          if (err && err.code !== 'ENOENT') throw err;
+        }
+      };
+    } catch (err) {
+      if (!err || err.code !== 'EEXIST') throw err;
+
+      let existing = null;
+      try {
+        const raw = await fs.readFile(lockPath, 'utf8');
+        existing = JSON.parse(raw);
+      } catch (_) {
+        existing = null;
+      }
+
+      if (isStaleLock(existing, { staleTtlMs, now, isAlive })) {
+        onWarn(
+          `stale dossier lockfile at ${lockPath} (pid=${existing && existing.pid != null ? existing.pid : '?'}); overriding`
+        );
+        try {
+          await fs.unlink(lockPath);
+        } catch (unlinkErr) {
+          if (unlinkErr && unlinkErr.code !== 'ENOENT') throw unlinkErr;
+        }
+        continue;
+      }
+
+      if (now() - start >= timeoutMs) {
+        const timeoutErr = new Error(
+          `timed out acquiring dossier lock at ${lockPath} after ${timeoutMs}ms`
+        );
+        timeoutErr.code = 'EDOSSIERLOCK';
+        timeoutErr.lockPath = lockPath;
+        timeoutErr.holder = existing;
+        throw timeoutErr;
+      }
+
+      await sleepFn(pollIntervalMs);
+    }
+  }
+}
+
+module.exports = {
+  LOCK_FILENAME,
+  DEFAULT_TIMEOUT_MS,
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_STALE_TTL_MS,
+  acquireLock,
+  isStaleLock,
+  defaultIsAlive
+};

package/src/dossier/research-index-store.js

@@ -0,0 +1,233 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { isValidSlug, RESEARCH_VERDICTS, isCanonicalAgent } = require('./schema');
+const { stripInjectionChars } = require('../lib/llm-content-sanitizer');
+
+const FEATURES_SUBDIR = 'features';
+const DOSSIER_FILENAME = 'dossier.md';
+const SECTION_HEADER = '## Research Index';
+const FOLLOWING_SECTION_HEADER = '## Agent Trail';
+
+const WHY_RELEVANT_MAX = 200;
+
+function dossierPath(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug, DOSSIER_FILENAME);
+}
+
+function stripQuotes(s) {
+  return s.replace(/^["']|["']$/g, '');
+}
+
+function parseResearchIndexBlock(raw) {
+  const sectionStart = raw.indexOf(SECTION_HEADER + '\n');
+  if (sectionStart === -1) return null;
+  const nextSection = raw.indexOf('\n## ', sectionStart + SECTION_HEADER.length);
+  const sectionEnd = nextSection === -1 ? raw.length : nextSection;
+  const marker = '```yaml\n';
+  const blockStart = raw.indexOf(marker, sectionStart);
+  if (blockStart === -1 || blockStart > sectionEnd) return null;
+  const codeStart = blockStart + marker.length;
+  const codeEnd = raw.indexOf('\n```', codeStart);
+  if (codeEnd === -1 || codeEnd > sectionEnd) return null;
+  return { sectionStart, sectionEnd, blockStart, codeStart, codeEnd };
+}
+
+function parseYamlResearchIndex(yamlText) {
+  const result = { researchs: [] };
+  const lines = yamlText.split('\n');
+  let inSection = false;
+  let currentItem = null;
+
+  const flushItem = () => {
+    if (currentItem !== null) {
+      result.researchs.push(currentItem);
+      currentItem = null;
+    }
+  };
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+
+    if (/^researchs:\s*(\[\])?\s*$/.test(line)) {
+      inSection = true;
+      continue;
+    }
+
+    if (!inSection) continue;
+
+    const listItemMatch = line.match(/^-\s+(\w+):\s*(.*)$/);
+    if (listItemMatch) {
+      flushItem();
+      currentItem = {};
+      currentItem[listItemMatch[1]] = stripQuotes(listItemMatch[2]);
+      continue;
+    }
+
+    const kvMatch = line.match(/^\s+(\w+):\s*(.*)$/);
+    if (kvMatch && currentItem !== null) {
+      currentItem[kvMatch[1]] = stripQuotes(kvMatch[2]);
+    }
+  }
+  flushItem();
+  return result;
+}
+
+function serializeResearchIndex(index) {
+  if (!index || !Array.isArray(index.researchs) || index.researchs.length === 0) {
+    return 'researchs: []';
+  }
+  const lines = ['researchs:'];
+  for (const item of index.researchs) {
+    const entries = Object.entries(item);
+    if (entries.length === 0) continue;
+    lines.push(`- ${entries[0][0]}: ${entries[0][1]}`);
+    for (const [k, v] of entries.slice(1)) {
+      lines.push(`  ${k}: ${v}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function validateResearchEntry(entry) {
+  const errors = [];
+  if (!entry.slug || !isValidSlug(entry.slug)) {
+    errors.push(`slug must be kebab-case (got: ${JSON.stringify(entry.slug)})`);
+  }
+  if (!entry.verdict || !RESEARCH_VERDICTS.has(entry.verdict)) {
+    errors.push(`verdict must be one of [${[...RESEARCH_VERDICTS].join(', ')}] (got: ${JSON.stringify(entry.verdict)})`);
+  }
+  if (!entry.agent_who_added || !isCanonicalAgent(entry.agent_who_added)) {
+    errors.push(`agent_who_added must be a canonical agent id (got: ${JSON.stringify(entry.agent_who_added)})`);
+  }
+  if (!entry.why_relevant || typeof entry.why_relevant !== 'string') {
+    errors.push('why_relevant is required (string)');
+  }
+  if (entry.why_relevant && entry.why_relevant.length > WHY_RELEVANT_MAX) {
+    errors.push(`why_relevant must be ≤ ${WHY_RELEVANT_MAX} chars (got: ${entry.why_relevant.length})`);
+  }
+  if (!entry.summary_path || typeof entry.summary_path !== 'string') {
+    errors.push('summary_path is required');
+  }
+  return errors;
+}
+
+function insertResearchIndexSection(raw, yamlContent) {
+  const sectionBlock = `${SECTION_HEADER}\n\n\`\`\`yaml\n${yamlContent}\n\`\`\`\n`;
+  const agentTrailIdx = raw.indexOf('\n' + FOLLOWING_SECTION_HEADER);
+  if (agentTrailIdx !== -1) {
+    return raw.slice(0, agentTrailIdx + 1) + sectionBlock + '\n' + raw.slice(agentTrailIdx + 1);
+  }
+  return raw + (raw.endsWith('\n') ? '' : '\n') + '\n' + sectionBlock;
+}
+
+async function addResearch({
+  slug,
+  contextDir,
+  researchSlug,
+  verdict,
+  agent,
+  whyRelevant,
+  summaryPath,
+  now = () => new Date()
+}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid feature slug: ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+
+  const computedSummaryPath = summaryPath || `researchs/${researchSlug}/summary.md`;
+
+  // SF-project-09: strip injection carriers from why_relevant before persistence.
+  // This text is loaded by every chain agent that opens dossier.md.
+  const safeWhyRelevant = typeof whyRelevant === 'string'
+    ? stripInjectionChars(whyRelevant)
+    : whyRelevant;
+
+  const candidate = {
+    slug: researchSlug,
+    verdict,
+    agent_who_added: agent,
+    why_relevant: safeWhyRelevant,
+    added_at: now().toISOString(),
+    summary_path: computedSummaryPath
+  };
+
+  const errors = validateResearchEntry(candidate);
+  if (errors.length > 0) {
+    const err = new Error(`invalid research entry: ${errors.join('; ')}`);
+    err.code = 'ERESEARCHVALIDATION';
+    err.errors = errors;
+    throw err;
+  }
+
+  const p = dossierPath(contextDir, slug);
+  let raw;
+  try {
+    raw = await fs.readFile(p, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      const e = new Error(`dossier not found for slug "${slug}"`);
+      e.code = 'EDOSSIERMISSING';
+      throw e;
+    }
+    throw err;
+  }
+
+  const parsed = parseResearchIndexBlock(raw);
+  let index = { researchs: [] };
+  if (parsed) {
+    const yamlText = raw.slice(parsed.codeStart, parsed.codeEnd);
+    index = parseYamlResearchIndex(yamlText);
+  }
+
+  // Idempotency: dedup by slug.
+  // last-write-wins on verdict + why_relevant; preserve agent_who_added + added_at from first write.
+  const existingIdx = index.researchs.findIndex(r => r.slug === researchSlug);
+  let action;
+  if (existingIdx !== -1) {
+    const existing = index.researchs[existingIdx];
+    if (
+      existing.verdict === verdict &&
+      existing.why_relevant === safeWhyRelevant &&
+      existing.summary_path === computedSummaryPath
+    ) {
+      return { added: false, updated: false, slug: researchSlug };
+    }
+    existing.verdict = verdict;
+    existing.why_relevant = safeWhyRelevant;
+    existing.summary_path = computedSummaryPath;
+    action = 'updated';
+  } else {
+    index.researchs.push(candidate);
+    action = 'added';
+  }
+
+  const newYaml = serializeResearchIndex(index);
+  let newRaw;
+  if (parsed) {
+    newRaw = raw.slice(0, parsed.codeStart) + newYaml + raw.slice(parsed.codeEnd);
+  } else {
+    newRaw = insertResearchIndexSection(raw, newYaml);
+  }
+
+  await fs.writeFile(p, newRaw, 'utf8');
+  return {
+    added: action === 'added',
+    updated: action === 'updated',
+    slug: researchSlug
+  };
+}
+
+module.exports = {
+  addResearch,
+  parseResearchIndexBlock,
+  parseYamlResearchIndex,
+  serializeResearchIndex,
+  validateResearchEntry,
+  insertResearchIndexSection,
+  SECTION_HEADER,
+  WHY_RELEVANT_MAX
+};

package/src/dossier/revision-store.js

@@ -0,0 +1,313 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const { isCanonicalAgent, isValidSlug } = require('./schema');
+const { shouldCompact, compact } = require('./dossier-compact');
+
+const FEATURES_SUBDIR = 'features';
+const REVISIONS_FILENAME = 'revisions.json';
+const MAX_REVISION_ROUNDS = 3;
+
+const VALID_SEVERITIES = new Set(['blocking', 'advisory']);
+const VALID_STATUSES = new Set(['pending', 'approved', 'rejected', 'resolved']);
+
+// Which workflow gate each agent "owns" (for anti-loop counter)
+const GATE_BY_AGENT = {
+  product: 'requirements',
+  analyst: 'requirements',
+  architect: 'design',
+  'ux-ui': 'design',
+  pm: 'plan',
+  dev: 'plan',
+  qa: 'execution'
+};
+
+function revisionsPath(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug, REVISIONS_FILENAME);
+}
+
+function dossierPath(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug, 'dossier.md');
+}
+
+function workflowStatePath(contextDir) {
+  return path.join(contextDir, 'workflow.state.json');
+}
+
+function nextRevId(existing) {
+  const n = existing.length + 1;
+  return `rev-${String(n).padStart(3, '0')}`;
+}
+
+async function readRevisions({ slug, contextDir }) {
+  const p = revisionsPath(contextDir, slug);
+  try {
+    const raw = await fs.readFile(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+async function writeRevisions({ slug, contextDir, revisions }) {
+  const p = revisionsPath(contextDir, slug);
+  await fs.mkdir(path.dirname(p), { recursive: true });
+  await fs.writeFile(p, JSON.stringify(revisions, null, 2) + '\n', 'utf8');
+}
+
+// Replace the content of one ## section in a markdown file.
+async function updateDossierSection(filePath, sectionName, newContent) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch {
+    return; // dossier absent — skip silently
+  }
+
+  const lines = raw.split('\n');
+  let sectionStart = -1;
+  let sectionEnd = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimEnd() === `## ${sectionName}`) {
+      sectionStart = i;
+    } else if (sectionStart !== -1 && i > sectionStart && /^## /.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  let rebuilt;
+  if (sectionStart === -1) {
+    // Append section at end
+    rebuilt = raw.trimEnd() + `\n\n## ${sectionName}\n\n${newContent.trimEnd()}\n`;
+  } else {
+    const before = lines.slice(0, sectionStart + 1);
+    const after = lines.slice(sectionEnd);
+    rebuilt = [...before, '', newContent.trimEnd(), '', ...after].join('\n');
+  }
+
+  await fs.writeFile(filePath, rebuilt, 'utf8');
+}
+
+function buildRevisionTable(revisions) {
+  if (revisions.length === 0) {
+    return '_(sem revisões abertas)_';
+  }
+  const header = '| id | requested_by | target | severity | status |';
+  const divider = '|----|-------------|--------|----------|--------|';
+  const rows = revisions.map((r) =>
+    `| ${r.id} | ${r.requested_by} | ${r.target} | ${r.severity} | ${r.status} |`
+  );
+  return [header, divider, ...rows].join('\n');
+}
+
+async function readWorkflowState(contextDir) {
+  const p = workflowStatePath(contextDir);
+  try {
+    const raw = await fs.readFile(p, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function writeWorkflowState(contextDir, state) {
+  const p = workflowStatePath(contextDir);
+  await fs.writeFile(p, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+async function open({
+  slug,
+  contextDir,
+  requestedBy,
+  target,
+  targetArtifact,
+  reason,
+  severity,
+  evidenceCodeRefs = [],
+  now = () => new Date()
+} = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug: ${JSON.stringify(slug)}`);
+    err.code = 'EREVSLUG';
+    throw err;
+  }
+  if (!isCanonicalAgent(requestedBy)) {
+    const err = new Error(`requested_by must be a canonical agent id (got: ${JSON.stringify(requestedBy)})`);
+    err.code = 'EREVAGENT';
+    throw err;
+  }
+  if (!isCanonicalAgent(target)) {
+    const err = new Error(`target must be a canonical agent id (got: ${JSON.stringify(target)})`);
+    err.code = 'EREVAGENT';
+    throw err;
+  }
+  if (!VALID_SEVERITIES.has(severity)) {
+    const err = new Error(`severity must be 'blocking' or 'advisory' (got: ${JSON.stringify(severity)})`);
+    err.code = 'EREVSCHEMA';
+    throw err;
+  }
+  if (!targetArtifact || typeof targetArtifact !== 'string') {
+    const err = new Error('target_artifact must be a non-empty relative path');
+    err.code = 'EREVSCHEMA';
+    throw err;
+  }
+  if (!reason || typeof reason !== 'string' || !reason.trim()) {
+    const err = new Error('reason must be a non-empty string');
+    err.code = 'EREVSCHEMA';
+    throw err;
+  }
+
+  const revisions = await readRevisions({ slug, contextDir });
+  const id = nextRevId(revisions);
+  const createdAt = now().toISOString();
+
+  const revision = {
+    id,
+    status: 'pending',
+    requested_by: requestedBy,
+    target,
+    target_artifact: targetArtifact,
+    reason: reason.trim(),
+    severity,
+    evidence_code_refs: Array.isArray(evidenceCodeRefs) ? evidenceCodeRefs : [],
+    created_at: createdAt,
+    resolved_at: null,
+    resolution: null
+  };
+
+  revisions.push(revision);
+  await writeRevisions({ slug, contextDir, revisions });
+
+  // Update dossier ## Revision Requests
+  const dp = dossierPath(contextDir, slug);
+  await updateDossierSection(dp, 'Revision Requests', buildRevisionTable(revisions));
+
+  return revision;
+}
+
+async function list({ slug, contextDir, status } = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug: ${JSON.stringify(slug)}`);
+    err.code = 'EREVSLUG';
+    throw err;
+  }
+  const revisions = await readRevisions({ slug, contextDir });
+  if (status && VALID_STATUSES.has(status)) {
+    return revisions.filter((r) => r.status === status);
+  }
+  return revisions;
+}
+
+async function resolve({
+  slug,
+  contextDir,
+  revId,
+  action,
+  forceRevision = false,
+  now = () => new Date()
+} = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug: ${JSON.stringify(slug)}`);
+    err.code = 'EREVSLUG';
+    throw err;
+  }
+  if (action !== 'approve' && action !== 'reject') {
+    const err = new Error(`action must be 'approve' or 'reject' (got: ${JSON.stringify(action)})`);
+    err.code = 'EREVSCHEMA';
+    throw err;
+  }
+
+  const revisions = await readRevisions({ slug, contextDir });
+  const idx = revisions.findIndex((r) => r.id === revId);
+  if (idx === -1) {
+    const err = new Error(`revision '${revId}' not found in ${slug}`);
+    err.code = 'EREVNOTFOUND';
+    throw err;
+  }
+
+  const rev = revisions[idx];
+  if (rev.status !== 'pending') {
+    const err = new Error(`revision '${revId}' is '${rev.status}' — only pending revisions can be resolved`);
+    err.code = 'EREVNOTPENDING';
+    throw err;
+  }
+
+  const resolvedAt = now().toISOString();
+
+  if (action === 'reject') {
+    revisions[idx] = { ...rev, status: 'rejected', resolved_at: resolvedAt, resolution: 'rejected' };
+    await writeRevisions({ slug, contextDir, revisions });
+    const dp = dossierPath(contextDir, slug);
+    await updateDossierSection(dp, 'Revision Requests', buildRevisionTable(revisions));
+    if (await shouldCompact({ slug, contextDir })) await compact({ slug, contextDir });
+    return { revision: revisions[idx], gateIncremented: null };
+  }
+
+  // approve path: check anti-loop limit
+  const gate = GATE_BY_AGENT[rev.target] || null;
+  let gateIncremented = null;
+  let newRounds = null;
+
+  if (gate) {
+    const wfState = await readWorkflowState(contextDir);
+    if (wfState) {
+      const rounds = (wfState.gate_revision_rounds || {})[gate] || 0;
+      if (rounds >= MAX_REVISION_ROUNDS && !forceRevision) {
+        const err = new Error(
+          `Anti-loop: gate '${gate}' already had ${rounds} revision round(s) (max ${MAX_REVISION_ROUNDS}). ` +
+          `Use --force-revision to override.`
+        );
+        err.code = 'EREVLOOP';
+        err.gate = gate;
+        err.rounds = rounds;
+        throw err;
+      }
+      newRounds = rounds + 1;
+      const updatedState = {
+        ...wfState,
+        gate_revision_rounds: {
+          ...(wfState.gate_revision_rounds || {}),
+          [gate]: newRounds
+        }
+      };
+      await writeWorkflowState(contextDir, updatedState);
+      gateIncremented = { gate, rounds: newRounds };
+    }
+  }
+
+  revisions[idx] = { ...rev, status: 'approved', resolved_at: resolvedAt, resolution: 'approved' };
+  await writeRevisions({ slug, contextDir, revisions });
+  const dp = dossierPath(contextDir, slug);
+  await updateDossierSection(dp, 'Revision Requests', buildRevisionTable(revisions));
+  if (await shouldCompact({ slug, contextDir })) await compact({ slug, contextDir });
+
+  return { revision: revisions[idx], gateIncremented };
+}
+
+async function getBlockingRevisions({ slug, contextDir }) {
+  if (!slug || !isValidSlug(slug)) return [];
+  const revisions = await readRevisions({ slug, contextDir });
+  return revisions.filter((r) => r.severity === 'blocking' && r.status === 'pending');
+}
+
+module.exports = {
+  VALID_SEVERITIES,
+  VALID_STATUSES,
+  GATE_BY_AGENT,
+  MAX_REVISION_ROUNDS,
+  revisionsPath,
+  readRevisions,
+  writeRevisions,
+  updateDossierSection,
+  buildRevisionTable,
+  open,
+  list,
+  resolve,
+  getBlockingRevisions
+};