Initial pipelines server, CLI, TUI, and Go installation
This commit is contained in:
+118
@@ -0,0 +1,118 @@
|
||||
# CLI and agent authoring
|
||||
|
||||
`pipelines help` lists commands; `pipelines help edit` (or `edit --help`) shows
|
||||
command-specific flags and examples. Installed commands work from any directory.
|
||||
The installed command is a compiled Go binary; only service lifecycle management
|
||||
delegates to the private Python helper. The binary discovers its manifest through
|
||||
the system command symlink. A separately `go install ./cmd/pipelines`-installed
|
||||
binary can select a managed installation using `PIPELINES_PREFIX`.
|
||||
For source development, use `go run ./cmd/pipelines help`; start the native server
|
||||
separately. Set `PIPELINES_URL` or pass `--url` to select another server.
|
||||
|
||||
## Draft-first OpenCode workflow
|
||||
|
||||
```sh
|
||||
pipelines edit # fuzzy pipeline selection
|
||||
pipelines edit "bug fix" # ask OpenCode what to change
|
||||
pipelines edit "bug fix" "Add a review step"
|
||||
pipelines new "release notes" "Summarize changes and notify my phone"
|
||||
pipelines new "weekly digest" --template scheduled-summary
|
||||
```
|
||||
|
||||
`new` asks for a name when omitted. `edit` accepts an exact name or ID, with names
|
||||
taking precedence over numeric IDs. Both copy a definition into a private draft
|
||||
and launch the host OpenCode interface. An isolated authoring workspace contains
|
||||
the bundled `pipelines` skill and format reference. The CLI creates an OpenCode
|
||||
session and **explicitly activates the skill with `resume=false` before opening
|
||||
the interface**. It does not modify shared OpenCode configuration or copy login
|
||||
credentials. Your OpenCode permissions remain in effect; auto-approval is not used.
|
||||
|
||||
The skill encourages editing only the draft, running server validation, summarizing
|
||||
the changes, and leaving submission to the user. This is an instruction, not a
|
||||
security sandbox: an agent with CLI/shell access can submit when explicitly asked.
|
||||
Every submission, including agent-issued `submit`/`rpc`, still uses server validation.
|
||||
|
||||
For agents or scripts that should not open a terminal:
|
||||
|
||||
```sh
|
||||
pipelines new "release notes" --no-open
|
||||
pipelines edit "bug fix" --json
|
||||
pipelines drafts --json
|
||||
pipelines validate /path/to/pipeline-123.md --json
|
||||
pipelines submit /path/to/pipeline-123.md --json
|
||||
```
|
||||
|
||||
`--json` never opens an editor or picker; provide a name explicitly. It returns
|
||||
draft metadata including `path`, `name`, `server`, `create_only`, and `base_version`.
|
||||
`--no-open` prints the path and review commands. `$PIPELINES_DRAFT_DIR` overrides
|
||||
the shared cache directory. CLI and TUI drafts use private Markdown plus metadata
|
||||
sidecars; `submit FILE` can publish either. External files require `--name NAME`.
|
||||
|
||||
New drafts use create-only submissions and cannot overwrite existing names.
|
||||
Edits carry a latest-version guard checked atomically by the server. On conflict,
|
||||
inspect/export the latest version and reconcile the draft. `--force` explicitly
|
||||
bypasses the version guard only, **never** syntax, graph, model, tool, schedule,
|
||||
or notification validation. Original versions/sources remain immutable.
|
||||
Submitting activates included schedules, so review them before publishing.
|
||||
|
||||
## CLI/TUI capability map
|
||||
|
||||
| TUI action | Agent-capable CLI |
|
||||
| --- | --- |
|
||||
| Browse/search pipelines | `list --json`, `show NAME --json` |
|
||||
| Original source and history | `export NAME --version N`, `versions NAME --json` |
|
||||
| Browse templates/source | `templates --json`, `template KEY --source` |
|
||||
| Create or edit a definition | `new`, `edit`, `drafts` |
|
||||
| Validate and publish | `validate FILE`, `submit FILE` |
|
||||
| Start a run | `run NAME PROMPT --yes --json` |
|
||||
| Run history/inspection | `runs --json`, `inspect ID --json` |
|
||||
| Cancel | `cancel ID --json` |
|
||||
| Connection and phone settings | `connection --json`, `ping --json` |
|
||||
| Operational diagnostics | installed `logs`, `status`, `doctor` |
|
||||
|
||||
The TUI does not spawn CLI processes for each request. Both front ends share
|
||||
`internal/client`'s command transport and `internal/draft`'s persisted drafts;
|
||||
the server owns all validation, persistence, execution, and schedules. `rpc`
|
||||
exposes the full protocol as an escape hatch, so no server command is TUI-only:
|
||||
|
||||
```sh
|
||||
printf '%s' '{"type":"get_pipeline","pipeline_id":1,"version":1}' | pipelines rpc -
|
||||
```
|
||||
|
||||
Existing protocol commands: `ping`, `list_pipelines`, `get_pipeline`,
|
||||
`list_templates`, `validate`, `submit`, `run_pipeline`, `list_runs`, `get_run`,
|
||||
`cancel_run`. See `internal/protocol/message.go` for JSON envelopes. Mutating RPCs
|
||||
have real effects; they are not previews. TUI-only animation, scrolling, and
|
||||
transient client logs are presentation, not separate server capabilities.
|
||||
|
||||
## Scripted runs
|
||||
|
||||
```sh
|
||||
cd ~/repos/project
|
||||
pipelines run "bug fix" "Fix the layout" --yes --json
|
||||
pipelines run "bug fix" "Fix the layout" --yes --json --wait --timeout 10m
|
||||
pipelines run "bug fix" "Fix the layout" --yes --json \
|
||||
--allow-tools --write-paths internal/example.go --request-key my-unique-task
|
||||
```
|
||||
|
||||
Runs default to the current directory and latest accepted version. The server
|
||||
checks allowed workspace roots, including symlink resolution. `--version` chooses
|
||||
an immutable version in JSON mode. `--yes` never grants tools implicitly.
|
||||
Go-specific file editing and restricted Go shell checks remain in effect.
|
||||
`--wait` polls until terminal status, returns nonzero on failure/cancellation,
|
||||
and does not cancel a run when waiting times out. Reuse `--request-key` to prevent
|
||||
duplicate work. Without JSON, `run` opens the existing interactive composer and
|
||||
live inspector; Enter inserts a newline, Ctrl+S continues.
|
||||
|
||||
JSON results go to stdout, errors to stderr (JSON error envelopes when requested),
|
||||
and failures exit nonzero. Export/template `--source` deliberately prints raw
|
||||
Markdown. `--timeout` bounds each server request and the optional wait duration.
|
||||
|
||||
## Verification scope
|
||||
|
||||
CLI integration tests exercise draft/validate/submit/history/conflict handling and
|
||||
scripted run/inspection/cancellation through a real local WebSocket server (the
|
||||
run test uses a controlled executor, not a model). The isolated installed CLI
|
||||
also exercised the actual OpenCode API's session creation and skill activation,
|
||||
while capturing interactive launch arguments to avoid a model turn. Full
|
||||
model-driven authoring and Linux execution are **not tested**.
|
||||
Reference in New Issue
Block a user