@hybridlabor-api/aos 4.13.1 → 4.14.0

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/index.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * BDB Plan Builder — turn an Agent-Native-style plan folder into ONE
+ * self-contained HTML file in the BDB look, which `aos-plan-canvas` then opens
+ * through the normal `.html` artifact path (annotation, chat and verdict all
+ * already work for HTML).
+ *
+ * No dependencies, no network at build time. Plan content is treated as
+ * untrusted input: everything is escaped, and raw HTML only ever reaches a
+ * sandboxed iframe without `allow-scripts`.
+ *
+ *   renderPlanFolder('./plans/my-plan')  -> { html, warnings, outFile }
+ *   renderPlanSource({ plan, canvas })    -> { html, warnings }
+ *   parseMdx(text)                       -> blocks
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { parseMdx } = require('./mdx');
+const { renderBoard, renderDocument, prototypeHint, page } = require('./render');
+const { slugify } = require('../plan-canvas/markdown');
+
+const PLAN_FILE = 'plan.mdx';
+const OUTPUT_FILE = 'plan.builder.html';
+const OPTIONAL_SOURCES = [
+  { key: 'canvas', file: 'canvas.mdx', title: 'Canvas', board: true },
+  { key: 'prototype', file: 'prototype.mdx', title: 'Prototype' }
+];
+
+function readIfPresent(dir, file, warnings) {
+  const full = path.join(dir, file);
+  if (!fs.existsSync(full)) return null;
+  try {
+    return fs.readFileSync(full, 'utf8');
+  } catch (error) {
+    warnings.push(`could not read ${file}: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Render one or more MDX sources into a single HTML document.
+ *
+ * @param {{plan?: string, canvas?: string, prototype?: string, state?: object, title?: string}} source
+ * @returns {{html: string, warnings: string[]}}
+ */
+function renderPlanSource(source = {}) {
+  const warnings = [];
+  const ctx = { warnings, headings: [], ids: new Map(), hasMermaid: false, boards: 0, docBlocks: 0, dir: source.dir || null };
+  const sections = [];
+  const allBlocks = [];
+
+  const render = (mdx, heading, asBoard, file) => {
+    ctx.src = file;
+    const blocks = parseMdx(text(mdx));
+    allBlocks.push(...blocks);
+    for (const warning of blocks.warnings || []) warnings.push(warning);
+    if (heading) {
+      const id = uniqueHeading(heading, ctx);
+      ctx.headings.push({ id, text: heading, level: 2 });
+      sections.push(`<h2 class="sec" id="${id}">${heading}</h2>`);
+    }
+    sections.push(asBoard ? renderBoard(blocks, ctx) : renderDocument(blocks, ctx));
+    return blocks.frontmatter || {};
+  };
+
+  const frontmatter = render(source.plan, null, false, PLAN_FILE);
+  for (const extra of OPTIONAL_SOURCES) {
+    const mdx = source[extra.key];
+    if (!text(mdx)) continue;
+    render(mdx, extra.title, extra.board, extra.file);
+  }
+
+  sections.push(prototypeHint(allBlocks, frontmatter));
+
+  const state = source.state && typeof source.state === 'object' ? source.state : {};
+  const kind = text(frontmatter.kind) || text(state.kind);
+  const title = source.title || frontmatter.title || state.title || 'Plan';
+  const status = text(frontmatter.status || state.status || state.kind);
+  const meta = [
+    kind ? `kind: ${kind}` : '',
+    state.localOnly ? 'local-only' : '',
+    `${warnings.length} warning(s)`
+  ].filter(Boolean).join(' · ');
+
+  const body = sections.filter(Boolean).join('\n');
+  const html = page({
+    title: text(title),
+    status,
+    meta,
+    headings: ctx.headings,
+    body,
+    warnings,
+    hasMermaid: ctx.hasMermaid,
+    hasBoard: ctx.boards > 0,
+    boardOnly: ctx.boards > 0 && ctx.docBlocks === 0,
+    recap: kind === 'recap' ? frontmatter : null
+  });
+  return { html, warnings };
+}
+
+function text(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+function uniqueHeading(raw, ctx) {
+  const base = slugify(raw) || 'section';
+  const count = ctx.ids.get(base) || 0;
+  ctx.ids.set(base, count + 1);
+  return count ? `${base}-${count}` : base;
+}
+
+/**
+ * Build the HTML for a plan folder (or a single plan.mdx path) and write it
+ * next to the plan as `plan.builder.html`.
+ *
+ * A folder without `plan.mdx` is an error, reported — never thrown — so the
+ * CLI can turn it into exit code 2 with a clear message.
+ *
+ * @param {string} dirOrFile
+ * @returns {{html?: string, warnings: string[], outFile?: string, error?: string}}
+ */
+function renderPlanFolder(dirOrFile) {
+  const warnings = [];
+  const target = path.resolve(dirOrFile);
+
+  let dir = target;
+  let planPath = path.join(target, PLAN_FILE);
+  let stat = null;
+  try {
+    stat = fs.statSync(target);
+  } catch {
+    stat = null;
+  }
+
+  if (stat && stat.isFile()) {
+    dir = path.dirname(target);
+    planPath = target;
+    if (path.basename(target) !== PLAN_FILE) {
+      return { error: `expected ${PLAN_FILE} (got ${path.basename(target)})`, warnings };
+    }
+  } else if (!stat) {
+    return { error: `plan path not found: ${dirOrFile}`, warnings };
+  } else if (!stat.isDirectory()) {
+    return { error: `not a plan folder or file: ${dirOrFile}`, warnings };
+  }
+
+  if (!fs.existsSync(planPath)) {
+    return { error: `no ${PLAN_FILE} in ${dir}`, warnings };
+  }
+
+  let planText;
+  try {
+    planText = fs.readFileSync(planPath, 'utf8');
+  } catch (error) {
+    return { error: `could not read ${planPath}: ${error.message}`, warnings };
+  }
+
+  const source = { plan: planText, dir };
+  for (const extra of OPTIONAL_SOURCES) {
+    const mdx = readIfPresent(dir, extra.file, warnings);
+    if (mdx) source[extra.key] = mdx;
+  }
+  const statePath = path.join(dir, '.plan-state.json');
+  if (fs.existsSync(statePath)) {
+    try {
+      source.state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    } catch (error) {
+      warnings.push(`could not parse .plan-state.json: ${error.message}`);
+    }
+  }
+
+  const result = renderPlanSource(source);
+  warnings.push(...result.warnings);
+
+  const outFile = path.join(dir, OUTPUT_FILE);
+  try {
+    fs.writeFileSync(outFile, result.html);
+  } catch (error) {
+    return { html: result.html, warnings, error: `could not write ${outFile}: ${error.message}` };
+  }
+
+  return { html: result.html, warnings, outFile };
+}
+
+module.exports = { renderPlanFolder, renderPlanSource, parseMdx, OUTPUT_FILE, PLAN_FILE };

package/skills/global_config/plan-canvas/scripts/lib/plan-builder/kit.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Low-fidelity wireframe kit: the layout tags authored inside <Screen> /
+ * <FrameScreen> (<Col>, <Row>, <Box>, <Lines>, ...) rendered as plain,
+ * escaped HTML. Only numbers that were parsed and clamped reach a style
+ * attribute; every string goes through escapeHtml.
+ */
+
+const { escapeHtml: esc } = require('../plan-canvas/markdown');
+
+const DEFAULT_WIDTHS = [92, 78, 86, 64, 72];
+
+function str(value) {
+  if (value === undefined || value === null || value === true || value === false) return '';
+  return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+
+function clamp(value, min, max, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
+}
+
+function flag(value) {
+  return value === true || value === 'true';
+}
+
+function plainChildren(block) {
+  return (block.childrenRaw || '').trim();
+}
+
+// Inline text for a kit node: explicit props first, then literal children.
+function labelOf(block, ...keys) {
+  for (const key of keys) {
+    const value = str(block.props[key]);
+    if (value) return value;
+  }
+  return plainChildren(block);
+}
+
+function cls(base, ...extra) {
+  return [base, ...extra.filter(Boolean)].join(' ');
+}
+
+function chips(items) {
+  const list = Array.isArray(items) ? items : [];
+  return list.map((item) => {
+    const obj = item && typeof item === 'object' ? item : { label: str(item) };
+    return `<span class="${cls('k-chip', flag(obj.active) && 'on')}">${esc(str(obj.label || obj.text))}</span>`;
+  }).join('');
+}
+
+const TAGS = {
+  FrameScreen: (b, inner) => `<div class="k-frame">${inner}</div>`,
+  Main: (b, inner) => `<div class="k-col k-main">${inner}</div>`,
+  Col: (b, inner) => `<div class="${cls('k-col', flag(b.props.full) && 'full')}">${inner}</div>`,
+  Row: (b, inner) => `<div class="${cls('k-row', flag(b.props.full) && 'full')}">${inner}</div>`,
+  Box: (b, inner) => `<div class="${cls('k-box', flag(b.props.dashed) && 'dashed', flag(b.props.full) && 'full')}">${inner}</div>`,
+  Card: (b, inner) => `<div class="k-box k-card">${inner}</div>`,
+  Lines: (b) => {
+    const count = clamp(b.props.n, 1, 40, 3);
+    const widths = Array.isArray(b.props.widths) ? b.props.widths : [];
+    let html = '';
+    for (let i = 0; i < count; i++) {
+      const width = clamp(widths[i], 4, 100, DEFAULT_WIDTHS[i % DEFAULT_WIDTHS.length]);
+      html += `<i class="k-bar" style="width:${width}%"></i>`;
+    }
+    return `<div class="k-lines">${html}</div>`;
+  },
+  IconSquare: (b) => `<i class="${cls('k-icon', flag(b.props.active) && 'on')}"></i>`,
+  Divider: () => '<hr class="k-div">',
+  StatusBar: () => '<div class="k-status"><i></i><i></i><i></i><b></b></div>',
+  TaskRow: (b) => {
+    const done = flag(b.props.done);
+    const note = str(b.props.note);
+    return `<div class="${cls('k-task', done && 'done')}"><i class="k-check"></i>` +
+      `<span class="k-text">${esc(labelOf(b, 'title', 'label', 'text'))}</span>` +
+      (note ? `<span class="k-text k-muted">${esc(note)}</span>` : '') + '</div>';
+  },
+  Text: (b) => {
+    const tone = str(b.props.tone) === 'muted' ? 'k-muted' : '';
+    const weight = str(b.props.weight) === 'bold' ? 'k-bold' : '';
+    return `<span class="${cls('k-text', tone, weight)}">${esc(labelOf(b, 'value', 'text', 'label'))}</span>`;
+  },
+  Title: (b) => `<div class="k-title">${esc(labelOf(b, 'text', 'value', 'label'))}</div>`,
+  SectionLabel: (b) => `<div class="k-section-label">${esc(labelOf(b, 'label', 'text', 'value'))}</div>`,
+  Btn: (b) => `<span class="${cls('k-btn', flag(b.props.primary) && 'on')}">${esc(labelOf(b, 'label', 'text'))}</span>`,
+  Chips: (b) => `<div class="k-chips">${chips(b.props.items)}</div>`,
+  Skeleton: (b) => {
+    const lines = clamp(b.props.lines, 0, 20, 0);
+    if (lines) return TAGS.Lines({ props: { n: lines, widths: b.props.widths } });
+    const width = clamp(b.props.width ?? b.props.w, 4, 100, 100);
+    const height = clamp(b.props.height ?? b.props.h, 4, 600, 14);
+    return `<i class="k-skel" style="width:${width}%;height:${height}px"></i>`;
+  }
+};
+
+const KIT_TAGS = new Set(Object.keys(TAGS));
+
+function renderKit(blocks, ctx) {
+  const out = [];
+  for (const block of blocks || []) {
+    if (block.type === 'tag') {
+      const handler = Object.hasOwn(TAGS, block.name) ? TAGS[block.name] : null;
+      if (handler) {
+        out.push(handler(block, renderKit(block.children, ctx)));
+      } else {
+        ctx.warnings.push(`unknown wireframe kit tag <${block.name}>`);
+        out.push(`<div class="k-unknown">&lt;${esc(block.name)}&gt;</div>`);
+      }
+    } else if (block.type === 'heading') {
+      out.push(`<div class="k-title">${esc(block.text)}</div>`);
+    } else if (block.type === 'prose') {
+      out.push(`<span class="k-text">${esc(block.text)}</span>`);
+    } else if (block.type === 'malformed') {
+      ctx.warnings.push(block.message || 'malformed wireframe kit markup');
+      out.push(`<div class="k-unknown">${esc(block.message || 'malformed')}</div>`);
+    }
+  }
+  return out.join('');
+}
+
+module.exports = { renderKit, KIT_TAGS };