From 95d70d5865541975b0884025636f055513b5fd20 Mon Sep 17 00:00:00 2001 From: dtzp555 Date: Mon, 11 May 2026 04:11:55 +1000 Subject: [PATCH] =?UTF-8?q?docs(release):=20v3.15.0=20=E2=80=94=20README?= =?UTF-8?q?=20AI=20prompt=20blocks=20+=20Upgrading=20rewrite=20+=20CHANGEL?= =?UTF-8?q?OG?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §Installation, §Upgrading, §Troubleshooting each start with a copy-paste AI prompt block for Claude Code / Cursor / Copilot. The Upgrading section explains the three paths (light / full / fresh-install) and rollback usage. All Commands table gains an `ocp doctor` row. package.json bumped to 3.15.0. CHANGELOG.md gains the v3.15.0 entry covering doctor, the cross-version update path, --rollback, fresh-install routing, and AI prompt blocks. Notes the dependency on PR #90 (plist env merge bug fix, already merged). No cli.js citation needed: docs + version bump only, no server.mjs change. Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 33 +++++++++++++++++++++ README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++----- package.json | 2 +- 3 files changed, 111 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3afcc88..1ea0093 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,38 @@ # Changelog +## v3.15.0 — 2026-XX-XX (release date filled at tag time) + +### Features + +- **`ocp doctor`** — health & upgrade-readiness check; primary entry for AI-driven debugging. + `--json` mode emits a `next_action` with `ai_executable[]` for agents to run verbatim + and `human_required[]` for steps requiring the user (typically only OAuth). +- **`ocp update` cross-version path** — for cross-minor jumps (e.g. v3.10 → v3.14), + `ocp update` now runs doctor → snapshot → `setup.mjs` (with the plist env-merge from + PR #90) → service restart → post-flight `/health` + `/v1/models` verification. + Same-patch updates retain the existing light path; users see no change for routine + patch bumps. +- **`ocp update --rollback`** — restore the most recent (or specified) upgrade snapshot. + Snapshots are saved to `~/.ocp/upgrade-snapshot-/` and never auto-deleted. +- **Fresh-install routing** — `ocp update` on installations < v3.4.0 routes to a fresh-install + flow (with `--yes` to skip confirmation; AI agents pass this). OAuth survives via Claude + Code's credential store; users do not re-OAuth unless their token was independently broken. +- **AI prompt blocks in README** — §Installation, §Upgrading, and §Troubleshooting each + start with a copy-paste prompt for Claude Code / Cursor / Copilot, so users can drive + install / setup / upgrade through their existing AI assistant. + +### Behavior changes + +- `ocp update` may take 10–30s longer when a cross-minor jump triggers the full path + (snapshot + post-flight). Patch bumps are unchanged. +- Pre-v3.4.0 installs are routed to fresh-install rather than failing silently or + half-migrating. + +### Governance + +- No `cli.js` citation needed (no `server.mjs` change). ALIGNMENT.md Rule 2 not engaged. +- Depends on PR #90 (plist env merge bug fix; merged before this release). + ## v3.14.0 — 2026-05-10 ### Features (security hardening) diff --git a/README.md b/README.md index aa61049..79c749c 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,20 @@ Any tool that accepts `OPENAI_BASE_URL` works with OCP: ## Installation +The simplest path: ask your AI. + + Paste this prompt to Claude Code / Cursor / Copilot: + + ``` + Install OCP for me. Read README §Manual Installation and follow it. + Tell me when I need to run `claude auth login`. + ``` + +The AI will run `git clone`, `npm install`, `node setup.mjs`, and tell you +when to OAuth. + +### Manual Installation + OCP has two roles: **Server** (runs the proxy, needs Claude CLI) and **Client** (connects to a server, zero dependencies). ``` @@ -501,6 +515,7 @@ ocp keys List all API keys (multi mode) ocp keys add Create a new API key ocp keys revoke Revoke an API key ocp connect One-command LAN client setup +ocp doctor Health & upgrade-readiness check; primary entry for AI-driven debugging. --json produces a next_action for AI agents. ocp lan Show LAN connection info & IP ocp settings View tunable settings ocp settings Update a setting at runtime @@ -527,17 +542,57 @@ ocp --help > **Cloud/Linux servers:** If `ocp: command not found`, the binary isn't in PATH. Full path: `~/.openclaw/projects/ocp/ocp` -### Self-Update +## Upgrading + +The simplest path: ask your AI. + + Paste this prompt: + + ``` + Upgrade my OCP. Run `ocp update` and follow whatever it says. + If it tells me to run `claude auth login`, I'll do that. + ``` + +What `ocp update` does: + +- **Patch bump** (e.g. `v3.14.0 → v3.14.1`): + light path (git pull + npm install + restart). +- **Cross-minor** (e.g. `v3.10 → v3.14`): + full path: pre-flight check, snapshot, `setup.mjs` (with plist env-merge), + service restart, post-flight `/health` and `/v1/models` verification. +- **Old version** (< v3.4.0): + fresh-install. Pre-v3.4 lacked admin-key/usage-db, so there is nothing to + migrate. Your OAuth token (managed by the Claude Code CLI, not OCP) is + preserved; you do not need to re-OAuth unless your token expired + separately. + +Snapshots are saved to `~/.ocp/upgrade-snapshot-/` and never +auto-deleted. Clean old ones with `rm -rf ~/.ocp/upgrade-snapshot-*` once +you're confident the upgrade is stable. + +### Manual upgrade — same command, no AI ```bash -# Check if a new version is available -ocp update --check - -# Pull latest, sync plugin, restart proxy — one command -ocp update +ocp update # smart-pick path +ocp update --check # show available updates, don't apply +ocp update --dry-run # preview plan +ocp update --target v3.13.0 # pin a specific version +ocp update --rollback # restore most recent snapshot +ocp update --rollback --list +ocp update --rollback --dry-run ``` -`ocp update` runs (in order): `git pull` → `npm install` → plugin sync → **OpenClaw model registry sync** (v3.11.0+) → proxy restart → health check. +### When upgrade fails + +`ocp update` prints a recovery line on failure. To restore from the snapshot: + +```bash +ocp update --rollback +ocp doctor +``` + +If `ocp doctor` still reports problems after rollback, open a GitHub issue +with the snapshot path and the doctor JSON output (`ocp doctor --json`). ### OpenClaw Auto-Sync (v3.11.0+) @@ -710,6 +765,21 @@ After installing the gateway plugin, use `/ocp` slash commands in your chat: ## Troubleshooting +The simplest path: ask your AI. + + Paste this prompt: + + ``` + Run `ocp doctor` and follow its `next_action`. Tell me if you hit + anything that needs human input. + ``` + +The doctor produces a JSON `next_action` with `ai_executable[]` (commands +the agent runs verbatim) and `human_required[]` (steps that need you, +typically just OAuth). + +### Manual debugging + ### Setup fails with "claude: command not found" `setup.mjs` requires the Claude CLI to be on `PATH`. Install it via the [official guide](https://docs.anthropic.com/en/docs/claude-cli), confirm with `which claude`, then run `claude auth login` before re-running `node setup.mjs`. diff --git a/package.json b/package.json index 2545cc8..8451dd6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "open-claude-proxy", - "version": "3.14.0", + "version": "3.15.0", "description": "OCP (Open Claude Proxy) — use your Claude Pro/Max subscription as an OpenAI-compatible API for any IDE. Works with Cline, OpenCode, Aider, Continue.dev, OpenClaw, and more.", "type": "module", "bin": {