@aifabrix/builder 2.49.2 → 2.50.0

package/scripts/lib/plan-meta.js

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Resolve plan paths and patch YAML frontmatter.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { REPO_ROOT, PLANS_DIR } = require('./plan-config');
+
+/**
+ * @param {string} msg
+ * @returns {never}
+ */
+function die(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+/**
+ * @param {string} input
+ * @returns {string}
+ */
+function resolvePlanPath(input) {
+  if (!input) {
+    die('Plan path or id required (e.g. 417.0)');
+  }
+  const resolved = path.resolve(REPO_ROOT, input);
+  if (fs.existsSync(resolved)) {
+    return resolved;
+  }
+  if (!fs.existsSync(PLANS_DIR)) {
+    die(`Plans directory not found: ${PLANS_DIR}`);
+  }
+  /** @param {string} dir */
+  function findIn(dir) {
+    if (!fs.existsSync(dir)) {
+      return null;
+    }
+    for (const name of fs.readdirSync(dir)) {
+      const full = path.join(dir, name);
+      if (fs.statSync(full).isDirectory()) {
+        const found = findIn(full);
+        if (found) {
+          return found;
+        }
+      } else if (name.endsWith('.plan.md')) {
+        const base = name.slice(0, -'.plan.md'.length);
+        if (base === input || base.startsWith(`${input}-`)) {
+          return full;
+        }
+      }
+    }
+    return null;
+  }
+  const exactRoot = path.join(PLANS_DIR, `${input}.plan.md`);
+  if (fs.existsSync(exactRoot)) {
+    return exactRoot;
+  }
+  const plansRoot = fs.readdirSync(PLANS_DIR);
+  const prefixMatch = plansRoot.find((n) => {
+    if (!n.endsWith('.plan.md')) {
+      return false;
+    }
+    const base = n.slice(0, -'.plan.md'.length);
+    return base === input || base.startsWith(`${input}-`);
+  });
+  if (prefixMatch) {
+    return path.join(PLANS_DIR, prefixMatch);
+  }
+  const nested = findIn(PLANS_DIR);
+  if (nested) {
+    return nested;
+  }
+  die(`Plan not found: ${input}`);
+}
+
+/**
+ * @param {string} planPath
+ * @param {string} key
+ * @param {string} value
+ */
+function patchPlanMeta(planPath, key, value) {
+  const raw = fs.readFileSync(planPath, 'utf8');
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) {
+    die('Plan has no frontmatter to patch');
+  }
+  let yaml = match[1];
+  const quoted = `"${String(value).replace(/"/g, '\\"')}"`;
+  const re = new RegExp(`^${key}:.*$`, 'm');
+  if (re.test(yaml)) {
+    yaml = yaml.replace(re, `${key}: ${quoted}`);
+  } else {
+    yaml = `${yaml}\n${key}: ${quoted}`;
+  }
+  fs.writeFileSync(planPath, `---\n${yaml}\n---\n${match[2]}`, 'utf8');
+}
+
+module.exports = {
+  die,
+  resolvePlanPath,
+  patchPlanMeta
+};

