From 29d3d234814b8f5009c455fb566a414a00d74f41 Mon Sep 17 00:00:00 2001 From: Gio Lodi Date: Fri, 30 Oct 2026 11:44:15 +1100 Subject: [PATCH 1/3] Add `AGENTS.md` The repo had no agent instructions. The build and test commands, the generated-file rules (`README.md`, `commands.generated.ts`), and the multi-file checklist for adding a command weren't written down anywhere. --- Generated with the help of Claude Code, https://claude.ai/code Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a4e8c9a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,59 @@ +# AGENTS.md + +`beeper` is an oclif CLI that talks to Beeper Desktop or Beeper Server through `@beeper/desktop-api`. + +## Layout + +A Bun workspace: + +- `packages/cli` — the CLI itself (`@beeper/cli`, published as `beeper-cli`). +- `packages/cli-plugin-cloudflare` — an oclif plugin built on the CLI's plugin SDK (`packages/cli/src/plugin-sdk.ts`). +- `packages/npm` — the npm wrapper that ships the prebuilt binaries. + +Inside `packages/cli`, one file per command under `src/commands//.ts`; shared code lives in `src/lib`. + +## Bootstrap + +Bun is pinned to the version in `package.json` → `packageManager`. + +```sh +bun install --frozen-lockfile +``` + +## Build, test, lint + +Run from the repo root; these are what CI runs. + +```sh +bun run typecheck +bun run test +bun run lint +``` + +`bun run check` runs typecheck, test, build, and pack in one go. +Try the CLI from source with `bun --filter @beeper/cli run dev -- `. + +`bun run test` in `packages/cli` is more than unit tests: it builds, verifies the README is up to date, checks API copy against the SDK, validates the command manifest, runs `test/cli-smoke.ts`, then `bun test`. +Unit tests use `bun:test` and live in `packages/cli/test/*.test.ts`; stub the SDK with `test/fixtures/fake-client.ts`. + +Ignore the shell scripts in `packages/cli/scripts/` without an extension (`format`, `mock`, `test`, …); use the `package.json` scripts. + +## Adding or changing a command + +Commands extend `BeeperCommand` (`src/lib/command.ts`), which supplies the global flags. +Anything that writes to Beeper or local CLI state must call `ensureWritable(flags)` so `--read-only` holds. +Raise user-facing failures with the helpers in `src/lib/errors.ts`, not bare `Error`s, so exit codes and `--json` output stay consistent. + +A new command also needs: + +- An entry with at least one example in `src/lib/manifest.ts`. +- Its name in `expectedCommands` in `test/cli-smoke.ts`. +- If it wraps a new SDK method, its description in `src/lib/copy.ts` and a row in `scripts/check-api-copy.ts`. + +Then regenerate the READMEs with `bun --filter @beeper/cli run readme`. +That rewrites both `packages/cli/README.md` and the root `README.md`; never edit either by hand. +`src/commands.generated.ts` is rewritten by every build — commit it with the change. + +## Changesets + +User-facing changes to a published package need a changeset: `bun run changeset`. From 7ea708f5c8dd0bc54cd770f880ad2c27f897a7db Mon Sep 17 00:00:00 2001 From: Gio Lodi Date: Fri, 30 Oct 2026 11:45:45 +1100 Subject: [PATCH 2/3] Add `CLAUDE.md` importing `AGENTS.md` Claude Code reads `CLAUDE.md`, not `AGENTS.md`. --- Generated with the help of Claude Code, https://claude.ai/code Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From 6a776a792fb95a20c11ce6460edce5069d5ac15c Mon Sep 17 00:00:00 2001 From: Gio Lodi Date: Fri, 30 Oct 2026 13:41:20 +1100 Subject: [PATCH 3/3] Drop guidance on extensionless scripts Whether those scripts stay is the team's call, not something `AGENTS.md` should decide for them. --- Generated with the help of Claude Code, https://claude.ai/code Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a4e8c9a..36f0645 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,8 +36,6 @@ Try the CLI from source with `bun --filter @beeper/cli run dev -- `. `bun run test` in `packages/cli` is more than unit tests: it builds, verifies the README is up to date, checks API copy against the SDK, validates the command manifest, runs `test/cli-smoke.ts`, then `bun test`. Unit tests use `bun:test` and live in `packages/cli/test/*.test.ts`; stub the SDK with `test/fixtures/fake-client.ts`. -Ignore the shell scripts in `packages/cli/scripts/` without an extension (`format`, `mock`, `test`, …); use the `package.json` scripts. - ## Adding or changing a command Commands extend `BeeperCommand` (`src/lib/command.ts`), which supplies the global flags.