@aifabrix/builder 2.49.1 → 2.50.0

package/scripts/lib/plan-run-core.js

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Plan run and archive core (miso / builder).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { DONE_DIR, REQUIRE_APPROVAL_TO_ARCHIVE } = require('./plan-config');
+const { resolvePlanPath, patchPlanMeta, die } = require('./plan-meta');
+const { loadPlanFile } = require('./plan-parse');
+const { runAllGates } = require('./plan-gates');
+const { buildSummaryMarkdown, writeReport } = require('./plan-run-report');
+const { resolveActor } = require('./plan-actor');
+
+/**
+ * @param {import('./plan-gates').GateResult[]} gates
+ */
+function gatesPassing(gates) {
+  return gates.filter((g) => g.status === 'fail').length === 0;
+}
+
+/**
+ * @param {string} planInput
+ * @param {{ actorName?: string }} [opts]
+ */
+function runPlan(planInput, opts = {}) {
+  const planPath = resolvePlanPath(planInput);
+  const actorInfo = resolveActor(opts.actorName);
+  const runAt = new Date().toISOString();
+  const planName = path.basename(planPath, '.plan.md');
+  console.log(`Validating: ${planName}\n`);
+
+  const result = runAllGates(planPath);
+
+  let overallStatus = 'PASS';
+  if (!gatesPassing(result.gates)) {
+    overallStatus = 'FAIL';
+  } else if (result.gates.some((g) => g.status === 'warn')) {
+    overallStatus = 'PASS_WITH_WARNINGS';
+  }
+  if (result.blockingPending.length) {
+    overallStatus = 'FAIL';
+  }
+
+  for (const g of result.gates) {
+    const prefix =
+      g.status === 'pass' ? '✔' : g.status === 'warn' ? '⚠' : g.status === 'skip' ? '○' : '✖';
+    console.log(`${prefix} ${g.label}${g.detail ? ` — ${g.detail}` : ''}`);
+  }
+
+  const summary = buildSummaryMarkdown({
+    planPath,
+    planName,
+    actor: actorInfo?.displayName,
+    runAt,
+    gates: result.gates,
+    todos: result.todos,
+    blockingPending: result.blockingPending,
+    manualPending: result.manualPending,
+    overallStatus
+  });
+  writeReport(summary, planName);
+
+  if (!gatesPassing(result.gates) || result.blockingPending.length) {
+    process.exit(1);
+  }
+
+  return { planPath, planName, summary, overallStatus };
+}
+
+/**
+ * @param {string} planInput
+ * @param {string} [summary]
+ * @param {{ allowUnapproved?: boolean }} [opts]
+ */
+function archivePlan(planInput, summary, opts = {}) {
+  const planPath = resolvePlanPath(planInput);
+  const planName = path.basename(planPath, '.plan.md');
+  const loaded = loadPlanFile(planPath);
+  if (
+    REQUIRE_APPROVAL_TO_ARCHIVE &&
+    loaded &&
+    !loaded.meta.approvedBy &&
+    !opts.allowUnapproved
+  ) {
+    die('Plan not approved — run plan-approve first or use --allow-unapproved');
+  }
+
+  fs.mkdirSync(DONE_DIR, { recursive: true });
+  const dest = path.join(DONE_DIR, path.basename(planPath));
+  if (fs.existsSync(dest)) {
+    die(`Already archived: ${dest}`);
+  }
+  fs.renameSync(planPath, dest);
+  if (summary) {
+    fs.writeFileSync(path.join(DONE_DIR, `${planName}.validation.md`), summary, 'utf8');
+  }
+  console.log(`✔ Archived → ${dest}`);
+  return dest;
+}
+
+/**
+ * @param {string} planInput
+ * @param {string} [actorOverride]
+ */
+function approvePlan(planInput, actorOverride) {
+  const planPath = resolvePlanPath(planInput);
+  const actor = resolveActor(actorOverride);
+  const name = actor?.displayName || actorOverride;
+  if (!name) {
+    die('Set actor first: node scripts/plan-set-actor.js "Your Name"');
+  }
+  const today = new Date().toISOString().slice(0, 10);
+  patchPlanMeta(planPath, 'approvedBy', name);
+  patchPlanMeta(planPath, 'approvedAt', today);
+  patchPlanMeta(planPath, 'status', 'approved');
+  console.log(`✔ Approved ${path.basename(planPath)} by ${name} on ${today}`);
+}
+
+module.exports = {
+  runPlan,
+  archivePlan,
+  approvePlan
+};

