From 640999156f65ff17745f3ed9039218d08c68e549 Mon Sep 17 00:00:00 2001 From: steven Date: Sat, 22 Aug 2026 19:59:55 +0800 Subject: [PATCH 1/2] Simplify the command synopsis in the README --json is documented in the JSON output section; repeating it on every synopsis line is noise. Co-Authored-By: Claude Fable 5 --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index efd0270..cba4450 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,16 @@ credentials for Pixel and Time Off, verifies identity, and issues read-only API requests — with stable JSON output designed for scripts and automation. ```text -fm [--json] doctor -fm [--json] version -fm [--json] pixel auth login [--token-stdin] -fm [--json] pixel auth status -fm [--json] pixel auth logout -fm [--json] pixel request get -fm [--json] time-off auth login [--token-stdin] -fm [--json] time-off auth status -fm [--json] time-off auth logout -fm [--json] time-off request get +fm doctor +fm version +fm pixel auth login [--token-stdin] +fm pixel auth status +fm pixel auth logout +fm pixel request get +fm time-off auth login [--token-stdin] +fm time-off auth status +fm time-off auth logout +fm time-off request get ``` ## Installation From e7cda5d16bf81fda1d8ad3b5eb82861ac2eb0c9b Mon Sep 17 00:00:00 2001 From: steven Date: Sat, 22 Aug 2026 20:03:58 +0800 Subject: [PATCH 2/2] Add development docs and AGENTS.md docs/development.md covers setup, testing, and layout; AGENTS.md gives coding agents the verification commands, conventions, and the security rules this project requires. Co-Authored-By: Claude Fable 5 --- AGENTS.md | 51 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 3 ++- docs/development.md | 51 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 104 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 docs/development.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a64818b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,51 @@ +# AGENTS.md + +Guidance for AI coding agents working in this repository. + +## What this is + +`fm` is the FeedMob CLI: a Ruby gem packaged into native binaries with +Tebako and distributed via Homebrew (the formula lives in `Formula/fm.rb` in +this repo). See `README.md` for user-facing behavior. + +## Setup and verification + +```sh +bundle install +bundle exec exe/fm version # run from the working tree +bundle exec rake test # minitest +bundle exec rubocop --format simple +``` + +Tests and RuboCop must pass before opening a PR; CI also runs the +release-packaging test matrix and Formula checks. Target Ruby is 3.2+ +(`.ruby-version` pins the exact patch). + +## Conventions + +- `# frozen_string_literal: true` in every Ruby file; follow existing style, + RuboCop config is the authority. +- Runtime dependencies go in the gemspec and `packaging/Gemfile` only — the + release build packages just those. Dev/test dependencies stay in the root + `Gemfile`. +- `Formula/fm.rb` is rendered by `script/render-homebrew-formula` during a + release. Never hand-edit it outside the release flow; it follows brew + style and is excluded from project RuboCop. +- `FeedMob::CLI::VERSION` is bumped by the release workflow, not by hand. + Tests must derive expected versions from the constant, never hardcode one. + +## Security rules (hard requirements) + +- Credentials never appear in argv, logs, JSON output, error messages, or + test fixtures. Tests use sentinel tokens and loopback HTTP servers only. +- Never touch the real macOS Keychain in tests — inject the fakes provided + through the `Keychain` constructor. +- Base URLs are HTTPS-only; plain HTTP is allowed solely for loopback with + explicit `FEEDMOB_ALLOW_INSECURE_HTTP=1`. +- Never overwrite a published tag or GitHub Release; the release pipeline + refuses to and so should you. + +## Releasing + +See `docs/release.md`. Releases are a manual workflow dispatch with +auto-incremented versions; Formula PRs are always reviewed by a human. diff --git a/README.md b/README.md index cba4450..7e17c18 100644 --- a/README.md +++ b/README.md @@ -114,5 +114,6 @@ a stable JSON envelope to stdout, including errors: ## Development and releasing -See [docs/release.md](docs/release.md) for the Tebako/Homebrew release +See [docs/development.md](docs/development.md) for local setup and testing, +and [docs/release.md](docs/release.md) for the Tebako/Homebrew release pipeline and maintainer workflow. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..81cb1ba --- /dev/null +++ b/docs/development.md @@ -0,0 +1,51 @@ +# Development + +## Setup + +Requires Ruby 3.2+ (the repo pins `.ruby-version`; rbenv is used when +available): + +```sh +bundle install +``` + +Run the CLI from the working tree: + +```sh +bundle exec exe/fm version +bundle exec exe/fm doctor +``` + +Install it like an end user (isolated gem home under `~/.local`): + +```sh +make install-local +export PATH="$HOME/.local/bin:$PATH" +``` + +`PREFIX=/your/prefix make install-local` changes the install location. + +## Tests and lint + +```sh +bundle exec rake test +bundle exec rubocop --format simple +``` + +Both run in CI on every PR, along with the release-packaging test matrix +(four native targets) and Formula checks. Platform-specific release tests +skip automatically on non-matching hosts. + +## Layout + +- `lib/feedmob/cli/` — commands, credential storage (Keychain on macOS, + AES-256-GCM encrypted file elsewhere), HTTP client, JSON envelope +- `exe/fm` — entry point +- `script/` — release pipeline scripts (build, verify, publish, formula) +- `packaging/` — pinned Tebako/Ruby release configuration and runtime Gemfile +- `Formula/fm.rb` — Homebrew formula, rendered at release time + +## Releasing + +See [release.md](release.md). Versions auto-increment from the latest tag; +publishing is a single manual workflow dispatch with a confirmation gate.