@shanyucoder/flowgrid 0.1.0

package/adapters/laravel/codegen/runners/lib/tag-plan.mjs

@@ -0,0 +1,155 @@
+import { loadCodegenRegistry, resolveTagDefinition } from './codegen-registry.mjs'
+
+/**
+ * @param {object} spec
+ * @param {{ ctx: object, commands: object[], artisanLines: string[], manual: object }} plan
+ * @param {Record<string, unknown>} registry
+ */
+export function buildTagPlan(spec, plan, registry) {
+  const entries = []
+  const commandById = Object.fromEntries(plan.commands.map((c) => [c.id, c]))
+  const skippedById = Object.fromEntries((plan.skipped ?? []).map((s) => [s.id, s]))
+  const seen = new Set()
+
+  for (const tag of spec.tags ?? []) {
+    if (seen.has(tag)) continue
+    seen.add(tag)
+
+    const def = resolveTagDefinition(tag, registry)
+    const entry = {
+      tag,
+      phase: def.phase ?? 'unknown',
+      layer: def.layer ?? null,
+      owner: def.owner ?? (def.phase === 'codegen' ? 'script' : def.phase === 'handoff' ? 'agent' : null),
+      match: def.match,
+      commandId: resolveCommandId(tag, def, plan),
+      artisan: null,
+      handoffTopic: null,
+      extract: def.extract ?? null,
+      status: 'pending'
+    }
+
+    if (entry.commandId && commandById[entry.commandId]) {
+      entry.artisan = commandById[entry.commandId].artisan
+      entry.status = 'planned'
+    } else if (entry.commandId && skippedById[entry.commandId]) {
+      entry.artisan = skippedById[entry.commandId].artisan
+      entry.status = 'skipped'
+    } else if (def.phase === 'handoff' || tag.startsWith('#manual-')) {
+      entry.handoffTopic = def.suffix ?? (tag.split(':').slice(1).join(':') || 'general')
+      entry.status = 'handoff'
+    } else if (def.phase === 'spec') {
+      entry.status = 'spec-only'
+    } else if (def.layer === 'skip') {
+      entry.status = 'skipped'
+      entry.handoffTopic = def.suffix
+    } else if (def.phase === 'codegen' && !entry.commandId) {
+      entry.status = 'skipped'
+    }
+
+    entries.push(entry)
+  }
+
+  for (const cmd of plan.commands) {
+    if (!entries.some((e) => e.commandId === cmd.id)) {
+      entries.push({
+        tag: `(command:${cmd.id})`,
+        phase: 'codegen',
+        layer: cmd.id,
+        owner: 'script',
+        match: 'inferred',
+        commandId: cmd.id,
+        artisan: cmd.artisan,
+        description: cmd.description,
+        handoffTopic: null,
+        extract: 'codegen.md',
+        status: 'planned'
+      })
+    }
+  }
+
+  for (const topic of [...new Set(plan.manual.actions)]) {
+    if (!entries.some((e) => e.handoffTopic === topic && e.phase === 'handoff')) {
+      entries.push({
+        tag: `#manual-action:${topic}`,
+        phase: 'handoff',
+        layer: 'action',
+        owner: 'agent',
+        match: 'inferred',
+        commandId: null,
+        artisan: null,
+        handoffTopic: topic,
+        extract: 'entity-relationship.md',
+        status: 'handoff'
+      })
+    }
+  }
+
+  for (const id of [...new Set(plan.manual.services)]) {
+    if (!entries.some((e) => e.handoffTopic === id && e.layer === 'service')) {
+      entries.push({
+        tag: `#manual-service:${id}`,
+        phase: 'handoff',
+        layer: 'service',
+        owner: 'agent',
+        match: 'inferred',
+        commandId: null,
+        artisan: null,
+        handoffTopic: id,
+        extract: 'call-external.md',
+        status: 'handoff'
+      })
+    }
+  }
+
+  for (const id of [...new Set(plan.manual.tests)]) {
+    entries.push({
+      tag: `#manual-test:${id}`,
+      phase: 'handoff',
+      layer: 'tests',
+      owner: 'unit',
+      match: 'inferred',
+      commandId: null,
+      artisan: null,
+      handoffTopic: id,
+      extract: 'unit-coverage.md',
+      status: 'handoff'
+    })
+  }
+
+  return entries
+}
+
+/**
+ * @param {string} tag
+ * @param {Record<string, unknown>} def
+ * @param {{ commands: object[] }} plan
+ */
+function resolveCommandId(tag, def, plan) {
+  if (def.commandId) return def.commandId
+
+  if (tag.startsWith('#gen:action-')) {
+    const action = tag.slice('#gen:action-'.length)
+    const found = plan.commands.find((c) => c.id === `action-${action}` || c.artisan?.includes(` ${action}`))
+    return found?.id ?? null
+  }
+
+  if (tag === '#gen:crud') return 'controller-wizard'
+  if (tag === '#gen:module') return 'module'
+  if (tag === '#gen:model-platform' || tag === '#gen:model-tenant') return 'model'
+  if (tag === '#gen:test-module') return 'module-test'
+  if (tag === '#gen:select-items') {
+    return plan.commands.find((c) => c.id?.startsWith('select-items'))?.id ?? null
+  }
+
+  return null
+}
+
+/**
+ * @param {object} spec
+ * @param {{ ctx: object, commands: object[], artisanLines: string[], manual: object }} plan
+ */
+export async function buildTagPlanWithRegistry(spec, plan) {
+  const registry = await loadCodegenRegistry()
+  return { registry, tagPlan: buildTagPlan(spec, plan, registry) }
+}

