kuzysignal 0.0.1__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.
Files changed (66) hide show
  1. kuzysignal-0.0.1/DESIGN.md +242 -0
  2. kuzysignal-0.0.1/LICENSE +661 -0
  3. kuzysignal-0.0.1/MANIFEST.in +13 -0
  4. kuzysignal-0.0.1/PKG-INFO +245 -0
  5. kuzysignal-0.0.1/README.md +216 -0
  6. kuzysignal-0.0.1/debian/changelog +6 -0
  7. kuzysignal-0.0.1/debian/control +35 -0
  8. kuzysignal-0.0.1/debian/copyright +20 -0
  9. kuzysignal-0.0.1/debian/kuzysignal.dirs +1 -0
  10. kuzysignal-0.0.1/debian/kuzysignal.install +7 -0
  11. kuzysignal-0.0.1/debian/kuzysignal.postinst +18 -0
  12. kuzysignal-0.0.1/debian/not-installed +5 -0
  13. kuzysignal-0.0.1/debian/rules +24 -0
  14. kuzysignal-0.0.1/debian/source/format +1 -0
  15. kuzysignal-0.0.1/docs/DISTRIBUTION_PACKAGING.md +52 -0
  16. kuzysignal-0.0.1/packaging/build-kuzy-signal-cli.sh +149 -0
  17. kuzysignal-0.0.1/packaging/rpm/20-signal-cli-copr.conf +3 -0
  18. kuzysignal-0.0.1/packaging/rpm/kuzysignal.spec +63 -0
  19. kuzysignal-0.0.1/packaging/systemd/kuzysignald.service +19 -0
  20. kuzysignal-0.0.1/packaging/systemd/kuzysignald@.service +29 -0
  21. kuzysignal-0.0.1/pyproject.toml +87 -0
  22. kuzysignal-0.0.1/setup.cfg +4 -0
  23. kuzysignal-0.0.1/src/kuzysignal/__init__.py +16 -0
  24. kuzysignal-0.0.1/src/kuzysignal/__main__.py +10 -0
  25. kuzysignal-0.0.1/src/kuzysignal/adapters.py +467 -0
  26. kuzysignal-0.0.1/src/kuzysignal/backend/__init__.py +14 -0
  27. kuzysignal-0.0.1/src/kuzysignal/backend/jsonrpc.py +145 -0
  28. kuzysignal-0.0.1/src/kuzysignal/backend/signal_cli.py +760 -0
  29. kuzysignal-0.0.1/src/kuzysignal/cli.py +1251 -0
  30. kuzysignal-0.0.1/src/kuzysignal/config.py +129 -0
  31. kuzysignal-0.0.1/src/kuzysignal/daemon.py +242 -0
  32. kuzysignal-0.0.1/src/kuzysignal/data/inject-adapters/default.json +81 -0
  33. kuzysignal-0.0.1/src/kuzysignal/dispatch.py +174 -0
  34. kuzysignal-0.0.1/src/kuzysignal/errors.py +51 -0
  35. kuzysignal-0.0.1/src/kuzysignal/jsonio.py +40 -0
  36. kuzysignal-0.0.1/src/kuzysignal/messages.py +297 -0
  37. kuzysignal-0.0.1/src/kuzysignal/prompts.py +75 -0
  38. kuzysignal-0.0.1/src/kuzysignal/py.typed +0 -0
  39. kuzysignal-0.0.1/src/kuzysignal/service.py +336 -0
  40. kuzysignal-0.0.1/src/kuzysignal/store.py +97 -0
  41. kuzysignal-0.0.1/src/kuzysignal/version.py +7 -0
  42. kuzysignal-0.0.1/src/kuzysignal.egg-info/PKG-INFO +245 -0
  43. kuzysignal-0.0.1/src/kuzysignal.egg-info/SOURCES.txt +64 -0
  44. kuzysignal-0.0.1/src/kuzysignal.egg-info/dependency_links.txt +1 -0
  45. kuzysignal-0.0.1/src/kuzysignal.egg-info/entry_points.txt +3 -0
  46. kuzysignal-0.0.1/src/kuzysignal.egg-info/requires.txt +5 -0
  47. kuzysignal-0.0.1/src/kuzysignal.egg-info/top_level.txt +1 -0
  48. kuzysignal-0.0.1/tests/__init__.py +0 -0
  49. kuzysignal-0.0.1/tests/conftest.py +13 -0
  50. kuzysignal-0.0.1/tests/test_adapter_dispatch.py +86 -0
  51. kuzysignal-0.0.1/tests/test_adapters.py +188 -0
  52. kuzysignal-0.0.1/tests/test_calls.py +90 -0
  53. kuzysignal-0.0.1/tests/test_daemon_supervise.py +96 -0
  54. kuzysignal-0.0.1/tests/test_dispatch.py +138 -0
  55. kuzysignal-0.0.1/tests/test_edit_delete_contacts_profile.py +379 -0
  56. kuzysignal-0.0.1/tests/test_group_join.py +23 -0
  57. kuzysignal-0.0.1/tests/test_groups_identities.py +325 -0
  58. kuzysignal-0.0.1/tests/test_messages.py +118 -0
  59. kuzysignal-0.0.1/tests/test_prompts.py +73 -0
  60. kuzysignal-0.0.1/tests/test_reactions.py +117 -0
  61. kuzysignal-0.0.1/tests/test_receipts_typing_devices_stickers.py +278 -0
  62. kuzysignal-0.0.1/tests/test_registration.py +183 -0
  63. kuzysignal-0.0.1/tests/test_rpm_packaging.py +30 -0
  64. kuzysignal-0.0.1/tests/test_service.py +349 -0
  65. kuzysignal-0.0.1/tests/test_smoke.py +82 -0
  66. kuzysignal-0.0.1/tests/test_ux_gaps.py +245 -0
