@shanyucoder/flowgrid 0.1.0

package/adapters/laravel/codegen/runners/validate-registry.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { loadCodegenRegistry, REGISTRY_REL, resolveTagDefinition } from './lib/codegen-registry.mjs'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+
+async function main() {
+  const registry = await loadCodegenRegistry(root)
+  const errors = []
+  const warnings = []
+
+  console.log(`api-codegen.registry v${registry.version}`)
+  console.log(`  path: ${REGISTRY_REL}`)
+  console.log(`  gen tags: ${Object.keys(registry.genTags ?? {}).length}`)
+  console.log(`  prefix rules: ${Object.keys(registry.prefixRules ?? {}).length}`)
+  console.log(`  domain tags: ${Object.keys(registry.domainTags ?? {}).length}`)
+  console.log(`  profiles: ${Object.keys(registry.profiles ?? {}).join(', ')}`)
+
+  for (const [tag, def] of Object.entries(registry.genTags ?? {})) {
+    if (!def.phase) warnings.push(`genTags.${tag}: missing phase`)
+    if (def.phase === 'codegen' && !def.commandId && !def.note) {
+      warnings.push(`genTags.${tag}: codegen tag without commandId`)
+    }
+  }
+
+  for (const [alias, canonical] of Object.entries(registry.aliases ?? {})) {
+    const resolved = resolveTagDefinition(canonical, registry)
+    if (resolved.match === 'unknown') {
+      errors.push(`aliases "${alias}" → "${canonical}" — target not in registry`)
+    }
+  }
+
+  for (const warning of warnings) {
+    console.warn(`  warn: ${warning}`)
+  }
+
+  if (errors.length > 0) {
+    for (const error of errors) {
+      console.error(`  error: ${error}`)
+    }
+    process.exit(1)
+  }
+
+  console.log('  validate: OK')
+}
+
+main().catch((error) => {
+  console.error(error.message ?? error)
+  process.exit(1)
+})

package/adapters/laravel/php/README.md

@@ -0,0 +1,26 @@
+# Laravel PHP unitgen
+
+Source of truth for the Laravel BE unit-test generator. Synced by
+`flowgrid init --type=be --adapter=laravel` into the product checkout at
+`src/.flowgrid/php/` (gitignored, owned by `.flowgrid/php/install-manifest.json`).
+
+## Run
+
+```bash
+cd src   # Laravel app root (artisan + composer.json)
+php .flowgrid/php/bin/unit-gen.php --spec <base-docs>/…/01-backend-spec.yaml [--dry-run] [--force] [--phase all]
+```
+
+Or via toolkit CLI (spawns the synced engine):
+
+```bash
+flowgrid api-unit-gen --adapter=laravel -- --spec <path>
+```
+
+## Dependency
+
+Product `composer.json` must include `symfony/yaml` in `require-dev` (used to
+parse `01-backend-spec.yaml` / `02-openapi.yaml`).
+
+Registries stay at product-root `registries/unit-test.registry.json` (also
+synced by init from `adapters/laravel/registries/`).

package/adapters/laravel/php/bin/unit-gen.php

