@shanyucoder/flowgrid 0.1.0

package/engines/spec/lib/open-qa.mjs

@@ -0,0 +1,66 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { parse } from 'yaml'
+
+/** Walk up from a bundle dir to the docs hub (`qa/open` or `architecture/`). */
+export function findDocsHubRoot(fromDir) {
+  let dir = path.resolve(fromDir)
+  for (let i = 0; i < 40; i++) {
+    if (existsSync(path.join(dir, 'qa', 'open')) || existsSync(path.join(dir, 'architecture'))) {
+      return dir
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+export function openQaCsv(hubRoot, bundleId) {
+  return getOpenQaDetails(hubRoot, bundleId).csv
+}
+
+export function getOpenQaDetails(hubRoot, bundleId) {
+  if (!hubRoot || !bundleId) return { csv: '', techDebt: [] }
+  const openDir = path.join(hubRoot, 'qa', 'open')
+  if (!existsSync(openDir)) return { csv: '', techDebt: [] }
+  const prefix = `QA-${bundleId}-`
+  const ids = []
+  const techDebt = []
+  for (const name of readdirSync(openDir)) {
+    if (!/\.ya?ml$/i.test(name)) continue
+    const stem = name.replace(/\.ya?ml$/i, '')
+    if (!stem.startsWith(prefix)) continue
+    let id = stem
+    let kind = ''
+    let question = ''
+    try {
+      const parsed = parse(readFileSync(path.join(openDir, name), 'utf8'))
+      if (parsed && typeof parsed.id === 'string' && parsed.id.trim()) id = parsed.id.trim()
+      if (parsed && typeof parsed.kind === 'string') kind = parsed.kind
+      if (parsed && typeof parsed.question === 'string') question = parsed.question.trim().split('\n')[0]
+    } catch {
+      /* filename */
+    }
+    ids.push(id)
+    if (kind === 'tech-debt') {
+      techDebt.push({ id, status: 'open', summary: question })
+    }
+  }
+  ids.sort()
+  techDebt.sort((a, b) => a.id.localeCompare(b.id))
+  return { csv: ids.join(', '), techDebt }
+}
+
+const QA_FIELD = 'Q&A'
+
+/** Set or remove `Q&A` on a business spec object (comma-separated ids). */
+export function applyOpenQaField(spec, bundlePath, bundleId) {
+  const hub = findDocsHubRoot(path.dirname(path.resolve(bundlePath)))
+  const qa = getOpenQaDetails(hub, bundleId)
+  if (qa.csv) spec[QA_FIELD] = qa.csv
+  else delete spec[QA_FIELD]
+  if (qa.techDebt && qa.techDebt.length > 0) spec.pendingTechDebt = qa.techDebt
+  else delete spec.pendingTechDebt
+  return spec
+}

package/engines/spec/lib/project-business-layout.mjs

@@ -0,0 +1,214 @@
+const TECH_KEYS = new Set([
+  'id',
+  'tags',
+  'extract',
+  'bind',
+  'widget',
+  'apiRefs',
+  'reuseFrom',
+  'hidden',
+  'testId',
+  'testIds',
+  'i18n',
+  'href',
+  'active',
+  'component',
+])
+
+const CSS_VISUAL = new Set([
+  'width',
+  'height',
+  'maxWidth',
+  'maxHeight',
+  'padding',
+  'borderRadius',
+  'overflow',
+  'scroll',
+  'background',
+])
+
+const BUSINESS_SCALAR = [
+  'kind',
+  'label',
+  'value',
+  'purpose',
+  'description',
+  'copy',
+  'position',
+  'color',
+  'variant',
+  'interaction',
+  'validation',
+  'messages',
+  'states',
+  'i18n',
+  'trigger',
+]
+
+function pruneEmpty(value) {
+  if (value == null || value === '') return undefined
+  if (Array.isArray(value)) {
+    const next = value.map(pruneEmpty).filter((v) => v != null && v !== '')
+    return next.length ? next : undefined
+  }
+  if (typeof value === 'object') {
+    const out = {}
+    for (const [k, v] of Object.entries(value)) {
+      const pv = pruneEmpty(v)
+      if (pv != null && pv !== '') out[k] = pv
+    }
+    return Object.keys(out).length ? out : undefined
+  }
+  return value
+}
+
+function projectVisual(visual) {
+  if (visual == null || typeof visual !== 'object' || Array.isArray(visual)) return pruneEmpty(visual)
+  const out = {}
+  for (const [k, v] of Object.entries(visual)) {
+    if (CSS_VISUAL.has(k)) continue
+    const pv = pruneEmpty(v)
+    if (pv != null) out[k] = pv
+  }
+  return Object.keys(out).length ? out : undefined
+}
+
+function projectErrorNotes(block) {
+  if (block == null) return undefined
+  if (typeof block === 'string') return block
+  if (Array.isArray(block)) {
+    const notes = block
+      .map((row) => {
+        if (typeof row === 'string') return row
+        if (row && typeof row === 'object') {
+          const bits = [row.condition, row.notes].filter(Boolean)
+          return bits.length ? bits.join(': ') : undefined
+        }
+        return undefined
+      })
+      .filter(Boolean)
+    return notes.length ? notes : undefined
+  }
+  if (typeof block === 'object') {
+    if (block.notes) return block.notes
+    if (block.override === true) return pruneEmpty({ override: true, notes: block.notes })
+  }
+  return undefined
+}
+
+function projectNode(node) {
+  if (!node || typeof node !== 'object') return undefined
+  const out = {}
+  for (const key of BUSINESS_SCALAR) {
+    if (node[key] == null) continue
+    const pv = key === 'visual' ? projectVisual(node.visual) : pruneEmpty(node[key])
+    if (pv != null) out[key] = pv
+  }
+  const visual = projectVisual(node.visual)
+  if (visual) out.visual = visual
+
+  const items = (node.items || []).map(projectNode).filter(Boolean)
+  if (items.length) out.items = items
+  const sections = (node.sections || []).map(projectNode).filter(Boolean)
+  if (sections.length) out.sections = sections
+
+  const onSuccess = pruneEmpty(node.onSuccess)
+  if (onSuccess) out.onSuccess = onSuccess
+  const common = projectErrorNotes(node.onCommonError)
+  if (common) out.onCommonError = common
+  const specific = projectErrorNotes(node.onSpecificError)
+  if (specific) out.onSpecificError = specific
+
+  const actions = pruneEmpty(node.actions)
+  if (actions) out.actions = actions
+
+  return Object.keys(out).length ? out : undefined
+}
+
+function projectNavLevels(levels = []) {
+  return levels
+    .map((n) => {
+      if (!n || typeof n !== 'object') return undefined
+      const row = {}
+      if (n.label) row.label = n.label
+      if (n.purpose) row.purpose = n.purpose
+      const children = projectNavLevels(n.children || [])
+      if (children.length) row.children = children
+      return Object.keys(row).length ? row : undefined
+    })
+    .filter(Boolean)
+}
+
+function projectNav(nav) {
+  if (!nav || typeof nav !== 'object') return undefined
+  const out = {}
+  if (nav.sidebar && typeof nav.sidebar === 'object') {
+    const sb = {}
+    if (nav.sidebar.purpose) sb.purpose = nav.sidebar.purpose
+    if (nav.sidebar.enabled === false) sb.enabled = false
+    const levels = projectNavLevels(nav.sidebar.levels || [])
+    if (levels.length) sb.levels = levels
+    if (Object.keys(sb).length) out.sidebar = sb
+  }
+  if (Array.isArray(nav.breadcrumb) && nav.breadcrumb.length) {
+    out.breadcrumb = nav.breadcrumb
+      .map((c) => (typeof c === 'string' ? c : c?.label))
+      .filter(Boolean)
+  }
+  return Object.keys(out).length ? out : undefined
+}
+
+function projectActions(actions = []) {
+  return actions.map(projectNode).filter(Boolean)
+}
+
+function projectBehavior(behavior) {
+  if (!behavior || typeof behavior !== 'object') return undefined
+  const out = {}
+  for (const [verb, block] of Object.entries(behavior)) {
+    if (!block || typeof block !== 'object') continue
+    const row = {}
+    if (block.enabled === false) row.enabled = false
+    else if (block.enabled === true) row.enabled = true
+    if (block.surface) row.surface = block.surface
+    if (block.mode) row.mode = block.mode
+    if (block.notes) row.notes = block.notes
+    if (Object.keys(row).length) out[verb] = row
+  }
+  return Object.keys(out).length ? out : undefined
+}
+
+/**
+ * ir/spec.yaml layout: labels/purpose/validation/actions — no ids, tags, bind, components.
+ */
+export function projectBusinessPage(design = {}) {
+  const page = {}
+  const nav = projectNav(design.nav)
+  if (nav) page.nav = nav
+  const sections = (design.sections || []).map(projectNode).filter(Boolean)
+  if (sections.length) page.sections = sections
+  const zones = (design.zones || []).map(projectNode).filter(Boolean)
+  if (zones.length) page.zones = zones
+  const behavior = projectBehavior(design.behavior)
+  if (behavior) page.behavior = behavior
+  const actions = projectActions(design.actions || [])
+  if (actions.length) page.actions = actions
+  return page
+}
+
+export { TECH_KEYS }
+
+export function isPlaceholderLegacy(legacy) {
+  if (legacy == null) return true
+  if (typeof legacy !== 'object' || Array.isArray(legacy)) return false
+  const keys = Object.keys(legacy).filter((k) => k !== 'id')
+  if (!keys.length) return true
+  for (const key of keys) {
+    const v = legacy[key]
+    if (v == null || v === '') continue
+    if (Array.isArray(v) && v.length === 0) continue
+    if (typeof v === 'object' && !Array.isArray(v) && !Object.keys(v).length) continue
+    return false
+  }
+  return true
+}

package/engines/spec/lib/testcase-matrix-facets.mjs

@@ -0,0 +1,9 @@
+/** SSOT facet names for TC testMatrix (skill /testcase, grill-testcase). */
+export const TEST_MATRIX_FACETS = [
+  'positive_boundary',
+  'negative_length',
+  'negative_format',
+  'negative_duplicate',
+  'concurrency_double_submit',
+  'network_interruption',
+];

package/engines/spec/merge-bundle.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { mergeBundleFile } from './lib/bundle-ir.mjs'
+
+async function main() {
+  const paths = process.argv.slice(2).filter((a) => !a.startsWith('-'))
+
+  if (!paths.length) {
+    console.error('Usage: pnpm spec:merge -- <bundle.yaml> [more...]')
+    process.exit(1)
+  }
+
+  let failed = 0
+  for (const p of paths) {
+    try {
+      await mergeBundleFile(path.resolve(p))
+      console.log(`spec:merge: ${p}`)
+    } catch (error) {
+      failed++
+      console.error(`spec:merge: FAIL ${p}: ${error.message ?? error}`)
+    }
+  }
+
+  process.exit(failed > 0 ? 1 : 0)
+}
+
+main()

package/engines/spec/normalize-bundle-gen.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Partition bundle.spec → design + bundle.gen (portal-feature-bundle/v1).
+ * Usage: pnpm spec:normalize-gen -- <bundle.yaml> [--write]
+ */
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parse, stringify } from 'yaml'
+import { hasGenContent, partitionSpecSection } from './lib/bundle-schema.mjs'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+
+async function normalizeBundle(bundlePath, write = false) {
+  const absolute = path.resolve(bundlePath)
+  const bundle = parse(await readFile(absolute, 'utf8')) ?? {}
+  const { designSpec, gen } = partitionSpecSection(bundle.spec ?? {}, bundle.gen ?? {})
+
+  if (designSpec.ui?.screens) {
+    const screen = designSpec.ui.screens[0]
+    if (screen?.layout?.length) {
+      bundle.review = bundle.review ?? {}
+      bundle.review.layoutNotes = screen.layout
+    }
+    if (screen?.actions?.length) {
+      bundle.design = bundle.design ?? {}
+      bundle.design.actions = screen.actions
+    }
+    delete designSpec.ui.screens
+  }
+
+  bundle.spec = designSpec
+  if (hasGenContent(gen)) bundle.gen = gen
+  else delete bundle.gen
+
+  if (write) {
+    await writeFile(absolute, stringify(bundle, { lineWidth: 0 }), 'utf8')
+  }
+
+  return { bundlePath: absolute, hasGen: hasGenContent(gen) }
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  const write = args.includes('--write')
+  const paths = args.filter((a) => !a.startsWith('-'))
+
+  if (!paths.length) {
+    console.error('Usage: pnpm spec:normalize-gen -- <bundle.yaml> [--write]')
+    process.exit(1)
+  }
+
+  let failed = 0
+  for (const p of paths) {
+    try {
+      const { bundlePath, hasGen } = await normalizeBundle(p, write)
+      console.log(
+        `spec:normalize-gen: ${path.relative(root, bundlePath)}${hasGen ? ' (+gen)' : ''}${write ? ' [written]' : ' [dry]'}`
+      )
+    } catch (error) {
+      failed++
+      console.error(`spec:normalize-gen: FAIL ${p}: ${error.message ?? error}`)
+    }
+  }
+
+  process.exit(failed > 0 ? 1 : 0)
+}
+
+main()

package/engines/spec/split-all.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { readdir } from 'node:fs/promises'
+import path from 'node:path'
+import { splitBundleFile, checkSplitBundle } from './lib/bundle-ir.mjs'
+import { writeBundleMarkdownFile } from '../docs/lib/render-bundle-markdown.mjs'
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'ir', 'generated', 'dist', 'cache'])
+
+function parseCli(argv) {
+  const args = argv.slice(2)
+  let root = 'surfaces'
+  let check = false
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--root' && args[i + 1]) {
+      root = args[++i]
+      continue
+    }
+    if (args[i] === '--check') check = true
+  }
+  return { root: path.resolve(root), check }
+}
+
+async function globBundles(dir) {
+  const files = []
+  let entries = []
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return files
+  }
+  for (const entry of entries) {
+    const entryPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue
+      files.push(...(await globBundles(entryPath)))
+      continue
+    }
+    if (entry.isFile() && entry.name.endsWith('.bundle.yaml')) files.push(entryPath)
+  }
+  return files.sort()
+}
+
+async function main() {
+  const { root: ROOT, check } = parseCli(process.argv)
+  const bundles = await globBundles(ROOT)
+
+  if (!bundles.length) {
+    console.log(`spec:split:all: no *.bundle.yaml found under ${path.relative(process.cwd(), ROOT) || ROOT}`)
+    return
+  }
+
+  let failed = 0
+  for (const bundlePath of bundles) {
+    const rel = path.relative(process.cwd(), bundlePath)
+    try {
+      if (check) {
+        const { ok, mismatches } = await checkSplitBundle(bundlePath)
+        if (ok) console.log(`✔ spec:split:all:check ${rel}`)
+        else {
+          failed++
+          console.error(`✖ spec:split:all:check ${rel}: ${mismatches.join('; ')}`)
+        }
+        continue
+      }
+      await splitBundleFile(bundlePath)
+      await writeBundleMarkdownFile(bundlePath)
+      console.log(`✔ spec:split:all ${rel}`)
+    } catch (error) {
+      failed++
+      console.error(`✖ spec:split:all ${rel}: ${error.message ?? error}`)
+    }
+  }
+
+  console.log(`\nspec:split:all: ${bundles.length - failed}/${bundles.length} bundle(s) ${check ? 'checked' : 'split'}`)
+  process.exit(failed > 0 ? 1 : 0)
+}
+
+main()

