From 7cc15cca922f9c3f8aa8e3238aaddafaeb6e8ad0 Mon Sep 17 00:00:00 2001 From: Alex Blank Date: Mon, 27 Jul 2026 15:15:56 +0200 Subject: [PATCH] docs: establish project documentation baseline Provide installation, security, contribution, licensing, and release guidance while removing user-specific service configuration. --- CHANGELOG.md | 18 +++ CONTRIBUTING.md | 47 ++++++++ LICENSE | 201 +++++++++++++++++++++++++++++++ README.md | 135 +++++++++++++++++++++ SECURITY.md | 41 +++++++ docs/README.md | 22 ++++ package.json | 12 ++ systemd/pi-status-bridge.service | 2 +- ui/README.md | 48 +++++++- ui/package.json | 6 + ui/src-tauri/Cargo.toml | 2 + 11 files changed, 529 insertions(+), 5 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 SECURITY.md create mode 100644 docs/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..0a80102 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,18 @@ +# Changelog + +All notable changes to Pi Status Bridge are documented here. The project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses [Semantic Versioning](https://semver.org/). + +## [Unreleased] + +### Changed + +- Documentation and repository metadata are being established for public collaboration. + +## [0.1.0] - 2026-07-27 + +### Added + +- Local Unix-socket bridge for Pi RPC agents and worktree-aware session management. +- Bounded Pi child recovery, local client CLI, and systemd user-service example. +- Tauri desktop UI and Noctalia v4/v5 presentation adapters. +- Automated bridge, protocol, adapter, and desktop tests. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b6321d8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,47 @@ +# Contributing to Pi Status Bridge + +## Reason for existence + +Keep contributions reviewable and preserve the bridge's worktree isolation, local-only transport, and Pi-owned approval policy. + +## Before coding + +1. Create a focused branch; do not develop directly on `main`. +2. Read [`DESIGN.md`](DESIGN.md) and the relevant document under [`specs/`](specs/). +3. State which boundary changes: bridge protocol, Pi RPC adapter, desktop UI, or Noctalia adapter. +4. Add or update the narrowest test that proves the behavior. + +## Development workflow + +```bash +npm --prefix ui ci +npm test +npm run check +``` + +Use Node.js 20+ and Rust/Tauri tooling for UI work. Keep generated directories untracked: `ui/node_modules/`, `ui/dist/`, `ui/src-tauri/target/`, and `ui/src-tauri/gen/schemas/`. + +## Required invariants + +- **Never** expose a TCP listener in v1. +- **Never** route a request to a worktree other than the explicitly selected agent. +- **Never** let the bridge, desktop client, or Noctalia adapters decide an extension approval. +- **Never** commit runtime sockets, sessions, logs, build outputs, secrets, or agent artifacts. + +## Pull requests + +1. Use a Conventional Commit-style title, for example `fix(protocol): reject malformed frames`. +2. Explain the user-visible behavior and the invariant protected. +3. Include tests for the changed contract; include manual verification steps for desktop or Noctalia changes. +4. Run `npm test` and `npm run check` before requesting review. +5. Push the feature branch and merge through the forge workflow; do not directly push `main`. + +## Documentation changes + +Update the closest authoritative document when behavior, setup, security boundaries, or test coverage changes. Keep the root README concise and link detailed design material rather than duplicating it. + +## Verification + +```bash +npm test && npm run check +``` diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..69b3f1a --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ +Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 Alex Blank + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..974e0ac --- /dev/null +++ b/README.md @@ -0,0 +1,135 @@ +# Pi Status Bridge + +> A local Unix-socket bridge and desktop UI for monitoring and controlling persistent [Pi](https://github.com/badlogic/pi-mono) coding-agent sessions without bypassing Pi-owned safety policy. + +Pi Status Bridge keeps one Pi RPC agent per selected worktree, exposes a local-only protocol, and provides desktop and Noctalia adapters. It is experimental software: use it on worktrees you control and verify the documented security boundaries before daily use. + +## What it provides + +- A local bridge that owns Pi RPC child processes, sessions, recovery, and worktree routing. +- A same-user Unix-domain socket; it never listens on TCP. +- A Tauri + React desktop client for agents, transcripts, prompts, model/thinking controls, and extension requests. +- Presentation-only adapters for Noctalia v4 and v5. +- A local client CLI for request/response and event subscriptions. +- Bounded recovery for unexpected Pi child exits. + +## Requirements + +- Node.js 20 or newer. +- A working `pi` command available on `PATH`; the bridge starts Pi with `pi --mode rpc`. +- Linux or another Unix-like environment with an absolute `XDG_RUNTIME_DIR`. +- For the desktop UI: Rust stable and the native prerequisites required by [Tauri v2](https://v2.tauri.app/start/prerequisites/). +- For Noctalia integration: a compatible Noctalia v4 or v5 installation. + +## Quick start + +Clone the repository and install the desktop UI dependencies: + +```bash +git clone ssh://git@git.commumedia.org:2222/alex/pi-gui.git +cd pi-gui +npm --prefix ui ci +``` + +Start the bridge for your home worktree. `XDG_RUNTIME_DIR` must already be set by the desktop session. + +```bash +node src/bridge/cli.js \ + --worktree "$HOME" \ + --session-root "$HOME/.local/state/pi-status-bridge/sessions" +``` + +The bridge prints its socket path as JSON. In another terminal, start the desktop client: + +```bash +npm --prefix ui run tauri dev +``` + +The desktop client reads `PI_STATUS_BRIDGE_SOCKET` when set; otherwise it uses `$XDG_RUNTIME_DIR/pi-status-bridge/bridge.sock`. + +## CLI usage + +### Bridge daemon + +```bash +node src/bridge/cli.js [--worktree ] [--runtime-dir ] [--session-root ] +``` + +- `--worktree` defaults to the current user's home directory. +- `--runtime-dir` overrides `XDG_RUNTIME_DIR`; it must be absolute. +- `--session-root` selects where the bridge stores Pi session references. + +### Local client + +Use the printed socket path or export it once: + +```bash +export PI_STATUS_BRIDGE_SOCKET="$XDG_RUNTIME_DIR/pi-status-bridge/bridge.sock" +node src/client/cli.js request '{"op":"list_agents"}' +node src/client/cli.js subscribe --agent +``` + +The request payload is the local protocol JSON. See [`DESIGN.md`](DESIGN.md) for the architectural contract and [`specs/FULL_PI_PANEL_SPEC.md`](specs/FULL_PI_PANEL_SPEC.md) for the desktop surface. + +### Noctalia relay + +```bash +node src/client/noctalia-relay-cli.js \ + --socket "$PI_STATUS_BRIDGE_SOCKET" \ + --agent +``` + +Install the adapter that matches your desktop: [`noctalia-plugin/`](noctalia-plugin/) supports v4 and [`noctalia-v5-plugin/`](noctalia-v5-plugin/) supports v5. Both adapters are presentation-only; neither starts Pi nor approves extension requests. + +## Run as a user service + +The included [`systemd/pi-status-bridge.service`](systemd/pi-status-bridge.service) is a portable user-service example. Install the bridge CLI, then ensure both `pi-status-bridge` and `pi` are on the user service's `PATH`: + +```bash +npm install --global . +command -v pi-status-bridge pi + +mkdir -p ~/.config/systemd/user +cp systemd/pi-status-bridge.service ~/.config/systemd/user/ +systemctl --user daemon-reload +systemctl --user enable --now pi-status-bridge.service +systemctl --user status pi-status-bridge.service +``` + +If systemd cannot locate either executable, add a user-service drop-in that sets `PATH` to their containing directories; do not hard-code another user's home path in the tracked unit. + +## Development + +```bash +# Bridge and protocol tests, then Tauri tests +npm test + +# JavaScript syntax checks and production UI build +npm run check + +# Desktop UI only +npm --prefix ui run dev +npm --prefix ui run tauri dev +``` + +`npm test` is the repository acceptance command. It runs the Node test suite and the Tauri Rust tests. `npm run check` additionally builds the UI. + +## Architecture and documentation + +- [`docs/README.md`](docs/README.md) — documentation index. +- [`DESIGN.md`](DESIGN.md) — system boundaries and security invariants. +- [`IMPLEMENTATION_PLAN.md`](IMPLEMENTATION_PLAN.md) — implementation milestones. +- [`TEST_PLAN.md`](TEST_PLAN.md) — automated, manual, and soak-test acceptance criteria. +- [`specs/`](specs/) — detailed UI and Tauri architecture specifications. + +## Contributing + +Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a change. Keep prompts and worktree routing explicit, preserve local-only transport, and run both verification commands before review. + +## Security + +Read [`SECURITY.md`](SECURITY.md) before deployment or vulnerability reporting. The bridge must never introduce a network listener or bypass Pi extension approvals. + +## License + +Copyright 2026 Alex Blank. Licensed under the [Apache License 2.0](LICENSE). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..3003ffd --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ +# Security Policy + +## Reason for existence + +Pi Status Bridge controls local coding-agent sessions. Security reports and changes must preserve the same-user, local-only boundary. + +## Supported versions + +| Version | Supported | +| --- | --- | +| `0.1.x` | Yes | +| Earlier versions | No | + +## Reporting a vulnerability + +Do **not** open a public issue for a suspected vulnerability. Report it privately to the repository maintainers through the hosting forge, including: + +- affected commit or version; +- reproduction steps and prerequisites; +- impact, especially cross-user access, cross-worktree routing, or approval bypass; and +- a proposed mitigation when available. + +Maintainers will acknowledge the report, reproduce it, and coordinate disclosure before publishing details. + +## Security boundaries + +- The bridge listens only on a Unix-domain socket under `XDG_RUNTIME_DIR`. +- The socket directory and socket are owner-only resources. +- Agents are keyed by canonical worktree paths; requests cannot silently cross worktree boundaries. +- Pi extensions retain ownership of confirmations and approvals. +- Prompts and tool payloads must not be emitted in routine lifecycle logs. + +A change that weakens any boundary above requires an explicit design update and security review before merge. + +## Verification + +```bash +npm test +``` + +The test suite covers socket ownership, malformed protocol messages, agent isolation, recovery, and adapter behavior. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..58ebbbd --- /dev/null +++ b/docs/README.md @@ -0,0 +1,22 @@ +# Documentation index + +## Reason for existence + +Point contributors and operators to the authoritative document for each concern without duplicating implementation detail. + +| Need | Authoritative document | +| --- | --- | +| Install, run, and verify the project | [`../README.md`](../README.md) | +| Understand boundaries and security invariants | [`../DESIGN.md`](../DESIGN.md) | +| Follow implementation milestones | [`../IMPLEMENTATION_PLAN.md`](../IMPLEMENTATION_PLAN.md) | +| Execute acceptance and soak testing | [`../TEST_PLAN.md`](../TEST_PLAN.md) | +| Understand the desktop product surface | [`../specs/FULL_PI_PANEL_SPEC.md`](../specs/FULL_PI_PANEL_SPEC.md) | +| Understand Tauri integration | [`../specs/TAURI_CLIENT_ARCHITECTURE.md`](../specs/TAURI_CLIENT_ARCHITECTURE.md) | +| Contribute safely | [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | +| Report vulnerabilities | [`../SECURITY.md`](../SECURITY.md) | + +## Verification + +```bash +test -f README.md && test -f DESIGN.md && test -f TEST_PLAN.md +``` diff --git a/package.json b/package.json index f410ebc..d014668 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,19 @@ { "name": "pi-status-bridge", "version": "0.1.0", + "description": "Local Unix-socket bridge and desktop UI for persistent Pi coding-agent sessions", "private": true, + "license": "Apache-2.0", + "repository": { + "type": "git", + "url": "ssh://git@git.commumedia.org:2222/alex/pi-gui.git" + }, + "keywords": [ + "pi", + "coding-agent", + "tauri", + "noctalia" + ], "type": "module", "bin": { "pi-status-bridge": "src/bridge/cli.js", diff --git a/systemd/pi-status-bridge.service b/systemd/pi-status-bridge.service index db96898..adafe52 100644 --- a/systemd/pi-status-bridge.service +++ b/systemd/pi-status-bridge.service @@ -4,7 +4,7 @@ After=graphical-session.target [Service] Type=simple -ExecStart=/home/alex/.npm-global/bin/pi-status-bridge --session-root %h/.local/state/pi-status-bridge/sessions +ExecStart=/usr/bin/env pi-status-bridge --session-root %h/.local/state/pi-status-bridge/sessions Restart=on-failure RestartSec=3 diff --git a/ui/README.md b/ui/README.md index 102e366..0d9de14 100644 --- a/ui/README.md +++ b/ui/README.md @@ -1,7 +1,47 @@ -# Tauri + React + Typescript +# Pi Status UI -This template should help get you started developing with Tauri, React and Typescript in Vite. +## Reason for existence -## Recommended IDE Setup +Provide the desktop control surface for Pi Status Bridge. The UI presents bridge state and forwards user intent; it never owns Pi sessions, worktree routing, or approval policy. -- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) +## Requirements + +- Node.js 20+. +- Rust stable and the native dependencies required by [Tauri v2](https://v2.tauri.app/start/prerequisites/). +- A running Pi Status Bridge socket. By default the app uses `$XDG_RUNTIME_DIR/pi-status-bridge/bridge.sock`; set `PI_STATUS_BRIDGE_SOCKET` to override it. + +## Develop + +From the repository root: + +```bash +npm --prefix ui ci +node src/bridge/cli.js --worktree "$HOME" +npm --prefix ui run tauri dev +``` + +The second command starts the bridge; run it in a separate terminal. The Tauri app connects to it on startup. + +## Commands + +```bash +npm --prefix ui run dev # Vite frontend only +npm --prefix ui run build # typecheck and build frontend assets +npm --prefix ui run tauri dev # run the desktop client +npm --prefix ui run tauri build # package a desktop bundle +``` + +## Boundaries + +- The UI sends operations only to the selected bridge agent. +- Extension responses are forwarded unchanged to Pi. +- The UI must not add a network transport or persist competing model/thinking defaults. + +## Verification + +```bash +cargo test --manifest-path ui/src-tauri/Cargo.toml +npm --prefix ui run build +``` + +See the [root README](../README.md) for bridge setup and repository-wide verification. diff --git a/ui/package.json b/ui/package.json index 0d268fb..146ee02 100644 --- a/ui/package.json +++ b/ui/package.json @@ -2,6 +2,12 @@ "name": "pi-status-ui", "private": true, "version": "0.1.0", + "description": "Standalone desktop client for Pi Status Bridge", + "license": "Apache-2.0", + "repository": { + "type": "git", + "url": "ssh://git@git.commumedia.org:2222/alex/pi-gui.git" + }, "type": "module", "scripts": { "dev": "vite", diff --git a/ui/src-tauri/Cargo.toml b/ui/src-tauri/Cargo.toml index a2bc07a..2ecf3f3 100644 --- a/ui/src-tauri/Cargo.toml +++ b/ui/src-tauri/Cargo.toml @@ -3,6 +3,8 @@ name = "pi-status-ui" version = "0.1.0" description = "Standalone desktop client for Pi Status Bridge" authors = ["alex"] +license = "Apache-2.0" +repository = "ssh://git@git.commumedia.org:2222/alex/pi-gui.git" edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html