diff --git a/README.md b/README.md index 230e1baf..589a3dca 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,15 @@ # Pipelines -Reusable, sequential workflows for your repositories. A Go CLI/TUI and native -server reuse your OpenCode login; Docker ntfy handles phone notifications. +Reusable, sequential workflows for your repositories, with a Go CLI/TUI, +OpenCode model stages, retained run history, and optional phone notifications. ## Install `./install.sh` defaults to full **Docker server + ntfy** setup; use `--native` for native binaries only. Docker mode needs Docker Compose and Python 3; native mode needs Go 1.27+ and uses your existing OpenCode for model stages. +For the host CLI/TUI walkthrough below, also install Go 1.27+; the Docker +installer installs/updates those clients when host Go is available. ```sh git clone https://git.a-wan.net/alan/pipelines.git @@ -25,10 +27,25 @@ Native mode installs the Go binaries and shared OpenCode `pipelines` skill witho login checks or automatic services. Docker mode configures ntfy accounts/token, checks publishing/health, and opens container OpenCode provider login on first setup; existing settings, credentials and volumes are retained on reinstall. +Docker provider credentials live in its persistent container volume, separately +from your host OpenCode login. Setup asks for ntfy account passwords, then your +model-provider login and a model; it validates that model with a small real +generation (provider charges may apply). With plain `go install ./cmd/...`, also run `pipelines skill install`. For system-wide use, install the binaries into your chosen system bin directory with the appropriate permissions. Configuration and data remain per-user. +Docker setup starts the server and saves its client endpoint (default host port +**8081**). Do **not** also start `pipelines serve` for this setup. Explicit `--url` +and `PIPELINES_URL` override the saved endpoint; restart existing TUIs after setup. +Docker mounts your home and installation checkout at their original paths and +uses your UID/GID. Other host repositories need a bind mount at the same absolute +path; repositories on another client computer are not automatically transferred. +These unauthenticated server ports are for trusted networks only—do not expose +them to the public Internet. + +### Native server instead (optional) + Start a native server explicitly; fresh databases contain no pipelines: ```sh @@ -49,6 +66,54 @@ directory you invoke `pipelines run` from. Preview with `--print`. Stop any exis foreground/legacy server first. Disable with `pipelines service disable` before uninstalling. See [installation](docs/install.md) for environment and boot options. +## Your first pipeline and run + +Start in the repository you want the workflow to operate on: + +```sh +cd /path/to/your/repository +pipelines +``` + +1. **Create:** press **n** or use **:new**. Choose **OpenCode** to author a + workflow together, or **nvim** to edit the Markdown yourself. The selected + editor must be installed on your client computer. Describe the stages, their + inputs/outputs, and the tools they need. Templates (**b** on Home) are optional; + a fresh installation has no published pipelines. +2. **Keep a draft:** finish/exit the editor. Nothing is published just because you + edited it. Press **d** / **:drafts** to find retained drafts; **e** edits and + **v** validates the selected draft. +3. **Publish:** press **s** in Drafts. If it has no name, type one into the name + prompt and press Enter. Then review and explicitly confirm submission. The + server validates it and creates an immutable pipeline version; the draft stays. +4. **Run:** select the published pipeline, press Enter to open it, then **:run** to + start a run. Supply your task and review the confirmation. The run uses the + directory from which you launched the client, not the installer checkout. +5. **Inspect:** watch the full graph and stage progress. **Tab** expands/focuses + panes; **n/p** select recorded stage visits; **hjkl** pan a focused graph. + On a failed run, **D** / **:debug** opens a fresh OpenCode debugging conversation; + retry requires confirmation and restarts the pinned workflow, so earlier side + effects may happen again. + +Quit with **:quit**; **q** does not exit. For a terminal-only run after publication: + +```sh +pipelines run "your pipeline name" "Describe the task" +``` + +### Phone notifications + +Open **:status** for the server and ntfy connection details. In the ntfy phone +app, add the displayed ntfy server, sign in as **phone-reader** with the password +you set during installation, and subscribe to the displayed topic. Stages must +include a `notify` block to send notifications; see [ntfy setup](docs/ntfy.md). +Installation checks publishing, not reception on your phone. + +For Tailscale, both devices must be connected; use +`http://:8090`. Binding to `0.0.0.0` does not bypass firewalls: +UFW/Docker forwarding rules can allow LAN sources but drop Tailscale sources. +See [Tailscale troubleshooting](docs/ntfy.md#tailscale-address-times-out-while-lan-works). + ## Uninstall ```sh @@ -128,9 +193,10 @@ commands support `--json` for agents and scripts. In the TUI, press **d** (or use **:drafts**) to browse retained drafts, including CLI-created ones. **e** reopens a draft, **v** validates it, and **s** opens explicit -submission confirmation. Drafts remain retained after submission. +submission confirmation, asking for a name first if needed. Drafts remain retained +after submission. -From a run, press **p** / **:pipeline** to open the pipeline version it used. +From a run, press **P** / **:pipeline** to open the pipeline version it used. Initial run input also records `pwd`. Press **r** / **:retry** on a failed run (or `pipelines retry `) to start a new attempt with the same original input, directory, and pipeline version. Completed side effects are not undone. @@ -138,7 +204,8 @@ Retries restart at the entry stage with fresh OpenCode sessions, never the previ conversation or intermediate stage output. Pipelines does not automatically delete generation, agent, or formatting-repair sessions, including on failure/cancellation. Primary session IDs are retained in run steps (`pipelines inspect --json`). -On Home, **r** opens all recent runs; both Home panels show the shortcut. +On Home, **r** opens global run history; **/** fuzzy-searches it. Inside a pipeline, +**r** / **:runs** opens only that pipeline's history. Quit the TUI with **:quit**; **q** does not exit. **Ctrl+C** remains an interrupt. Starting/retrying/canceling runs and deleting drafts require confirmation. CLI publication also prompts; use `--yes` only for explicitly approved automation. @@ -150,12 +217,12 @@ The TUI uses soft light/dark-adaptive cards, muted metadata, subtle selections, and local loading animations instead of heavy character borders and inverted bars. The dashboard includes all-history usage, success rate, average completed duration, per-pipeline usage, and a 14-day activity chart. CLI: `pipelines stats [--json]`. -Use **:status** for a scrollable server/ntfy popup with health, ports, server-computer -IPs and candidate URLs. CLI: `pipelines status [--json]`. Candidate URLs are not +Use **:status** for two panels: server addresses and ntfy phone connection details. +CLI: `pipelines status [--json]`. Candidate URLs are not verified reachable; publishing endpoints and credentials are not disclosed. Retry is offered only after the failed run and its agent have fully stopped. -The run inspector shows its actual path above the details, using the same graph -renderer as pipeline definitions. **g** focuses the graph (arrows pan, j/k scroll). +The run inspector shows the entire pinned graph above the details, dimming stages +and routes not executed. **g** focuses the graph; **hjkl** or arrows pan it. The path and elapsed duration update while running. **a** opens the active/latest OpenCode session's recorded tool evidence; this does not attach a live OpenCode UI. Press **D** / **:debug** (or `pipelines debug `) for a fresh OpenCode