@aifabrix/builder 2.49.2 → 2.51.0

package/scripts/lib/docker-image-content-gate-core.js

@@ -0,0 +1,166 @@
+/**
+ * Forbidden-path profiles for Docker image content gate (plan 154.3).
+ *
+ * @fileoverview Offline path checks + docker image listing
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+
+/** @type {readonly string[]} */
+const BUILDER_API_FORBIDDEN = [
+  '/app/.cursor',
+  '/app/builder',
+  '/app/integration',
+  '/app/tests',
+  '/app/docs',
+  '/app/scripts',
+  '/app/packages',
+  '/app/bin/aifabrix.js'
+];
+
+/** @type {readonly string[]} */
+const BUILDER_API_TEMPLATE_ALLOWED_PREFIXES = [
+  '/app/templates/openapi',
+  '/app/templates/external-system'
+];
+
+/**
+ * @param {string} profile
+ * @returns {string[]}
+ */
+function forbiddenPathsForProfile(profile) {
+  const normalized = String(profile || '').trim().toLowerCase();
+  if (normalized === 'builder-api') {
+    return [...BUILDER_API_FORBIDDEN];
+  }
+  throw new Error(`Unsupported profile: ${profile}`);
+}
+
+/**
+ * @param {string[]} pathsPresent
+ * @param {string[]} forbidden
+ * @returns {string[]}
+ */
+function findForbiddenPrefixViolations(pathsPresent, forbidden) {
+  const violations = [];
+  for (const forbiddenPath of forbidden) {
+    const prefix = forbiddenPath.replace(/\/$/, '');
+    for (const present of pathsPresent) {
+      const normalized = present.replace(/\/$/, '');
+      if (normalized === prefix || normalized.startsWith(`${prefix}/`)) {
+        violations.push(forbiddenPath);
+        break;
+      }
+    }
+  }
+  return violations;
+}
+
+/**
+ * @param {string} present
+ * @returns {boolean}
+ */
+function isAllowedBuilderApiTemplatePath(present) {
+  const normalized = present.replace(/\/$/, '');
+  if (normalized === '/app/templates') {
+    return true;
+  }
+  if (!normalized.startsWith('/app/templates')) {
+    return true;
+  }
+  return BUILDER_API_TEMPLATE_ALLOWED_PREFIXES.some((prefix) => (
+    normalized === prefix || normalized.startsWith(`${prefix}/`)
+  ));
+}
+
+/**
+ * @param {string[]} pathsPresent
+ * @returns {string[]}
+ */
+function findBuilderApiTemplateViolations(pathsPresent) {
+  const violations = [];
+  for (const present of pathsPresent) {
+    if (!isAllowedBuilderApiTemplatePath(present)) {
+      violations.push(present);
+    }
+  }
+  return violations;
+}
+
+/**
+ * @param {string[]} pathsPresent
+ * @returns {string[]}
+ */
+function findBuilderApiMarkdownViolations(pathsPresent) {
+  const violations = [];
+  for (const present of pathsPresent) {
+    if (!present.endsWith('.md')) {
+      continue;
+    }
+    if (present.startsWith('/app/lib/')) {
+      violations.push(present);
+    }
+  }
+  return violations;
+}
+
+/**
+ * @param {string} image
+ * @param {string} workdir
+ * @param {number} maxdepth
+ * @returns {string[]}
+ */
+function listImagePaths(image, workdir, maxdepth = 6) {
+  const proc = spawnSync(
+    'docker',
+    [
+      'run',
+      '--rm',
+      '--entrypoint',
+      'sh',
+      image,
+      '-c',
+      `find ${workdir} -mindepth 1 -maxdepth ${maxdepth} \\( -type d -o -type f \\) 2>/dev/null`
+    ],
+    { encoding: 'utf8' }
+  );
+  if (proc.status !== 0) {
+    throw new Error((proc.stderr || proc.stdout || '').trim() || `docker run failed for image ${image}`);
+  }
+  return proc.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * @param {string} image
+ * @param {string} profile
+ * @returns {string[]}
+ */
+function checkImage(image, profile) {
+  const normalized = String(profile || '').trim().toLowerCase();
+  const paths = listImagePaths(image, '/app');
+  const forbidden = forbiddenPathsForProfile(profile);
+  const violations = findForbiddenPrefixViolations(paths, forbidden);
+
+  if (normalized === 'builder-api') {
+    violations.push(...findBuilderApiTemplateViolations(paths));
+    violations.push(...findBuilderApiMarkdownViolations(paths));
+  }
+
+  return [...new Set(violations)].sort();
+}
+
+module.exports = {
+  BUILDER_API_FORBIDDEN,
+  BUILDER_API_TEMPLATE_ALLOWED_PREFIXES,
+  forbiddenPathsForProfile,
+  findForbiddenPrefixViolations,
+  isAllowedBuilderApiTemplatePath,
+  findBuilderApiTemplateViolations,
+  findBuilderApiMarkdownViolations,
+  listImagePaths,
+  checkImage
+};

package/scripts/lib/plan-actor.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Plan actor display name (~/.aifabrix/plan-actor.yaml, shared across repos).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '../..');
+const LEGACY_REPO_ACTOR_PATH = path.join(REPO_ROOT, '.aifabrix', 'plan-actor.yaml');
+
+/**
+ * @typedef {Object} PlanActor
+ * @property {string} displayName - Human-readable validator name for plan records
+ * @property {string} [email] - Optional contact email
+ */
+
+/**
+ * @returns {string} Absolute path to the shared ~/.aifabrix config directory
+ */
+function resolveAifabrixDir() {
+  if (process.env.AIFABRIX_HOME) {
+    return path.join(process.env.AIFABRIX_HOME, '.aifabrix');
+  }
+  return path.join(os.homedir(), '.aifabrix');
+}
+
+/**
+ * @returns {string} Absolute path to plan-actor.yaml (global or PLAN_ACTOR_PATH override)
+ */
+function resolveActorPath() {
+  if (process.env.PLAN_ACTOR_PATH) {
+    return process.env.PLAN_ACTOR_PATH;
+  }
+  return path.join(resolveAifabrixDir(), 'plan-actor.yaml');
+}
+
+/**
+ * One-time copy from repo-local `.aifabrix/plan-actor.yaml` when global file missing.
+ * @returns {void}
+ */
+function migrateLegacyActorIfNeeded() {
+  const actorPath = resolveActorPath();
+  if (fs.existsSync(actorPath) || !fs.existsSync(LEGACY_REPO_ACTOR_PATH)) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(actorPath), { recursive: true });
+  fs.copyFileSync(LEGACY_REPO_ACTOR_PATH, actorPath);
+}
+
+/**
+ * @returns {PlanActor|null} Parsed actor from disk, or null when file or displayName is missing
+ */
+function loadActor() {
+  migrateLegacyActorIfNeeded();
+  const actorPath = resolveActorPath();
+  if (!fs.existsSync(actorPath)) {
+    return null;
+  }
+  const raw = fs.readFileSync(actorPath, 'utf8');
+  const nameMatch = raw.match(/^displayName:\s*"?([^"\n]+)"?\s*$/m);
+  const emailMatch = raw.match(/^email:\s*"?([^"\n]+)"?\s*$/m);
+  if (!nameMatch) {
+    return null;
+  }
+  const actor = { displayName: nameMatch[1].trim() };
+  if (emailMatch) {
+    actor.email = emailMatch[1].trim();
+  }
+  return actor;
+}
+
+/**
+ * @param {string} displayName - Validator display name written to plan-actor.yaml
+ * @param {string} [email] - Optional email stored alongside the display name
+ * @returns {string} Absolute path to the written plan-actor.yaml file
+ */
+function saveActor(displayName, email) {
+  const actorPath = resolveActorPath();
+  fs.mkdirSync(path.dirname(actorPath), { recursive: true });
+  const lines = [`displayName: ${JSON.stringify(displayName)}`];
+  if (email) {
+    lines.push(`email: ${JSON.stringify(email)}`);
+  }
+  fs.writeFileSync(actorPath, `${lines.join('\n')}\n`, 'utf8');
+  return actorPath;
+}
+
+/**
+ * @param {string} [overrideName] - CLI or env override; skips reading plan-actor.yaml when set
+ * @returns {PlanActor|null} Override actor, loaded actor, or null when none is configured
+ */
+function resolveActor(overrideName) {
+  if (overrideName) {
+    return { displayName: overrideName };
+  }
+  return loadActor();
+}
+
+module.exports = {
+  ACTOR_PATH: resolveActorPath(),
+  resolveActorPath,
+  loadActor,
+  saveActor,
+  resolveActor,
+  migrateLegacyActorIfNeeded
+};

