Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .agnostic-ai/AGNOSTIC_AI.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/`
Expand Down
16 changes: 8 additions & 8 deletions .agnostic-ai/rules/io-boundaries.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,37 +5,37 @@ 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/`

**The IO boundary.** The only layer that talks to the outside world.

- 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.
2 changes: 1 addition & 1 deletion .agnostic-ai/rules/phel.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down
16 changes: 12 additions & 4 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -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 #
53 changes: 53 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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.
139 changes: 70 additions & 69 deletions README.md
Original file line number Diff line number Diff line change
@@ -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 <target>` (with short aliases) and a
`composer <script>`:
## Tasks

| Task | Command |
| --------------------------- | ----------------------------- |
| Run from sources | `composer dev [args]` |
| Build standalone PHP | `composer build` → `out/main.php` |
| Run tests | `composer test` |
| Format | `composer format` |
| Watch (reload on save) | `composer watch` |
| REPL | `composer repl` |
| Local gate (format+lint+test) | `composer check` |
| Mutation-test `core/` | `composer mutate` |
| Scaffold a command | `make new-command NAME=foo` |
Each task is a composer script. The `Makefile` calls the same scripts and adds short aliases.

| Task | Command | Alias |
| --- | --- | --- |
| Run from sources | `composer dev greet alice` | `make d ARGS="greet alice"` |
| Run tests | `composer test` | `make t` |
| Format files | `composer format` | `make f` |
| Fast gate: format check, lint, tests | `composer check` | `make c` |
| Mutation-test `core/` | `composer mutate` | `make mu` |
| Full CI gate | `composer ci` | `make ci` |
| Build the standalone binary at `out/main.php` | `composer build` | `make b` |
| Regenerate the PHP wrappers | `composer export` | `make export` |
| Recompile on save | `composer watch` | `make w` |
| Open a REPL | `composer repl` | `make r` |
| Create a command | `make new-command NAME=foo` | `make nc NAME=foo` |

Composer reads flags itself, so put `--` before flags meant for the app:

```bash
composer dev greet alice # positional args forward as-is
composer dev -- greet alice --loud # put -- before flags (composer convention)
php out/main.php add 1 2 3 # run the built binary
php out/main.php add -- -1 2 # -- before negative numbers
composer dev -- greet alice --loud
php out/main.php add 1 2 3
php out/main.php add -- -1 2 # -- is also needed for negative numbers
```

## Project layout
## Layout

```
src/
├── app.phel ; the Application: registers every command
├── main.phel ; dispatches the app (build-mode guarded)
├── core/ ; PURE logic — no IO (greeting, adder; adder exported to PHP)
├── commands/ ; IO boundary: parse args, print, exit (greet, add)
└── PhelGenerated/ ; auto-generated PHP wrappers
app.phel registers every command
main.phel runs the app (skipped during build)
core/ pure logic: greeting, adder
commands/ input and output: greet, add
PhelGenerated/ generated PHP wrappers (git-ignored)
tests/
├── core/ ; pure unit tests (no CLI harness)
└── commands/ ; CLI handler smoke tests
docs/ ; architecture.md (layering), conventions.md (idioms)
bin/new-command ; scaffold a command across both layers
example/ ; call an exported Phel fn from PHP
phel-config.php ; build / export / format config
.githooks/pre-commit ; auto-installed gate (composer check)
core/ unit tests, no CLI harness
commands/ one smoke test per command
app-test.phel runs the real app
bin/new-command command scaffolder
docs/ architecture and conventions
example/ calls an exported Phel function from PHP
```

## Adding a command
## Add a command

```bash
make new-command NAME=foo # generates core + command + both tests, registers it
make new-command NAME=say-hi
```

Then fill in the logic. The scaffolder also registers the command in
`src/app.phel`. Keep commands thin; put real logic in `core/`. See
[docs/architecture.md](docs/architecture.md).
This creates `src/core/say-hi.phel`, `src/commands/say-hi.phel`, and a test for each. It also adds the command to `src/app.phel`. If that file has been reshaped so the edit is unsafe, the script prints the two lines to add by hand.

Put the logic in `core/` and keep the command to reading arguments, calling core, and printing. [docs/architecture.md](docs/architecture.md) explains why.

## Exporting Phel to PHP
## Export to PHP

Mark a `core/` function `{:export true}` (see `src/core/adder.phel`), then:
Mark a `core/` function with `{:export true}` (see `src/core/adder.phel`), then:

```bash
composer export # regenerates src/PhelGenerated/**
composer export
php example/using-exported-phel-function.php
```

## AI agent config (optional)

Conventions are authored once as agnostic specs under `.agnostic-ai/rules/` and
transpiled per tool with [agnostic-ai](https://github.com/chemaclass/agnostic-ai)
(`agnostic-ai sync`). The emitted `.claude/`, `AGENTS.md` are git-ignored: run
`agnostic-ai sync` after cloning, and edit the specs, not the output.
`vendor/bin/phel agent-install --auto` adds Phel's built-in idiom skills.

## Docker

```bash
Expand All @@ -107,9 +99,18 @@ docker exec -ti phel_cli_skeleton bash
composer install
```

The container runs as a non-root user.

## AI tool config

The rules for AI coding tools live as specs in `.agnostic-ai/` and are turned into each tool's own files by [agnostic-ai](https://github.com/chemaclass/agnostic-ai). The generated files are git-ignored. After cloning, run `agnostic-ai sync` to create them, and edit the specs, never the output. Install the CLI first, from [its docs](https://agnostic-ai.org/docs/installation/).

`vendor/bin/phel agent-install --auto` adds Phel's own idiom skills.

## More

- [docs/architecture.md](docs/architecture.md) — the core/commands layering rule
- [docs/conventions.md](docs/conventions.md) — Phel idioms, naming, gotchas
- Phel docs: <https://phel-lang.org/documentation/getting-started/>
- `phel\cli` guide: `vendor/phel-lang/phel-lang/docs/cli-guide.md`
- [CONTRIBUTING.md](CONTRIBUTING.md): setup, the gate, commit and PR conventions
- [docs/architecture.md](docs/architecture.md): the `core/` and `commands/` rule
- [docs/conventions.md](docs/conventions.md): naming, idioms, and gotchas
- [Phel documentation](https://phel-lang.org/documentation/getting-started/)
- `vendor/phel-lang/phel-lang/docs/cli-reference.md`: every `phel` command
Loading
Loading