@shanyucoder/flowgrid 0.1.0

package/adapters/laravel/codegen/runners/lib/detect-existing.mjs

@@ -0,0 +1,84 @@
+import { accessSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const defaultRepoRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), '../../..')
+
+function pathExists(filePath) {
+  try {
+    accessSync(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {{ module: string, entity: string, pathModel: string }} ctx
+ * @param {string} repoRoot
+ */
+export function detectExistingCodegen(ctx, repoRoot = defaultRepoRoot) {
+  const src = repoRoot
+  const moduleJson = path.join(src, 'Modules', ctx.module, 'module.json')
+  const modelPath = path.join(src, 'app/Models', ctx.pathModel, `${ctx.entity}.php`)
+  const controllerPath = path.join(
+    src,
+    'Modules',
+    ctx.module,
+    'Http/Controllers',
+    `${ctx.entity}Controller.php`
+  )
+  const testsMarker = path.join(src, 'Modules', ctx.module, 'Tests/Feature/ModuleRouteFilesTest.php')
+
+  return {
+    module: { exists: pathExists(moduleJson), path: moduleJson },
+    model: { exists: pathExists(modelPath), path: modelPath },
+    controller: { exists: pathExists(controllerPath), path: controllerPath },
+    tests: { exists: pathExists(testsMarker), path: testsMarker }
+  }
+}
+
+const COMMAND_LAYER = {
+  module: 'module',
+  model: 'model',
+  'controller-wizard': 'controller',
+  'module-test': 'tests'
+}
+
+/**
+ * @param {{ commands: object[], artisanLines: string[], ctx: object, manual: object }} plan
+ * @param {ReturnType<typeof detectExistingCodegen>} existing
+ * @param {{ force?: boolean, repoRoot?: string }} options
+ */
+export function applyExistingSkips(plan, existing, options = {}) {
+  const repoRoot = options.repoRoot ?? defaultRepoRoot
+  if (options.force) {
+    return { ...plan, skipped: [], existing }
+  }
+
+  const skipped = []
+  const commands = []
+
+  for (const cmd of plan.commands) {
+    const layer = COMMAND_LAYER[cmd.id] ?? null
+    if (layer && existing[layer]?.exists) {
+      skipped.push({
+        id: cmd.id,
+        artisan: cmd.artisan,
+        layer,
+        reason: 'already exists',
+        path: path.relative(repoRoot, existing[layer].path)
+      })
+      continue
+    }
+    commands.push(cmd)
+  }
+
+  return {
+    ...plan,
+    commands,
+    artisanLines: commands.map((c) => `php artisan ${c.artisan}`),
+    skipped,
+    existing
+  }
+}

package/adapters/laravel/codegen/runners/lib/exec-artisan.mjs

@@ -0,0 +1,86 @@
+import { spawn } from 'node:child_process'
+import { spawnSync } from 'node:child_process'
+import { resolveLaravelProject } from '../../../shared/project.mjs'
+
+const { laravelRoot } = resolveLaravelProject()
+const php = process.env.FLOWGRID_PHP || 'php'
+
+function splitCommand(line) {
+  const args = []
+  const pattern = /"((?:\\.|[^"])*)"|'((?:\\.|[^'])*)'|([^\s]+)/g
+  for (const match of line.matchAll(pattern)) {
+    args.push((match[1] ?? match[2] ?? match[3]).replace(/\\(["'])/g, '$1'))
+  }
+  return args
+}
+
+export function assertArtisanCapabilities(commands) {
+  const result = spawnSync(php, ['artisan', 'list', '--format=json'], {
+    cwd: laravelRoot,
+    encoding: 'utf8',
+    env: process.env
+  })
+  if (result.status !== 0) {
+    throw new Error(`Laravel Artisan preflight failed: ${result.stderr || result.stdout}`)
+  }
+  let listed
+  try {
+    listed = JSON.parse(result.stdout)
+  } catch {
+    throw new Error('Laravel Artisan preflight returned invalid JSON')
+  }
+  const names = new Set((listed.commands ?? []).map((entry) => entry.name))
+  const missing = [...new Set(commands.map((entry) => splitCommand(
+    entry.artisan.replace(/^php artisan\s+/, '').trim()
+  )[0]))].filter((name) => !names.has(name))
+  if (missing.length) {
+    throw new Error(`Laravel modules-v1 commands missing: ${missing.join(', ')}`)
+  }
+}
+
+/**
+ * @param {string} artisanLine e.g. "m:module Admin" or full "php artisan m:module Admin"
+ * @param {{ dryRun?: boolean }} options
+ */
+export function runArtisan(artisanLine, options = {}) {
+  const line = artisanLine.replace(/^php artisan\s+/, '').trim()
+  const [command, ...rest] = splitCommand(line)
+
+  if (options.dryRun) {
+    return Promise.resolve({ code: 0, stdout: `[dry-run] php artisan ${line}`, stderr: '' })
+  }
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(php, ['artisan', command, ...rest], {
+      cwd: laravelRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: process.env
+    })
+
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (d) => { stdout += d })
+    child.stderr.on('data', (d) => { stderr += d })
+    child.on('error', reject)
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }))
+  })
+}
+
+/**
+ * @param {{ artisan: string, id: string }[]} commands
+ * @param {{ dryRun?: boolean, stopOnError?: boolean }} options
+ */
+export async function runCommandPlan(commands, options = {}) {
+  const results = []
+  if (!options.dryRun && commands.length) assertArtisanCapabilities(commands)
+
+  for (const item of commands) {
+    const result = await runArtisan(item.artisan, { dryRun: options.dryRun })
+    results.push({ ...item, ...result })
+    if (result.code !== 0 && options.stopOnError !== false) {
+      break
+    }
+  }
+
+  return results
+}

