Split gor into reusable gor-core library + gor CLI (typed operations)

[kerryhatcher]

Summary

Split gor into a reusable gor-core library crate and a thin gor CLI crate so other Rust applications can depend on gor's GitHub functionality directly — calling typed operations that return structured data — instead of shelling out to the gor binary or reimplementing the GitHub API layer themselves.

Problem

Today gor is a single crate with a lib.rs + main.rs split, but the "library" only exposes Gor::run() (parse args, dispatch). Every command in src/cmd/* entangles three concerns:

1. clap argument structs,
2. GitHub API calls, and
3. printing tables/JSON to stdout.

Operations return () and print directly; there are no typed models (raw serde_json::Value throughout). A consumer crate that wants "list labels" gets printed text, not Vec<Label>. The only reuse paths available are shelling out to the CLI or reimplementing the API layer.

Proposed solution

A Cargo workspace with two crates:

• gor-core — publishable library: Client, auth, host, config, repository detection, keyring, error types, and one module per GitHub domain holding both its lean typed model and its typed operations. No CLI dependencies.
• gor — binary: clap definitions, rendering (tables + JSON), and thin handlers that resolve args → call a gor-core op → render.

Locked decisions

Axis	Decision
Reuse target	Typed operations returning models, not just a raw client
Packaging	Cargo workspace: gor-core (lib) + gor (bin)
Scope	Everything — all 24 command domains converted
Model fidelity	Lean structs: hand-written fields gor uses + #[serde(flatten)] extra capture-rest

Dependency split

gor-core keeps: reqwest, serde, serde_json, serde_yaml_ng, keyring (optional), thiserror, dirs, gix, tracing.

gor-core drops (they move to the gor bin): clap, clap_complete, indicatif, console, anyhow.

Reusable pattern (per domain)

#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Label {
    pub name: String,
    pub color: String,
    pub description: Option<String>,
    #[serde(flatten)]
    pub extra: serde_json::Map<String, serde_json::Value>, // capture-rest
}

pub fn list(client: &Client, spec: &RepoSplit, opts: &ListOptions)
    -> Result<Vec<Label>, GorError>;

Consumer usage:

let client = gor_core::client::Client::new("github.com")?;
let spec = gor_core::repository::parse_repo_spec("owner/repo")?;
let labels = gor_core::label::list(&client, &spec, &Default::default())?;

Rules: ops return Result<T, GorError> (never anyhow, never print); status→error mapping (404 → NotFound, etc.) lives in the op; models are #[non_exhaustive] + capture-rest so API additions don't break consumers.

Stays bin-only (no reusable API surface)

completion, alias, browse, extension, config (wraps gor_core::config), interactive auth prompting (token exchange itself moves to core), and api (thin raw-request passthrough).

Migration plan

1. Create the workspace; move shared core files into crates/gor-core, move cli.rs / output.rs (→ render.rs) / main.rs / cmd/ into crates/gor. Compile green, no behavior change.
2. Convert label end to end as the template.
3. Convert the remaining 23 domains one at a time — each independently reviewable, build never breaking.
4. Delete dead helpers left in the bin.

Testing

• Existing CLI integration tests (assert_cmd, insta) are the safety net — CLI behavior/output must not change.
• Add per-op unit tests against wiremock asserting typed data and correct GorError variant mapping.
• Doctests on public gor-core items (crate keeps #![deny(missing_docs)]).

Non-goals

• No new commands or features.
• No change to CLI flags, output format, or config format.
• No async conversion — stays reqwest::blocking.
• No full faithful GitHub models (every documented field) — lean structs + capture-rest instead.

Notes / open questions

• #![deny(missing_docs)] + unwrap_used = "deny" carry into gor-core — every public model field/op needs docs. Real cost, sequenced per-domain.
• Library crate name gor-core assumed; open to alternatives.

---

Full design spec committed on branch refactor/split-core-library at docs/superpowers/specs/2026-07-20-core-library-split-design.md.

[kerryhatcher]

Implementation Plan: Split gor into gor-core + gor CLI

This implements the refactor described above. It's a behavior-preserving restructuring — no CLI flag, output, or config changes. The safety net is the existing assert_cmd/insta integration tests, which must stay green throughout.

---

Current state (grounding)

• Single crate gor-cli (lib gor), workspace already declared with members = ["."].
• lib.rs exposes only Gor::run() — parse args + dispatch. Every cmd/*.rs entangles clap structs + API calls + serde_json::Value + stdout printing.
• Core infra (client.rs, error.rs, host.rs, config.rs, keyring_store.rs, repository.rs) is already cleanly typed (GorError, Client, Host, RepoSplit) — these move almost verbatim to core.
• 27 command domains, ~13K lines in cmd/. label.rs (586 LOC, 5 subcommands: list/create/edit/delete/clone) is the designated template.
• The refactor/split-core-library branch and design spec do not exist yet on the remote — they're referenced as a future commit. This plan supersedes that.

---

Phase 0 — Setup & branch (no behavior change)

1. Create branch refactor/split-core-library from main.
2. Create the design spec at docs/superpowers/specs/2026-07-20-core-library-split-design.md (commit the issue's locked decisions verbatim).
3. Record an ADR (adrs new --no-edit "Split gor into gor-core library and gor CLI") capturing the workspace/typed-ops/capture-rest decisions, status accepted.

Phase 1 — Workspace skeleton, compile green (the "move" step)

Goal: two crates, identical behavior, gor binary depends on gor-core.

1. Restructure to crates/gor-core/ and crates/gor/; root Cargo.toml becomes a pure workspace with members = ["crates/*"].
2. crates/gor-core/Cargo.toml — lib, name = "gor-core", keeps: reqwest, serde, serde_json, serde_yaml_ng, keyring (optional), thiserror, dirs, gix, tracing. Inherits workspace lints incl. #![deny(missing_docs)] + unwrap_used = "deny".
3. crates/gor/Cargo.toml — bin gor, depends on gor-core = { path = "../gor-core" }, keeps: clap, clap_complete, indicatif, console, anyhow, miette, tracing-subscriber.
4. Move as-is into gor-core/src/: client.rs, host.rs, config.rs, keyring_store.rs, repository.rs, error.rs, auth/ (device flow + token verification — token exchange is core; interactive prompting stays bin-side). Move into gor/src/: cli.rs, output.rs→render.rs, main.rs, cmd/.
5. gor-core/src/lib.rs: re-export client, host, config, repository, error, auth, keyring_store. Add pub use client::Client; pub use error::GorError; pub use repository::RepoSplit;.
6. gor/src/lib.rs: keep Gor (dispatch only), now use gor_core::*. Update all crate::client::Client → gor_core::client::Client (etc.) across cmd/.
7. Update workspace cargo-shear ignored list, deny.toml, _typos.toml paths if needed.
8. Gate: just ci green, all existing tests pass, gor --help snapshots unchanged. Commit build: split workspace into gor-core + gor crates.

Phase 2 — Template domain: label (end-to-end proof of pattern)

This proves the per-domain conversion pattern. Do it carefully; it becomes the template for the other 23.

1. crates/gor-core/src/label.rs — new module:
   • pub struct Label (#[non_exhaustive], #[derive(Debug, Clone, Serialize, Deserialize)]): name, color, description: Option<String>, #[serde(flatten)] extra: serde_json::Map.
   • pub struct ListOptions { search: Option<String>, limit: u32 } + Default.
   • pub fn list(client: &Client, spec: &RepoSplit, opts: &ListOptions) -> Result<Vec<Label>, GorError> — moves the API call + status→error mapping (404→NotFound, non-2xx→Auth/InvalidInput). Client-side search/truncate moves here (operates on typed Label).
   • pub fn create(...) -> Result<Label, GorError>, update(...), delete(...), clone_from(...) — each returns the typed model or (); status mapping in-op.
2. Tests in gor-core: #[cfg(test)] with wiremock — assert typed Vec<Label> and correct GorError variant for 404/422/429. Doctests on public items.
3. crates/gor/src/cmd/label.rs — thin handler: resolve args (repo detect, hostname) → call gor_core::label::* → render::* (table/JSON). Confirmation prompts for delete stay here. print_json field-selection stays bin-side (operates on the model serialized via serde_json::to_value).
4. Gate: just ci green; gor label list/create/edit/delete/clone output byte-identical (insta snapshots + assert_cmd). Commit refactor(label): extract typed ops into gor-core.

Phase 3 — Convert remaining 23 domains (one PR each, build never breaks)

Order follows the issue's dependency chain (auth → list → view → mutate) and sizes (smallest first to build momentum):

Batch	Domains (LOC)	Notes
3a — small leaf ops	browse, attestation, extension, classroom, config(bin wrapper), copilot, ruleset, alias, cache	browse/completion/extension/alias/config stay bin-only (per issue) — just verify they don't grow a core API surface.
3b — medium	org, secret, variable, keys, search, workflow, project	Each: typed model + ops in core, thin handler in bin.
3c — large	gist, run, codespace, api	api stays bin-only passthrough (raw request).
3d — largest	release, repo, issue, pr	pr.rs is 2236 LOC — split into multiple core submodules if needed (pr::list, pr::view, pr::merge...).

Per-domain checklist (paste into each PR):

• Core module with #[non_exhaustive] models + capture-rest extra.
• Ops return Result<T, GorError>, status→error mapping in-op.
• wiremock unit tests for happy path + each error variant.
• Doctests on public items.
• Bin handler thinned to args→op→render; no serde_json::Value indexing, no anyhow in core.
• just ci green; integration snapshots unchanged.

Phase 4 — Cleanup & publishability

1. Delete dead bin helpers (e.g. urlencoding in label.rs → use a shared gor_core::util or urlencoding crate; truncate moves to render).
2. Move shared pagination/field-selection into gor_core::util (currently cmd/util.rs is only 50 LOC, mostly truncate).
3. Audit gor-core for any remaining anyhow/print_stdout/console/indicatif usage — must be zero.
4. gor-core metadata: description, keywords, categories = ["api-bindings", "web-programming::http-client"], documentation = "https://docs.rs/gor-core".
5. Verify #![deny(missing_docs)] + unwrap_used = "deny" pass across all core public items.
6. cargo doc --no-deps -p gor-core clean.
7. Final just ci. Commit chore: finalize gor-core for publishing.

Phase 5 — Merge & release

1. Open PR refactor/split-core-library → main, referencing closes #2.
2. After merge: release-plz publishes gor-core 0.1.0 + bumped gor-cli. Update README usage section with the consumer example from the issue.

---

Risks & mitigations

• Behavior drift on large domains (pr, issue, release, repo). Mitigation: insta snapshots locked before conversion; any diff halts the PR. Keep bin handler as a near-mechanical move first, then extract.
• #[non_exhaustive] + missing_docs cost. Real per-field documentation burden. Mitigation: sequenced per-domain (Phase 3), not a big-bang.
• keyring feature propagation. gor-core carries keyring as optional feature; gor bin forwards keyring = ["gor-core/keyring"].
• env!("CARGO_PKG_VERSION") in Client user-agent now reports gor-core's version — acceptable, or inject version at call site.
• api command stays bin-only (raw passthrough) per issue — don't over-engineer it.

Estimating effort

Phase 1 is a half-day of mechanical moves. Phase 2 (label template) is a focused session — the pattern is the deliverable. Phase 3 is the bulk: 23 domains, but each is independent and reviewable. Phase 4–5 are light. The whole thing is tractable as a sequence of small PRs, which is exactly the issue's stated constraint ("each independently reviewable, build never breaking").

[kerryhatcher]

Progress Update — Phase 3 in progress

✅ Completed (9 domains converted)

Domain	Phase	Status
label	2	✅
cache	3a	✅
org	3b	✅
secret	3b	✅
variable	3b	✅
project	3b	✅
keys	3b	✅
search	3b	✅
workflow	3b	✅

🔜 Remaining (7 domains)

3c: gist, run, codespace
3d: release, repo, issue, pr

📄 Handoff Document

A detailed handoff document covering the conversion pattern, all lint constraints, file structure, and everything needed to complete the remaining work is available on the branch:

👉 HANDOFF.md

Key links

• Branch:
• Draft PR: #3
• Design spec: docs/superpowers/specs/2026-07-20-core-library-split-design.md