blip-boop 0.1.0__tar.gz

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.
@@ -0,0 +1,7 @@
1
+ # Copy to .env, fill in the values, then run: source .env
2
+ export BLIP_BOOP_CLIENT_ID="your-github-app-client-id"
3
+ export BLIP_BOOP_APP_SLUG="your-github-app-slug"
4
+ export BLIP_BOOP_WEBHOOK_SECRET="replace-with-a-long-random-secret"
5
+ export BLIP_BOOP_ADMIN_TOKEN="replace-with-another-random-secret-at-least-32-characters"
6
+ export BLIP_BOOP_MAX_USERS="50"
7
+ export BLIP_BOOP_MAX_TERMINALS="1"
@@ -0,0 +1,124 @@
1
+ # Beta administration
2
+
3
+ Invitations grant access to a GitHub account. Seats limit how many admitted
4
+ accounts can be present at the same time. An invitation does not reserve a seat.
5
+
6
+ ## Configure the operator credential
7
+
8
+ Set `BLIP_BOOP_ADMIN_TOKEN` to a random secret of at least 32 characters in the
9
+ relay environment and your operator terminal. Use a different value from the
10
+ webhook secret. Terminal participants never receive this credential.
11
+
12
+ For example, generate a value locally and copy it into your private environment
13
+ configuration, not into the repository:
14
+
15
+ ```sh
16
+ python3 -c 'import secrets; print(secrets.token_hex(32))'
17
+ ```
18
+
19
+ The relay refuses to start without an administrator credential. Configuration:
20
+
21
+ | Variable | Default | Purpose |
22
+ | --- | --- | --- |
23
+ | `BLIP_BOOP_ADMIN_TOKEN` | Required | Authenticates operator commands |
24
+ | `BLIP_BOOP_MAX_USERS` | `50` | Maximum simultaneous GitHub accounts |
25
+ | `BLIP_BOOP_MAX_TERMINALS` | `1` | Maximum terminal leases per account |
26
+
27
+ Changing these limits or credentials requires restarting the relay. Run one
28
+ relay process: admission and presence leases are protected by an in-process
29
+ lock, not coordinated across multiple service instances.
30
+
31
+ ## Create an invitation
32
+
33
+ From the project directory, load your private operator environment and select
34
+ the relay you administer:
35
+
36
+ ```sh
37
+ source .env
38
+ export BLIP_BOOP_SERVER=http://127.0.0.1:8766
39
+ python3 blip_boop.py admin invite create --days 7
40
+ ```
41
+
42
+ Use your HTTPS service URL instead for Render. Once the package is installed,
43
+ replace `python3 blip_boop.py` with `blip-boop`. Alternatively, specify the address
44
+ before the administration action:
45
+
46
+ ```sh
47
+ blip-boop admin --server https://YOUR-RELAY invite create --days 7
48
+ ```
49
+
50
+ The JSON output includes an invitation `id`, a secret `code`, and its expiry.
51
+ Send the code privately to one person. The default lifetime is seven days; the
52
+ maximum is 90 days. Codes are displayed only on creation and cannot be retrieved
53
+ from the server later. Only their hashes are stored.
54
+
55
+ During `blip-boop login`, an unregistered person authorizes GitHub, then enters
56
+ the invitation at a hidden terminal prompt. The invitation is consumed only
57
+ when both admission and session creation succeed. Expired, revoked, or consumed
58
+ codes cannot admit another account. Admitted members can sign in again without
59
+ a fresh invitation; a spare code supplied by an existing member is not consumed.
60
+
61
+ ## Manage invitations and members
62
+
63
+ ```sh
64
+ blip-boop admin invites
65
+ blip-boop admin invite revoke INVITATION_ID
66
+ blip-boop admin users
67
+ blip-boop admin revoke NUMERIC_GITHUB_USER_ID
68
+ blip-boop admin restore NUMERIC_GITHUB_USER_ID
69
+ blip-boop admin status
70
+ blip-boop admin close
71
+ blip-boop admin open
72
+ ```
73
+
74
+ `invites` lists metadata, not secret codes. Revoke an unused invitation by its
75
+ public ID. To remove a member who has already joined, revoke the account using
76
+ the numeric GitHub ID shown by `users`. Revocation removes live presence, deletes
77
+ sessions, and blocks new sign-ins, including attempts with another invitation.
78
+ Restoring access does not restore old session tokens: the member must sign in
79
+ again. Ordinary member tokens cannot call administration endpoints.
80
+
81
+ `close` pauses new registrations without consuming attempted invitation codes.
82
+ Existing admitted members can still sign in and join. `open` resumes admission
83
+ with valid invitations. Both settings survive a server restart.
84
+
85
+ `status` reports admitted accounts, connected accounts, connected terminal leases,
86
+ and configured limits. It does not expose these counts to participants and does
87
+ not measure hosting charges or enforce a global billing cap.
88
+
89
+ ## How seats work
90
+
91
+ - The 50-account default applies to accounts present together, not all invited
92
+ members. Each account has one terminal, one pixel, and one seat.
93
+ - Admission is checked atomically before registering a terminal lease. Simultaneous
94
+ arrivals cannot exceed the configured account or terminal limit.
95
+ - Already connected accounts can renew their leases while the space is full.
96
+ A new account sees `space full`; a second terminal sees `terminal limit`.
97
+ - The client retries after 30 seconds without asking the person to authenticate
98
+ or redeem another code. There is no reservation or guaranteed queue order.
99
+ - Quitting sends a best-effort leave request. A stale terminal lease expires
100
+ after 45 seconds and is cleaned up on the next relay request. Closing the
101
+ terminal releases its account's seat; after an abrupt exit, wait for expiry
102
+ before opening another terminal.
103
+ - A terminal permits only one active long-poll at a time. The HTTP server also
104
+ bounds request threads to the configured terminal capacity plus 16 extra
105
+ requests, rejecting excess connections rather than growing without a bound.
106
+
107
+ These controls bound admitted presence and waiting requests. They do not replace
108
+ network-level abuse controls, request-rate limiting, or Render billing controls.
109
+
110
+ ## Upgrade from the open prototype
111
+
112
+ The existing SQLite database is extended in place. Colors, pixel identifiers,
113
+ sessions, and webhook deduplication data are preserved. Existing prototype
114
+ accounts are **not automatically admitted**: their sessions cannot bypass the
115
+ invitation check.
116
+
117
+ 1. Configure the new administrator token and restart the server.
118
+ 2. Create an invitation for yourself using an operator command.
119
+ 3. Run `blip-boop login --server URL`, authorize GitHub and redeem that invitation.
120
+ 4. Reopen your terminal, then invite other testers.
121
+
122
+ Invitations, consumed-code records, access revocations, and registration state
123
+ survive restarts. Presence and live connection claims do not. Avoid rolling back
124
+ to the old server code: it has no beta admission checks.
@@ -0,0 +1,28 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [0.1.0] - 2026-11-17
11
+
12
+ ### Added
13
+
14
+ - A terminal space with colored participant pixels and white contribution particles.
15
+ - GitHub App device sign-in and shared signals for pushes, issues, pull requests,
16
+ and reviews.
17
+ - Single-use beta invitations, access administration, and admission limits of
18
+ 50 simultaneous accounts and one terminal per account.
19
+ - Persistent colors, relay sessions, invitation records, and webhook deduplication.
20
+ - An MIT license and release packaging for the initial 0.1.0 distribution.
21
+
22
+ ### Changed
23
+
24
+ - Use the hosted Render relay by default during sign-in.
25
+ - Send compact contribution and idle messages instead of repeating participant lists.
26
+
27
+ [Unreleased]: https://github.com/loreleimoutiez/blip-boop/compare/v0.1.0...HEAD
28
+ [0.1.0]: https://github.com/loreleimoutiez/blip-boop/releases/tag/v0.1.0
@@ -0,0 +1,94 @@
1
+ # First Render deployment
2
+
3
+ This is a deployment configuration for a small test group. It does not turn the
4
+ current relay into a production-ready public service. The request limiting,
5
+ abuse controls and load testing described in RELEASE.md remain necessary
6
+ before broad public access.
7
+
8
+ ## Cost controls
9
+
10
+ `render.yaml` requests exactly one small paid Python web service and a 1 GB
11
+ persistent disk in Frankfurt. It does not configure autoscaling, a separate
12
+ database service, a paid workspace upgrade, or automatic deploys on commits.
13
+
14
+ Render documents a spending limit for **build pipeline minutes**, not a global
15
+ cap on all service charges. Outbound bandwidth overages can still be billed.
16
+ Fixed compute and disk sizes are not a guarantee of a fixed total bill.
17
+
18
+ Before creating the service:
19
+
20
+ 1. Review the current service and disk prices displayed by Render.
21
+ 2. Use a Hobby workspace unless you specifically need a paid workspace plan.
22
+ 3. In **Workspace Settings → Build Pipeline → Set spend limit**, set additional
23
+ pipeline spending to zero if offered by the dashboard. Verify the value
24
+ before confirming; it controls builds, not runtime or bandwidth charges.
25
+ 4. Leave autoscaling and preview environments disabled and review usage in Billing.
26
+
27
+ If an absolute global spending ceiling is required, resolve that requirement
28
+ with the hosting provider before adding paid resources. Do not treat this
29
+ Blueprint as enforcing that ceiling.
30
+
31
+ References: [Render billing FAQ](https://render.com/docs/faq),
32
+ [build pipeline spending limits](https://render.com/docs/build-pipeline).
33
+
34
+ ## Prepare the repository
35
+
36
+ Put the project in a GitHub repository that Render can read. The repository can
37
+ be private. Include `render.yaml`, the Python modules, `pyproject.toml`, and the
38
+ documentation. Local credentials, databases and tunnel binaries are excluded by
39
+ the project's `.gitignore`; review staged files before publishing.
40
+
41
+ The configuration file contains no credentials. Fill in environment variables
42
+ in Render, using the values from your local `.env`:
43
+
44
+ | Variable | Value |
45
+ | --- | --- |
46
+ | `BLIP_BOOP_CLIENT_ID` | The GitHub App Client ID, not its numeric App ID |
47
+ | `BLIP_BOOP_APP_SLUG` | The app's URL slug, currently `blip-boop-echo` |
48
+ | `BLIP_BOOP_WEBHOOK_SECRET` | The same secret entered in GitHub's webhook settings |
49
+ | `BLIP_BOOP_ADMIN_TOKEN` | A separate random secret of at least 32 characters |
50
+
51
+ The Blueprint explicitly sets `BLIP_BOOP_MAX_USERS=50` and
52
+ `BLIP_BOOP_MAX_TERMINALS=1`. [Beta administration](ADMINISTRATION.md) describes
53
+ how to create your own invitation and operate the beta.
54
+
55
+ The downloaded GitHub App private key is not used by the current device-login
56
+ and webhook implementation. Do not upload it to the repository or service.
57
+
58
+ ## Create and verify the service
59
+
60
+ 1. Create a Render account and connect the GitHub repository.
61
+ 2. Select **New → Blueprint**, choose the repository, and review `render.yaml`.
62
+ 3. Enter the four credentials/configuration values. Review the requested paid service,
63
+ disk, workspace, and total estimate before confirming resource creation.
64
+ 4. Once deployed, visit `https://YOUR-SERVICE.onrender.com/health`. The response
65
+ should be `{"ok": true}`.
66
+ 5. In the GitHub App settings, replace the temporary webhook URL with
67
+ `https://YOUR-SERVICE.onrender.com/webhooks/github`. Keep webhook delivery
68
+ active and SSL verification enabled, and verify the four event subscriptions.
69
+ 6. Set the same administrator token in your operator terminal, create an invitation
70
+ for yourself, then sign in against the new relay. The first login prompts for
71
+ the code. See [Beta administration](ADMINISTRATION.md).
72
+
73
+ ```sh
74
+ blip-boop login --server https://YOUR-SERVICE.onrender.com
75
+ blip-boop
76
+ ```
77
+
78
+ The first deployment uses a new database. Sessions from the local relay do not
79
+ transfer; sign in again. Keep future deploys to one instance because presence
80
+ and transient signals are in memory.
81
+
82
+ Check GitHub's webhook deliveries for a successful response. With the terminal
83
+ connected, create an issue or push to a selected repository and verify a particle
84
+ appears. Repeat with a second account. Deployment and restart interrupt live
85
+ connections temporarily; clients should reconnect automatically.
86
+
87
+ The local tunnel is no longer needed once GitHub and both clients are using the
88
+ new relay. Do not stop it while clients or webhooks still depend on it.
89
+
90
+ ## After the small-group test
91
+
92
+ Add the permanent relay URL as the client default, complete the release checks,
93
+ and only then publish the package. See RELEASE.md. Future users should need only
94
+ `pipx install blip-boop`, `blip-boop login`, and `blip-boop`.
@@ -0,0 +1,215 @@
1
+ # Development and self-hosting
2
+
3
+ Technical setup for developers and relay operators. For the project overview,
4
+ see [README.md](README.md).
5
+
6
+ Colored pixels sit quietly at the bottom of the screen. When someone contributes,
7
+ a small white particle rises, drifts, and fades away. No scores, leaderboards,
8
+ or public usernames — just a shared sense that someone else is making something.
9
+
10
+ This development version includes an invite-only terminal client and a
11
+ single-process relay. See [Beta administration](ADMINISTRATION.md) for the
12
+ operator credential, single-use codes, connection limits, and upgrade steps.
13
+ It uses a dedicated GitHub App and signed webhooks instead of the delayed public
14
+ activity feed. You must configure the app and run the relay before signing in.
15
+ The hosted beta address is documented in README.md; the setup below is for
16
+ development and self-hosting.
17
+
18
+ For a first hosted test, see [the Render deployment guide](DEPLOYMENT.md).
19
+ The supplied `render.yaml` defines one paid service and a persistent disk;
20
+ it does not enforce a global spending cap.
21
+
22
+ ## Install
23
+
24
+ Requirements: Linux or macOS, Python 3.10+, and a terminal with Unicode and
25
+ 24-bit ANSI color support. GitHub CLI is no longer required.
26
+
27
+ From this directory, with [pipx](https://pipx.pypa.io) installed:
28
+
29
+ ```sh
30
+ pipx install .
31
+ ```
32
+
33
+ For an existing installation, update with `pipx install --force .`.
34
+ For development, use `pipx install --editable .` instead. The package has not
35
+ been published on PyPI.
36
+
37
+ Alternatively:
38
+
39
+ ```sh
40
+ python3 -m venv .venv
41
+ .venv/bin/python -m pip install .
42
+ source .venv/bin/activate
43
+ ```
44
+
45
+ You can also use `python3 blip_boop.py` instead of `blip-boop` in the commands below.
46
+
47
+ ## Set up the GitHub App
48
+
49
+ 1. Register a GitHub App in your GitHub developer settings. Choose a name and
50
+ homepage URL, and enable **Device flow** for terminal sign-in. This flow does
51
+ not use an OAuth callback URL, a client secret, or an app private key.
52
+ 2. Enable webhooks. Use `https://YOUR-RELAY/webhooks/github` as the webhook URL
53
+ and choose a long random webhook secret. The URL must be reachable by GitHub.
54
+ 3. Grant read-only repository permissions for **Contents**, **Issues**, and
55
+ **Pull requests**. Metadata access is included by GitHub.
56
+ 4. Subscribe to **Push**, **Issues**, **Pull request**, and **Pull request review**
57
+ events. The app also receives authorization revocation events automatically.
58
+ 5. Copy the app's **Client ID** (not the numeric App ID), URL slug, and webhook
59
+ secret into a local `.env` file using `.env.example` as a template. Set a
60
+ separate random `BLIP_BOOP_ADMIN_TOKEN` of at least 32 characters too.
61
+ 6. Install the app on the repositories you want to contribute from. For other
62
+ people to use it, allow installation on other accounts when registering it.
63
+
64
+ GitHub integration needs the Client ID, app slug and webhook secret. Beta
65
+ administration additionally requires the separate administrator token. GitHub
66
+ handles which selected repositories deliver events; an organization may need to approve
67
+ installation. Signing in alone does not enable activity from every repository.
68
+
69
+ References: [GitHub App device authorization](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app),
70
+ [webhooks with GitHub Apps](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps).
71
+
72
+ ## Start the relay
73
+
74
+ From the directory containing your `.env`:
75
+
76
+ ```sh
77
+ source .env
78
+ blip-boop serve --data-dir .relay-data
79
+ ```
80
+
81
+ The relay listens on `http://127.0.0.1:8765`. For local GitHub testing, forward
82
+ an HTTPS development tunnel to that port and set the GitHub App webhook URL to
83
+ `https://YOUR-TUNNEL/webhooks/github`.
84
+
85
+ For remote clients, expose the same relay through an HTTPS reverse proxy. HTTP
86
+ is accepted by the client only for localhost. Use the final URL directly, without
87
+ redirects; the client does not forward credentials through redirects. The relay's
88
+ `/health` endpoint reports whether it is running.
89
+
90
+ `--host` and `--port` change the bind address and port. `BLIP_BOOP_CLIENT_ID`,
91
+ `BLIP_BOOP_APP_SLUG`, `BLIP_BOOP_WEBHOOK_SECRET`, and `BLIP_BOOP_ADMIN_TOKEN`
92
+ must be set in the server's environment. Terminal clients do not need those
93
+ variables or the webhook secret.
94
+
95
+ This is a development server, not a production hosting setup. It uses one process,
96
+ SQLite, and in-memory presence. Public deployment still needs request limiting,
97
+ network-level abuse controls, HTTPS termination, and hosting configuration.
98
+ Account and terminal admission limits and bounded request threads are implemented;
99
+ per-client request-rate limiting and load testing remain to be completed.
100
+ Multiple workers cannot share the current in-memory event relay.
101
+
102
+ ## Sign in and run
103
+
104
+ Create a single-use invitation with your operator credential first; see
105
+ [Beta administration](ADMINISTRATION.md). Existing prototype accounts must
106
+ redeem an invitation once after upgrading.
107
+
108
+ In another terminal:
109
+
110
+ ```sh
111
+ blip-boop login --server http://127.0.0.1:8765
112
+ blip-boop
113
+ ```
114
+
115
+ For another computer, use your relay's HTTPS URL in `login --server URL`.
116
+ The URL is saved with the session; ordinary launches do not need it again.
117
+ `BLIP_BOOP_SERVER` can also select a server. Switching servers requires signing in
118
+ again; credentials are never silently sent to a different relay.
119
+
120
+ The login command opens GitHub in your browser and displays a device code.
121
+ After authorization, it opens the app installation page so you can select
122
+ repositories. Authorizing an app and installing it on repositories are separate
123
+ steps; both are needed for contributions to appear.
124
+
125
+ ```sh
126
+ blip-boop status
127
+ blip-boop --help
128
+ blip-boop --version
129
+ ```
130
+
131
+ `status` checks your saved session against the relay without adding a pixel.
132
+ Application terminal text, source code, and documentation are in English.
133
+
134
+ ## The shared scene
135
+
136
+ Each connected person has one colored pixel. There are no simulated users or
137
+ manual particle triggers. Each account can connect one terminal at a time. A small dot identifies your own pixel only on your screen.
138
+
139
+ A particle is emitted for each supported webhook:
140
+
141
+ | Activity | Trigger |
142
+ | --- | --- |
143
+ | Push | One particle per push, excluding branch/tag deletion |
144
+ | Pull request | Opened |
145
+ | Issue | Opened |
146
+ | Review | Submitted |
147
+
148
+ Events are attributed to the GitHub sender. A push represents the person who
149
+ pushed, not necessarily the authors of all included commits. Bot events are
150
+ ignored. Events from connected people are broadcast to everyone in this relay;
151
+ there are no private rooms yet. Only install it on repositories whose activity
152
+ timing you want to share, including private repositories if you select them.
153
+
154
+ Particles match the users' small square shape, start white, and fade over
155
+ 18–26 seconds. There are no scores, activity histories, or catch-up animations
156
+ when you first join. GitHub delivery can still be delayed: this is responsive
157
+ webhook delivery, not a hard real-time guarantee. Local, unpushed commits are
158
+ not tracked.
159
+
160
+ The client uses an authenticated long-poll connection: the relay answers as soon
161
+ as presence or a contribution changes, otherwise after about 20 seconds. This
162
+ is not periodic polling of GitHub's public activity feed. The participant list
163
+ is sent on initial connection and when membership or colors change. Contributions
164
+ carry only pixel identifiers; idle responses contain only an event cursor.
165
+ Older clients can still request full snapshots. After reconnecting, the presence
166
+ cursor refreshes the list when needed, including after a server restart.
167
+ Color changes reach
168
+ the server on the next request. Network failures show `offline` and reconnect
169
+ automatically. Abruptly closed terminals disappear within about a minute.
170
+
171
+ ## Controls and storage
172
+
173
+ - `c`: change your color and save it for future sessions.
174
+ - `q`, `Esc`, or `Ctrl+C`: quit and restore the terminal.
175
+
176
+ Settings live outside the installation directory:
177
+
178
+ | Platform | Configuration directory |
179
+ | --- | --- |
180
+ | Linux | `~/.config/blip-boop/` |
181
+ | macOS | `~/Library/Application Support/blip-boop/` |
182
+ | Absolute `XDG_CONFIG_HOME` set | `$XDG_CONFIG_HOME/blip-boop/` |
183
+
184
+ `settings.json` stores your color. `session.json` holds the relay URL and a
185
+ blip-boop session token with owner-only file permissions. It does not store your
186
+ GitHub access token. When running from the original source directory, an old
187
+ `.local/settings.json` color is imported if no user settings exist yet.
188
+
189
+ The GitHub access token is used transiently during sign-in: the client sends it
190
+ to the chosen relay, which verifies your identity with GitHub, then discards it.
191
+ Use a relay you trust. Relay sessions expire after 30 days; GitHub App revocation
192
+ invalidates them when its webhook is delivered.
193
+
194
+ The relay stores GitHub numeric user IDs, random pixel identifiers, colors,
195
+ hashed session tokens, and delivery IDs in SQLite. Peers receive only pixel IDs,
196
+ colors, and contribution signals, not GitHub IDs, usernames, repository names,
197
+ commit messages, or raw webhook payloads. This hides usernames in the interface;
198
+ it does not guarantee anonymity from activity timing or repeated colors.
199
+
200
+ Webhook signatures are validated before processing. Redeliveries are deduplicated
201
+ for seven days. Sessions and deduplication survive a server restart; live presence
202
+ and recent signals do not. The transient buffer holds up to 1,000 signals and
203
+ only replays signals from the last 45 seconds during a brief reconnection.
204
+
205
+ ## Tests
206
+
207
+ ```sh
208
+ python3 -m unittest discover -s tests
209
+ ```
210
+
211
+ Tests cover two participants receiving a signed contribution, filtering and
212
+ deduplication, invalid signatures, session revocation, presence expiry, HTTP
213
+ routes, device login, and persistent sessions. GitHub is replaced by a test
214
+ identity provider; real GitHub authorization and delivery still need to be
215
+ verified after registering the app and exposing the webhook URL.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Loreleï
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,20 @@
1
+ include README.md
2
+ include PYPI_README.md
3
+ include LICENSE
4
+ include CHANGELOG.md
5
+ include DEVELOPMENT.md
6
+ include RELEASE.md
7
+ include DEPLOYMENT.md
8
+ include ADMINISTRATION.md
9
+ include render.yaml
10
+ include .env.example
11
+ recursive-include tests *.py
12
+ exclude .env
13
+ global-exclude *.pem *.key *.sqlite3 *.sqlite3-* *.pyc
14
+ prune .local
15
+ prune .relay-data
16
+ prune .venv
17
+ prune .venv-release
18
+ prune build
19
+ prune dist
20
+ prune __pycache__
@@ -0,0 +1,94 @@
1
+ Metadata-Version: 2.4
2
+ Name: blip-boop
3
+ Version: 0.1.0
4
+ Summary: Colored presences and floating particles in your terminal.
5
+ Author: Loreleï
6
+ License-Expression: MIT
7
+ Keywords: terminal,github,ambient,collaboration,pixels
8
+ Classifier: Development Status :: 3 - Alpha
9
+ Classifier: Environment :: Console
10
+ Classifier: Operating System :: POSIX
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: >=3.10
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Dynamic: license-file
16
+
17
+ # blip-boop
18
+
19
+ **A little company in your terminal.**
20
+
21
+ Leave it open beside your code. You are a small colored pixel at the bottom of
22
+ an otherwise quiet screen. When you contribute on GitHub, a white particle rises,
23
+ drifts, and fades away. Other connected people share the space as colors.
24
+
25
+ No scores, leaderboards, or public usernames. Just a quiet sign that someone
26
+ else is making something.
27
+
28
+ ## Install and join
29
+
30
+ Requires Linux or macOS, Python 3.10+, and a terminal with Unicode and 24-bit
31
+ color support. Install with [pipx](https://pipx.pypa.io):
32
+
33
+ ```sh
34
+ pipx install blip-boop
35
+ blip-boop login
36
+ blip-boop
37
+ ```
38
+
39
+ The hosted beta is **invite-only**. Get a one-time invitation from the operator
40
+ before your first login. Login opens GitHub in your browser and displays a device
41
+ code, then asks for the invitation in a hidden terminal prompt. The invitation
42
+ is linked to your GitHub account; later logins do not need another code.
43
+
44
+ Authorize the GitHub App, then install it on the repositories you want to
45
+ connect. No server setup or GitHub CLI installation is needed to participate.
46
+ The client uses `https://blip-boop-relay.onrender.com` by default.
47
+
48
+ The beta supports 50 simultaneous accounts and one terminal per account.
49
+ If the space is full, the client retries periodically without consuming another
50
+ invitation. Windows is not currently supported.
51
+
52
+ ## What makes a particle?
53
+
54
+ - A push, excluding branch or tag deletion: one particle per push.
55
+ - A pull request opened.
56
+ - An issue opened.
57
+ - A review submitted.
58
+
59
+ Only supported GitHub events from connected participants produce particles.
60
+ Local commits that have not been pushed and bot events are not tracked. GitHub
61
+ webhook delivery may be delayed. Particles fade over 18–26 seconds.
62
+
63
+ ## Controls
64
+
65
+ - `c`: change your color and save it for next time.
66
+ - `q`, `Esc`, or `Ctrl+C`: quit.
67
+ - A small dot marks your own pixel.
68
+
69
+ ```sh
70
+ blip-boop status
71
+ blip-boop --help
72
+ blip-boop --version
73
+ pipx upgrade blip-boop
74
+ ```
75
+
76
+ For another relay, run `blip-boop login --server https://YOUR-RELAY`.
77
+ Settings and your relay session are saved in your user configuration directory.
78
+
79
+ ## Privacy
80
+
81
+ Peers receive pixel identifiers, colors, and contribution signals, not GitHub
82
+ usernames, repository names, code, or commit messages. The relay uses your
83
+ GitHub numeric user ID to match events to your pixel. It verifies a GitHub access
84
+ token transiently at sign-in; the token is not saved by blip-boop.
85
+
86
+ Connecting a private repository shares the timing of its supported activity.
87
+ Colors and timing can identify someone, so hidden usernames do not guarantee
88
+ anonymity. All participants on the hosted relay share the same space.
89
+
90
+ ## License
91
+
92
+ MIT. The package includes client, relay, and operator command code. Hosted relay
93
+ administration requires a separate secret credential; installing the package
94
+ does not grant administrator access.