package/adapters/laravel/codegen/runners/lib/validate.mjs

@@ -0,0 +1,77 @@
+import { parseTags } from './parse-tags.mjs'
+import { validateTagsAgainstRegistry } from './codegen-registry.mjs'
+import { resolveCodegenContext } from './plan.mjs'
+
+/**
+ * @param {object} spec
+ * @param {{ requireApproved?: boolean, registry?: Record<string, unknown> }} options
+ */
+export function validateSpec(spec, options = {}) {
+  const errors = []
+  const warnings = []
+  const ctx = resolveCodegenContext(spec)
+  const tags = parseTags(spec.tags ?? [])
+
+  if (!ctx.module) errors.push('Missing codegen.module (or modules[0].name)')
+  if (!ctx.entity) errors.push('Missing codegen.entity (or modules[0].entities[0].name)')
+  if (!ctx.pathModel) errors.push('Missing codegen.pathModel (Platform|Tenant)')
+  const className = /^[A-Z][A-Za-z0-9]*$/
+  if (ctx.module && !className.test(ctx.module)) {
+    errors.push(`Invalid codegen.module "${ctx.module}" — expected a PHP class segment`)
+  }
+  if (ctx.entity && !className.test(ctx.entity)) {
+    errors.push(`Invalid codegen.entity "${ctx.entity}" — expected a PHP class segment`)
+  }
+  if (ctx.pathModel && !className.test(ctx.pathModel)) {
+    errors.push(`Invalid codegen.pathModel "${ctx.pathModel}"`)
+  }
+
+  const approval = spec.approval?.status
+  if (options.requireApproved && approval !== 'approved') {
+    errors.push(`approval.status must be "approved" (current: ${approval ?? 'missing'})`)
+  } else if (!approval) {
+    warnings.push('approval.status not set — grill should set draft|reviewed|approved')
+  }
+
+  const endpoints = spec.api?.endpoints ?? []
+  if (endpoints.length === 0) {
+    errors.push('api.endpoints is empty')
+  }
+
+  for (const endpoint of endpoints) {
+    if (!endpoint.action) {
+      errors.push(`Endpoint ${endpoint.id ?? endpoint.path} missing action (search|detail|create|update|delete|select-items|setting|custom)`)
+    }
+    if (endpoint.action === 'setting' && !endpoint.setting?.relation) {
+      errors.push(`Endpoint ${endpoint.id} action=setting requires setting.relation and setting.method`)
+    }
+  }
+
+  if (tags.domain.includes('call-external') || tags.raw.includes('#call-external')) {
+    if (!(spec.externalCalls ?? []).length) {
+      errors.push('#call-external tag requires externalCalls[] block')
+    }
+  }
+
+  if (tags.domain.includes('cross-entity-service') || tags.raw.includes('#cross-entity-service')) {
+    if (!(spec.services ?? []).length) {
+      errors.push('#cross-entity-service tag requires services[] block')
+    }
+  }
+
+  const openQuestions = spec.openQuestions ?? []
+  if (openQuestions.length > 0) {
+    warnings.push(`${openQuestions.length} openQuestions remain — resolve or accept before /api-code`)
+  }
+
+  const plan = spec.codegen?.commands ?? []
+  if (plan.length === 0) {
+    warnings.push('codegen.commands empty — run api:gen:dry --write-spec after grill to populate')
+  }
+
+  if (options.registry) {
+    warnings.push(...validateTagsAgainstRegistry(spec.tags ?? [], options.registry))
+  }
+
+  return { ok: errors.length === 0, errors, warnings, ctx }
+}

