patchwork-os 0.2.0-alpha.9 → 0.2.0-beta.0

package/README.bridge.md

@@ -40,6 +40,12 @@ claude --ide
 
 > **Updating?** Use `npm install -g claude-ide-bridge@latest` — `npm update -g` may lag the registry cache after a new release.
 
+> **macOS LaunchAgent users:** always install from the registry (`npm install -g patchwork-os`) or
+> from a tarball (`npm pack && npm install -g patchwork-os-*.tgz`).
+> Running `npm install -g .` from a repo checkout creates a symlink — the macOS sandbox
+> cannot follow it, causing EPERM when launchctl starts the bridge.
+> `patchwork-os launchd install` will refuse to proceed and print fix instructions.
+
 After `init`, type `/mcp` in Claude Code to confirm the bridge is connected. Type `/ide` to see open files, diagnostics, and editor state.
 
 > **One bridge per workspace.** Each project runs its own bridge instance on its own port. Start a separate `claude-ide-bridge --watch` in each directory.

package/README.md

@@ -1,67 +1,347 @@
 # Patchwork OS
 
-**AI that works while you're away. Runs on your machine. Doesn't lock you in.**
+### Your personal AI runtime, local-first.
+
+> Patchwork OS is a local-first personal AI runtime: pluggable model providers, hot-reloadable tools, YAML recipes, a delegation policy with approval queue, and a durable trace memory — all running on your machine, all under your policy.
+
+You decide which model. You decide which actions need a human nod. You own the credentials, the logs, and the deployment. Nothing phones home.
+
+**Five primitives, one runtime:**
+
+- **Tools** — 170+ built-in (LSP, git, terminal, debugger, files) plus any plugin you write. Plugins hot-reload — Claude can author a tool mid-session and call it on the next turn. See [Live Toolsmithing](documents/live-toolsmithing.md).
+- **Recipes** — YAML automations triggered by cron, file save, git commit, test run, or webhook. Anything that can POST a JSON payload can fire a recipe.
+- **Delegation Policy** — three risk tiers, four-source precedence (managed → project-local → project → user). Auto-approve safe, require approval for risky, block dangerous.
+- **Trace memory** — every approval, every recipe run, every enrichment is durable JSONL. Past decisions are surfaced into future sessions automatically. Bundle and back up with [`patchwork traces export`](src/commands/tracesExport.ts).
+- **OAuth** — turn your runtime into a private personal API. PKCE S256, dynamic client registration, deployable on a VPS in minutes.
+
+> **Why not [an MCP server / Zapier / a hosted assistant / a local agent framework]?** See [the comparison page](documents/comparison.md) for the honest tradeoff against each.
+>
+> **What does this look like in one diagram?** See the [architecture overview](documents/architecture.md).
+
+---
+
+The same codebase ships **two ways to use it.** Pick the layer you need.
+
+| | What you get | Install | Best for |
+|---|---|---|---|
+| **🔌 Claude IDE Bridge** | MCP bridge connecting Claude Code to your IDE. 170+ tools — diagnostics, LSP, debugger, terminal, git, GitHub, file ops. | `npm i -g patchwork-os` then run `claude-ide-bridge` | Anyone who wants Claude Code to see and act on their editor state |
+| **🤖 Patchwork OS** | Everything in the bridge **plus** YAML recipes, approval queue, oversight dashboard, mobile push approvals, multi-model providers, JetBrains companion. | Same package, run `patchwork patchwork-init` | Power users running automation, agent workflows, or background tasks |
+
+Same codebase. Bridge is the foundation; Patchwork OS is the optional layer on top. **No vendor lock-in. Runs on your machine.**
+
+---
+
+## 🔌 Claude IDE Bridge — Quick Start
 
 ```bash
-npx patchwork-os@alpha patchwork-init
+# 1. Install the npm package
+npm install -g patchwork-os
+
+# 2. Install the VS Code / Cursor / Windsurf extension
+#    Search "Claude IDE Bridge" on OpenVSX, or:
+claude-ide-bridge install-extension
+
+# 3. Start the bridge for your workspace
+claude-ide-bridge --workspace .
+
+# 4. Connect Claude Code (in another terminal)
+CLAUDE_CODE_IDE_SKIP_VALID_CHECK=true claude --ide
 ```
 
