From 8fbf9861f14cb89789b8b1928a8966c14b96f318 Mon Sep 17 00:00:00 2001 From: meeech <4623+meeech@users.noreply.github.com> Date: Tue, 14 Apr 2026 00:31:35 -0400 Subject: [PATCH] docs: update documentation for pnpm migration Convert npm run/install/ci -> pnpm equivalents, npx -> pnpm exec, package-lock.json -> pnpm-lock.yaml across CLAUDE.md, groups/global/, docs/SPEC.md, docs/DEBUG_CHECKLIST.md, docs/BRANCH-FORK-MAINTENANCE.md, and docs/docker-sandboxes.md. Kept .npmrc and npm config references where they document real files. --- CLAUDE.md | 10 +++++----- docs/BRANCH-FORK-MAINTENANCE.md | 2 +- docs/DEBUG_CHECKLIST.md | 4 ++-- docs/SPEC.md | 4 ++-- docs/docker-sandboxes.md | 32 ++++++++++++++++---------------- groups/global/CLAUDE.md | 10 +++++----- 6 files changed, 31 insertions(+), 31 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d6552cb..cc4ea75 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -102,13 +102,13 @@ Before creating a PR, adding a skill, or preparing any contribution, you MUST re Run commands directly — don't tell the user to run them. ```bash -npm run dev # Host with hot reload -npm run build # Compile host TypeScript (src/) -./container/build.sh # Rebuild agent container image (nanoclaw-agent:latest) -npm test # Host tests +pnpm run dev # Host with hot reload +pnpm run build # Compile host TypeScript (src/) +./container/build.sh # Rebuild agent container image (nanoclaw-agent:latest) +pnpm test # Host tests ``` -Container typecheck is a separate tsconfig — if you edit `container/agent-runner/src/`, run `npx tsc -p container/agent-runner/tsconfig.json --noEmit` to check it. +Container typecheck is a separate tsconfig — if you edit `container/agent-runner/src/`, run `pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit` to check it. Service management: ```bash diff --git a/docs/BRANCH-FORK-MAINTENANCE.md b/docs/BRANCH-FORK-MAINTENANCE.md index 4891f38..3f2cf98 100644 --- a/docs/BRANCH-FORK-MAINTENANCE.md +++ b/docs/BRANCH-FORK-MAINTENANCE.md @@ -57,7 +57,7 @@ The same files conflict every time: | File | Resolution | |------|------------| | `package.json` | Take main's version + keep fork/branch-specific deps | -| `package-lock.json` | `git checkout main -- package-lock.json && npm install` | +| `pnpm-lock.yaml` | `git checkout main -- pnpm-lock.yaml && pnpm install` | | `.env.example` | Combine: main's entries + fork/branch-specific entries | | `repo-tokens/badge.svg` | Take main's version (auto-generated) | diff --git a/docs/DEBUG_CHECKLIST.md b/docs/DEBUG_CHECKLIST.md index a7b3de1..af4058a 100644 --- a/docs/DEBUG_CHECKLIST.md +++ b/docs/DEBUG_CHECKLIST.md @@ -148,7 +148,7 @@ grep 'QR\|authentication required\|qr' logs/nanoclaw.log | tail -5 ls -la store/auth/ # Re-authenticate if needed -npm run auth +pnpm run auth ``` ## Service Management @@ -167,5 +167,5 @@ launchctl bootout gui/$(id -u)/com.nanoclaw launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.nanoclaw.plist # Rebuild after code changes -npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw +pnpm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw ``` diff --git a/docs/SPEC.md b/docs/SPEC.md index 598f34e..687336f 100644 --- a/docs/SPEC.md +++ b/docs/SPEC.md @@ -404,7 +404,7 @@ Only the authentication variables (`CLAUDE_CODE_OAUTH_TOKEN` and `ANTHROPIC_API_ Set the `ASSISTANT_NAME` environment variable: ```bash -ASSISTANT_NAME=Bot npm start +ASSISTANT_NAME=Bot pnpm start ``` Or edit the default in `src/config.ts`. This changes: @@ -779,7 +779,7 @@ chmod 700 groups/ Run manually for verbose output: ```bash -npm run dev +pnpm run dev # or node dist/index.js ``` diff --git a/docs/docker-sandboxes.md b/docs/docker-sandboxes.md index e887bad..f4a666d 100644 --- a/docs/docker-sandboxes.md +++ b/docs/docker-sandboxes.md @@ -87,8 +87,8 @@ mv nanoclaw "$WORKSPACE/nanoclaw" cd "$WORKSPACE/nanoclaw" # Install dependencies -npm install -npm install https-proxy-agent +pnpm install +pnpm install https-proxy-agent ``` ## Step 4: Apply Proxy and Sandbox Patches @@ -97,7 +97,7 @@ NanoClaw needs several patches to work inside a Docker Sandbox. These handle pro ### 4a. Dockerfile — proxy args for container image build -`npm install` inside `docker build` fails with `SELF_SIGNED_CERT_IN_CHAIN` because the sandbox's MITM proxy presents its own certificate. Add proxy build args to `container/Dockerfile`: +`pnpm install` inside `docker build` fails with `SELF_SIGNED_CERT_IN_CHAIN` because the sandbox's MITM proxy presents its own certificate. Add proxy build args to `container/Dockerfile`: Add these lines after the `FROM` line: @@ -111,7 +111,7 @@ ARG npm_config_strict_ssl=true RUN npm config set strict-ssl ${npm_config_strict_ssl} ``` -And after the `RUN npm install` line: +And after the `RUN pnpm install` line: ```dockerfile RUN npm config set strict-ssl true @@ -185,7 +185,7 @@ Patch `setup/container.ts` to pass the same proxy `--build-arg` flags as `build. ## Step 5: Build ```bash -npm run build +pnpm run build bash container/build.sh ``` @@ -195,10 +195,10 @@ bash container/build.sh ```bash # Apply the Telegram skill -npx tsx scripts/apply-skill.ts .claude/skills/add-telegram +pnpm exec tsx scripts/apply-skill.ts .claude/skills/add-telegram # Rebuild after applying the skill -npm run build +pnpm run build # Configure .env cat > .env << EOF @@ -209,7 +209,7 @@ EOF mkdir -p data/env && cp .env data/env/env # Register your chat -npx tsx setup/index.ts --step register \ +pnpm exec tsx setup/index.ts --step register \ --jid "tg:" \ --name "My Chat" \ --trigger "@nanoclaw" \ @@ -235,10 +235,10 @@ Make sure you configured proxy bypass in [Step 1](#step-1-create-the-sandbox) fi ```bash # Apply the WhatsApp skill -npx tsx scripts/apply-skill.ts .claude/skills/add-whatsapp +pnpm exec tsx scripts/apply-skill.ts .claude/skills/add-whatsapp # Rebuild -npm run build +pnpm run build # Configure .env cat > .env << EOF @@ -250,13 +250,13 @@ mkdir -p data/env && cp .env data/env/env # Authenticate (choose one): # QR code — scan with WhatsApp camera: -npx tsx src/whatsapp-auth.ts +pnpm exec tsx src/whatsapp-auth.ts # OR pairing code — enter code in WhatsApp > Linked Devices > Link with phone number: -npx tsx src/whatsapp-auth.ts --pairing-code --phone +pnpm exec tsx src/whatsapp-auth.ts --pairing-code --phone # Register your chat (JID = your phone number + @s.whatsapp.net) -npx tsx setup/index.ts --step register \ +pnpm exec tsx setup/index.ts --step register \ --jid "@s.whatsapp.net" \ --name "My Chat" \ --trigger "@nanoclaw" \ @@ -276,7 +276,7 @@ Apply both skills, patch both for proxy support, combine the `.env` variables, a ## Step 7: Run ```bash -npm start +pnpm start ``` You don't need to set `ANTHROPIC_API_KEY` manually. The sandbox proxy intercepts requests and replaces `proxy-managed` with your real key automatically. @@ -306,7 +306,7 @@ The workspace is mounted via virtiofs. Git's pack file handling can corrupt over ## Troubleshooting -### npm install fails with SELF_SIGNED_CERT_IN_CHAIN +### pnpm install fails with SELF_SIGNED_CERT_IN_CHAIN ```bash npm config set strict-ssl false ``` @@ -355,5 +355,5 @@ Run the auth command interactively inside the sandbox (not piped through `docker ```bash docker sandbox run shell-nanoclaw-workspace # Then inside: -npx tsx src/whatsapp-auth.ts +pnpm exec tsx src/whatsapp-auth.ts ``` diff --git a/groups/global/CLAUDE.md b/groups/global/CLAUDE.md index dc585e2..c4428ff 100644 --- a/groups/global/CLAUDE.md +++ b/groups/global/CLAUDE.md @@ -98,7 +98,7 @@ Standard Markdown works: `**bold**`, `*italic*`, `[links](url)`, `# headings`. ## Installing Packages & Tools -Your container is ephemeral — anything installed via `apt-get` or `npm install -g` is lost on restart. To install packages that persist, use the self-modification tools: +Your container is ephemeral — anything installed via `apt-get` or `pnpm install -g` is lost on restart. To install packages that persist, use the self-modification tools: 1. **`install_packages`** — request system (apt) or global npm packages. Requires admin approval. 2. **`request_rebuild`** — rebuild your container image so approved packages are baked in. Always call this after `install_packages` to apply the changes. @@ -111,16 +111,16 @@ request_rebuild({ reason: "Apply ffmpeg + transformers" }) # → Admin approves → image rebuilt with the packages ``` -**When to use this vs workspace npm install:** -- `npm install` in `/workspace/agent/` persists on disk (it's mounted) but isn't on the global PATH — use it for project-level dependencies +**When to use this vs workspace pnpm install:** +- `pnpm install` in `/workspace/agent/` persists on disk (it's mounted) but isn't on the global PATH — use it for project-level dependencies - `install_packages` is for system tools (ffmpeg, imagemagick) and global npm packages that need to be on PATH ### MCP Servers -Use **`add_mcp_server`** to add an MCP server to your configuration, then **`request_rebuild`** to apply. Browse available servers at https://mcp.so — it's a curated directory of high-quality MCP servers. Most Node.js servers run via `npx`, e.g.: +Use **`add_mcp_server`** to add an MCP server to your configuration, then **`request_rebuild`** to apply. Browse available servers at https://mcp.so — it's a curated directory of high-quality MCP servers. Most Node.js servers run via `pnpm dlx`, e.g.: ``` -add_mcp_server({ name: "memory", command: "npx", args: ["@modelcontextprotocol/server-memory"] }) +add_mcp_server({ name: "memory", command: "pnpm", args: ["dlx", "@modelcontextprotocol/server-memory"] }) request_rebuild({ reason: "Add memory MCP server" }) ```