package/scripts/lib/plan-config.js

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Plan lifecycle paths and gate policy (builder).
+ */
+
+'use strict';
+
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '../..');
+const PLANS_DIR = path.join(REPO_ROOT, '.cursor/plans');
+
+module.exports = {
+  REPO_ROOT,
+  PLANS_DIR,
+  DONE_DIR: path.join(PLANS_DIR, 'Done'),
+  REPORT_DIR: path.join(REPO_ROOT, 'temp/plan-validation'),
+  REQUIRED_SKILLS: ['builder-validate-implementation'],
+  STRICT_FRONTMATTER: false,
+  REQUIRE_APPROVAL_TO_ARCHIVE: true
+};

package/scripts/lib/plan-gates.js

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Plan quality gates (miso / builder — config-driven).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { loadPlanFile, hasSurface } = require('./plan-parse');
+const { REQUIRED_SKILLS, STRICT_FRONTMATTER, REPO_ROOT } = require('./plan-config');
+
+const SKILLS_DIR = path.join(REPO_ROOT, '.cursor/skills');
+
+/**
+ * @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 };
+}
+
+/**
+ * @returns {GateResult}
+ */
+function gateSkills() {
+  if (!REQUIRED_SKILLS.length) {
+    return gate('skills', 'skip', 'none configured');
+  }
+  const missing = REQUIRED_SKILLS.filter(
+    (name) => !fs.existsSync(path.join(SKILLS_DIR, name, 'SKILL.md'))
+  );
+  if (missing.length) {
+    return gate('skills', 'fail', `missing: ${missing.join(', ')}`);
+  }
+  return gate('skills', 'pass');
+}
+
+/**
+ * @param {Record<string, unknown>} meta
+ * @returns {GateResult}
+ */
+function gatePlanFrontmatter(meta) {
+  const errors = [];
+  const warns = [];
+  if (!meta.name && !meta.overview) {
+    errors.push('name or overview');
+  }
+  if (!Array.isArray(meta.todos) || meta.todos.length === 0) {
+    errors.push('todos');
+  }
+  if (STRICT_FRONTMATTER) {
+    if (!meta.name) {
+      errors.push('name');
+    }
+    if (!meta.overview) {
+      errors.push('overview');
+    }
+    if (!meta.status) {
+      errors.push('status');
+    }
+    if (!meta.planType) {
+      errors.push('planType');
+    }
+    if (!meta.createdBy) {
+      errors.push('createdBy');
+    }
+    if (meta.planType === 'code' && !Array.isArray(meta.surfaces)) {
+      errors.push('surfaces');
+    }
+  } else if (!meta.createdBy) {
+    warns.push('createdBy');
+  }
+  if (errors.length) {
+    return gate('plan-frontmatter', 'fail', `missing: ${errors.join(', ')}`);
+  }
+  if (warns.length) {
+    return gate('plan-frontmatter', 'warn', `missing: ${warns.join(', ')}`);
+  }
+  return gate('plan-frontmatter', 'pass');
+}
+
+/**
+ * @param {Record<string, unknown>} meta
+ * @returns {GateResult}
+ */
+function gateApiTier(meta) {
+  if (!hasSurface(meta, 'api')) {
+    return gate('api-tier', 'skip', 'no api surface');
+  }
+  const tiers = meta.apiTiers;
+  if (!Array.isArray(tiers) || tiers.length === 0) {
+    return gate('api-tier', 'warn', 'api surface without apiTiers');
+  }
+  return gate('api-tier', 'pass');
+}
+
+/**
+ * @param {Array<{ id: string, status: string, content: string }>} todos
+ */
+function auditTodos(todos) {
+  const blockingPending = todos.filter(
+    (t) => t.status === 'pending' || t.status === 'in_progress'
+  );
+  const manualPending = todos.filter(
+    (t) =>
+      (t.status === 'pending' || t.status === 'in_progress') &&
+      /manual|pilot|proof|e2e smoke|live test|business validation/i.test(t.content)
+  );
+  return { blockingPending, manualPending };
+}
+
+/**
+ * @param {string} planPath
+ */
+function runAllGates(planPath) {
+  const loaded = loadPlanFile(planPath);
+  if (!loaded) {
+    return {
+      gates: [gate('plan-parse', 'fail', 'invalid frontmatter')],
+      todos: [],
+      blockingPending: [],
+      manualPending: []
+    };
+  }
+
+  const { meta } = loaded;
+  const todos = Array.isArray(meta.todos) ? meta.todos : [];
+  const gates = [
+    gateSkills(),
+    gatePlanFrontmatter(meta),
+    gateApiTier(meta),
+    gate('todos', todos.length ? 'pass' : 'fail', `${todos.length} todo(s)`)
+  ];
+
+  const { blockingPending, manualPending } = auditTodos(
+    todos.map((t) => ({
+      id: String(t.id || ''),
+      status: String(t.status || 'pending'),
+      content: String(t.content || '')
+    }))
+  );
+
+  return { gates, todos, blockingPending, manualPending };
+}
+
+module.exports = {
+  runAllGates
+};

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 = JSON.stringify(String(value));
+  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
+};