feat(exitcode): error-envelope emitter companion (stable YAML failure contract) #99

New issue

Closed

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

coilysiren commented

2026-06-07 04:07:44 +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/main.go - classifyExit, emitErrorEnvelope, kindFor/reasonFor, plus the ExitErrHandler no-op idiom. Driven by the already-extracted exitcode package.

What it does: walks exitcode.From, falls back to UpstreamFailed for *exec.ExitError, and renders the stable YAML failure envelope (kind/hint/reason/exit_code/audit_log_path) documented in coily SECURITY.md. Reimplemented per consumer today.

Also lift: the ExitErrHandler no-op + bubble-to-main idiom, needed so coded-exit handling isn't short-circuited by urfave's default os.Exit(1).

Consumer seams to parameterize: app name, the audit-log-path accessor, any consumer-specific hint text. Candidate API: exitcode.EmitEnvelope(w, err, auditPath) + a small ExitErrHandler helper.

Suggested home (pre-refactor): the exitcode package, as its top-half (rendering) companion.

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

Note: this is the rendering counterpart to cli-guard#2 (WithReason at deny sites) - together they make the failure contract fully upstream-owned.

> 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/main.go` - `classifyExit`, `emitErrorEnvelope`, `kindFor`/`reasonFor`, plus the `ExitErrHandler` no-op idiom. Driven by the already-extracted `exitcode` package. **What it does:** walks `exitcode.From`, falls back to `UpstreamFailed` for `*exec.ExitError`, and renders the stable YAML failure envelope (`kind`/`hint`/`reason`/`exit_code`/`audit_log_path`) documented in coily SECURITY.md. Reimplemented per consumer today. **Also lift:** the `ExitErrHandler` no-op + bubble-to-main idiom, needed so coded-exit handling isn't short-circuited by urfave's default `os.Exit(1)`. **Consumer seams to parameterize:** app name, the audit-log-path accessor, any consumer-specific `hint` text. Candidate API: `exitcode.EmitEnvelope(w, err, auditPath)` + a small `ExitErrHandler` helper. **Suggested home (pre-refactor):** the `exitcode` package, as its top-half (rendering) companion. **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 **Note:** this is the rendering counterpart to cli-guard#2 (WithReason at deny sites) - together they make the failure contract fully upstream-owned.

coilysiren added the

label

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

coilysiren commented

2026-06-17 08:23:21 +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:21 +00:00