@aifabrix/builder 2.52.0 → 2.53.0

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

@@ -1,125 +0,0 @@
-/**
- * @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

@@ -1,119 +0,0 @@
-/**
- * @fileoverview Plan run report writer (shared).
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { REPORT_DIR } = require('./plan-config');
-
-/**
- * @param {unknown} value
- * @returns {string}
- */
-function escapeMarkdownCell(value) {
-  return String(value ?? '')
-    .replace(/\r?\n+/g, ' ')
-    .replace(/\|/g, '\\|')
-    .trim();
-}
-
-/**
- * @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(`| ${escapeMarkdownCell(g.label)} | ${icon} | ${escapeMarkdownCell(g.detail || '')} |`);
-  }
-
-  lines.push('', '## Todos', '', '| ID | Status | Content |', '| --- | --- | --- |');
-  for (const t of todos) {
-    lines.push(
-      `| ${escapeMarkdownCell(t.id)} | ${escapeMarkdownCell(t.status)} | ${escapeMarkdownCell(t.content).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

@@ -1,24 +0,0 @@
-#!/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

@@ -1,49 +0,0 @@
-#!/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

@@ -1,13 +0,0 @@
-#!/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

@@ -1,21 +0,0 @@
-#!/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

@@ -1,80 +0,0 @@
-#!/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

@@ -1,110 +0,0 @@
-#!/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

@@ -1,32 +0,0 @@
-#!/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

@@ -1,29 +0,0 @@
-#!/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

@@ -1,18 +0,0 @@
-#!/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

@@ -1,55 +0,0 @@
-#!/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);
-}