docs: document cli-fp-gen and add Windows codegen verification

Author: ikelaiah

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `cli-fp-gen` project scaffolding workflow is now documented from the main README, including a direct link to the dedicated generator guide.
+
+### Testing
+
+- Added a Windows PowerShell verification path for `cli-fp-gen` in `tests/codegen/run_all_tests.ps1`.
+- Code generator documentation now includes both the Bash test scripts and the PowerShell verification command.
+
 ## [1.1.6] - 2026-02-21
 
 ### Added

README.md

@@ -17,6 +17,7 @@ Combines Free Pascal's speed and reliability with professional-grade features. T
   - [📑 Table of Contents](#-table-of-contents)
   - [✨ Features](#-features)
   - [🚀 Quick Start](#-quick-start)
+  - [🧩 Project Generator](#-project-generator)
   - [🎯 Parameter Types and Validation](#-parameter-types-and-validation)
     - [Basic Types](#basic-types)
     - [Boolean and Flags](#boolean-and-flags)
@@ -180,6 +181,21 @@ Options:
 A runtime-only Lazarus package is provided in `packages/lazarus/cli_fp.lpk`.
 To use it, open the `.lpk` file in Lazarus, click “Compile,” then click “Add” to add it to your project’s required packages.
 
+## 🧩 Project Generator
+
+This repository also includes `cli-fp-gen`, a scaffold generator for new `cli-fp` applications.
+
+Typical workflow:
+
+```powershell
+fpc -Futools\cli-fp-gen\src .\tools\cli-fp-gen\cli_fp_gen.lpr
+.\tools\cli-fp-gen\cli_fp_gen.exe init .\build-temp\myapp --name myapp
+.\tools\cli-fp-gen\cli_fp_gen.exe add command greet --project .\build-temp\myapp --description "Say hello"
+.\tools\cli-fp-gen\cli_fp_gen.exe generate --project .\build-temp\myapp
+```
+
+Full generator documentation, project layout details, and `clifp.json` reference are in [docs/codegen.md](docs/codegen.md).
+
 ### Progress Indicator Captions (v1.1.6)
 
 Progress indicators now support inline status text via:
@@ -322,6 +338,7 @@ Each parameter type has built-in validation:
 - [User Manual](docs/user-manual.md): Complete guide for using the framework, *including a cheat sheet*
 - [API Reference](docs/api-reference.md): Detailed API reference for the framework
 - [Technical Documentation](docs/technical-docs.md): Architecture and implementation details
+- [Code Generator](docs/codegen.md): `cli-fp-gen` usage, generated layout, and verification notes
 - [Examples](examples/): Working example applications
 - [Changelog](CHANGELOG.md): Version history and updates
 

docs/codegen.md

@@ -101,6 +101,26 @@ fpc "-Fu..\..\src" "-Fu.\src" "-Fu.\src\generated" "-Fu.\src\commands" .\src\MyA
 
 Adjust the `..\..\src` path to point at the `cli-fp` framework `src/` directory.
 
+## Verification
+
+### Linux/macOS (Bash)
+
+The repository includes focused codegen checks under `tests/codegen/`:
+
+- `run_golden_test.sh`
+- `run_compile_smoke.sh`
+- `run_ops_test.sh`
+
+### Windows (PowerShell)
+
+Use the Windows-native verification script from the repository root:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\tests\codegen\run_all_tests.ps1
+```
+
+This script compiles `cli-fp-gen`, verifies golden output, compiles a generated app, and checks `init` / `generate` / `add command` / `remove command` behavior plus the path validation guard.
+
 ## Notes
 
 - Commands are defined in a flat list with `parent` paths (slash-delimited, e.g. `repo/remote`).

tests/codegen/run_all_tests.ps1

@@ -0,0 +1,142 @@
+$ErrorActionPreference = 'Stop'
+
+function New-TempDir {
+  $path = Join-Path ([System.IO.Path]::GetTempPath()) ("cli-fp-codegen-" + [System.Guid]::NewGuid().ToString("N"))
+  New-Item -ItemType Directory -Path $path | Out-Null
+  return $path
+}
+
+function Normalize-Content([string]$Path) {
+  return (Get-Content -Raw $Path) -replace "`r`n", "`n"
+}
+
+function Assert-True([bool]$Condition, [string]$Message) {
+  if (-not $Condition) {
+    throw $Message
+  }
+}
+
+function Write-JsonFile([string]$Path, $Object) {
+  $Object | ConvertTo-Json -Depth 20 | Set-Content -Path $Path
+}
+
+$RootDir = (Resolve-Path (Join-Path $PSScriptRoot "..\..")).Path
+$GenSrc = Join-Path $RootDir "tools\cli-fp-gen\cli_fp_gen.lpr"
+$GenExe = Join-Path $RootDir "tools\cli-fp-gen\cli_fp_gen.exe"
+$FixtureDir = Join-Path $RootDir "tests\codegen-fixtures\golden-basic"
+$GoldenDir = Join-Path $RootDir "tests\codegen-golden\golden-basic"
+$TmpDir = New-TempDir
+
+try {
+  fpc "-Fu$RootDir\tools\cli-fp-gen\src" $GenSrc | Out-Null
+
+  # Golden output check
+  $GoldenProject = Join-Path $TmpDir "golden"
+  New-Item -ItemType Directory -Force -Path $GoldenProject | Out-Null
+  Copy-Item -Force (Join-Path $FixtureDir "clifp.json") (Join-Path $GoldenProject "clifp.json")
+  & $GenExe generate --project $GoldenProject | Out-Null
+
+  $GoldenFiles = @(
+    "src\GoldenDemo.lpr",
+    "src\generated\GoldenDemo_CommandRegistry_Generated.pas",
+    "src\generated\.clifp-manifest.json",
+    "src\commands\GoldenDemo_Command_Greet.pas",
+    "src\commands\GoldenDemo_Command_Repo.pas",
+    "src\commands\GoldenDemo_Command_RepoClone.pas",
+    "src\commands\GoldenDemo_Command_Types.pas"
+  )
+
+  foreach ($RelativePath in $GoldenFiles) {
+    $Expected = Normalize-Content (Join-Path $GoldenDir $RelativePath)
+    $Actual = Normalize-Content (Join-Path $GoldenProject $RelativePath)
+    Assert-True ($Expected -eq $Actual) "Golden mismatch: $RelativePath"
+  }
+
+  Write-Host "Golden test passed"
+
+  # Compile smoke check
+  fpc `
+    "-Fu$RootDir\src" `
+    "-Fu$GoldenProject\src" `
+    "-Fu$GoldenProject\src\generated" `
+    "-Fu$GoldenProject\src\commands" `
+    (Join-Path $GoldenProject "src\GoldenDemo.lpr") | Out-Null
+
+  & (Join-Path $GoldenProject "src\GoldenDemo.exe") --help | Out-Null
+  & (Join-Path $GoldenProject "src\GoldenDemo.exe") repo | Out-Null
+
+  Write-Host "Compile smoke test passed"
+
+  # Operations and path guard check
+  $DemoProject = Join-Path $TmpDir "demo"
+  & $GenExe init $DemoProject --force | Out-Null
+
+  $DryRunOutput = (& $GenExe add command repo --project $DemoProject --description "Repo tools" --dry-run) | Out-String
+  Assert-True ($DryRunOutput -match "Demo_Command_Repo\.pas") "Dry-run add did not preview the new command stub"
+  Assert-True (-not ((Get-Content -Raw (Join-Path $DemoProject "clifp.json")) -match '"name"\s*:\s*"repo"')) "Dry-run add modified clifp.json"
+  Assert-True (-not (Test-Path (Join-Path $DemoProject "src\commands\Demo_Command_Repo.pas"))) "Dry-run add created a command stub"
+
+  & $GenExe add command repo --project $DemoProject --description "Repo tools" | Out-Null
+  & $GenExe add command clone --parent repo --project $DemoProject --description "Clone repo" | Out-Null
+
+  $null = (& $GenExe remove command repo --project $DemoProject 2>&1 | Out-String)
+  Assert-True ($LASTEXITCODE -ne 0) "Expected remove command without --cascade to fail"
+
+  & $GenExe remove command repo --cascade --project $DemoProject | Out-Null
+  Assert-True (-not ((Get-Content -Raw (Join-Path $DemoProject "clifp.json")) -match '"name"\s*:\s*"repo"')) "repo command still present after cascade remove"
+
+  $DemoSpec = Get-Content -Raw (Join-Path $DemoProject "clifp.json") | ConvertFrom-Json
+  $OldProgramPath = Join-Path $DemoProject $DemoSpec.app.programFile
+  Assert-True (Test-Path $OldProgramPath) "Expected original program file to exist after init"
+
+  $DemoSpec.app.programFile = "src/DemoRenamed.lpr"
+  Write-JsonFile (Join-Path $DemoProject "clifp.json") $DemoSpec
+  & $GenExe generate --project $DemoProject | Out-Null
+
+  Assert-True (Test-Path (Join-Path $DemoProject "src\DemoRenamed.lpr")) "Renamed program file was not generated"
+  Assert-True (-not (Test-Path $OldProgramPath)) "Old generated program file was not removed by manifest cleanup"
+  Assert-True ((Get-Content -Raw (Join-Path $DemoProject "src\generated\.clifp-manifest.json")) -match "src/DemoRenamed\.lpr") "Manifest did not track renamed program file"
+
+  $DescriptionsProject = Join-Path $TmpDir "descriptions"
+  & $GenExe init $DescriptionsProject --force | Out-Null
+  & $GenExe add command repo --project $DescriptionsProject --description "Owner's tools" | Out-Null
+
+  $DescriptionsSpec = Get-Content -Raw (Join-Path $DescriptionsProject "clifp.json") | ConvertFrom-Json
+  foreach ($Command in $DescriptionsSpec.commands) {
+    if ($Command.name -eq "repo") {
+      $Command.description = "Repo team's tools"
+    }
+  }
+  Write-JsonFile (Join-Path $DescriptionsProject "clifp.json") $DescriptionsSpec
+  & $GenExe generate --project $DescriptionsProject | Out-Null
+
+  $ProgramPath = Join-Path $DescriptionsProject $DescriptionsSpec.app.programFile
+  fpc `
+    "-Fu$RootDir\src" `
+    "-Fu$DescriptionsProject\src" `
+    "-Fu$DescriptionsProject\src\generated" `
+    "-Fu$DescriptionsProject\src\commands" `
+    $ProgramPath | Out-Null
+
+  $ExePath = [System.IO.Path]::ChangeExtension($ProgramPath, ".exe")
+  $HelpOutput = (& $ExePath repo --help) | Out-String
+  Assert-True ($HelpOutput -match "Repo team's tools") "Regenerated command description did not update runtime help"
+
+  $PathGuardProject = Join-Path $TmpDir "path-guard"
+  & $GenExe init $PathGuardProject --force | Out-Null
+
+  $PathGuardSpec = Get-Content -Raw (Join-Path $PathGuardProject "clifp.json") | ConvertFrom-Json
+  $PathGuardSpec.app.programFile = "../outside/Escape.lpr"
+  Write-JsonFile (Join-Path $PathGuardProject "clifp.json") $PathGuardSpec
+
+  $null = (& $GenExe generate --project $PathGuardProject 2>&1 | Out-String)
+  Assert-True ($LASTEXITCODE -ne 0) "Expected invalid programFile path to fail validation"
+  Assert-True (-not (Test-Path (Join-Path $TmpDir "outside\Escape.lpr"))) "Generator wrote a program file outside the project directory"
+
+  Write-Host "Ops test passed"
+}
+finally {
+  if (Test-Path $TmpDir) {
+    Remove-Item -Recurse -Force $TmpDir
+  }
+}