package/adapters/laravel/codegen/runners/lib/workspace-analysis.mjs

@@ -0,0 +1,202 @@
+import { accessSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const defaultRepoRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), '../../..')
+
+const WIRE_TRAITS = {
+  search: 'EntrySearchTrait',
+  detail: 'EntryDetailTrait',
+  create: 'EntryCreateTrait',
+  update: 'EntryUpdateTrait',
+  delete: 'EntryDeleteTrait',
+  'bulk-delete': 'EntryBulkDeleteTrait',
+  selectItems: 'EntrySelectTrait'
+}
+
+function exists(filePath) {
+  try {
+    accessSync(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function readText(filePath) {
+  try {
+    return readFileSync(filePath, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * @param {{ module: string, entity: string, pathModel: string }} ctx
+ * @param {string} repoRoot
+ */
+export function resolveWorkspacePaths(ctx, repoRoot = defaultRepoRoot) {
+  const src = repoRoot
+  const moduleRoot = path.join(src, 'Modules', ctx.module)
+  const entity = ctx.entity
+
+  return {
+    moduleJson: path.join(moduleRoot, 'module.json'),
+    model: path.join(src, 'app/Models', ctx.pathModel, `${entity}.php`),
+    modelTest: path.join(src, 'tests/Unit/Models', ctx.pathModel, `${entity}ModelTest.php`),
+    factory: path.join(src, 'database/factories', ctx.pathModel, `${entity}Factory.php`),
+    controller: path.join(moduleRoot, 'Http/Controllers', `${entity}Controller.php`),
+    createRequest: path.join(moduleRoot, 'Http/Requests', `${entity}CreateRequest.php`),
+    searchRequest: path.join(moduleRoot, 'Http/Requests', `${entity}SearchRequest.php`),
+    action: path.join(moduleRoot, 'Http/Actions', `${entity}Action.php`),
+    query: path.join(moduleRoot, 'Http/Queries', `${entity}Query.php`),
+    resource: path.join(moduleRoot, 'Http/Resources', `${entity}Resource.php`),
+    routes: path.join(moduleRoot, 'Routes/api.php'),
+    moduleRouteSmokeTest: path.join(moduleRoot, 'Tests/Feature/ModuleRouteFilesTest.php'),
+    controllerTest: path.join(
+      moduleRoot,
+      'Tests/Feature/Http/Controllers',
+      `${entity}ControllerTest.php`
+    )
+  }
+}
+
+/**
+ * @param {string} controllerContent
+ * @param {string} routesContent
+ * @param {string} entity
+ */
+export function detectWiredActions(controllerContent, routesContent, entity) {
+  const prefix = entity.toLowerCase()
+  const wired = {
+    search: false,
+    detail: false,
+    create: false,
+    update: false,
+    delete: false,
+    'bulk-delete': false,
+    selectItems: false
+  }
+
+  for (const [action, trait] of Object.entries(WIRE_TRAITS)) {
+    if (controllerContent.includes(`use ${trait}`) || controllerContent.includes(`use ${trait};`)) {
+      wired[action] = true
+    }
+  }
+
+  const routeChecks = {
+    search: [`'search'`, `"search"`, 'search('],
+    detail: ['getDetail', 'detail/{id}'],
+    create: ["Route::post('/',", 'Route::post("/"', ",'create'"],
+    update: ["'update'", 'edit/{id}'],
+    delete: ["'delete'", 'delete/{id}'],
+    'bulk-delete': ['bulkDelete', 'bulk-delete'],
+    selectItems: ['select-items', 'selectItems', 'EntrySelectTrait']
+  }
+
+  const routeScope = routesContent.includes(`prefix('${prefix}')`)
+    ? routesContent.slice(routesContent.indexOf(`prefix('${prefix}')`))
+    : routesContent
+
+  for (const [action, needles] of Object.entries(routeChecks)) {
+    if (needles.some((n) => routeScope.includes(n))) {
+      wired[action] = true
+    }
+  }
+
+  return wired
+}
+
+/**
+ * @param {object} spec
+ */
+export function inferWireFromSpec(spec) {
+  const wire = {
+    search: false,
+    detail: false,
+    create: false,
+    update: false,
+    delete: false,
+    'bulk-delete': false,
+    selectItems: false
+  }
+
+  for (const endpoint of spec.api?.endpoints ?? []) {
+    const action = endpoint.action
+    if (action === 'search') wire.search = true
+    if (action === 'detail') wire.detail = true
+    if (action === 'create') wire.create = true
+    if (action === 'update') wire.update = true
+    if (action === 'delete') wire.delete = true
+    if (action === 'bulk-delete') wire['bulk-delete'] = true
+    if (action === 'select-items') wire.selectItems = true
+  }
+
+  return { ...wire, ...(spec.codegen?.wire ?? {}) }
+}
+
+/**
+ * @param {{ module: string, entity: string, pathModel: string }} ctx
+ * @param {object} spec
+ * @param {string} repoRoot
+ */
+export function analyzeWorkspace(ctx, spec, repoRoot = defaultRepoRoot) {
+  const paths = resolveWorkspacePaths(ctx, repoRoot)
+  const controllerContent = readText(paths.controller)
+  const routesContent = readText(paths.routes)
+  const wire = inferWireFromSpec(spec)
+
+  const files = {
+    module: exists(paths.moduleJson),
+    model: exists(paths.model),
+    modelTest: exists(paths.modelTest),
+    factory: exists(paths.factory),
+    controller: exists(paths.controller),
+    createRequest: exists(paths.createRequest),
+    searchRequest: exists(paths.searchRequest),
+    action: exists(paths.action),
+    query: exists(paths.query),
+    resource: exists(paths.resource),
+    moduleRouteSmokeTest: exists(paths.moduleRouteSmokeTest),
+    controllerTest: exists(paths.controllerTest)
+  }
+
+  const wired = files.controller
+    ? detectWiredActions(controllerContent, routesContent, ctx.entity)
+    : {
+        search: false,
+        detail: false,
+        create: false,
+        update: false,
+        delete: false,
+        'bulk-delete': false,
+        selectItems: false
+      }
+
+  const pendingWire = {}
+  for (const [key, wanted] of Object.entries(wire)) {
+    if (!wanted) continue
+    const wiredKey = key === 'selectItems' ? 'selectItems' : key
+    pendingWire[key] = !wired[wiredKey]
+  }
+
+  return {
+    paths,
+    files,
+    wire,
+    wired,
+    pendingWire,
+    moduleExists: files.module,
+    modelExists: files.model,
+    controllerExists: files.controller,
+    controllerComplete:
+      files.controller &&
+      (!wire.search || wired.search) &&
+      (!wire.detail || wired.detail) &&
+      (!wire.create || wired.create) &&
+      (!wire.update || wired.update) &&
+      (!wire.delete || wired.delete) &&
+      (!wire['bulk-delete'] || wired['bulk-delete']) &&
+      (!wire.selectItems || wired.selectItems)
+  }
+}

package/adapters/laravel/codegen/runners/lib/write-handoff.mjs

@@ -0,0 +1,149 @@
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+
+const MANUAL_HINTS = {
+  relationships: 'Sync Eloquent relationships in Action — `entity-relationship.md`',
+  'chain-scope': 'Scope Query by session chain_id — tenant/chain context in Query',
+  'default-per-page': 'Set default per_page (e.g. 100) in SearchRequest or Query — assert in `/unit`',
+  'nested-managers-resource': 'Map nested managers in Resource — align with OpenAPI `02-openapi.yaml`'
+}
+
+/**
+ * @param {object} params
+ */
+export function renderHandoffMarkdown({
+  spec,
+  specFile,
+  plan,
+  tagPlan = [],
+  commandResults = [],
+  serviceStubs = [],
+  dryRun = false
+}) {
+  const slug = spec.feature?.id ?? 'feature'
+  const module = plan.ctx.module
+  const lines = [
+    `# HANDOFF — ${slug}`,
+    '',
+    `Generated: ${new Date().toISOString()}`,
+    `Spec: \`${specFile}\``,
+    `Manifest: \`generated/codegen.manifest.json\``,
+    dryRun ? '\nMode: **dry-run** (no files written, no artisan executed)\n' : '',
+    '## Generator commands',
+    '',
+    ...(plan.artisanLines.length
+      ? plan.artisanLines.map((l) => `- \`${l}\``)
+      : ['- _(none — check codegen block)_']),
+    ''
+  ]
+
+  if (tagPlan.length > 0) {
+    lines.push('## Tag plan', '')
+    lines.push('| Tag | Phase | Status | Next |')
+    lines.push('|-----|-------|--------|------|')
+    for (const entry of tagPlan) {
+      const next =
+        entry.artisan
+          ? `\`${entry.artisan}\``
+          : entry.handoffTopic
+            ? `HANDOFF: ${entry.handoffTopic}`
+            : entry.extract
+              ? `see \`${entry.extract}\``
+              : '—'
+      lines.push(`| \`${entry.tag}\` | ${entry.phase} | ${entry.status} | ${next} |`)
+    }
+    lines.push('')
+  }
+
+  if (commandResults.length > 0) {
+    lines.push('## Execution log', '')
+    for (const r of commandResults) {
+      const status = r.code === 0 ? 'OK' : `FAIL (${r.code})`
+      lines.push(`- **${r.id}** [${status}]: \`php artisan ${r.artisan}\``)
+      if (r.code !== 0 && r.stderr) {
+        lines.push(`  - stderr: \`${r.stderr.trim().slice(0, 200)}\``)
+      }
+    }
+    lines.push('')
+  }
+
+  const handoffEntries = tagPlan.filter((e) => e.status === 'handoff')
+  const manualActions = [
+    ...new Set([
+      ...handoffEntries.filter((e) => e.layer === 'action').map((e) => e.handoffTopic),
+      ...plan.manual.actions
+    ])
+  ].filter(Boolean)
+
+  if (manualActions.length > 0) {
+    lines.push('## Agent next — #manual-action', '')
+    for (const item of manualActions) {
+      const hint = MANUAL_HINTS[item] ?? 'Implement per spec notes and `entity-relationship.md`'
+      lines.push(`- [ ] **${item}** — ${hint}`)
+    }
+    lines.push('')
+  }
+
+  const manualServices = [
+    ...new Set([
+      ...handoffEntries.filter((e) => e.layer === 'service').map((e) => e.handoffTopic),
+      ...plan.manual.services
+    ])
+  ].filter(Boolean)
+
+  if (manualServices.length > 0 || serviceStubs.length > 0) {
+    lines.push('## Agent next — #manual-service', '')
+    for (const id of manualServices) {
+      lines.push(`- [ ] Implement service **${id}** — see \`call-external.md\` / \`cross-entity-service.md\``)
+    }
+    for (const stub of serviceStubs) {
+      lines.push(`- Stub: \`${stub}\``)
+    }
+    lines.push('')
+  }
+
+  const manualTests = [
+    ...new Set([
+      ...handoffEntries.filter((e) => e.layer === 'tests').map((e) => e.handoffTopic),
+      ...plan.manual.tests
+    ])
+  ].filter(Boolean)
+
+  if (manualTests.length > 0) {
+    lines.push('## Agent next — #manual-test', '')
+    for (const t of manualTests) {
+      lines.push(`- [ ] **${t}** — implement in `/unit` (\`unit-coverage.md\`)`)
+    }
+    lines.push('')
+  }
+
+  lines.push(
+    '## Verify',
+    '',
+    '```bash',
+    `php artisan test --filter=${module}`,
+    '```',
+    '',
+    '## OpenAPI',
+    '',
+    'Resource fields must match `02-openapi.yaml`. Update YAML if contract fix found.',
+    ''
+  )
+
+  return lines.join('\n')
+}
+
+/**
+ * @param {string} featureDir
+ * @param {string} content
+ * @param {{ dryRun?: boolean }} options
+ */
+export async function writeHandoff(featureDir, content, options = {}) {
+  const target = path.join(featureDir, 'generated', 'HANDOFF.md')
+  if (options.dryRun) {
+    return target
+  }
+  await mkdir(path.dirname(target), { recursive: true })
+  await writeFile(target, content, 'utf8')
+  return target
+}

package/adapters/laravel/codegen/runners/lib/write-manifest.mjs

@@ -0,0 +1,81 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * @param {object} params
+ */
+export function buildCodegenManifest({
+  spec,
+  specFile,
+  plan,
+  tagPlan,
+  registry,
+  commandResults = [],
+  serviceStubs = [],
+  dryRun = false
+}) {
+  return {
+    generatedAt: new Date().toISOString(),
+    dryRun,
+    specFile,
+    feature: spec.feature?.id ?? null,
+    approval: spec.approval?.status ?? null,
+    profile: plan.ctx.profile,
+    module: plan.ctx.module,
+    entity: plan.ctx.entity,
+    pathModel: plan.ctx.pathModel,
+    registry: registry.registryPath ?? 'registries/codegen.registry.json',
+    wire: spec.codegen?.wire ?? null,
+    tags: spec.tags ?? [],
+    tagPlan,
+    commands: plan.commands.map((c) => ({
+      id: c.id,
+      artisan: c.artisan,
+      description: c.description ?? null,
+      shell: `php artisan ${c.artisan}`
+    })),
+    artisanLines: plan.artisanLines,
+    existing: plan.existing ?? null,
+    workspace: plan.analysis
+      ? {
+          files: plan.analysis.files,
+          wired: plan.analysis.wired,
+          pendingWire: plan.analysis.pendingWire,
+          controllerComplete: plan.analysis.controllerComplete
+        }
+      : null,
+    skipped: (plan.skipped ?? []).map((s) => ({
+      id: s.id,
+      layer: s.layer,
+      artisan: s.artisan,
+      reason: s.reason,
+      path: s.path
+    })),
+    manual: plan.manual,
+    serviceStubs,
+    execution: commandResults.map((r) => ({
+      id: r.id,
+      status: r.stdout?.startsWith('[skipped]')
+        ? 'SKIPPED'
+        : r.code === 0
+          ? 'OK'
+          : `FAIL (${r.code})`,
+      artisan: r.artisan
+    }))
+  }
+}
+
+/**
+ * @param {string} featureDir
+ * @param {Record<string, unknown>} manifest
+ * @param {{ dryRun?: boolean }} options
+ */
+export async function writeCodegenManifest(featureDir, manifest, options = {}) {
+  const target = path.join(featureDir, 'generated', 'codegen.manifest.json')
+  if (options.dryRun) {
+    return target
+  }
+  await mkdir(path.dirname(target), { recursive: true })
+  await writeFile(target, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+  return target
+}