Files
pipelines/internal/cli/help.go
T
alan 1f75e4797e Broker chat from an operator's own OpenCode endpoint and adopt existing sessions
Add an opt-in way to broker chat from an operator-supplied OpenCode service
instead of the instance the server spawns for itself, and a way to adopt a
session that already exists on that endpoint so it appears in chat_sessions and
can be continued from the app.

- Endpoint selection: the `-opencode-endpoint` server flag (defaulting to
  `PIPELINES_OPENCODE_ENDPOINT`) opts in; precedence is explicit flag >
  explicit environment > the endpoint recorded on a previous run, with the
  spawned instance as the default. opencode.OpenEndpoint validates the
  reference once (http(s), host, no userinfo/query/fragment/path), detects the
  backend from its own /api/info (v2) or /global/health (v1) contract, and
  requires a streamable text/event-stream event path. It owns no process
  (Close is a no-op) and never calls startServe; every failure names the
  endpoint and disables chat rather than silently falling back. An
  authenticated endpoint takes an optional password only through the private
  file PIPELINES_OPENCODE_ENDPOINT_PASSWORD_FILE, with
  PIPELINES_OPENCODE_ENDPOINT_USERNAME overriding the detected default.
- Persistence: the validated choice is recorded in an additive single-row
  server_settings table so a restart with no flag/environment reuses it; an
  unreachable recorded endpoint disables chat with a clear message and no
  fallback.
- chat_adopt: a new protocol request (ChatAdoptRequest) with handleChatAdopt in
  internal/server/chat.go. It refuses a nil broker/registry/payload and a
  blank or foreign-shaped id before any endpoint call, reads the endpoint via
  the shared Chat.Session (which reuses Sessions/decodeChatSessions), records
  through the existing RecordOperatorSession with the endpoint's directory and
  title verbatim, and echoes the adopted session plus its registry row like
  chat_create. A missing id is refused naming the id and records nothing; an
  endpoint record with an empty directory is refused rather than substituting
  the server's working directory or home.
- CLI: `pipelines chat-adopt <session-id> [--json]` (usage, notes, help
  inventory, dispatch) with docs/cli.md updated under Chat sessions.
- Autostart preserves the endpoint variables (and the password-file reference,
  never an inline secret) via serviceEnvironmentKeys.

Checks before committing:
- Package location: the change is user-facing chat behaviour, so the packaged
  authoring skill reference internal/author/skill/references/operations.md is
  updated in the same change (Brokered OpenCode chat section) with a dated
  verification-evidence entry and the not-deployed state. No new reference file
  is added, so internal/author/install.go's managed inventory is unchanged.
- Packaged templates: this repository packages no template set for this
  behaviour and none references the chat endpoint, so no template needs
  updating.
- Verification: `go build ./...`, `go vet` on the touched packages, `gofmt -l`
  clean and `go test ./...` all pass. The unit tests cover the endpoint
  validation/precedence, the adopt happy path and refusals, the recorded
  endpoint round-trip, the protocol round-trip and the CLI dispatch. The live
  scratch-server check against the operator's real endpoint was not run in this
  change.

Nothing unrelated is staged; docs left stale (README and other shared documents)
are not edited here and are for a single folding writer.
2026-10-17 20:14:11 +01:00

102 lines
5.8 KiB
Go

