@aifabrix/builder 2.49.2 → 2.50.0

package/scripts/lib/builder-api-docker-staging-core.js

@@ -0,0 +1,183 @@
+/**
+ * Runtime file discovery for builder-api Docker staging (plan 154.3).
+ *
+ * @fileoverview Require-graph walk + supplemental runtime assets
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRE_RE = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+/** @type {readonly string[]} */
+const ENTRY_FILES = ['bin/builder-api-spike.js', 'bin/builder-api-cleanup.js'];
+
+/** @type {readonly string[]} */
+const STAGING_SKIP_FILES = ['package.json', 'package-lock.json'];
+
+/** @type {readonly string[]} */
+const SUPPLEMENTAL_DIRS = [
+  'lib/schema',
+  'lib/programmatic/help-content',
+  'templates/openapi',
+  'templates/external-system',
+  'lib/datasource/capability/templates'
+];
+
+/** @type {readonly string[]} */
+const MANIFEST_FORBIDDEN_PREFIXES = [
+  'templates/applications/',
+  'templates/github/',
+  'templates/infra/',
+  'templates/python/',
+  'templates/typescript/',
+  'templates/channels/',
+  'integration/',
+  'tests/',
+  'scripts/',
+  '.cursor/',
+  'builder/',
+  'packages/',
+  'docs/',
+  'bin/aifabrix.js',
+  'lib/cli/'
+];
+
+/**
+ * @param {string} repoRoot
+ * @param {string} fromFile
+ * @param {string} req
+ * @returns {string|null}
+ */
+function resolveRelativeRequire(repoRoot, fromFile, req) {
+  if (!req.startsWith('.')) {
+    return null;
+  }
+  const base = path.dirname(fromFile);
+  let resolved = path.resolve(repoRoot, base, req);
+  if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+    resolved = path.join(resolved, 'index.js');
+  }
+  if (!resolved.endsWith('.js') && fs.existsSync(`${resolved}.js`)) {
+    resolved = `${resolved}.js`;
+  }
+  if (!fs.existsSync(resolved)) {
+    return null;
+  }
+  return path.relative(repoRoot, resolved).split(path.sep).join('/');
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {string} relFile
+ * @returns {string[]}
+ */
+function collectRequiresFromFile(repoRoot, relFile) {
+  const abs = path.join(repoRoot, relFile);
+  const content = fs.readFileSync(abs, 'utf8');
+  const found = [];
+  let match;
+  while ((match = REQUIRE_RE.exec(content)) !== null) {
+    const target = resolveRelativeRequire(repoRoot, relFile, match[1]);
+    if (target) {
+      found.push(target);
+    }
+  }
+  return found;
+}
+
+/**
+ * @param {string} dir
+ * @param {string} repoRoot
+ * @param {Set<string>} out
+ * @returns {void}
+ */
+function addDirectoryFiles(dir, repoRoot, out) {
+  const abs = path.join(repoRoot, dir);
+  if (!fs.existsSync(abs)) {
+    return;
+  }
+  for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+    const rel = path.join(dir, entry.name).split(path.sep).join('/');
+    if (entry.isDirectory()) {
+      addDirectoryFiles(rel, repoRoot, out);
+      continue;
+    }
+    out.add(rel);
+  }
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {string[]}
+ */
+function discoverRuntimeFiles(repoRoot) {
+  const seen = new Set();
+  const queue = [...ENTRY_FILES];
+
+  while (queue.length > 0) {
+    const rel = queue.shift();
+    if (!rel || seen.has(rel)) {
+      continue;
+    }
+    if (!fs.existsSync(path.join(repoRoot, rel))) {
+      continue;
+    }
+    seen.add(rel);
+    for (const next of collectRequiresFromFile(repoRoot, rel)) {
+      if (!seen.has(next)) {
+        queue.push(next);
+      }
+    }
+  }
+
+  for (const dir of SUPPLEMENTAL_DIRS) {
+    addDirectoryFiles(dir, repoRoot, seen);
+  }
+
+  return [...seen].sort().filter((rel) => !STAGING_SKIP_FILES.includes(rel));
+}
+
+/**
+ * @param {string} relPath
+ * @returns {boolean}
+ */
+function isForbiddenManifestPath(relPath) {
+  const normalized = relPath.split(path.sep).join('/');
+  for (const prefix of MANIFEST_FORBIDDEN_PREFIXES) {
+    if (normalized === prefix.replace(/\/$/, '') || normalized.startsWith(prefix)) {
+      return true;
+    }
+  }
+  if (normalized.endsWith('.md') && normalized.startsWith('lib/')) {
+    if (normalized.startsWith('lib/programmatic/help-content/')) {
+      return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string[]} manifest
+ * @returns {string[]}
+ */
+function findManifestViolations(manifest) {
+  return manifest.filter(isForbiddenManifestPath);
+}
+
+module.exports = {
+  ENTRY_FILES,
+  SUPPLEMENTAL_DIRS,
+  MANIFEST_FORBIDDEN_PREFIXES,
+  STAGING_SKIP_FILES,
+  discoverRuntimeFiles,
+  findManifestViolations,
+  isForbiddenManifestPath,
+  resolveRelativeRequire,
+  collectRequiresFromFile
+};

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: "${displayName.replace(/"/g, '\\"')}"`];
+  if (email) {
+    lines.push(`email: "${email.replace(/"/g, '\\"')}"`);
+  }
+  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
+};