ma-agents 3.12.3 → 3.13.0

package/lib/bmad-cache/wds/src/scripts/wds-init-page.js

@@ -0,0 +1,229 @@
+// wds-init-page.js — WDS scaffold: initialize new page spec
+// Usage: node src/scripts/wds-init-page.js --page "01 Start" --scenario "01 Onboarding"
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : true;
+      args[key] = value;
+      if (value !== true) i++;
+    }
+  }
+  return args;
+}
+
+function toSlug(str) {
+  return str.toLowerCase().replaceAll(/\s+/g, '-');
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node src/scripts/wds-init-page.js --page "01 Start" --scenario "01 Onboarding" [options]',
+      '',
+      'Required:',
+      '  --page        Page name with number, e.g. "01 Start"',
+      '  --scenario    Scenario name, e.g. "01 New User Onboarding"',
+      '',
+      'Optional:',
+      '  --platform    Platform value (default: "Mobile web")',
+      '  --visibility  Visibility value (default: "Public")',
+      '  --output      Base path to write to (default: current directory)',
+      '',
+    ].join('\n'),
+  );
+}
+
+function buildTemplate({ pageSlug, pageName, scenarioSlug, scenarioName, platform, visibility }) {
+  const sketchFile = `sketches/${pageSlug}-concept.jpg`;
+
+  const navEmpty = `← [Previous]() | [Next →]()`;
+
+  const metaTable = [
+    '| Property | Value |',
+    '|----------|-------|',
+    `| Scenario | ${scenarioName} |`,
+    `| Page Number | ${pageName.split(' ')[0]} |`,
+    `| Platform | ${platform} |`,
+    `| Page Type | — |`,
+    `| Viewport | — |`,
+    `| Interaction | — |`,
+    `| Visibility | ${visibility} |`,
+  ].join('\n');
+
+  const overviewSection = [
+    '| Property | Value |',
+    '|----------|-------|',
+    '| Purpose | — |',
+    '| User Situation | — |',
+    '| Success Criteria | — |',
+    '| Entry Points | — |',
+    '| Exit Points | — |',
+  ].join('\n');
+
+  const spacingTable = [
+    '| Token | Direction | Type | Size | Reason |',
+    '|-------|-----------|------|------|--------|',
+    `| \`${pageSlug}-v-space-md\` | Vertical | space | md | — |`,
+  ].join('\n');
+
+  const typographyTable = [
+    '| Element | Semantic | Size | Weight | Typeface |',
+    '|---------|----------|------|--------|----------|',
+    '| Page title | H1 | — | — | — |',
+  ].join('\n');
+
+  const statesTable = [
+    '| State | When | Appearance | Actions |',
+    '|-------|------|------------|---------|',
+    '| Default | On load | — | — |',
+  ].join('\n');
+
+  return [
+    navEmpty,
+    '',
+    `![${pageName}](${sketchFile})`,
+    '',
+    navEmpty,
+    '',
+    '---',
+    '',
+    `# ${pageName}`,
+    '',
+    '## Page Metadata',
+    '',
+    metaTable,
+    '',
+    '---',
+    '',
+    '## Overview',
+    '',
+    overviewSection,
+    '',
+    '---',
+    '',
+    '## Reference Materials',
+    '',
+    '- —',
+    '',
+    '---',
+    '',
+    '## Layout Structure',
+    '',
+    '```',
+    '+---------------------------+',
+    '|         Header            |',
+    '+---------------------------+',
+    '|                           |',
+    '|         Content           |',
+    '|                           |',
+    '+---------------------------+',
+    '|         Footer            |',
+    '+---------------------------+',
+    '```',
+    '',
+    '---',
+    '',
+    '## Spacing',
+    '',
+    spacingTable,
+    '',
+    '---',
+    '',
+    '## Typography',
+    '',
+    typographyTable,
+    '',
+    '---',
+    '',
+    '## Page Sections',
+    '',
+    `### Section: Main`,
+    '',
+    `<!-- Objects go here. Use wds-add-object.js to append. -->`,
+    '',
+    '---',
+    '',
+    '## Page States',
+    '',
+    statesTable,
+    '',
+    '---',
+    '',
+    '## Open Questions',
+    '',
+    '- —',
+    '',
+    '---',
+    '',
+    '## Checklist',
+    '',
+    '- [ ] Navigation links updated',
+    '- [ ] Sketch added',
+    '- [ ] All objects have SE + EN content',
+    '- [ ] All Object IDs use correct prefix',
+    '- [ ] Page States defined',
+    '- [ ] Spacing tokens defined',
+    '',
+    navEmpty,
+    '',
+  ].join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!args.page || !args.scenario) {
+    process.stderr.write('Error: --page and --scenario are required.\n\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  const pageName = args.page;
+  const scenarioName = args.scenario;
+  const platform = args.platform || 'Mobile web';
+  const visibility = args.visibility || 'Public';
+  const outputBase = args.output || process.cwd();
+
+  const pageSlug = toSlug(pageName);
+  const scenarioSlug = toSlug(scenarioName);
+
+  const pageDir = path.join(outputBase, 'C-UX-Scenarios', scenarioSlug, pageSlug);
+  const sketchesDir = path.join(pageDir, 'sketches');
+  const pageFile = path.join(pageDir, `${pageSlug}.md`);
+
+  try {
+    fs.mkdirSync(pageDir, { recursive: true });
+    fs.mkdirSync(sketchesDir, { recursive: true });
+  } catch (error) {
+    process.stderr.write(`Error creating directories: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  const content = buildTemplate({ pageSlug, pageName, scenarioSlug, scenarioName, platform, visibility });
+
+  try {
+    fs.writeFileSync(pageFile, content, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error writing file: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`✓ Created ${pageSlug}.md\n`);
+  process.stdout.write(`  Path: ${pageFile}\n`);
+  process.stdout.write(`  Run wds-nav.js to update navigation links.\n`);
+}
+
+main();

package/lib/bmad-cache/wds/src/scripts/wds-init-scenario.js

@@ -0,0 +1,120 @@
+// wds-init-scenario.js — WDS scaffold: initialize new scenario folder
+// Usage: node src/scripts/wds-init-scenario.js --scenario "01 Onboarding" --description "New user first visit to account creation"
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : true;
+      args[key] = value;
+      if (value !== true) i++;
+    }
+  }
+  return args;
+}
+
+function toSlug(str) {
+  return str.toLowerCase().replaceAll(/\s+/g, '-');
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node src/scripts/wds-init-scenario.js --scenario "01 Onboarding" [options]',
+      '',
+      'Required:',
+      '  --scenario      Scenario name with number, e.g. "01 New User Onboarding"',
+      '',
+      'Optional:',
+      '  --description   Short description of the scenario',
+      '  --output        Base path to write to (default: current directory)',
+      '',
+    ].join('\n'),
+  );
+}
+
+function buildReadme({ scenarioName, scenarioSlug, description }) {
+  const scenarioNumber = scenarioName.split(' ')[0];
+  const desc = description || '—';
+
+  return [
+    `# Scenario ${scenarioNumber}: ${scenarioName}`,
+    '',
+    `**Description:** ${desc}`,
+    '',
+    '**Trigger Map:** [Link to trigger map]()',
+    '',
+    '---',
+    '',
+    '## Pages',
+    '',
+    '| # | Page | File | Status |',
+    '|---|------|------|--------|',
+    '| — | (no pages yet) | — | — |',
+    '',
+    '---',
+    '',
+    '## Notes',
+    '',
+    '- Add pages with: `node src/scripts/wds-init-page.js --scenario "' + scenarioName + '" --page "01 Start"`',
+    '- Update navigation after adding pages: `node src/scripts/wds-nav.js --scenario "' + scenarioName + '"`',
+    '- Validate pages: `node src/scripts/wds-validate.js --scenario "' + scenarioName + '"`',
+    '',
+  ].join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!args.scenario) {
+    process.stderr.write('Error: --scenario is required.\n\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  const scenarioName = args.scenario;
+  const description = args.description || '';
+  const outputBase = args.output || process.cwd();
+
+  const scenarioSlug = toSlug(scenarioName);
+  const scenarioDir = path.join(outputBase, 'C-UX-Scenarios', scenarioSlug);
+  const readmeFile = path.join(scenarioDir, 'README.md');
+
+  if (fs.existsSync(scenarioDir)) {
+    process.stderr.write(`Error: Scenario folder already exists: ${scenarioDir}\n`);
+    process.exit(1);
+  }
+
+  try {
+    fs.mkdirSync(scenarioDir, { recursive: true });
+  } catch (error) {
+    process.stderr.write(`Error creating directory: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  const content = buildReadme({ scenarioName, scenarioSlug, description });
+
+  try {
+    fs.writeFileSync(readmeFile, content, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error writing README: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`✓ Created scenario ${scenarioSlug}/\n`);
+  process.stdout.write(`  Path: ${scenarioDir}\n`);
+  process.stdout.write(`  README: ${readmeFile}\n`);
+}
+
+main();

package/lib/bmad-cache/wds/src/scripts/wds-nav.js

@@ -0,0 +1,201 @@
+// wds-nav.js — WDS scaffold: generate/update navigation links across all pages in a scenario
+// Usage: node src/scripts/wds-nav.js --scenario "01 Onboarding"
+//        node src/scripts/wds-nav.js --all
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const key = argv[i].slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : true;
+      args[key] = value;
+      if (value !== true) i++;
+    }
+  }
+  return args;
+}
+
+function toSlug(str) {
+  return str.toLowerCase().replaceAll(/\s+/g, '-');
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node src/scripts/wds-nav.js --scenario "01 Onboarding"',
+      '       node src/scripts/wds-nav.js --all',
+      '',
+      'Options:',
+      '  --scenario    Scenario name or slug to update',
+      '  --all         Update all scenarios',
+      '  --output      Base path (default: current directory)',
+      '',
+    ].join('\n'),
+  );
+}
+
+// Build a human-readable page name from the slug for nav labels
+// e.g. "01-start" -> "01 Start"
+function slugToLabel(slug) {
+  return slug
+    .split('-')
+    .map((part, i) => (i === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1)))
+    .join(' ');
+}
+
+function buildNavRow(prev, next) {
+  const leftPart = prev ? `← [${slugToLabel(prev.slug)}](../${prev.slug}/${prev.slug}.md)` : '←';
+  const rightPart = next ? `[${slugToLabel(next.slug)} →](../${next.slug}/${next.slug}.md)` : '→';
+  return `${leftPart} | ${rightPart}`;
+}
+
+// Replace all 3 occurrences of navigation rows in a page file.
+// Nav rows are lines matching the pattern: starts with '←' or contains '| [' and ends with '→'
+// We identify them by a simple pattern: line that starts with "←" (after trim).
+function updateNavInContent(content, navRow) {
+  const lines = content.split('\n');
+  const result = [];
+  let navCount = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Match navigation rows: lines that start with "←" (our nav format)
+    if (trimmed.startsWith('←')) {
+      result.push(navRow);
+      navCount++;
+    } else {
+      result.push(line);
+    }
+  }
+
+  return { content: result.join('\n'), navCount };
+}
+
+function getPageFolders(scenarioDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(scenarioDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((name) => {
+      // Must have a matching .md file inside
+      const mdFile = path.join(scenarioDir, name, `${name}.md`);
+      return fs.existsSync(mdFile);
+    })
+    .sort(); // Sort alphabetically — page numbers ensure correct order
+}
+
+function processScenario(scenariosBase, scenarioSlug) {
+  const scenarioDir = path.join(scenariosBase, scenarioSlug);
+
+  if (!fs.existsSync(scenarioDir)) {
+    process.stderr.write(`Error: Scenario not found: ${scenarioDir}\n`);
+    return false;
+  }
+
+  const pageSlugs = getPageFolders(scenarioDir);
+
+  if (pageSlugs.length === 0) {
+    process.stdout.write(`  ${scenarioSlug}: no pages found, skipping.\n`);
+    return true;
+  }
+
+  let updated = 0;
+
+  for (let i = 0; i < pageSlugs.length; i++) {
+    const slug = pageSlugs[i];
+    const prev = i > 0 ? { slug: pageSlugs[i - 1] } : null;
+    const next = i < pageSlugs.length - 1 ? { slug: pageSlugs[i + 1] } : null;
+    const navRow = buildNavRow(prev, next);
+
+    const mdFile = path.join(scenarioDir, slug, `${slug}.md`);
+    let content;
+    try {
+      content = fs.readFileSync(mdFile, 'utf8');
+    } catch (error) {
+      process.stderr.write(`  Error reading ${mdFile}: ${error.message}\n`);
+      continue;
+    }
+
+    const { content: newContent, navCount } = updateNavInContent(content, navRow);
+
+    if (navCount === 0) {
+      process.stderr.write(`  Warning: No navigation rows found in ${slug}.md\n`);
+    }
+
+    try {
+      fs.writeFileSync(mdFile, newContent, 'utf8');
+      updated++;
+    } catch (error) {
+      process.stderr.write(`  Error writing ${mdFile}: ${error.message}\n`);
+    }
+  }
+
+  process.stdout.write(`✓ Updated navigation for ${updated} pages in ${scenarioSlug}\n`);
+  return true;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!args.scenario && !args.all) {
+    process.stderr.write('Error: --scenario or --all is required.\n\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  const outputBase = args.output || process.cwd();
+  const scenariosBase = path.join(outputBase, 'C-UX-Scenarios');
+
+  if (!fs.existsSync(scenariosBase)) {
+    process.stderr.write(`Error: C-UX-Scenarios directory not found at: ${scenariosBase}\n`);
+    process.exit(1);
+  }
+
+  if (args.all) {
+    let entries;
+    try {
+      entries = fs.readdirSync(scenariosBase, { withFileTypes: true });
+    } catch (error) {
+      process.stderr.write(`Error reading C-UX-Scenarios: ${error.message}\n`);
+      process.exit(1);
+    }
+
+    const scenarios = entries
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort();
+
+    if (scenarios.length === 0) {
+      process.stdout.write('No scenarios found.\n');
+      process.exit(0);
+    }
+
+    let allOk = true;
+    for (const slug of scenarios) {
+      if (!processScenario(scenariosBase, slug)) allOk = false;
+    }
+    process.exit(allOk ? 0 : 1);
+  } else {
+    const scenarioSlug = toSlug(args.scenario);
+    const ok = processScenario(scenariosBase, scenarioSlug);
+    process.exit(ok ? 0 : 1);
+  }
+}
+
+main();