@@ -0,0 +1,307 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+$engineRoot = dirname(__DIR__);
+require_once $engineRoot.'/src/Autoload.php';
+
+use FlowGrid\Laravel\UnitGen\ArtisanRunner;
+use FlowGrid\Laravel\UnitGen\CodegenManifest;
+use FlowGrid\Laravel\UnitGen\ProjectResolver;
+use FlowGrid\Laravel\UnitGen\SpecReader;
+use FlowGrid\Laravel\UnitGen\UnitPlanner;
+use FlowGrid\Laravel\UnitGen\UnitRegistry;
+use FlowGrid\Laravel\UnitGen\WriteFiles;
+
+function bootstrapVendor(): void
+{
+    $roots = [];
+    $ck = getenv('FLOWGRID_PROJECT_ROOT') ?: '';
+    if ($ck !== '') {
+        $roots[] = $ck;
+        $roots[] = $ck.'/src';
+        $roots[] = $ck.'/vendor';
+    }
+    try {
+        $resolved = ProjectResolver::resolve();
+        $roots[] = $resolved['laravelRoot'];
+        $roots[] = $resolved['targetRoot'];
+    } catch (Throwable) {
+        // resolve later after args; vendor may still be findable
+    }
+
+    foreach ($roots as $root) {
+        foreach ([$root.'/vendor/autoload.php', $root.'/../vendor/autoload.php'] as $autoload) {
+            if (is_file($autoload)) {
+                require_once $autoload;
+
+                return;
+            }
+        }
+    }
+}
+
+/**
+ * @param  list<string>  $argv
+ * @return array{dryRun: bool, force: bool, spec: ?string, phase: string, execute: bool}
+ */
+function parseArgs(array $argv): array
+{
+    $options = [
+        'dryRun' => false,
+        'force' => false,
+        'spec' => null,
+        'phase' => 'all',
+        'execute' => true,
+    ];
+
+    for ($i = 0; $i < count($argv); $i++) {
+        $arg = $argv[$i];
+        if ($arg === '--dry' || $arg === '--dry-run') {
+            $options['dryRun'] = true;
+        } elseif ($arg === '--force') {
+            $options['force'] = true;
+        } elseif ($arg === '--plan-only') {
+            $options['execute'] = false;
+        } elseif ($arg === '--phase') {
+            $options['phase'] = $argv[++$i] ?? 'all';
+        } elseif ($arg === '--spec') {
+            $options['spec'] = $argv[++$i] ?? null;
+        } elseif (!str_starts_with($arg, '-') && $options['spec'] === null) {
+            $options['spec'] = $arg;
+        }
+    }
+
+    if ($options['spec'] === null) {
+        throw new RuntimeException(
+            'Usage: php unit-gen.php --spec <01-backend-spec.yaml> [--dry-run] [--force] [--phase stub|enriched|behavioral|all] [--plan-only]'
+        );
+    }
+
+    return $options;
+}
+
+function resolveSpecPaths(string $root, ?string $specArg, ?string $idArg): array
+{
+    if ($specArg !== null) {
+        return [$specArg];
+    }
+    if ($idArg === null) {
+        throw new RuntimeException("Either --spec or --id must be provided");
+    }
+    $script = dirname(__DIR__, 2) . '/shared/resolve-cli.mjs';
+    if (!is_file($script)) {
+        throw new RuntimeException("resolve-cli.mjs not found at $script");
+    }
+    $cmd = sprintf("node %s %s %s api-codegen", escapeshellarg($script), escapeshellarg($root), escapeshellarg($idArg));
+    $output = shell_exec($cmd);
+    if ($output === null || $output === false) {
+        throw new RuntimeException("Failed to execute resolve-cli.mjs for --id $idArg");
+    }
+    $data = json_decode($output, true);
+    if (!$data || !($data['success'] ?? false)) {
+        $err = $data['error'] ?? 'Unknown error';
+        throw new RuntimeException("Failed to resolve ID $idArg: $err");
+    }
+    foreach ($data['notes'] ?? [] as $note) {
+        echo "  note: $note\n";
+    }
+    $paths = $data['paths'] ?? [];
+    if (count($paths) === 0) {
+        throw new RuntimeException("--id $idArg: no codegen specs");
+    }
+    $kind = $data['kind'] ?? 'unknown';
+    echo "api-unit-gen: --id $idArg -> " . count($paths) . " spec(s) ($kind)\n";
+    return $paths;
+}
+
+try {
+    bootstrapVendor();
+    $options = parseArgs(array_slice($argv, 1));
+    $project = ProjectResolver::resolve();
+    $laravelRoot = $project['laravelRoot'];
+
+    // Prefer product vendor after resolve
+    foreach ([$laravelRoot.'/vendor/autoload.php', $project['targetRoot'].'/vendor/autoload.php'] as $autoload) {
+        if (is_file($autoload)) {
+            require_once $autoload;
+            break;
+        }
+    }
+
+    $loaded = UnitRegistry::load($project['targetRoot']);
+    $registry = $loaded['registry'];
+
+    $idArg = null;
+    $specArg = $options['spec'];
+    if ($options['spec'] === null) {
+        for ($i = 1; $i < count($argv); $i++) {
+            if ($argv[$i] === '--id' && isset($argv[$i + 1])) {
+                $idArg = $argv[$i + 1];
+                break;
+            }
+        }
+    }
+
+    $paths = resolveSpecPaths($project['targetRoot'], $specArg, $idArg);
+    if (count($paths) > 1) {
+        echo "api-unit-gen: " . count($paths) . " spec(s) to process\n";
+    }
+
+    $failed = 0;
+    foreach ($paths as $specPath) {
+        try {
+            $specData = SpecReader::read($specPath);
+            $manifestData = CodegenManifest::read($specData['featureDir']);
+
+            $ctx = UnitPlanner::buildUnitContext(
+                $specData['spec'],
+                $specData['specFile'],
+                $manifestData['manifest'],
+                $laravelRoot,
+                ['phase' => $options['phase']]
+            );
+            $plan = UnitPlanner::buildUnitPlan($ctx, $registry);
+
+            echo "api-unit-gen: module={$ctx['module']} entity={$ctx['entity']} profile={$ctx['profile']} phase={$ctx['phase']}\n";
+            echo "  target: {$laravelRoot}\n";
+            echo "  spec: {$specData['specFile']}\n";
+            echo '  registry: '.UnitRegistry::REGISTRY_REL."\n";
+            if ($options['dryRun']) {
+                echo "  mode: dry-run\n";
+            }
+            if ($options['force']) {
+                echo "  mode: force\n";
+            }
+
+            if ($plan['skippedPatterns'] !== []) {
+                echo "\nSkipped patterns:\n";
+                foreach ($plan['skippedPatterns'] as $item) {
+                    $artisan = !empty($item['artisan']) ? ' → php artisan '.$item['artisan'] : '';
+                    echo "  {$item['patternId']}: {$item['reason']}{$artisan}\n";
+                }
+            }
+
+            if ($plan['commands'] !== []) {
+                echo "\nArtisan commands:\n";
+                foreach ($plan['commands'] as $cmd) {
+                    echo "  php artisan {$cmd['artisan']}\n";
+                }
+            }
+
+            $commandResults = [];
+            if ($options['execute'] && $plan['commands'] !== []) {
+                $commands = $plan['commands'];
+                if ($options['force']) {
+                    $commands = array_map(
+                        static fn ($c) => array_merge($c, ['artisan' => $c['artisan'].' --force']),
+                        $commands
+                    );
+                }
+                foreach ($commands as $cmd) {
+                    $result = ArtisanRunner::run($cmd['artisan'], $laravelRoot, ['dryRun' => $options['dryRun']]);
+                    $commandResults[] = array_merge($cmd, $result);
+                    if ($result['code'] !== 0 && $options['execute'] && !$options['dryRun']) {
+                        throw new RuntimeException(
+                            "Command failed: {$cmd['artisan']}\n".($result['stderr'] ?: $result['stdout'])
+                        );
+                    }
+                }
+            }
+
+            $rendered = WriteFiles::renderFileOutputs($plan['files'], $ctx);
+            $writeResult = WriteFiles::writeOutputs($laravelRoot, $rendered, [
+                'dryRun' => $options['dryRun'],
+                'force' => $options['force'],
+            ]);
+            $written = $writeResult['written'];
+            $skipped = $writeResult['skipped'];
+
+            $unitManifest = [
+                'generatedAt' => gmdate('c'),
+                'specFile' => $specData['specFile'],
+                'phase' => $ctx['phase'],
+                'profile' => $ctx['profile'],
+                'module' => $ctx['module'],
+                'entity' => $ctx['entity'],
+                'feature' => $ctx['feature'],
+                'codegenManifest' => 'generated/codegen.manifest.json',
+                'unitRegistry' => UnitRegistry::REGISTRY_REL,
+                'commands' => array_map(
+                    static fn ($c) => [
+                        'pattern' => $c['patternId'],
+                        'artisan' => $c['artisan'],
+                        'shell' => 'php artisan '.$c['artisan'],
+                    ],
+                    $plan['commands']
+                ),
+                'files' => array_map(
+                    static fn ($f) => [
+                        'layer' => $f['layer'],
+                        'path' => $f['relativePath'],
+                        'pattern' => $f['patternId'],
+                        'reqIds' => $f['reqIds'],
+                    ],
+                    $plan['files']
+                ),
+                'written' => array_map(static fn ($w) => $w['relativePath'], $written),
+                'skipped' => array_map(
+                    static fn ($s) => ['path' => $s['relativePath'], 'reason' => $s['reason']],
+                    $skipped
+                ),
+                'skippedPatterns' => $plan['skippedPatterns'],
+                'needsUnit' => $plan['needsUnit'],
+                'mocks' => array_map(static fn ($m) => '#test-mock:'.$m, $ctx['unitTags']['mocks']),
+                'execution' => array_map(
+                    static fn ($r) => [
+                        'id' => $r['id'],
+                        'status' => ($r['code'] ?? 1) === 0 ? 'OK' : 'FAIL ('.($r['code'] ?? 1).')',
+                        'artisan' => $r['artisan'],
+                    ],
+                    $commandResults
+                ),
+            ];
+
+            $handoff = WriteFiles::renderUnitHandoffMarkdown(
+                $ctx,
+                $written,
+                $skipped,
+                $plan['needsUnit'],
+                $plan['commands'],
+                $plan['skippedPatterns']
+            );
+            $meta = WriteFiles::writeUnitMeta($specData['featureDir'], $unitManifest, $handoff, [
+                'dryRun' => $options['dryRun'],
+            ]);
+
+            foreach ($written as $w) {
+                $prefix = $options['dryRun'] ? '[dry]' : 'write';
+                echo "  {$prefix}: {$w['relativePath']}\n";
+            }
+            foreach ($skipped as $s) {
+                echo "  skip: {$s['relativePath']} ({$s['reason']})\n";
+            }
+            foreach ($plan['needsUnit'] as $item) {
+                echo "  needs-unit: {$item['tag']}\n";
+            }
+
+            if (!$options['dryRun'] && !empty($meta['manifestPath'])) {
+                echo "  manifest: {$meta['manifestPath']}\n";
+                echo "  handoff: {$meta['handoffPath']}\n";
+            }
+
+            if (count($paths) > 1) echo "\n";
+        } catch (Throwable $e) {
+            $failed++;
+            fwrite(STDERR, "api-unit-gen: FAIL $specPath: " . ($e->getMessage() ?: (string) $e) . "\n");
+        }
+    }
+    if ($failed > 0) exit(1);
+
+    echo "\napi-unit-gen complete — verify with php artisan test; needsUnit should be [] for implemented patterns\n";
+    exit(0);
+} catch (Throwable $error) {
+    fwrite(STDERR, ($error->getMessage() ?: (string) $error)."\n");
+    exit(1);
+}