package/scripts/lib/plan-parse.js

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Parse Cursor plan frontmatter (shared).
+ */
+
+'use strict';
+
+const { readFileSync } = require('../../lib/internal/fs-real-sync');
+const { REPO_ROOT, PLANS_DIR } = require('./plan-config');
+
+const TODO_STATUSES = new Set(['pending', 'in_progress', 'completed', 'cancelled']);
+
+/**
+ * @param {string} block
+ * @returns {Array<{ id: string, content: string, status: string }>}
+ */
+function parseTodosBlock(block) {
+  const todos = [];
+  const chunks = block
+    .trim()
+    .split(/(?:^|\n)\s*-\s+id:\s*/)
+    .filter(Boolean);
+  for (const chunk of chunks) {
+    const idLine = chunk.split(/\r?\n/)[0].trim();
+    const contentMatch = chunk.match(/\n\s+content:\s*\|\s*\n([\s\S]*?)(?=\n\s+status:)/);
+    const statusMatch = chunk.match(/\n\s+status:\s*(\w+)/);
+    todos.push({
+      id: idLine,
+      content: contentMatch ? contentMatch[1].replace(/^\s{6}/gm, '').trim() : '',
+      status: statusMatch ? statusMatch[1] : 'pending'
+    });
+  }
+  return todos;
+}
+
+/**
+ * @param {string} raw
+ * @returns {Record<string, unknown> | null}
+ */
+function parseSimpleYaml(raw) {
+  const meta = {};
+  const lines = raw.split(/\r?\n/);
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    const keyMatch = line.match(/^([a-zA-Z0-9_]+):\s*(.*)$/);
+    if (!keyMatch) {
+      i += 1;
+      continue;
+    }
+    const key = keyMatch[1];
+    const rest = keyMatch[2].trim();
+
+    if (key === 'todos' && rest === '') {
+      const block = [];
+      i += 1;
+      while (i < lines.length && !/^[a-zA-Z0-9_]+:\s*/.test(lines[i])) {
+        block.push(lines[i]);
+        i += 1;
+      }
+      meta.todos = parseTodosBlock(block.join('\n'));
+      continue;
+    }
+
+    if (rest === '|' || rest === '>') {
+      const block = [];
+      i += 1;
+      while (i < lines.length && /^\s/.test(lines[i])) {
+        block.push(lines[i].replace(/^\s{2}/, ''));
+        i += 1;
+      }
+      meta[key] = block.join('\n').trimEnd();
+      continue;
+    }
+
+    if (rest === '' && i + 1 < lines.length && lines[i + 1].trim().startsWith('- ')) {
+      const items = [];
+      i += 1;
+      while (i < lines.length && lines[i].trim().startsWith('- ')) {
+        items.push(lines[i].trim().slice(2).trim());
+        i += 1;
+      }
+      meta[key] = items;
+      continue;
+    }
+
+    if (rest.startsWith('"') && rest.endsWith('"')) {
+      meta[key] = rest.slice(1, -1).replace(/\\"/g, '"');
+    } else if (rest === 'true' || rest === 'false') {
+      meta[key] = rest === 'true';
+    } else if (/^\d+$/.test(rest)) {
+      meta[key] = Number(rest);
+    } else if (rest) {
+      meta[key] = rest;
+    } else {
+      meta[key] = null;
+    }
+    i += 1;
+  }
+
+  return meta;
+}
+
+/**
+ * @param {string} planPath
+ * @returns {{ meta: Record<string, unknown>, body: string } | null}
+ */
+function loadPlanFile(planPath) {
+  const raw = readFileSync(planPath, 'utf8');
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) {
+    return null;
+  }
+  const meta = parseSimpleYaml(match[1]) || {};
+  if (Array.isArray(meta.todos)) {
+    meta.todos = normalizeTodos(meta.todos);
+  }
+  return { meta, body: match[2] };
+}
+
+/**
+ * @param {unknown} todos
+ * @returns {Array<{ id: string, content: string, status: string }>}
+ */
+function normalizeTodos(todos) {
+  if (!Array.isArray(todos)) {
+    return [];
+  }
+  return todos
+    .filter((t) => t && typeof t === 'object')
+    .map((t) => {
+      const item = /** @type {{ id?: string, content?: string, status?: string }} */ (t);
+      let status = String(item.status || 'pending');
+      if (!TODO_STATUSES.has(status)) {
+        status = 'pending';
+      }
+      return {
+        id: String(item.id || ''),
+        content: String(item.content || ''),
+        status
+      };
+    })
+    .filter((t) => t.id);
+}
+
+/**
+ * @param {Record<string, unknown>} meta
+ * @param {string} surface
+ * @returns {boolean}
+ */
+function hasSurface(meta, surface) {
+  const surfaces = meta.surfaces;
+  return Array.isArray(surfaces) && surfaces.includes(surface);
+}
+
+module.exports = {
+  REPO_ROOT,
+  PLANS_DIR,
+  loadPlanFile,
+  normalizeTodos,
+  hasSurface
+};