package/engines/spec/split-bundle.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { checkSplitBundle, splitBundleFile } from './lib/bundle-ir.mjs'
+import { writeBundleMarkdownFile } from '../docs/lib/render-bundle-markdown.mjs'
+
+async function main() {
+  const args = process.argv.slice(2)
+  const check = args.includes('--check')
+  const paths = args.filter((a) => !a.startsWith('-'))
+
+  if (!paths.length) {
+    console.error('Usage: pnpm spec:split -- <bundle.yaml> [more...]')
+    console.error('       pnpm spec:split --check -- <bundle.yaml>')
+    process.exit(1)
+  }
+
+  let failed = 0
+  for (const p of paths) {
+    const resolved = path.resolve(p)
+    try {
+      if (check) {
+        const { ok, mismatches } = await checkSplitBundle(resolved)
+        if (ok) {
+          console.log(`spec:split:check OK ${path.relative(process.cwd(), resolved)}`)
+        } else {
+          failed++
+          console.error(`spec:split:check FAIL ${path.relative(process.cwd(), resolved)}`)
+          for (const m of mismatches) console.error(`  - ${m}`)
+        }
+      } else {
+        const { irDir } = await splitBundleFile(resolved)
+        const mdOut = await writeBundleMarkdownFile(resolved)
+        const mdNote = mdOut ? ` + ${path.relative(process.cwd(), mdOut)}` : ' (no MD; missing ir/spec.yaml)'
+        console.log(`spec:split: ${path.relative(process.cwd(), resolved)} → ${path.relative(process.cwd(), irDir)}/${mdNote}`)
+      }
+    } catch (error) {
+      failed++
+      console.error(`spec:split: FAIL ${p}: ${error.message ?? error}`)
+    }
+  }
+
+  process.exit(failed > 0 ? 1 : 0)
+}
+
+main()

