mosaicstack/stack
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases 11 Wiki Activity

feat: unify mosaic CLI — single binary, no PATH conflict #351

Merged
jason.woltje merged 1 commits from feat/unify-mosaic-cli into main 2026-04-03 00:41:07 +00:00
Conversation 0 Commits 1 Files Changed 43 +724 -1475
jason.woltje commented 2026-04-03 00:24:11 +00:00
Owner
Copy Link

Problem

Two different binaries both named mosaic:

  • ~/.config/mosaic/bin/mosaic (bash framework launcher)
  • ~/.npm-global/bin/mosaic (npm CLI)

Whichever appears first on PATH shadows the other. Users had to carefully order PATH entries.

Solution

One mosaic binary — the npm CLI (@mosaic/cli) is the single entrypoint.

Runtime commands (claude, codex, opencode, pi, yolo) and framework management commands (init, doctor, sync, seq, bootstrap, coord, upgrade) delegate to the renamed mosaic-launch bash script via execFileSync at its absolute path (~/.config/mosaic/bin/mosaic-launch).

Users only need ~/.npm-global/bin on PATH.

Changes

File Change
packages/mosaic/framework/bin/mosaic → mosaic-launch Renamed
packages/cli/src/cli.ts Added launcher delegation for all runtime + management commands
tools/install.sh Removed framework PATH requirement, auto-cleans old mosaic binary, simplified summary
packages/mosaic/framework/install.sh Added sources to preserved paths (fixes rsync noise about agent-skills)
packages/mosaic/framework/tools/orchestrator/session-run.sh Updated references to mosaic-launch

After this change

$ mosaic --help
Usage: mosaic [options] [command]

Mosaic Stack CLI

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  claude          Launch Claude Code with Mosaic injection
  codex           Launch Codex with Mosaic injection
  opencode        Launch OpenCode with Mosaic injection
  pi              Launch Pi with Mosaic injection
  yolo <runtime>  Launch a runtime in dangerous-permissions mode
  init            Generate SOUL.md (agent identity contract)
  doctor          Health audit
  sync            Sync skills from canonical source
  login           Sign in to a Mosaic gateway
  tui             Launch interactive TUI
  update          Check for and install CLI updates
  wizard          Run the Mosaic installation wizard
  ...

All from a single mosaic binary.

## Problem Two different binaries both named `mosaic`: - `~/.config/mosaic/bin/mosaic` (bash framework launcher) - `~/.npm-global/bin/mosaic` (npm CLI) Whichever appears first on PATH shadows the other. Users had to carefully order PATH entries. ## Solution **One `mosaic` binary** — the npm CLI (`@mosaic/cli`) is the single entrypoint. Runtime commands (`claude`, `codex`, `opencode`, `pi`, `yolo`) and framework management commands (`init`, `doctor`, `sync`, `seq`, `bootstrap`, `coord`, `upgrade`) delegate to the renamed `mosaic-launch` bash script via `execFileSync` at its absolute path (`~/.config/mosaic/bin/mosaic-launch`). Users only need `~/.npm-global/bin` on PATH. ## Changes | File | Change | |---|---| | `packages/mosaic/framework/bin/mosaic` → `mosaic-launch` | Renamed | | `packages/cli/src/cli.ts` | Added launcher delegation for all runtime + management commands | | `tools/install.sh` | Removed framework PATH requirement, auto-cleans old `mosaic` binary, simplified summary | | `packages/mosaic/framework/install.sh` | Added `sources` to preserved paths (fixes rsync noise about agent-skills) | | `packages/mosaic/framework/tools/orchestrator/session-run.sh` | Updated references to `mosaic-launch` | ## After this change ``` $ mosaic --help Usage: mosaic [options] [command] Mosaic Stack CLI Options: -V, --version output the version number -h, --help display help for command Commands: claude Launch Claude Code with Mosaic injection codex Launch Codex with Mosaic injection opencode Launch OpenCode with Mosaic injection pi Launch Pi with Mosaic injection yolo <runtime> Launch a runtime in dangerous-permissions mode init Generate SOUL.md (agent identity contract) doctor Health audit sync Sync skills from canonical source login Sign in to a Mosaic gateway tui Launch interactive TUI update Check for and install CLI updates wizard Run the Mosaic installation wizard ... ``` All from a single `mosaic` binary.
jason.woltje added 1 commit 2026-04-03 00:24:12 +00:00
feat: unify mosaic CLI — single binary, no PATH conflict
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details
0a76afb7f2 
- Rename framework bash launcher: mosaic → mosaic-launch
- npm CLI (@mosaic/cli) is now the single 'mosaic' binary on PATH
- Add launcher delegation: mosaic {claude,codex,opencode,pi,yolo}
  delegates to mosaic-launch via execFileSync with inherited stdio
- Add delegated management commands: init, doctor, sync, seq,
  bootstrap, coord, upgrade
- install.sh: remove framework bin PATH requirement, clean up old
  mosaic binary on upgrade, simplified summary output
- framework install.sh: preserve sources/ dir (fixes rsync noise
  about agent-skills)
- session-run.sh: update references to mosaic-launch

Users now only need ~/.npm-global/bin on PATH. The npm CLI finds
mosaic-launch at its absolute path (~/.config/mosaic/bin/mosaic-launch).
jason.woltje force-pushed feat/unify-mosaic-cli from 0a76afb7f2 to 2b99908de4 2026-04-03 00:30:29 +00:00 Compare
jason.woltje force-pushed feat/unify-mosaic-cli from 2b99908de4 to 15830e2f2a 2026-04-03 00:37:20 +00:00 Compare
jason.woltje merged commit 8efbaf100e into main 2026-04-03 00:41:07 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#351
Delete Branch "feat/unify-mosaic-cli"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?