package/scripts/lib/plan-prevalidate-gates.js

@@ -0,0 +1,326 @@
+/**
+ * @fileoverview Pre-implementation plan validation gates (/validate-plan).
+ */
+
+/* eslint-disable valid-jsdoc, require-jsdoc */
+
+'use strict';
+
+const {
+  statSync,
+  mkdirSync,
+  writeFileSync
+} = require('../../lib/internal/fs-real-sync');
+const path = require('path');
+const { loadPlanFile, hasSurface } = require('./plan-parse');
+
+const REPO_ROOT = path.resolve(__dirname, '../..');
+const PREVALIDATE_REPORT_DIR = path.join(REPO_ROOT, 'temp/plan-prevalidation');
+
+/**
+ * @typedef {{ label: string, status: 'pass' | 'fail' | 'warn' | 'skip', detail?: string }} GateResult
+ */
+
+/**
+ * @param {string} label
+ * @param {'pass' | 'fail' | 'warn' | 'skip'} status
+ * @param {string} [detail]
+ * @returns {GateResult}
+ */
+function gate(label, status, detail) {
+  return { label, status, detail };
+}
+
+/**
+ * @param {string} body
+ * @param {string} heading
+ * @returns {boolean}
+ */
+function hasHeading(body, heading) {
+  const re = new RegExp(`^## ${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm');
+  return re.test(body);
+}
+
+/**
+ * @param {string} body
+ * @returns {string | null}
+ */
+function extractReportStatus(body) {
+  const reportMatch = body.match(/## Plan Validation Report[\s\S]*?\*\*Status\*\*:\s*(.+)/i);
+  if (!reportMatch) {
+    return null;
+  }
+  const line = reportMatch[1].trim();
+  if (/VALIDATED/i.test(line) && !/NEEDS|INCOMPLETE/i.test(line)) {
+    return 'validated';
+  }
+  if (/NEEDS UPDATES/i.test(line)) {
+    return 'needs-updates';
+  }
+  if (/INCOMPLETE/i.test(line)) {
+    return 'incomplete';
+  }
+  return null;
+}
+
+/**
+ * @param {string} body
+ * @param {string} subsection
+ * @returns {boolean}
+ */
+function hasReportSubsection(body, subsection) {
+  const reportIdx = body.indexOf('## Plan Validation Report');
+  if (reportIdx < 0) {
+    return false;
+  }
+  const report = body.slice(reportIdx);
+  const re = new RegExp(`^### ${subsection.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+  return re.test(report);
+}
+
+/**
+ * @param {string} planPath
+ * @param {string | undefined} lastValidatedAt
+ * @returns {boolean}
+ */
+function isValidationStale(planPath, lastValidatedAt) {
+  if (!lastValidatedAt) {
+    return false;
+  }
+  const validatedMs = Date.parse(String(lastValidatedAt));
+  if (Number.isNaN(validatedMs)) {
+    return false;
+  }
+  const mtime = statSync(planPath).mtimeMs;
+  return mtime > validatedMs + 86400000;
+}
+
+/**
+ * @param {string} body
+ * @returns {boolean}
+ */
+function needsManualSection(body, meta) {
+  const reportIdx = body.indexOf('## Plan Validation Report');
+  const planBody = reportIdx >= 0 ? body.slice(0, reportIdx) : body;
+  const todos = Array.isArray(meta.todos) ? meta.todos : [];
+  const todoText = todos.map((t) => `${t.content} ${t.id}`).join(' ');
+  const combined = `${planBody}\n${todoText}`;
+  return /manual|pilot|live proof|e2e smoke|container proof|dev-reload/i.test(combined);
+}
+
+/**
+ * @param {Record<string, unknown>} meta
+ * @returns {boolean}
+ */
+function isCodePlan(meta) {
+  return meta.planType === 'code';
+}
+
+/**
+ * @param {Record<string, unknown>} meta
+ * @returns {boolean}
+ */
+function isMetaPlan(meta) {
+  return meta.planType === 'meta';
+}
+
+/**
+ * @param {string} planPath
+ * @param {{ allowNeedsUpdates?: boolean, repoProfile?: string }} [opts]
+ */
+function runPrevalidateGates(planPath, opts = {}) {
+  const loaded = loadPlanFile(planPath);
+  if (!loaded) {
+    return {
+      gates: [gate('plan-parse', 'fail', 'invalid or missing frontmatter')],
+      reportStatus: 'incomplete',
+      planValidatedStatus: 'incomplete',
+      meta: {},
+      body: ''
+    };
+  }
+
+  const { meta, body } = loaded;
+  const gates = [];
+  const code = isCodePlan(meta);
+  const metaPlan = isMetaPlan(meta);
+
+  if (!meta.name && !meta.overview) {
+    gates.push(gate('frontmatter-name', 'fail', 'name or overview required'));
+  } else {
+    gates.push(gate('frontmatter-name', 'pass'));
+  }
+
+  if (!Array.isArray(meta.todos) || meta.todos.length === 0) {
+    gates.push(gate('todos', 'fail', 'frontmatter todos required'));
+  } else {
+    gates.push(gate('todos', 'pass', `${meta.todos.length} todo(s)`));
+  }
+
+  const scopeSections = ['Scope', 'Rules and Standards', 'Before Development', 'Definition of Done'];
+  for (const section of scopeSections) {
+    if (!hasHeading(body, section)) {
+      gates.push(gate(`section-${section}`, 'fail', `missing ## ${section}`));
+    } else {
+      gates.push(gate(`section-${section}`, 'pass'));
+    }
+  }
+
+  if (hasHeading(body, 'Scope')) {
+    const scopeOk =
+      /### In scope/i.test(body) && /### Out of scope/i.test(body);
+    gates.push(
+      scopeOk
+        ? gate('scope-boundaries', 'pass')
+        : gate('scope-boundaries', 'fail', 'Scope needs ### In scope and ### Out of scope')
+    );
+  }
+
+  if (code) {
+    for (const section of ['Architecture alignment', 'Code reuse scan', 'Expected Automated Tests']) {
+      gates.push(
+        hasHeading(body, section)
+          ? gate(`section-${section}`, 'pass')
+          : gate(`section-${section}`, 'fail', `code plan missing ## ${section}`)
+      );
+    }
+    if (!hasHeading(body, 'File Size Reduction Candidates')) {
+      gates.push(gate('file-size-section', 'warn', 'missing ## File Size Reduction Candidates'));
+    } else {
+      gates.push(gate('file-size-section', 'pass'));
+    }
+    if (hasSurface(meta, 'api') && !meta.apiTiers) {
+      gates.push(gate('api-tiers', 'fail', 'api surface requires apiTiers in frontmatter'));
+    } else if (hasSurface(meta, 'api')) {
+      gates.push(gate('api-tiers', 'pass'));
+    } else {
+      gates.push(gate('api-tiers', 'skip', 'no api surface'));
+    }
+  } else if (metaPlan) {
+    gates.push(gate('architecture-section', 'skip', 'meta plan'));
+    gates.push(gate('reuse-section', 'skip', 'meta plan'));
+    gates.push(gate('automated-tests-section', 'skip', 'meta plan'));
+  } else {
+    gates.push(gate('code-sections', 'skip', `planType=${meta.planType || 'unknown'}`));
+  }
+
+  if (code && needsManualSection(body, meta) && !hasHeading(body, 'Manual testing')) {
+    gates.push(gate('manual-testing-section', 'fail', 'manual scope detected — add ## Manual testing'));
+  } else if (metaPlan) {
+    gates.push(gate('manual-testing-section', 'skip', 'meta plan'));
+  } else if (needsManualSection(body, meta)) {
+    gates.push(gate('manual-testing-section', 'pass'));
+  } else {
+    gates.push(gate('manual-testing-section', 'skip', 'no manual scope'));
+  }
+
+  if (!hasHeading(body, 'Plan Validation Report')) {
+    gates.push(gate('validation-report', 'fail', 'missing ## Plan Validation Report'));
+  } else {
+    gates.push(gate('validation-report', 'pass'));
+    const reportStatus = extractReportStatus(body);
+    if (!reportStatus) {
+      gates.push(gate('report-status', 'fail', 'report missing **Status**: VALIDATED line'));
+    } else if (reportStatus === 'validated') {
+      gates.push(gate('report-status', 'pass', 'VALIDATED'));
+    } else if (reportStatus === 'needs-updates') {
+      gates.push(
+        gate('report-status', opts.allowNeedsUpdates ? 'warn' : 'fail', 'NEEDS UPDATES')
+      );
+    } else {
+      gates.push(gate('report-status', 'fail', 'INCOMPLETE'));
+    }
+
+    if (code) {
+      for (const sub of [
+        'Architecture alignment',
+        'Code reuse scan',
+        'Testing strategy',
+        'Manual testing and approval'
+      ]) {
+        gates.push(
+          hasReportSubsection(body, sub)
+            ? gate(`report-${sub}`, 'pass')
+            : gate(`report-${sub}`, 'fail', `report missing ### ${sub}`)
+        );
+      }
+    }
+  }
+
+  if (isValidationStale(planPath, meta.lastValidatedAt)) {
+    gates.push(gate('staleness', 'fail', 'plan modified after lastValidatedAt — re-validate'));
+  } else if (meta.lastValidatedAt) {
+    gates.push(gate('staleness', 'pass'));
+  } else {
+    gates.push(gate('staleness', 'skip', 'not yet validated'));
+  }
+
+  const hasFail = gates.some((g) => g.status === 'fail');
+  const hasWarn = gates.some((g) => g.status === 'warn');
+  let planValidatedStatus = 'validated';
+  if (hasFail) {
+    planValidatedStatus = 'incomplete';
+  } else if (hasWarn) {
+    planValidatedStatus = 'needs-updates';
+  }
+
+  const reportStatus = extractReportStatus(body) || planValidatedStatus;
+  if (reportStatus !== 'validated') {
+    planValidatedStatus = reportStatus === 'needs-updates' ? 'needs-updates' : 'incomplete';
+  }
+  if (hasFail) {
+    planValidatedStatus = 'incomplete';
+  }
+
+  return { gates, reportStatus, planValidatedStatus, meta, body };
+}
+
+/**
+ * @param {object} params
+ * @returns {string}
+ */
+function buildPrevalidateReport(params) {
+  const { planPath, planName, actor, runAt, gates, planValidatedStatus, reportStatus } = params;
+  const lines = [
+    '# Plan pre-validation summary',
+    '',
+    '| Field | Value |',
+    '| --- | --- |',
+    `| **Plan** | \`${planName}\` |`,
+    `| **Stamp status** | \`${planValidatedStatus}\` |`,
+    `| **Report status** | \`${reportStatus || 'unknown'}\` |`,
+    `| **Run at** | ${runAt} |`,
+    `| **Validated by** | ${actor || '_not set_'} |`,
+    `| **Plan file** | \`${path.relative(REPO_ROOT, planPath)}\` |`,
+    '',
+    '## Gates',
+    '',
+    '| Gate | Result | Detail |',
+    '| --- | --- | --- |'
+  ];
+  for (const g of gates) {
+    lines.push(`| ${g.label} | ${g.status} | ${(g.detail || '').replace(/\|/g, '\\|')} |`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * @param {string} content
+ * @param {string} planBaseName
+ */
+function writePrevalidateReport(content, planBaseName) {
+  mkdirSync(PREVALIDATE_REPORT_DIR, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  writeFileSync(path.join(PREVALIDATE_REPORT_DIR, `${planBaseName}.${stamp}.md`), content, 'utf8');
+  writeFileSync(path.join(PREVALIDATE_REPORT_DIR, 'LATEST.md'), content, 'utf8');
+}
+
+module.exports = {
+  PREVALIDATE_REPORT_DIR,
+  runPrevalidateGates,
+  buildPrevalidateReport,
+  writePrevalidateReport,
+  hasHeading,
+  extractReportStatus,
+  isValidationStale
+};