Add Bun bundle docs and Telegram grammY support
This commit is contained in:
Peter Steinberger
30
docs/mac/bun.md
Normal file
30
docs/mac/bun.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# Bundled Bun runtime (mac app only)
|
||||
|
||||
Date: 2025-12-07 · Owner: steipete · Scope: packaged mac app runtime
|
||||
|
||||
## What we ship
|
||||
- The mac menu-bar app embeds an **arm64 Bun runtime** under `Contents/Resources/Relay/` only for the packaged app. Dev/CI keep using pnpm+node.
|
||||
- Payload: `bun` binary (defaults to `/opt/homebrew/bin/bun`, override with `BUN_PATH=/path/to/bun`), `dist/` output, production `node_modules/`, and the root `package.json`/`pnpm-lock.yaml` for provenance.
|
||||
- We prune dev/build tooling (vite, rolldown, biome, vitest, tsc/tsx, @types, etc.) and drop all non-macOS sharp vendors so only `sharp-darwin-arm64` + `sharp-libvips-darwin-arm64` remain.
|
||||
|
||||
## Build/packaging flow
|
||||
- Run `scripts/package-mac-app.sh` (or `BUN_PATH=/custom/bun scripts/package-mac-app.sh`).
|
||||
- Ensures deps via `pnpm install`, then `pnpm exec tsc`.
|
||||
- Builds the Swift app and stages `dist/`, Bun, and production `node_modules` into `Contents/Resources/Relay/` using a temp deploy (hoisted layout, no dev deps).
|
||||
- Prunes optional tooling + extra sharp vendors, then codesigns binaries and native addons.
|
||||
- Architecture: **arm64 only**. Ship a separate bundle if you need Rosetta/x64.
|
||||
|
||||
## Runtime behavior
|
||||
- `CommandResolver` prefers the bundled `bun dist/index.js <subcommand>` when present; falls back to system `clawdis`/pnpm/node otherwise.
|
||||
- `RelayProcessManager` runs in the bundled cwd/PATH so native deps (sharp, undici) resolve without installing anything on the host.
|
||||
|
||||
## Testing the bundle
|
||||
- After packaging: `cd dist/Clawdis.app/Contents/Resources/Relay && ./bun dist/index.js --help` should print the CLI help without missing-module errors.
|
||||
- If sharp fails to load, confirm the remaining `@img/sharp-darwin-arm64` + `@img/sharp-libvips-darwin-arm64` directories exist and are codesigned.
|
||||
|
||||
## Notes / limits
|
||||
- Bundle is mac-app-only; keep using pnpm+node for dev/test.
|
||||
- Packaging stops early if Bun or `pnpm build` prerequisites are missing.
|
||||
|
||||
## FAQ
|
||||
- **What does `--legacy` do?** When used with `pnpm deploy`, `--legacy` builds a classic flattened `node_modules` layout instead of pnpm's symlinked structure. We no longer need it in the current packaging flow because we create a self-contained hoisted install directly in the temp deploy dir.
|
||||
62
docs/telegram.md
Normal file
62
docs/telegram.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Telegram (Bot API)
|
||||
|
||||
Updated: 2025-12-07
|
||||
|
||||
Status: ready for bot-mode use with grammY (long-poll + webhook). Text + media send, proxy, and webhook helpers all ship in-tree.
|
||||
|
||||
## Goals
|
||||
- Let you talk to Clawdis via a Telegram bot in DMs and groups.
|
||||
- Share the same `main` session used by WhatsApp/WebChat; groups stay isolated as `group:<chatId>`.
|
||||
- Keep transport routing deterministic: replies always go back to the surface they arrived on.
|
||||
|
||||
## How it will work (Bot API)
|
||||
1) Create a bot with @BotFather and grab the token.
|
||||
2) Configure Clawdis with `TELEGRAM_BOT_TOKEN` (or `telegram.botToken` in `~/.clawdis/clawdis.json`).
|
||||
3) Run the relay with provider `telegram` via `clawdis relay:telegram` (grammY long-poll). Webhook mode: `clawdis relay:telegram --webhook --port 8787 --webhook-secret <secret>` (optionally `--webhook-url` when the public URL differs).
|
||||
4) Direct chats: user sends the first message; all subsequent turns land in the shared `main` session (default, no extra config).
|
||||
5) Groups: add the bot, disable privacy mode (or make it admin) so it can read messages; group threads stay on `group:<chatId>` and require mention/command to trigger replies.
|
||||
6) Optional allowlist: reuse `inbound.allowFrom` for direct chats by chat id (`123456789` or `telegram:123456789`).
|
||||
|
||||
## Capabilities & limits (Bot API)
|
||||
- Sees only messages sent after it’s added to a chat; no pre-history access.
|
||||
- Cannot DM users first; they must initiate. Channels are receive-only unless the bot is an admin poster.
|
||||
- File size caps follow Telegram Bot API (up to 2 GB for documents; smaller for some media types).
|
||||
- Typing indicators (`sendChatAction`) supported; inline reply/threading supported where Telegram allows.
|
||||
|
||||
## Planned implementation details
|
||||
- Library: grammY is the only client for send + relay (fetch fallback removed).
|
||||
- Inbound normalization: maps Bot API updates to `MsgContext` with `Surface: "telegram"`, `ChatType: direct|group`, `SenderName`, `MediaPath`/`MediaType` when attachments arrive, and `Timestamp`; groups require @bot mention by default.
|
||||
- Outbound: text and media (photo/video/audio/document) with optional caption; chunked to limits. Typing cue sent best-effort.
|
||||
- Config: `TELEGRAM_BOT_TOKEN` env or `telegram.botToken` required; `telegram.requireMention`, `telegram.allowFrom`, `telegram.mediaMaxMb`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl` supported.
|
||||
|
||||
Example config:
|
||||
```json5
|
||||
{
|
||||
telegram: {
|
||||
botToken: "123:abc",
|
||||
requireMention: true,
|
||||
allowFrom: ["123456789"], // direct chat ids allowed (or "*")
|
||||
mediaMaxMb: 5,
|
||||
proxy: "socks5://localhost:9050",
|
||||
webhookSecret: "mysecret",
|
||||
webhookUrl: "https://yourdomain.com/telegram-webhook"
|
||||
}
|
||||
}
|
||||
```
|
||||
- Tests: grammY-based paths in `src/telegram/*.test.ts` cover DM + group gating; add more media and webhook cases as needed.
|
||||
|
||||
## Group etiquette
|
||||
- Keep privacy mode off if you expect the bot to read all messages; with privacy on, it only sees commands/mentions.
|
||||
- Make the bot an admin if you need it to send in restricted groups or channels.
|
||||
- Mention the bot (`@yourbot`) or use commands to trigger; we’ll honor `group.requireMention` by default to avoid noise.
|
||||
|
||||
## Roadmap
|
||||
- ✅ Design and defaults (this doc)
|
||||
- ✅ grammY long-poll relay + text/media send
|
||||
- ✅ Proxy + webhook helpers (setWebhook/deleteWebhook, health endpoint, optional public URL)
|
||||
- ⏳ Add more grammY coverage (webhook payloads, media edge cases)
|
||||
|
||||
## Safety & ops
|
||||
- Treat the bot token as a secret (equivalent to account control); store under `~/.clawdis/credentials/` with 0600 perms.
|
||||
- Respect Telegram rate limits (429s); we’ll add throttling in the provider to stay below flood thresholds.
|
||||
- Use a test bot for development to avoid hitting production chats.
|
||||
Reference in New Issue
Block a user