refactor: align project with Go API CLI Playbook SOP

[Leechael]

Summary

• Rename packages to match SOP layout: internal/cli -> internal/cmd, internal/roam -> internal/client
• Extract internal/model for shared types (APIError, SearchResult, PageSearchResult, EstimateResult)
• Add internal/output with Formatter struct (JSON/plain/jq modes, Hint to stderr)
• Add ExitCode(err) int with stable exit codes: 0 (OK), 1 (error), 2 (auth 401/403), 3 (not found 404)
• Add embedded help system: docs/help/topics/ with HELP TOPICS block in root --help, file-based topic routing
• Add help topics: exit-codes and datalog (Clojure dialect reference with regex, string ops, schema attributes)
• Update go.mod module path to github.com/Leechael/roam-cli
• Fix Makefile ci target to output binary to bin/ instead of repo root
• Add golden snapshot tests for root help and help topic routing
• Add httptest-based unit tests for client package (Q, Write, BatchActions, error mapping)
• Add output Formatter unit tests (JSON, plain, jq validation)

Test plan

• make ci passes (fmt, vet, unit tests, BDD tests, build)
• roam-cli --help shows HELP TOPICS block with datalog and exit-codes
• roam-cli help exit-codes prints topic content
• roam-cli help datalog prints Datalog query reference
• roam-cli help unknown-xyz exits non-zero and lists available topics
• Golden snapshot tests pass without -update flag
• Client httptest tests cover success, 401, 404, empty body

---

Summary by cubic

Aligned the CLI with the SOP layout, added stable exit codes, and introduced an embedded help system with topic files. Also fixed output formatting so plain/default modes no longer print unexpected JSON.

• Refactors

  • Renamed packages: internal/cli -> internal/cmd, internal/roam -> internal/client; extracted shared types into internal/model.
  • Added internal/output for consistent JSON/plain/jq formatting.
  • Switched entrypoint to cmd.NewRootCmd() and cmd.ExitCode(); silenced Cobra usage/errors for cleaner stderr.
  • Updated module path to github.com/Leechael/roam-cli; fixed imports; make ci now builds to bin/.

• New Features

  • Stable exit codes: 0 OK, 1 error, 2 auth (401/403), 3 not found (404).
  • Embedded help topics with a HELP TOPICS block; help <topic> reads from docs/help/topics/ (added datalog and exit-codes).
  • Relative dates across flags (today/yesterday/tomorrow); added block find --today.
  • Tests: httptest client coverage, output formatter tests, and golden snapshots for root/help topics.
  • Fixed: internal/output Print is a no-op in plain/default modes to avoid unexpected JSON output.

^{Written for commit efdf628. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 37 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="internal/output/output.go">

<violation number="1" location="internal/output/output.go:55">
P2: Print always falls back to JSON even in plain/default modes. This contradicts the documented behavior and will emit JSON when callers expect to write their own human-readable/plain output.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}