From 3f391183f1e6909b34761522cfe92e4d8e575c14 Mon Sep 17 00:00:00 2001 From: Adrian Stanca Date: Tue, 21 Apr 2026 16:11:13 +0100 Subject: [PATCH 1/4] =?UTF-8?q?feat:=20deploy=20paths=20=E2=80=94=20script?= =?UTF-8?q?s,=20npm=20scripts,=20and=20docs/deploy.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add deploy-from-source.sh (pack, link, global, registry) and package.json deploy:* scripts. Document all install/publish options in docs/deploy.md; link from README, advanced-setup, AGENTS; ignore npm pack tarballs. Made-with: Cursor --- .gitignore | 2 + AGENTS.md | 5 ++- README.md | 4 +- docs/advanced-setup.md | 2 + docs/deploy.md | 85 +++++++++++++++++++++++++++++++++++ package.json | 4 ++ scripts/deploy-from-source.sh | 39 ++++++++++++++++ 7 files changed, 139 insertions(+), 2 deletions(-) create mode 100644 docs/deploy.md create mode 100755 scripts/deploy-from-source.sh diff --git a/.gitignore b/.gitignore index 6ae40bc368..eac54aa43d 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,5 @@ CLAUDE.md package-lock.json /.claude coverage/ +# npm pack output from deploy:pack / scripts/deploy-from-source.sh pack +gitlawb-openclaude-*.tgz diff --git a/AGENTS.md b/AGENTS.md index bd5daa2490..3a6af36b31 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,4 +54,7 @@ This repository **does not** ship editor-only trees (for example `.cursor/` or t ## Further reading - [docs/agent-workflow.md](docs/agent-workflow.md) — repository map, local OpenAI-compatible servers, browser CORS, fork sync. -- [Hermes agent `AGENTS.md`](https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md) — example of a deeper, project-wide agent guide (structure reference only). +- **Deploy / install:** [docs/deploy.md](docs/deploy.md) (registry, source, tarball, upstream release, fork npm). +- **Hermes / Nous:** [hermes-agent `AGENTS.md`](https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md) (structure and depth) and [FAQ & troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) (operators, browser UIs, gateways). +- **Human-facing docs:** `README.md`, `docs/`, `SECURITY.md` + diff --git a/README.md b/README.md index d623ce0b62..aeaf9c23af 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Use OpenAI-compatible APIs, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, A OpenClaude is also mirrored to GitLawb: [gitlawb.com/node/repos/z6MkqDnb/openclaude](https://gitlawb.com/node/repos/z6MkqDnb/openclaude) -[Quick Start](#quick-start) | [Setup Guides](#setup-guides) | [Providers](#supported-providers) | [Source Build](#source-build-and-local-development) | [VS Code Extension](#vs-code-extension) | [Community](#community) +[Quick Start](#quick-start) | [Deploy / install](docs/deploy.md) | [Setup Guides](#setup-guides) | [Providers](#supported-providers) | [Source Build](#source-build-and-local-development) | [VS Code Extension](#vs-code-extension) | [Community](#community) ## Star History @@ -35,6 +35,8 @@ OpenClaude is also mirrored to GitLawb: npm install -g @gitlawb/openclaude ``` +For **every install path** (registry, global from git, `npm pack`, `npm link`, upstream releases, fork publishing notes), see **[docs/deploy.md](docs/deploy.md)**. + If the install later reports `ripgrep not found`, install ripgrep system-wide and confirm `rg --version` works in the same terminal before starting OpenClaude. ### Start diff --git a/docs/advanced-setup.md b/docs/advanced-setup.md index 291aee7d7b..20bfcbcbf5 100644 --- a/docs/advanced-setup.md +++ b/docs/advanced-setup.md @@ -4,6 +4,8 @@ This guide is for users who want source builds, Bun workflows, provider profiles ## Install Options +See **[deploy.md](./deploy.md)** for a single index of registry install, `npm pack`, `npm link`, global install from a checkout, upstream CI publish, and fork-scoped npm. + ### Option A: npm ```bash diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 0000000000..f8b0747f37 --- /dev/null +++ b/docs/deploy.md @@ -0,0 +1,85 @@ +# Deploy and install OpenClaude + +This document covers every supported way to get **`openclaude`** onto a machine: from npm, from a source checkout, as a tarball, and how **upstream** publishes. Fork maintainers: see **Fork-scoped npm** at the end. + +## 1. Install from npm (recommended for users) + +Uses the package published by maintainers (`@gitlawb/openclaude`). + +```bash +npm install -g @gitlawb/openclaude@latest +openclaude --version +``` + +From the repo you can run the same via: + +```bash +bun run deploy:registry +# equivalent: ./scripts/deploy-from-source.sh registry +``` + +## 2. Global install from a git checkout + +After cloning, install dependencies, build the bundle, then install globally from the current directory. + +```bash +cd openclaude +bun install --frozen-lockfile +bun run deploy:install-global +# equivalent: ./scripts/deploy-from-source.sh global +``` + +Requires **Bun** and **npm**. This installs whatever version is in **`package.json`** (e.g. `0.4.0`). + +## 3. Development link (`npm link`) + +Keeps `openclaude` pointing at your working tree (good for active development). + +```bash +bun install --frozen-lockfile +bun run deploy:link +# equivalent: ./scripts/deploy-from-source.sh link +``` + +## 4. Pack a tarball (CI, air-gapped, or manual install) + +`npm pack` runs **`prepack`** → **`npm run build`**, so you get a built tarball without a separate build step. + +```bash +bun install --frozen-lockfile +bun run deploy:pack +# equivalent: ./scripts/deploy-from-source.sh pack +``` + +Install elsewhere: + +```bash +npm install -g ./gitlawb-openclaude-0.4.0.tgz +``` + +(Version in the filename follows **`package.json`**.) + +## 5. Upstream automated release (GitHub + npm + GHCR) + +On **`Gitlawb/openclaude`** only, pushing to **`main`** runs **Release Please**. When it opens and merges a release PR and creates a tag, CI publishes: + +- **`npm publish`** for `@gitlawb/openclaude` (with provenance) +- **Docker** image to `ghcr.io/gitlawb/openclaude` + +Forks (`github.repository != 'Gitlawb/openclaude'`) do **not** run that workflow gate—see `.github/workflows/release.yml` `if:` conditions. + +## 6. Fork-scoped npm package (optional) + +To publish **your fork** under your own scope (example: `@myuser/openclaude`): + +1. Change **`package.json`** field **`name`** to your scope (and update **`bin`** / docs references if you rename the CLI—non-trivial). +2. Ensure **`publishConfig.access`** matches your registry policy. +3. `npm login` and **`npm publish --access public`** from a clean **`bun run build`** tree. + +Do not publish to **`@gitlawb`** unless you are a maintainer with npm access. Prefer contributing upstream and using the **registry install** or **upstream automated release** paths above for end users. + +## See also + +- [Advanced setup](./advanced-setup.md) — source builds, `npm link`, providers. +- [README](../README.md) — quick start and links. +- [SECURITY.md](../SECURITY.md) — release and disclosure policy. diff --git a/package.json b/package.json index f7cfe07440..e04ae83abe 100644 --- a/package.json +++ b/package.json @@ -48,6 +48,10 @@ "doctor:report": "bun run scripts/system-check.ts --out reports/doctor-runtime.json", "hardening:check": "bun run smoke && bun run doctor:runtime", "hardening:strict": "bun run typecheck && bun run hardening:check", + "deploy:pack": "./scripts/deploy-from-source.sh pack", + "deploy:link": "./scripts/deploy-from-source.sh link", + "deploy:install-global": "./scripts/deploy-from-source.sh global", + "deploy:registry": "./scripts/deploy-from-source.sh registry", "prepack": "npm run build" }, "dependencies": { diff --git a/scripts/deploy-from-source.sh b/scripts/deploy-from-source.sh new file mode 100755 index 0000000000..b076811638 --- /dev/null +++ b/scripts/deploy-from-source.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# Install OpenClaude from a git checkout: pack tarball, npm link, global install, +# or refresh from the public registry. Run from repo root or via package.json scripts. +set -euo pipefail +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +cd "$ROOT" + +usage() { + echo "Usage: $0 {pack|link|global|registry}" >&2 + echo " pack — bun install, npm pack (prepack runs build → .tgz in repo root)" >&2 + echo " link — bun install, build, npm link (dev symlink)" >&2 + echo " global — bun install, build, npm install -g . (global openclaude from this tree)" >&2 + echo " registry — npm install -g @gitlawb/openclaude@latest (official publish)" >&2 + exit 1 +} + +MODE="${1:-}" +case "$MODE" in +pack) + bun install --frozen-lockfile + npm pack + ;; +link) + bun install --frozen-lockfile + bun run build + npm link + ;; +global) + bun install --frozen-lockfile + bun run build + npm install -g . + ;; +registry) + npm install -g @gitlawb/openclaude@latest + ;; +*) + usage + ;; +esac From 6d58c6fe5a9fb471a50b963a623e4d043b60f94c Mon Sep 17 00:00:00 2001 From: Adrian Stanca Date: Tue, 21 Apr 2026 17:21:55 +0100 Subject: [PATCH 2/4] =?UTF-8?q?chore:=20deploy=20polish=20=E2=80=94=20bash?= =?UTF-8?q?=20scripts,=20help=20mode,=20VS=20Code=20tasks,=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Made-with: Cursor --- .vscode/tasks.json | 74 +++++++++++++++++++++++++++++++++++ AGENTS.md | 2 + docs/deploy.md | 11 ++++++ package.json | 8 ++-- scripts/deploy-from-source.sh | 13 +++++- 5 files changed, 102 insertions(+), 6 deletions(-) create mode 100644 .vscode/tasks.json diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000000..9f27e9e1d6 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,74 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "OpenClaude: smoke", + "type": "shell", + "command": "${workspaceFolder}/scripts/cursor-dev-path.sh bun run smoke", + "group": { + "kind": "test", + "isDefault": true + }, + "presentation": { + "reveal": "always", + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "OpenClaude: unit tests", + "type": "shell", + "command": "${workspaceFolder}/scripts/cursor-dev-path.sh bun test --max-concurrency=1", + "group": "test", + "presentation": { + "reveal": "always", + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "OpenClaude: provider tests", + "type": "shell", + "command": "${workspaceFolder}/scripts/cursor-dev-path.sh bun run test:provider", + "group": "test", + "presentation": { + "reveal": "always", + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "OpenClaude: runtime doctor", + "type": "shell", + "command": "${workspaceFolder}/scripts/cursor-dev-path.sh bun run doctor:runtime", + "group": "test", + "presentation": { + "reveal": "always", + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "OpenClaude: deploy pack", + "type": "shell", + "command": "${workspaceFolder}/scripts/cursor-dev-path.sh bash scripts/deploy-from-source.sh pack", + "group": "build", + "presentation": { + "reveal": "always", + "panel": "shared" + }, + "problemMatcher": [] + }, + { + "label": "OpenClaude: deploy link", + "type": "shell", + "command": "${workspaceFolder}/scripts/cursor-dev-path.sh bash scripts/deploy-from-source.sh link", + "group": "build", + "presentation": { + "reveal": "always", + "panel": "shared" + }, + "problemMatcher": [] + } + ] +} diff --git a/AGENTS.md b/AGENTS.md index 3a6af36b31..af767cf718 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,6 +38,8 @@ Pick the **narrowest** check that covers your change. When in doubt, at least `b | Provider recommendation tests | `bun run test:provider-recommendation` | | Stricter gate (typecheck + smoke + runtime doctor) | `bun run hardening:strict` | | Runtime / profile diagnostics | `bun run doctor:runtime` | +| Pack tarball from checkout | `bun run deploy:pack` (see `docs/deploy.md`) | +| Install / link / registry deploy paths | `docs/deploy.md`; `bun run deploy:*` | CI runs **PR Checks** on GitHub; align with those workflows when you touch packaging, entrypoints, or core paths. diff --git a/docs/deploy.md b/docs/deploy.md index f8b0747f37..9b75d08cd6 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -2,6 +2,17 @@ This document covers every supported way to get **`openclaude`** onto a machine: from npm, from a source checkout, as a tarball, and how **upstream** publishes. Fork maintainers: see **Fork-scoped npm** at the end. +## Quick reference (`package.json`) + +| Script | Equivalent shell | +|--------|-------------------| +| `bun run deploy:registry` | `bash scripts/deploy-from-source.sh registry` | +| `bun run deploy:install-global` | `bash scripts/deploy-from-source.sh global` | +| `bun run deploy:link` | `bash scripts/deploy-from-source.sh link` | +| `bun run deploy:pack` | `bash scripts/deploy-from-source.sh pack` | + +Run `bash scripts/deploy-from-source.sh help` for the same usage text. Palette tasks **OpenClaude: deploy pack** / **OpenClaude: deploy link** live in `.vscode/tasks.json` (PATH via `cursor-dev-path.sh`). + ## 1. Install from npm (recommended for users) Uses the package published by maintainers (`@gitlawb/openclaude`). diff --git a/package.json b/package.json index e04ae83abe..127857c802 100644 --- a/package.json +++ b/package.json @@ -48,10 +48,10 @@ "doctor:report": "bun run scripts/system-check.ts --out reports/doctor-runtime.json", "hardening:check": "bun run smoke && bun run doctor:runtime", "hardening:strict": "bun run typecheck && bun run hardening:check", - "deploy:pack": "./scripts/deploy-from-source.sh pack", - "deploy:link": "./scripts/deploy-from-source.sh link", - "deploy:install-global": "./scripts/deploy-from-source.sh global", - "deploy:registry": "./scripts/deploy-from-source.sh registry", + "deploy:pack": "bash scripts/deploy-from-source.sh pack", + "deploy:link": "bash scripts/deploy-from-source.sh link", + "deploy:install-global": "bash scripts/deploy-from-source.sh global", + "deploy:registry": "bash scripts/deploy-from-source.sh registry", "prepack": "npm run build" }, "dependencies": { diff --git a/scripts/deploy-from-source.sh b/scripts/deploy-from-source.sh index b076811638..43b1c3c7b9 100755 --- a/scripts/deploy-from-source.sh +++ b/scripts/deploy-from-source.sh @@ -6,16 +6,24 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$ROOT" usage() { - echo "Usage: $0 {pack|link|global|registry}" >&2 + echo "Usage: $0 {pack|link|global|registry|help}" >&2 echo " pack — bun install, npm pack (prepack runs build → .tgz in repo root)" >&2 echo " link — bun install, build, npm link (dev symlink)" >&2 echo " global — bun install, build, npm install -g . (global openclaude from this tree)" >&2 echo " registry — npm install -g @gitlawb/openclaude@latest (official publish)" >&2 - exit 1 + echo " help — print this message and exit 0" >&2 } MODE="${1:-}" case "$MODE" in +help) + usage + exit 0 + ;; +"") + usage + exit 1 + ;; pack) bun install --frozen-lockfile npm pack @@ -35,5 +43,6 @@ registry) ;; *) usage + exit 1 ;; esac From 13c624a69b58215ace318471ba02b39381beb609 Mon Sep 17 00:00:00 2001 From: Adrian Stanca Date: Tue, 21 Apr 2026 20:04:04 +0100 Subject: [PATCH 3/4] docs: streamline AGENTS further reading and README links Made-with: Cursor --- AGENTS.md | 7 +------ README.md | 4 +--- 2 files changed, 2 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index af767cf718..bd5daa2490 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,8 +38,6 @@ Pick the **narrowest** check that covers your change. When in doubt, at least `b | Provider recommendation tests | `bun run test:provider-recommendation` | | Stricter gate (typecheck + smoke + runtime doctor) | `bun run hardening:strict` | | Runtime / profile diagnostics | `bun run doctor:runtime` | -| Pack tarball from checkout | `bun run deploy:pack` (see `docs/deploy.md`) | -| Install / link / registry deploy paths | `docs/deploy.md`; `bun run deploy:*` | CI runs **PR Checks** on GitHub; align with those workflows when you touch packaging, entrypoints, or core paths. @@ -56,7 +54,4 @@ This repository **does not** ship editor-only trees (for example `.cursor/` or t ## Further reading - [docs/agent-workflow.md](docs/agent-workflow.md) — repository map, local OpenAI-compatible servers, browser CORS, fork sync. -- **Deploy / install:** [docs/deploy.md](docs/deploy.md) (registry, source, tarball, upstream release, fork npm). -- **Hermes / Nous:** [hermes-agent `AGENTS.md`](https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md) (structure and depth) and [FAQ & troubleshooting](https://hermes-agent.nousresearch.com/docs/reference/faq) (operators, browser UIs, gateways). -- **Human-facing docs:** `README.md`, `docs/`, `SECURITY.md` - +- [Hermes agent `AGENTS.md`](https://github.com/NousResearch/hermes-agent/blob/main/AGENTS.md) — example of a deeper, project-wide agent guide (structure reference only). diff --git a/README.md b/README.md index aeaf9c23af..d623ce0b62 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Use OpenAI-compatible APIs, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, A OpenClaude is also mirrored to GitLawb: [gitlawb.com/node/repos/z6MkqDnb/openclaude](https://gitlawb.com/node/repos/z6MkqDnb/openclaude) -[Quick Start](#quick-start) | [Deploy / install](docs/deploy.md) | [Setup Guides](#setup-guides) | [Providers](#supported-providers) | [Source Build](#source-build-and-local-development) | [VS Code Extension](#vs-code-extension) | [Community](#community) +[Quick Start](#quick-start) | [Setup Guides](#setup-guides) | [Providers](#supported-providers) | [Source Build](#source-build-and-local-development) | [VS Code Extension](#vs-code-extension) | [Community](#community) ## Star History @@ -35,8 +35,6 @@ OpenClaude is also mirrored to GitLawb: npm install -g @gitlawb/openclaude ``` -For **every install path** (registry, global from git, `npm pack`, `npm link`, upstream releases, fork publishing notes), see **[docs/deploy.md](docs/deploy.md)**. - If the install later reports `ripgrep not found`, install ripgrep system-wide and confirm `rg --version` works in the same terminal before starting OpenClaude. ### Start From ce15290dacbbb7d3dcc7bc82084b1608dddd371f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 21 Apr 2026 23:24:56 +0000 Subject: [PATCH 4/4] docs(deploy): version-agnostic tarball example and bash equivalents Co-authored-by: adrian stanca --- docs/deploy.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/deploy.md b/docs/deploy.md index 9b75d08cd6..07453e7c28 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -26,7 +26,7 @@ From the repo you can run the same via: ```bash bun run deploy:registry -# equivalent: ./scripts/deploy-from-source.sh registry +# equivalent: bash scripts/deploy-from-source.sh registry ``` ## 2. Global install from a git checkout @@ -37,10 +37,10 @@ After cloning, install dependencies, build the bundle, then install globally fro cd openclaude bun install --frozen-lockfile bun run deploy:install-global -# equivalent: ./scripts/deploy-from-source.sh global +# equivalent: bash scripts/deploy-from-source.sh global ``` -Requires **Bun** and **npm**. This installs whatever version is in **`package.json`** (e.g. `0.4.0`). +Requires **Bun** and **npm**. This installs whatever **`version`** is set to in **`package.json`** at install time. ## 3. Development link (`npm link`) @@ -49,7 +49,7 @@ Keeps `openclaude` pointing at your working tree (good for active development). ```bash bun install --frozen-lockfile bun run deploy:link -# equivalent: ./scripts/deploy-from-source.sh link +# equivalent: bash scripts/deploy-from-source.sh link ``` ## 4. Pack a tarball (CI, air-gapped, or manual install) @@ -59,17 +59,16 @@ bun run deploy:link ```bash bun install --frozen-lockfile bun run deploy:pack -# equivalent: ./scripts/deploy-from-source.sh pack +# equivalent: bash scripts/deploy-from-source.sh pack ``` -Install elsewhere: +Install elsewhere (use the **exact** `.tgz` name printed by `npm pack`, or a glob that resolves to one file): ```bash -npm install -g ./gitlawb-openclaude-0.4.0.tgz +npm install -g ./gitlawb-openclaude-.tgz +# e.g. ./gitlawb-openclaude-0.5.2.tgz — the middle segment matches package.json "version" ``` -(Version in the filename follows **`package.json`**.) - ## 5. Upstream automated release (GitHub + npm + GHCR) On **`Gitlawb/openclaude`** only, pushing to **`main`** runs **Release Please**. When it opens and merges a release PR and creates a tag, CI publishes: