You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Decide and document how a CLI that is not written in Python obtains base-cli's lifecycle
guarantees, or state explicitly that it cannot and that the platform's scope is
contract-and-conformance only.
Background
The [platform] roadmap (#274 contract, #275 spec artifact, #276 conformance runner, #277 catalog) is coherent and covers describing and verifying CLIs written in any language.
None of it provides anything to a non-Python CLI. Today a Go, Rust, Node, JVM, or .NET CLI can be
conformance-tested against cli-platform/v1 but gets zero base-cli functionality, because every
behaviour that constitutes the product's value proposition lives in Python-only modules:
Capability
Implementation
Reusable outside Python?
Run bundles, run IDs, run.json lifecycle metadata
_runtime.py, _lifecycle.py
No
Retention policy for bundles (count/age/bytes, leases)
_runtime.py
No
Layered config with per-key provenance
config.py
No
Click-aware argv redaction
redaction.py
No — depends on the Click parse tree
Structured/JSON logging, secure log files
logging.py
No
Temp ownership and audited recursive cleanup
_cleanup.py
No
Extension discovery
extensions.py
No — importlib entry points
Versioned JSON/NDJSON envelopes
json_contracts.py, output.py
Yes, as a wire format
COMMAND_PROTOCOL_V1 record framing
command_protocol.py
Yes, by design
So of nine capabilities, two are language-neutral and both are only serialization formats. The
stated positioning — "the production lifecycle layer" — remains Python-only while the platform
vision is language-neutral. That gap is currently unowned by any issue.
Adjacent evidence that the seam was intended to exist: command_protocol.py explicitly tunes its
framing so "the Python decoder [is not] more permissive than the Bash and Zsh readers"
(lib/python/base_cli/command_protocol.py:202-206), and base-bash-libs is a sibling repo. The
cross-language intent is real but stops at record framing.
Scope
Produce an architecture decision that picks one of these, with the reasoning recorded:
Sidecar / wrapper runtime. A small executable (base-run <cli> [args...]) that owns the
lifecycle around an arbitrary child process: allocates the run bundle and run ID, exports the
propagation environment (see the companion run-identity issue), captures and frames child
stdout/stderr, writes run.json, applies retention, and redacts argv from a declarative
sensitivity spec rather than a Click parse tree. Language-neutral by construction; the child
needs no SDK. Costs: argv redaction without a parse tree is weaker, and the child cannot use Context directly.
Explicitly Python-only lifecycle. Keep the runtime Python-only and narrow the platform's
promise to contract, spec, conformance, and catalog. Then say so plainly in README.md, docs/index.md, and docs/framework-choice.md so an evaluating platform team is not misled by
"CLI platform" framing.
Option 3 is a legitimate answer and is cheap; what is not acceptable is leaving it implicit.
Acceptance criteria
One ADR names the chosen option, the rejected options, and the reasoning.
Review with at least one owner of a non-Python CLI; have them state which of the nine capabilities
above they would actually adopt through the chosen mechanism.
Non-goals
Do not add a Go/Rust/Node runtime to this repository.
Do not reimplement Click-aware redaction outside Python.
Goal
Decide and document how a CLI that is not written in Python obtains base-cli's lifecycle
guarantees, or state explicitly that it cannot and that the platform's scope is
contract-and-conformance only.
Background
The
[platform]roadmap (#274 contract, #275 spec artifact, #276 conformance runner,#277 catalog) is coherent and covers describing and verifying CLIs written in any language.
None of it provides anything to a non-Python CLI. Today a Go, Rust, Node, JVM, or .NET CLI can be
conformance-tested against
cli-platform/v1but gets zero base-cli functionality, because everybehaviour that constitutes the product's value proposition lives in Python-only modules:
run.jsonlifecycle metadata_runtime.py,_lifecycle.py_runtime.pyconfig.pyredaction.pylogging.py_cleanup.pyextensions.pyjson_contracts.py,output.pyCOMMAND_PROTOCOL_V1record framingcommand_protocol.pySo of nine capabilities, two are language-neutral and both are only serialization formats. The
stated positioning — "the production lifecycle layer" — remains Python-only while the platform
vision is language-neutral. That gap is currently unowned by any issue.
Adjacent evidence that the seam was intended to exist:
command_protocol.pyexplicitly tunes itsframing so "the Python decoder [is not] more permissive than the Bash and Zsh readers"
(
lib/python/base_cli/command_protocol.py:202-206), andbase-bash-libsis a sibling repo. Thecross-language intent is real but stops at record framing.
Scope
Produce an architecture decision that picks one of these, with the reasoning recorded:
base-run <cli> [args...]) that owns thelifecycle around an arbitrary child process: allocates the run bundle and run ID, exports the
propagation environment (see the companion run-identity issue), captures and frames child
stdout/stderr, writes
run.json, applies retention, and redacts argv from a declarativesensitivity spec rather than a Click parse tree. Language-neutral by construction; the child
needs no SDK. Costs: argv redaction without a parse tree is weaker, and the child cannot use
Contextdirectly.run.jsonschema,config precedence/provenance rules, and log record schema as normative specifications
([platform] Reconcile and freeze the cli-platform/v1 behavioral contract #274/[platform] Publish a portable inspectable CLI specification artifact #275), then implement small libraries per language. Highest fidelity, highest cost, and it
multiplies the bus-factor-1 problem this repo already documents.
promise to contract, spec, conformance, and catalog. Then say so plainly in
README.md,docs/index.md, anddocs/framework-choice.mdso an evaluating platform team is not misled by"CLI platform" framing.
Option 3 is a legitimate answer and is cheap; what is not acceptable is leaving it implicit.
Acceptance criteria
run.jsonvalidates against the same schema a Python consumer produces, plus theconformance-runner evidence from [platform] Build a language-neutral black-box CLI conformance runner #276.
README.md,docs/index.md, anddocs/framework-choice.mdstate the language boundarywithout hedging, and [platform] Reconcile and freeze the cli-platform/v1 behavioral contract #274-[platform] Define signed CLI Catalog ingestion and governance boundaries #277 are re-scoped in their own text to "contract and conformance,
not runtime".
run.jsonschema are published as versioned specifications underdocs/schemas/in every option, since [platform] Publish a portable inspectable CLI specification artifact #275 and [platform] Build a language-neutral black-box CLI conformance runner #276 already depend on them being normative.Validation
Review with at least one owner of a non-Python CLI; have them state which of the nine capabilities
above they would actually adopt through the chosen mechanism.
Non-goals