@jaimevalasek/aioson 1.7.0 → 1.8.0

package/src/dossier/dossier-compact.js

@@ -0,0 +1,159 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { isValidSlug } = require('./schema');
+
+const FEATURES_SUBDIR = 'features';
+const DOSSIER_FILENAME = 'dossier.md';
+const HISTORY_FILENAME = 'dossier-history.md';
+const MAX_ACTIVE_SIZE = 15000;
+const TARGET_ACTIVE_SIZE = 10000;
+
+// Sections whose content can be migrated once the gate they belong to is closed.
+// The ordering reflects which gates close first in MEDIUM flow.
+const MIGRATABLE_SECTIONS = [
+  'Why',
+  'What',
+  'Rules & Design-Docs aplicáveis'
+];
+
+function dossierPath(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug, DOSSIER_FILENAME);
+}
+
+function historyPath(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug, HISTORY_FILENAME);
+}
+
+function splitSections(raw) {
+  const result = [];
+  const lines = raw.split('\n');
+  let current = null;
+  let buf = [];
+  let frontmatter = null;
+  let inFm = false;
+  let fmClosed = false;
+  let fmBuf = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!fmClosed) {
+      if (i === 0 && line === '---') { inFm = true; fmBuf.push(line); continue; }
+      if (inFm) {
+        fmBuf.push(line);
+        if (line === '---' && i > 0) { fmClosed = true; frontmatter = fmBuf.join('\n'); continue; }
+        continue;
+      }
+      fmClosed = true;
+    }
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      if (current !== null) result.push({ heading: current, lines: buf });
+      current = m[1].trim();
+      buf = [];
+    } else {
+      if (current !== null) buf.push(line);
+    }
+  }
+  if (current !== null) result.push({ heading: current, lines: buf });
+  return { frontmatter, sections: result };
+}
+
+function joinSections(frontmatter, sections) {
+  const parts = [];
+  if (frontmatter) parts.push(frontmatter, '');
+  for (const sec of sections) {
+    parts.push(`## ${sec.heading}`);
+    parts.push(...sec.lines);
+  }
+  return parts.join('\n');
+}
+
+async function compact({ slug, contextDir, now = () => new Date(), force = false } = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug: ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    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;
+  }
+
+  if (!force && Buffer.byteLength(raw, 'utf8') <= MAX_ACTIVE_SIZE) {
+    return { compacted: false, reason: 'size_ok', sizeBytes: Buffer.byteLength(raw, 'utf8') };
+  }
+
+  const { frontmatter, sections } = splitSections(raw);
+  const date = now().toISOString().slice(0, 10);
+  const hp = historyPath(contextDir, slug);
+
+  // Load or initialize history
+  let historyContent = '';
+  try {
+    historyContent = await fs.readFile(hp, 'utf8');
+  } catch {
+    historyContent = `# Dossier History — ${slug}\n\n`;
+  }
+
+  const migratedHeadings = [];
+  const activeSections = [];
+
+  for (const sec of sections) {
+    const body = sec.lines.join('\n').trim();
+    const isEmpty = !body || body.startsWith('_(vazio') || body.startsWith('_(empty') || body.startsWith('_(preencher');
+
+    if (MIGRATABLE_SECTIONS.includes(sec.heading) && !isEmpty) {
+      // Append to history (append-only, never compact again)
+      const anchor = sec.heading.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+/g, '-');
+      historyContent += `\n## [Migrated from active dossier on ${date}] ${sec.heading} {#${anchor}-${date}}\n\n${body}\n`;
+      migratedHeadings.push(sec.heading);
+
+      // Replace in active with summary + link
+      activeSections.push({
+        heading: sec.heading,
+        lines: [``, `_(migrated to [dossier-history.md](dossier-history.md#${anchor}-${date}))_`, ``]
+      });
+    } else {
+      activeSections.push(sec);
+    }
+  }
+
+  if (migratedHeadings.length === 0) {
+    return { compacted: false, reason: 'nothing_migratable', sizeBytes: Buffer.byteLength(raw, 'utf8') };
+  }
+
+  const newRaw = joinSections(frontmatter, activeSections);
+  await fs.writeFile(p, newRaw, 'utf8');
+  // History is append-only
+  await fs.writeFile(hp, historyContent, 'utf8');
+
+  return {
+    compacted: true,
+    migratedSections: migratedHeadings,
+    activeSizeBytes: Buffer.byteLength(newRaw, 'utf8'),
+    historyPath: hp
+  };
+}
+
+async function shouldCompact({ slug, contextDir } = {}) {
+  const p = dossierPath(contextDir, slug);
+  try {
+    const stat = await fs.stat(p);
+    return stat.size > MAX_ACTIVE_SIZE;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { compact, shouldCompact, MAX_ACTIVE_SIZE, TARGET_ACTIVE_SIZE, dossierPath, historyPath };

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/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
+};