rallysmith 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of rallysmith might be problematic. Click here for more details.

Files changed (39) hide show
  1. package/.claude-plugin/mcp.json +12 -0
  2. package/.claude-plugin/plugin.json +22 -0
  3. package/.codex-plugin/mcp.json +12 -0
  4. package/.codex-plugin/plugin.json +38 -0
  5. package/LICENSE +201 -0
  6. package/README.md +42 -0
  7. package/assets/rallysmith-icon.png +0 -0
  8. package/assets/rallysmith-icon.svg +31 -0
  9. package/cli.mjs +4 -0
  10. package/docs/dashboard.md +67 -0
  11. package/docs/distribution.md +119 -0
  12. package/docs/host-support.md +44 -0
  13. package/docs/release-policy.md +33 -0
  14. package/docs/server.md +79 -0
  15. package/docs/usage.md +95 -0
  16. package/launcher.mjs +199 -0
  17. package/notices/MCP-SDK-LICENSE +216 -0
  18. package/notices/RUST-1.97.1-COPYRIGHT-library.html +5556 -0
  19. package/notices/THIRD-PARTY-NOTICES.md +1781 -0
  20. package/notices/preview-dependency-notices.zip +0 -0
  21. package/notices/preview-notice-inventory.tsv +630 -0
  22. package/package.json +68 -0
  23. package/skills/independent-review/SKILL.md +8 -0
  24. package/skills/independent-review/agents/openai.yaml +6 -0
  25. package/skills/independent-review/assets/icon.svg +6 -0
  26. package/skills/scoped-delegation/SKILL.md +8 -0
  27. package/skills/scoped-delegation/agents/openai.yaml +6 -0
  28. package/skills/scoped-delegation/assets/icon.svg +6 -0
  29. package/skills/start-team/SKILL.md +34 -0
  30. package/skills/start-team/agents/openai.yaml +6 -0
  31. package/skills/start-team/assets/icon.svg +6 -0
  32. package/skills/start-team/references/board-and-messaging.md +13 -0
  33. package/skills/start-team/references/cli-workflow.md +13 -0
  34. package/skills/submission-handoff/SKILL.md +12 -0
  35. package/skills/submission-handoff/agents/openai.yaml +6 -0
  36. package/skills/submission-handoff/assets/icon.svg +6 -0
  37. package/skills/team-coordination/SKILL.md +14 -0
  38. package/skills/team-coordination/agents/openai.yaml +6 -0
  39. package/skills/team-coordination/assets/icon.svg +6 -0
