Post-1.0: clet/cli agent-discoverability alignment

[tig]

Tracks workstream E / checklist item 7 in PLAN.md. North star — not blocking 1.0.

Bring ocgv/shot into line with the tui-cs clet / cli family so they're usable by AI agents, not just humans at a pipeline.

Ideas

• Expose the grid/tree pickers through the cli agent-discoverability layer.
• Add clet-style JSON-out + clean exit-code modes (envelope {"schemaVersion":1,"status":"ok","value":...}; exit codes 0/1/2/130).
• Evaluate an --opencli-style manifest for agent discovery.

Design discussion welcome.

[tig]

Design proposal — bringing ocgv/shot onto the clet/cli contract

Sketch for workstream E. Post-1.0, non-blocking. Goal: make the grid/tree pickers first-class to AI agents, not just humans at a pipeline, using the same contract as clet and the Terminal.Gui.Cli library.

The core tension

clet and cli are standalone CLI binaries: they emit a JSON envelope on stdout and signal outcome via the process exit code. ocgv/shot are PowerShell cmdlets: they emit objects to the pipeline, and PowerShell — not the cmdlet — owns serialization (| ConvertTo-Json) and process exit. There is no per-cmdlet process exit code.

So "add clet-style JSON-out + exit codes" doesn't map 1:1. There are really two distinct consumption models, and we should serve both deliberately:

	In-PowerShell agent (drives pwsh)	Cross-process agent (no PowerShell)
Today	ocgv returns objects → | ConvertTo-Json already works	nothing — must spin up pwsh, import module, marshal
Want	opt-in envelope + status so cancel ≠ empty selection	a thin native pstui CLI speaking the clet contract

Gap that bites agents today

OutConsoleGridViewCmdletCommand.EndProcessing() writes selected objects via WriteObject. On Esc/cancel the window calls RequestStop with no accepted result, so zero objects are written — which is identical to "accepted, selected nothing." An agent cannot tell cancelled from empty. clet solves this with explicit status: "cancelled" (exit 130). This is the single most valuable thing to fix, and it's independent of any CLI work.

Proposed contract mapping

Adopt clet's envelope verbatim so agents reuse one parser across the family:

{ "schemaVersion": 1, "status": "ok",        "value": [ ...selected objects... ] } // exit 0
{ "schemaVersion": 1, "status": "no-result", "value": [] }                          // exit 1  (accepted, empty)
{ "schemaVersion": 1, "status": "cancelled" }                                       // exit 130 (Esc/Ctrl-C/-timeout)
{ "schemaVersion": 1, "status": "error", "code": "usage", "message": "…" }           // exit 2

value shape keys off the existing OutputModeOption:

• Single → scalar (the one selected object)
• Multiple → array
• None → viewer semantics: { "status": "ok" } with no value (matches clet's "browser clets")

shot is a viewer today (no selection contract); aligning it mainly means a discoverable manifest + status: ok/cancelled on dismiss, optionally a future "return selected node path" mode.

Per-idea breakdown (the three checkboxes)

1. Expose pickers through the cli layer. Terminal.Gui.Cli already turns Terminal.Gui Views into scriptable CLI commands with typed JSON output + POSIX exit codes + --opencli. The v2 rewrite gave us reusable OutGridViewWindow/ShowObjectTreeWindow classes — the natural move is a small pstui host exe that registers these Views as cli commands (pstui grid …, pstui tree …). This is the cleanest path for cross-process agents and gets --opencli essentially for free.

2. clet-style JSON-out + exit codes. Lands in two independent pieces:

• Cmdlet side (cheap, high value): add an opt-in -AsJson/-OutputJson (and maybe -Timeout) switch that emits the envelope above as a single string and, crucially, distinguishes cancel from empty. No process-exit change — PowerShell agents read status.
• CLI side: the pstui host maps status → process exit codes 0/1/2/130 per clet.

3. --opencli manifest. Comes with the cli integration. Manifest entries describe each picker ({"alias":"grid","kind":"input","resultType":"object[]", "options":[…]}), so an agent can discover params (-Filter, -FullScreen, -Search, -Focus, -AllProperties, OutputMode) without docs.

Suggested phasing

1. Envelope + cancel/no-result distinction in the cmdlets (-AsJson, -Timeout). Self-contained, useful immediately, no new project. Biggest bang for buck.
2. pstui CLI host on Terminal.Gui.Cli wrapping the existing Window classes → exit codes + --opencli.
3. Optional: shot "return selected node" mode for symmetry with select/grid.

Open questions

• Naming for non-PS agents: keep ocgv/shot aliases inside PowerShell (per the PLAN's stable-contract rule), but pick clet-family verbs for the CLI host — pstui grid/pstui tree, or select/pick to mirror clet?
• Where does the envelope live? A shared helper in PSTui.Models so cmdlet and CLI host produce byte-identical JSON.
• -Timeout: clet has --timeout 30s for unattended agent runs. Worth adding to the cmdlets too (cancel → status: cancelled).
• Dependency cost: does taking Terminal.Gui.Cli pull anything that complicates the in-process PowerShell binary module load (TFM/runtime)? Keeping the CLI host a separate exe sidesteps that.

Happy to prototype phase 1 (the envelope + cancel distinction) behind a switch once 1.0 ships, since it's contained and doesn't touch the default pipeline behavior.

[tig]

Correction — the cmdlet must stay idiomatic; this is why they don't merge

Retracting the "cancel ≠ empty / status:"cancelled" in the cmdlet" part of my earlier comment. That imported a CLI-binary idiom into a PowerShell cmdlet, where the established idiom is the opposite.

Standard PS precedent. The canonical analog is Out-GridView -PassThru / -OutputMode Single|Multiple: on Cancel/close it writes nothing to the pipeline — indistinguishable from "OK with no selection." No status object, no thrown error. ocgv already mirrors this; its own help says "Press ESC to cancel without output." More generally, cmdlets signal outcome via the pipeline (objects or nothing) and the error stream / terminating exceptions — never an in-band status envelope. Ctrl-C is StopProcessing() (pipeline stops), a separate mechanism, not a return value.

So the cmdlet should keep its current behavior unchanged — silent on cancel, like Out-GridView. No -AsJson, no envelope, no exit-code semantics in the cmdlet. An in-PowerShell agent does what any consumer does: take whatever objects come back (| ConvertTo-Json if it wants text) and treat empty as "nothing selected," same as a human.

Why ocgv/shot are not merged into clet/cli — and won't be. The two contracts are mutually exclusive idioms in different runtimes:

	PowerShell cmdlet (ocgv/shot)	clet / Terminal.Gui.Cli binary
Output	objects on the pipeline	JSON envelope on stdout
Cancel	silent (no output)	status:"cancelled", exit 130
Errors	error stream / terminating exception	status:"error", exit 2
Discovery	Get-Help, Get-Command, param metadata	--opencli manifest

Forcing either idiom onto the other breaks its native ecosystem. That's the core tension, and the resolution is don't merge — keep ocgv/shot as idiomatic cmdlets.

Where the agent story lives, then. Entirely in a separate CLI surface — a pstui host built on Terminal.Gui.Cli that reuses the v2 OutGridViewWindow/ShowObjectTreeWindow Views and speaks the clet contract natively (envelope + 0/1/2/130 + --opencli). That host can distinguish cancel from empty because in the CLI world that distinction is idiomatic. The cmdlet and the host share the View classes, not the output contract.

Net: idea #1 (expose the Views via cli) and #3 (--opencli) stay — as a separate binary. Idea #2 ("clet-style JSON-out in the cmdlets") is withdrawn; it conflicts with PS idioms.