From 43f2728283e7e939bd00de85bd06f4952ec94c3e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Guti=C3=A9rrez?= <35082514+alezmad@users.noreply.github.com> Date: Wed, 15 Apr 2026 02:34:45 +0100 Subject: [PATCH] docs: specs for binary distribution pipeline + per-peer capabilities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Capture the design for the two tier-2 items that weren't shipped inline in alpha.28 — both require CI/infrastructure work (GitHub Actions, Homebrew tap, winget manifest) or broker schema migration that's safer to do as a separate PR with feature flag rollout. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-04-15-cli-distribution-pipeline.md | 58 ++++++++++++++ .../specs/2026-04-15-per-peer-capabilities.md | 75 +++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 .artifacts/specs/2026-04-15-cli-distribution-pipeline.md create mode 100644 .artifacts/specs/2026-04-15-per-peer-capabilities.md diff --git a/.artifacts/specs/2026-04-15-cli-distribution-pipeline.md b/.artifacts/specs/2026-04-15-cli-distribution-pipeline.md new file mode 100644 index 0000000..982b6b2 --- /dev/null +++ b/.artifacts/specs/2026-04-15-cli-distribution-pipeline.md @@ -0,0 +1,58 @@ +# CLI Distribution Pipeline + +## Status +- Shell installer (`/install`): ✅ live, needs polish +- Single-binary build script (`scripts/build-binaries.ts`): ✅ written, not wired to CI +- GitHub Releases publish: ❌ not set up +- Homebrew tap: ❌ not set up +- winget manifest: ❌ not set up + +## Shipped this session (alpha.28) +- `bun build --compile` script at `apps/cli-v2/scripts/build-binaries.ts` produces + `dist/bin/claudemesh-{darwin,linux,windows}-{x64,arm64}` locally. +- `/install` updated to use the one-command `claudemesh ` flow. +- `claudemesh url-handler install` registers the `claudemesh://` scheme on the three OSes. + +## What's missing + +### 1. GitHub Actions to build + publish binaries +```yaml +# .github/workflows/release-binaries.yml +on: { push: { tags: ['v*'] } } +jobs: + build: + strategy: { matrix: { target: [darwin-x64, darwin-arm64, linux-x64, linux-arm64, windows-x64] } } + steps: + - uses: oven-sh/setup-bun@v2 + - run: cd apps/cli-v2 && bun install --frozen-lockfile + - run: cd apps/cli-v2 && bun run scripts/build-binaries.ts + - uses: softprops/action-gh-release@v2 + with: { files: apps/cli-v2/dist/bin/* } +``` + +### 2. `/install` detects missing Node and downloads a binary +Current `/install` requires Node 20+. Next iteration: detect absence, curl the +right binary from GitHub Releases, drop it in `~/.claudemesh/bin/`, add to PATH. + +### 3. Homebrew tap (`homebrew-claudemesh`) +Separate repo with a formula that points at the GitHub Release artifact. +Users: `brew install alezmad/claudemesh/claudemesh`. Auto-updated by the +release workflow via `brew bump-formula-pr`. + +### 4. winget manifest +YAML in `microsoft/winget-pkgs` repo pointing at the Windows .exe. + +### 5. Auto-update in-CLI +Already have `showUpdateNotice`. Upgrade to offer `claudemesh upgrade` that +re-runs `/install` OR downloads a new binary in place. + +## Why this matters +Current state: users need Node, npm, and patience. Goal state: +``` +curl -fsSL claudemesh.com/install | sh +``` +…and that's it, on any OS, with or without Node. + +## Priority +After tier-1 usability (done), this is the next biggest lever for adoption. +Estimate: 1-2 days for full pipeline, mostly CI config + release testing. diff --git a/.artifacts/specs/2026-04-15-per-peer-capabilities.md b/.artifacts/specs/2026-04-15-per-peer-capabilities.md new file mode 100644 index 0000000..d0f7aab --- /dev/null +++ b/.artifacts/specs/2026-04-15-per-peer-capabilities.md @@ -0,0 +1,75 @@ +# Per-Peer Capabilities + +## Goal +Give mesh members fine-grained control over what peers can do to their +session. Today: any mesh peer can send you any message; all messages get +pushed as `` reminders. Users can't say "only @alice can send me +messages," "read-only peers," or "@bob can broadcast but not DM." + +## Current state +- Mesh-level role: `admin` | `member` (only affects invite issuance) +- No per-peer filter — every peer message is delivered +- No per-peer read/write split (all peers have the same capabilities) + +## Target capability model + +| Capability | Meaning | +|--------------|--------------------------------------------------------| +| `read` | Peer appears in your list_peers, can see your summary | +| `dm` | Peer can send you direct messages | +| `broadcast` | Peer's group broadcasts reach you | +| `state-read` | Peer can read shared state keys | +| `state-write`| Peer can set shared state keys | +| `file-read` | Peer can read files you've shared (already exists) | + +## CLI surface +``` +claudemesh grant @alice dm broadcast # allow direct + broadcast +claudemesh grant @bob state-read # read-only +claudemesh revoke @alice broadcast +claudemesh grants # list current grants per peer +claudemesh block @spammer # shorthand for revoke-all +``` + +## Broker schema +New column on `mesh_member`: +```sql +peer_grants jsonb DEFAULT '{}'::jsonb + -- shape: { "": ["dm", "broadcast", ...] } +``` + +Alternative (cleaner): separate `peer_grant` table keyed on +`(member_id, target_pubkey)`. + +## Enforcement point +Broker's message router (`apps/broker/src/index.ts` — send flow). +Before writing the encrypted message to the recipient's queue, check +`recipient.peer_grants[sender_pubkey]` against message kind. Drop +silently if disallowed (sender sees delivered, recipient sees nothing — +matches Signal/iMessage block semantics). + +## Defaults +- Unknown peers: `read + dm` (matches current behavior — additive-safe rollout) +- Existing members: grandfathered into `read + dm + broadcast + state-read` + via a migration +- `claudemesh profile --default-grants read dm` lets users change their own default + +## UI +- `claudemesh peers` renders a `[grants: dm,broadcast]` tag per peer +- `claudemesh verify` gains a `--with-grants` flag that shows the grant set + alongside the safety number (helps the "did I accidentally block them?" check) + +## Crypto implications +Grants are server-enforced metadata. Not capability tokens. A malicious +broker could forward messages regardless — this is about UX trust (spam / +noise control), not protocol security. The spec is clear about this. + +## Migration plan +1. Ship broker schema change (jsonb column, nullable, default `{}`). +2. Ship `grant/revoke/grants/block` CLI commands against an unused column. +3. Enable enforcement in broker behind a per-mesh feature flag. +4. Flip on for all meshes. + +## Priority +Nice-to-have. The killer feature here is `block` — every mesh gets a bad +actor eventually. Ship `block` first even if the full grant system is deferred.