Evaluate upgrade to Restish v2

[apgiorgi]

Restish — the library dci is built on — was redesigned in a major way (v2.0.0). We're currently pinned to v0.21.2 and will need to decide whether/when to move.

This issue tracks an evaluation of that upgrade:

• Feasibility — is it a dependency bump or something larger?
• What needs to be done — concrete work to move to v2.
• What's superseded or redundant — which parts of our code the redesign makes obsolete.
• How to do it cleanly — the lowest-risk path, if we move at all.

Analysis posted as a comment below.

[apgiorgi]

Evaluation

(Claude Code)

Headline: this is not a dependency upgrade — it's a rewrite. And "we'll need to update eventually" deserves scrutiny, because the cost is high and the forcing function is weak:

• We're on v0.21.2, which is the CVE-2025-22868 security patch. We are not sitting on a known vuln.
• The redesign is v2.0.0 (May 2026), and it didn't evolve the library API — it deleted it.

Why it's a rewrite, not a bump

dci-cli's entire architecture is "import restish as a Go library, manipulate its cobra tree, call cli.Run()." Every restish symbol we use now lives in packages that no longer exist publicly in v2:

What we import today	Status in v2
restish/cli (Init, Defaults, AddLoader, AddAuth, Load, Run, Root, Cache, Stdout, GetLastStatus, GetExitCode, AddContentType)	Moved to internal/cli — unimportable
restish/oauth (AuthorizationCodeHandler)	Moved to internal/auth — unimportable
restish/openapi (New)	Moved to internal/openapi — unimportable

The only public Go package in v2 is restish/v2/plugin. Go forbids importing internal/ from another module, so go get .../v2 + fixing imports is physically impossible — there is nothing to import.

The extension model inverted. v1: we are the binary, restish is our library. v2: restish is the binary, and you extend it with out-of-process plugin executables named restish-<name> that speak CBOR over stdin/stdout (hook plugins for auth/loader/middleware/formatter, command plugins, TLS signers). That's backwards from how dci-cli is built.

What in our code is superseded / has no v2 equivalent

Most of main.go exists only to bend restish's in-process cobra tree. None of it survives, because in v2 we don't own the root command:

• Branding + usage template (brandRootCommand, dciUsageTemplate, applyCommandBranding) — manipulates cli.Root. Gone.
• Command lockdown (RemoveCommand on cli.Root) — gone; v2 controls surfaced ops via its typed JSONC config.
• The completion / ValidArgsFunction workaround (~lines 577–669) — exists purely to fight v1's lazy os.Args-based loading. v2 generates commands differently; the whole chapter is moot.
• API-key bearer injection (applyAPIKeyAuth poking cli.Cache) — superseded by v2's own secret store; becomes config/env or an auth hook plugin.
• Custom customer-context file — v2.1.0 added "trusted project config" + typed profiles, which may finally make the custom file unnecessary.
• Table content type (dciTableContentType + AddContentType) — becomes a formatter hook plugin (separate restish-table executable).
• Doer-context hints (maybeHintDoerContext via GetLastStatus) — becomes wrapper logic.

Carries over cleanly: the embedded skills/dci-cli (ours, unrelated to restish), the DCI API base + OAuth endpoint values (re-expressed in v2 config format), and the onboarding flow concept.

Options

1. Stay on v0.21.2 (recommended default). It works, it's CVE-patched, and the single-file wrapper model is exactly what v2 removed. "Eventually" only becomes real if a new CVE lands in v0.21.x with no backport, or we specifically want a v2 feature (page-param pagination, body validation, JSONC config). Until then, upgrading is negative ROI.
2. Re-architect as a v2 wrapper. dci becomes a thin launcher shipping the v2 restish binary + a generated apis.jsonc + DCI plugins (restish-table formatter, an auth hook). Ground-up rewrite, multi-week; trades a self-contained file for a binary + config + N plugin processes. The lockdown/branding UX largely can't be reproduced.
3. Fork. Pin a fork and un-internal/ the packages we need. Lowest rewrite cost, but we own a fork of an actively-moving project forever.

Recommendation

Don't upgrade now. The redesign removed exactly the capability dci-cli is built on, there's no security pressure to move, and the rewrite is large with real UX regressions.

Set a trigger instead: revisit only if a v0.21.x CVE goes unpatched, or a concrete v2 feature becomes a requirement. When that happens, the path is Option 2 (wrapper + plugins), starting by reproducing just OpenAPI loading + OAuth in raw v2 config to validate the auth flow before touching output/branding.

[apgiorgi]

Benefit / cost analysis for our needs

(Claude Code)

For a locked-down, single-API, table-first wrapper, almost everything v2 added targets use cases we deliberately don't have (multi-API config, extensibility, ad-hoc REST exploration). The genuine upside is narrow.

Benefits that could matter to us

v2 feature	Relevant to dci?	Verdict
Page-parameter pagination (?page=N, v2.1.0)	No — see check below	DCI uses token pagination, not page numbers. Doesn't apply.
Authenticated OpenAPI discovery (v2.1.1)	Maybe	Minor; we fetch the spec fine today.
Dependency modernization (cobra 1.10, new yaml, msgpack v3, x/net 0.50, …)	Yes, slow-burn	Real but gradual — see "what we lose".
Body validation (--rsh-validate)	Barely	Marginal; matters for write-heavy APIs.
Typed JSONC config	No	Internal nicety; lockdown hides config from users.
MCP plugin (restish-mcp)	Redundant	DoiT already ships dedicated DCI MCP servers.
Out-of-process plugins (CSV/bulk/PKCS#11)	No	This is the cost of v2 for us — the feature that deleted our embedding model.

Upside collapses to: dependency freshness, plus maybe pagination — which we checked.

Pagination check (the one item that could have flipped this)

Fetched the live DCI spec from https://api.doit.com/openapi.yaml (DoiT API v1) and analyzed pagination:

• Request params: pageToken and maxResults (plus a few offset/limit).
• Response fields: pageToken (34×), rowCount (21×).

DCI uses token / cursor pagination (pageToken echoed from response into the next request) — not page-number (?page=N) pagination. v2.1.0's pagination feature is specifically for page numbers, so it does not apply to DCI. restish auto-pagination — v1 link-header or v2 page-param — fits neither scheme; users pass pageToken manually in both v0.21.2 and v2. No pagination win from upgrading.

What we lose by staying on v0.21.2

• Dependency / security drift — the only concrete, compounding loss. v0.21.2 pins old cobra/pflag/yaml/x/net; v0.21.x is a dead branch with no backports. Transitive CVEs will accumulate over time. This, not feature envy, is what eventually forces a move.
• No automatic new features — anything upstream adds, we'd reimplement ourselves if wanted.
• Divergence from upstream — docs/examples/community move to v2; we maintain against a snapshot.

Net

The pagination check came back negative, so the benefit/cost is even more lopsided than first thought: a full rewrite buys us essentially only dependency freshness, with MCP and plugins either redundant or actively counter to our model. The real forcing function remains transitive-dependency CVE drift — which is a "watch and patch deps" problem long before it's a "rewrite onto v2" problem. Recommendation stands: don't upgrade now.