feat: add 'prime' subcommand for LLM agent orientation#6
Merged
Conversation
Agents calling this CLI as a tool tend to flail without a written contract:
piping JSON to python, looking for a --json flag (there is none — JSON is
the only output mode), redirecting stderr with 2>&1. 'prime' is the
emerging convention for "load context for the agent" subcommands.
'crono-export prime' prints a one-screen primer covering:
- I/O contract: JSON array on stdout, errors on stderr, '[]' is success
- Auth: env vars, no token cache
- Date flags: --today/--days/--start..--end, "today" is local
- Each subcommand's row shape, with the typed-vs-string distinction
called out (servings/biometrics/exercises are typed; nutrition/notes
return raw CSV strings — cast with jq tonumber)
- jq recipes for the questions an agent is most likely to ask
Also pointer in root --help and README so an agent finds it without
having to be told.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 25, 2026
4 tasks
DTTerastar
added a commit
that referenced
this pull request
May 19, 2026
Review feedback on #44: - **Must fix #1: README.md stale.** Replaced the "no token cache" paragraph with the cache location ($XDG_CACHE_HOME), the CRONOMETER_NO_CACHE opt-out, the `auth logout` subcommand, and a security note ("treat session.json like a password"). Folds in the reviewer's nice-to-have #5 (security guidance) at the same time. - **Must fix #2: gofmt.** Ran `gofmt -w` on `cmd/format.go` and `internal/cronoclient/daterange_test.go` (trailing blank line + struct field alignment). `internal/cronoapi/gwt.go` is also flagged but is pre-existing from #37 — landed as a separate chore commit so this PR's diff stays scoped to release-blocker work. - **Nice-to-have #4: cache schema version.** Added `cacheSchemaVersion = 1` and a `Version int` field on cachedSession. Old/mismatched versions are silently treated as a miss so a future incompatible bump triggers a transparent re-login instead of a JSON-shape error. New test: TestSessionCacheVersionMismatch. Skipped: race on concurrent fresh logins (#6) — reviewer agreed this is fine for a single-user CLI. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
DTTerastar
added a commit
that referenced
this pull request
May 19, 2026
* feat: release-blocker bundle for v0.2.0 (#17 #18 #21 #16 #15 #23 #39 #40) Bundles eight ship-blocker fixes called out in the QA triage on main: - **#39 session cache (major):** persist auth/cookies to $XDG_CACHE_HOME/crono-export/session.json (mode 0600), retry-on-stale, CRONOMETER_NO_CACHE escape hatch, new `auth logout` subcommand. Fixes the rate-limit foot-gun where 5–6 back-to-back calls trip Cronometer's throttle. Also de-duplicates the "login failed: login failed:" wrap. - **#17 typed nutrition/notes JSON (breaking):** csvToJSON now returns []map[string]any with best-effort coercion (numeric → float64, true/false → bool, empty → null). Drops the contract drift where two of five subcommands forced jq `tonumber` on every column. - **#15 + #23 validation before login:** Args=cobra.NoArgs + a PreRunE that calls chosenFormat — bad --format / positional args now exit fast without burning a Cronometer login attempt. - **#16 + #18 + #21 contract-violation trio:** empty markdown is silent on stdout (friendly note → stderr); --until alone uses 7d window ending at --until (was 1-day); inverted --since/--until warns to stderr and returns empty + exit 0 (was non-zero error). - **#40 VitaminDIU cosmetic:** strippedSuffix table had "UI" instead of the standard "IU" abbreviation; vitamin D markdown was rendering without splitting the unit. Added TestStrippedSuffix to cover. - **#19 closed as part-fixed/part-wontfix:** zone-as-UTC was already fixed by the clean-room rewrite (#37); the wire CSV carries no time-of-day to surface. Documented in prime GOTCHAS. New tests cover: strippedSuffix (cmd), resolveDateRange (cronoclient), coerceCSVValue + csvToJSON (cronoclient), session cache round-trip (cronoclient). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fixup: address PR review — README, gofmt, cache schema version Review feedback on #44: - **Must fix #1: README.md stale.** Replaced the "no token cache" paragraph with the cache location ($XDG_CACHE_HOME), the CRONOMETER_NO_CACHE opt-out, the `auth logout` subcommand, and a security note ("treat session.json like a password"). Folds in the reviewer's nice-to-have #5 (security guidance) at the same time. - **Must fix #2: gofmt.** Ran `gofmt -w` on `cmd/format.go` and `internal/cronoclient/daterange_test.go` (trailing blank line + struct field alignment). `internal/cronoapi/gwt.go` is also flagged but is pre-existing from #37 — landed as a separate chore commit so this PR's diff stays scoped to release-blocker work. - **Nice-to-have #4: cache schema version.** Added `cacheSchemaVersion = 1` and a `Version int` field on cachedSession. Old/mismatched versions are silently treated as a miss so a future incompatible bump triggers a transparent re-login instead of a JSON-shape error. New test: TestSessionCacheVersionMismatch. Skipped: race on concurrent fresh logins (#6) — reviewer agreed this is fine for a single-user CLI. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: gofmt internal/cronoapi/gwt.go (preexisting drift from #37) Pure formatting: column-aligned const block and var block. No logic change. Flagged by `gofmt -l .` during review of #44. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Agents calling this CLI as a tool tend to flail without a written contract — piping JSON to python, hunting for a non-existent
--jsonflag, redirecting stderr with2>&1.primeis the emerging convention (à la liftoff-cli, disler/pi-vs-claude-code) for "load context for the agent" subcommands.crono-export primeprints a one-screen primer covering:[]is success-with-zero-rows.--today/--days N/--start..--end; "today" is local.jq tonumber).Also added a pointer in root
--helpand the README feature bullet so an agent finds it without being told.Test plan
go build ./...cleango vet ./...cleancrono-export primeproduces 77 lines of orientation, exit 0crono-export --helplistsprimeand the LLM pointerprimefirst and see if the flailing pattern stops🤖 Generated with Claude Code