package/adapters/laravel/codegen/runners/lib/parse-tags.mjs

@@ -0,0 +1,49 @@
+const PREFIX = {
+  genModule: '#gen:module',
+  genModelPlatform: '#gen:model-platform',
+  genModelTenant: '#gen:model-tenant',
+  genCrud: '#gen:crud',
+  genAction: '#gen:action-',
+  genSelectItems: '#gen:select-items',
+  genCreateOrUpdate: '#gen:create-or-update:',
+  genAuthApi: '#gen:auth-api',
+  genTestModule: '#gen:test-module',
+  genTestSmoke: '#gen:test-smoke',
+  skipGen: '#skip-gen:',
+  manualAction: '#manual-action:',
+  manualService: '#manual-service:',
+  manualTest: '#manual-test:',
+  callExternal: '#call-external',
+  crossEntityService: '#cross-entity-service',
+  derivedData: '#derived-data'
+}
+
+/**
+ * @param {string[]} tags
+ */
+export function parseTags(tags = []) {
+  const parsed = {
+    domain: [],
+    gen: [],
+    skipGen: [],
+    manualActions: [],
+    manualServices: [],
+    manualTests: [],
+    raw: tags.map((t) => String(t).trim()).filter(Boolean)
+  }
+
+  for (const tag of parsed.raw) {
+    if (tag === PREFIX.callExternal) parsed.domain.push('call-external')
+    else if (tag === PREFIX.crossEntityService) parsed.domain.push('cross-entity-service')
+    else if (tag === PREFIX.derivedData) parsed.domain.push('derived-data')
+    else if (tag.startsWith(PREFIX.skipGen)) parsed.skipGen.push(tag.slice(PREFIX.skipGen.length))
+    else if (tag.startsWith(PREFIX.manualAction)) parsed.manualActions.push(tag.slice(PREFIX.manualAction.length) || 'general')
+    else if (tag.startsWith(PREFIX.manualService)) parsed.manualServices.push(tag.slice(PREFIX.manualService.length))
+    else if (tag.startsWith(PREFIX.manualTest)) parsed.manualTests.push(tag.slice(PREFIX.manualTest.length))
+    else if (tag.startsWith('#gen:')) parsed.gen.push(tag)
+  }
+
+  return parsed
+}
+
+export { PREFIX }

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

@@ -0,0 +1,122 @@
+import { parseTags } from './parse-tags.mjs'
+import { analyzeWorkspace } from './workspace-analysis.mjs'
+import { resolveArtisanCommands, inferWireFromSpec } from './resolve-commands.mjs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const defaultRepoRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), '../../..')
+
+const ADD_ACTIONS = new Set(['search', 'detail', 'create', 'update', 'delete', 'bulk-delete'])
+
+/**
+ * @param {object} spec
+ */
+export function resolveCodegenContext(spec) {
+  const codegen = spec.codegen ?? {}
+  const primaryModule = spec.modules?.[0]
+  const primaryEntity = primaryModule?.entities?.[0]
+
+  const module = codegen.module ?? primaryModule?.name
+  const entity = codegen.entity ?? primaryEntity?.name
+  const pathModel = codegen.pathModel ?? primaryEntity?.mode ?? 'Platform'
+  const sharedModel = codegen.sharedModel ?? true
+  const profile = codegen.profile ?? 'crud-standard'
+  const skip = new Set([...(codegen.skip ?? []), ...parseTags(spec.tags ?? []).skipGen])
+  const tags = parseTags(spec.tags ?? [])
+
+  return { module, entity, pathModel, sharedModel, profile, skip, tags, codegen }
+}
+
+/**
+ * @param {object} spec
+ */
+function inferWireFromEndpoints(spec) {
+  return inferWireFromSpec(spec)
+}
+
+/**
+ * @param {object} spec
+ * @param {{ repoRoot?: string, force?: boolean }} options
+ */
+export function buildCommandPlan(spec, options = {}) {
+  const repoRoot = options.repoRoot ?? defaultRepoRoot
+  const ctx = resolveCodegenContext(spec)
+  const manual = buildManualItems(spec, ctx)
+  const analysis = analyzeWorkspace(ctx, spec, repoRoot)
+  const resolved = resolveArtisanCommands(spec, ctx, analysis, {
+    force: options.force,
+    profile: ctx.profile,
+    skip: ctx.skip,
+    repoRoot
+  })
+
+  return {
+    ctx,
+    commands: resolved.commands,
+    artisanLines: resolved.artisanLines,
+    manual,
+    skipped: resolved.skipped,
+    existing: analysis.files,
+    analysis,
+    paths: analysis.paths
+  }
+}
+
+/**
+ * @param {object} spec
+ * @param {object} ctx
+ */
+function buildManualItems(spec, ctx) {
+  const manual = { actions: [], services: [], tests: [] }
+
+  const hasRelationships = (spec.modules ?? []).some((m) =>
+    (m.entities ?? []).some((e) => (e.relationships ?? []).length > 0)
+  )
+  if (hasRelationships || ctx.tags.manualActions.length > 0) {
+    manual.actions.push(...ctx.tags.manualActions)
+    if (hasRelationships && !manual.actions.includes('relationships')) {
+      manual.actions.push('relationships')
+    }
+  }
+
+  if ((spec.externalCalls ?? []).length > 0) {
+    for (const call of spec.externalCalls) {
+      manual.services.push(call.id ?? call.service ?? 'external')
+    }
+  }
+  if ((spec.services ?? []).length > 0) {
+    for (const svc of spec.services) {
+      manual.services.push(svc.id ?? svc.class ?? 'cross-entity')
+    }
+  }
+  manual.services.push(...ctx.tags.manualServices)
+  manual.tests.push(...ctx.tags.manualTests)
+
+  for (const endpoint of spec.api?.endpoints ?? []) {
+    if (endpoint.action === 'custom') {
+      manual.actions.push(endpoint.id)
+    }
+  }
+
+  return manual
+}
+
+/**
+ * @param {object} spec
+ * @param {{ repoRoot?: string, force?: boolean }} options
+ */
+export function enrichSpecCodegen(spec, options = {}) {
+  const plan = buildCommandPlan(spec, options)
+  spec.codegen = {
+    ...(spec.codegen ?? {}),
+    module: plan.ctx.module,
+    entity: plan.ctx.entity,
+    pathModel: plan.ctx.pathModel,
+    sharedModel: plan.ctx.sharedModel,
+    profile: plan.ctx.profile,
+    wire: { ...inferWireFromEndpoints(spec), ...(spec.codegen?.wire ?? {}) },
+    skip: [...plan.ctx.skip],
+    commands: plan.artisanLines
+  }
+  return spec
+}

package/adapters/laravel/codegen/runners/lib/read-spec.mjs

@@ -0,0 +1,30 @@
+import { parse, stringify } from 'yaml'
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * @param {string} specPath
+ */
+export async function readSpecFile(specPath) {
+  const absolute = path.resolve(specPath)
+  const raw = await readFile(absolute, 'utf8')
+  const spec = parse(raw) ?? {}
+  const parent = path.dirname(absolute)
+  const featureDir = path.basename(parent) === 'backend' ? path.dirname(parent) : parent
+
+  return {
+    spec,
+    specFile: absolute,
+    featureDir,
+    raw
+  }
+}
+
+/**
+ * @param {string} specFile
+ * @param {object} spec
+ */
+export async function writeSpecFile(specFile, spec) {
+  const content = stringify(spec, { lineWidth: 0 })
+  await writeFile(specFile, content, 'utf8')
+}

