cli-fp v1.3.2

Release Date: 2026-07-30

Overview

Version 1.3.2 is a contract-hardening patch release. It removes a hidden
runtime dependency on TBaseCommand, formally deprecates the non-functional
custom-completion callback registration methods, and establishes the
maintenance roadmap for the next releases.

Existing applications based on TBaseCommand remain source-compatible.

ICommand Contract Fix

Earlier versions accepted commands through the ICommand interface but cast
the selected command to TBaseCommand before execution. A valid independent
implementation of ICommand could therefore register successfully and then
fail with an invalid type cast at runtime.

Version 1.3.2 removes that downcast. Parameter handoff now uses the optional
ICommandParameterReceiver capability:

• TBaseCommand implements ICommandParameterReceiver, preserving existing
  parameter lookup behaviour.
• Commands that implement only ICommand can execute without inheriting from
  TBaseCommand.
• Commands that need framework-managed parameter lookup can derive from
  TBaseCommand or implement the optional receiver contract.

The regression suite now includes an interface-only command and verifies its
execution and exit code.

Deprecated Completion Callback APIs

The following concrete TCLIApplication methods are now marked deprecated:

• RegisterFlagValueCompletion()
• RegisterPositionalCompletion()

These methods have always been non-functional stubs. They remain as no-ops in
the 1.x line for source compatibility and are planned for removal in v2.0.0.

Built-in completion is unchanged. Registered commands, subcommands, flags,
Boolean values, and enum values continue to be completed from command
metadata.

Maintenance Roadmap

The new project roadmap records the intended sequence:

• v1.3.2: correct current contracts;
• v1.4.0: add a simple callback API and typed argument access;
• v1.5.0: split help and completion out of TCLIApplication; and
• v2.0.0: adopt an explicit execution context and retire legacy shared-state
  plumbing.

Convenience APIs are expected to delegate to one underlying implementation so
that improved ergonomics do not create parallel parsing or validation paths.

Verification

• Framework suite: 39 tests, 0 errors, 0 failures.
• Added regression coverage for an ICommand implementation that does not
  inherit from TBaseCommand.
• Verified that use of a deprecated callback registration method produces the
  intended FPC compiler warning.
• Full Windows generator suite passed:
  • generator unit tests;
  • golden-output test;
  • generated-project compile smoke test; and
  • generator operations test.
• All seven example applications compiled successfully.
• Lazarus runtime package compiled with version metadata at 1.3.2.
• Local Markdown targets resolve and fenced code blocks are balanced across 39
  Markdown files.
• FPC version: 3.2.2.

Compatibility

No migration is required for applications using TBaseCommand,
CreateCLIApplication, existing command registration, schema-version-1
clifp.json files, or generated projects.

Applications that call either deprecated custom-completion registration method
may receive a compiler warning. Removing those calls does not change runtime
behaviour because the methods did not register callbacks.

Versioning

• The README release badge now targets 1.3.2.
• The Lazarus package metadata now targets 1.3.2.

Full Changelog: v1.3.1...v1.3.2

cli-fp v1.3.1

Release Date: July 28, 2026

Overview

Version 1.3.1 is a documentation-focused patch release that makes cli-fp
easier to learn, evaluate, and adopt. It adds a verified path from installing
Free Pascal to running a generated native CLI, gives newcomers a concise
Object Pascal orientation, and reorganizes the documentation around developer
goals.

The release also corrects dependency, compiler-command, platform-support,
console, and API descriptions found during a source-backed documentation
audit.

There are no framework runtime, public API, generator-schema, or generated
output changes in this release.

A Faster First Success

The README now guides a new developer through:

1. installing and verifying Free Pascal;
2. compiling cli-fp-gen;
3. generating an application;
4. compiling the generated Pascal units into a native executable;
5. implementing the generated greet command; and
6. running the result as Myapp greet --name Ada.

The documented command implementation and its Hello, Ada! result were
compile- and runtime-verified with FPC 3.2.2.

Free Pascal Orientation

New sections explain the project’s essential Pascal conventions, including:

• .lpr program entry points and .pas units;
• uses clauses and FPC -Fu unit-search paths;
• {$mode objfpc};
• TBaseCommand inheritance and overridden Execute methods; and
• returning application exit codes through Halt(App.Execute).

The README also highlights how the project uses classes, interfaces, generics,
exceptions, deterministic cleanup, conditional compilation, FPCUnit, native
binaries, and platform-aware console code.

Documentation Navigation

A new docs/README.md documentation home provides:

