Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,16 @@ updates:
groups:
minor-and-patch:
update-types: [minor, patch]
- package-ecosystem: npm
directory: /cli
schedule:
interval: weekly
open-pull-requests-limit: 5
groups:
bun-runtime:
patterns: ["@oven/bun-*"]
opentui:
patterns: ["@opentui/*"]
- package-ecosystem: github-actions
directory: /
schedule:
Expand Down
41 changes: 41 additions & 0 deletions .github/workflows/cli.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
name: Terminal client

on:
push:
pull_request:

permissions:
contents: read

concurrency:
group: cli-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
check:
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest]
runs-on: ${{ matrix.os }}
timeout-minutes: 15
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: 26
cache: npm
cache-dependency-path: cli/package-lock.json
- run: npm ci --include=dev --include=optional --ignore-scripts
working-directory: cli
- run: npm run release:check
working-directory: cli
- run: node bin/gitmsg.mjs --help
working-directory: cli
- run: npm pack --pack-destination "$RUNNER_TEMP"
working-directory: cli
- run: npm run test:package -- "$RUNNER_TEMP"/yiaany-gitmsg-*.tgz
working-directory: cli
7 changes: 7 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,10 @@ credentials.json
/events/
/media/
/exports/
# Terminal build output and accidental local CLI credentials.
/cli/dist/
/cli/*.tgz
.gitmsg-local/
gitmsg-auth.json
gitmsg-room-key.txt
.gitmsg-room-key-*.txt
54 changes: 54 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,59 @@ Use synthetic screenshots and the PR checklist. Never attach tokens, cookies,
private chat exports, room keys, real invite links or full network captures.
Security bugs go through [SECURITY.md](SECURITY.md), not public issues.

## Terminal client

The OpenTUI application lives in **`cli/`**, with a separate npm manifest/lockfile.
It reuses the website's protocol, encryption and call state machine; do not fork
the wire format just to make a terminal feature easier. CLI dependencies do not
belong in the Next.js root package.

Use **Node >=26.4** (OpenTUI's declared engine). Optional npm dependencies provide
the pinned Bun runtime; no separate shell installer is needed:

```sh
cd cli
npm ci --include=dev --include=optional --ignore-scripts
npm run dev
```

`npm run dev` needs a real terminal. Read [CLI usage](docs/CLI.md) for sign-in;
contributors need no production token/client secret. For a separate OAuth app,
enable Device Flow and supply only its public Client ID. Unit/UI tests require no
credentials, microphone permission or real GitHub writes.

Before a CLI PR, from `cli/`:

```sh
npm run release:check
```

Also run the root website tests/typecheck/build for shared protocol changes. The
CI jobs are separate so CLI native dependencies do not enter a website build.

Useful paths:

| Path | Purpose |
| --- | --- |
| `cli/src/app.tsx`, `motion.tsx`, `themes.ts` | Terminal screens, input, animation and themes |
| `cli/src/rooms.ts`, `github.ts`, `device-flow.ts` | Validated GitHub operations and device login |
| `cli/src/credentials.ts`, `room-keys.ts` | OS credential and room-key storage boundaries |
| `cli/src/call-*.ts`, `call-view.tsx`, `calls.ts` | Audio devices, isolated Node WebRTC worker and ASCII UI |
| `cli/bin/`, `cli/scripts/` | Fixed-executable launcher, builds and publication allowlist |
| `cli/tests/` | Synthetic transport, rendering, native WebRTC and failure-path tests |

Preserve drafts, keyboard/mouse navigation, compact layouts, themes and reduced
motion. Microphone diagrams must use measured levels; no fake presence, connection
success or clipboard acknowledgement. Calls/recording never start on an incoming
event or while merely reading a chat. Keep audio queues bounded; stop devices and
workers after cancellation, denial, hangup, sign-out and exit. Never load the
native WebRTC module directly into Bun: it runs in the isolated Node worker.

Use synthetic screenshots. Real OAuth, invites, sends and calls require explicit
consent and private test accounts/rooms. Do not connect tests to somebody's inbox.
Publishing or promoting an npm tag is not a side effect of a PR or test run; follow
the [separate release gates](docs/CLI_RELEASE.md).

## Project guardrails

- Keep interface copy **English** and follow the current components, spacing and
Expand All @@ -62,6 +115,7 @@ Security bugs go through [SECURITY.md](SECURITY.md), not public issues.
| `src/lib/protocol.ts`, `room-crypto.ts` | Event validation, history and encryption |
| `src/lib/audio-call.ts` | Direct audio lifecycle and resource cleanup |
| `src/components/` | Messenger UI and browser integrations |
| `cli/` | Separately packaged OpenTUI messenger, native audio and tests |
| `tests/`, `scripts/check-secrets.mjs` | Regression checks and publication safety |
| `docs/`, `public/integrations/`, `plugins/` | Protocol, CLI and opt-in integrations |

Expand Down
52 changes: 50 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

<p align="center">
<strong>Your DMs. Their version control. Our questionable judgment.</strong><br />
A real messenger built on GitHub. Yes, every “lol” is a commit.
A real messenger built on GitHub. Now in your terminal. Yes, every “lol” is a commit.
</p>

<p align="center">
Expand All @@ -25,14 +25,62 @@
</p>

<p align="center">
<a href="#-wait-this-actually-works">The good stuff</a> ·
<a href="#-wait-this-actually-works">The good stuff</a> ·
<a href="#-your-terminal-can-make-phone-calls-now">Terminal CLI</a> ·
<a href="docs/SETUP.md">Self-host</a> ·
<a href="CONTRIBUTING.md">Contribute</a> ·
<a href="https://github.com/yiaany/gitmsg/issues/new/choose">Break something?</a>
</p>

---

## ☎️ Your terminal can make phone calls now

**Chat. Send voice notes. Call your friends. Without leaving the terminal.**
An actual OpenTUI messenger, not `curl` wearing a trench coat.

> **Bill Gates pays for our DMs. We brought the ASCII art.**
> Your terminal is a phone. Your database is GitHub. Your messages are commits.
> This is either peak engineering or a cry for help. **Holy shit, it works.**
>
> <sub>The Bill Gates part is a joke: GitHub is owned by Microsoft, not a personal
> sponsorship. API quotas, storage, hosting and your network costs still apply.
> Live audio is peer-to-peer, not a Microsoft-funded conference bridge.</sub>

### One install. One command. Your own GitHub account.

**npm release candidate:** `@yiaany/gitmsg@0.1.0-alpha.0`. The commands below are
for **after the first alpha is published**; registry ownership/authorization is
still a release gate. The unrelated npm package `gitmsg` is **not this project**.

With **Node.js >=26.4** and npm:

```sh
npm install --global @yiaany/gitmsg@alpha
gitmsg
```

That's it. npm installs the matching Bun runtime too; no separate shell installer.
Choose **Continue with GitHub**, approve the one-time code, and use your own chats.
No token paste, client secret or personal OAuth app required. Want your own OAuth
app or an existing GitHub API token from your credential manager? [You can →](docs/CLI.md#your-own-github-connection)

- **Real WebRTC audio calls.** Connecting spinner, connected timer, themed ASCII
art and a voice diagram driven by your actual microphone. Not random bars.
- **Messages, images, voice notes, Copy / Reply, per-chat drafts and five themes.**
- **Optional `/secure` encryption.** New content and call signaling use shared
AES-256-GCM keys; audio uses WebRTC transport encryption.
- **`gitmsg` or `git message`**, from any directory. It never commits your project.

Alpha caveats: calls need two-person private-chat metadata; incoming calls follow
the open conversation. No TURN means some networks won't connect. A real
website-to-CLI call still needs live acceptance testing. OAuth asks for broad
`repo` access; standard messages are GitHub-readable. This is not an audited
Signal replacement or an offline messenger.

**[CLI quick start & commands](docs/CLI.md)** · **[Full terminal manual](cli/README.md)** ·
**[Contribute to the CLI](CONTRIBUTING.md#terminal-client)** · **[Release checklist](docs/CLI_RELEASE.md)**

## 💬 Wait, this actually works?

**Chats are repositories. Messages are commits.** “I never said that” now comes with a `git log`.
Expand Down
7 changes: 7 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,13 @@ against other users or production chat repositories without permission.
networks cannot connect. Standard SDP can disclose IP addresses in Git history.
- Public profiles/channels are public. Never make chat/settings/Saved Messages
repositories public when opening this **source-code** repository.
- The terminal OAuth Client ID is public configuration, not a client secret.
Device Flow still requires GitHub approval and requests broad `repo read:user`
access. Tokens use an OS credential store or session memory, never a plaintext
fallback. Keep npm authorization and room-key backups outside source/artifacts.
- npm installs pinned platform runtime/native dependencies. The CLI never fetches
an executable at launch; dependency integrity is not an independent security
audit. [CLI release gates](docs/CLI_RELEASE.md) cover the exact package archive.

See [safe publication](docs/PUBLISHING.md) for the release checklist. Secret
scanners reduce accidents; they cannot prove the absence of all sensitive data.
8 changes: 8 additions & 0 deletions THIRD_PARTY_NOTICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,3 +56,11 @@ the upstream `app/globals.css` and `components/kokonutui/ai-prompt.tsx`.

`qrcode-generator` 2.0.4: Copyright (c) 2009 Kazuhiko Arase, MIT License.
The full MIT terms above apply to this notice.

# Terminal client

The separately packaged OpenTUI client uses React, OpenTUI, platform Bun runtimes
and the isolated Node WebRTC dependency. Package-specific licensing boundaries
and upstream native-code notices are listed in
[`cli/THIRD_PARTY_NOTICES.md`](cli/THIRD_PARTY_NOTICES.md), which is also included
in its npm allowlist. Website-only components/fonts are not part of that payload.
21 changes: 21 additions & 0 deletions cli/LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 gitmsg contributors

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.
Loading
Loading