package/adapters/laravel/php/bin/validate-registry.php

@@ -0,0 +1,61 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+$engineRoot = dirname(__DIR__);
+require_once $engineRoot.'/src/Autoload.php';
+
+use FlowGrid\Laravel\UnitGen\UnitRegistry;
+
+try {
+    $root = getenv('FLOWGRID_PROJECT_ROOT') ?: dirname($engineRoot);
+    $loaded = UnitRegistry::load($root);
+    $registry = $loaded['registry'];
+    $errors = [];
+    $warnings = [];
+
+    echo 'api-unit-test.registry v'.$registry['version']."\n";
+    echo '  path: '.UnitRegistry::REGISTRY_REL."\n";
+    echo '  patterns: '.count($registry['patterns'] ?? [])."\n";
+    echo '  commonBaselines: '.count($registry['commonBaselines']['app'] ?? [])."\n";
+
+    foreach ($registry['patterns'] ?? [] as $id => $pattern) {
+        if (empty($pattern['status'])) {
+            $warnings[] = "patterns.{$id}: missing status";
+        }
+        if (($pattern['status'] ?? null) === 'implemented' && empty($pattern['command']) && empty($pattern['template'])) {
+            $errors[] = "patterns.{$id}: implemented but no command or template";
+        }
+        if (!empty($pattern['fallbackTag']) && !str_starts_with((string) $pattern['fallbackTag'], '#needs-unit-test:')) {
+            $warnings[] = "patterns.{$id}: fallbackTag should start with #needs-unit-test:";
+        }
+    }
+
+    foreach ($registry['manualTopicMap'] ?? [] as $topic => $entry) {
+        $patternId = is_string($entry) ? $entry : ($entry['patternId'] ?? null);
+        if (!$patternId) {
+            $errors[] = "manualTopicMap.{$topic}: missing patternId";
+            continue;
+        }
+        if (empty($registry['patterns'][$patternId])) {
+            $errors[] = "manualTopicMap.{$topic} → unknown pattern [{$patternId}]";
+        }
+    }
+
+    foreach ($warnings as $warning) {
+        fwrite(STDERR, "  warn: {$warning}\n");
+    }
+    if ($errors !== []) {
+        foreach ($errors as $error) {
+            fwrite(STDERR, "  error: {$error}\n");
+        }
+        exit(1);
+    }
+
+    echo "  validate: OK\n";
+    exit(0);
+} catch (Throwable $error) {
+    fwrite(STDERR, ($error->getMessage() ?: (string) $error)."\n");
+    exit(1);
+}

