siesa-agents 2.1.90 → 2.1.92

package/siesa-agents/wds/scripts/README.md

@@ -0,0 +1,155 @@
+# WDS Scaffold Scripts
+
+Node.js scripts that enforce deterministic output from AI agents. Agents provide content via CLI flags; scripts produce structure.
+
+All scripts use only Node.js stdlib (no external dependencies). Run from the project root.
+
+---
+
+## Scripts
+
+### `wds-init-scenario.js` — Initialize a scenario
+
+Creates the scenario folder and a README index file.
+
+```bash
+node src/scripts/wds-init-scenario.js \
+  --scenario "01 New User Onboarding" \
+  --description "New user first visit to account creation"
+```
+
+Output: `C-UX-Scenarios/01-new-user-onboarding/README.md`
+
+---
+
+### `wds-init-page.js` — Initialize a page spec
+
+Creates a new page spec file with all required sections pre-filled with placeholders.
+
+```bash
+node src/scripts/wds-init-page.js \
+  --page "01 Start" \
+  --scenario "01 New User Onboarding" \
+  --platform "Mobile web" \
+  --visibility "Public"
+```
+
+Output:
+- `C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md`
+- `C-UX-Scenarios/01-new-user-onboarding/01-start/sketches/`
+
+After creating all pages in a scenario, run `wds-nav.js` to wire up navigation links.
+
+---
+
+### `wds-nav.js` — Update navigation links
+
+Scans pages in a scenario (sorted by name) and writes correct prev/next navigation rows into each page spec.
+
+```bash
+# One scenario
+node src/scripts/wds-nav.js --scenario "01 New User Onboarding"
+
+# All scenarios
+node src/scripts/wds-nav.js --all
+```
+
+Run this after adding or removing pages, or after reordering page numbers.
+
+---
+
+### `wds-add-object.js` — Append an object spec
+
+Appends a structured object spec block to a page spec under a named section.
+
+```bash
+node src/scripts/wds-add-object.js \
+  --page "C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md" \
+  --section "Hero" \
+  --object "Primary Headline" \
+  --component "H1 heading" \
+  --se "Välkommen" \
+  --en "Welcome" \
+  --behavior "Static display"
+```
+
+Object ID is auto-derived: `start-hero-primary-headline`
+
+The section heading (`### Section: Hero`) is created if it doesn't already exist.
+
+---
+
+### `wds-add-spacing.js` — Append a spacing object
+
+Appends a spacing notation entry to the `## Spacing` section of a page spec.
+
+```bash
+node src/scripts/wds-add-spacing.js \
+  --page "C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md" \
+  --direction v \
+  --type space \
+  --size xl \
+  --reason "major section boundary between hero and features"
+```
+
+Valid directions: `v` (vertical), `h` (horizontal)
+Valid types: `space`, `separator`, `line`
+Valid sizes: `zero`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `flex`
+
+Spacing ID is auto-derived: `start-v-space-xl`
+
+---
+
+### `wds-validate.js` — Validate page specs
+
+Checks page spec files for structural correctness.
+
+```bash
+# Single page
+node src/scripts/wds-validate.js \
+  --page "C-UX-Scenarios/01-new-user-onboarding/01-start/01-start.md"
+
+# All pages in a scenario
+node src/scripts/wds-validate.js --scenario "01 New User Onboarding"
+
+# All scenarios
+node src/scripts/wds-validate.js --all
+```
+
+Validates:
+- Required sections present
+- Object IDs are kebab-case with correct page prefix
+- No duplicate Object IDs
+- Navigation rows (3 expected)
+- Metadata table has all required properties
+- Sketches folder exists
+- SE + EN content present for each object
+
+---
+
+## How agents use these scripts
+
+1. Agent calls `wds-init-scenario.js` with scenario name and description
+2. Agent calls `wds-init-page.js` for each page in the scenario
+3. Agent calls `wds-nav.js` to wire navigation after all pages exist
+4. Agent calls `wds-add-object.js` for each UI object, providing Swedish and English content
+5. Agent calls `wds-add-spacing.js` for each spacing decision
+6. Agent calls `wds-validate.js` to confirm the spec is structurally correct before handoff
+
+The agent never writes raw markdown — it only supplies content as flag values. The scripts own all structural decisions.
+
+---
+
+## File location convention
+
+```
+C-UX-Scenarios/
+  {scenario-slug}/
+    README.md
+    {page-slug}/
+      {page-slug}.md
+      sketches/
+        {page-slug}-concept.jpg
+```
+
+Example: `C-UX-Scenarios/01-new-user-onboarding/02-signup/02-signup.md`

