shiptrail 0.1.0__tar.gz

shiptrail-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+# Keep LF line endings in the repo and on checkout, whatever core.autocrlf says.
+* text=auto eol=lf
+*.png binary
+*.jpg binary

shiptrail-0.1.0/.github/workflows/baselines.yml

@@ -0,0 +1,34 @@
+name: Update Linux baselines
+on:
+  workflow_dispatch:
+permissions: {}
+jobs:
+  baselines:
+    permissions:
+      contents: read
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          python-version: '3.11'
+      - run: uv sync --locked
+      - run: npm ci
+        working-directory: web
+      - run: npx playwright install --with-deps chromium
+        working-directory: web
+      - run: npm run build
+        working-directory: web
+      - run: npm run e2e:update
+        working-directory: web
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: linux-baselines
+          path: web/e2e/baselines/linux/
+          retention-days: 7

shiptrail-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,117 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions: {}
+
+# A newer push to the same branch or PR replaces the older run; tag (release) runs never cancel.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref_type == 'branch' }}
+
+jobs:
+  python:
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, windows-latest, macos-latest]
+        python: ['3.11', '3.12', '3.13']
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv lock --check
+      - run: uv sync --locked
+      - run: uv run --locked pytest
+
+  web:
+    permissions:
+      contents: read
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+
+  dashboard:
+    uses: ./.github/workflows/dashboard.yml
+    permissions:
+      contents: read
+
+  package:
+    needs: [python, web, dashboard]
+    permissions:
+      contents: read
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          python-version: '3.11'
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci
+        working-directory: web
+      - run: npm run build
+        working-directory: web
+      - run: uv build
+      - run: python tools/release_artifacts.py dist
+      - name: Validate tagged changelog before publishing
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: python tools/release_artifacts.py dist --tag "$RELEASE_TAG" --notes release-notes.md
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  smoke:
+    needs: package
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, windows-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          python-version: '3.11'
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: distributions
+          path: dist
+      - run: uv run --no-project --python 3.11 python tools/release_smoke.py dist
+      - run: uv run --no-project --python 3.11 python tools/upgrade_smoke.py dist

shiptrail-0.1.0/.github/workflows/dashboard.yml

@@ -0,0 +1,49 @@
+name: Dashboard E2E
+on:
+  workflow_call:
+permissions: {}
+jobs:
+  dashboard:
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, windows-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          python-version: '3.11'
+      - run: uv sync --locked
+      - run: uv run --locked yapf --diff web/e2e_server.py tests/fake_cli.py
+      - run: uv run --locked pytest tests/test_engine_api.py tests/test_engine_streams.py
+      - run: npm ci
+        working-directory: web
+      - run: npx playwright install --with-deps chromium
+        working-directory: web
+      - run: npm run typecheck
+        working-directory: web
+      - run: npm run lint
+        working-directory: web
+      - run: npm test
+        working-directory: web
+      - run: npm run build
+        working-directory: web
+      - run: npm run e2e
+        working-directory: web
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: failure()
+        with:
+          name: dashboard-failure-${{ matrix.os }}
+          path: |
+            web/test-results/
+            web/playwright-report/
+          retention-days: 7