package/scripts/lib/plan-run-report.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Plan run report writer (shared).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { REPORT_DIR } = require('./plan-config');
+
+/**
+ * @param {object} params
+ * @returns {string}
+ */
+function buildSummaryMarkdown(params) {
+  const {
+    planPath,
+    planName,
+    actor,
+    runAt,
+    gates,
+    todos,
+    blockingPending,
+    manualPending,
+    overallStatus
+  } = params;
+
+  const lines = [
+    '# Plan validation summary',
+    '',
+    '| Field | Value |',
+    '| --- | --- |',
+    `| **Plan** | \`${planName}\` |`,
+    `| **Status** | **${overallStatus}** |`,
+    `| **Run at** | ${runAt} |`,
+    `| **Validated by** | ${actor || '_not set_'} |`,
+    `| **Plan file** | \`${planPath}\` |`,
+    '',
+    '## Quality gates',
+    '',
+    '| Gate | Result | Detail |',
+    '| --- | --- | --- |'
+  ];
+
+  for (const g of gates) {
+    const icon = g.status === 'pass' ? 'pass' : g.status === 'warn' ? 'warn' : 'FAIL';
+    lines.push(`| ${g.label} | ${icon} | ${(g.detail || '').replace(/\|/g, '\\|')} |`);
+  }
+
+  lines.push('', '## Todos', '', '| ID | Status | Content |', '| --- | --- | --- |');
+  for (const t of todos) {
+    lines.push(
+      `| ${t.id} | ${t.status} | ${String(t.content).replace(/\|/g, '\\|').slice(0, 100)} |`
+    );
+  }
+
+  if (blockingPending.length) {
+    lines.push('', '### Blocking', '');
+    for (const t of blockingPending) {
+      lines.push(`- **${t.id}**: ${t.content}`);
+    }
+  }
+  if (manualPending.length) {
+    lines.push('', '### Manual (non-blocking)', '');
+    for (const t of manualPending) {
+      lines.push(`- **${t.id}**: ${t.content}`);
+    }
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * @param {string} content
+ * @param {string} planBaseName
+ */
+function writeReport(content, planBaseName) {
+  fs.mkdirSync(REPORT_DIR, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  fs.writeFileSync(path.join(REPORT_DIR, `${planBaseName}.${stamp}.md`), content, 'utf8');
+  fs.writeFileSync(path.join(REPORT_DIR, 'LATEST.md'), content, 'utf8');
+  console.log('Report: temp/plan-validation/LATEST.md');
+}
+
+/**
+ * @param {string} planBaseName
+ * @returns {{ summary: string, overallStatus: string } | null}
+ */
+function readLatestReportForPlan(planBaseName) {
+  const latest = path.join(REPORT_DIR, 'LATEST.md');
+  if (!fs.existsSync(latest)) {
+    return null;
+  }
+  const summary = fs.readFileSync(latest, 'utf8');
+  const planMatch = summary.match(/\|\s*\*\*Plan\*\*\s*\|\s*`([^`]+)`\s*\|/);
+  if (!planMatch || planMatch[1] !== planBaseName) {
+    return null;
+  }
+  const statusMatch = summary.match(/\|\s*\*\*Status\*\*\s*\|\s*\*\*([^*]+)\*\*\s*\|/);
+  const overallStatus = statusMatch ? statusMatch[1].trim() : '';
+  return { summary, overallStatus };
+}
+
+module.exports = {
+  buildSummaryMarkdown,
+  writeReport,
+  readLatestReportForPlan
+};

package/scripts/plan-approve.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+'use strict';
+
+const { resolvePlanPath, patchPlanMeta, die } = require('./lib/plan-meta');
+const { resolveActor } = require('./lib/plan-actor');
+
+const planInput = process.argv[2];
+if (!planInput) {
+  die('Usage: node scripts/plan-approve.js <plan-path-or-id>');
+}
+
+const planPath = resolvePlanPath(planInput);
+const actor = resolveActor(process.argv[3]);
+const name = actor?.displayName || process.argv[3];
+if (!name) {
+  die('Set actor first via /validate-implementation (plan-set-actor)');
+}
+
+const today = new Date().toISOString().slice(0, 10);
+patchPlanMeta(planPath, 'approvedBy', name);
+patchPlanMeta(planPath, 'approvedAt', today);
+patchPlanMeta(planPath, 'status', 'approved');
+console.log(`✔ Approved ${planPath} by ${name} on ${today}`);

package/scripts/plan-archive.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+'use strict';
+
+const { runPlan, archivePlan } = require('./lib/plan-run-core');
+const { resolvePlanPath } = require('./lib/plan-meta');
+const { readLatestReportForPlan } = require('./lib/plan-run-report');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const planInput = args.find((a) => !a.startsWith('--'));
+const allowUnapproved = args.includes('--allow-unapproved');
+const revalidate = args.includes('--revalidate');
+
+if (!planInput) {
+  console.error(
+    'Usage: node scripts/plan-archive.js <plan-path-or-id> [--allow-unapproved] [--revalidate]'
+  );
+  process.exit(1);
+}
+
+const planPath = resolvePlanPath(planInput);
+const planName = path.basename(planPath, '.plan.md');
+
+let summary = '';
+let runSummary = '';
+
+if (!revalidate) {
+  const cached = readLatestReportForPlan(planName);
+  if (cached) {
+    if (cached.overallStatus !== 'PASS' && cached.overallStatus !== 'PASS_WITH_WARNINGS') {
+      console.error(
+        `Latest report for ${planName} is ${cached.overallStatus} — run plan-run.js or use --revalidate after fixing`
+      );
+      process.exit(1);
+    }
+    summary = cached.summary;
+    console.log('Using cached report: temp/plan-validation/LATEST.md');
+  }
+}
+
+if (!summary) {
+  const result = runPlan(planInput);
+  runSummary = result.summary;
+  summary = runSummary;
+}
+
+archivePlan(planPath, summary, { allowUnapproved });
+console.log(`Plan archived: ${planName}`);

package/scripts/plan-run.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+'use strict';
+
+const { runPlan } = require('./lib/plan-run-core');
+
+const planInput = process.argv[2];
+if (!planInput) {
+  console.error('Usage: node scripts/plan-run.js <plan-path-or-id>');
+  process.exit(1);
+}
+
+runPlan(planInput);

package/scripts/plan-set-actor.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * Save plan validator display name to ~/.aifabrix/plan-actor.yaml (shared across repos).
+ *
+ * @example node scripts/plan-set-actor.js "Your Name"
+ */
+
+'use strict';
+
+const { saveActor } = require('./lib/plan-actor');
+
+const name = process.argv.slice(2).join(' ').trim();
+if (!name) {
+  console.error('Usage: node scripts/plan-set-actor.js "Your Name"');
+  process.exit(1);
+}
+
+const actorPath = saveActor(name);
+console.log(`✔ Saved actor: ${name}`);
+console.log(`  ${actorPath}`);

package/scripts/plan-validate.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/* eslint-disable no-console, require-jsdoc, valid-jsdoc, max-statements, complexity */
+'use strict';
+
+const path = require('path');
+const { resolvePlanPath, patchPlanMeta, die } = require('./lib/plan-meta');
+const { resolveActor } = require('./lib/plan-actor');
+const {
+  runPrevalidateGates,
+  buildPrevalidateReport,
+  writePrevalidateReport
+} = require('./lib/plan-prevalidate-gates');
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const allowNeedsUpdates = args.includes('--allow-needs-updates');
+const actorIdx = args.indexOf('--actor');
+const actorOverride = actorIdx >= 0 ? args[actorIdx + 1] : undefined;
+const planInput = args.find((a, i) => {
+  if (a.startsWith('--')) {
+    return false;
+  }
+  if (actorIdx >= 0 && (i === actorIdx || i === actorIdx + 1)) {
+    return false;
+  }
+  return true;
+});
+
+if (!planInput) {
+  die('Usage: node scripts/plan-validate.js <plan-path-or-id> [--dry-run] [--allow-needs-updates] [--actor Name]');
+}
+
+const planPath = resolvePlanPath(planInput);
+const actorInfo = resolveActor(actorOverride);
+if (!actorInfo && !dryRun) {
+  die('Set actor first: node scripts/plan-set-actor.js "Your Name" (or pass --actor)');
+}
+
+const result = runPrevalidateGates(planPath, { allowNeedsUpdates });
+const planName = path.basename(planPath, '.plan.md');
+const runAt = new Date().toISOString();
+const actor = actorInfo?.displayName;
+
+for (const g of result.gates) {
+  const prefix =
+    g.status === 'pass' ? '✔' : g.status === 'warn' ? '⚠' : g.status === 'skip' ? '○' : '✖';
+  console.log(`${prefix} ${g.label}${g.detail ? ` — ${g.detail}` : ''}`);
+}
+
+writePrevalidateReport(
+  buildPrevalidateReport({
+    planPath,
+    planName,
+    actor,
+    runAt,
+    gates: result.gates,
+    planValidatedStatus: result.planValidatedStatus,
+    reportStatus: result.reportStatus
+  }),
+  planName
+);
+console.log('Report: temp/plan-prevalidation/LATEST.md');
+
+const canStamp =
+  result.planValidatedStatus === 'validated' ||
+  (allowNeedsUpdates && result.planValidatedStatus === 'needs-updates');
+
+if (!dryRun && canStamp && actor) {
+  const today = new Date().toISOString().slice(0, 10);
+  patchPlanMeta(planPath, 'planValidatedStatus', result.planValidatedStatus);
+  patchPlanMeta(planPath, 'lastValidatedBy', actor);
+  patchPlanMeta(planPath, 'lastValidatedAt', today);
+  console.log(`✔ Stamped ${planName}: ${result.planValidatedStatus} by ${actor} on ${today}`);
+} else if (!dryRun && result.planValidatedStatus === 'validated' && !actor) {
+  die('Cannot stamp validated plan without actor');
+}
+
+if (result.planValidatedStatus !== 'validated') {
+  process.exit(1);
+}

package/scripts/pnpm/af.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * aifabrix builder passthrough for builder-api (this repo).
+ * Usage: pnpm run af <subcommand>  |  npm run af -- <subcommand>
+ */
+import { spawn } from 'node:child_process';
+import { resolveAifabrixBin } from './lib/resolve-aifabrix-bin.mjs';
+
+const AIFABRIX_BIN = resolveAifabrixBin();
+
+const USAGE = `Usage: pnpm run af <subcommand>
+
+Subcommands:
+  ba-resolve      aifabrix resolve builder-api
+  ba-run          aifabrix run builder-api
+  ba-reload       aifabrix run builder-api --reload
+  ba-logs         aifabrix logs builder-api
+  ba-down         aifabrix down-app builder-api
+  ba-build        aifabrix build builder-api
+  dev-build       ba-build then ba-run (local Docker image)
+  dev-reload      Docker live reload (spinner + URL + .temp/dev-reload.log)
+  dev-promote     build --base --from-dev + run --base (global image; TAG=1.9.5 pnpm run dev-promote)
+`;
+
+const COMMANDS = {
+  'ba-resolve': [AIFABRIX_BIN, 'resolve', 'builder-api'],
+  'ba-run': [AIFABRIX_BIN, 'run', 'builder-api'],
+  'ba-reload': [AIFABRIX_BIN, 'run', 'builder-api', '--reload'],
+  'ba-logs': [AIFABRIX_BIN, 'logs', 'builder-api'],
+  'ba-down': [AIFABRIX_BIN, 'down-app', 'builder-api'],
+  'ba-build': [AIFABRIX_BIN, 'build', 'builder-api']
+};
+
+async function runDevBuild() {
+  await runCommand(COMMANDS['ba-build']);
+  await runCommand(COMMANDS['ba-run']);
+}
+
+function resolvePromoteTag() {
+  const fromArg = process.argv[3];
+  const tag = (process.env.TAG || fromArg || '').trim();
+  if (!tag || tag === 'latest') {
+    return null;
+  }
+  return tag;
+}
+
+async function runDevPromote() {
+  const tag = resolvePromoteTag();
+  if (tag) {
+    await runCommand([AIFABRIX_BIN, 'build', 'builder-api', '--base', '--from-dev', '--tag', tag]);
+    await runCommand([AIFABRIX_BIN, 'run', 'builder-api', '--base', '--tag', tag]);
+    return;
+  }
+  await runCommand([AIFABRIX_BIN, 'build', 'builder-api', '--base', '--from-dev']);
+  await runCommand([AIFABRIX_BIN, 'run', 'builder-api', '--base']);
+}
+
+function runCommand(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(args[0], args.slice(1), { stdio: 'inherit', shell: false });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`${args.join(' ')} exited with code ${code}`));
+    });
+  });
+}
+
+async function main() {
+  const sub = process.argv[2];
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.error(USAGE);
+    process.exit(sub ? 0 : 1);
+  }
+  if (sub === 'dev-build') {
+    await runDevBuild();
+    return;
+  }
+  if (sub === 'dev-reload') {
+    const { runDevReload } = await import('./lib/dev-reload-core.mjs');
+    await runDevReload({
+      appKey: 'builder-api',
+      displayName: 'Builder API',
+      portBase: 3005,
+      healthPath: '/api/v1/builder/health',
+      apiOnly: true
+    });
+    return;
+  }
+  if (sub === 'dev-promote') {
+    await runDevPromote();
+    return;
+  }
+  const args = COMMANDS[sub];
+  if (!args) {
+    console.error(`Unknown af subcommand: ${sub}\n`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+  await runCommand(args);
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/scripts/pnpm/check-quiet.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Offline pre-commit gate — same as build:ci; logs in .temp/validation/
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const logDir = path.join(repoRoot, '.temp', 'validation');
+const logFile = path.join(logDir, 'build-ci.log');
+
+fs.mkdirSync(logDir, { recursive: true });
+console.log(`[check-quiet] Running build:ci (logs → ${logFile})`);
+
+const result = spawnSync('npm', ['run', 'build:ci'], {
+  cwd: repoRoot,
+  env: process.env,
+  encoding: 'utf8'
+});
+
+const output = `${result.stdout || ''}${result.stderr || ''}`;
+fs.writeFileSync(logFile, output, 'utf8');
+
+if (result.status === 0) {
+  console.log('[check-quiet] ✓ passed');
+  process.exit(0);
+}
+
+console.error(`[check-quiet] ✗ failed — see ${logFile}`);
+process.exit(result.status ?? 1);

package/scripts/pnpm/dev-install.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Bootstrap builder repo deps and link local aifabrix CLI from bin/aifabrix.js.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+/**
+ * @param {string} label
+ * @param {string} command
+ * @param {string[]} args
+ */
+function runStep(label, command, args) {
+  console.log(`[dev-install] ${label}`);
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    stdio: 'inherit',
+    env: process.env
+  });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+runStep('npm install', 'npm', ['install']);
+runStep('link local CLI (install:local)', 'npm', ['run', 'install:local']);

package/scripts/pnpm/dev-reload.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Docker live reload for builder-api — quiet console, logs in .temp/dev-reload.log
+ *
+ * Equivalent to: aifabrix resolve builder-api && aifabrix run builder-api --reload
+ */
+import { runDevReload } from './lib/dev-reload-core.mjs';
+
+runDevReload({
+  appKey: 'builder-api',
+  displayName: 'Builder API',
+  portBase: 3005,
+  healthPath: '/api/v1/builder/health',
+  apiOnly: true
+}).catch((err) => {
+  console.error(`[dev-reload] ${err.message || err}`);
+  process.exit(1);
+});

package/scripts/pnpm/help.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+const showAll = process.argv.includes('--all');
+
+const publicSections = [
+  {
+    title: 'Start here (80/20)',
+    lines: [
+      'aifabrix setup     → once (any directory)',
+      'dev-install        → after clone (npm install + install:local)',
+      'dev-reload         → daily (Docker live reload)',
+      'check-quiet        → before commit (build:ci → .temp/validation/)',
+      'Full guide: QUICK-START.md'
+    ]
+  },
+  {
+    title: 'Sometimes',
+    lines: [
+      'dev                → builder-api on host (aifabrix resolve builder-api first)',
+      'ui-build           → N/A (no UI in this repo)',
+      'check              → lint + test (fast, not full CI)',
+      'pnpm run af ba-logs | ba-down'
+    ]
+  }
+];
+
+const advancedLines = [
+  '--- Advanced (help -- --all) ---',
+  'dev-build / dev-promote / af ba-*',
+  'build:ci           → lint + schema-sync + flags + test:ci (same as GitHub)',
+  'sync-json          → publish builder/builder-api → templates/',
+  'test:154           → builder-api scoped Jest + arch grep',
+  'test:manual        → live API tests (aifabrix login first)',
+  'test:integration   → integration fixtures (TEST_LANGUAGE=python|typescript optional)',
+  'test:hubspot-wizard [-- --type negative|positive]',
+  'docker-image-gate-builder-api',
+  'builder-api:build | builder-api:nest | builder-api:cleanup',
+  'install:global / uninstall:global / diagnose:cli',
+  'Docs: docs/development/pnpm-commands.md'
+];
+
+console.log('AI Fabrix Builder — pnpm commands\n');
+for (const section of publicSections) {
+  console.log(section.title);
+  for (const line of section.lines) {
+    console.log(`  ${line}`);
+  }
+  console.log('');
+}
+if (!showAll) {
+  console.log('Run: pnpm run help -- --all');
+  process.exit(0);
+}
+for (const line of advancedLines) {
+  console.log(line);
+}