package/siesa-agents/wds/scripts/wds-add-object.js

@@ -0,0 +1,207 @@
+// wds-add-object.js — WDS scaffold: append an object spec block to a page spec file
+// Usage: node src/scripts/wds-add-object.js --page "C-UX-Scenarios/01-onboarding/01-start/01-start.md" \
+//          --section "Hero" --object "Primary Headline" --component "H1 heading" \
+//          --se "Välkommen" --en "Welcome"
+
+'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
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '') // strip accents: á→a, ó→o, ñ→n, ü→u
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-') // any run of non-alphanumeric → single dash
+    .replace(/^-+|-+$/g, ''); // trim leading/trailing dashes
+}
+
+function printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node src/scripts/wds-add-object.js --page <path> --section <name> --object <name> [options]',
+      '',
+      'Required:',
+      '  --page        Path to the page spec .md file',
+      '  --section     Section name (e.g. "Hero")',
+      '  --object      Object name (e.g. "Primary Headline")',
+      '',
+      'Optional:',
+      '  --component   Component name (default: "—")',
+      '  --translation Translation key (auto-derived if omitted)',
+      '  --se          Swedish text content',
+      '  --en          English text content',
+      '  --behavior    Behavior description (e.g. "onClick: submit form")',
+      '  --component-path  Path to component file (default: "—")',
+      '',
+    ].join('\n'),
+  );
+}
+
+// Derive page slug from file path: "01-start/01-start.md" -> "01-start"
+function pageSlugFromPath(filePath) {
+  const base = path.basename(filePath, '.md');
+  return base;
+}
+
+// Derive Object ID: pageSlug + sectionSlug + objectSlug
+// e.g. page=01-start, section=Hero, object=Primary Headline -> 01-start-hero-primary-headline
+function deriveObjectId(pageSlug, sectionName, objectName) {
+  // Strip leading page number from pageSlug for ID prefix
+  // "01-start" -> "start", "02-signup" -> "signup"
+  const slugParts = pageSlug.split('-');
+  const pagePrefix = slugParts.length > 1 ? slugParts.slice(1).join('-') : pageSlug;
+  const sectionSlug = toSlug(sectionName);
+  const objectSlug = toSlug(objectName);
+  return `${pagePrefix}-${sectionSlug}-${objectSlug}`;
+}
+
+function buildObjectBlock({ objectName, objectId, component, componentPath, translationKey, se, en, behavior }) {
+  const compDisplay = componentPath && componentPath !== '—' ? `[${component}](${componentPath})` : component || '—';
+
+  const lines = [
+    `#### ${objectName}`,
+    '',
+    `**OBJECT ID:** \`${objectId}\``,
+    '',
+    '| Property | Value |',
+    '|----------|-------|',
+    `| Component | ${compDisplay} |`,
+    `| Translation Key | \`${translationKey}\` |`,
+    `| SE | "${se || '—'}" |`,
+    `| EN | "${en || '—'}" |`,
+    `| Behavior | ${behavior || '—'} |`,
+    '',
+  ];
+
+  return lines.join('\n');
+}
+
+// Insert content after a section heading. Creates the section heading if it doesn't exist.
+function insertUnderSection(content, sectionHeading, objectBlock) {
+  const lines = content.split('\n');
+  const headingLine = `### Section: ${sectionHeading}`;
+  const headingIdx = lines.findIndex((l) => l.trim() === headingLine);
+
+  if (headingIdx === -1) {
+    // Section doesn't exist — append it before the next ## heading after ## Page Sections
+    const pageSectionsIdx = lines.findIndex((l) => l.trim() === '## Page Sections');
+    if (pageSectionsIdx === -1) {
+      // Just append at end before last nav row
+      return content + `\n${headingLine}\n\n${objectBlock}\n`;
+    }
+
+    // Find end of ## Page Sections block
+    let insertIdx = pageSectionsIdx + 1;
+    while (insertIdx < lines.length) {
+      const t = lines[insertIdx].trim();
+      if (t.startsWith('## ') || t === '---') break;
+      insertIdx++;
+    }
+
+    const before = lines.slice(0, insertIdx);
+    const after = lines.slice(insertIdx);
+    return [...before, '', headingLine, '', objectBlock, ...after].join('\n');
+  } else {
+    // Find the end of this section (next ### or ## or end of file)
+    let insertIdx = headingIdx + 1;
+    // Skip blank lines after heading
+    while (insertIdx < lines.length && lines[insertIdx].trim() === '') insertIdx++;
+    // Skip comment lines
+    while (insertIdx < lines.length && lines[insertIdx].trim().startsWith('<!--')) insertIdx++;
+
+    // Find end of section
+    let endIdx = insertIdx;
+    while (endIdx < lines.length) {
+      const t = lines[endIdx].trim();
+      if (t.startsWith('### ') || t.startsWith('## ') || t === '---') break;
+      endIdx++;
+    }
+
+    // Insert object block before end of section
+    const before = lines.slice(0, endIdx);
+    const after = lines.slice(endIdx);
+    return [...before, '', objectBlock, ...after].join('\n');
+  }
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!args.page || !args.section || !args.object) {
+    process.stderr.write('Error: --page, --section, and --object are required.\n\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  const filePath = path.resolve(args.page);
+
+  if (!fs.existsSync(filePath)) {
+    process.stderr.write(`Error: File not found: ${filePath}\n`);
+    process.exit(1);
+  }
+
+  const pageSlug = pageSlugFromPath(filePath);
+  const objectId = deriveObjectId(pageSlug, args.section, args.object);
+
+  // Auto-derive translation key from objectId
+  const translationKey = args.translation || objectId.replaceAll('-', '.');
+
+  const objectBlock = buildObjectBlock({
+    objectName: args.object,
+    objectId,
+    component: args.component || '—',
+    componentPath: args['component-path'] || '—',
+    translationKey,
+    se: args.se || '',
+    en: args.en || '',
+    behavior: args.behavior || '—',
+  });
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error reading file: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  // Check for duplicate object ID
+  if (content.includes(`\`${objectId}\``)) {
+    process.stderr.write(`Error: Object ID already exists in file: ${objectId}\n`);
+    process.exit(1);
+  }
+
+  const updated = insertUnderSection(content, args.section, objectBlock);
+
+  try {
+    fs.writeFileSync(filePath, updated, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error writing file: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`✓ Added object ${objectId}\n`);
+  process.stdout.write(`  File: ${filePath}\n`);
+}
+
+main();

package/siesa-agents/wds/scripts/wds-add-spacing.js

@@ -0,0 +1,158 @@
+// wds-add-spacing.js — WDS scaffold: append a spacing object to a page spec file
+// Usage: node src/scripts/wds-add-spacing.js --page "C-UX-Scenarios/01-onboarding/01-start/01-start.md" \
+//          --direction v --type space --size xl --reason "major section boundary between hero and features"
+
+'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 printUsage() {
+  process.stdout.write(
+    [
+      'Usage: node src/scripts/wds-add-spacing.js --page <path> --direction <v|h> --type <type> --size <size> [options]',
+      '',
+      'Required:',
+      '  --page        Path to the page spec .md file',
+      '  --direction   v (vertical) or h (horizontal)',
+      '  --type        space | separator | line',
+      '  --size        zero | sm | md | lg | xl | 2xl | 3xl | flex',
+      '',
+      'Optional:',
+      '  --reason      Why this spacing exists',
+      '',
+      'Valid directions: v, h',
+      'Valid types:      space, separator, line',
+      'Valid sizes:      zero, sm, md, lg, xl, 2xl, 3xl, flex',
+      '',
+    ].join('\n'),
+  );
+}
+
+const VALID_DIRECTIONS = ['v', 'h'];
+const VALID_TYPES = ['space', 'separator', 'line'];
+const VALID_SIZES = ['zero', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', 'flex'];
+
+// Derive page prefix from slug: "01-start" -> "start"
+function pagePrefix(slug) {
+  const parts = slug.split('-');
+  return parts.length > 1 ? parts.slice(1).join('-') : slug;
+}
+
+function pageSlugFromPath(filePath) {
+  return path.basename(filePath, '.md');
+}
+
+function buildSpacingBlock(spacingId, reason) {
+  const icon = '↕';
+  const reasonText = reason ? ` — ${reason}` : '';
+  return `#### ${icon} \`${spacingId}\`${reasonText}\n`;
+}
+
+function appendToSpacingSection(content, spacingBlock) {
+  const lines = content.split('\n');
+  const spacingIdx = lines.findIndex((l) => l.trim() === '## Spacing');
+
+  if (spacingIdx === -1) {
+    // No spacing section — append before first ## after metadata
+    return content + `\n## Spacing\n\n${spacingBlock}\n`;
+  }
+
+  // Find end of spacing section (next ## or ---)
+  let endIdx = spacingIdx + 1;
+  while (endIdx < lines.length) {
+    const t = lines[endIdx].trim();
+    if ((t.startsWith('## ') && t !== '## Spacing') || t === '---') break;
+    endIdx++;
+  }
+
+  // Insert just before the end marker
+  const before = lines.slice(0, endIdx);
+  const after = lines.slice(endIdx);
+  return [...before, spacingBlock, ...after].join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!args.page || !args.direction || !args.type || args.size === 0) {
+    process.stderr.write('Error: --page, --direction, --type, and --size are required.\n\n');
+    printUsage();
+    process.exit(1);
+  }
+
+  if (!VALID_DIRECTIONS.includes(args.direction)) {
+    process.stderr.write(`Error: Invalid direction "${args.direction}". Must be: ${VALID_DIRECTIONS.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  if (!VALID_TYPES.includes(args.type)) {
+    process.stderr.write(`Error: Invalid type "${args.type}". Must be: ${VALID_TYPES.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  if (!VALID_SIZES.includes(args.size)) {
+    process.stderr.write(`Error: Invalid size "${args.size}". Must be: ${VALID_SIZES.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  const filePath = path.resolve(args.page);
+
+  if (!fs.existsSync(filePath)) {
+    process.stderr.write(`Error: File not found: ${filePath}\n`);
+    process.exit(1);
+  }
+
+  const slug = pageSlugFromPath(filePath);
+  const prefix = pagePrefix(slug);
+  const spacingId = `${prefix}-${args.direction}-${args.type}-${args.size}`;
+  const reason = args.reason || '';
+
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error reading file: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  // Check for duplicate spacing ID
+  if (content.includes(`\`${spacingId}\``)) {
+    process.stderr.write(`Error: Spacing ID already exists in file: ${spacingId}\n`);
+    process.stderr.write('Use a different combination of direction/type/size or manually edit the file.\n');
+    process.exit(1);
+  }
+
+  const spacingBlock = buildSpacingBlock(spacingId, reason);
+  const updated = appendToSpacingSection(content, spacingBlock);
+
+  try {
+    fs.writeFileSync(filePath, updated, 'utf8');
+  } catch (error) {
+    process.stderr.write(`Error writing file: ${error.message}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`✓ Added spacing object ${spacingId}\n`);
+  process.stdout.write(`  File: ${filePath}\n`);
+}
+
+main();