shiptrail-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions: {}
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: ${{ contains(github.ref_name, 'rc') && 'testpypi' || 'pypi' }}
+    permissions:
+      actions: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: distributions
+          path: artifacts
+      - name: Select distribution files (checksums are release assets)
+        run: |
+          mkdir dist
+          cp artifacts/*.whl artifacts/*.tar.gz dist/
+      - name: Publish candidate to TestPyPI
+        if: contains(github.ref_name, 'rc')
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - name: Publish stable release to PyPI
+        if: ${{ !contains(github.ref_name, 'rc') }}
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  release:
+    needs: publish
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      actions: read
+      contents: write
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: distributions
+          path: dist
+      - uses: actions/attest-build-provenance@977bb373ede98d70efdf65b84cb5f73e068dcc2a # v3
+        with:
+          subject-checksums: dist/SHA256SUMS
+      - name: Extract changelog notes
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: python tools/release_artifacts.py dist --tag "$RELEASE_TAG" --notes release-notes.md
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          args=()
+          if [[ "$RELEASE_TAG" == *rc* ]]; then args+=(--prerelease); fi
+          gh release create "$RELEASE_TAG" dist/*.whl dist/*.tar.gz dist/SHA256SUMS --verify-tag --title "$RELEASE_TAG" --notes-file release-notes.md "${args[@]}"

shiptrail-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Runtime state of factory runs
+/shiptrail/jobs/
+*.tmp
+
+# Local factory installation
+/.claude/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+/dist/
+/src/shiptrail/dashboard_dist/
+/web/node_modules/
+/web/test-results/
+/web/playwright-report/

shiptrail-0.1.0/AGENTS.md

@@ -0,0 +1,26 @@
+# Working on shiptrail
+
+Use Python 3.11+ and the development environment from `uv sync --locked`.
+
+## Python formatting
+
+YAPF is the Python formatter for this repository. Its pinned version and style live in
+`pyproject.toml` (PEP 8, four spaces, 100 columns).
+
+Before testing and committing Python changes, format each Python file you created or
+modified, then check those same files:
+
+```powershell
+uv run --locked yapf --in-place path/to/file.py path/to/other.py
+uv run --locked yapf --diff path/to/file.py path/to/other.py
+```
+
+The check must exit zero. Run the relevant tests after formatting. Preserve fixture
+contents used as test evidence; do not reformat files under `tests/fixtures/`.
+
+For an explicitly requested repository-wide formatting pass:
+
+```powershell
+uv run --locked yapf --in-place --recursive .
+uv run --locked yapf --diff --recursive .
+```

shiptrail-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.1.0] - 2026-10-18
+
+First release under the Shiptrail name. Shiptrail runs a configurable pipeline of Claude Code,
+Codex and OpenCode agents against a repository, with a local dashboard.
+
+- `shiptrail init` sets up any folder, detects the installed tools and writes the project's
+  `shiptrail/` folder, starter instructions and in-chat shortcuts.
+- The dashboard covers the command center, jobs, backlog, pipelines with a machine-wide
+  library, activity, usage and repository settings.
+- `shiptrail upgrade` keeps a repository's engine range and shortcuts in step with the
+  installed engine.
+
+## [0.1.0rc1] - 2026-10-18
+
+Release candidate for 0.1.0; no `shiptrail upgrade` needed.

shiptrail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danijel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shiptrail-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: shiptrail
+Version: 0.1.0
+Summary: A deterministic engine for local coding agents
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: psutil<8,>=6
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: uvicorn<1,>=0.30
+Description-Content-Type: text/markdown
+
+# Shiptrail
+
+Shiptrail runs a configurable pipeline of Claude Code, Codex, and OpenCode agents against
+your repository. Each job gets its own branch and worktree. The engine stores job state, streams
+logs to a local dashboard, and either merges a verified result or pauses with a clear request
+for you.
+
+## Requirements
+
+- Python 3.11+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
+- Git. A new folder is set up by `shiptrail init`; an existing repository can use any branch.
+- Claude Code, Codex, or OpenCode CLI, signed in. Install the client you select in the pipeline.
+- Optional: [agent-browser](https://github.com/vercel-labs/agent-browser) for browser checks:
+  `npm install -g agent-browser && agent-browser install`. `shiptrail doctor` reports it but does
+  not require it.
+
+## Install
+
+Install the engine once per machine:
+
+```bash
+uv tool install shiptrail
+```
+
+Release candidate, from TestPyPI, until the stable release is published:
+
+```bash
+uv tool install --default-index https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ shiptrail
+```
+
+If uv is not installed, `install.py` is an optional bootstrap. It prints uv's official
+installation instructions and asks before running the official installer, then installs the
+engine:
+
+```powershell
+python install.py
+```
+
+Pass `--target path/to/your-project` to also run `shiptrail init` in that folder.
+
+## Quick start
+
+Start from any folder, empty or not:
+
+```bash
+cd path/to/your-project
+shiptrail init
+shiptrail doctor
+shiptrail start "build a todo app"
+```
+
+`shiptrail init` looks for Claude Code, Codex and OpenCode on your machine, shows the plan, and
+asks once before it changes anything. With one usable tool it uses that tool without asking.
+With several it asks which one the pipeline should start on (Enter takes the first):
+
+```text
+Found Claude Code, Codex and OpenCode.
+Which tool should the pipeline use by default?
+  1) Claude Code
+  2) Codex
+  3) OpenCode
+  4) Mixed: the template's choice for each stage
+You can change any stage later on the Pipelines page. [1]:
+Plan for C:\path\to\your-project:
+  would create: git repository on main
+  would write: AGENTS.md (starter; edit the TODO lines)
+  would write: CLAUDE.md (imports AGENTS.md for Claude Code)
+  would commit: AGENTS.md, CLAUDE.md as the first commit on main
+  would write: shiptrail/config.json
+  would write: shiptrail/backlog.md
+  would write: .claude/skills/shiptrail/SKILL.md
+  would write: .agents/skills/shiptrail/SKILL.md
+  would write: .opencode/skills/shiptrail/SKILL.md
+  would update: .gitignore
+Continue? [Y/n]
+```
+
+The answer sets the tool every stage starts on; each stage can use a different tool afterwards, on
+the Pipelines page. "Mixed" keeps the template's tool for each stage and moves a stage to your
+first tool when its own is not installed. `init` installs the in-chat shortcut (`/shiptrail` or
+`$shiptrail`) for every tool it found. If none is installed it stops and says how to install one;
+`--provider claude|codex|opencode|both` skips detection, for scripts.
+
+What init does:
+
+- **No git repository:** creates one on `main` and makes a first commit with the starter
+  instructions file. If git has no name or email configured, it stops and prints the two
+  `git config` commands to run.
+- **Existing repository:** uses its current branch as the base branch and records it in
+  `shiptrail/config.json`. Nothing is renamed.
+- **No `AGENTS.md` or `CLAUDE.md`:** writes a starter with `TODO` lines. With Claude Code alone that is
+  `CLAUDE.md`. When other tools share the project it is `AGENTS.md`, plus a `CLAUDE.md` that imports
+  it, so every tool reads the same instructions. Edit them to describe
+  your install, dev server and checks. If the folder has a `package.json` with `dev`, `test`,
+  `build` or `lint` scripts, those commands are filled in.
+
+Then commit the shiptrail files (`shiptrail/`, the skill wrapper and `.gitignore`) before the first
+job. The engine never pushes to a remote.
+
+Run `shiptrail --help` for the commands, or `shiptrail <command> --help` for one of them.
+
+## Use it
+
+Start work with the skill command from your client:
+
+```text
+/shiptrail Add a dark mode toggle to settings     (Claude Code)
+$shiptrail Add a dark mode toggle to settings     (Codex)
+```
+
+Other commands:
+
+| Command | What it does |
+|---|---|
+| `shiptrail start "<title>"` | Queue a job from the title |
+| `shiptrail status` | List jobs and any that need you |
+| `shiptrail approve <job-id>` | Approve a finished job and merge it into the base branch |
+| `shiptrail rework <job-id> "<note>"` | Send a job back to the builder with a note |
+| `shiptrail resume <job-id>` / `shiptrail stop <job-id>` | Resume or stop a job |
+| `shiptrail delete <job-id>` | Delete a job, its worktree and its branch |
+| `shiptrail doctor` | Check tools, logins and ports, with a fix for each problem |
+| `shiptrail dashboard` | Open this repository's dashboard |
+
+You can also add work to `shiptrail/backlog.md` or the dashboard backlog, then start it with
+`shiptrail next`.
+
+## Define your pipeline
+
+Edit the pipelines in `shiptrail/config.json` or use Dashboard Settings. Full runs a spec,
+builder, parallel reviewers, and approval. Fast uses the shorter implementation and approval
+flow. Configure roles, providers, model and effort per execution, retry limits, and merge
+policy. Jobs retain a snapshot of their pipeline and role instructions, so later settings
+changes affect new jobs only.
+
+In the pipeline editor, Role, Model and Effort are dropdowns. Roles are the built-in ones plus any in
+`shiptrail/roles/`. Models and efforts are read from your installed tools, `codex debug models` and
+`opencode models`, which only list metadata and never call a model. The answers are cached for ten
+minutes. Claude Code has no such command, so it offers its aliases. If a tool is missing or does not
+answer, the dropdown falls back to built-in choices and says why. "Custom..." accepts any other value.
+A saved model that is not in a tool's list is kept and flagged.
+
+## When a job needs you
+
+Jobs pause when an agent is blocked, a review requests changes beyond the retry limit, the
+approver escalates a product or risk decision, or the merge policy requires your review.
+`shiptrail status` and the dashboard show the reason and the reports to inspect. Resolve the
+request in the branch, then resume or rework the job. The engine never pushes to a remote.
+
+## The dashboard
+
+Run `shiptrail dashboard` to open the dashboard for this repository, or `shiptrail serve --open` to
+start the service and open it. By default the URL is `http://127.0.0.1:5099/`. The dashboard shows
+jobs across registered repositories, pipeline steps, reports, timeline, logs and usage. It also
+supports backlog management, repository and machine settings, and job actions such as stop,
+resume, approve, rework and delete. The service listens on localhost only.
+
+## What a job leaves behind
+
+The repository keeps its configuration and backlog in `shiptrail/`. `shiptrail/backlog.md` keeps
+its plain line format; backlog priority and status are committed beside it in the sidecar
+`shiptrail/backlog.meta.json`, which may be deleted safely (items fall back to normal priority
+and ready status). Job state, reports,
+attempt logs and archived outputs live under `shiptrail/jobs/<job-id>/`; worktrees are kept
+beside the repository until merged or deleted. The exact report set depends on the pipeline.
+The machine registry and service state live in the user data directory (or `SHIPTRAIL_HOME`).
+
+## Customising
+
+Built-in roles ship with the engine. To customize a role for one repository, run
+`shiptrail eject <role>` and edit the resulting file in `shiptrail/roles/`. The dashboard Settings
+page edits pipeline configuration; machine settings control provider executable paths
+(`cli.claude`, `cli.codex`, `cli.opencode`), concurrency and available ports. Ejected roles
+remain repository-local and can be compared with the built-in version using
+`shiptrail eject <role> --diff`.
+
+## Working on this repo
+
+Set up the development environment with `uv sync --locked`. The Python suite runs with
+`uv run --locked pytest`, or in parallel with `uv run --locked pytest -n 4` (about a minute, against
+about six serially). Tests that touch the fixed sandbox port range are kept on one worker.
+
+The dashboard lives in `web/`: run `npm ci`, then `npm run build` to rebuild the bundle the
+engine serves, and `npm run typecheck`, `npm run lint`, `npm test` and `npm run e2e` to check it.
+
+## License
+
+See [LICENSE](LICENSE).