Skip to content

fix(cli): consumer-found DX fixes for chat, .env, doctor and eval - #663

Merged
LinuxDevil merged 1 commit into
mainfrom
fix/cli-dx-consumer
Oct 16, 2026
Merged

LinuxDevil merged 1 commit into
mainfrom
fix/cli-dx-consumer

Conversation

@LinuxDevil

Copy link
Copy Markdown
Owner

Problem

A consumer run of the CLI found:

  1. lousho chat printed only error: User not found. (an OpenRouter 401), dropping the error code, category, HTTP status and fix that docs/cli.md promises. The scaffolded src/index.ts had the same issue.
  2. A .env saved with a UTF-8 BOM (PowerShell 5.1 Set-Content -Encoding utf8) silently lost its first key: process.loadEnvFile keeps the BOM, so the variable came out as \uFEFFOPENROUTER_API_KEY.
  3. lousho doctor: doctor src/agent.ts failed with LOUSHO_SPEC_UNSUPPORTED_FORMAT and the wrong fix text. The scaffold's npm run doctor (no path) exited 0 with the agent's key missing. --ping passed with a bogus OpenRouter key because /models needs no auth. Fix lines said export X= on Windows.
  4. The lousho eval table hid the scores of passing scored gates; they only showed up in --json.
  5. fallow dead-code reported two false positives in packages/create-lousho-agent.
  6. On Windows, npx C:\abs\path\x.tgz silently does nothing, and the docs didn't say so.

Fix

  • chat REPL: error events are held until the run ends. The error that failed the run is printed from the run's rejection: error: <msg> (<category>, HTTP <status>), then [CODE] hint (docs). Other error events print with their code's help line. The scaffold's errorText does the same through the public SDKError API.
  • .env: bin/lousho.js and the scaffold read the file, strip a leading BOM and parse it with util.parseEnv (Node >= 21.7; the engines floor is 22.19). Variables already set still win.
  • doctor: .ts/.js modules are imported the same way lousho dev imports them (new agentModuleConfig() in devReload; the agent is not built). The doctor checks the module's model provider, so a missing key is a failure. The scaffold's doctor script is now lousho doctor src/agent.ts. OpenRouter is pinged at /api/v1/key, a 401/403 is a failure, and a custom OPENAI_BASE_URL ping is labelled reachability-only. Fix lines use $env:X="..." on win32. An unsupported file type gets the right fix text.
  • eval: the SCORES column shows every assertion that isn't a plain yes/no (0/1 against threshold 1).
  • .fallowrc.json: added ignoreUnresolvedImports for ../dist/index.js and ignoreExports for create-lousho-agent's main.
  • Docs: cli.md, installation.md, the create-lousho-agent README, CHANGELOG Unreleased, llms-full.txt.

Verification

  • Tests written first: chat (provider 401 printed once, with category, status and code), bin (BOM .env, existing env wins), doctorCore (module loading, missing key fails, OpenRouter /key, reachability label, PowerShell fix, unsupported-format fix), templates, evalReport.
  • npx tsc --noEmit, npm run lint, npm run docs:llms:check and npm run build pass. npx vitest run src/cli passes: 536 tests.
  • packages/create-lousho-agent template e2e (real install, typecheck, tests) passes with the new template.
  • Manual Windows run: lousho doctor agent.ts with a BOM .env loads the key from .env, loads the module, FAILs on the missing OpenRouter key with a PowerShell fix line, and exits 1.
  • npx fallow dead-code: the two create-lousho-agent findings are gone. Still reported, and unrelated to this PR: @lousho/build-ai-agent as an unused dependency of apps/agent-forge. It looks specific to this worktree.
  • Full npm run test:coverage on Windows: 1 failure, the timing-sensitive src/storage/sqlite/connection.test.ts lock-contention test. It passes on its own (env-only, under load). Because of that failure no coverage file was written, so the full npm run fallow health run did not happen locally.

🤖 Generated with Claude Code

- lousho chat (and the scaffolded src/index.ts) print a failed turn with its
  error code, provider failure category, HTTP status and fix.
- .env files saved with a UTF-8 BOM keep their first key (bin/lousho.js and
  the scaffold read the file, drop the BOM and parse with util.parseEnv;
  variables already set still win).
- lousho doctor loads .ts/.js agent modules like lousho dev, fails on a
  missing key for the module's provider, pings OpenRouter at /api/v1/key
  (a rejected key fails), labels reachability-only pings, and prints
  PowerShell fix lines on Windows. Scaffolded npm run doctor targets
  src/agent.ts.
- lousho eval's table shows scores of passing scored gates.
- fallow: ignore the create-lousho-agent bin's ../dist import and main export.
- Docs: Windows npx with an absolute .tgz path does nothing; use a relative
  path or a file: spec.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@LinuxDevil
LinuxDevil merged commit 6b4f6b4 into main Oct 16, 2026
@LinuxDevil
LinuxDevil deleted the fix/cli-dx-consumer branch October 16, 2026 20:47
LinuxDevil added a commit that referenced this pull request Oct 16, 2026
#662 added a Google ping target with a 'base' field while #663 changed
PingTarget to a full 'url' plus 'checksKey', so main stopped type-checking.
Gemini's /models needs the key, so a 200 proves it.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant