@jaimevalasek/aioson 1.7.2 → 1.8.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/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
+};

package/src/dossier/schema.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const SCHEMA_VERSION = '1.0';
+
+const CANONICAL_AGENT_IDS = Object.freeze(new Set([
+  'analyst',
+  'architect',
+  'committer',
+  'copywriter',
+  'cypher',
+  'design-hybrid-forge',
+  'dev',
+  'deyvin',
+  'discover',
+  'discovery-design-doc',
+  'genome',
+  'neo',
+  'orache',
+  'orchestrator',
+  'pair',
+  'pentester',
+  'pm',
+  'product',
+  'profiler-enricher',
+  'profiler-forge',
+  'profiler-researcher',
+  'qa',
+  'setup',
+  'sheldon',
+  'site-forge',
+  'squad',
+  'tester',
+  'ux-ui',
+  'validator'
+]));
+
+const ORIGIN_PSEUDO_IDS = Object.freeze(new Set(['dossier-init', 'dossier-init-prompt']));
+
+const REQUIRED_FRONTMATTER_FIELDS = Object.freeze([
+  'feature_slug',
+  'schema_version',
+  'created_by',
+  'created_at',
+  'status',
+  'classification',
+  'last_updated_by',
+  'last_updated_at'
+]);
+
+const ALLOWED_STATUSES = Object.freeze(new Set(['active', 'paused', 'closed']));
+const ALLOWED_CLASSIFICATIONS = Object.freeze(new Set(['MICRO', 'SMALL', 'MEDIUM']));
+
+const REQUIRED_SECTIONS = Object.freeze([
+  'Why',
+  'What',
+  'Code Map',
+  'Rules & Design-Docs aplicáveis',
+  'Agent Trail',
+  'Revision Requests'
+]);
+
+const SLUG_REGEX = /^[a-z0-9][a-z0-9-]*$/;
+const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+function isValidSlug(value) {
+  return typeof value === 'string' && SLUG_REGEX.test(value);
+}
+
+function isValidIsoDate(value) {
+  if (typeof value !== 'string' || !ISO_DATE_REGEX.test(value)) return false;
+  const ts = Date.parse(value);
+  return Number.isFinite(ts);
+}
+
+function isCanonicalAgent(value) {
+  return typeof value === 'string' && CANONICAL_AGENT_IDS.has(value);
+}
+
+function isAllowedAuthor(value) {
+  return isCanonicalAgent(value) || (typeof value === 'string' && ORIGIN_PSEUDO_IDS.has(value));
+}
+
+function validateFrontmatter(fm) {
+  const errors = [];
+
+  if (!fm || typeof fm !== 'object') {
+    return { valid: false, errors: ['frontmatter is missing or not an object'] };
+  }
+
+  for (const field of REQUIRED_FRONTMATTER_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(fm, field) || fm[field] === '' || fm[field] === null || fm[field] === undefined) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+
+  if (fm.feature_slug !== undefined && !isValidSlug(fm.feature_slug)) {
+    errors.push(`feature_slug must be kebab-case (got: ${JSON.stringify(fm.feature_slug)})`);
+  }
+
+  if (fm.schema_version !== undefined && fm.schema_version !== SCHEMA_VERSION) {
+    errors.push(`unsupported schema_version: ${JSON.stringify(fm.schema_version)} (expected ${SCHEMA_VERSION})`);
+  }
+
+  if (fm.status !== undefined && !ALLOWED_STATUSES.has(fm.status)) {
+    errors.push(`status must be one of [${[...ALLOWED_STATUSES].join(', ')}] (got: ${JSON.stringify(fm.status)})`);
+  }
+
+  if (fm.classification !== undefined && !ALLOWED_CLASSIFICATIONS.has(fm.classification)) {
+    errors.push(`classification must be one of [${[...ALLOWED_CLASSIFICATIONS].join(', ')}] (got: ${JSON.stringify(fm.classification)})`);
+  }
+
+  if (fm.created_by !== undefined && !isAllowedAuthor(fm.created_by)) {
+    errors.push(`created_by must be a canonical agent id or 'dossier-init' (got: ${JSON.stringify(fm.created_by)})`);
+  }
+
+  if (fm.last_updated_by !== undefined && !isAllowedAuthor(fm.last_updated_by)) {
+    errors.push(`last_updated_by must be a canonical agent id or 'dossier-init' (got: ${JSON.stringify(fm.last_updated_by)})`);
+  }
+
+  if (fm.created_at !== undefined && !isValidIsoDate(fm.created_at)) {
+    errors.push(`created_at must be ISO 8601 (got: ${JSON.stringify(fm.created_at)})`);
+  }
+
+  if (fm.last_updated_at !== undefined && !isValidIsoDate(fm.last_updated_at)) {
+    errors.push(`last_updated_at must be ISO 8601 (got: ${JSON.stringify(fm.last_updated_at)})`);
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+function assertFrontmatter(fm) {
+  const result = validateFrontmatter(fm);
+  if (!result.valid) {
+    const err = new Error(`invalid dossier frontmatter: ${result.errors.join('; ')}`);
+    err.code = 'EDOSSIERSCHEMA';
+    err.errors = result.errors;
+    throw err;
+  }
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  CANONICAL_AGENT_IDS,
+  ORIGIN_PSEUDO_IDS,
+  REQUIRED_FRONTMATTER_FIELDS,
+  ALLOWED_STATUSES,
+  ALLOWED_CLASSIFICATIONS,
+  REQUIRED_SECTIONS,
+  isValidSlug,
+  isValidIsoDate,
+  isCanonicalAgent,
+  isAllowedAuthor,
+  validateFrontmatter,
+  assertFrontmatter
+};