• goal-based routes into the user, generator, API, and maintainer guides;
• an examples map showing which application demonstrates each feature;
• a repository-layout overview;
• guidance for developers new to Free Pascal; and
• a clear distinction between current documentation and historical release or
  test records.

The user manual, generator guide, API reference, technical documentation, and
completion guides now link back into this navigation structure.

Manual and Generator Improvements

• Replaced the user manual’s duplicated opening reference material with
  prerequisites and focused learning paths.
• Retained a single API cheat sheet for experienced users.
• Clarified root-command selection, help scopes, parameter conversion, debug
  access, and console behaviour.
• Added verified cross-platform generator and generated-application commands.
• Explained how clifp.json, the .lpr entry point, generated registry units,
  and user-owned command units become one native executable.
• Removed the dated “Phase 1” framing from the current generator guide.

Accuracy Corrections

• Described parameter types as metadata used for validation and help while
  making clear that command code retrieves values as strings.
• Documented the standard FCL JSON units required by cli-fp-gen.
• Added required PowerShell quoting around FPC -Fu arguments.
• Separated CI-tested Windows/Linux environments from expected but currently
  untested Unix targets.
• Corrected Windows console and ANSI cursor-control descriptions.
• Expanded selected public API declarations and identified intentionally
  omitted testing and disabled callback surfaces.
• Preserved the distinction between general help, command-level help,
  complete help, version output, and completion-script generation.

Verification

• Framework suite: 38 tests, 0 failures.
• Full Windows generator suite passed.
• The documented generated project compiled and ran successfully.
• RootCommandDemo compiled and completed its root and named actions.
• The Lazarus runtime package compiled with version metadata at 1.3.1.
• Local links and heading anchors across 30 Markdown files resolve.
• Fenced code blocks across 30 Markdown files are balanced.
• git diff --check passed.

Compatibility

No migration is required. Existing applications, public API usage,
schema-version-1 clifp.json files, and generated projects continue to work as
they did in v1.3.0.

Versioning

• The README release badge now targets 1.3.1.
• The Lazarus package metadata now targets 1.3.1.

Full Changelog: v1.3.0...v1.3.1

cli-fp v1.3.0 — Superseded by v1.3.1

Release Date: July 28, 2026

Superseded by v1.3.1

v1.3.0 introduced optional root commands, but its documentation contains
known inaccuracies. Please use v1.3.1, which includes corrected and
substantially improved documentation.

Overview

Version 1.3.0 introduces optional root commands, allowing focused utilities
to run directly as app [options] without giving up named commands or nested
subcommands. It also adds root-command support to cli-fp-gen and completes a
documentation-correction pass for the public API, build commands, and shell
completion guidance.

This is a backward-compatible minor release. Existing applications and
schema-v1 generator specifications require no migration.

Optional Root Commands

Applications can opt into a root command that runs without requiring a named
command.

myapp
myapp --name Gus

Named commands and nested subcommands remain available:

myapp about
myapp repo clone

Existing applications using the two-argument factory retain their
command-first behavior and continue to show general help when invoked without
a command.

Framework API

The new overload accepts any existing ICommand implementation:

RootCommand := TGreetCommand.Create('', 'Greet someone');
RootCommand.AddStringParameter('-n', '--name', 'Name to greet',
  False, 'World');

App := CreateCLIApplication('MyApp', '1.0.0', RootCommand);
Halt(App.Execute);

Root execution shares the same parsing, typed validation, defaults, help, and
exception handling as named commands. Sole help/version requests and
first-argument completion-script requests retain precedence over root
selection.

Root parameters are local to the root command. Persistent/inherited flags and
positional arguments are not introduced in this release.

Help and Completion

• General help includes the root description and parameters.
• Complete help includes a dedicated root-options section.
• Bash and PowerShell completion include root parameter flags.
• Built-in boolean and enum value completion works at the root level.
• Root-level completion remains commands-first until the user starts an
  option with -.

Generator Support

Schema version 1 now accepts an optional rootCommand object. The following
shows that member in isolation; a complete specification still requires
schemaVersion, app, and commands:

{
  "rootCommand": {
    "description": "Run the default action",
    "parameters": []
  }
}

When configured, cli-fp-gen:

• creates a user-owned <App>_RootCommand.pas stub;
• generates root parameter registration;
• calls the three-argument application factory; and
• retains any root stub if rootCommand is later removed from the spec.

Existing specifications without rootCommand generate as before.

Documentation

The documentation received a release-wide accuracy and onboarding pass:

• Reworked the README to help new developers choose between root commands,
  named commands, and combined applications.
• Corrected public API signatures and copy/paste Pascal examples, with key
  examples verified by compilation.
