Skip to content

platform: decide how non-Python CLIs obtain the base-cli lifecycle #382

Description

@codeforester

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/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:

  1. 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.
  2. Thin per-language SDKs over a frozen spec. Publish the run-bundle layout, run.json schema,
    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.
  3. 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

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or product improvement

Type

No type

Projects

  • Status
    Backlog

Relationships

None yet

Development

No branches or pull requests

Issue actions