package/adapters/laravel/php/composer.json

@@ -0,0 +1,16 @@
+{
+  "name": "flowgrid/laravel-unitgen",
+  "description": "FlowGrid Laravel unit-test generator (synced into src/.flowgrid/php)",
+  "type": "library",
+  "autoload": {
+    "psr-4": {
+      "FlowGrid\\Laravel\\UnitGen\\": "src/"
+    }
+  },
+  "require": {
+    "php": ">=8.2"
+  },
+  "suggest": {
+    "symfony/yaml": "Required at product require-dev to parse backend specs"
+  }
+}

package/adapters/laravel/php/src/ArtisanRunner.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace FlowGrid\Laravel\UnitGen;
+
+final class ArtisanRunner
+{
+    /**
+     * @param  array{dryRun?: bool}  $options
+     * @return array{code: int, stdout: string, stderr: string}
+     */
+    public static function run(string $artisanLine, string $laravelRoot, array $options = []): array
+    {
+        $line = preg_replace('/^php artisan\s+/', '', trim($artisanLine)) ?? trim($artisanLine);
+        if (!empty($options['dryRun'])) {
+            return ['code' => 0, 'stdout' => "[dry-run] php artisan {$line}", 'stderr' => ''];
+        }
+
+        $php = getenv('FLOWGRID_PHP') ?: 'php';
+        $args = self::splitCommand($line);
+        $command = array_merge([$php, 'artisan'], $args);
+
+        $descriptors = [
+            0 => ['pipe', 'r'],
+            1 => ['pipe', 'w'],
+            2 => ['pipe', 'w'],
+        ];
+        $proc = proc_open($command, $descriptors, $pipes, $laravelRoot, null);
+        if (!is_resource($proc)) {
+            return ['code' => 1, 'stdout' => '', 'stderr' => 'Failed to spawn artisan'];
+        }
+        fclose($pipes[0]);
+        $stdout = stream_get_contents($pipes[1]) ?: '';
+        $stderr = stream_get_contents($pipes[2]) ?: '';
+        fclose($pipes[1]);
+        fclose($pipes[2]);
+        $code = proc_close($proc);
+
+        return ['code' => $code, 'stdout' => $stdout, 'stderr' => $stderr];
+    }
+
+    /** @return list<string> */
+    private static function splitCommand(string $line): array
+    {
+        $args = [];
+        if (preg_match_all('/"((?:\\\\.|[^"])*)"|\'((?:\\\\.|[^\'])*)\'|([^\s]+)/', $line, $matches, PREG_SET_ORDER)) {
+            foreach ($matches as $match) {
+                $raw = $match[1] !== '' ? $match[1] : ($match[2] !== '' ? $match[2] : $match[3]);
+                $args[] = preg_replace('/\\\\(["\'])/', '$1', $raw) ?? $raw;
+            }
+        }
+
+        return $args;
+    }
+}