package cli
const help = `PIPELINES — reusable workflows for your repositories
Usage: pipelines <command> [arguments] [options]
AUTHOR
new [name] [prompt] Create a draft and open the configured harness
edit [name|id] [prompt] Pick a pipeline, draft changes, open a configured harness
drafts List retained draft files (including TUI drafts)
validate <draft.md> Check a draft using the server's validator
submit <draft.md> Explicitly publish a new immutable version
BROWSE
list List registered pipelines
search QUERY Search pipelines, versions, runs, steps, field text, artifacts
show <name|id> Inspect graph, settings, source and history
versions <name|id> List immutable versions
export [name|id ...] Select/export definitions as ZIP; one name prints Markdown
import [FILE.zip] Select/import definitions; explicitly resolve conflicts
templates List optional templates (never seeds the DB)
template <key> Inspect a template; --source prints Markdown
EXECUTE
provider-check Validate a provider/model with a tool-free response
run [name] [prompt] Fuzzy selection, multiline prompt, live inspector
runs List audited runs; --pipeline filters results
inspect <run-id> Inspect stages, outputs, errors and status
cancel <run-id> Cancel a run; changes are NOT rolled back
decide <run-id> [stage] Choose an option for a run waiting on a person
retry <run-id> Restart a failed run with its original input and directory
title <run-id> "<title>" Rename a run after the fact; input/steps unchanged
debug <run-id> Investigate a run with a configured harness or nvim
chat-adopt <session-id> Adopt an existing OpenCode session into chat_sessions
draft-delete <draft.md> Delete a selected retained draft and its metadata
connection Server and public phone connection (no secrets)
status Server/ntfy health, ports and server computer IPs
stats All-history usage, pipeline counts and daily activity
ping Check connection and identify the running server build
version Identify this CLI build without connecting (--version)
rpc <request.json|-> Send any protocol command (automation escape hatch)
MAINTAIN
retention report Show what a run-history policy would remove (read-only)
retention apply Remove it after approval; artifacts go with their run
SERVER / INTERFACE
harness [opencode|pi] Launch the configured default harness in this directory
harness setup opencode|pi Login/select separate harness and new-pipeline defaults
tui Open the dashboard (default with no command)
serve Start native server in the foreground (Ctrl+C stops it)
service enable Configure user autostart
service disable | status Stop/remove autostart, or inspect OS service status
skill install Install/update the shared Pi/OpenCode authoring skill
uninstall [--yes] Remove verified Go binaries; retain data and drafts
Legacy managed installs: select PIPELINES_PREFIX explicitly for start/stop,
restart/doctor/logs and retained-data or --purge uninstallation.
Options: --url ws://127.0.0.1:8080/connect --json --help
Use pipelines help <command> for its flags. Names with spaces must be quoted.
Stage result format:
Model and agent stages accept a line-oriented result. The first non-empty line
is the declared outcome, followed by "# " sections. "# output" is required and
short (a JSON object carrying the next stage's data); additional sections are
free-form markdown evidence. The legacy {"outcome":...,"output":...} JSON
envelope remains accepted for compatibility.
Examples:
pipelines edit "bug fix" "Add a review step"
pipelines new "release notes" "Summarize changes and notify my phone"
pipelines new "Add a feature" --template task --no-open --json --yes
pipelines validate /path/to/draft.md --json
pipelines submit /path/to/draft.md
pipelines run "bug fix" "Fix the layout" --json
pipelines run "bug fix" "Fix the layout" --model openai/gpt-5 --stage-model review=openai/o4 --json
Run retention (local, explicit, never automatic):
pipelines retention report --db ~/.local/share/pipelines/data/pipelines.db --keep 200 --json
pipelines retention apply --db ~/.local/share/pipelines/data/pipelines.db --keep 200 --yes
Launch-time model overrides: 'pipelines run --model P/M' covers every model stage;
'--stage-model STAGE=P/M' (repeatable; a repeated key is last-wins) overrides one
stage and wins over --model, which wins over the model pinned in the pipeline
version. Overrides apply to that run only, are recorded on the run, and are
validated before the run starts (an unknown stage key names the valid keys).
Draft-first: the configured harness (Pi/OpenCode; host by default, or Docker-linked
when a checkout is linked) edits a private draft; nvim remains a client editor.
Nothing is published automatically.
Every submission is validated server-side. Submission activates any schedules.
JSON mode never launches an editor or picker; supply explicit arguments.
Search: the 'pipelines search QUERY' command and the TUI '/' popup find pipelines,
versions, runs, steps/visits, artifact names and the text of stage inputs,
outputs and evidence. A bare status word (queued, running, succeeded, failed,
canceled, interrupted) or a date (today, yesterday, this week, or YYYY-MM-DD in
local time) selects runs. --type narrows to pipeline, version, run, step, field
or artifact; unrecognised words stay text.
`