@brms/ai-skills 0.1.0

package/skills/brms-prototype-generator/scripts/plan-pages.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+function usage() {
+  console.log('Usage: node scripts/plan-pages.mjs <entry-md> --repo-root <repo> --target-project <project/name-or-path> --page-prefix <PAGE_PREFIX_4_PLUS> [--format json|markdown|both] [--out <file>]')
+}
+
+function parseArgs(argv) {
+  const args = {
+    repoRoot: process.cwd(),
+    format: 'markdown',
+    pagePrefix: '',
+    out: '',
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--repo-root') {
+      args.repoRoot = argv[i + 1] || ''
+      i += 1
+    }
+    else if (arg === '--target-project') {
+      args.targetProject = argv[i + 1] || ''
+      i += 1
+    }
+    else if (arg === '--page-prefix') {
+      args.pagePrefix = (argv[i + 1] || '').toUpperCase()
+      i += 1
+    }
+    else if (arg === '--format') {
+      args.format = argv[i + 1] || ''
+      i += 1
+    }
+    else if (arg === '--out') {
+      args.out = argv[i + 1] || ''
+      i += 1
+    }
+    else if (arg === '--help' || arg === '-h') {
+      args.help = true
+    }
+    else if (!args.entry) {
+      args.entry = arg
+    }
+    else {
+      throw new Error(`Unknown argument: ${arg}`)
+    }
+  }
+
+  if (!['json', 'markdown', 'both'].includes(args.format))
+    throw new Error('--format must be one of: json, markdown, both')
+  if (!args.pagePrefix)
+    throw new Error('--page-prefix is required before page-package generation. Use the 4+ character page prefix, for example DMDA -> DMDA01.')
+  if (args.pagePrefix && !/^[A-Z0-9]{4,}$/.test(args.pagePrefix))
+    throw new Error('--page-prefix must be a 4+ character uppercase page prefix, for example DMDA -> DMDA01. Do not use a 2-character module prefix such as KQ.')
+
+  return args
+}
+
+function toRepoRelative(filePath, repoRoot) {
+  return path.relative(repoRoot, filePath).replaceAll(path.sep, '/')
+}
+
+function normalizeProjectPath(targetProject) {
+  const clean = targetProject.replaceAll('\\', '/').replace(/^\/+|\/+$/g, '')
+  if (!clean)
+    return ''
+  if (clean.startsWith('project/'))
+    return clean
+  return `project/${clean}`
+}
+
+function discoverTarget(repoRoot, targetProject) {
+  const projectDir = normalizeProjectPath(targetProject)
+  if (!projectDir)
+    throw new Error('--target-project is required after target confirmation')
+
+  const absProjectDir = path.resolve(repoRoot, projectDir)
+  const srcDir = path.join(absProjectDir, 'src')
+  const viewsDir = path.join(srcDir, 'views')
+  const routeConfigDir = path.join(srcDir, 'routers', 'config')
+  const routeConfigIndex = path.join(routeConfigDir, 'index.ts')
+  const packageJson = path.join(absProjectDir, 'package.json')
+
+  return {
+    projectDir: toRepoRelative(absProjectDir, repoRoot),
+    packageName: fs.existsSync(packageJson) ? JSON.parse(fs.readFileSync(packageJson, 'utf8')).name || '' : '',
+    viewsDir: fs.existsSync(viewsDir) ? toRepoRelative(viewsDir, repoRoot) : '',
+    routeConfigDir: fs.existsSync(routeConfigDir) ? toRepoRelative(routeConfigDir, repoRoot) : '',
+    routeConfigIndex: fs.existsSync(routeConfigIndex) ? toRepoRelative(routeConfigIndex, repoRoot) : '',
+    canRegisterStaticRoute: fs.existsSync(routeConfigDir) && fs.existsSync(routeConfigIndex),
+  }
+}
+
+function runAnalyzer(entry, repoRoot) {
+  const script = path.join(repoRoot, '.claude', 'skills', 'brms-prototype-generator', 'scripts', 'analyze-doc.mjs')
+  const output = execFileSync(process.execPath, [script, entry, '--repo-root', repoRoot, '--format', 'json'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    maxBuffer: 20 * 1024 * 1024,
+  })
+  return JSON.parse(output)
+}
+
+function pad2(value) {
+  return String(value).padStart(2, '0')
+}
+
+function inferPageType(page) {
+  const text = `${page.title} ${page.purpose || ''}`.toLowerCase()
+  if (/附件|上传|资料|attachment|upload/.test(text))
+    return 'attachment-management'
+  if (/任务|提醒|通知|task/.test(text))
+    return 'task-management'
+  if (/详情|detail/.test(text))
+    return 'detail-display'
+  if (/新增|录入|填报|申请|entry|form/.test(text))
+    return 'form-entry'
+  if (/结构|层级|上下级|主从|master/.test(text))
+    return 'master-detail'
+  if (/查询|综合|query|search/.test(text))
+    return 'list-query'
+  return 'list-maintenance'
+}
+
+function requiredResources(type, page) {
+  const resources = new Set(['references/resource-index.md'])
+  if (['list-query', 'list-maintenance', 'attachment-management', 'task-management', 'master-detail'].includes(type))
+    resources.add('references/01-list-query.md')
+  if (type === 'form-entry')
+    resources.add('references/02-form-entry.md')
+  if (type === 'detail-display')
+    resources.add('references/03-detail-display.md')
+  if (type === 'master-detail')
+    resources.add('references/04-composite-page-package.md')
+  if (['list-maintenance', 'master-detail', 'attachment-management', 'task-management'].includes(type))
+    resources.add('references/05-dialog-patterns.md')
+
+  const text = `${page.title} ${page.purpose || ''} ${page.functionTables?.map(table => table.headers.join(' ')).join(' ') || ''}`
+  if (/新增|编辑|详情|变更|弹窗|抽屉|上传|附件|modal|dialog|drawer|upload|attachment/i.test(text))
+    resources.add('references/05-dialog-patterns.md')
+
+  return Array.from(resources)
+}
+
+function buildPageCode(pagePrefix, index) {
+  if (!pagePrefix)
+    return `CONFIRM_CODE_${pad2(index)}`
+  return `${pagePrefix}${pad2(index)}`
+}
+
+function pageTargetFile(target, pageCode) {
+  if (!target.viewsDir || /^CONFIRM_CODE_/.test(pageCode))
+    return ''
+  const module = pageCode.slice(0, 2)
+  const submodule = pageCode.slice(2, 4)
+  return `${target.viewsDir}/${module}/${submodule}/${pageCode}.vue`
+}
+
+function collectNavigationTitles(nodes, result = []) {
+  for (const node of nodes || []) {
+    result.push(node.note ? `${node.title} (${node.note})` : node.title)
+    collectNavigationTitles(node.children || [], result)
+  }
+  return result
+}
+
+function collectNavigationEdges(nodes, parent = null, result = []) {
+  for (const node of nodes || []) {
+    if (parent) {
+      result.push({
+        fromTitle: parent.title,
+        fromNote: parent.note || '',
+        toTitle: node.title,
+        toNote: node.note || '',
+      })
+    }
+    collectNavigationEdges(node.children || [], node, result)
+  }
+  return result
+}
+
+function normalizeTitle(value) {
+  return String(value || '').replace(/[()（）\s]/g, '')
+}
+
+function buildTitleToPage(pages) {
+  const exact = new Map()
+  for (const page of pages)
+    exact.set(normalizeTitle(page.title), page)
+  return exact
+}
+
+function attachNavigationContracts(pages, report) {
+  const titleToPage = buildTitleToPage(pages)
+  const edges = report.navigationBlocks.flatMap(block => collectNavigationEdges(block.tree || []))
+  const unresolved = []
+
+  for (const edge of edges) {
+    const fromPage = titleToPage.get(normalizeTitle(edge.fromTitle))
+    const toPage = titleToPage.get(normalizeTitle(edge.toTitle))
+    const contract = {
+      fromTitle: edge.fromTitle,
+      toTitle: edge.toTitle,
+      note: edge.toNote || edge.fromNote || '',
+      requiredSourceEntry: 'visible button, business-field click, card, tab, or row/cell click',
+      requiredPush: toPage ? `router.push({ path: '/web/${toPage.pageCode}', query: {...} })` : 'resolve target page code before generating',
+      requiredTargetRead: 'target page reads route.query as default filter or context',
+    }
+
+    if (fromPage && toPage) {
+      fromPage.outboundNavigation.push(contract)
+      toPage.inboundNavigation.push(contract)
+    }
+    else if (!fromPage && toPage) {
+      toPage.menuEntries.push({
+        fromTitle: edge.fromTitle,
+        note: edge.toNote || edge.fromNote || '',
+      })
+    }
+    else {
+      unresolved.push(contract)
+    }
+  }
+
+  return unresolved
+}
+
+function createPlan(report, target, pagePrefix) {
+  const completePages = report.pages.filter(page => page.complete)
+  const pages = completePages.map((page, index) => {
+    const pageCode = buildPageCode(pagePrefix, index + 1)
+    const type = inferPageType(page)
+    return {
+      index: index + 1,
+      title: page.title,
+      pageCode,
+      type,
+      source: `${page.source}:${page.line}`,
+      targetFile: pageTargetFile(target, pageCode),
+      dataSource: 'mock',
+      fieldDesignComplete: page.hasCompleteFieldDesign,
+      menuEntries: [],
+      inboundNavigation: [],
+      outboundNavigation: [],
+      issues: page.issues || [],
+      requiredResources: requiredResources(type, page),
+      forbiddenFiles: [
+        `${target.projectDir}/src/routers/config/localMenu.ts`,
+        'package.json',
+        'pnpm-lock.yaml',
+      ],
+      workerScope: pageTargetFile(target, pageCode) || '<confirm target file after page code is assigned>',
+      validationCommand: pageTargetFile(target, pageCode)
+        ? `node .claude/skills/brms-prototype-generator/scripts/validate-generated.mjs ${pageTargetFile(target, pageCode)} --repo-root .`
+        : 'assign page code first, then run validate-generated.mjs on the generated file',
+    }
+  })
+  const unresolvedNavigation = attachNavigationContracts(pages, report)
+
+  return {
+    entry: report.entry,
+    target,
+    summary: {
+      pageCount: report.summary.pageCount,
+      completePages: report.summary.completePages,
+      plannedPages: pages.length,
+      pagesMissingFieldKeys: report.summary.pagesMissingFieldKeys,
+      menuStructureDetected: report.summary.menuStructureDetected,
+      recommendedGenerationMode: report.summary.completePages >= 4 ? 'coordinator-subagents' : 'single-agent-package',
+    },
+    navigation: {
+      blocks: report.navigationBlocks.length,
+      titles: report.navigationBlocks.flatMap(block => collectNavigationTitles(block.tree || [])),
+      unresolved: unresolvedNavigation,
+    },
+    globalRules: [
+      'Do not reread the full product Markdown for each page; use this plan and the assigned page packet.',
+      'Page codes must be 6+ uppercase letters/digits and use a 4+ page prefix, for example DMDA01 maps to src/views/DM/DA/DMDA01.vue.',
+      'Default to mock-backed UI unless explicit serviceName and methodName are documented.',
+      'Every documented cross-page navigation edge must have a source UI entry with router.push({ path: "/web/<PAGE_CODE>", query }) and a target page that reads route.query.',
+      'Unresolved navigation nodes in this plan are blocking questions; map them to a generated page or ask the user before dropping the jump.',
+      'Coordinator owns shared data, route config, final validation, and handoff summary.',
+      'Workers may edit only their assigned page file.',
+    ],
+    pages,
+  }
+}
+
+function toMarkdown(plan) {
+  const lines = [
+    '# BRMS Prototype Generation Plan',
+    '',
+    `- Entry: \`${plan.entry}\``,
+    `- Target project: \`${plan.target.projectDir}\``,
+    `- Package: \`${plan.target.packageName || 'unknown'}\``,
+    `- Static route config: ${plan.target.canRegisterStaticRoute ? `yes (\`${plan.target.routeConfigDir}\`)` : 'no'}`,
+    `- Planned pages: ${plan.summary.plannedPages}`,
+    `- Recommended mode: \`${plan.summary.recommendedGenerationMode}\``,
+    `- Pages missing field keys: ${plan.summary.pagesMissingFieldKeys}`,
+    `- Menu structure detected: ${plan.summary.menuStructureDetected ? 'yes' : 'no'}`,
+    '',
+    '## Global Rules',
+    '',
+    ...plan.globalRules.map(rule => `- ${rule}`),
+    '',
+  ]
+
+  if (plan.navigation.titles.length) {
+    lines.push('## Navigation Titles', '')
+    plan.navigation.titles.forEach(title => lines.push(`- ${title}`))
+    lines.push('')
+  }
+
+  if (plan.navigation.unresolved.length) {
+    lines.push('## Unresolved Navigation', '')
+    plan.navigation.unresolved.forEach((item) => {
+      lines.push(`- ${item.fromTitle} -> ${item.toTitle}${item.note ? ` (${item.note})` : ''}: map to a generated page or ask before dropping this jump.`)
+    })
+    lines.push('')
+  }
+
+  lines.push('## Page Packets', '')
+  plan.pages.forEach((page) => {
+    lines.push(`### ${page.index}. ${page.title}`)
+    lines.push(`- Page code: \`${page.pageCode}\``)
+    lines.push(`- Type: \`${page.type}\``)
+    lines.push(`- Source: \`${page.source}\``)
+    lines.push(`- Target file: ${page.targetFile ? `\`${page.targetFile}\`` : '`assign after page code confirmation`'}`)
+    lines.push(`- Data source: \`${page.dataSource}\``)
+    lines.push(`- Field design complete: ${page.fieldDesignComplete ? 'yes' : 'no'}`)
+    if (page.issues.length)
+      lines.push(`- Issues: ${page.issues.join('; ')}`)
+    if (page.menuEntries.length) {
+      lines.push('- Menu/navigation entries:')
+      page.menuEntries.forEach(item => lines.push(`  - From ${item.fromTitle}${item.note ? ` (${item.note})` : ''}`))
+    }
+    if (page.inboundNavigation.length) {
+      lines.push('- Inbound navigation:')
+      page.inboundNavigation.forEach(item => lines.push(`  - ${item.fromTitle} -> ${item.toTitle}: ${item.requiredTargetRead}`))
+    }
+    if (page.outboundNavigation.length) {
+      lines.push('- Outbound navigation:')
+      page.outboundNavigation.forEach(item => lines.push(`  - ${item.fromTitle} -> ${item.toTitle}: ${item.requiredPush}; ${item.requiredSourceEntry}`))
+    }
+    lines.push(`- Required resources: ${page.requiredResources.map(resource => `\`${resource}\``).join(', ')}`)
+    lines.push(`- Worker scope: \`${page.workerScope}\``)
+    lines.push(`- Validation: \`${page.validationCommand}\``)
+    lines.push('')
+  })
+
+  return lines.join('\n')
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help || !args.entry) {
+    usage()
+    process.exit(args.help ? 0 : 1)
+  }
+
+  const repoRoot = path.resolve(args.repoRoot || process.cwd())
+  const target = discoverTarget(repoRoot, args.targetProject)
+  const report = runAnalyzer(args.entry, repoRoot)
+  const plan = createPlan(report, target, args.pagePrefix)
+  const json = JSON.stringify(plan, null, 2)
+  const markdown = toMarkdown(plan)
+
+  if (args.out) {
+    const outFile = path.resolve(repoRoot, args.out)
+    fs.mkdirSync(path.dirname(outFile), { recursive: true })
+    fs.writeFileSync(outFile, args.out.endsWith('.json') ? json : markdown, 'utf8')
+  }
+
+  if (args.format === 'json' || args.format === 'both')
+    console.log(json)
+  if (args.format === 'both')
+    console.log('\n---\n')
+  if (args.format === 'markdown' || args.format === 'both')
+    console.log(markdown)
+}
+
+try {
+  main()
+}
+catch (error) {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+}