package/engines/template-builder/runner.mjs

@@ -0,0 +1,96 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import pc from 'picocolors';
+import { scanProject, extractDna, generateDesignRegistry, parameterizeTemplate } from './scanner.mjs';
+
+export async function runBuildTemplateCode(args = []) {
+  const projectRoot = process.cwd();
+  const isDry = args.includes('--dry-run');
+  const isForce = args.includes('--force');
+  
+  let samplePath = '';
+  const sampleArg = args.find(a => a.startsWith('--sample='));
+  if (sampleArg) {
+    samplePath = sampleArg.split('=')[1];
+  }
+
+  // Load config if exists
+  const configPath = path.join(projectRoot, '.flowgrid', 'config.json');
+  let config = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (!samplePath && config.goldenSample) {
+        samplePath = config.goldenSample;
+      }
+    } catch {}
+  }
+
+  console.log(pc.cyan(`\n=== FlowGrid Custom Template & DSL Builder ===`));
+  console.log(`- Project Root: ${projectRoot}`);
+  console.log(`- Base Profile: ${config.baseProfile || 'custom'}`);
+
+  // 1. Scan Project
+  const projectInfo = scanProject(projectRoot);
+  console.log(pc.green(`✔ Detected UI Library:`), projectInfo.uiLibrary);
+
+  // 2. Resolve Golden Sample
+  if (!samplePath) {
+    // Attempt auto-discovery in src/pages or pages
+    const candidateDirs = ['src/pages', 'pages', 'src/views', 'views', 'src/app'];
+    for (const dir of candidateDirs) {
+      const fullDir = path.join(projectRoot, dir);
+      if (fs.existsSync(fullDir)) {
+        const files = fs.readdirSync(fullDir, { recursive: true });
+        const sample = files.find(f => (typeof f === 'string') && (f.endsWith('.vue') || f.endsWith('.tsx') || f.endsWith('.jsx')));
+        if (sample) {
+          samplePath = path.join(dir, sample);
+          break;
+        }
+      }
+    }
+  }
+
+  if (!samplePath || !fs.existsSync(path.join(projectRoot, samplePath))) {
+    console.log(pc.yellow(`\n[WARN] No Golden Sample found. Please provide one via: flowgrid build-template-code --sample=<path/to/Sample.vue>`));
+    return { code: 0 };
+  }
+
+  const fullSamplePath = path.join(projectRoot, samplePath);
+  console.log(pc.green(`✔ Using Golden Sample:`), samplePath);
+
+  // 3. Extract DNA
+  const dna = extractDna(fullSamplePath);
+  console.log(`  * Layout Shells: ${dna.shells.join(', ')}`);
+  console.log(`  * Widgets: ${dna.widgets.length} components extracted`);
+
+  // 4. Target output directory
+  const outputDir = path.join(projectRoot, '.flowgrid', 'adapters', 'custom');
+  if (isDry) {
+    console.log(pc.magenta(`\n[DRY RUN] Would generate:`));
+    console.log(`  - ${path.join(outputDir, 'registries', 'design.registry.json')}`);
+    console.log(`  - ${path.join(outputDir, 'templates', 'list.vue.hbs')}`);
+    return { code: 0 };
+  }
+
+  // 5. Generate Registry & Templates
+  const regResult = generateDesignRegistry({
+    uiLibrary: projectInfo.uiLibrary,
+    shells: dna.shells,
+    widgets: dna.widgets,
+    outputDir
+  });
+  console.log(pc.green(`✔ Generated Registry:`), regResult.registryPath);
+
+  const tplResult = parameterizeTemplate({
+    sampleContent: dna.rawContent,
+    outputDir,
+    templateName: dna.ext === '.tsx' ? 'list.tsx.hbs' : 'list.vue.hbs'
+  });
+  console.log(pc.green(`✔ Generated Template:`), tplResult.templatePath);
+
+  console.log(pc.cyan(`\n✨ Custom Template and DSL Registry successfully established!`));
+  console.log(pc.gray(`Run 'flowgrid split' or '/spec' to author specifications matching this custom base.\n`));
+
+  return { code: 0 };
+}