package/adapters/laravel/php/src/Autoload.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+spl_autoload_register(static function (string $class): void {
+    $prefix = 'FlowGrid\\Laravel\\UnitGen\\';
+    if (!str_starts_with($class, $prefix)) {
+        return;
+    }
+    $relative = str_replace('\\', '/', substr($class, strlen($prefix)));
+    $file = dirname(__DIR__).'/src/'.$relative.'.php';
+    if (is_file($file)) {
+        require_once $file;
+    }
+});

package/adapters/laravel/php/src/CodegenManifest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace FlowGrid\Laravel\UnitGen;
+
+final class CodegenManifest
+{
+    /**
+     * @return array{manifest: array<string, mixed>, manifestPath: string}
+     */
+    public static function read(string $featureDir): array
+    {
+        $manifestPath = $featureDir.DIRECTORY_SEPARATOR.'generated'.DIRECTORY_SEPARATOR.'codegen.manifest.json';
+        if (!is_file($manifestPath)) {
+            throw new \RuntimeException(
+                "Missing {$manifestPath} — run flowgrid api-gen --spec ... first"
+            );
+        }
+
+        $manifest = json_decode((string) file_get_contents($manifestPath), true, 512, JSON_THROW_ON_ERROR);
+        if (!is_array($manifest) || empty($manifest['module']) || empty($manifest['entity'])) {
+            throw new \RuntimeException("Invalid codegen manifest at {$manifestPath}");
+        }
+
+        return ['manifest' => $manifest, 'manifestPath' => $manifestPath];
+    }
+}

