From e3d2e9306b3d471a3e8722467ec9d4bf7ff4ab76 Mon Sep 17 00:00:00 2001 From: teernisse Date: Mon, 23 Feb 2026 01:32:18 -0500 Subject: [PATCH] Document TUI controls, category synonyms, flag aliases, and compare JSON AGENTS.md: - Add command table covering all five commands - Expand input tolerance section with flag alias table - Add filtering/sorting, auto JSON, and structured error sections - Include canonical examples for compare README.md: - Expand compare command docs with ranking explanation and --count flag - Replace tui stub with full keybinding reference (tab, /, s, g, c, a, l, r, [/], 1-9, u/d, b/f, ?, q) - Add compare-specific flags section and sort alias note - Add category synonym table showing all bidirectional mappings - Add flag alias resolution table (zipcode->zip, dept->department, etc.) - Add compare JSON schema documenting all response fields Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 38 ++++++++++++++++++++++++- README.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 115 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 826b84c..bcadc0c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,16 +2,52 @@ The `pubcli` CLI is intentionally tolerant of minor syntax mistakes when intent is clear. +## Commands + +| Command | Purpose | Requires | +|---------|---------|----------| +| `pubcli` | Fetch deals | `--store` or `--zip` | +| `pubcli stores` | List nearby stores | `--zip` | +| `pubcli categories` | List categories with counts | `--store` or `--zip` | +| `pubcli compare` | Rank nearby stores by deal quality | `--zip` | +| `pubcli tui` | Interactive deal browser | `--store` or `--zip`, interactive terminal | + +## Input Tolerance + Accepted flexible forms include: - `-zip 33101` -> interpreted as `--zip 33101` - `zip=33101` -> interpreted as `--zip=33101` - `--ziip 33101` -> interpreted as `--zip 33101` - `categoriess` -> interpreted as `categories` +Flag aliases: `zipcode`/`postal-code` -> `--zip`, `dept` -> `--department`, `search` -> `--query`, `sortby`/`orderby` -> `--sort`, `max` -> `--limit`. + The CLI prints a `note:` line when it auto-corrects input. Use canonical syntax in future commands: - `pubcli --zip 33101` - `pubcli --store 1425 --bogo` - `pubcli categories --zip 33101` - `pubcli stores --zip 33101 --json` +- `pubcli compare --zip 33101 --category produce` +- `pubcli compare --zip 33101 --bogo --count 3 --json` -When intent is unclear, errors include a direct explanation and relevant examples. +## Filtering and Sorting + +Deal filter flags (`--bogo`, `--category`, `--department`, `--query`, `--sort`, `--limit`) are available on `pubcli`, `compare`, and `tui`. + +Sort accepts: `relevance` (default), `savings`, `ending`. Aliases `end`, `expiry`, `expiration` map to `ending`. + +Category synonyms: `veggies` -> `produce`, `chicken` -> `meat`, `bread` -> `bakery`, `cheese` -> `dairy`, `cold cuts` -> `deli`, etc. + +## Auto JSON + +When stdout is not a TTY, JSON output is enabled automatically. This means piping to `jq` or another process produces JSON without requiring `--json`. + +## Errors + +When intent is unclear, errors include a direct explanation and relevant examples. In JSON mode, errors are structured: + +```json +{"error":{"code":"INVALID_ARGS","message":"...","suggestions":["..."],"exitCode":2}} +``` + +Exit codes: `0` success, `1` not found, `2` invalid args, `3` upstream error, `4` internal error. diff --git a/README.md b/README.md index 549c191..cc75bc3 100644 --- a/README.md +++ b/README.md @@ -95,16 +95,37 @@ pubcli categories -z 33101 --json ### `pubcli compare` -Compare nearby stores and rank them by matching deal quality. +Compare nearby stores and rank them by filtered deal quality. Requires `--zip`. Stores are ranked by number of matched deals, then deal score, then distance. ```bash pubcli compare --zip 33101 pubcli compare --zip 33101 --category produce --sort savings +pubcli compare --zip 33101 --bogo --count 3 --json ``` ### `pubcli tui` -Keyboard-driven interactive browser for deal lists. +Full-screen interactive browser for deal lists with a responsive two-pane layout: +- async startup loading spinner + skeleton while store/deals are fetched +- visual deal sections (BOGO/category grouped) with jump navigation + +Controls: + +- `tab` — switch focus between list and detail panes +- `/` — fuzzy filter deals in the list pane +- `s` — cycle sort mode (`relevance` -> `savings` -> `ending`) +- `g` — toggle BOGO-only inline filter +- `c` — cycle category inline filter +- `a` — cycle department inline filter +- `l` — cycle result limit inline filter +- `r` — reset inline sort/filter options back to CLI-start defaults +- `j` / `k` or arrows — navigate list and scroll detail +- `u` / `d` — half-page detail scroll +- `b` / `f` or `pgup` / `pgdown` — full-page detail scroll +- `[` / `]` — jump to previous/next section +- `1..9` — jump directly to a numbered section +- `?` — toggle inline help +- `q` — quit ```bash pubcli tui --zip 33101 @@ -113,13 +134,13 @@ pubcli tui --store 1425 --category meat --sort ending ## Flags -Global flags: +Global flags (available on all commands): - `-s, --store string` Publix store number (example: `1425`) - `-z, --zip string` ZIP code for store lookup - `--json` Output JSON instead of styled terminal output -Deal filtering flags (`pubcli` root command): +Deal filtering flags (available on `pubcli`, `compare`, and `tui`): - `--bogo` Show only BOGO deals - `-c, --category string` Filter by category (example: `bogo`, `meat`, `produce`) @@ -128,17 +149,40 @@ Deal filtering flags (`pubcli` root command): - `--sort string` Sort by `relevance` (default), `savings`, or `ending` - `-n, --limit int` Limit results (`0` means no limit) +Compare-specific flags: + +- `--count int` Number of nearby stores to compare, 1-10 (default `5`) + +Sort accepts aliases: `end`, `expiry`, and `expiration` are equivalent to `ending`. + ## Behavior Notes -- Either `--store` or `--zip` is required for deal and category lookups. +- Either `--store` or `--zip` is required for deal and category lookups. `compare` requires `--zip`. - If only `--zip` is provided, the nearest store is selected automatically. - When using text output and ZIP-based store resolution, the selected store is shown. -- Filtering is applied in this order: `bogo`, `category`, `department`, `query`, `limit`. -- Category matching is case-insensitive and supports practical synonyms (for example `veggies` matches `produce`). +- Filtering is applied in this order: `bogo` + `category`, `department`, `query`, `sort`, `limit`. +- Category matching is case-insensitive and supports synonym groups (see below). - Department and query filters use case-insensitive substring matching. - Running `pubcli` with no args prints compact quick-start help. - When stdout is not a TTY (for example piping to another process), JSON output is enabled automatically unless explicitly set. +### Category Synonyms + +Category filtering recognizes synonyms so common names map to the right deals: + +| Category | Also matches | +|----------|-------------| +| `bogo` | `bogof`, `buy one get one`, `buy1get1`, `2 for 1`, `two for one` | +| `produce` | `fruit`, `fruits`, `vegetable`, `vegetables`, `veggie`, `veggies` | +| `meat` | `beef`, `chicken`, `poultry`, `pork`, `seafood` | +| `dairy` | `milk`, `cheese`, `yogurt` | +| `bakery` | `bread`, `pastry`, `pastries` | +| `deli` | `delicatessen`, `cold cuts`, `lunch meat` | +| `frozen` | `frozen foods` | +| `grocery` | `pantry`, `shelf` | + +Synonym matching is bidirectional — using `chicken` as a category filter matches deals tagged `meat`, and vice versa. + ## CLI Input Tolerance The CLI auto-corrects common input mistakes and prints a `note:` describing the normalization: @@ -147,6 +191,18 @@ The CLI auto-corrects common input mistakes and prints a `note:` describing the - `zip=33101` -> `--zip=33101` - `--ziip 33101` -> `--zip 33101` - `stores zip 33101` -> `stores --zip 33101` +- `categoriess` -> `categories` + +Flag aliases are recognized and rewritten: + +| Alias | Resolves to | +|-------|------------| +| `zipcode`, `postal-code` | `--zip` | +| `store-number`, `storeno` | `--store` | +| `dept` | `--department` | +| `search` | `--query` | +| `sortby`, `orderby` | `--sort` | +| `max` | `--limit` | Command argument tokens are preserved for command workflows like: @@ -192,6 +248,21 @@ Object map of category name to deal count: } ``` +### Compare (`pubcli compare ... --json`) + +Array of objects ranked by deal quality: + +- `rank` (number) +- `number` (string) — store number +- `name` (string) +- `city` (string) +- `state` (string) +- `distance` (string) +- `matchedDeals` (number) +- `bogoDeals` (number) +- `score` (number) +- `topDeal` (string) + ## Structured Errors When command execution fails, errors include: