From adc3982a4aa7862dd49465d4a3dbba5f08cd51de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= Date: Fri, 5 Jun 2026 22:29:35 +0000 Subject: [PATCH] fix: bootstrap agent discovery + adapter version independence (#120) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Step 1: detect hermes/claude before choosing adapter - Adapter versions independent from CLI — install @latest - ACP verification: hermes acp --help - Remove uwf-builtin (not ready) Refs #120 --- .changeset/bootstrap-ux-3.md | 11 ++++--- packages/cli/src/commands/prompt.ts | 50 +++++++++++++++++------------ 2 files changed, 35 insertions(+), 26 deletions(-) diff --git a/.changeset/bootstrap-ux-3.md b/.changeset/bootstrap-ux-3.md index cf11d3b..6474a0f 100644 --- a/.changeset/bootstrap-ux-3.md +++ b/.changeset/bootstrap-ux-3.md @@ -2,12 +2,13 @@ "@united-workforce/cli": patch --- -fix: improve bootstrap docs — pnpm/npm parity, adapter install order, preset provider table (#118) +fix: improve bootstrap docs — agent discovery, pnpm/npm parity, preset provider table (#118, #120) -- Step 1: show pnpm and npm side-by-side (not just pnpm with a comment) +- Step 1: detect installed agents (hermes/claude) before choosing adapter +- Step 1: clarify adapter versions are independent from CLI — install @latest +- Step 1: show pnpm and npm side-by-side - Step 1: add "adapter must be installed before `uwf setup --agent`" note -- Step 1: add `uwf --version` and adapter version verification with PATH troubleshooting +- Step 1: add ACP verification step (hermes acp --help) - Step 2: `--agent` takes adapter command name (e.g. `uwf-hermes`), not npm package - Step 2: preset providers listed as a table with names and default base URLs -- Step 2: non-preset providers must specify `--base-url` manually -- Upgrade scenario: also show npm alternatives +- Remove uwf-builtin from supported adapters (not ready yet) diff --git a/packages/cli/src/commands/prompt.ts b/packages/cli/src/commands/prompt.ts index a2d323d..35cc81c 100644 --- a/packages/cli/src/commands/prompt.ts +++ b/packages/cli/src/commands/prompt.ts @@ -78,41 +78,49 @@ npm prefix -g # global prefix; bin is /bin # FIX: add the missing directory to your shell's startup file # (e.g. ~/.bashrc, ~/.zshrc, ~/.profile, or fish config): # export PATH=":$PATH" - -# 4. (uwf-hermes only) hermes CLI -which hermes -# FIX: if hermes is in a virtualenv, add it to PATH: -# export PATH="$HOME/.hermes/hermes-agent/.venv/bin:$PATH" -# or create a symlink: ln -s ~/.hermes/hermes-agent/.venv/bin/hermes ~/.local/bin/hermes \`\`\` **All checks must pass before continuing.** If you had to modify PATH, verify the change persists by opening a new shell or sourcing your shell config. -### Step 1 — Install CLI and agent adapter +### Step 1 — Discover agents and install adapter -Install the CLI using **either** pnpm or npm: +**First, detect which supported agents are already installed on the user's machine:** \`\`\`bash -# Using pnpm (recommended) -pnpm add -g @united-workforce/cli +# Check for Hermes Agent +which hermes 2>/dev/null && hermes --version -# Using npm -npm install -g @united-workforce/cli +# Check for Claude Code +which claude 2>/dev/null && claude --version # should show "X.Y.Z (Claude Code)" \`\`\` -Next, install an agent adapter (**must be installed before running \`uwf setup --agent\`**): +**Based on the results:** -| Adapter | Install (pnpm / npm) | When to use | -|---------|----------------------|-------------| -| uwf-hermes | \`pnpm add -g @united-workforce/agent-hermes\` / \`npm i -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent | -| uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` / \`npm i -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly | -| uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` / \`npm i -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) | +- **Only hermes found** → install \`uwf-hermes\` adapter +- **Only claude found** → install \`uwf-claude-code\` adapter +- **Both found** → ask the user which agent they want uwf to use as default +- **Neither found** → the user must install at least one agent first: + - Hermes Agent: https://hermes-agent.nousresearch.com/docs + - Claude Code: \`npm install -g @anthropic-ai/claude-code\` -**After installing, verify that \`uwf\` and the adapter command (e.g. \`uwf-hermes\`) are available in PATH.** Run: +**Install the uwf CLI and the chosen adapter** using pnpm or npm: + +\`\`\`bash +# CLI (required) +pnpm add -g @united-workforce/cli # or: npm install -g @united-workforce/cli + +# Adapter — install the one matching the detected agent: +pnpm add -g @united-workforce/agent-hermes # or: npm i -g @united-workforce/agent-hermes +pnpm add -g @united-workforce/agent-claude-code # or: npm i -g @united-workforce/agent-claude-code +\`\`\` + +**⚠ Adapter versions are independent from CLI versions.** Do NOT try to match adapter version to CLI version. Just install \`@latest\` (the default). + +**After installing, verify that \`uwf\` and the adapter are available in PATH:** \`\`\`bash uwf --version # should print ${CLI_VERSION} -uwf-hermes --version # (or uwf-claude-code / uwf-builtin) +uwf-hermes --version # or: uwf-claude-code --version \`\`\` If either command is not found, the global bin directory is not in the current shell's PATH. **You must fix this before continuing:** @@ -128,7 +136,7 @@ If either command is not found, the global bin directory is not in the current s \`\`\` 3. Source the updated config or open a new shell, then re-verify the commands work. -**uwf-hermes** also requires the Hermes ACP plugin: +**uwf-hermes** also requires the Hermes ACP plugin. Verify with \`hermes acp --help\`. If not available, install it: \`\`\`bash # Option A: install into hermes venv (recommended) source ~/.hermes/hermes-agent/.venv/bin/activate && pip install hermes-agent[acp] -- 2.43.0