package/adapters/laravel/php/src/ParseTags.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace FlowGrid\Laravel\UnitGen;
+
+final class ParseTags
+{
+    private const GEN_TEST = '#gen:test-';
+    private const NEEDS_UNIT = '#needs-unit-test:';
+    private const SKIP_UNIT = '#skip-unit-test:';
+    private const TEST_MOCK = '#test-mock:';
+
+    /**
+     * @param  list<string>  $tags
+     * @return array{gen: array<string, true>, skip: array<string, true>, needs: list<string>, mocks: list<string>, raw: list<string>}
+     */
+    public static function parse(array $tags = []): array
+    {
+        $parsed = [
+            'gen' => [],
+            'skip' => [],
+            'needs' => [],
+            'mocks' => [],
+            'raw' => $tags,
+        ];
+
+        foreach ($tags as $tag) {
+            $text = trim((string) $tag);
+            if (str_starts_with($text, self::GEN_TEST)) {
+                $parsed['gen'][trim(substr($text, strlen(self::GEN_TEST)))] = true;
+            } elseif (str_starts_with($text, self::SKIP_UNIT)) {
+                $parsed['skip'][strtolower(trim(substr($text, strlen(self::SKIP_UNIT))))] = true;
+            } elseif (str_starts_with($text, self::NEEDS_UNIT)) {
+                $parsed['needs'][] = $text;
+            } elseif (str_starts_with($text, self::TEST_MOCK)) {
+                $parsed['mocks'][] = trim(substr($text, strlen(self::TEST_MOCK)));
+            }
+        }
+
+        return $parsed;
+    }
+
+    /** @param array{skip: array<string, true>} $unitTags */
+    public static function isLayerSkipped(array $unitTags, string $layer): bool
+    {
+        $key = strtolower($layer);
+
+        return isset($unitTags['skip'][$key]) || isset($unitTags['skip']['all']);
+    }
+
+    /** @param array{gen: array<string, true>} $unitTags */
+    public static function hasExplicitGenTag(array $unitTags, string $genKey): bool
+    {
+        return isset($unitTags['gen'][$genKey]);
+    }
+
+    public static function patternGenKey(string $patternId): string
+    {
+        return str_replace('.', '-', $patternId);
+    }
+}