@remits/remits-cli 0.1.69

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Remits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# remits-cli
+
+Local CLI for rapid Remits component testing without push/sync cycles.
+
+## Install
+
+```bash
+npm install -g @remits/remits-cli
+```
+
+On each command run, `remits-cli` checks the npm `latest` version for `@remits/remits-cli`. If a newer version exists, it installs it globally with npm and re-runs the original command. To skip this check for one run, pass `--no-auto-update`; to disable it for a process environment, set `REMITS_CLI_AUTO_UPDATE=0`.
+
+## Common Commands
+
+```bash
+remits-cli auth --base-url https://your-remits-host --account-id 123
+remits-cli start
+remits-cli status
+remits-cli stop
+remits-cli install --skills
+remits-cli tools
+remits-cli tool --base-url http://localhost:8080 --name "My Tool" --input '{"foo":"bar"}'
+remits-cli components stage
+remits-cli test run --test 45
+remits-cli test run --test "My New Test" --names "test case 1,test case 2"
+git add -A
+git commit -m "sync passing changes"
+git push
+remits-cli components sync
+remits-cli token --path page/my-embeddable
+remits-cli data-mode
+remits-cli data-mode set prod
+remits-cli sessions list
+remits-cli config set --agent codex
+```
+
+## Skill Install
+
+```bash
+remits-cli install --skills
+```
+
+Optional:
+
+```bash
+remits-cli install --skills --target codex
+remits-cli install --skills --target claude
+remits-cli install --skills --target gemini
+remits-cli install --skills --overwrite true
+```
+
+## How It Works
+
+- `components stage` uploads the current working tree into the staging cache used by test-mode execution.
+- `components sync` performs a server-side sync from the git remote into the Remits platform for the selected branch. It does not run local git commands.
+- `components commit` is a convenience wrapper that performs local git commit/push, then `components sync`, then local `git fetch`/`git pull --ff-only`.
+- `components sync` returns the post-sync branch SHA produced by the platform. `components commit` verifies that `origin/<branch>` and local `HEAD` both match that exact SHA after the final pull.
+- `components push` is deprecated and currently behaves the same as `components stage`.
+- `accountId` resolution for CLI commands: explicit `--account-id` flag wins, then the current repo's `account-info.json`, then the active session. For `remits-cli tool` calls the server applies a further precedence — explicit `--account-id` > `input.accountId` > session/repo default — so a tool can execute against a different account than the surrounding repo.
+- Auth sessions are stored per `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without overwriting the other session.
+- `remits-cli start` scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json` before bringing up the background service.
+- Front-stage guides are **not** bundled with the CLI npm package. For account-work commands (`components`, `test`, `token`, `tools`, `tool`) and on `auth`, `remits-cli` downloads the latest guides from the authenticated `/cli/guides` endpoint and writes them into the current account repo: root `platform-overview.md` / `development-guide.md`, `guides/*.md`, `guides/features/*.md`, and the agent-guidance files `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` (from `docs/guides/remits-components-zip-readme.md`).
+- Guide sync requires authentication. If no valid session exists and the terminal is interactive, the CLI auto-authenticates first; in non-interactive contexts (CI, agent sandboxes) it skips silently so guides are only ever delivered to users who can authenticate to the platform.
+- During account-repo discovery, `remits-cli` also overwrites the installed remits-cli `SKILL.md` for `claude`, `codex`, and `gemini` so local agents stay on the latest packaged instructions.
+- The platform repo's `docs/guides/` tree remains the single source of truth; the platform serves it from the classpath, so published CLI versions never carry guide content.
+- Authenticated users also get the **core Remits platform repo** locally. After guide sync (and on `auth` / discovery), `remits-cli` ensures `git@github.com:tmillhouse/remits.git` is cloned (default `~/remits`, override with `REMITS_PLATFORM_DIR`; cloning only runs in an interactive terminal). On each authenticated run it also fast-forwards the repo (`git pull --ff-only`, once per process) so back-stage analysis runs against current code — skipped automatically if the working tree is dirty, so local work is never clobbered. The clone is tracked in `~/.remits-cli/account-repos.json` under the reserved `platform` entry so agents can analyze back-stage seams and open a fix PR when a front-stage failure turns out to be platform brittleness. An existing copy found during a `remits-cli start` scan (or the running CLI source in dev) is recorded instead of cloning a duplicate.
+- Branch defaults to the current local git branch.
+- Data mode defaults to `test`. Use `remits-cli data-mode set prod` only for production investigation.
+- Test activity is streamed from websocket `TestSuite` events while final status is also polled from `/cli/test`.
+- Tool execution writes the full response to a separate file so large payloads do not bloat the session log.
+
+## Service, Dashboard, WebSocket, and Tmux Lifecycle
+
+- The primary lifecycle commands are `remits-cli start`, `remits-cli stop`, and `remits-cli status`.
+- `remits-cli listen`, `remits-cli listen stop`, and `remits-cli listen status` still work as compatibility aliases.
+- Most non-lifecycle commands auto-start the background service if authenticated sessions already exist and no service is running.
+- Successful `remits-cli auth` also attempts to auto-start the background service.
+- `remits-cli start` starts a detached background process by default. Use `remits-cli start --foreground true` only when you want to run the daemon in the current terminal.
+- `remits-cli status` reports whether the background service is alive and prints the dashboard URL when available.
+- `remits-cli stop` stops the background service, kills the shared tmux session, and clears pane tracking state.
+- The service starts a localhost dashboard that acts as a control center for remits-cli integration state.
+- The dashboard shows websocket connection health, topic subscriptions, tmux session/panes, the discovered account repo index, global state files, and per-repo remits-cli files.
+- If websocket connections are disconnected or the tmux session is missing, the dashboard exposes actions to reconnect websockets or recreate the tmux session.
+- The service groups sessions by `baseUrl` so one websocket connection can service multiple authenticated accounts on the same Remits environment.
+- Websocket subscriptions are deduplicated by user topic. If multiple authenticated accounts share the same websocket topic, the listener subscribes once and maps that topic back to all related accounts.
+- The daemon keeps STOMP heartbeats enabled and runs a maintenance watchdog that recreates unhealthy websocket connections and recreates the shared tmux session if it disappears.
+- If the machine sleeps, the network drops, or auth sessions change while the daemon is already running, the service now attempts to reconnect and resubscribe automatically once connectivity returns.
+- Incoming websocket messages of type `remits-cli` are dispatched into dedicated tmux windows so the selected agent can continue working interactively with a full terminal view.
+- The listener creates a shared tmux session named `remits-listener`.
+- Support tickets are the primary unit of dispatched work. Each ticket gets its own tmux window/workstream.
+- The listener enables tmux mouse support, increases scrollback history, and keeps exited panes visible for inspection.
+- Follow-up messages with the same `ticketId` are routed back to the existing pane when it is still alive.
+- Legacy payloads that only include `taskId` are still supported as a fallback routing key.
+- If a pane for a tracked ticket has exited or is dead, the listener removes that mapping and creates a replacement pane.
+- Pane commands are launched through the user's login shell so the pane inherits the normal interactive `PATH`.
+- The preferred agent comes from `remits-cli config set --agent claude|codex|gemini`. The default is `claude`.
+
+## Support Tickets
+
+- Support tickets are stored as documents in the `support_tickets` collection.
+- New tickets and ticket updates are delivered over the `remits-cli` websocket channel and appear as local tmux workstreams.
+- Think of this as a lightweight local support queue: the platform creates and updates tickets centrally, and local agents receive those tickets to investigate and resolve.
+- `accountId` / `accountName` identify the account that owns the ticket.
+- If present, `implementationAccountId` / `implementationAccountName` identify the platform or product context that owns the shared implementation.
+- Listener repo dispatch prefers `implementationAccountId` when present, then falls back to `accountId`. If one of those repos is indexed locally in `~/.remits-cli/account-repos.json`, it will be preferred as the tmux working directory.
+- Agents must resolve account `type` (`PLATFORM`, `PRODUCT`, `CLIENT`) before deciding which local repo to use. A `CLIENT` ticket may still require code changes in a parent `PLATFORM` or `PRODUCT` repo.
+- Use `mcp_support_ticket` to manage ticket state:
+
+```bash
+remits-cli tool --name "mcp_support_ticket" --input '{"action":"read","ticketId":"123"}' --data-mode prod
+remits-cli tool --name "mcp_support_ticket" --input '{"action":"accept","ticketId":"123","assignee":"codex"}' --data-mode prod
+remits-cli tool --name "mcp_support_ticket" --input '{"action":"update_status","ticketId":"123","status":"in_progress","notes":"Investigating logs"}' --data-mode prod
+remits-cli tool --name "mcp_support_ticket" --input '{"action":"complete","ticketId":"123","resolution":"Fixed and verified"}' --data-mode prod
+```
+
+- Recommended ticket flow: `read` first, then `accept`, then `update_status` as work progresses, then `complete` or `release`.
+
+## Logging and State Files
+
+There are two separate state areas:
+
+- Repo-local state in `./.remits-cli/` for request/response artifacts tied to the current working tree.
+- Global state in `~/.remits-cli/` for authentication, listener lifecycle, and cross-repo account mapping.
+
+### Repo-local state
+
+- `./.remits-cli/sessions/<current-session>.jsonl`
+  Records all `/cli/*` HTTP requests made from the current repo session.
+- `./.remits-cli/tool-responses/<callId>.json`
+  Stores full tool responses for `remits-cli tool`.
+- `./.remits-cli/tools/tools.json`
+  Cached tool definitions for the current repo.
+- `./.remits-cli/current-session.txt`
+  Tracks the active local session log name.
+
+### Global state
+
+- `~/.remits-cli/sessions.json`
+  Auth sessions keyed by account ID, base URL, and data mode so local and production sessions can coexist safely.
+- `~/.remits-cli/config.json`
+  CLI config such as the preferred agent.
+- `~/.remits-cli/listener.pid`
+  PID for the background remits-cli service process.
+- `~/.remits-cli/service-state.json`
+  Dashboard URL, repo scan summary, and websocket state snapshot for the running service.
+- `~/.remits-cli/dispatch-panes.json`
+  Persistent map of support ticket routing key to the active tmux pane id for that ticket's dedicated window. `ticketId` is preferred, with legacy `taskId` fallback.
+- `~/.remits-cli/account-repos.json`
+  Index of known account repositories on this machine, rebuilt by `remits-cli start` via account-info discovery and also refreshed when commands run inside an account repo.
+- `~/.remits-cli/tmux-activity.log`
+  Human-readable global activity log for listener and tmux lifecycle events.
+
+## Control Center
+
+- `remits-cli start` prints or records a localhost dashboard URL such as `http://127.0.0.1:8787/`.
+- Open that page in a browser to inspect the full local remits-cli integration state without manually opening JSON files.
+- The page refreshes automatically and includes the latest global state files plus per-repo `account-info.json`, local tools snapshot, and current session log tail for every indexed account repo.
+
+## Tmux Activity Log
+
+- `~/.remits-cli/tmux-activity.log` is the quickest way to understand what the listener is doing.
+- It records timestamped lifecycle events such as listener start/stop, websocket connect/disconnect, topic subscription, dispatch receipt, pane creation, follow-up delivery, pane replacement, and dispatch failures.
+- Prompt bodies are not written verbatim to this log. The log stores summarized metadata such as `accountId`, `ticketId`, any legacy `taskId`, available keys, and prompt length.
+- Typical inspection commands:
+
+```bash
+tail -f ~/.remits-cli/tmux-activity.log
+tail -n 200 ~/.remits-cli/tmux-activity.log
+```
+
+## Operational Notes
+
+- `tmux` must be installed for agent dispatch to work. Without it, websocket dispatch is received but agent panes cannot be created.
+- In sandboxed local agent environments, `remits-cli` network calls may fail with `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM`, or similar errors even when dispatch worked correctly. That means the command needs escalated permissions or must be run outside the sandbox.
+- If the platform returns a 500 or other unexpected server-side failure, stop normal task execution and escalate to a Remits system admin. Agents should not invent workarounds for platform faults.
+- Recommended durable update flow for agents: `components stage` for testing, then `git add/commit/push`, then `remits-cli components sync`, then `git pull --ff-only` to confirm platform-generated files like `account-info.json`.
+- In sandboxed agent environments, local git writes may require a single approval step. If you want to minimize approval churn, `remits-cli components commit` consolidates the local git and sync phases into one CLI command.
+- If account repo discovery fails for a websocket message, dispatch is skipped because the listener does not know which local directory to open for that account.
+- If you authenticate a new account while the listener is already running, the listener now refreshes its websocket clients automatically instead of requiring a manual restart.
+- Session logs redact token fields and replace large component content fields with length summaries.