From 1fcfd97b1db29db10d42c4edcc0e345f561cde8d Mon Sep 17 00:00:00 2001 From: Dan Richards Date: Sun, 28 Jun 2026 13:27:35 -0400 Subject: [PATCH 1/3] Add Crow CLI README --- README.md | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a152b86 --- /dev/null +++ b/README.md @@ -0,0 +1,139 @@ +# Crow CLI + +This repository contains `crowbot/listen`, a Laravel package that lets a local +developer or agent read Crow handoff events from the command line. + +It provides two Artisan commands: + +- `crow:read`: fetch one unread Crow event and print an AI-agent-ready brief. +- `crow:listen`: run a local HTTP listener for live Crow events forwarded from + the Crow API. + +The package is required by `crow-api` as `crowbot/listen`. + +## Requirements + +- PHP 8.2+ +- Composer +- A Crow API token with access to listener events +- A running Crow API, usually `https://crow.test/api/v1` +- expose.dev or another tunnel if using live push delivery with `crow:listen` + +## Install In A Laravel App + +Require the package through Composer. In the local Crow workspace, the API uses +the package as a path/dev dependency. + +Publish config when needed: + +```bash +php artisan vendor:publish --tag=crow-listen-config +``` + +Configure environment variables: + +```dotenv +CROW_API_URL=https://crow.test/api/v1 +CROW_API_TOKEN=your-sanctum-token +CROW_APP_ID= +CROW_LISTEN_PUBLIC_URL= +CROW_LISTEN_SECRET= +CROW_LISTEN_HOST=127.0.0.1 +CROW_LISTEN_PORT=8787 +``` + +Required: + +- `CROW_API_URL`: Crow API base. The package appends `/api/v1` if missing. +- `CROW_API_TOKEN`: bearer token used for API requests. + +Optional: + +- `CROW_APP_ID`: limit reads/listeners to a Crow app. +- `CROW_LISTEN_PUBLIC_URL`: public tunnel URL Crow can call for live events. +- `CROW_LISTEN_SECRET`: fixed signing secret for listener webhooks. If omitted, + `crow:listen` generates a temporary secret. +- `CROW_LISTEN_HOST` and `CROW_LISTEN_PORT`: local listener bind address. + +## Read Events + +Fetch the latest unread event: + +```bash +php artisan crow:read +``` + +Fetch a specific event: + +```bash +php artisan crow:read EVENT_ID +``` + +Filter by app or event type: + +```bash +php artisan crow:read --app-id=1 --events=recon.ready +``` + +Print raw JSON and leave the event unread: + +```bash +php artisan crow:read --json --leave-unread +``` + +## Listen For Live Events + +Start a local listener and register it with Crow: + +```bash +expose share --subdomain=your-name --server=us-2 http://127.0.0.1:8787 +CROW_LISTEN_PUBLIC_URL=https://your-name.us-2.sharedwithexpose.com php artisan crow:listen +``` + +Run without registering, useful for local webhook tests: + +```bash +php artisan crow:listen --no-register --port=8787 +``` + +Health endpoint: + +```text +GET /health +``` + +Event endpoint: + +```text +POST /crow/events +``` + +Live events are signed with: + +```text +X-Crow-Timestamp +X-Crow-Signature +``` + +The signature is `hash_hmac('sha256', timestamp + "." + body, secret)`. + +## Local Package Development + +From this package directory: + +```bash +composer install +vendor/bin/phpunit +``` + +Useful files: + +- `src/Commands/CrowReadCommand.php`: one-shot event fetch command. +- `src/Commands/CrowListenCommand.php`: live listener command. +- `src/CrowApiClient.php`: Crow API wrapper. +- `src/ListenerServer.php`: small local HTTP listener. +- `src/EventFormatter.php`: markdown/JSON output formatting. +- `config/crow-listen.php`: environment-backed config. + +When changing package behavior through the `api/` app, run the API's relevant +tests as well as this package's PHPUnit suite. From 4a60add515f4f91e8be861b9ad301ca55d2fec49 Mon Sep 17 00:00:00 2001 From: Dan Richards Date: Fri, 10 Jul 2026 17:03:24 -0400 Subject: [PATCH 2/3] Ignore Composer dependencies and PHPUnit cache --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..27eff37 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/vendor/ +/.phpunit.cache/ From 82bda882ac8bfe68caf5d0d4245ec556801f40c3 Mon Sep 17 00:00:00 2001 From: Dan Richards Date: Fri, 14 Aug 2026 01:18:55 -0400 Subject: [PATCH 3/3] Refresh CLI implementation status --- IMPLEMENTATION.md | 158 ++++++++++++++++++++++++++++------------------ 1 file changed, 98 insertions(+), 60 deletions(-) diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index 958d964..4096107 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -1,60 +1,98 @@ -# Laravel Zero CLI Migration Plan - -## Summary - -Convert this repo in place from a Laravel package into a Laravel Zero 12 standalone CLI named `crow`, with Composer package identity `crowbot/cli`. The primary UX becomes PHAR-first distribution through Packagist, short commands like `crow plan`, and a new `crow auth login` setup flow. - -Use the current Laravel Zero docs path: `composer create-project` style skeleton, commands in `app/Commands`, config in `config`, PHAR builds via `php crow app:build crow`, and Packagist PHAR bin behavior from the PHAR distribution docs. - -## Key Changes - -- Replace package scaffolding with Laravel Zero app scaffolding: - - `composer.json` becomes a Laravel Zero project using `laravel-zero/framework:^12`. - - Rename app executable to `crow`. - - Set Composer package name to `crowbot/cli`. - - Remove Laravel package auto-discovery and `CrowListenServiceProvider`. - - Add `box.json`, `bootstrap/app.php`, Laravel Zero `config/app.php`, and `config/commands.php`. -- Move reusable code into app namespace: - - Existing commands become Laravel Zero commands under `app/Commands`. - - Existing client, formatter, and listener classes move under `app/Support` or equivalent `App\...` namespace. - - Keep behavior of current `plan`, `read`, and `listen` flows unless explicitly changed below. -- Command UX: - - Primary commands are `crow plan`, `crow read`, and `crow listen`. - - Add hidden/compat aliases for `crow:plan`, `crow:read`, and `crow:listen` where Laravel command aliasing allows it. - - Update command output that currently says `php artisan crow:plan ` to say `crow plan `. -- Auth/config: - - Add `crow auth login`. - - Prompt for API token and optional API URL. - - Store credentials in `~/.crow/config.json` with restrictive permissions where supported. - - Config precedence: explicit command option, environment variable, `~/.crow/config.json`, then default config. - - Keep default API URL as the current `https://crow.test/api/v1`. - - Preserve existing env vars like `CROW_API_TOKEN`, `CROW_API_URL`, `CROW_APP_ID`, and listener options for automation. -- PHAR-first distribution: - - Build artifact name is `builds/crow`. - - Composer `bin` points to `builds/crow` for release/Packagist distribution. - - Move Laravel Zero runtime dependencies to the release model recommended by the docs for PHAR Packagist installs. - - Include Laravel Zero `dotenv` and `http` components so HTTP and adjacent `.env` files work in PHAR usage. - -## Test Plan - -- Port current PHPUnit/Testbench command tests to Laravel Zero app tests. -- Cover: - - `crow plan` lists plans and prints `crow plan `. - - `crow plan ` outputs markdown/json and handles API failures. - - `crow read` fetches latest or by ID and respects `--leave-unread`. - - `crow listen` preserves listener registration/no-register behavior. - - `crow auth login` writes `~/.crow/config.json` and command config reads it. - - Env vars override stored config. - - Hidden compatibility aliases still execute the same command behavior. -- Add build verification: - - `composer test` or equivalent test command passes. - - `php crow list` shows the expected commands. - - `php crow app:build crow --build-version=` creates `builds/crow`. - - `./builds/crow plan --help` runs successfully. - -## Assumptions - -- This repo stops being a Laravel installable package and becomes only the standalone CLI. -- v1 does not add native single-file binaries; PHAR is the release artifact. -- `crow auth login` is the only new auth command for this migration; logout/status can be added later. -- Production still defaults to `https://crow.test/api/v1` until a different URL is provided. +# Crow CLI Implementation + +This is the canonical implementation status and backlog for the standalone +Laravel Zero `crow` CLI. + +Status labels: + +- `[x]` Done in source or documented evidence. +- `[~]` Partially done, modeled, or not fully verified. +- `[ ]` Not done. + +## Current Read + +The Laravel Zero migration is complete in source. This repository is a +standalone CLI app named `crow`, with command code under `app/Commands`, support +code under `app/Support`, PHAR configuration, a checked-in `builds/crow` +artifact, and feature tests for the primary command flows. + +The remaining work is release confidence: refresh the PHAR before publication, +verify Packagist/global Composer installation, decide the production default API +URL, and add release smoke evidence. + +## Done + +- [x] Converted the repository from a Laravel package into a Laravel Zero 12 + project. +- [x] Composer package identity is `crowbot/cli`. +- [x] The executable entrypoint is `crow`. +- [x] Composer `bin` points at `builds/crow` for PHAR-backed distribution. +- [x] Added Laravel Zero app scaffolding: `bootstrap/app.php`, `config/app.php`, + `config/commands.php`, `box.json`, and app/service-provider wiring. +- [x] Moved runtime code into the app namespace under `app/Commands` and + `app/Support`. +- [x] Implemented `crow plan` for listing implementation-plan handoffs, fetching + a specific plan, JSON output, and file output. +- [x] Implemented `crow read` for latest/specific event reads, unread handling, + app filtering, and event-type filters. +- [x] Implemented `crow listen` with listener registration, `--no-register`, + host/port/public URL options, shared secret support, `/crow/events`, and + `/health`. +- [x] Implemented `crow auth login` with browser launch, token prompt, + `--api-url`, `--api-token`, `--global`, and `--no-browser`. +- [x] Credentials are written to the nearest project `.crow/config.json` by + default, with `~/.crow/config.json` used for `--global` or when no project + root is found. +- [x] Config precedence is explicit option, environment, project config, global + config, then built-in default. +- [x] Restrictive config directory/file permissions are attempted where the + platform supports them. +- [x] Existing automation environment variables are preserved, including + `CROW_API_URL`, `CROW_API_TOKEN`, `CROW_APP_ID`, listener URL/host/port, and + listener secret. +- [x] Hidden compatibility command names are available for `crow:plan`, + `crow:read`, and `crow:listen`. +- [x] Feature and unit tests cover plan, read, listen, auth login, config + precedence, listener behavior, aliases, and API failures. + +## Partial + +- [~] A PHAR artifact exists at `builds/crow`, but it should be rebuilt and + smoke-tested from the release commit before publication. +- [~] The default API URL remains `https://crow.test/api/v1`; production release + should either change it or document the required user override. +- [~] Packagist/Composer global installation is documented, but a dated + install-from-package smoke report is not recorded here. +- [~] `auth login` exists, but logout/status commands are still future + ergonomics work. + +## Not Done + +- [ ] Publish and verify a Packagist/global Composer install. +- [ ] Add dated release smoke evidence for `builds/crow`. +- [ ] Add `crow auth logout`. +- [ ] Add `crow auth status`. +- [ ] Decide and document the production default API URL before public release. +- [ ] Native single-file binaries outside PHAR distribution. + +## Next Priority + +1. Rebuild the PHAR from a clean release commit with + `php crow app:build crow --build-version=`. +2. Smoke-test `./builds/crow list`, `./builds/crow plan --help`, auth login + with `--no-browser`, and one real API-backed plan/read command. +3. Publish or dry-run Packagist installation and verify `composer global require + crowbot/cli` exposes `crow`. +4. Decide whether the public default API URL should remain `crow.test`, move to + production, or require explicit setup. +5. Add `auth status` and `auth logout` after release packaging is verified. + +## Verification Needed + +- [ ] `composer test` +- [ ] `php crow list` +- [ ] `php crow app:build crow --build-version=` +- [ ] `./builds/crow plan --help` +- [ ] `./builds/crow auth login --api-token= --no-browser` +- [ ] `composer global require crowbot/cli` from a published or local package + source.