package/adapters/laravel/codegen/runners/lib/resolve-commands.mjs

@@ -0,0 +1,234 @@
+import path from 'node:path'
+import { analyzeWorkspace, inferWireFromSpec } from './workspace-analysis.mjs'
+
+const ADD_ACTIONS = new Set(['search', 'detail', 'create', 'update', 'delete', 'bulk-delete'])
+
+/**
+ * @param {Record<string, boolean>} wire
+ */
+function needsActionClass(wire) {
+  return wire.create || wire.update || wire.delete
+}
+
+/**
+ * @param {Record<string, boolean>} wire
+ */
+function buildControllerWizardCommand(ctx, wire, analysis, options = {}) {
+  const { module, entity, pathModel, sharedModel } = ctx
+  const flags = [
+    `--shared-model=${sharedModel && !analysis.modelExists ? 'yes' : 'no'}`,
+    `--path-model=${pathModel}`,
+    `--create-request=${wire.create ? 'yes' : 'no'}`,
+    `--search-request=${wire.search ? 'yes' : 'no'}`,
+    `--action-class=${needsActionClass(wire) || analysis.files.action ? 'yes' : 'no'}`,
+    `--query-class=${wire.search || wire.detail ? 'yes' : 'no'}`,
+    `--resource-class=yes`,
+    `--overwrite-controller=${options.force ? 'yes' : 'no'}`,
+    `--wire-search=${wire.search ? 'yes' : 'no'}`,
+    `--wire-detail=${wire.detail ? 'yes' : 'no'}`,
+    `--wire-create=${wire.create ? 'yes' : 'no'}`,
+    `--wire-update=${wire.update ? 'yes' : 'no'}`,
+    `--wire-delete=${wire.delete ? 'yes' : 'no'}`,
+    `--wire-multiple-delete=${wire['bulk-delete'] ? 'yes' : 'no'}`,
+    `--select-items=${wire.selectItems ? 'yes' : 'no'}`,
+    '--skip-questions'
+  ]
+
+  if (options.force) {
+    flags.push('--force', '--yes')
+  }
+
+  return {
+    id: 'controller-wizard',
+    artisan: `m:controller ${module} ${entity} ${flags.join(' ')}`,
+    description: analysis.controllerExists
+      ? 'Controller wizard — keep existing files, wire missing endpoints'
+      : 'CRUD controller wizard with wired endpoints'
+  }
+}
+
+/**
+ * @param {object} spec
+ * @param {object} ctx from resolveCodegenContext
+ * @param {ReturnType<typeof analyzeWorkspace>} analysis
+ * @param {{ force?: boolean, profile?: string, skip?: Set<string> }} options
+ */
+export function resolveArtisanCommands(spec, ctx, analysis, options = {}) {
+  const { module, entity, pathModel, profile } = ctx
+  const skip = options.skip ?? ctx.skip ?? new Set()
+  const force = options.force === true
+  const wire = analysis.wire
+  const commands = []
+  const skipped = []
+
+  const pushSkip = (id, artisan, layer, reason, filePath) => {
+    skipped.push({
+      id,
+      artisan,
+      layer,
+      reason,
+      path: filePath ? path.relative(options.repoRoot ?? '', filePath) : null
+    })
+  }
+
+  // --- module ---
+  const wantsModule = ctx.tags?.gen?.includes('#gen:module') || profile !== 'patch'
+  const moduleArtisan = `m:module ${module}${force ? ' --force' : ''}`
+  if (!wantsModule || skip.has('module')) {
+    if (wantsModule) pushSkip('module', moduleArtisan, 'module', 'codegen.skip', null)
+  } else if (analysis.moduleExists && !force) {
+    pushSkip('module', moduleArtisan, 'module', 'already exists', analysis.paths.moduleJson)
+  } else {
+    commands.push({
+      id: 'module',
+      artisan: moduleArtisan,
+      description: 'Create module scaffold + route smoke tests'
+    })
+  }
+
+  // --- model ---
+  const modelArtisan = `m:model ${entity} ${pathModel} --create-model=yes --create-migration=yes --create-factory=yes --create-seeder=no --skip-questions${force ? ' --force' : ''}`
+  const modelTag = ctx.tags?.gen?.find((t) => t.startsWith('#gen:model-'))
+  const needsModel =
+    modelTag ||
+    (!skip.has('model') && profile !== 'patch' && !ctx.tags?.skipGen?.includes('model'))
+
+  if (!needsModel || skip.has('model')) {
+    if (needsModel) pushSkip('model', modelArtisan, 'model', 'codegen.skip', null)
+  } else if (analysis.modelExists && !force) {
+    pushSkip('model', modelArtisan, 'model', 'already exists', analysis.paths.model)
+  } else {
+    commands.push({
+      id: 'model',
+      artisan: modelArtisan,
+      description: `App model + migration (${pathModel})`
+    })
+  }
+
+  // --- controller / wire ---
+  const wantsCrud =
+    ctx.tags?.gen?.includes('#gen:crud') || profile === 'crud-standard' || profile === 'patch'
+
+  if (!skip.has('controller') && wantsCrud) {
+    if (profile === 'patch' || analysis.controllerExists) {
+      resolvePatchControllerCommands(spec, ctx, analysis, commands, skipped, { force, repoRoot: options.repoRoot })
+    } else {
+      commands.push(buildControllerWizardCommand(ctx, wire, analysis, { force }))
+    }
+  }
+
+  // --- tests ---
+  const testAllArtisan = `m:module-test ${module} --type=all${force ? ' --force' : ''}`
+  const testControllerArtisan = `m:module-test ${module} --type=controller --class=${entity}${force ? ' --force' : ''}`
+
+  if (!skip.has('tests') && (ctx.tags?.gen?.includes('#gen:test-module') || profile !== 'patch')) {
+    if (analysis.files.controllerTest && !force) {
+      pushSkip('module-test', testControllerArtisan, 'tests', 'already exists', analysis.paths.controllerTest)
+    } else if (analysis.files.moduleRouteSmokeTest && analysis.controllerExists && !analysis.files.controllerTest) {
+      commands.push({
+        id: 'module-test',
+        artisan: testControllerArtisan,
+        description: `Controller test for ${entity}`
+      })
+    } else if (analysis.files.moduleRouteSmokeTest && !force) {
+      pushSkip('module-test', testAllArtisan, 'tests', 'module tests already exist', analysis.paths.moduleRouteSmokeTest)
+    } else {
+      commands.push({
+        id: 'module-test',
+        artisan: testAllArtisan,
+        description: 'Unit/feature tests per module class'
+      })
+    }
+  }
+
+  return {
+    commands,
+    skipped,
+    artisanLines: commands.map((c) => `php artisan ${c.artisan}`),
+    analysis
+  }
+}
+
+/**
+ * @param {object} spec
+ * @param {object} ctx
+ * @param {ReturnType<typeof analyzeWorkspace>} analysis
+ * @param {object[]} commands
+ * @param {object[]} skipped
+ * @param {{ force?: boolean, repoRoot?: string }} options
+ */
+function resolvePatchControllerCommands(spec, ctx, analysis, commands, skipped, options) {
+  const { module, entity } = ctx
+  const wire = analysis.wire
+  const pending = analysis.pendingWire
+
+  if (!analysis.controllerExists) {
+    commands.push(buildControllerWizardCommand(ctx, wire, analysis, { force: options.force }))
+    return
+  }
+
+  if (analysis.controllerComplete && !options.force) {
+    skipped.push({
+      id: 'controller-wizard',
+      artisan: `m:controller ${module} ${entity} ...`,
+      layer: 'controller',
+      reason: 'controller wired for spec endpoints',
+      path: path.relative(options.repoRoot ?? '', analysis.paths.controller)
+    })
+    return
+  }
+
+  for (const endpoint of spec.api?.endpoints ?? []) {
+    const action = endpoint.action
+    if (!action || action === 'custom' || action === 'setting' || action === 'select-items') continue
+    if (!ADD_ACTIONS.has(action)) continue
+
+    const wireKey = action === 'bulk-delete' ? 'bulk-delete' : action
+    if (!wire[wireKey]) continue
+
+    if (!pending[wireKey] && !options.force) {
+      skipped.push({
+        id: `action-${endpoint.id}`,
+        artisan: `add:action ${module} ${entity} ${action}`,
+        layer: 'controller',
+        reason: 'endpoint already wired',
+        path: path.relative(options.repoRoot ?? '', analysis.paths.controller)
+      })
+      continue
+    }
+
+    const flags = ['--skip-questions']
+    if (options.force) flags.push('--yes')
+
+    commands.push({
+      id: `action-${endpoint.id}`,
+      artisan: `add:action ${module} ${entity} ${action} ${flags.join(' ')}`,
+      description: endpoint.purpose ?? `wire ${action}`
+    })
+  }
+
+  if (wire.selectItems && pending.selectItems) {
+    const flags = ['--skip-questions']
+    if (options.force) flags.push('--yes')
+    commands.push({
+      id: 'select-items',
+      artisan: `add:select-item ${module} ${entity} ${flags.join(' ')}`,
+      description: 'Wire select-items endpoint'
+    })
+  }
+
+  for (const endpoint of spec.api?.endpoints ?? []) {
+    if (endpoint.action === 'setting' && endpoint.setting) {
+      const { relation, method } = endpoint.setting
+      commands.push({
+        id: `setting-${endpoint.id}`,
+        artisan: `m:add-createOrUpdate ${module} ${entity} ${relation} ${method}`,
+        description: endpoint.purpose ?? 'hasOne setting'
+      })
+    } else if (endpoint.action === 'custom') {
+      // manual — no artisan
+    }
+  }
+}
+
+export { inferWireFromSpec }