-That one command sets up 5 local recipes, detects Ollama, and drops a terminal dashboard at your fingertips — under 90 seconds on a warm npm cache.
+Type `/ide` in Claude Code to confirm the connection. That's it — Claude now sees your diagnostics, open files, and editor state, and can call 170+ tools to act on them.
+
+**What the bridge gives Claude:**
+
+- Diagnostics, LSP navigation (goto / references / call hierarchy), refactoring with risk analysis
+- Terminal — run commands, read output, wait for async work
+- Git — status, diff, commit, push, blame, checkout, branch list
+- GitHub — open PRs, list issues, post reviews, fetch run logs
+- Debugger — set breakpoints, evaluate expressions, inspect runtime state
+- Files — read, edit by line range, search and replace, capture screenshots
+- Code quality — `auditDependencies`, `detectUnusedCode`, `getCodeCoverage`, `getGitHotspots`
+
+The bridge runs without any flags. No recipes, no automation, no dashboard — just the IDE-Claude connection.
+
+**Compatible IDEs:** VS Code, Cursor, Windsurf, Google Antigravity. JetBrains IDEs via [companion plugin](#jetbrains-plugin).
+
+**Transport layers:**
 
-## What it does
+| Client | Protocol |
+|---|---|
+| Claude Code CLI | WebSocket `ws://127.0.0.1:<port>` |
+| Claude Desktop | stdio shim → WebSocket |
+| Remote (claude.ai, Codex CLI) | Streamable HTTP + Bearer token |
 
-Patchwork OS watches for things that matter, acts, and asks before anything risky goes out.
+**Tool modes:**
 
-- **A developer's overnight.** Tests fail on a push → a one-paragraph triage note lands in your inbox. You wake up knowing where to look.
-- **A small business's inbox.** New customer questions triaged, follow-ups drafted in your voice. Nothing sends without your nod.
-- **A parent's morning.** Field-trip form flagged, reply drafted to the teacher — done before the first coffee.
+| Mode | Tools | When to use |
+|---|---|---|
+| Full _(default)_ | ~170 | All git, GitHub, terminal, file ops, orchestration |
+| Slim (`--slim`) | ~60 | LSP + debugger + editor state only |
 
-## How it works
+Bridge-only docs: [documents/platform-docs.md](documents/platform-docs.md)
 
-- **Recipes** — plain YAML files describe what to watch and what to do. Share them like dotfiles. No code required.
-- **Your models, your keys** — Claude, GPT, Gemini, Grok, or local Ollama. Swap anytime. Nothing phones home.
-- **Oversight first** — everything risky lands in `~/.patchwork/inbox/` for your approval before it goes anywhere.
+---
 
-## After init
+## 🤖 Patchwork OS — Quick Start
 
 ```bash
-patchwork-os recipe list            # see installed recipes
-patchwork-os recipe run daily-status  # run one now
-patchwork-os                        # open terminal dashboard
+npx patchwork-os@beta patchwork-init
 ```
 
-The oversight web UI runs at `http://localhost:3100` when the bridge is active.
+Sets up 5 local recipes, detects Ollama, and opens a terminal dashboard — under 90 seconds.
 
-## 5 starter recipes (no API key needed)
+### ☀️ Morning Brief — the hero workflow
 
-| Recipe | Trigger | What it does |
-|---|---|---|
-| `ambient-journal` | git commit | appends one line to `~/.patchwork/journal/` |
-| `daily-status` | cron 08:00 | morning brief from yesterday's commits |
-| `watch-failing-tests` | test run | drops triage note to inbox on failure |
-| `lint-on-save` | file save | surfaces new TS/JS diagnostics to inbox |
-| `stale-branches` | cron weekly | lists branches older than 30 days |
+Get an AI digest of your Gmail, calendar, and tasks every morning — or on demand:
+
+```bash
+# First-time setup (connect Gmail + Google Calendar)
+patchwork-os patchwork-init
+patchwork-os connections connect gmail
+patchwork-os connections connect google-calendar
+
+# Run it now
+patchwork-os recipe run morning-brief
+```
+
+The brief lands in `~/.patchwork/inbox/` as a Markdown file. Open the dashboard (`http://localhost:3200`) to read it, approve any drafted replies, or let it auto-send at 08:00 via the built-in cron trigger.
+
+No connectors yet? Run with `--local` using Ollama — it summarises your clipboard and last-touched files instead.
+
+---
+
+### What it adds on top of the bridge
+
+Patchwork OS is a local automation platform that watches your workspace for events, runs AI-powered recipes in response, and routes anything risky through an approval queue before it goes anywhere.
+
+Think of it as a background agent that acts on your behalf — but asks before sending, writing, or modifying anything consequential.
+
+- Test suite fails on CI → triage note in your inbox before you wake up
+- Customer email arrives → draft reply in your voice, pending your approval
+- Field-trip permission form flagged → reply drafted to the teacher, waiting for your nod
+
+**Recipes** are plain YAML files. They declare a trigger (cron, file save, git commit, test run, webhook) and an action (run a prompt, write to inbox, call a connector). No code required. Share them like dotfiles.
+
+**Models** are yours. Claude, GPT, Gemini, Grok, or local Ollama. Swap at any time. Nothing phones home.
+
+**Oversight** is non-negotiable. Every write or external action lands in `~/.patchwork/inbox/` for approval. The web UI at `http://localhost:3200` shows pending approvals, live sessions, recipe run history, and analytics.
+
+### Patchwork commands
+
+```bash
+# One-command setup: extension + CLAUDE.md + starter recipes
+patchwork patchwork-init
+
+# Explore
+patchwork recipe list                      # installed recipes
+patchwork recipe run daily-status         # run one now
+patchwork recipe run morning-brief --local # run with local Ollama
+patchwork tools list                      # browse 170+ tools
+patchwork                                 # open terminal dashboard
+
+# Web UI — bridge + extension watcher in tmux
+patchwork start-all                       # then http://localhost:3200
+```
+
+### Starter recipes
+
+The package ships these in `templates/recipes/`. Recipes that need API keys are noted; the rest are zero-config.
+
+| Recipe | Trigger | What it does | Needs |
+|---|---|---|---|
+| `ambient-journal` | git commit | Appends one line to `~/.patchwork/journal/` | — |
+| `daily-status` | cron 08:00 | Morning brief from yesterday's commits | — |
+| `lint-on-save` | file save | Surfaces new TS/JS diagnostics to inbox | — |
+| `stale-branches` | cron weekly | Lists branches older than 30 days | — |
+| `watch-failing-tests` | test run | Drops triage note to inbox on failure | — |
+| `project-health-check` | manual | Snapshot of repo health + flagged risks | — |
+| `ctx-loop-test` | manual | Smoke test for context-platform end-to-end | — |
+| `morning-brief` | cron 08:00 | Gmail + Linear + Slack + Calendar digest | Gmail, Linear, Slack, Google Calendar |
+| `morning-brief-slack` | cron 08:00 | Same brief but only posts to Slack | Linear, Slack |
+| `gmail-health-check` | manual | Verify Gmail connector + token state | Gmail |
+| `inbox-triage` | manual | Triage Gmail unread → suggest archive/reply | Gmail |
+| `sentry-to-linear` | manual | Sentry issue → Linear ticket (one-shot) | Sentry, Linear |
+
+**Connectors available** (all writes governed by your delegation policy): Slack, GitHub, Linear, Gmail, Google Calendar, Google Drive, Sentry, Notion, Confluence, Datadog, HubSpot, Intercom, Stripe, Zendesk, Jira, PagerDuty, Discord, Asana, GitLab.
+
+**Delegation policy presets** ([`templates/policies/`](templates/policies/)): five persona starters — conservative, developer, headless-CI, regulated-industry, personal-assistant. Copy one into `~/.patchwork/config.json` and restart.
+
+**Webhook recipe starters** ([`templates/recipes/webhook/`](templates/recipes/webhook/)): five webhook-triggered recipes — capture-thought, morning-brief (on-demand), meeting-prep, incident-intake, customer-escalation. Anything that can POST HTTP can drive these — iPhone Shortcut, Stream Deck, Home Assistant, NFC tag, monitoring tool.
+
+### Automation hooks
 
-All 5 write to `~/.patchwork/inbox/` only. Nothing is sent anywhere without your approval.
+Event-driven hooks trigger Claude tasks automatically. Activate with `--automation --automation-policy <path.json> --claude-driver subprocess`.
 
-## Roadmap
+Key hooks:
 
-| Phase | Status |
+| Hook | Fires when |
 |---|---|
-| Foundation — init, recipes, terminal dashboard | **shipped (W1)** |
-| Connectors — Gmail, calendar, Slack | W2 |
-| Mobile oversight — approve from phone | W3 |
-| Community recipes + ecosystem | Q3 |
+| `onFileSave` | Matching files saved |
+| `onDiagnosticsStateChange` | Errors appear or clear |
+| `onRecipeSave` | Any `.yaml`/`.yml` saved — runs preflight |
+| `onGitCommit` / `onGitPush` / `onGitPull` | Git tools succeed |
+| `onTestRun` | Test run completes (filter: any/failure/pass-after-fail) |
+| `onBranchCheckout` | After branch switch |
+| `onPullRequest` | After `githubCreatePR` succeeds |
+| `onCompaction` | Before/after Claude context compaction |
+| `onTaskCreated` / `onTaskSuccess` | Orchestrator task lifecycle |
 
-## From source
+All hooks support inline prompts, named prompt references, and a minimum 5s cooldown. Full reference: [documents/platform-docs.md → Automation Hooks](documents/platform-docs.md)
+
+---
+
+## Architecture
+
+```
+patchwork-os (npm package)
+│
+├── claude-ide-bridge          ← run alone for bridge-only mode
+│   ├── MCP server             170+ tools over WebSocket / HTTP / stdio
+│   ├── VS Code extension      LSP, debugger, editor state, live diagnostics
+│   ├── Git / GitHub           gitCommit, gitPush, githubCreatePR, …
+│   ├── Terminal               runInTerminal, getTerminalOutput, …
+│   └── Code quality           auditDependencies, detectUnusedCode, getCodeCoverage
+│
+└── patchwork                  ← run for full Patchwork OS layer
+    ├── Recipe runner          YAML triggers → LLM prompt → action
+    ├── Connectors             Linear, Sentry, Slack, Google Calendar, +
+    ├── Orchestrator           Claude subprocess tasks, automation hooks
+    ├── Oversight inbox        ~/.patchwork/inbox/ — approval queue
+    └── Web dashboard          http://localhost:3200 — approvals, sessions, analytics
+```
+
+The npm package ships **three CLI binaries** that share the same code:
+
+| Binary | Default behavior |
+|---|---|
+| `claude-ide-bridge` | Bridge only — no automation, no recipe runner, no dashboard |
+| `patchwork` | Full Patchwork OS — automation + recipes + dashboard |
+| `patchwork-os` | Alias for `patchwork` |
+
+Use whichever fits your mental model.
+
+---
+
+## Tool surface (v0.2.0-beta.0)
+
+170+ MCP tools across 15 categories. Highlights:
+
+| Category | Tools |
+|---|---|
+| LSP / Code Intelligence | `getDiagnostics`, `goToDefinition`, `findReferences`, `getCallHierarchy`, `renameSymbol`, `refactorAnalyze`, `explainSymbol`, … (37 tools) |
+| Git | `getGitStatus`, `getGitDiff`, `gitCommit`, `gitPush`, `gitCheckout`, `gitBlame`, … (16 tools) |
+| GitHub | `githubCreatePR`, `githubListPRs`, `githubCreateIssue`, `githubPostPRReview`, … (13 tools) |
+| Terminal | `runInTerminal`, `createTerminal`, `getTerminalOutput`, `waitForTerminalOutput` |
+| File Operations | `editText`, `searchAndReplace`, `searchWorkspace`, `findFiles`, `getFileTree`, … |
+| Debugger | `setDebugBreakpoints`, `startDebugging`, `evaluateInDebugger` |
+| Orchestrator | `runClaudeTask`, `listClaudeTasks`, `getClaudeTaskStatus` |
+| Context Platform | `ctxGetTaskContext`, `ctxQueryTraces`, `ctxSaveTrace`, `enrichStackTrace` |
+
+Full reference: [documents/platform-docs.md](documents/platform-docs.md)
+
+---
+
+## Plugin system
+
+Extend the tool surface without forking the bridge.
+
+```bash
+# Scaffold a new plugin
+patchwork gen-plugin-stub ./my-plugin --name "org/name" --prefix "myPrefix"
+
+# Load at runtime
+claude-ide-bridge --plugin ./my-plugin
+```
+
+Plugins register MCP tools in-process. With `--plugin-watch`, the bridge reloads them on save — Claude can write a tool *during* a session and use it on the next turn. See [documents/live-toolsmithing.md](documents/live-toolsmithing.md) for the worked walkthrough and [examples/plugins/sqlite-library/](examples/plugins/sqlite-library/) for a runnable example.
+
+Publish to npm with keyword `claude-ide-bridge-plugin` for distribution.
+
+Full reference: [documents/plugin-authoring.md](documents/plugin-authoring.md)
+
+---
+
+## JetBrains plugin
+
+Companion IntelliJ plugin (v1.0.0) on the JetBrains Marketplace. Covers 49 handlers: core tools, PSI-based LSP (goto, references, hover, rename, symbols, format), XDebugger integration, and code style tools.
+
+Use the same bridge from VS Code and JetBrains IDEs simultaneously — IntelliJ IDEA, PyCharm, GoLand, WebStorm, and other IntelliJ-platform editors.
+
+Source: [intellij-plugin/](intellij-plugin/)
+
+---
+
+## Remote deployment
+
+Run headless on a VPS with full tool support via VS Code Remote-SSH.
+
+```bash
+claude-ide-bridge --bind 0.0.0.0 \
+  --issuer-url https://your-domain.com \
+  --fixed-token <uuid> \
+  --vps
+```
+
+Systemd service and deploy scripts in [`deploy/`](deploy/). Full guide: [docs/remote-access.md](docs/remote-access.md).
+
+---
+
+## What's shipped
+
+| Feature | Status |
+|---|---|
+| 170+ MCP tools (LSP, git, tests, debugger, diagnostics) | **shipped** |
+| VS Code / Cursor / Windsurf / Antigravity extension | **shipped** |
+| JetBrains plugin (49 handlers) | **shipped** |
+| `patchwork-init` — one-command setup | **shipped** |
+| Terminal dashboard | **shipped** |
+| Web oversight UI (approvals, sessions, recipes) | **shipped** |
+| Recipe runner (YAML, cron, manual, webhook) | **shipped** |
+| Multi-provider LLM (Claude, Gemini, OpenAI, Grok, Ollama) | **shipped** |
+| Connectors: Linear, Sentry, Slack, Google Calendar, Intercom, HubSpot, Datadog, Stripe | **shipped** |
+| Cross-session memory (traces, handoff notes) | **shipped** |
+| Mobile oversight PWA (push approvals) | **shipped (beta)** |
+| Community recipe marketplace | Q3 2026 |
+
+---
+
+## Install from source
 
 ```bash
 git clone https://github.com/Oolab-labs/patchwork-os
 cd patchwork-os
 npm install && npm run build
-node dist/index.js patchwork-init
+
+# Pack first — do NOT use `npm install -g .`
+# Symlink installs break the macOS LaunchAgent (EPERM at startup)
+npm pack
+npm install -g patchwork-os-*.tgz
+patchwork patchwork-init
 ```
 
+---
+
+## Documentation
+
+| Doc | Contents |
+|---|---|
+| [documents/platform-docs.md](documents/platform-docs.md) | Full tool reference (170+ tools), automation hooks, connectors |
+| [documents/prompts-reference.md](documents/prompts-reference.md) | All 72 MCP prompts |
+| [documents/styleguide.md](documents/styleguide.md) | Code conventions, UI patterns |
+| [documents/roadmap.md](documents/roadmap.md) | Development direction |
+| [documents/data-reference.md](documents/data-reference.md) | Data flows, state management, protocol details |
+| [documents/plugin-authoring.md](documents/plugin-authoring.md) | Plugin manifest schema, entrypoint API, distribution |
+| [documents/live-toolsmithing.md](documents/live-toolsmithing.md) | Write tools while the AI is using them — hot-reload narrative + worked example |
+| [documents/triggers.md](documents/triggers.md) | Anything Can Trigger Your AI — iPhone Shortcuts, Stream Deck, Home Assistant, curl, GitHub Actions |
+| [documents/speculative-refactoring.md](documents/speculative-refactoring.md) | Stage multi-file edits, review the diff, commit or discard — honest about commit-phase semantics |
+| [documents/architecture.md](documents/architecture.md) | One-page architecture diagram + how to read it |
+| [documents/comparison.md](documents/comparison.md) | Patchwork vs MCP server / Zapier / hosted assistants / agent frameworks — honest tradeoffs |
+| [docs/adr/](docs/adr/) | Architecture Decision Records |
+| [docs/remote-access.md](docs/remote-access.md) | VPS deployment guide |
+
+---
+
 ## License
 
-MIT © Oolab Labs. Built on the [Claude IDE Bridge](./README.bridge.md).
+MIT © Oolab Labs

package/deploy/bootstrap-new-vps.sh

@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
 # deploy/bootstrap-new-vps.sh
-# Full fresh-server setup for claude-ide-bridge on a NEW VPS.
+# Full fresh-server setup for patchwork-os on a NEW VPS.
 # Handles everything from Node.js install to running HTTPS service.
 #
 # Usage (run as root on a fresh Ubuntu 22.04/24.04 VPS):
-#   curl -fsSL https://raw.githubusercontent.com/Oolab-labs/claude-ide-bridge/main/deploy/bootstrap-new-vps.sh | \
+#   curl -fsSL https://raw.githubusercontent.com/Oolab-labs/patchwork-os/main/deploy/bootstrap-new-vps.sh | \
 #     DOMAIN=bridge.example.com bash
 #
 #   Or after cloning:
@@ -14,9 +14,9 @@
 #   DOMAIN        Subdomain for the bridge  (e.g. bridge.example.com)
 #
 # Optional environment variables:
-#   REPO_URL      Git repo URL              (default: https://github.com/Oolab-labs/claude-ide-bridge)
-#   INSTALL_DIR   Where to clone the repo   (default: /opt/claude-ide-bridge)
-#   SERVICE_USER  System user to run bridge (default: claude-bridge)
+#   REPO_URL      Git repo URL              (default: https://github.com/Oolab-labs/patchwork-os)
+#   INSTALL_DIR   Where to clone the repo   (default: /opt/patchwork-os)
+#   SERVICE_USER  System user to run bridge (default: patchwork)
 #   PORT          Bridge port               (default: 9000)
 #   BRANCH        Git branch to clone       (default: main)
 #   SKIP_CERTBOT  Set to 1 to skip TLS cert (useful if DNS not yet set)
@@ -25,13 +25,13 @@ set -euo pipefail
 
 # ── Config ────────────────────────────────────────────────────────────────────
 DOMAIN="${DOMAIN:-}"
-REPO_URL="${REPO_URL:-https://github.com/Oolab-labs/claude-ide-bridge}"
-INSTALL_DIR="${INSTALL_DIR:-/opt/claude-ide-bridge}"
-SERVICE_USER="${SERVICE_USER:-claude-bridge}"
+REPO_URL="${REPO_URL:-https://github.com/Oolab-labs/patchwork-os}"
+INSTALL_DIR="${INSTALL_DIR:-/opt/patchwork-os}"
+SERVICE_USER="${SERVICE_USER:-patchwork}"
 PORT="${PORT:-9000}"
 BRANCH="${BRANCH:-main}"
 SKIP_CERTBOT="${SKIP_CERTBOT:-0}"
-SERVICE_NAME="claude-ide-bridge"
+SERVICE_NAME="patchwork-os"
 
 RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
 info()    { echo -e "${GREEN}✓${NC} $*"; }
@@ -163,8 +163,8 @@ section "Systemd service"
 # Generate service file from template (parameterised for this install)
 cat > "/etc/systemd/system/${SERVICE_NAME}.service" <<SERVICE
 [Unit]
-Description=Claude IDE Bridge MCP Server
-Documentation=https://github.com/Oolab-labs/claude-ide-bridge
+Description=Patchwork OS bridge
+Documentation=https://github.com/Oolab-labs/patchwork-os
 After=network.target
 StartLimitIntervalSec=120
 StartLimitBurst=5
@@ -193,7 +193,7 @@ RestartSec=5
 
 StandardOutput=journal
 StandardError=journal
-SyslogIdentifier=claude-ide-bridge
+SyslogIdentifier=patchwork-os
 
 NoNewPrivileges=true
 PrivateTmp=true

package/deploy/bootstrap-vps.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+# deploy/bootstrap-vps.sh
+# Full VPS bootstrap for patchworkos.com
+# Run as root on a fresh Ubuntu 24.04 VPS
+# Usage: bash bootstrap-vps.sh
+
+set -euo pipefail
+
+DOMAIN="patchworkos.com"
+EMAIL="support@gigsecure.co.ke"
+BRIDGE_PORT=3284
+BRIDGE_USER="patchwork"
+BRIDGE_HOME="/opt/patchwork"
+NODE_VERSION="22"
+
+# ── Colours ──────────────────────────────────────────────────────────────────
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+info()  { echo -e "${GREEN}[bootstrap]${NC} $*"; }
+warn()  { echo -e "${YELLOW}[bootstrap]${NC} $*"; }
+error() { echo -e "${RED}[bootstrap]${NC} $*"; exit 1; }
+
+# ── 1. System updates ─────────────────────────────────────────────────────────
+info "Updating system packages..."
+apt-get update -qq
+apt-get upgrade -y -qq
+apt-get install -y -qq curl wget gnupg2 ca-certificates lsb-release \
+  nginx certbot python3-certbot-nginx ufw git jq unzip
+
+# ── 2. Node.js ────────────────────────────────────────────────────────────────
+info "Installing Node.js ${NODE_VERSION}..."
+curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - >/dev/null
+apt-get install -y -qq nodejs
+node --version
+npm --version
+
+# ── 3. Service user ───────────────────────────────────────────────────────────
+info "Creating service user '${BRIDGE_USER}'..."
+id "${BRIDGE_USER}" &>/dev/null || useradd -r -m -d "${BRIDGE_HOME}" -s /bin/bash "${BRIDGE_USER}"
+mkdir -p "${BRIDGE_HOME}"
+chown "${BRIDGE_USER}:${BRIDGE_USER}" "${BRIDGE_HOME}"
+
+# ── 4. Install bridge globally ────────────────────────────────────────────────
+info "Installing patchwork-os from npm..."
+npm install -g patchwork-os@alpha 2>&1 | tail -5
+# `patchwork-os` ships three bin aliases: `patchwork` (preferred),
+# `patchwork-os`, and the legacy `claude-ide-bridge`. Use the canonical
+# `patchwork` name for the systemd unit + nginx config below.
+BRIDGE_BIN="$(which patchwork)"
+info "Bridge binary: ${BRIDGE_BIN}"
+
+# ── 5. Generate fixed token ───────────────────────────────────────────────────
+FIXED_TOKEN="$(uuidgen | tr '[:upper:]' '[:lower:]')"
+info "Generated bridge token (save this!): ${FIXED_TOKEN}"
+
+# Persist token to a file readable only by root + patchwork user
+TOKEN_FILE="/etc/patchwork/bridge-token"
+mkdir -p /etc/patchwork
+echo "${FIXED_TOKEN}" > "${TOKEN_FILE}"
+chown root:"${BRIDGE_USER}" "${TOKEN_FILE}"
+chmod 640 "${TOKEN_FILE}"
+
+# ── 6. Systemd service ────────────────────────────────────────────────────────
+info "Writing systemd service..."
+cat > /etc/systemd/system/patchwork-bridge.service <<EOF
+[Unit]
+Description=Patchwork OS — Claude IDE Bridge
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${BRIDGE_USER}
+Group=${BRIDGE_USER}
+WorkingDirectory=${BRIDGE_HOME}
+Environment=NODE_ENV=production
+Environment=HOME=${BRIDGE_HOME}
+
+ExecStart=${BRIDGE_BIN} \\
+  --bind 0.0.0.0 \\
+  --port ${BRIDGE_PORT} \\
+  --vps \\
+  --issuer-url https://${DOMAIN} \\
+  --cors-origin https://claude.ai \\
+  --cors-origin https://app.patchworkos.com \\
+  --fixed-token ${FIXED_TOKEN}
+
+Restart=always
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=patchwork-bridge
+
+# Hardening
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=${BRIDGE_HOME}
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable patchwork-bridge
+
+# ── 7. UFW firewall ───────────────────────────────────────────────────────────
+info "Configuring firewall..."
+ufw --force reset >/dev/null
+ufw default deny incoming >/dev/null
+ufw default allow outgoing >/dev/null
+ufw allow ssh >/dev/null
+ufw allow http >/dev/null
+ufw allow https >/dev/null
+ufw --force enable >/dev/null
+ufw status
+
+# ── 8. Nginx config — HTTP only first (certbot needs nginx up to issue cert) ──
+info "Writing nginx config (HTTP only)..."
+cat > /etc/nginx/sites-available/patchworkos <<'NGINX'
+server {
+    listen 80;
+    listen [::]:80;
+    server_name patchworkos.com www.patchworkos.com;
+
+    location /.well-known/acme-challenge/ { root /var/www/html; }
+
+    location / {
+        proxy_pass         http://127.0.0.1:3284;
+        proxy_http_version 1.1;
+        proxy_set_header   Upgrade $http_upgrade;
+        proxy_set_header   Connection "upgrade";
+        proxy_set_header   Host $host;
+        proxy_set_header   X-Real-IP $remote_addr;
+        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+}
+NGINX
+
+ln -sf /etc/nginx/sites-available/patchworkos /etc/nginx/sites-enabled/patchworkos
+rm -f /etc/nginx/sites-enabled/default
+
+nginx -t
+systemctl reload nginx
+
+# ── 9. TLS certificate ────────────────────────────────────────────────────────
+info "Issuing Let's Encrypt certificate for ${DOMAIN}..."
+certbot --nginx \
+  -d "${DOMAIN}" \
+  -d "www.${DOMAIN}" \
+  --non-interactive \
+  --agree-tos \
+  --email "${EMAIL}" \
+  --redirect
+
+# Certbot rewrites the nginx config with SSL — reload to apply
+systemctl reload nginx
+
+# ── 10. Start bridge ──────────────────────────────────────────────────────────
+info "Starting bridge service..."
+systemctl start patchwork-bridge
+sleep 3
+systemctl is-active patchwork-bridge && info "Bridge is running." || warn "Bridge may have failed — check: journalctl -u patchwork-bridge -n 50"
+
+# ── 11. Print summary ─────────────────────────────────────────────────────────
+echo ""
+echo -e "${GREEN}═══════════════════════════════════════════════════${NC}"
+echo -e "${GREEN}  Patchwork OS — VPS bootstrap complete${NC}"
+echo -e "${GREEN}═══════════════════════════════════════════════════${NC}"
+echo ""
+echo "  Domain:       https://${DOMAIN}"
+echo "  Bridge port:  ${BRIDGE_PORT} (internal, nginx proxied)"
+echo "  Token file:   ${TOKEN_FILE}"
+echo "  Token:        ${FIXED_TOKEN}"
+echo ""
+echo "  Service:      systemctl status patchwork-bridge"
+echo "  Logs:         journalctl -u patchwork-bridge -f"
+echo "  Nginx logs:   tail -f /var/log/nginx/access.log"
+echo ""
+echo -e "${YELLOW}  Save the token above — you'll need it to connect Claude Code.${NC}"
+echo ""
+echo "  To connect Claude Code remotely:"
+echo "    claude mcp add patchwork https://${DOMAIN}/mcp --token ${FIXED_TOKEN}"
+echo ""