@aifabrix/builder 2.49.2 → 2.51.0

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

package/scripts/pnpm/lib/dev-reload-core.mjs

@@ -0,0 +1,189 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveAifabrixBin } from './resolve-aifabrix-bin.mjs';
+import { resolveAppUrl } from './resolve-app-url.mjs';
+import { createSpinner } from './spinner.mjs';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const LOG_FILE = 'dev-reload.log';
+const CAPTURE_PID_FILE = 'dev-reload-capture.pid';
+
+/**
+ * @typedef {Object} DevReloadProfile
+ * @property {string} appKey
+ * @property {string} displayName
+ * @property {number} portBase
+ * @property {string} [webServerUrlEnvKey]
+ * @property {string} [healthPath]
+ * @property {boolean} [apiOnly]
+ * @property {string} [uiBuildCommand]
+ * @property {string} [uiOutputDir]
+ */
+
+/**
+ * @param {DevReloadProfile} profile
+ * @returns {Promise<void>}
+ */
+export async function runDevReload(profile) {
+  const logPath = prepareLogFile();
+  appendSessionBanner(profile.appKey, logPath);
+
+  const aifabrix = resolveAifabrixBin();
+  const spinner = createSpinner(`Starting ${profile.displayName} (live reload)…`);
+  spinner.start();
+
+  await runToLogFile(aifabrix, ['resolve', profile.appKey], logPath);
+  const runExit = await runToLogFile(aifabrix, ['run', profile.appKey, '--reload'], logPath);
+  if (runExit !== 0) {
+    spinner.stop();
+    printRunFailure(logPath);
+    process.exit(runExit);
+  }
+  spinner.stop();
+
+  startBackgroundLogCapture(profile.appKey, logPath);
+  printDevReloadSummary(profile, logPath);
+}
+
+/**
+ * @returns {string}
+ */
+function prepareLogFile() {
+  const logDir = path.join(repoRoot, '.temp');
+  fs.mkdirSync(logDir, { recursive: true });
+  const logPath = path.join(logDir, LOG_FILE);
+  fs.writeFileSync(logPath, '');
+  return logPath;
+}
+
+/**
+ * @returns {string}
+ */
+function capturePidPath() {
+  return path.join(repoRoot, '.temp', CAPTURE_PID_FILE);
+}
+
+function stopPreviousCapture() {
+  const pidPath = capturePidPath();
+  if (!fs.existsSync(pidPath)) {
+    return;
+  }
+  const pid = Number.parseInt(fs.readFileSync(pidPath, 'utf8').trim(), 10);
+  if (!pid) {
+    return;
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    // already stopped
+  }
+}
+
+/**
+ * @param {string} appKey
+ * @param {string} logPath
+ */
+function startBackgroundLogCapture(appKey, logPath) {
+  stopPreviousCapture();
+
+  const captureScript = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    'dev-reload-log-capture.mjs'
+  );
+  const child = spawn(process.execPath, [captureScript, appKey, logPath], {
+    cwd: repoRoot,
+    env: process.env,
+    detached: true,
+    stdio: 'ignore'
+  });
+  child.unref();
+  fs.writeFileSync(capturePidPath(), String(child.pid));
+}
+
+/**
+ * @param {DevReloadProfile} profile
+ * @param {string} logPath
+ */
+function printDevReloadSummary(profile, logPath) {
+  const appUrl = resolveAppUrl(profile, { repoRoot }).replace(/\/+$/, '');
+  const absLog = path.resolve(logPath);
+  const healthUrl = profile.healthPath ? `${appUrl}${profile.healthPath}` : `${appUrl}/`;
+
+  console.log('');
+  console.log('═'.repeat(60));
+  console.log(`  ${profile.displayName} — live reload (Docker)`);
+  console.log('═'.repeat(60));
+  console.log('');
+  console.log(`  App URL:  ${appUrl}/`);
+  if (profile.healthPath) {
+    console.log(`  Health:   ${healthUrl}`);
+  }
+  console.log(`  Logs:     ${absLog}`);
+  console.log('');
+  console.log('  Backend code on mounted paths reloads automatically.');
+  if (!profile.apiOnly && profile.uiBuildCommand && profile.uiOutputDir) {
+    console.log('');
+    console.log('  UI changes: run');
+    console.log(`    ${profile.uiBuildCommand}`);
+    console.log(`    → ${profile.uiOutputDir}`);
+  }
+  console.log('');
+  console.log('  Log capture runs in the background (this command exits).');
+  console.log('═'.repeat(60));
+  console.log('');
+}
+
+/**
+ * @param {string} logPath
+ */
+function printRunFailure(logPath) {
+  console.error(`\n[dev-reload] Start failed. Logs: ${path.resolve(logPath)}\n`);
+  if (!fs.existsSync(logPath)) {
+    return;
+  }
+  const lines = fs.readFileSync(logPath, 'utf8').trim().split('\n').filter(Boolean);
+  const tail = lines.slice(-15).join('\n');
+  if (tail) {
+    console.error(tail);
+    console.error('');
+  }
+}
+
+/**
+ * @param {string} appKey
+ * @param {string} logPath
+ */
+function appendSessionBanner(appKey, logPath) {
+  const banner =
+    `\n${'='.repeat(72)}\n` +
+    `[${new Date().toISOString()}] dev-reload session: ${appKey}\n` +
+    `${'='.repeat(72)}\n`;
+  fs.appendFileSync(logPath, banner);
+}
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {string} logPath
+ * @returns {Promise<number>}
+ */
+function runToLogFile(command, args, logPath) {
+  return new Promise((resolve) => {
+    const proc = spawn(command, args, {
+      cwd: repoRoot,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+
+    const append = (chunk) => {
+      fs.appendFileSync(logPath, chunk);
+    };
+
+    proc.stdout.on('data', append);
+    proc.stderr.on('data', append);
+    proc.on('close', (code) => resolve(typeof code === 'number' ? code : 1));
+    proc.on('error', () => resolve(1));
+  });
+}

package/scripts/pnpm/lib/dev-reload-log-capture.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Background log capture for dev-reload (detached child).
+ * Usage: node dev-reload-log-capture.mjs <appKey> <logPath>
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { resolveAifabrixBin } from './resolve-aifabrix-bin.mjs';
+import { resolveLogKeys } from './dev-reload-log-utils.mjs';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const appKey = process.argv[2];
+const logPath = process.argv[3];
+
+if (!appKey || !logPath) {
+  console.error('Usage: node dev-reload-log-capture.mjs <appKey> <logPath>');
+  process.exit(2);
+}
+
+const aifabrix = resolveAifabrixBin();
+const logKeys = resolveLogKeys(repoRoot, appKey);
+
+await Promise.all(
+  logKeys.map((key) => followAppLogsToFile(aifabrix, key, logPath, key === appKey))
+);
+
+/**
+ * @param {string} aifabrix
+ * @param {string} key
+ * @param {string} filePath
+ * @param {boolean} required
+ */
+function followAppLogsToFile(aifabrix, key, filePath, required) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(aifabrix, ['logs', key, '-f', '--tail', '100'], {
+      cwd: repoRoot,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+
+    const prefix = `[${key}] `;
+    const onLine = (line) => {
+      fs.appendFileSync(filePath, `${new Date().toISOString()} ${prefix}${line}\n`);
+    };
+
+    readline.createInterface({ input: proc.stdout }).on('line', onLine);
+    readline.createInterface({ input: proc.stderr }).on('line', onLine);
+
+    proc.on('close', (code) => {
+      if (code !== 0 && required) {
+        reject(new Error(`Log capture ended for ${key} (exit ${code ?? 1})`));
+        return;
+      }
+      resolve();
+    });
+    proc.on('error', (err) => {
+      if (required) {
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}

package/scripts/pnpm/lib/dev-reload-log-utils.mjs

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * @param {string} repoRoot
+ * @param {string} appKey
+ * @returns {string[]}
+ */
+export function resolveLogKeys(repoRoot, appKey) {
+  return [appKey, ...readCompanionKeys(repoRoot, appKey)];
+}
+
+/**
+ * @param {string} repoRoot
+ * @param {string} appKey
+ * @returns {string[]}
+ */
+function readCompanionKeys(repoRoot, appKey) {
+  const yamlPath = path.join(repoRoot, 'builder', appKey, 'application.yaml');
+  if (!fs.existsSync(yamlPath)) {
+    return [];
+  }
+  const text = fs.readFileSync(yamlPath, 'utf8');
+  if (!/^\s*worker:\s*true\s*$/m.test(text)) {
+    return [];
+  }
+  const companions = [`${appKey}-worker`];
+  if (/^\s*imageRunBeat:/m.test(text)) {
+    companions.push(`${appKey}-beat`);
+  }
+  return companions;
+}