docs: explain the value Base-CLI adds to a consumer - #31
Conversation
| while the consumer keeps its command tree, configuration policy, and domain | ||
| behavior. | ||
|
|
||
| | Shared concern | Northstar example | What the framework supplies | |
There was a problem hiding this comment.
Content-completeness gap vs. the linked issue. Issue #18's suggested fix asked for a concrete before/after of cli.py: "the ~30 lines of cli.py that produce a production-shaped CLI, annotated to mark which behavior would otherwise be hand-written" (or at minimum a "without base-cli you would also write ..." callout). This table lists Northstar examples and framework capabilities in the abstract, but never ties a specific behavior to the lines of cli.py/profile.py a reader would otherwise have had to write themselves (e.g. log setup, temp/state path plumbing, redaction wiring, envelope serialization). A reader still can't tell, line-by-line, which parts of cli.py represent effort base-cli is saving them versus ordinary Click code — the specific gap the issue called out.
| | Diagnostics | `--debug --log-file ... release reconcile` | Lifecycle logging, log placement, and registered sensitive-argument redaction. | | ||
| | Per-run files and cleanup | `release reconcile` | Managed runtime/temp paths and cleanup hooks; Northstar owns its state record. | | ||
|
|
||
| ## What this demo still owns |
There was a problem hiding this comment.
Duplication risk with README's existing "Framework boundary" section. README.md:66-72 (unchanged by this PR) already states: "Base-CLI owns the invocation lifecycle, context, logging, runtime paths, cleanup, and structured output. Northstar owns the Click command tree, service fixture schema, release planning policy, and domain-facing messages." This "What this demo still owns" section restates the same ownership boundary in different words, with no cross-reference between the two. The two descriptions can now drift out of sync as the codebase evolves (e.g. if a new lifecycle option or consumer-owned setting is added, only one of the two places is likely to get updated). Consider having one of the two sections link to the other as the source of truth, or trimming this section to defer to the existing "Framework boundary" write-up.
| | Human and machine output | `northstar status --format json` | Public record renderers and stable JSON records. | | ||
| | Automation envelope | `northstar --json status --format json` | A versioned success/error envelope and the command's exit status. | | ||
| | Safe state-changing workflow | `northstar --dry-run release reconcile` | A lifecycle dry-run flag and consistent invocation context; Northstar decides what its local demo operation means. | | ||
| | Diagnostics | `--debug --log-file ... release reconcile` | Lifecycle logging, log placement, and registered sensitive-argument redaction. | |
There was a problem hiding this comment.
Minor inconsistency: this row's example command, --debug --log-file ... release reconcile, omits the northstar prefix present in every sibling row (northstar status --format json, northstar --json status --format json, northstar --dry-run release reconcile). Worth prefixing with northstar for consistency, e.g. northstar --debug --log-file ... release reconcile.
1 participant
Fixes #18