diff --git a/.agnostic-ai/AGNOSTIC_AI.md b/.agnostic-ai/AGNOSTIC_AI.md index 0f0e2e9..7ef55ff 100644 --- a/.agnostic-ai/AGNOSTIC_AI.md +++ b/.agnostic-ai/AGNOSTIC_AI.md @@ -4,6 +4,24 @@ This file is regenerated by [agnostic-ai](https://github.com/chemaclass/agnostic-ai). Every supported AI tool reads a copy of this body from its native entry-point (CLAUDE.md, AGENTS.md, GEMINI.md, CONVENTIONS.md, ...) so a single source of truth drives every target. +## Project + +A Phel CLI skeleton (PHP 8.5, phel-lang `^0.54`). `src/core/` is pure logic, `src/commands/` is the input and output boundary, and `src/app.phel` lists the commands. Read `docs/architecture.md` before adding code and `CONTRIBUTING.md` before opening a PR. + +## Commands + +- `composer ci`: the full gate (format check, lint, tests, mutation, build, export). Run it once before pushing. +- `composer check`: the fast gate used by the pre-commit hook. +- `composer dev -- greet alice --loud`: run from sources. Put `--` before flags. +- `composer mutate`: mutation-test `src/core/`; it fails below 90%. +- `make new-command NAME=foo`: scaffold a command, its tests, and its registration in `src/app.phel`. + +## Rules of the codebase + +- Tests require `cli-skeleton.app`, never `cli-skeleton.main`. +- Parse integers with `parse-int` in `core/adder.phel`, not `parse-long`, which clamps overflow. +- Commit subjects are conventional (`fix:`, `feat:`, `ref:`, `docs:`, `ci:`, `chore:`). + ## Where the specs live - **Agents**: `.agnostic-ai/agents/` diff --git a/.agnostic-ai/rules/io-boundaries.md b/.agnostic-ai/rules/io-boundaries.md index e48aee0..b7f3b30 100644 --- a/.agnostic-ai/rules/io-boundaries.md +++ b/.agnostic-ai/rules/io-boundaries.md @@ -5,18 +5,18 @@ globs: src/**,tests/**,*.phel # IO Boundaries -Dependency direction: `commands/` → `core/`. Never the reverse. +Dependency direction: `commands/` requires `core/`. Never the reverse. Full rationale: [docs/architecture.md](../../docs/architecture.md). ## `src/core/` -**Pure logic.** Same input → same output, no observable effect. +**Pure logic.** Same input gives the same output, with no observable effect. - Accepts and returns plain data (maps, vectors, structs). - May NOT: print, prompt, read the clock, `rand`, mutate global atoms, `php/exit`, hit the filesystem, sleep. - MAY: do math, build new data, throw on invalid input. -- Test target: deterministic 1:1 unit tests in `tests/core/` — no CLI harness. +- Test target: deterministic unit tests in `tests/core/`, with no CLI harness. ## `src/commands/` @@ -24,18 +24,18 @@ Full rationale: [docs/architecture.md](../../docs/architecture.md). - Read args/opts via `cli/arg`, `cli/opt`; prompt via `cli/ask`. - Print via `cli/success`, `cli/warning`, `cli/error`; return an exit code. -- Keep handlers thin: parse input → call a `core/` fn → emit the result. +- Keep handlers thin: parse input, call a `core/` fn, emit the result. - Test target: handler smoke tests in `tests/commands/` driving the real dispatcher with `cli/argv` + `cli/buffered-output`. ## Smell test - A `core/` fn that prints, prompts, reads `php/microtime`, or calls - `php/rand` → move the effect into the command, pass the value in instead. -- A command doing real computation inline → extract it into `core/` and + `php/rand`: move the effect into the command and pass the value in. +- A command doing real computation inline: extract it into `core/` and unit-test it there. ## Scaling -When commands stop being thin, split the boundary into `core/ → glue/ → io/` -(pure logic → pure wiring → effects). Same one-way rule, finer grained. +When commands stop being thin, split the boundary into `core/`, `glue/`, and `io/` +(pure logic, pure wiring, effects). Same one-way rule, finer grained. diff --git a/.agnostic-ai/rules/phel.md b/.agnostic-ai/rules/phel.md index 700fb02..431c3fd 100644 --- a/.agnostic-ai/rules/phel.md +++ b/.agnostic-ai/rules/phel.md @@ -29,7 +29,7 @@ Skip it on private `defn-` unless the behavior is subtle. - `for` builds sequences, `doseq` does side effects. - CLI args via `(cli/argv *argv*)`, not raw `php/$argv`. `*argv*` is the core global holding user args (excludes the program name). -- `*build-mode*` guard around top-level side effects in `main.phel` — without +- `*build-mode*` guard around top-level side effects in `main.phel`. Without it `composer build` would execute the app. ## Exporting to PHP diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 761a35b..f005f58 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -5,7 +5,7 @@ body: - type: markdown attributes: value: | - Thanks for filing! For bugs in **phel-lang itself** (compiler, runtime, + For bugs in **phel-lang itself** (compiler, runtime, CLI commands like `phel lint` / `phel doctor`), please file at https://github.com/phel-lang/phel-lang/issues instead. This tracker is for the cli-skeleton template. @@ -14,7 +14,7 @@ body: attributes: label: Phel version description: Output of `vendor/bin/phel --version` - placeholder: v0.39.0 + placeholder: v0.54.0 validations: required: true - type: input diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 96a2bad..3b96669 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,7 +1,15 @@ -## 📚 Description +## Description -Replace this text with a short description of your feature/bugfix. +What does this change, and why? -## 🔖 Changes +## Changes -- List individual changes in more detail +- + +## Verification + +How did you check it? Name the command and the result for each acceptance criterion. + +- [ ] `composer ci` passes + +Closes # diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..60946bc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,53 @@ +# Contributing + +Thanks for helping. This repo is a template, so a change should keep it small and easy to read. + +## Set up + +```bash +git clone https://github.com/phel-lang/cli-skeleton.git +cd cli-skeleton +composer install +``` + +You need PHP 8.5 or newer and Composer. `composer install` also points Git at `.githooks/`, so the pre-commit hook runs the fast gate. + +## Before you push + +```bash +composer ci +``` + +It runs the format check, the linter, the tests, mutation testing on `core/`, the build, and the export. CI runs the same steps and then runs the built binary and the PHP example. + +For a quick loop while you work, use `composer check` (format check, lint, tests) or `composer watch`. + +## Where code goes + +- `src/core/`: pure logic. No printing, prompting, clock, randomness, or exit codes. +- `src/commands/`: reads arguments, calls `core/`, prints, returns an exit code. +- `src/app.phel`: the list of commands. A command missing here fails `tests/app-test.phel`. + +Read [docs/architecture.md](docs/architecture.md) before adding a command and [docs/conventions.md](docs/conventions.md) for naming and gotchas. `make new-command NAME=foo` creates the files and registers the command. + +## Tests + +- Test `core/` functions with plain data in and out. Do not use the CLI harness there. +- Give each command a smoke test through the real dispatcher. +- Fix a bug by writing the failing test first. + +## Commits and pull requests + +- Use conventional commit subjects that say what changed: `fix: reject non-integer input in add`. Types in use: `feat`, `fix`, `ref`, `docs`, `ci`, `build`, `chore`. +- Open one pull request per issue and link it with `Closes #123`. +- State how you checked each acceptance criterion. The PR template has a section for it. +- Keep unrelated cleanups out. Open a new issue for them. +- Do not rewrite history on a branch that is already pushed. + +## Reporting bugs + +Open an issue with your Phel and PHP versions and the exact commands that fail. Bugs in the compiler or in `phel` commands such as `lint` and `format` belong in [phel-lang/phel-lang](https://github.com/phel-lang/phel-lang/issues). + +## AI tool config + +Rules for AI coding tools are specs under `.agnostic-ai/`. Edit the specs, then run `agnostic-ai sync`. The generated files are git-ignored, and the pre-commit hook runs `agnostic-ai sync --check` when the CLI is installed. diff --git a/README.md b/README.md index 4993e7a..d4e0d7d 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,96 @@ # Phel CLI Skeleton -[Phel](https://phel-lang.org/) is a functional Lisp that compiles to PHP. This -is a minimal, opinionated starting point for a real **CLI application** with Phel. +A starting point for a command-line app in [Phel](https://phel-lang.org/), a functional Lisp that compiles to PHP. It ships two sample commands, `greet` and `add`, with tests, a command scaffolder, and a pre-commit gate. -It ships: +## What you get -- A data-driven dispatcher on [`phel\cli`](https://phel-lang.org/) (a - `symfony/console` wrapper) with sample `greet` + `add` subcommands. -- A pure **`core/` ÷ IO `commands/`** layering that stays testable as it grows - ([docs/architecture.md](docs/architecture.md)). -- A pure function exported to PHP via an auto-generated wrapper. -- Fast inner loop: pre-commit gate, command scaffolder, and watch mode. +- A command dispatcher built on `phel\cli`, which wraps `symfony/console`. +- Two layers: `core/` holds pure logic, `commands/` handles input and output. See [docs/architecture.md](docs/architecture.md). +- Unit tests for the core, smoke tests for every command, and mutation testing for the core. +- `bin/new-command` creates a command with its tests and registers it. +- A pure function exported to PHP through a generated wrapper. +- CI that builds the standalone binary and runs it. ## Requirements -- PHP **>= 8.5** ([phpbrew](https://github.com/phpbrew/phpbrew) on Linux, - [shivammathur/homebrew-php](https://github.com/shivammathur/homebrew-php) on macOS) - and [Composer](https://getcomposer.org/) — or use the bundled - `build/Dockerfile` + `docker-compose.yml`. +- PHP 8.5 or newer, and [Composer](https://getcomposer.org/). +- Or Docker: the repo includes a `Dockerfile` and a compose file (see [Docker](#docker)). -> Requires a tagged Phel release (`phel-lang/phel-lang` `^0.54`). Pin it to an -> exact version for a production app. +The skeleton requires phel-lang `^0.54`. Pin an exact version before you ship an app. -## Getting started +## Quick start ```bash -composer install # also installs the .githooks pre-commit gate -make help # list every dev task +composer install # also installs the pre-commit hook +composer dev greet alice +composer check # format check, lint, tests ``` -## Commands +`make help` lists every task. -Every task is both a `make ` (with short aliases) and a -`composer