package/adapters/laravel/codegen/runners/lib/stub-services.mjs

@@ -0,0 +1,91 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { assertContained } from '../../../shared/project.mjs'
+
+/**
+ * @param {string} fqcn
+ */
+function splitClass(fqcn) {
+  const parts = fqcn.replace(/^Modules\\/, '').split('\\')
+  const short = parts.pop()
+  const namespace = `Modules\\${parts.join('\\')}`
+  const filePath = `Modules/${parts.join('/')}/${short}.php`
+  return { namespace, short, filePath }
+}
+
+/**
+ * @param {object} spec
+ * @param {string} featureDir docs/features/{slug}
+ * @param {{ dryRun?: boolean, laravelRoot: string }} options
+ */
+export async function writeServiceStubs(spec, featureDir, options = {}) {
+  const written = []
+  const module = spec.codegen?.module ?? spec.modules?.[0]?.name
+  if (!options.laravelRoot) throw new Error('laravelRoot is required for service stubs')
+
+  const stubs = []
+
+  for (const call of spec.externalCalls ?? []) {
+    const fqcn = call.service ?? `Modules\\${module}\\Services\\External\\${pascal(call.id)}Service`
+    stubs.push({ fqcn, kind: 'external', ref: call.id })
+  }
+
+  for (const svc of spec.services ?? []) {
+    const fqcn = svc.class ?? `Modules\\${module}\\Services\\${pascal(svc.id)}Service`
+    stubs.push({ fqcn, kind: 'cross-entity', ref: svc.id })
+  }
+
+  for (const stub of stubs) {
+    const { namespace, short, filePath } = splitClass(stub.fqcn)
+    const target = assertContained(options.laravelRoot, path.join(options.laravelRoot, filePath), 'service stub')
+
+    const body = `<?php
+
+namespace ${namespace};
+
+/**
+ * ${stub.kind} service — implement per HANDOFF (#manual-service:${stub.ref}).
+ *
+ * @see ${path.join(featureDir, 'generated/HANDOFF.md')}
+ */
+class ${short}
+{
+    public function __invoke(mixed ...$args): mixed
+    {
+        throw new \\RuntimeException('TODO: implement ${stub.ref}');
+    }
+}
+`
+
+    if (options.dryRun) {
+      written.push(`[dry-run] ${filePath}`)
+      continue
+    }
+
+    await mkdir(path.dirname(target), { recursive: true })
+    try {
+      await writeFile(target, body, { flag: 'wx' })
+      written.push(filePath)
+    } catch (err) {
+      if (err.code === 'EEXIST') {
+        written.push(`${filePath} (exists, skipped)`)
+      } else {
+        throw err
+      }
+    }
+  }
+
+  return written
+}
+
+/**
+ * @param {string} value
+ */
+function pascal(value) {
+  return String(value)
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join('')
+}