• Updated root-command and code-generator instructions, including
  case-sensitive Linux build commands.
• Aligned Bash and PowerShell completion guides with current behavior.
• Clarified date-time parsing, Boolean defaults, password handling, and current
  custom-completion limitations.
• Repaired local documentation links and labelled dated test reports as
  historical snapshots.

Examples and Verification

• Added examples/RootCommandDemo.
• Corrected copy/paste API examples, generated-program filename casing, and
  shell-completion compatibility notes.
• Removed the generated password-help claim that values are masked; password
  values are raw strings and must be handled as sensitive by the application.
• Expanded the framework suite from 30 to 38 tests.
• Added generator parsing, round-trip, golden-output, runtime, and compile
  coverage for root commands.
• Verified the full framework and generator suites on Windows with FPC 3.2.2.
• GitHub Actions passed on Linux and Windows for both push and pull-request
  events.

Versioning

• The Lazarus package version is now 1.3.0.
• The README version badge is now 1.3.0.

This work addresses
[SUGGESTION] Have a root command #14.

Full Changelog: v1.2.0...v1.3.0

cli-fp v1.2.0

Release Date: July 27, 2026

Overview

Version 1.2.0 introduces cli-fp-gen, a standalone project and command
scaffold generator for cli-fp. It turns a versioned clifp.json
specification into a compilable Free Pascal application while keeping generated
infrastructure separate from user-owned command implementations.

This is a backward-compatible minor release. Existing cli-fp applications do
not require migration.

New: cli-fp-gen

The generator supports the complete initial project workflow:

cli-fp-gen init <target-dir> [--name <app-name>] [--version <x.y.z>] [--dry-run] [--force]
cli-fp-gen generate [--project <dir-or-spec-file>] [--dry-run] [--force]
cli-fp-gen add command <name> [--parent <cmd/path>] [--description <text>] [--project <dir-or-spec-file>] [--dry-run] [--force]
cli-fp-gen remove command <cmd/path> [--cascade] [--project <dir-or-spec-file>] [--dry-run] [--force]

Generated project structure

• A Pascal program entry point under src/
• A generated command registry under src/generated/
• User-owned command stubs under src/commands/
• A generated-file manifest for stale-file cleanup
• A versioned clifp.json project specification as the source of truth

Supported parameter kinds

Generated command registration supports:

• String, integer, float, flag, and explicit boolean parameters
• Path, enum, date/time, array, password, and URL parameters
• Required values, defaults, descriptions, short flags, and long flags

File ownership

Generated entry points and registry units are refreshed by generate. Command
stubs are created once and preserved on subsequent runs unless --force is
explicitly supplied.

Safety and correctness

The generator includes safeguards for:

• Existing project specifications during init
• Project-relative generated program paths
• Manifest cleanup outside the project directory
• Case-sensitive path handling on Linux and other case-sensitive filesystems
• Manifest cleanup through Unix symbolic links and Windows reparse points,
  including directory junctions
• Exception-safe cleanup of partially parsed commands and parameters when
  clifp.json is malformed
• Invalid command tokens and missing parents
• Duplicate command paths and generated Pascal identifier collisions
• Reserved Pascal words used as application names
• Safe Pascal string escaping in generated source

--dry-run previews file operations without modifying the project.

Framework fix

Boolean parameter lookups now report a configured default as an available value,
matching the documented GetParameterValue contract and the behavior of other
parameter kinds.

Automated testing

GitHub Actions now verifies the framework and generator on Linux and Windows.
The automated suite includes:

• 30 framework unit tests
• Focused generator naming, validation, parsing-error, and ownership tests
• Golden-output comparisons
• Generator lifecycle and file-ownership checks
• Program and manifest path-safety checks, including Unix symlink and Windows
  junction escape attempts
• Compilation and execution of a generated application
• Lazarus package compilation
• Compilation of all six shipped example applications

Local test runners are available for Bash and PowerShell.

Build and use the generator

Compile from the repository root:

fpc -Futools/cli-fp-gen/src tools/cli-fp-gen/cli_fp_gen.lpr

Then create a project:

tools/cli-fp-gen/cli_fp_gen init ./my-app --name my-app

On Windows, use cli_fp_gen.exe.

See codegen.md for the complete specification and
workflow reference.

Upgrade notes

• Existing applications remain source compatible.
• The Lazarus package version is now 1.2.0.
• The generator is distributed as source and must be compiled before use.
• No clifp.json migration is required; schema version 1 is the current format.

License

This project is licensed under the MIT License. See LICENSE.

---

Full Changelog: v1.1.6...v1.2.0