@jaimevalasek/aioson 1.7.0 → 1.8.0

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

package/src/dossier/store.js

@@ -0,0 +1,400 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const {
+  SCHEMA_VERSION,
+  REQUIRED_SECTIONS,
+  isValidSlug,
+  assertFrontmatter,
+  validateFrontmatter
+} = require('./schema');
+
+const FEATURES_SUBDIR = 'features';
+const DOSSIER_FILENAME = 'dossier.md';
+const DEFAULT_AUTHOR = 'dossier-init';
+
+function featureDir(contextDir, slug) {
+  return path.join(contextDir, FEATURES_SUBDIR, slug);
+}
+
+function dossierPath(contextDir, slug) {
+  return path.join(featureDir(contextDir, slug), DOSSIER_FILENAME);
+}
+
+function prdPath(contextDir, slug) {
+  return path.join(contextDir, `prd-${slug}.md`);
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseFrontmatter(markdown) {
+  const text = String(markdown || '');
+  if (!text.startsWith('---\n') && !text.startsWith('---\r\n')) {
+    return { ok: false, data: null, body: text, reason: 'missing_frontmatter' };
+  }
+  const lines = text.split(/\r?\n/);
+  let closingIndex = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      closingIndex = i;
+      break;
+    }
+  }
+  if (closingIndex === -1) {
+    return { ok: false, data: null, body: text, reason: 'unclosed_frontmatter' };
+  }
+  const data = {};
+  for (let i = 1; i < closingIndex; i += 1) {
+    const line = lines[i].trim();
+    if (!line || line.startsWith('#')) continue;
+    const match = line.match(/^([a-zA-Z0-9_]+)\s*:\s*(.*)$/);
+    if (!match) {
+      return { ok: false, data: null, body: text, reason: 'invalid_frontmatter_line', line };
+    }
+    let val = match[2].trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    data[match[1]] = val;
+  }
+  const body = lines.slice(closingIndex + 1).join('\n');
+  return { ok: true, data, body };
+}
+
+function parseSections(markdown) {
+  const text = String(markdown || '');
+  const parsed = parseFrontmatter(text);
+  const body = parsed.ok ? parsed.body : text;
+  const sections = Object.create(null);
+
+  const lines = body.split(/\r?\n/);
+  let current = null;
+  let buf = [];
+
+  const flush = () => {
+    if (current !== null) {
+      sections[current] = buf.join('\n').replace(/\s+$/, '');
+    }
+  };
+
+  for (const line of lines) {
+    const m = line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      flush();
+      current = m[1].trim();
+      buf = [];
+    } else if (current !== null) {
+      buf.push(line);
+    }
+  }
+  flush();
+
+  return sections;
+}
+
+function extractPrdSection(prdMarkdown, headingNames) {
+  if (!prdMarkdown) return null;
+  const sections = parseSections(prdMarkdown);
+  for (const name of headingNames) {
+    if (sections[name]) {
+      const trimmed = sections[name].trim();
+      if (trimmed) return trimmed;
+    }
+  }
+  return null;
+}
+
+function buildDossierMarkdown({
+  slug,
+  classification,
+  createdAt,
+  author,
+  why,
+  what
+}) {
+  const fm = [
+    '---',
+    `feature_slug: ${slug}`,
+    `schema_version: "${SCHEMA_VERSION}"`,
+    `created_by: ${author}`,
+    `created_at: ${createdAt}`,
+    'status: active',
+    `classification: ${classification}`,
+    `last_updated_by: ${author}`,
+    `last_updated_at: ${createdAt}`,
+    '---',
+    ''
+  ].join('\n');
+
+  const body = [
+    '## Why',
+    '',
+    why || '_(preencher manualmente — PRD não encontrado ou sem seção de Vision/Problem)_',
+    '',
+    '## What',
+    '',
+    what || '_(preencher manualmente — PRD não encontrado ou sem seção de Escopo)_',
+    '',
+    '## Code Map',
+    '',
+    '```yaml',
+    'files: []',
+    'modules: []',
+    'patterns: []',
+    '```',
+    '',
+    '## Rules & Design-Docs aplicáveis',
+    '',
+    '_(vazio — populado a partir da Phase 2)_',
+    '',
+    '## Agent Trail',
+    '',
+    '_(vazio — populado a partir da Phase 2)_',
+    '',
+    '## Revision Requests',
+    '',
+    '_(vazio — populado a partir da Phase 2)_',
+    ''
+  ].join('\n');
+
+  return fm + body;
+}
+
+async function init({
+  slug,
+  contextDir,
+  classification = 'MEDIUM',
+  author = DEFAULT_AUTHOR,
+  now = () => new Date(),
+  prdContent,
+  whyText,
+  whatText
+} = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug (must be kebab-case): ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+  if (typeof contextDir !== 'string' || !contextDir) {
+    throw new TypeError('init: contextDir must be a non-empty string');
+  }
+
+  const dir = featureDir(contextDir, slug);
+  const filePath = dossierPath(contextDir, slug);
+
+  let prd = prdContent;
+  if (prd === undefined) {
+    const candidate = prdPath(contextDir, slug);
+    if (await fileExists(candidate)) {
+      prd = await fs.readFile(candidate, 'utf8');
+    }
+  }
+
+  const why = whyText !== undefined ? whyText : extractPrdSection(prd, ['Problem', 'Why', 'Vision']);
+  const what = whatText !== undefined ? whatText : extractPrdSection(prd, ['Escopo do MVP', 'Scope', 'What']);
+
+  const createdAt = now().toISOString();
+  const markdown = buildDossierMarkdown({
+    slug,
+    classification,
+    createdAt,
+    author,
+    why,
+    what
+  });
+
+  // Validate before writing — fail fast if our own builder produces invalid output.
+  const fmValidation = validateFrontmatter({
+    feature_slug: slug,
+    schema_version: SCHEMA_VERSION,
+    created_by: author,
+    created_at: createdAt,
+    status: 'active',
+    classification,
+    last_updated_by: author,
+    last_updated_at: createdAt
+  });
+  if (!fmValidation.valid) {
+    const err = new Error(`refusing to write invalid dossier: ${fmValidation.errors.join('; ')}`);
+    err.code = 'EDOSSIERSCHEMA';
+    err.errors = fmValidation.errors;
+    throw err;
+  }
+
+  await fs.mkdir(dir, { recursive: true });
+  let fh;
+  try {
+    fh = await fs.open(filePath, 'wx');
+  } catch (err) {
+    if (err && err.code === 'EEXIST') {
+      const e = new Error(`dossier already exists at ${filePath}`);
+      e.code = 'EDOSSIEREXISTS';
+      e.path = filePath;
+      throw e;
+    }
+    throw err;
+  }
+  try {
+    await fh.writeFile(markdown);
+  } finally {
+    await fh.close();
+  }
+
+  return { path: filePath, dir, frontmatter: fmValidation, sections: parseSections(markdown) };
+}
+
+async function read({ slug, contextDir } = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug (must be kebab-case): ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+  const filePath = dossierPath(contextDir, slug);
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      const e = new Error(`dossier not found for slug "${slug}" at ${filePath}`);
+      e.code = 'EDOSSIERMISSING';
+      e.path = filePath;
+      throw e;
+    }
+    throw err;
+  }
+
+  const fmParse = parseFrontmatter(raw);
+  if (!fmParse.ok) {
+    const err = new Error(`malformed dossier frontmatter at ${filePath}: ${fmParse.reason}`);
+    err.code = 'EDOSSIERPARSE';
+    err.path = filePath;
+    throw err;
+  }
+
+  // Schema validation — fail loud, never silent.
+  assertFrontmatter(fmParse.data);
+
+  return {
+    path: filePath,
+    raw,
+    frontmatter: fmParse.data,
+    sections: parseSections(raw)
+  };
+}
+
+async function show({ slug, contextDir } = {}) {
+  const { raw, frontmatter, sections, path: p } = await read({ slug, contextDir });
+
+  // Check for corrupted dossier-history.md (if present)
+  let historyWarn = null;
+  const hp = path.join(path.dirname(p), 'dossier-history.md');
+  try {
+    const histRaw = await fs.readFile(hp, 'utf8');
+    if (typeof histRaw !== 'string') historyWarn = 'history_corrupted';
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') historyWarn = 'history_corrupted';
+    // ENOENT = absent, not corrupted — silently ignore
+  }
+
+  const header = [
+    `# Dossier — ${frontmatter.feature_slug} (${frontmatter.classification})`,
+    `status=${frontmatter.status} schema=${frontmatter.schema_version} updated=${frontmatter.last_updated_at}`,
+    `path: ${p}`,
+    ''
+  ].join('\n');
+  return { header, raw, frontmatter, sections, path: p, warn: historyWarn };
+}
+
+// Append-only write to a named ## section in dossier.md.
+// Uses SHA-256 of (section + content) for dedup — repeated calls with same args are no-ops.
+async function addFinding({ slug, contextDir, agent, section, content, now = () => new Date() } = {}) {
+  if (!isValidSlug(slug)) {
+    const err = new Error(`invalid slug: ${JSON.stringify(slug)}`);
+    err.code = 'EDOSSIERSLUG';
+    throw err;
+  }
+  const filePath = dossierPath(contextDir, slug);
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      const e = new Error(`dossier not found for slug "${slug}" at ${filePath}`);
+      e.code = 'EDOSSIERMISSING';
+      e.path = filePath;
+      throw e;
+    }
+    throw err;
+  }
+
+  const hash = crypto.createHash('sha256').update(`${section}\0${content}`).digest('hex');
+  const hashMarker = `<!-- sha256:${hash} -->`;
+
+  // Idempotency: if hash already present, no-op silently
+  if (raw.includes(hashMarker)) {
+    return { added: false, hash };
+  }
+
+  const timestamp = now().toISOString();
+  const entry = [
+    hashMarker,
+    `**${timestamp}** | @${agent} | _${section}_`,
+    '',
+    content.trim(),
+    ''
+  ].join('\n');
+
+  // Append inside ## Agent Trail (or after it if not found)
+  const lines = raw.split('\n');
+  let trailEnd = lines.length;
+  let inTrail = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimEnd() === '## Agent Trail') {
+      inTrail = true;
+    } else if (inTrail && /^## /.test(lines[i])) {
+      trailEnd = i;
+      break;
+    }
+  }
+
+  // Insert before the next section (or at end of file)
+  const before = lines.slice(0, trailEnd);
+  const after = lines.slice(trailEnd);
+
+  // Trim trailing blank lines from before to avoid double blanks
+  while (before.length > 0 && before[before.length - 1].trim() === '') before.pop();
+  before.push('', entry.trimEnd());
+
+  const rebuilt = [...before, '', ...after].join('\n');
+  await fs.writeFile(filePath, rebuilt, 'utf8');
+
+  return { added: true, hash };
+}
+
+module.exports = {
+  FEATURES_SUBDIR,
+  DOSSIER_FILENAME,
+  DEFAULT_AUTHOR,
+  REQUIRED_SECTIONS,
+  featureDir,
+  dossierPath,
+  prdPath,
+  parseFrontmatter,
+  parseSections,
+  buildDossierMarkdown,
+  addFinding,
+  init,
+  read,
+  show
+};

package/src/execution-gateway.js

@@ -220,6 +220,9 @@ async function syncWorkflowRuntime(targetDir, input) {
   try {
     const state = input.state || {};
     const eventPayload = input.eventPayload || {};
+    if (!eventPayload.autonomy_mode && eventPayload.autonomyMode) {
+      eventPayload.autonomy_mode = eventPayload.autonomyMode;
+    }
     const activationAgent = normalizeText(input.activationAgent);
     const completedStage = normalizeText(input.completedStage);
     const sessionKey = makeWorkflowSessionKey(state);