From fde87b627445fe153b299ef48aba19e159eacf11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= Date: Fri, 5 Jun 2026 15:22:23 +0000 Subject: [PATCH] =?UTF-8?q?fix:=20setup=20UX=20improvements=20=E2=80=94=20?= =?UTF-8?q?adapter=20check,=20ENOENT,=20SQLite=20warning,=20VERSION,=20PAT?= =?UTF-8?q?H=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - setup validates adapter binary availability, prints install command if missing - setup prints 'Config saved to ✓' on success - spawn ENOENT gives actionable error with which command - SQLite ExperimentalWarning suppressed via NODE_OPTIONS - bootstrap VERSION reads cli package.json (was reading util) - bootstrap PATH guidance is shell-agnostic Fixes #114 --- .changeset/setup-ux-improvements.md | 12 ++++++++ packages/cli/src/commands/prompt.ts | 47 ++++++++++++++++++++++------- packages/cli/src/commands/setup.ts | 44 ++++++++++++++++++++++++++- packages/cli/src/commands/thread.ts | 18 +++++++++++ 4 files changed, 109 insertions(+), 12 deletions(-) create mode 100644 .changeset/setup-ux-improvements.md diff --git a/.changeset/setup-ux-improvements.md b/.changeset/setup-ux-improvements.md new file mode 100644 index 0000000..c2d7ec4 --- /dev/null +++ b/.changeset/setup-ux-improvements.md @@ -0,0 +1,12 @@ +--- +"@united-workforce/cli": patch +--- + +fix: setup UX improvements (#114) + +- Setup validates adapter availability and prints install command if missing +- Setup prints "Config saved to ✓" on success +- Spawn ENOENT gives actionable error ("not found in PATH" + which command) +- SQLite ExperimentalWarning suppressed via NODE_OPTIONS in spawned processes +- Bootstrap VERSION reads cli package version (was reading util version) +- Bootstrap PATH guidance is shell-agnostic (no hardcoded .bashrc/.profile) diff --git a/packages/cli/src/commands/prompt.ts b/packages/cli/src/commands/prompt.ts index 8a325a4..0901ef5 100644 --- a/packages/cli/src/commands/prompt.ts +++ b/packages/cli/src/commands/prompt.ts @@ -1,10 +1,35 @@ +import { readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; import { generateAdapterDevelopingReference, generateUsageReference, generateWorkflowAuthoringReference, - VERSION, } from "@united-workforce/util"; +// CLI package version (for bootstrap prompt — uwf --version prints this) +// Walk up from __dirname to find the nearest package.json (works from both src/ and dist/) +function _findCliVersion(): string { + let dir = dirname(fileURLToPath(import.meta.url)); + for (let i = 0; i < 5; i++) { + const candidate = join(dir, "package.json"); + try { + const pkg = JSON.parse(readFileSync(candidate, "utf-8")) as { + name?: string; + version?: string; + }; + if (pkg.name === "@united-workforce/cli") { + return pkg.version ?? "0.0.0"; + } + } catch { + // not found, keep walking + } + dir = dirname(dir); + } + return "0.0.0"; +} +const CLI_VERSION = _findCliVersion(); + export { generateAdapterDevelopingReference as cmdPromptAdapterDeveloping, generateUsageReference as cmdPromptUsage, @@ -45,14 +70,14 @@ pnpm --version || npm --version # 3. Global bin directory is in PATH # For pnpm: -pnpm root -g 2>/dev/null && pnpm bin -g +pnpm bin -g # prints the global bin directory # For npm: -npm prefix -g -# The "bin" directory printed above MUST be in your PATH. -# Test: echo $PATH | tr ':' '\\n' | grep -E "(pnpm|npm|node)" -# FIX: add the bin directory to ~/.profile or ~/.bashrc: -# export PATH="$(pnpm bin -g):$PATH" # pnpm -# export PATH="$(npm prefix -g)/bin:$PATH" # npm +npm prefix -g # global prefix; bin is /bin +# The directory printed above MUST be in your PATH. +# Test: echo \\$PATH | tr ':' '\\\\n' +# 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 @@ -61,13 +86,13 @@ which hermes # 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 profile. +**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 \`\`\`bash pnpm add -g @united-workforce/cli # or: npm install -g @united-workforce/cli -uwf --version # should print ${VERSION} +uwf --version # should print ${CLI_VERSION} \`\`\` Install an agent adapter (at least one is required): @@ -165,7 +190,7 @@ If the thread reaches \`$END\` with status \`completed\`, the setup is working. \`\`\`bash pnpm add -g @united-workforce/cli@latest # or: npm install -g @united-workforce/cli@latest -uwf --version # should print ${VERSION} +uwf --version # should print ${CLI_VERSION} # Also update your adapter(s) pnpm add -g @united-workforce/agent-hermes@latest diff --git a/packages/cli/src/commands/setup.ts b/packages/cli/src/commands/setup.ts index 2dd4a83..d44bedf 100644 --- a/packages/cli/src/commands/setup.ts +++ b/packages/cli/src/commands/setup.ts @@ -1,3 +1,4 @@ +import { execFileSync } from "node:child_process"; import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { stdin as input, stdout as output } from "node:process"; @@ -181,7 +182,6 @@ export async function _discoverAgents(): Promise { async function _tryWhichDiscovery(): Promise { try { - const { execFileSync } = await import("node:child_process"); const text = execFileSync("which", ["-a", "uwf-hermes", "uwf-claude-code", "uwf-cursor"], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], @@ -397,6 +397,37 @@ function mergeConfig(existing: Record, args: SetupArgs): Record }; } +/** + * Check if the configured adapter binary (and its dependencies) are in PATH. + * Returns warnings array — empty means all good. + */ +export function _checkAdapterAvailability(agentName: string): string[] { + const warnings: string[] = []; + const binary = `uwf-${agentName}`; + + try { + execFileSync("which", [binary], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }); + } catch { + warnings.push( + `${binary} not found in PATH. Install it: pnpm add -g @united-workforce/agent-${agentName}`, + ); + return warnings; // skip dependency check if adapter itself is missing + } + + // uwf-hermes depends on hermes CLI + if (agentName === "hermes") { + try { + execFileSync("which", ["hermes"], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }); + } catch { + warnings.push( + 'hermes CLI not found in PATH (required by uwf-hermes). Fix: export PATH="$HOME/.hermes/hermes-agent/.venv/bin:$PATH"', + ); + } + } + + return warnings; +} + /** * Non-interactive setup. All required args provided via CLI flags. */ @@ -411,15 +442,26 @@ export async function cmdSetup(args: SetupArgs): Promise writeFileSync(configPath, stringify(merged, { indent: 2 }), "utf8"); + // Print config path to stderr (stdout is reserved for JSON output) + console.error(`Config saved to ${configPath} ✓`); + // Validate model connectivity const validation = await validateModel(args.baseUrl, args.apiKey, args.model); + // Check adapter availability + const agentName = _agentNameFromBinary(args.agent ?? "hermes"); + const adapterWarnings = _checkAdapterAvailability(agentName); + for (const w of adapterWarnings) { + console.error(`⚠ ${w}`); + } + return { configPath, provider: args.provider, model: args.model, defaultAgent: merged.defaultAgent, validation, + adapterWarnings, }; } diff --git a/packages/cli/src/commands/thread.ts b/packages/cli/src/commands/thread.ts index c6cbcf4..d523fe7 100644 --- a/packages/cli/src/commands/thread.ts +++ b/packages/cli/src/commands/thread.ts @@ -1001,9 +1001,21 @@ function spawnAgent( stdio: ["ignore", "pipe", "pipe"], maxBuffer: 50 * 1024 * 1024, // 50 MB — stream-json output can be large cwd, + env: { + ...process.env, + NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"] + .filter(Boolean) + .join(" "), + }, }); } catch (e) { const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string | null }; + if (err.code === "ENOENT") { + failStep( + plog, + `"${agent.command}" not found in PATH. Install it or check your PATH config. Run: which ${agent.command}`, + ); + } const stderr = err.stderr == null ? "" @@ -1242,6 +1254,12 @@ async function cmdThreadStepBackground( const child = spawn(scriptPath, args, { detached: true, stdio: "ignore", + env: { + ...process.env, + NODE_OPTIONS: [process.env.NODE_OPTIONS, "--disable-warning=ExperimentalWarning"] + .filter(Boolean) + .join(" "), + }, }); child.unref(); -- 2.43.0