feat(clitree): new package - command-tree-to-JSON walker; export passthrough Usage prefix #95

New issue

Closed

opened 2026-06-07 04:07:41 +00:00 by coilysiren · 1 comment

coilysiren commented

2026-06-07 04:07:41 +00:00

Owner

Extraction candidate from the coily cmd/coily/ generic-code audit (2026-06-06). Source pinned at coily commit c7c17cb (canonical: forgejo.coilysiren.me/coilyco-bridge/coily). cli-guard is mid-refactor, so the "suggested home" below is the pre-refactor package layout - land this in whatever the post-refactor equivalent is, not necessarily the named package. The durable principle: the classifiers / argv-transforms are generic and move; the policy decisions and message copy stay in coily.

Source: cmd/coily/tree_json.go - treeNode, the tree walker, parseTreeJSONRequest, and a duplicated const passthroughUsagePrefix = "Pass-through to ".

What it does: walks a urfave/cli v3 command tree into a serializable treeNode (skips hidden and help), tags passthrough leaves with their underlying binary by sniffing the Usage prefix, supports subtree pathing, and emits indented JSON. Includes a leading-only --tree --json [path] argv guard that refuses to hijack a passthrough's verbatim argv.

Companion fix (do this as part of the issue): tree_json.go re-declares passthroughUsagePrefix and keeps it in sync with passthrough.Command's stamp via a guard test (TestPassthroughUsagePrefixMatchesCLIGuard). Export that constant from passthrough and consume it here - kills the cross-repo drift seam outright.

Consumer seams to parameterize: the synthetic root name ("coily") -> rootName string; accept a single []*cli.Command (or a root *cli.Command) instead of coily's builtIns/exec split. The unused repoExecResult arg drops out.

Suggested home (pre-refactor): new clitree package, paired with passthrough.

Done when:

generic logic lives in cli-guard with zero coily/Kai/Forgejo identifiers or defaults
behavior-covered tests (table tests where the source has them)
godoc-current.txt regenerated (scripts/check-godoc-current.sh --update)
coily migrated onto the extracted API, its local copy deleted, make test green both sides
closes this issue

Related: unblocks the capability-index renderer in cli-guard#100 (it walks the same treeNode).

> Extraction candidate from the coily `cmd/coily/` generic-code audit (2026-06-06). Source pinned at coily commit `c7c17cb` (canonical: `forgejo.coilysiren.me/coilyco-bridge/coily`). **cli-guard is mid-refactor**, so the "suggested home" below is the pre-refactor package layout - land this in whatever the post-refactor equivalent is, not necessarily the named package. The durable principle: **the classifiers / argv-transforms are generic and move; the policy decisions and message copy stay in coily.** **Source:** `cmd/coily/tree_json.go` - `treeNode`, the tree walker, `parseTreeJSONRequest`, and a **duplicated** const `passthroughUsagePrefix = "Pass-through to "`. **What it does:** walks a urfave/cli v3 command tree into a serializable `treeNode` (skips hidden and `help`), tags passthrough leaves with their underlying binary by sniffing the Usage prefix, supports subtree pathing, and emits indented JSON. Includes a leading-only `--tree --json [path]` argv guard that refuses to hijack a passthrough's verbatim argv. **Companion fix (do this as part of the issue):** `tree_json.go` re-declares `passthroughUsagePrefix` and keeps it in sync with `passthrough.Command`'s stamp via a guard test (`TestPassthroughUsagePrefixMatchesCLIGuard`). **Export that constant from `passthrough`** and consume it here - kills the cross-repo drift seam outright. **Consumer seams to parameterize:** the synthetic root name (`"coily"`) -> `rootName string`; accept a single `[]*cli.Command` (or a root `*cli.Command`) instead of coily's `builtIns`/`exec` split. The unused `repoExecResult` arg drops out. **Suggested home (pre-refactor):** new `clitree` package, paired with `passthrough`. **Done when:** - [ ] generic logic lives in cli-guard with zero coily/Kai/Forgejo identifiers or defaults - [ ] behavior-covered tests (table tests where the source has them) - [ ] `godoc-current.txt` regenerated (`scripts/check-godoc-current.sh --update`) - [ ] coily migrated onto the extracted API, its local copy deleted, `make test` green both sides - [ ] `closes` this issue **Related:** unblocks the capability-index renderer in cli-guard#100 (it walks the same `treeNode`).

coilysiren added the

label

2026-06-17 07:05:01 +00:00

coilysiren commented

2026-06-17 08:23:23 +00:00

Author

Owner

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: burndown-2026-06.

Backlog burndown 2026-06-17: closing low-priority (P3/P4) to bring the open count to a manageable level. Nothing lost — reopen if this resurfaces. Batch tag: `burndown-2026-06`.

coilysiren

2026-06-17 08:23:23 +00:00