@@ -0,0 +1,33 @@
1
+ # Release and recovery policy
2
+
3
+ The executable supports authorized project content. The npm installer and native platform implementations require target-specific qualification before public distribution. A production release must identify its supported Codex/Claude entrypoints and versions, exact source revision, executable and lockfile hashes, runtime prerequisites, distribution channel and known limits.
4
+
5
+ ## Build candidate
6
+
7
+ Use a clean reviewed source tree and locked dependencies. Rebuild the embedded UI when its source changes, then build the executable. Stage each candidate in a fresh directory outside repositories, check its complete file manifest and verify that both host packages refer to the same executable.
8
+
9
+ Use `node packaging/build-native.mjs` for distributable native builds. It remaps build-machine source paths, retains target-specific linker configuration and rejects detected local paths in the executable. Package only the resulting checked executable. Inspect the packaged binary too; compiler remapping does not cover every possible linker-generated or independently embedded string.
10
+
11
+ `build-release.mjs` also generates both host plugin definitions inside the root npm candidate and prepares separate exact-version npm catalogs under `OUTPUT/distribution`. Source templates remain neutral on `main`. Publish qualified npm packages before a separately approved update to the release-only `distribution` branch; never put the source tree or a local `./` plugin entry on that branch. Validate the packed plugin and generated catalogs, and keep version pins aligned. Artifact preparation does not publish or configure installed hosts.
12
+
13
+ Run the complete available Rust, Python and React suites against the candidate, including applicable native console, owner review, access boundaries, invitation replay, recovery, message/artifact and board checks. Record environment failures accurately; previous results do not qualify a changed candidate.
14
+
15
+ A distributable needs a separately validated recipient-local layout and installation process. Do not publish an existing personal installation or preview bundle as a relocatable release.
16
+
17
+ ## Update and recovery
18
+
19
+ npm owns executable package versions; host plugin managers own plugin versions. Close active native invocations before replacing packages, especially on Windows. Keep matching pinned versions across root/platform npm packages, plugins and direct registrations. Refresh direct registrations with the new native `setup` command. Keep mailbox data outside the application bundle, with its selected location saved independently of integration removal. Rehearse project-scoped backup and restore in disposable private storage and verify that other projects survive. Unsupported schemas must fail visibly; there is no implicit legacy-data conversion.
20
+
21
+ Stop affected invocations before removing a checked package. Remove only that package's host registrations and files; user mailboxes, exported snapshots and host chat histories have a separate lifecycle. Follow [backup and restore](usage.md#backup-and-restore) before any owner-authorized data change.
22
+
23
+ Native setup rolls back detected in-process write failures and preserves detected concurrent owner edits; it does not claim atomic multi-file recovery across power loss. Inspect `setup-status` after an interrupted operation. Exact-source native build/runtime checks and a same-version npm repair test do not establish a future schema upgrade path.
24
+
25
+ ## Distribution gates
26
+
27
+ - Verify the actual shipped components, applicable licenses/notices and toolchain/runtime requirements.
28
+ - Qualify native execution, installation/removal and upgrades separately for every advertised OS/architecture and host. A Windows build or mocked path test cannot qualify macOS/Linux. Native CI must pass before publishing each target.
29
+ - Verify host identity/review behavior and supported lifecycle on named host versions.
30
+ - Keep credentials, live data, logs, private session identifiers, machine-specific paths and internal development records out of the public tree and package.
31
+ - Validate the exact distributable artifact, not only a development executable.
32
+
33
+ Rallysmith uses the trusted operating-system account boundary. Same-user malicious process isolation and encryption at rest are not implemented. Public publication, service installation and adoption in another project are separate operator actions.
package/docs/server.md ADDED
@@ -0,0 +1,79 @@
1
+ # Rallysmith server
2
+
3
+ The Rust executable provides a stdio MCP server, local account storage, project/team setup, scoped messages and artifacts, canonical project rules, chat bindings and a loopback owner dashboard. It supports authorized project content. Native Windows/macOS/Linux qualification is tracked in the [support matrix](host-support.md).
4
+
5
+ ## Startup and data
6
+
7
+ Use `rallysmith codex` or `rallysmith claude` as the normal Desktop MCP command, started in the selected project workspace. Both use one account-local `rallysmith.sqlite` for every project. Fresh Windows setup creates `%LOCALAPPDATA%\Rallysmith\data\mailbox` with an account-private parent for Claude Desktop. Setup preserves existing mailbox locations. Native setup saves its selected directory for ordinary CLI, UI and MCP startup, including after integration removal. Without a saved selection, standalone commands use `%LOCALAPPDATA%\Rallysmith` on Windows, `~/Library/Application Support/Rallysmith` on macOS, and `${XDG_DATA_HOME:-~/.local/share}/Rallysmith` on Linux. An explicit `RALLYSMITH_DATA_DIR` overrides the complete root. The provider selects the appropriate host identity and review path. See [host configuration](usage.md).
8
+
9
+ Participant credentials are generated locally in `mailboxes/PROJECT/credentials/PARTICIPANT.token` below that private root. Windows uses private ACL, owner and reparse-point checks. POSIX storage requires current-user ownership, directories no broader than 0700, regular files no broader than 0600, and trusted non-writable ancestors. Symlinks, shared roots and permission drift fail closed without silently repairing existing data. macOS extended ACL allow entries are also rejected. New private files receive restrictive creation modes before content is written. Same-user malicious process isolation is outside the trust model.
10
+
11
+ `RALLYSMITH_MCP_LOG=1` enables optional diagnostics at `mcp-diagnostics.jsonl` below the selected private root. It is disabled by default and records transport/tool metadata rather than arguments, bodies, credentials or review proofs. For a Claude review creation failure, the tool also returns the failing step and available OS or SQLite error codes so that a storage failure can be diagnosed even when the log cannot open. Logs and the live data directory must not be committed or shipped.
12
+
13
+ Each logged connection has a random UUID, process ID and startup executable SHA-256/version. Request/response pairs retain numeric RPC IDs (string IDs are hashed), tool names, allowlisted result codes/states and a hash of valid message/dedupe UUIDs for send reconciliation. Similar payloads with different IDs remain separate operations. No body, preview, project/participant IDs, raw operation UUIDs, credentials or paths are recorded. EOF and transport-error events distinguish observed stream closure from an application result; they do not establish why a host closed the stream or prove a process crash. Missing events alone are inconclusive, particularly if logging was disabled, the connection used another root, or the process was killed.
14
+
15
+ ## Setup, identity and rules
16
+
17
+ Managers use `create_manager_project`, `issue_manager_invitation` and `join_manager_project` through their host connection. Setup and rules changes require owner review of the exact proposal. Invitations are one-time and add a separate team to the existing project. They grant manager messaging, not cross-team artifacts or member inboxes.
18
+
19
+ Rallysmith generates UUIDs independently of names. `get_my_identity` recovers the current chat's saved participant, project/team names and IDs, manager contact and project-owner flag. Custom roles are nonblank safe labels up to 128 Unicode characters. Presets are suggestions; the recorded manager participant ID determines manager authority.
20
+
21
+ Project/team/participant names allow safe Unicode, punctuation and emoji up to 256 characters. Team names and participant names must be unique within the project after trimming and Unicode lowercase comparison; stored display text retains the approved spelling. Control and directional formatting characters are rejected. Host chat references, cryptographic proofs and digests retain their own formats and do not grant authority by themselves.
22
+
23
+ Rules are project-wide. Only the founding manager proposes `update_project_rules` for owner approval. Each participant fetches `get_team_rules` and adopts its exact current revision/digest using its own `ack_team_rules` proof. Membership, credential or binding changes invalidate affected adoption. `get_team_status` reports recorded readiness, not current chat liveness. No member can adopt for another participant.
24
+
25
+ Rules are nonblank and at most 16 KiB of UTF-8. Full-content fetch evidence is scoped to the authenticated participant, current binding/credential, rules revision and MCP connection, and expires after ten minutes. A restarted connection fetches for itself. Publishing rechecks the exact approved content, predecessor, founding-manager authority and roster; a changed proposal or stale revision requires fresh review. Peer messages and rule text cannot establish publishing authority or override higher-priority host instructions.
26
+
27
+ Setup receipts describe approved setup-time observations, not current readiness. Desktop launch reservations retain the native host-returned child ID, creator and workspace. The child onboards through its own host connection against that reservation. Missing launch evidence stays pending; uncertain launches are reconciled rather than replaced. Readiness requires the current required roster's saved bindings and own-connection rule adoption; it does not prove chat liveness or future compliance.
28
+
29
+ ## Messages and artifacts
30
+
31
+ Use `generate_ids` for new message/artifact/request IDs, and retain IDs on unchanged retries. `send_message` requires the authenticated sender, recipient and current send grant. Its `data_class` defaults to `project`; `synthetic` is also valid for isolated tests; omit `destination` or use `pilot-mailbox`.
32
+
33
+ `send_message` mutates an account-local SQLite mailbox, not a network destination selected by its caller. Participant UUIDs select recipients under project/peer grants; they are not URLs. This says nothing about whether the host or model processes content remotely. Tool annotations describe these semantics and do not grant trust or bypass host review. The flat MCP input schema describes field types and enum/length limits; Rust validates cross-field envelope requirements and authority before storage.
34
+
35
+ Distinguish these outcomes:
36
+
37
+ - **Host denial:** Auto-review can reject before dispatch. Report the exact observed denial and stop; Rallysmith cannot approve it or know a host approval is pending. Do not retry, relay or repackage the denied content.
38
+ - **Server rejection:** `unauthorized` means Rallysmith received a call but could not authorize its routing, binding, identity or grants. It is not an owner-approval request. Recover only the current chat's own identity and inspect the intended scope.
39
+ - **Unknown:** a missing/failed response does not establish whether a commit happened. Preserve operation IDs and reconcile with `get_send_status` and `check_send_payload`. Not-found cannot exclude an in-flight commit; recovery or retry remains a separate authorized mutation.
40
+ - **Stored/existing:** the message is committed (or the identical request was already committed). Receipt and acknowledgment remain separate recipient actions, and neither establishes execution or task completion.
41
+
42
+ Only offer host approval controls verified for the actual host/version. OpenAI documents `/approve` for its open-source TUI; that does not establish support in Codex Desktop or an MCP API Rallysmith can invoke. See [Auto-review](https://learn.chatgpt.com/docs/sandboxing/auto-review).
43
+
44
+ Optional envelope metadata consists of `kind` and `preview` together, plus a UUID `correlation_id` and a nonempty body. Kinds are `delegation`, `handoff`, `review` and `coordination`; preview is at most 256 Unicode characters. Invalid metadata returns `invalid_request` with the relevant field and correction. A `reply_to_message_id` must reference an authorized incoming message.
45
+
46
+ `get_send_status` and `check_send_payload` inspect uncertain outcomes before a retry; `recover_send` resumes an authorized durable intent and `cancel_pending_send` cancels a still-pending intent. A stored result does not mean delivery. Recipients separately use `list_unread`, `read_message`, `mark_received` and `ack_message` under their grants. Acknowledgment is not task completion.
47
+
48
+ Deduplication is scoped by the authenticated sender, project and operation. Identical authorized retries preserve the original result; changed content under the same IDs conflicts. Unknown outcomes remain unknown until checked. Message state cannot establish review, acceptance or execution. Referencing an artifact never grants access, and a changed candidate invalidates affected review and testing.
49
+
50
+ `put_artifact` stores bounded bytes with producer, recipient, candidate and SHA-256. `get_artifact` requires the intended recipient and current grants. Artifact copies for different authorized recipients are separate records. Referencing an artifact does not grant access; candidate/digest and independent review/test reports must refer to the same work.
51
+
52
+ ## Board and dashboard
53
+
54
+ `record_team_task`, `update_team_task` and `get_runtime_view` are available to registered teams automatically. Managers manage team work; members update assigned tasks. Current binding, membership, rule adoption, expected revision and evidence checks remain enforced. Done requires a matching authorized artifact and remains `reported_not_independently_verified`.
55
+
56
+ Tasks use Backlog, Todo, In progress, In review, Done and Deferred. Creation starts in Backlog or Todo. In review requires a named candidate; Deferred requires a blocker. Blocked is a separate grouping and can accompany active work. Task updates compare the expected revision and recheck current evidence access, including on retries. Message storage, receipt, acknowledgment and review-message presence never advance a task automatically.
57
+
58
+ `rallysmith --web` opens the owner dashboard in a browser at port 5869 by default. `--port PORT` overrides it and `--no-open` suppresses browser launch. The printed access link establishes a private browser cookie named for the port, so simultaneous dashboards can share a browser profile. In desktop mode (`--desktop` or `--ui`), the server binds a separate loopback port and passes the private link directly to the Rallysmith window. If the window fails to confirm startup within 30 seconds, Rallysmith closes the listener and stops the desktop process. Both modes require CSRF, Host and Origin checks for writes. The server bounds request lifetimes and concurrent connections. In web mode, Q-to-quit and previous-screen restoration are supported in interactive Windows terminals. Stop ends either session. Closing the desktop window also ends its session, while closing a browser tab leaves its session running.
59
+
60
+ HTTP headers and request bodies share a two-second read deadline; response writes have a separate two-second budget. Headers are limited to 16 KiB, bodies to 64 KiB, and at most 16 connections are handled concurrently. A stalled connection expires without stopping the UI process. Responses are not cached, refuse framing and use a nonce Content Security Policy. The local access link and cookie protect against other websites and users, not malicious processes under the same trusted operating-system account.
61
+
62
+ The owner sees metadata for every stored project message, including historical and cross-team routes. Agent MCP views retain their own grants. Bodies, credentials and artifact bytes are excluded from snapshots. `export-workspace-local` writes a private disconnected owner snapshot; `export-team-view-local PROJECT TEAM` writes a scoped team snapshot. Regenerate exports to refresh them.
63
+
64
+ The live owner's Activity view retrieves stored history through cookie-authenticated `/api/activity` pages. Project/team, member, event group and text filters apply before selecting each page. Session-signed cursors bind the page boundary to its scope and filters, with a stable event key for equal timestamps. Each request returns at most 100 metadata entries (the UI requests 50); this page size is not a total-history cutoff. Newer inserts do not shift an older page boundary. This read-only route does not widen agent MCP access, change snapshot bounds, migrate the database or fetch message bodies/artifact bytes.
65
+
66
+ ## Local owner commands
67
+
68
+ Administrative commands run under the trusted local account; peer content cannot authorize them:
69
+
70
+ When run in a terminal, local commands print a readable result. Append `--json` to setup, status, uninstall or a local report command for machine-readable output. Piped results keep their existing JSON format. Set `NO_COLOR` for plain terminal output.
71
+
72
+ - `setup`, `setup-status` and `uninstall` manage direct host MCP/skills integration. Setup preserves unrelated TOML/JSON settings and records private ownership and backups. Native uninstall removes only unchanged owned integrations. The global npm launcher then removes its command and platform package. The mailbox and its saved location are retained. See [distribution](distribution.md).
73
+ - `team-presets` lists roster suggestions. `start-team-local PROJECT_NAME PRESET` guides fresh CLI setup; `get-team-setup-local PROJECT TEAM` reads its saved receipt. CLI role lists accept comma-separated values or a JSON array for labels containing commas.
74
+ - `create-team-chats-local PROJECT TEAM WORKSPACE`, `get-team-chats-local PROJECT TEAM` and `reconcile-team-chat-local PROJECT TEAM PARTICIPANT` manage explicitly selected independent CLI chats. Uncertain launches are retained and never blindly recreated. Desktop setup uses the host's native chat creation tools instead.
75
+ - `onboard-team-local PROJECT TEAM` coordinates saved CLI rule adoption; `--allow-claude-rules` is an explicit operator choice for the narrow Claude continuation. Host denials still apply.
76
+ - `backup-local PROJECT NAME` and `restore-local PROJECT NAME BASE PARTICIPANTS...` support project-scoped recovery. See the [recovery guide](usage.md#backup-and-restore).
77
+ - Rotation, revocation and configuration commands remain operator workflows. The [local-account tests](https://github.com/Piyeycorp/rallysmith/blob/main/tests/integration/test_local_account.py) and [rule tests](https://github.com/Piyeycorp/rallysmith/blob/main/tests/integration/test_team_rules.py) show their validation boundaries.
78
+
79
+ Build and test commands are in the [product README](../README.md). Test-only record schemas and fixtures live under `tests/integration/schemas` and `tests/integration/fixtures`; the executable enforces authority and cross-field relationships directly in Rust. Private credentials, data, logs and recovery snapshots are never package contents.
package/docs/usage.md ADDED
@@ -0,0 +1,95 @@
1
+ # Use Rallysmith
2
+
3
+ Rallysmith runs under the current operating-system account. Keep its executable/package at its installed location and its database outside the application bundle. Project content is supported within the approved project and peer permissions.
4
+
5
+ ## Open the dashboard
6
+
7
+ Run `rallysmith --desktop` or `rallysmith --ui` to open a desktop window. Close the window or use its Stop button to end that dashboard session.
8
+
9
+ Run `rallysmith --web` to open the same dashboard in your browser. It listens on `127.0.0.1:5869` by default. Use `--port PORT` for another nonzero port and `--no-open` to print the private access link without opening a browser. An occupied port produces an error.
10
+
11
+ Press Q or q in the interactive Windows terminal, without Enter, to stop and restore the prior screen. Browser Stop supports redirected/noninteractive launches. The server has no automatic idle shutdown; closing the browser tab leaves it running. `NO_COLOR` disables colors. Forced process termination cannot run terminal cleanup.
12
+
13
+ The dashboard provides project/team filters, board tasks, readiness, messages and activity. Every registered team has its board automatically. The owner message history includes all project routes; agent MCP access remains separately scoped. Message bodies and artifact bytes are not loaded into the dashboard. Message pagination filters the complete metadata collection before selecting a page.
14
+
15
+ Choose **Archive** on a project card in **All projects**, or use **Archive project** or **Archive team** in the board header. Select **Archived** at the bottom of the sidebar to open the read-only list of archived projects and teams. Use **Restore** there to return an item to the active list. Restoring a project keeps any separately archived teams in the archive. Archiving preserves tasks, messages, artifacts, and chat bindings. Agent access continues while archived.
16
+
17
+ Right-click a project in the sidebar or on its card for **New task** and **Archive project**. New task opens the form for that project. Use the chevron beside a sidebar project to show or hide its teams.
18
+
19
+ On the **Team** tab, choose **Remove member** to end that participant’s Rallysmith access and take them off the active roster. Their messages, artifacts, task history, and Codex or Claude chat are kept. The current team manager and the founding manager are protected from removal.
20
+
21
+ ## Account-wide host connection
22
+
23
+ The [host plugins](distribution.md#host-plugin-installation) bundle MCP configuration and skills. Use [`npx -y rallysmith setup`](distribution.md#account-setup) for account-wide installation. Setup registers the native executable by absolute path and uses a local Codex plugin when supported. Use one route per host. Replace the example path below with the path to the installed native executable when configuring a host manually.
24
+
25
+ ```json
26
+ {
27
+ "mcpServers": {
28
+ "rallysmith": {
29
+ "command": "/absolute/path/to/rallysmith",
30
+ "args": ["claude"]
31
+ }
32
+ }
33
+ }
34
+ ```
35
+
36
+ For Codex, use its TOML MCP configuration and the argument `codex`:
37
+
38
+ ```toml
39
+ [mcp_servers.rallysmith]
40
+ command = "/absolute/path/to/rallysmith"
41
+ args = ["codex"]
42
+ ```
43
+
44
+ No token belongs in this configuration. Both providers use one database in the [platform data root](server.md#startup-and-data). Native setup saves a deliberate `--data-dir` selection for ordinary CLI, MCP and UI startup as well as setting it on direct registrations. A manual environment override must be consistent across both hosts and the UI.
45
+
46
+ ### Claude review connector
47
+
48
+ Claude Desktop project chats use embedded review cards automatically. Local Code chats use their authenticated Code connection, with a separate Desktop owner-UI connection for review. Both invoke the same npm/native command with the `claude` provider, with no project or workspace argument. Direct registrations set only the shared data root in their environment. Restart Claude Desktop after changing configuration. The owner UI handles pending review IDs across projects; it cannot act as a project participant. The originating Code chat alone consumes its exact approved proposal. With the Code plugin, run `rallysmith setup --hosts claude-desktop` for the additional owner connection. Without the plugin, select `--hosts claude-code,claude-desktop` to configure both directly.
49
+
50
+ The card displays the exact setup or rule proposal. Use its approval controls; ordinary chat text does not substitute for a recorded decision. If a tool returns `review_pending`, open its review through the indicated connector, then continue the originating operation with the unchanged proposal. Changed proposals require fresh review. An unavailable card leaves the review pending; report unavailable controls rather than using another approval route.
51
+
52
+ During project creation or invitation joins in a Claude Desktop local Code chat, use **Approve proposal** or **Request changes** on the Rallysmith card. The manager chat waits up to two minutes and resumes when the card records your decision. If the wait ends first, use the card and continue in the same manager chat. Other Claude reviews use a separate native **Continue** question. Rallysmith checks the saved decision before applying the proposal.
53
+
54
+ ## Create or join a team
55
+
56
+ Ask a manager chat to create a project and team, or to join using an invitation. Names may contain safe Unicode, punctuation and emoji; project/team/participant IDs are generated UUIDs. Team names and participant names must be distinct within their project. Custom role labels are supported up to 128 Unicode characters; they do not confer manager authority.
57
+
58
+ Review project/team names, the manager/member roster, full rules and creation/chat scope before approving. Setup opens new independent member chats using the selected host. Managers record the host-returned launch references and coordinate each member's onboarding and rule adoption. Retain unknown/failed launch attempts for reconciliation rather than creating duplicates.
59
+
60
+ The founding manager issues a one-time invitation for another manager with a separate team. The invitation binds the join to the existing project and current rules. It grants manager messaging, not cross-team artifact access or ordinary member inboxes.
61
+
62
+ ## Rules and readiness
63
+
64
+ Rules are project-wide. `get_my_identity` identifies the founding manager using `is_project_owner`. That manager proposes `update_project_rules` for owner review. Each participant fetches and acknowledges the exact current revision/digest for its own binding; a manager cannot acknowledge for members.
65
+
66
+ Newly approved setups allow authorized project content. Existing projects keep their saved rules; installation does not silently rewrite them. Managers coordinate their members and report recorded readiness. Readiness does not establish that a chat is running or will automatically process stored mail. Use an explicit follow-up in an existing manager chat when needed.
67
+
68
+ ## Messages, artifacts and tasks
69
+
70
+ Message `data_class` defaults to `project`; use `synthetic` for isolated test content. The local destination can be omitted. Generate UUIDs for new records and retain them on unchanged retries. Check uncertain send outcomes before repeating them. Recipients separately record receipt and acknowledgment; neither is execution or task completion.
71
+
72
+ For optional message envelopes, supply `kind` and `preview` together with a UUID `correlation_id` and nonempty body. Kinds are `delegation`, `handoff`, `review` and `coordination`; preview is at most 256 Unicode characters. Validation errors identify the field to correct.
73
+
74
+ Check current peer grants before choosing an artifact recipient. Use Rallysmith artifact storage/retrieval and verify exact bytes, candidate and digest. A reference does not grant access. Keep independently authored review/test reports tied to the same candidate.
75
+
76
+ Create actual board tasks and report their state transitions explicitly. Done requires matching authorized evidence and remains a report rather than independent platform verification. Owner edits are labelled and revision-checked. Drag empty board space to scroll; drag a card to move it, or open its editor for keyboard operation.
77
+
78
+ ## Backup and restore
79
+
80
+ ```powershell
81
+ rallysmith backup-local PROJECT SNAPSHOT
82
+ rallysmith restore-local PROJECT SNAPSHOT 'C:\path\to\recovery-base' PARTICIPANT_UUID_1 PARTICIPANT_UUID_2
83
+ ```
84
+
85
+ Backups are private project-scoped snapshots below `backups/` in the selected platform data root. A failed operation may retain private staging for inspection. Restore reads the named snapshot from the current data root and writes to the explicit recovery base. It can add an absent project to a database containing other projects without replacing them. An identical retry is bound to the same snapshot and selected roster.
86
+
87
+ Restore creates fresh credentials for selected participants, revokes unselected participants and old publication approvals, cancels pending sends and requires rule readoption. Snapshot-era authority may be older than later revocations: the operator must reconcile the selected roster with current decisions. Do not point restore at live data or attempt legacy-schema conversion without a separately qualified procedure.
88
+
89
+ ## CLI workflows and removal
90
+
91
+ `team-presets` lists CLI roster suggestions. `start-team-local "PROJECT NAME" PRESET` guides fresh CLI setup without creating chats. `get-team-setup-local PROJECT TEAM` reads the saved receipt. CLI role lists accept comma-separated values or a JSON array for labels containing commas.
92
+
93
+ `create-team-chats-local PROJECT TEAM WORKSPACE` separately reviews and creates independent CLI chats. Use `get-team-chats-local PROJECT TEAM` to inspect attempts and `reconcile-team-chat-local PROJECT TEAM PARTICIPANT` to check uncertain launches without recreating them. `onboard-team-local PROJECT TEAM` coordinates saved-chat rules adoption. Its `--allow-claude-rules` option requires explicit operator authorization for the narrow Claude continuation; denials remain effective. The optional CLI wake workflow is operator-confirmed and does not support Desktop bindings.
94
+
95
+ Use native `setup-status` to inspect direct integrations and `uninstall` to remove unchanged owned registrations/skills and restore replaced entries. Retain the same `--home`/`--codex-home` location options used for setup. Native uninstall preserves the selected data root and does not remove npm binaries. npm manages package updates/removal; the host plugin manager manages plugins. Close affected invocations before replacing native files, especially on Windows. Mailboxes, exports and host-owned chats have a separate lifecycle.
package/launcher.mjs ADDED
@@ -0,0 +1,199 @@
1
+ import { spawn, spawnSync } from 'node:child_process';
2
+ import { createHash } from 'node:crypto';
3
+ import { createRequire } from 'node:module';
4
+ import { readFile, realpath, stat } from 'node:fs/promises';
5
+ import path from 'node:path';
6
+
7
+ const platforms = ['win32', 'darwin', 'linux'];
8
+ const architectures = ['x64', 'arm64'];
9
+ const versionPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
10
+ const nativePackage = (platform = process.platform, arch = process.arch) => `@piyeycorp/rallysmith-${platform}-${arch}`;
11
+
12
+ export async function npmCli() {
13
+ const nodeDirectory = path.dirname(process.execPath);
14
+ const entry = process.env.npm_execpath;
15
+ const candidates = [entry && path.join(path.dirname(entry), 'npm-cli.js'),
16
+ path.join(nodeDirectory, 'node_modules/npm/bin/npm-cli.js'),
17
+ path.resolve(nodeDirectory, '../lib/node_modules/npm/bin/npm-cli.js')].filter(Boolean);
18
+ for (const candidate of candidates) {
19
+ if ((await stat(candidate).catch(() => null))?.isFile()) return candidate;
20
+ }
21
+ const result = spawnSync(process.platform === 'win32' ? 'where.exe' : 'which', ['npm'], {
22
+ encoding: 'utf8', windowsHide: true, timeout: 5000,
23
+ });
24
+ for (const candidate of (result.stdout || '').trim().split(/\r?\n/).filter(Boolean)) {
25
+ const filename = candidate.toLowerCase().endsWith('.cmd')
26
+ ? path.join(path.dirname(candidate), 'node_modules/npm/bin/npm-cli.js')
27
+ : await realpath(candidate);
28
+ if (path.basename(filename) === 'npm-cli.js' && (await stat(filename).catch(() => null))?.isFile()) return filename;
29
+ }
30
+ throw new Error('Cannot locate npm-cli.js beside Node or on PATH');
31
+ }
32
+
33
+ export async function resolveNative({ platform = process.platform, arch = process.arch, packageRoot = import.meta.dirname } = {}) {
34
+ if (!platforms.includes(platform) || !architectures.includes(arch)) throw new Error(`Unsupported Rallysmith target: ${platform}-${arch}. No architecture fallback or source build is available.`);
35
+ const root = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
36
+ const name = nativePackage(platform, arch);
37
+ let metadataPath, metadata;
38
+ try {
39
+ metadataPath = createRequire(path.join(packageRoot, 'package.json')).resolve(`${name}/package.json`);
40
+ metadata = JSON.parse(await readFile(metadataPath, 'utf8'));
41
+ }
42
+ catch (error) {
43
+ if (!['MODULE_NOT_FOUND', 'ENOENT'].includes(error.code)) throw error;
44
+ throw new Error(`Missing optional native package ${name}@${root.version}. Reinstall with npm optional dependencies enabled (omit neither optional dependencies nor this target). This target may not have a published qualified package yet.`);
45
+ }
46
+ const relative = `bin/rallysmith${platform === 'win32' ? '.exe' : ''}`;
47
+ if (root.name !== 'rallysmith' || typeof root.version !== 'string' || !versionPattern.test(root.version) || metadata.name !== name || metadata.version !== root.version || !Array.isArray(metadata.os) || metadata.os.length !== 1 || metadata.os[0] !== platform || !Array.isArray(metadata.cpu) || metadata.cpu.length !== 1 || metadata.cpu[0] !== arch || metadata.rallysmith?.executable !== relative) {
48
+ throw new Error(`Invalid native package metadata or version mismatch for ${name}; expected ${root.version} and executable ${relative}. Reinstall matching npm packages.`);
49
+ }
50
+ const directory = await realpath(path.dirname(metadataPath));
51
+ const executable = await realpath(path.join(directory, relative));
52
+ const contained = path.relative(directory, executable);
53
+ if (contained.startsWith(`..${path.sep}`) || contained === '..' || path.isAbsolute(contained) || !(await stat(executable)).isFile()) throw new Error(`Native executable is outside its package containment boundary: ${name}`);
54
+ return executable;
55
+ }
56
+
57
+ function runNpm(npm, args) {
58
+ const result = spawnSync(process.execPath, [npm, ...args], {
59
+ encoding: 'utf8', windowsHide: true, timeout: 180_000,
60
+ });
61
+ if (result.error) throw result.error;
62
+ if (result.status !== 0) throw new Error(result.stderr.trim() || `npm ${args[0]} failed (${result.status})`);
63
+ return result.stdout.trim();
64
+ }
65
+
66
+ function globalPackageRoot(npm) {
67
+ const globalRoot = runNpm(npm, ['root', '--global']);
68
+ if (!path.isAbsolute(globalRoot) || /[\r\n]/.test(globalRoot)) throw new Error('npm returned an invalid global package directory');
69
+ return path.join(globalRoot, 'rallysmith');
70
+ }
71
+
72
+ async function globalSetupExecutable() {
73
+ const source = JSON.parse(await readFile(path.join(import.meta.dirname, 'package.json'), 'utf8'));
74
+ if (source.name !== 'rallysmith' || typeof source.version !== 'string' || !versionPattern.test(source.version)) {
75
+ throw new Error('Invalid Rallysmith package version');
76
+ }
77
+ if (!platforms.includes(process.platform) || !architectures.includes(process.arch)) {
78
+ throw new Error(`Unsupported Rallysmith target: ${process.platform}-${process.arch}.`);
79
+ }
80
+ const npm = await npmCli();
81
+ const packageRoot = globalPackageRoot(npm);
82
+ const sourceExecutable = await resolveNative();
83
+ const digest = async executable => createHash('sha256').update(await readFile(executable)).digest('hex');
84
+ const expected = await digest(sourceExecutable);
85
+ const installedVersion = async () => {
86
+ const contents = await readFile(path.join(packageRoot, 'package.json'), 'utf8').catch(error => {
87
+ if (error.code !== 'ENOENT') throw error;
88
+ return null;
89
+ });
90
+ return contents === null ? null : JSON.parse(contents).version;
91
+ };
92
+ const sameVersion = await installedVersion() === source.version;
93
+ if (sameVersion) {
94
+ const executable = await resolveNative({ packageRoot }).catch(() => null);
95
+ if (executable && (executable === sourceExecutable || await digest(executable) === expected)) return executable;
96
+ }
97
+ const install = ['install', '--global', '--ignore-scripts', '--no-audit', '--no-fund'];
98
+ if (sameVersion) install.push('--force');
99
+ runNpm(npm, [...install, `rallysmith@${source.version}`]);
100
+ if (await installedVersion() !== source.version) throw new Error('The global Rallysmith package does not match the requested version');
101
+ const executable = await resolveNative({ packageRoot });
102
+ if (await digest(executable) !== expected) throw new Error('The global Rallysmith binary differs from the requested package; reinstall it before setup');
103
+ return executable;
104
+ }
105
+
106
+ function displayPath(value) {
107
+ return value.replace(/[\p{Cc}\u202a-\u202e\u2066-\u2069]/gu, '�');
108
+ }
109
+
110
+ async function uninstallGlobal(args) {
111
+ const npm = await npmCli();
112
+ const packageRoot = globalPackageRoot(npm);
113
+ const installed = await realpath(packageRoot).catch(error => {
114
+ if (error.code !== 'ENOENT') throw error;
115
+ return null;
116
+ });
117
+ if (installed !== await realpath(import.meta.dirname)) {
118
+ throw new Error('Run rallysmith uninstall from the global installation. A project or npx copy does not own that installation.');
119
+ }
120
+
121
+ const executable = await resolveNative({ packageRoot });
122
+ const json = args.includes('--json') || !process.stdout.isTTY;
123
+ const nativeArgs = args.includes('--json') ? args : [...args, '--json'];
124
+ // Wait for the native executable to exit before replacing Windows package files.
125
+ const result = spawnSync(executable, nativeArgs, {
126
+ encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], windowsHide: !process.stdout.isTTY,
127
+ });
128
+ if (result.error) throw result.error;
129
+ if (result.status !== 0) {
130
+ process.exitCode = result.status ?? 1;
131
+ return;
132
+ }
133
+ const report = JSON.parse(result.stdout);
134
+ if (typeof report.removed !== 'boolean' || typeof report.dataPreserved !== 'string') {
135
+ throw new Error('Rallysmith did not confirm host cleanup. Run rallysmith setup-status to inspect the installation.');
136
+ }
137
+ const mailbox = displayPath(report.dataPreserved);
138
+ try {
139
+ runNpm(npm, ['uninstall', '--global', 'rallysmith', nativePackage(),
140
+ '--ignore-scripts', '--no-audit', '--no-fund', '--offline', '--dry-run=false']);
141
+ for (const entry of [packageRoot, path.join(path.dirname(packageRoot), nativePackage())]) {
142
+ const present = await stat(entry).catch(error => {
143
+ if (error.code !== 'ENOENT') throw error;
144
+ return null;
145
+ });
146
+ if (present) throw new Error('Rallysmith package files are still in the npm installation.');
147
+ }
148
+ } catch (error) {
149
+ const integrations = report.removed ? 'Host registrations and skills were removed.' : 'No host registrations were present.';
150
+ throw new Error(`${integrations}\nMailbox kept at ${mailbox}\nnpm could not remove the command. Close Rallysmith and its connected apps, then rerun uninstall.\n${error.message}`);
151
+ }
152
+ if (json) {
153
+ console.log(JSON.stringify({ ...report, commandRemoved: true }));
154
+ } else {
155
+ const colors = !Object.hasOwn(process.env, 'NO_COLOR') && process.env.TERM !== 'dumb';
156
+ const paint = (text, code) => colors ? `\u001b[${code}m${text}\u001b[0m` : text;
157
+ const integrations = report.removed ? 'Registrations and skills removed' : 'No registered integrations';
158
+ console.log([
159
+ '',
160
+ ` ${paint('Rallysmith', '1;33')} ${paint('✓ Uninstalled', '1;32')}`,
161
+ '',
162
+ ' Command Removed from this computer',
163
+ ` Apps ${integrations}`,
164
+ ` Mailbox ${mailbox}`,
165
+ '',
166
+ ' Your mailbox and saved location are ready for a future reinstall.',
167
+ '',
168
+ ].join('\n'));
169
+ }
170
+ }
171
+
172
+ export function reportLaunchError(error) {
173
+ console.error('Rallysmith error');
174
+ for (const line of error.message.split(/\r?\n/)) console.error(` ${displayPath(line)}`);
175
+ process.exitCode = 1;
176
+ }
177
+
178
+ export async function launch(args = process.argv.slice(2)) {
179
+ if (args[0] === 'uninstall') return uninstallGlobal(args);
180
+ const executable = args[0] === 'setup' ? await globalSetupExecutable() : await resolveNative();
181
+ if (args[0] === 'setup' && !args.includes('--codex-plugin')) args = [...args, '--codex-plugin'];
182
+ // GUI MCP hosts use pipes; keep their child console hidden while retaining an attached terminal.
183
+ const child = spawn(executable, args, { stdio: 'inherit', windowsHide: !process.stdin.isTTY && !process.stdout.isTTY });
184
+ const handlers = new Map();
185
+ // Relay signals and exit status for the native invocation.
186
+ for (const signal of process.platform === 'win32' ? ['SIGINT', 'SIGTERM'] : ['SIGINT', 'SIGTERM', 'SIGHUP']) {
187
+ const handler = () => { if (child.exitCode === null && child.signalCode === null) child.kill(signal); };
188
+ handlers.set(signal, handler);
189
+ process.on(signal, handler);
190
+ }
191
+ const cleanup = () => { for (const [signal, handler] of handlers) process.removeListener(signal, handler); };
192
+ child.once('error', error => { cleanup(); reportLaunchError(error); });
193
+ child.once('exit', (code, signal) => {
194
+ cleanup();
195
+ if (signal) process.kill(process.pid, signal);
196
+ else process.exitCode = code ?? 1;
197
+ });
198
+ return child;
199
+ }