Explicitly convert string chunks to Buffer.from(chunk, 'utf8') before
writing to process.stdout. This fixes UTF-8 mojibake (â instead of ◆/│)
seen in some Bun + terminal combinations (e.g. Ghostty on macOS) where
process.stdout.write(string) doesn't encode as UTF-8 by default.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Added explicit LANG=en_US.UTF-8 and stdout.setEncoding('utf8')
when Unicode mode is enabled. This should prevent UTF-8 mojibake
(â appearing instead of ◆) in terminals like Ghostty.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds debug logging to unicode-detect.ts to help troubleshoot why
Unicode rendering isn't working in Ghostty terminal. When SPAWN_DEBUG=1
is set, the CLI will show:
- Current TERM value (e.g., xterm-ghostty)
- SSH environment variables (SSH_CONNECTION, SSH_CLIENT, SSH_TTY)
- Whether ASCII mode is being forced
This will help identify if SSH detection is incorrectly triggering
ASCII fallback for local Ghostty sessions.
Usage: SPAWN_DEBUG=1 spawn list
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Reverses the overly conservative ASCII-only approach. Now defaults to
Unicode (beautiful spinners, checkmarks, symbols) on local macOS
Terminal, iTerm2, and modern Linux terminals, while still forcing
ASCII fallback for problematic environments:
- SSH sessions (encoding mismatches)
- Dumb terminals (TERM=dumb)
- Users can override with SPAWN_UNICODE=1 or SPAWN_NO_UNICODE=1
This fixes rendering issues while maintaining compatibility across
all environments.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Set both TERM=linux and CI=true in unicode-detect.ts
- CI env var provides additional Unicode disabling for @clack/prompts
- Fix test imports to use package.json instead of deleted version.ts
- Bump to 0.2.6
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Bumped CLI version from 0.2.4 to 0.2.5
- Added rule to CLAUDE.md: ANY change to cli/ requires a version bump
- Uses semantic versioning (patch for fixes, minor for features, major for breaking)
- Auto-update ensures users get latest version immediately
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Changed update banner to use +, -, | instead of Unicode box characters
- Replaced arrow (→) with ASCII arrow (->)
- Changed p.cancel() to plain console.error to avoid Unicode bullet
- Ensures clean rendering on all terminals regardless of Unicode support
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Removed CHECK_INTERVAL and cache-based update checking
- Now fetches latest version on every spawn invocation
- 5-second timeout keeps it fast
- Simplified tests to match new behavior (8 tests instead of 12)
- Users who don't want update checks can set SPAWN_NO_UPDATE_CHECK=1
This ensures users always get the latest version immediately when available.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Changed unicode detection to default to ASCII mode (TERM=linux)
- Users can opt-in to unicode with SPAWN_UNICODE=1
- Auto-detects SSH sessions and forces ASCII (common rendering issues)
- Fixes bullet point display issues in interactive selectors
To enable unicode: export SPAWN_UNICODE=1
To force ASCII: export SPAWN_ASCII=1 (or SPAWN_NO_UNICODE=1)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Removed src/version.ts file
- Updated src/commands.ts, src/index.ts, and src/update-check.ts to import version from package.json
- Using JSON import assertion: `import pkg from "../package.json" with { type: "json" }`
- Eliminates need to maintain version in two places
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Changes:
- Bumped version from 0.1.0 to 0.2.0
- Changed update-check mechanism to auto-install updates instead of just notifying
- checkForUpdates() now blocks and runs install.sh automatically when update is available
- Added executor wrapper for testability of execSync calls
- Updated all tests to mock executor.execSync instead of child_process.execSync
- Auto-update runs on every spawn invocation (24-hour cache prevents excessive checks)
- On update failure, shows error message but continues with original command
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Implements a non-intrusive update notification system that:
- Checks for new versions once per day
- Shows a styled notification when updates are available
- Stores check results in cache to minimize network requests
- Can be disabled with SPAWN_NO_UPDATE_CHECK=1
Implementation:
- New update-check.ts module with background version checking
- Comprehensive test suite (16 tests) covering all scenarios
- Integrated into main CLI entry point
- Updated documentation in README.md
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The 663-line bash CLI (spawn.sh) has drifted from the TypeScript CLI,
missing --prompt, security validation, download fallback, and other
features. Rather than maintaining two implementations, the installer
now auto-installs bun (~5 seconds) when it's not present, ensuring
every user gets the full-featured TypeScript CLI.
- Remove cli/spawn.sh (663 lines)
- Simplify install.sh: remove npm method, add bun auto-install
- Extract build_and_install() helper to deduplicate build logic
- Update cli/README.md and CLAUDE.md to reflect bun-only strategy
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fixes#132 - Some terminals can't render the unicode characters used by
@clack/prompts for bullets, selectors, and box drawing. This adds a
unicode detection module that runs before @clack/prompts is imported,
forcing ASCII mode when:
- SPAWN_NO_UNICODE=1 or SPAWN_ASCII=1 is set (explicit override)
- TERM is "dumb" or unset (common in basic terminals)
Also adds a troubleshooting hint in the help text.
Agent: ux-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tests the actual exported cmdRun and cmdAgentInfo functions (not inline
replicas) for their process.exit error paths: identifier validation
(injection, path traversal, length), unknown agent/cloud handling,
unimplemented combination suggestions, prompt security validation,
and empty input handling.
Agent: test-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tests the actual exported command functions end-to-end using mock.module
for @clack/prompts and loadManifest(true) to force cache refresh with
mocked fetch data. Covers matrix display, agent/cloud listing, agent
info output, and help text content verification.
Agent: test-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
- OAuth failures now explain WHY they failed (timeout, port conflict,
no runtime, network) and suggest specific fixes
- Add duration hints to long-running operations (SSH wait: 30-90s,
OAuth: 10-30s) so users know what to expect
- validateImplementation shows exact `spawn <agent> <cloud>` commands
users can run instead of just listing cloud names
- SSH wait failure suggests checking cloud provider dashboard
Agent: ux-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add legend to `spawn list` matrix output (+ implemented, - not yet available)
- Show cloud identifier keys in `spawn <agent>` info output for easy copy-paste
- Add CLI shortcut hint in interactive mode after selection
- Add agent descriptions to `spawn agents` output
- Add agent counts to `spawn clouds` output for consistency
- Fix misleading "Updating" spinner in `spawn update` (it only checks)
- Add `spawn help` to help text command listing
- Improve footer hints in agents/clouds output with actionable commands
Agent: ux-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tests the extractFlagValue generic function and the full CLI flag
extraction pipeline (--prompt/-p and --prompt-file). Existing tests
in index-parsing.test.ts and index-edge-cases.test.ts use simplified
re-implementations; these tests cover the exact behavior including
error messages, process.exit on missing values, startsWith("-") guard,
sequential two-pass extraction, and edge cases with flag-like values.
Agent: test-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- `spawn agents` now shows the key users need to type (e.g., `claude`)
alongside the display name and cloud count
- `spawn clouds` now shows the key (e.g., `sprite`) alongside the display
name and description
- Both commands show a usage hint at the bottom
- Error when both --prompt and --prompt-file are provided (was silently
overwriting)
- Remove duplicate agent validation in handleDefaultCommand (was loading
manifest twice without spinner, showing different error format)
Agent: ux-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Terminals without UTF-8 support display garbled characters (e.g., "â"
instead of bullets). Replace all Unicode symbols (bullets, em dashes,
arrows, check marks, box drawing) with ASCII equivalents.
Fixes#99
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: Extract duplicated prompt flag parsing into extractFlagValue helper
The --prompt and --prompt-file argument extraction in main() shared identical
patterns for flag detection, value validation, and args splicing. Extracted
into a reusable extractFlagValue() function that handles all three concerns.
Agent: complexity-hunter
* refactor: Consolidate multiple python3 JSON reads into single calls
OVH, Kamatera, and UpCloud each spawned separate python3 processes to
read different fields from the same JSON config file. Consolidate into
a single python3 call per file, printing all fields at once and reading
them with bash read. Also fixes OVH using string interpolation for the
file path instead of the safer sys.argv[1] pattern.
Agent: complexity-hunter
* refactor: Extract flyctl auth and token validation from ensure_fly_token
Split the 75-line ensure_fly_token into focused helpers:
- _try_flyctl_auth: encapsulates flyctl CLI token retrieval
- _validate_fly_token: encapsulates API validation with error reporting
The main function is now a clear sequential flow of token source attempts.
Agent: complexity-hunter
* refactor: Deduplicate retry backoff logic in kamatera_api
The two error branches (network error and HTTP 429/503) had identical
interval update and attempt increment code. Restructure with early
return for success, then unified backoff at the end of the loop.
Agent: complexity-hunter
* refactor: Remove unnecessary async IIFE wrapper in validateAndGetAgent
The function wrapped its body in `return (async () => { ... })()` when
it can simply be declared as `async function` directly.
Agent: complexity-hunter
---------
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Three new test files target gaps in existing coverage:
- index-edge-cases: tests startsWith("-") guard for --prompt/-p values, --prompt-file
validation, combined flag extraction order, and agent list truncation logic
- manifest-helpers: tests isValidManifest with unusual data shapes (arrays, strings,
numbers), corrupted cache handling, and countImplemented case sensitivity
- security-encoding: tests unicode homoglyphs, null bytes, CRLF line endings, BOM
markers, and control character handling in identifier/script/prompt validation
Agent: test-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- validateImplementation: Show which clouds ARE available when a
combination isn't implemented, instead of a dead-end error
- Interactive mode: Add guidance when no clouds available for agent
- handleError: Add 'spawn help' hint to generic error handler
- handleDefaultCommand: Show agent keys alongside names so users
know what to type (e.g., "claude" not just "Claude Code")
Agent: ux-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Show clear error when --prompt/-p or --prompt-file is used without a
value (previously silently ignored)
- Fix --prompt-file splice index bug when used after --prompt
- Replace echo -e with printf in fly/lib/common.sh for macOS bash 3.x
compatibility
- Fix incorrect env var name in README (DIGITALOCEAN_TOKEN -> DO_API_TOKEN)
- Add missing agent entries (gptme, OpenCode, Plandex) to 11 cloud READMEs
- Add all 13 agents to Civo README (previously only had 3)
Agent: ux-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Adds 30 new test cases covering previously untested functions in commands.ts
- Tests for getStatusDescription, renderMatrix helpers, validation logic
- Tests for error handling functions and download fallback logic
- Tests for agent/cloud validation and implementation checking
- Tests for calculateColumnWidth variations with different parameters
- Tests for isLocalSpawnCheckout file detection logic
This improves test coverage for core command logic that wasn't previously tested,
focusing on pure functions and logic that can be tested without full module mocking.
Agent: test-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
- Added 35 tests covering helper functions in commands.ts
- Tests cover error handling, string validation, column width calculation
- Tests verify renderMatrixRow color selection logic
- Tests validate isLocalSpawnCheckout and report functions
- All 35 new tests pass
- Focus on pure functions and functions with minimal side effects
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
Enhance UX across CLI and cloud providers with actionable error messages:
1. Modal sandbox creation failures now provide:
- Detailed error output from Python SDK
- Common causes (auth expired, quota issues, network)
- Step-by-step troubleshooting (re-auth, check quota, status page)
2. Modal CLI installation failures now explain:
- Missing pip/pip3 (with installation commands)
- Permission issues (suggest --user flag)
- Manual installation steps
3. Sprite connectivity failures now include:
- Commands to check sprite status and logs
- Steps to recreate sprite
- Support contact information
4. Sprite CLI installation now:
- Catches installation failures with helpful error messages
- Verifies installation succeeded before proceeding
- Provides manual installation instructions
5. CLI script download failures improved:
- Distinguish between 404 (doesn't exist) and other errors
- Provide specific next steps for each scenario
- Suggest checking matrix for implementation status
All error messages follow the pattern:
- What went wrong
- Why it might have happened (common causes)
- What to do next (actionable steps)
Agent: ux-engineer
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* ux: Improve error messages and user guidance across CLI and shell scripts
Enhanced error messages to be more actionable and user-friendly:
CLI improvements (commands.ts):
- Made validateNonEmptyString clearer: "is required but was not provided"
- Reordered troubleshooting steps to check matrix first (most common issue)
- Simplified 404 error message: "doesn't exist yet" vs "may not be implemented"
- Changed "Troubleshooting steps" to just "Troubleshooting" (less formal)
Shared library improvements (shared/common.sh):
- OAuth cancellation now explains why API key is needed and where to get it
- safe_read non-TTY error explains what non-interactive mode is with example
- get_resource_name error shows exact env var syntax needed
- Agent verification failures now list specific possible causes
- All improvements add context and next steps rather than just stating the problem
Hetzner library improvements (hetzner/lib/common.sh):
- Replaced technical "Remediation" with friendly "How to fix"
- Changed log_warn to log_error for error conditions (consistent severity)
- Added spacing for better readability of multi-line errors
- Made server creation errors more specific about account issues
All changes focus on helping users understand WHAT went wrong and HOW to fix it.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: Replace issue-triager with community-coordinator agent
Replace the issue-triager agent in the refactor team with a
community-coordinator that actively engages with GitHub issues:
acknowledges reports, posts interim updates, delegates to relevant
teammates, and posts final resolutions — so reporters feel heard.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fixes#59
The instanceof operator can fail in bundled/minified code or when
errors cross execution realm boundaries, causing the error:
"instanceof called on an object with an invalid prototype property"
This commit replaces all instanceof Error checks with duck typing
(checking for object with 'message' property) which is more reliable
across different execution contexts.
Changes:
- index.ts: Updated handleError() and prompt file error handling
- commands.ts: Updated getErrorMessage() helper
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Security:
- Fix command injection in modal/lib/common.sh (run_server, upload_file, interactive_session)
- Fix command injection in fly/lib/common.sh (run_server, upload_file, interactive_session)
- All container providers now use printf '%q' for proper shell escaping
Complexity:
- Extract _api_should_retry_on_error() helper in shared/common.sh (-19 lines)
- Refactor scaleway_api and upcloud_api to use shared retry helper (-24 lines)
- Extract _save_fly_token() helper in fly/lib/common.sh (-11 lines)
- Extract validateAndGetAgent() in commands.ts, reducing cmdRun/cmdAgentInfo duplication
- Refactor cmdList column width calculation to use calculateColumnWidth()
UX:
- Add actionable next steps to error messages in shared/common.sh
- Improve CLI bash fallback error messages with guidance (spawn.sh)
- Add OAuth progress indicator during browser authentication wait
- Show invalid model ID value and link to openrouter.ai/models
- Add troubleshooting steps for agent installation failures
Tests:
- Update test assertions in test/run.sh to match refactored patterns
- All tests passing: 74 TypeScript + 75 bash = 149 total, 0 failures
Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
~/.bun/bin is often NOT in PATH, causing 'command not found' after
install. Now picks the first dir already in PATH from:
1. ~/.local/bin (most universal)
2. $(bun pm bin -g)
3. ~/.bun/bin
4. ~/bin
Also consolidated PATH detection and instructions into shared helpers,
with clear shell-specific instructions when the dir isn't in PATH.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
bun link only registers packages for project-level linking — it does
not create global CLI binaries. bun install -g has the same issue.
New approach:
- bun: build cli.js, copy directly to $(bun pm bin -g)/spawn (55KB)
- npm: build with esbuild, copy to $(npm bin -g)/spawn
- Both methods put the binary exactly where the runtime expects it
Also replaced brittle hardcoded file downloads with git sparse-checkout
(with GitHub API fallback), so new source files never break the installer.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The install script had a hardcoded list of source files to download,
which broke whenever a new file was added (e.g., security.ts). Also,
openrouter.ai/lab/spawn served a stale cached version without the fix.
Now uses git sparse-checkout (fast, gets only cli/) with a GitHub API
fallback for environments without git. Adding new source files will
never break the installer again.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
commands.ts imports ./security.js but install.sh never downloaded
security.ts, causing build to fail with "Could not resolve" error.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
package.json bin points to cli.js, but it was never built during
installation. Both bun link and npm install -g failed silently because
the file didn't exist.
- Bun path: run `bun run build` before `bun link`
- npm path: use npx esbuild to bundle cli.js with node shebang
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Enhance the spawn CLI user experience with actionable error messages,
comprehensive help documentation, and visual progress feedback.
Changes:
- Help text: Add AUTHENTICATION, TROUBLESHOOTING, and MORE INFO sections
- Error messages: Show examples of valid options when validation fails
- Progress indicators: Add spinners for script downloads
- Install flow: Provide clear alternatives when npm install requires sudo
- README: Add environment variable documentation and alternative install URL
- Security errors: Suggest workarounds for false positives
All error messages now follow the pattern:
1. What went wrong
2. Why it matters
3. What to do next
Documentation: .docs/UX_IMPROVEMENTS_20260208.md
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
* refactor: extract shared test helpers and utilities
Created centralized test-helpers.ts module to eliminate duplication across test files:
**Extracted Helpers:**
- createMockManifest() - Reusable mock manifest data
- createEmptyManifest() - Empty manifest for edge cases
- createConsoleMocks() - Console spy setup
- createProcessExitMock() - Process exit mock
- restoreMocks() - Mock cleanup utility
- mockSuccessfulFetch() - Simplified successful fetch mock
- mockFailedFetch() - Simplified failed fetch mock
- mockFetchWithStatus() - Fetch mock with custom status
- setupTestEnvironment() - Test directory and env setup
- teardownTestEnvironment() - Cleanup utility
**Deduplication Impact:**
- commands.test.ts: Removed 50+ lines of duplicate mock setup
- manifest.test.ts: Removed 80+ lines of duplicate manifest data and setup code
- integration.test.ts: Removed 40+ lines of duplicate setup/teardown
**Benefits:**
- Single source of truth for test fixtures
- Consistent mock patterns across all tests
- Easier maintenance - changes to test setup in one place
- Improved test readability
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* refactor: Add non-interactive mode for agent execution
Implements --prompt and --prompt-file flags to enable non-interactive
agent execution. This allows users to:
- Execute agents with a prompt and exit automatically
- Use spawn in CI/CD pipelines and automation scripts
- Pass prompts via command line or file
Changes:
- TypeScript CLI: Parse --prompt/-p and --prompt-file flags
- Security: Add validatePrompt() to prevent command injection
- Commands: Pass prompt via SPAWN_PROMPT env var to bash scripts
- Bash scripts: Detect SPAWN_PROMPT and fork interactive/non-interactive
- Help text: Document new flags with examples
Implementation:
- claude.sh: Use 'claude -p' for non-interactive execution
- aider.sh: Use 'aider -m' for non-interactive execution
- shared/common.sh: Add execute_agent_non_interactive() helper
Security:
- Validates prompts for command injection patterns
- Length limit: 10KB max
- Blocks $(), backticks, piping to bash/sh
- Uses printf %q for proper shell escaping
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* docs: Add testing guide for non-interactive mode
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Sprite <noreply@sprite.dev>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Added back `mock`, `join`, `tmpdir`, `mkdirSync`, and `rmSync` imports
that were accidentally removed during test deduplication refactoring.
Tests now pass (39 pass, 11 skip, 1 fail - same pre-existing failure).
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