@@ -0,0 +1,242 @@
1
+ # kuzysignal — design note
2
+
3
+ **Status:** pre-alpha. Structure plus the core operations (send, groups,
4
+ identities/trust, attachment download, registration/linking) are implemented;
5
+ pending live verification against a real Signal account.
6
+
7
+ kuzysignal is the **Signal-protocol sibling of kuzychat**. Same shape — per-user
8
+ daemon, JSON-first CLI, profile/account addressing, send/receive/groups/
9
+ attachments — over Signal instead of XMPP.
10
+
11
+ ## 1. Architecture: A (signal-cli over JSON-RPC)
12
+
13
+ We do **not** reimplement the Signal protocol. kuzysignal drives
14
+ [`signal-cli`](https://github.com/AsamK/signal-cli) (Java, wraps libsignal) in
15
+ **JSON-RPC daemon mode** and maps its methods onto the kuzysignal command
16
+ surface.
17
+
18
+ ```
19
+ kuzysignal (Python) --JSON-RPC over UNIX socket--> signal-cli daemon (Java) ---> Signal servers
20
+ CLI + per-user daemon + event store protocol/crypto/registration/groups/attachments
21
+ ```
22
+
23
+ Rationale (decided with Michele): signal-cli is mature and JSON-first already,
24
+ so it is a clean fit for kuzychat's philosophy and gives us registration,
25
+ linking, sealed-sender, groups and attachments for free. The chosen language is
26
+ **Python** so we reuse kuzychat's architecture and conventions; signal-cli does
27
+ the heavy lifting, so there is no performance argument for Rust/C++ here.
28
+
29
+ ### Backend boundary (door left open for B)
30
+
31
+ `kuzysignal.backend` is a narrow seam. Today the only backend is
32
+ `signal_cli.SignalCliBackend`. A future **B** path (pure-Rust via `presage`, or
33
+ an in-process libsignal binding) could be swapped behind the same surface
34
+ without touching the CLI or daemon layers.
35
+
36
+ ## 2. Runtime requirement: Java 25 (important for packaging)
37
+
38
+ Measured on 2026-06-21 building `signal-cli v0.14.5`:
39
+
40
+ * **Build** requires JDK **25** (`build.gradle.kts`: `sourceCompatibility =
41
+ JavaVersion.VERSION_25`).
42
+ * **Runtime also** requires Java 25 — the jars are class-file version 69
43
+ (Java 25); they do **not** run on Java 21 (`UnsupportedClassVersionError`).
44
+
45
+ Consequences:
46
+
47
+ * openjdk-25 is packaged in Debian 13 (`openjdk-25-jdk-headless`, candidate
48
+ 25.0.3) — so this is available, not exotic.
49
+ * kuzysignal launches signal-cli with an explicit `JAVA_HOME` (default
50
+ `/usr/lib/jvm/java-25-openjdk-amd64`, override `KUZYSIGNAL_JAVA_HOME`) so it
51
+ never depends on the host's default `java` alternative.
52
+ * **Open packaging decision (Michele):** the deploy hosts will need JDK 25 for
53
+ the signal-cli backend. Either (a) standardise on JDK 25 (it's in Debian 13),
54
+ or (b) pin signal-cli to an older Java-21-compatible release (older Signal
55
+ client — riskier since Signal deprecates old clients). Recommendation: (a).
56
+
57
+ > Side effect noted during setup: installing `openjdk-25` flipped the system
58
+ > default `java` (update-alternatives, auto mode) from 21 to 25 on the build
59
+ > host. kuzysignal does not rely on the default (it pins `JAVA_HOME`), but other
60
+ > software might; restoring the default needs `update-alternatives` (outside the
61
+ > current NOPASSWD-apt scope).
62
+
63
+ ## 3. On-disk layout (per profile)
64
+
65
+ ```
66
+ <state_home>/profiles/<profile>/
67
+ config.json # account-name -> {number, ...}
68
+ signal-cli/ # signal-cli --config data dir (holds Signal secrets)
69
+ events.sqlite3 # local normalised event store
70
+ run/kuzysignald.sock # daemon control / signal-cli JSON-RPC socket
71
+ ```
72
+
73
+ Signal secrets live **inside signal-cli's own data dir**; kuzysignal stores only
74
+ the small name->number mapping.
75
+
76
+ ## 4. Command surface (mirrors kuzychat) and JSON-RPC mapping
77
+
78
+ | kuzysignal command | signal-cli JSON-RPC | status |
79
+ |---|---|---|
80
+ | `version` | — | done |
81
+ | `doctor` | (probe binary/JVM) | done |
82
+ | `account add/list` | (local config) | done |
83
+ | `send dm --to --text` | `send {recipient}` | wired |
84
+ | `send group --group --text` | `send {groupId}` | wired |
85
+ | `events [--kind]` | (local store) | done — read path |
86
+ | `daemon listen` | `daemon --socket` + `receive` -> normalised + stored | done |
87
+ | `account register/verify/link` | `register`/`verify`/`link` | done (one-shot) |
88
+ | `group list/create/update/quit/join` | `listGroups`/`updateGroup`(no id = create)/`updateGroup`/`quitGroup`/`joinGroup` | done |
89
+ | `receive` (one-shot) | — | deferred (see note) |
90
+
91
+ > **Read path / one-shot receive.** The per-user daemon is the *sole* consumer
92
+ > of the signal-cli socket: it normalises every `receive` notification into a
93
+ > `kuzysignal.message.v1` event (`messages.py`) and stores it. Consumers read
94
+ > via `events` (filterable by kind). A competing one-shot `receive` would race
95
+ > the daemon for delivery, so it is deliberately not implemented; if needed it
96
+ > will drain from the store rather than open a second socket consumer.
97
+ | `attachment get` | `getAttachment` (base64 over JSON-RPC) | done |
98
+ | `identities list/trust` | `listIdentities`/`trust` | done |
99
+ | `send reaction` | `sendReaction` | done |
100
+ | inbound reaction | `dataMessage.reaction` -> `kind=reaction` | done |
101
+ | `send edit --edit-timestamp` | `send {editTimestamp}` | done |
102
+ | `send delete --target-timestamp` | `remoteDelete` | done |
103
+ | `contacts list` | `listContacts` | done |
104
+ | `contacts update` | `updateContact` | done |
105
+ | `contacts remove [--forget]` | `removeContact` | done |
106
+ | `contacts block/unblock` | `block`/`unblock` | done |
107
+ | `profile set` | `updateProfile` | done |
108
+ | `send receipt --to --target-timestamp [--type]` | `sendReceipt` | done |
109
+ | `send typing --to\|--group [--stop]` | `sendTyping` | done |
110
+ | `devices list` | `listDevices` | done |
111
+ | `devices add --uri` | `addDevice` | done |
112
+ | `devices remove --device-id` | `removeDevice` | done |
113
+ | `stickers list` | `listStickerPacks` | done |
114
+ | `stickers add --uri` | `addStickerPack` | done |
115
+ | `stickers upload --path` | `uploadStickerPack` | done |
116
+ | `call start --to` | `startCall` (a "ring"; signaling only) | done |
117
+ | `call accept/hangup/reject --call-id` | `acceptCall`/`hangupCall`/`rejectCall` | done |
118
+ | inbound call | `callMessage` -> `kind=call` (offer/answer/hangup/busy/ice) | done |
119
+
120
+ All commands print exactly one JSON object to stdout (`jsonio.emit`); errors are
121
+ `{"ok": false, "error": {...}}` with a stable exit code.
122
+
123
+ ## 5. Open items / next steps
124
+
125
+ 1. ~~Packaging direction~~ — **decided: standardise on JDK 25** (in Debian 13;
126
+ `JAVA_HOME` pinned by kuzysignal). scirocco default `java` is now 25 (kept).
127
+ 2. ~~Normalise the `receive` envelope + dispatch to the agent runtime~~ —
128
+ **done.** `messages.py` normalises; `adapters.py` is a decoupled re-impl of
129
+ kuzychat's inject-adapter contract (schema `kuzysignal-inject-adapters-v1`,
130
+ same `kuzywrap-*` argv/placeholders/stdin=prompt/output=json); `prompts.py`
131
+ builds the inbound prompt; `dispatch.py` invokes the adapter with a
132
+ skip-if-in-progress guard (in-process flag + PID lock file with stale-lock
133
+ recovery). Daemon dispatches inbound messages; failures never kill the loop,
134
+ and a non-ok dispatch result is **logged** (not silently dropped — found live
135
+ by Livia: a Claude adapter on a Codex target failed `ok=false` and the
136
+ message vanished). The inject **adapter must match the agent's runtime**
137
+ (`kuzywrap-claude-local` vs `kuzywrap-codex-local`); `enable-service`/`verify`
138
+ make the adapter explicit and the daemon logs it at startup.
139
+ Common library with kuzychat deferred (decided: option 2).
140
+ 3. ~~Implement registration/linking flow~~ — **done.** The one genuinely
141
+ Signal-specific UX (phone number + captcha/verify, or device-link URI) is
142
+ wired as one-shot commands: `account register/verify/link` run a fresh
143
+ signal-cli process per call (NOT over the daemon, since an account must be set
144
+ up before its daemon runs) via `SignalCliBackend.run_cli`. `register` persists
145
+ the account-name -> number mapping on success; `verify` resolves the number
146
+ from config; `link` runs `link -n <name>`, surfaces the printed
147
+ `sgnl://linkdevice?...` URI under a `link_uri` key, and **blocks** until the
148
+ primary device scans it (or times out). Only **live verification** remains
149
+ (a real Signal number or a device to link) — pending from Michele.
150
+ 4. ~~Debian packaging~~ — **done.** A single `kuzysignal` deb (mirroring
151
+ kuzychat 0.8) `Depends: signal-cli` (virtual). The `signal-cli` provider is
152
+ the `kuzy-signal-cli` deb, which bundles the built signal-cli + a JDK-25
153
+ wrapper and `Provides: signal-cli`. apt resolution verified by simulate.
154
+ See [§6 Packaging](#6-packaging).
155
+ 5. ~~Implement groups / identities / attachment download~~ — **done.** Group
156
+ management (`group list/create/update/quit`), identities (`identities
157
+ list/trust`) and attachment download (`attachment get`) are wired over the
158
+ JSON-RPC daemon (`SignalCliBackend.create_group/update_group/quit_group/
159
+ list_identities/trust/get_attachment`). There is no `createGroup` method —
160
+ `updateGroup` with no `groupId` creates the group and returns its id;
161
+ `getAttachment` returns the file base64-encoded as `{"data": ...}`, which
162
+ `attachment get` decodes to `--out` when given. Pending **live verification**.
163
+ 6. ~~Daemon auto-recovery~~ — **done.** The daemon now *owns* and *supervises*
164
+ the signal-cli process: `Daemon._supervise()` (re)spawns signal-cli wired with
165
+ the notification handler and restarts it with exponential backoff when the
166
+ process dies or the JSON-RPC connection drops (`JsonRpcClient.is_closed` /
167
+ `SignalCliBackend.is_healthy`), surviving SIGINT/SIGTERM for a clean stop.
168
+ This also fixed a latent scaffold bug where `run()` did start→close→attach,
169
+ killing the just-spawned signal-cli and attaching to a dead socket.
170
+ 7. Reuse vs fork: evaluate lifting kuzychat's event store / dispatch / kuzywrap
171
+ adapter code rather than reimplementing.
172
+ 8. ~~systemd instance/reconciler model~~ — **done.** The package ships an
173
+ enabled oneshot reconciler (`kuzysignald.service` → `kuzysignal service
174
+ reconcile`) plus a per-instance template (`kuzysignald@.service`), driven by
175
+ an `/etc/kuzysignal/instances.d/<id>.conf` EnvironmentFile registry
176
+ (`src/kuzysignal/service.py`: pure `reconcile_plan`, `read_instances`, and a
177
+ `systemctl`-driving `reconcile` executor with an injectable runner). Only
178
+ **live verification** on a real systemd host remains, alongside the pending
179
+ live Signal number/device verification.
180
+
181
+ ## 6. Packaging
182
+
183
+ Single binary `kuzysignal` deb, built with the same debhelper + pybuild
184
+ toolchain as kuzychat 0.8 (`debian/control`, `debian/rules`, `debian/copyright`,
185
+ `debian/kuzysignal.install`). It ships the `kuzysignal` and `kuzysignald`
186
+ entry points, the Python package (including the `data/inject-adapters` JSON,
187
+ carried as package-data so it lands inside the package dir), and `README.md` /
188
+ `DESIGN.md` under `usr/share/doc/kuzysignal/`.
189
+
190
+ Runtime dep: `signal-cli` (virtual). kuzysignal does not name a concrete
191
+ signal-cli package — it depends on the virtual `signal-cli`.
192
+
193
+ The provider is **`kuzy-signal-cli`** (`packaging/build-kuzy-signal-cli.sh`): a
194
+ vendored bundle of the built signal-cli dist plus a `/usr/bin/signal-cli`
195
+ wrapper that pins `JAVA_HOME` to openjdk-25. It declares `Provides: signal-cli`,
196
+ `Conflicts/Replaces: signal-cli`, and `Depends: openjdk-25-jre-headless` (so the
197
+ JVM comes in transitively — kuzysignal itself does not depend on the JRE). It is
198
+ built from the gradle `installDist` output, not from a source deb, since
199
+ signal-cli's own build needs JDK 25 + network. **When signal-cli lands in
200
+ Debian:** stop building kuzy-signal-cli; the real package satisfies kuzysignal's
201
+ `Depends: signal-cli` with no change. Resolution of `kuzysignal` +
202
+ `kuzy-signal-cli` verified with `apt-get install -s`.
203
+
204
+ **systemd: instance/reconciler model.** Like kuzychat — which ships an enabled
205
+ `kuzychatd.service` reconciler plus a per-user worker template — kuzysignal
206
+ declares which `(profile, account)` daemons should run and reconciles systemd to
207
+ match. The kuzysignal model is per-instance (one daemon per `(profile,
208
+ account)`) and so a little simpler.
209
+
210
+ * **Instance registry.** An operator drops EnvironmentFiles into
211
+ `/etc/kuzysignal/instances.d/<id>.conf` (systemd `KEY=VALUE` format). The
212
+ instance id is the filename stem (`^[A-Za-z0-9_.-]+$`). Recognised keys:
213
+ `KUZYSIGNAL_PROFILE`, `KUZYSIGNAL_ACCOUNT`, `KUZYSIGNAL_USER` (the unix user to
214
+ run the daemon as) are required; `KUZYSIGNAL_STATE_HOME`, `KUZYSIGNAL_ADAPTER`,
215
+ `KUZYSIGNAL_TARGET`, `KUZYSIGNAL_TURN_TIMEOUT` are optional.
216
+
217
+ * **Template unit.** `packaging/systemd/kuzysignald@.service` is installed (but
218
+ never enabled by the package): `EnvironmentFile=-/etc/kuzysignal/instances.d/%i.conf`,
219
+ `ExecStart=/usr/bin/kuzysignald` (bare — `build_parser()` defaults each
220
+ `--profile/--account/--state-home/--adapter/--target/--turn-timeout` from the
221
+ matching `KUZYSIGNAL_*` env var, so the EnvironmentFile drives it),
222
+ `Restart=on-failure`. It deliberately carries no `User=` and no `[Install]`.
223
+
224
+ * **Reconciler.** `packaging/systemd/kuzysignald.service` is an enabled oneshot
225
+ (`Type=oneshot`, `RemainAfterExit=yes`, `WantedBy=multi-user.target`) whose
226
+ `ExecStart=/usr/bin/kuzysignal service reconcile` /
227
+ `ExecStop=… reconcile --stop`. `reconcile` (in `src/kuzysignal/service.py`)
228
+ reads the registry (`read_instances`), discovers which instances it currently
229
+ manages by the presence of its drop-in
230
+ (`/etc/systemd/system/kuzysignald@<id>.service.d/10-kuzysignal.conf`), computes
231
+ the set math (`reconcile_plan`: every desired instance to (re)start, managed −
232
+ desired to stop), then per desired instance writes that drop-in carrying
233
+ `[Service]\nUser=<KUZYSIGNAL_USER>` (the per-instance run-as user the template
234
+ omits) and runs `systemctl daemon-reload` + `enable --now`; per removed
235
+ instance it runs `disable --now` and deletes the drop-in. The module takes an
236
+ injectable runner so the executor is unit-tested against `tmp_path` dirs with a
237
+ fake `systemctl`; `--dry-run` computes and prints the plan but runs nothing.
238
+ `debian/rules`’ `override_dh_installsystemd` enables/starts the reconciler with
239
+ `--restart-after-upgrade` (a restart re-runs reconcile, bouncing every instance
240
+ onto the new binary) and installs the template `--no-enable --no-start`.
241
+ `debian/kuzysignal.postinst` creates `/etc/kuzysignal/instances.d` on
242
+ configure.