terminalchat-cli 0.0.0-stage → 0.1.1

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.
package/src/engine.js ADDED
@@ -0,0 +1,411 @@
1
+ /**
2
+ * src/engine.js — application core (EventEmitter)
3
+ *
4
+ * Owns the data directory, identity, friends, invites, outbox, state, and
5
+ * the Network layer. Exposes a clean method/event surface that the Ink UI
6
+ * (and the integration test) consumes — the UI never touches DHT or storage
7
+ * directly.
8
+ *
9
+ * Methods:
10
+ * start()
11
+ * sendMessage(friendKeyHex, body) → seq
12
+ * createInvite() → string (base58 code)
13
+ * join(code) → { friendKeyHex, name }
14
+ * addFriend(name, keyHex)
15
+ * getHistory(friendKeyHex, n) → Promise<entry[]>
16
+ * whoami() → { name, publicKey: hex }
17
+ * shutdown()
18
+ *
19
+ * Events:
20
+ * 'ready'
21
+ * 'friend-added' (friendKeyHex, name)
22
+ * 'friend-online' (friendKeyHex)
23
+ * 'friend-offline'(friendKeyHex)
24
+ * 'message' (friendKeyHex, entry) — entry has direction:'in'|'out'
25
+ * 'ack' (friendKeyHex, seq) — seq confirmed delivered
26
+ * 'error' (err)
27
+ */
28
+ import { EventEmitter } from 'node:events'
29
+ import { randomBytes } from 'node:crypto'
30
+ import { resolve } from 'node:path'
31
+ import { homedir } from 'node:os'
32
+ import b4a from 'b4a'
33
+ import { Network } from './network.js'
34
+ import { createStore } from './store.js'
35
+ import { loadOrCreate, bufferToHex, hexToBuffer } from './identity.js'
36
+ import { encodeInvite, decodeInvite } from './protocol.js'
37
+ import {
38
+ allocateSeq,
39
+ processAck,
40
+ getOutbox,
41
+ createInboxTracker,
42
+ buildSeenSet,
43
+ isSeen,
44
+ markSeen,
45
+ } from './outbox.js'
46
+
47
+ export class Engine extends EventEmitter {
48
+ /**
49
+ * @param {object} [opts]
50
+ * @param {string} [opts.dataDir] override data directory (default: ~/.terminalchat or TCHAT_DATA_DIR)
51
+ * @param {object} [opts.dhtOptions] extra options for `new DHT(...)` (e.g. { bootstrap })
52
+ * @param {Function} [opts.namePrompt] async () → string; for test use
53
+ */
54
+ constructor (opts = {}) {
55
+ super()
56
+ const baseDir = opts.dataDir
57
+ ?? process.env.TCHAT_DATA_DIR
58
+ ?? resolve(homedir(), '.terminalchat')
59
+
60
+ this._store = createStore(baseDir)
61
+ this._dhtOptions = opts.dhtOptions ?? {}
62
+ this._namePrompt = opts.namePrompt ?? undefined
63
+
64
+ this._identity = null
65
+ this._network = null
66
+
67
+ this._friends = {}
68
+ this._invites = {}
69
+ this._outboxData = {}
70
+ this._seqState = { nextSeq: {}, ackedUpTo: {} }
71
+
72
+ this._inboxTrackers = {} // { [keyHex]: InboxTracker }
73
+ this._seenSets = {} // { [keyHex]: Set<"sender:seq"> }
74
+
75
+ this._started = false
76
+ this._destroyed = false
77
+ }
78
+
79
+ // ---------------------------------------------------------------------------
80
+ // start
81
+ // ---------------------------------------------------------------------------
82
+
83
+ async start () {
84
+ if (this._started) return
85
+ this._store.ensure()
86
+
87
+ this._identity = await loadOrCreate(this._store, this._namePrompt)
88
+
89
+ this._friends = this._store.friends.load() ?? {}
90
+ this._invites = this._store.invites.load() ?? {}
91
+ this._outboxData = this._store.outbox.load() ?? {}
92
+ this._seqState = this._store.state.load() ?? { nextSeq: {}, ackedUpTo: {} }
93
+
94
+ this._pruneInvites()
95
+
96
+ for (const keyHex of Object.keys(this._friends)) {
97
+ await this._loadSeenSet(keyHex)
98
+ }
99
+
100
+ this._network = new Network(
101
+ {
102
+ keyPair: {
103
+ publicKey: this._identity.publicKey,
104
+ secretKey: this._identity.secretKey,
105
+ },
106
+ name: this._identity.name,
107
+ dhtOptions: this._dhtOptions,
108
+ },
109
+ {
110
+ isFriend: (k) => k in this._friends,
111
+ checkInvite: (s) => this._checkInvite(s),
112
+ consumeInvite: (s) => this._consumeInvite(s),
113
+ onHandshake: (k, n) => this._onHandshake(k, n),
114
+ onInviteAccepted: (k, n) => this._onInviteAccepted(k, n),
115
+ onFrame: (k, f) => this._onFrame(k, f),
116
+ onDisconnect: (k) => this._onDisconnect(k),
117
+ getHello: () => ({ type: 'hello', name: this._identity.name }),
118
+ getOutbox: (k) => getOutbox(this._outboxData, k),
119
+ }
120
+ )
121
+
122
+ await this._network.start()
123
+ await this._network.connectAll(Object.keys(this._friends))
124
+
125
+ this._started = true
126
+ this.emit('ready')
127
+ }
128
+
129
+ // ---------------------------------------------------------------------------
130
+ // sendMessage
131
+ // ---------------------------------------------------------------------------
132
+
133
+ sendMessage (friendKeyHex, body) {
134
+ if (!(friendKeyHex in this._friends)) throw new Error('Unknown friend')
135
+ if (typeof body !== 'string' || !body.trim()) throw new Error('Empty message')
136
+
137
+ const ts = Date.now()
138
+ const seq = allocateSeq(this._outboxData, this._seqState, friendKeyHex, ts, body)
139
+
140
+ this._saveOutbox()
141
+ this._saveState()
142
+
143
+ const entry = {
144
+ direction: 'out',
145
+ sender: bufferToHex(this._identity.publicKey),
146
+ seq,
147
+ ts,
148
+ body,
149
+ delivered: false,
150
+ }
151
+ this._store.appendHistory(friendKeyHex, entry)
152
+ this.emit('message', friendKeyHex, entry)
153
+
154
+ this._network.send(friendKeyHex, { type: 'msg', seq, ts, body })
155
+
156
+ return seq
157
+ }
158
+
159
+ // ---------------------------------------------------------------------------
160
+ // createInvite
161
+ // ---------------------------------------------------------------------------
162
+
163
+ createInvite () {
164
+ const secret = randomBytes(16)
165
+ const secretHex = b4a.toString(secret, 'hex')
166
+ this._invites[secretHex] = { createdAt: Date.now() }
167
+ this._store.invites.save(this._invites)
168
+ return encodeInvite(this._identity.publicKey, secret)
169
+ }
170
+
171
+ // ---------------------------------------------------------------------------
172
+ // join (joiner side)
173
+ // ---------------------------------------------------------------------------
174
+
175
+ async join (code) {
176
+ const { publicKey, secret } = decodeInvite(code)
177
+ const inviterKeyHex = bufferToHex(publicKey)
178
+ const secretHex = bufferToHex(secret)
179
+
180
+ return new Promise((resolve, reject) => {
181
+ const wasAlreadyFriend = !!this._friends[inviterKeyHex]
182
+
183
+ // Pre-add the inviter so our _handleHello accepts their responding hello.
184
+ // The name will be overwritten by _onHandshake once we receive their hello.
185
+ if (!wasAlreadyFriend) {
186
+ this._friends[inviterKeyHex] = { name: '…', addedAt: Date.now() }
187
+ }
188
+
189
+ let timer
190
+
191
+ // Once the inviter comes online (network accepted their hello), we're done.
192
+ const onOnline = (keyHex) => {
193
+ if (keyHex !== inviterKeyHex) return
194
+ this.off('friend-online', onOnline)
195
+ if (timer) clearTimeout(timer)
196
+ const name = this._friends[inviterKeyHex]?.name ?? ''
197
+ // Persist the friend now that the join succeeded
198
+ this._store.friends.save(this._friends)
199
+ this.emit('friend-added', inviterKeyHex, name)
200
+ resolve({ friendKeyHex: inviterKeyHex, name })
201
+ }
202
+ this.on('friend-online', onOnline)
203
+
204
+ // Patch getHello to include the invite secret for this one connection
205
+ const origGetHello = this._network._handlers.getHello
206
+ this._network._handlers.getHello = () => ({
207
+ type: 'hello', name: this._identity.name, invite: secretHex,
208
+ })
209
+
210
+ this._network._connectTo(inviterKeyHex)
211
+ .then(() => { this._network._handlers.getHello = origGetHello })
212
+ .catch(err => {
213
+ if (timer) clearTimeout(timer)
214
+ this._network._handlers.getHello = origGetHello
215
+ this.off('friend-online', onOnline)
216
+ if (!wasAlreadyFriend) delete this._friends[inviterKeyHex]
217
+ reject(err)
218
+ })
219
+
220
+ timer = setTimeout(() => {
221
+ this.off('friend-online', onOnline)
222
+ this._network._handlers.getHello = origGetHello
223
+ if (!wasAlreadyFriend) delete this._friends[inviterKeyHex]
224
+ reject(new Error('Join timed out'))
225
+ }, 30_000)
226
+ timer.unref?.()
227
+ })
228
+ }
229
+
230
+ // ---------------------------------------------------------------------------
231
+ // addFriend (manual / both-sides-add path)
232
+ // ---------------------------------------------------------------------------
233
+
234
+ addFriend (name, keyHex) {
235
+ if (this._friends[keyHex]) {
236
+ this._friends[keyHex].name = name
237
+ } else {
238
+ this._friends[keyHex] = { name, addedAt: Date.now() }
239
+ }
240
+ this._store.friends.save(this._friends)
241
+ this.emit('friend-added', keyHex, name)
242
+ }
243
+
244
+ // ---------------------------------------------------------------------------
245
+ // getHistory / whoami
246
+ // ---------------------------------------------------------------------------
247
+
248
+ async getHistory (friendKeyHex, n = 50) {
249
+ return this._store.readHistory(friendKeyHex, n)
250
+ }
251
+
252
+ whoami () {
253
+ return {
254
+ name: this._identity.name,
255
+ publicKey: bufferToHex(this._identity.publicKey),
256
+ }
257
+ }
258
+
259
+ // ---------------------------------------------------------------------------
260
+ // shutdown
261
+ // ---------------------------------------------------------------------------
262
+
263
+ async shutdown () {
264
+ if (this._destroyed) return
265
+ this._destroyed = true
266
+ this._saveOutbox()
267
+ this._saveState()
268
+ if (this._network) await this._network.destroy()
269
+ }
270
+
271
+ // ---------------------------------------------------------------------------
272
+ // Online status helpers (for UI)
273
+ // ---------------------------------------------------------------------------
274
+
275
+ isOnline (friendKeyHex) {
276
+ return this._network?.isOnline(friendKeyHex) ?? false
277
+ }
278
+
279
+ getFriends () {
280
+ return Object.entries(this._friends).map(([keyHex, info]) => ({
281
+ keyHex,
282
+ name: info.name,
283
+ online: this.isOnline(keyHex),
284
+ addedAt: info.addedAt,
285
+ }))
286
+ }
287
+
288
+ // ---------------------------------------------------------------------------
289
+ // Internal: network callbacks
290
+ // ---------------------------------------------------------------------------
291
+
292
+ _onHandshake (keyHex, name) {
293
+ if (this._friends[keyHex] && this._friends[keyHex].name !== name) {
294
+ this._friends[keyHex].name = name
295
+ this._store.friends.save(this._friends)
296
+ }
297
+ this._inboxTrackers[keyHex] = this._trackerFromSeen(keyHex)
298
+ this.emit('friend-online', keyHex)
299
+ }
300
+
301
+ _onInviteAccepted (keyHex, name) {
302
+ this._friends[keyHex] = { name, addedAt: Date.now() }
303
+ this._store.friends.save(this._friends)
304
+ this._inboxTrackers[keyHex] = createInboxTracker()
305
+ this._seenSets[keyHex] = new Set()
306
+ this.emit('friend-added', keyHex, name)
307
+ this.emit('friend-online', keyHex)
308
+ }
309
+
310
+ _trackerFromSeen (senderKeyHex) {
311
+ const tracker = createInboxTracker()
312
+ const seen = [...(this._seenSets[senderKeyHex] ?? [])]
313
+ .filter(id => id.startsWith(`${senderKeyHex}:`))
314
+ .map(id => Number(id.slice(senderKeyHex.length + 1)))
315
+ .filter(Number.isSafeInteger)
316
+ .sort((a, b) => a - b)
317
+ for (const seq of seen) tracker.receive(senderKeyHex, seq)
318
+ return tracker
319
+ }
320
+
321
+ _onDisconnect (keyHex) {
322
+ delete this._inboxTrackers[keyHex]
323
+ this.emit('friend-offline', keyHex)
324
+ }
325
+
326
+ _onFrame (keyHex, frame) {
327
+ switch (frame.type) {
328
+ case 'msg': this._handleMsg(keyHex, frame); break
329
+ case 'ack': this._handleAck(keyHex, frame); break
330
+ }
331
+ }
332
+
333
+ _handleMsg (senderKeyHex, frame) {
334
+ const tracker = this._inboxTrackers[senderKeyHex]
335
+ if (!tracker) return
336
+
337
+ const seenSet = this._seenSets[senderKeyHex] ?? (this._seenSets[senderKeyHex] = new Set())
338
+
339
+ if (isSeen(seenSet, senderKeyHex, frame.seq)) {
340
+ const ackUpTo = tracker.getAck(senderKeyHex)
341
+ this._network.send(senderKeyHex, { type: 'ack', upTo: ackUpTo })
342
+ return
343
+ }
344
+
345
+ const { stored, ackUpTo } = tracker.receive(senderKeyHex, frame.seq)
346
+ if (stored) {
347
+ markSeen(seenSet, senderKeyHex, frame.seq)
348
+ const entry = {
349
+ direction: 'in',
350
+ sender: senderKeyHex,
351
+ seq: frame.seq,
352
+ ts: frame.ts,
353
+ body: frame.body,
354
+ delivered: true,
355
+ }
356
+ this._store.appendHistory(senderKeyHex, entry)
357
+ this.emit('message', senderKeyHex, entry)
358
+ }
359
+
360
+ this._network.send(senderKeyHex, { type: 'ack', upTo: ackUpTo })
361
+ }
362
+
363
+ _handleAck (friendKeyHex, frame) {
364
+ const pruned = processAck(this._outboxData, this._seqState, friendKeyHex, frame.upTo)
365
+ if (pruned > 0) {
366
+ this._saveOutbox()
367
+ this._saveState()
368
+ this.emit('ack', friendKeyHex, frame.upTo)
369
+ }
370
+ }
371
+
372
+ // ---------------------------------------------------------------------------
373
+ // Internal: invites
374
+ // ---------------------------------------------------------------------------
375
+
376
+ _checkInvite (secretHex) {
377
+ const inv = this._invites[secretHex]
378
+ if (!inv) return false
379
+ if (Date.now() - inv.createdAt > 24 * 60 * 60 * 1000) {
380
+ delete this._invites[secretHex]
381
+ this._store.invites.save(this._invites)
382
+ return false
383
+ }
384
+ return true
385
+ }
386
+
387
+ _consumeInvite (secretHex) {
388
+ delete this._invites[secretHex]
389
+ this._store.invites.save(this._invites)
390
+ }
391
+
392
+ _pruneInvites () {
393
+ const now = Date.now()
394
+ let changed = false
395
+ for (const [hex, inv] of Object.entries(this._invites)) {
396
+ if (now - inv.createdAt > 24 * 60 * 60 * 1000) {
397
+ delete this._invites[hex]
398
+ changed = true
399
+ }
400
+ }
401
+ if (changed) this._store.invites.save(this._invites)
402
+ }
403
+
404
+ async _loadSeenSet (keyHex) {
405
+ const history = await this._store.readHistory(keyHex, 10_000)
406
+ this._seenSets[keyHex] = buildSeenSet(history)
407
+ }
408
+
409
+ _saveOutbox () { this._store.outbox.save(this._outboxData) }
410
+ _saveState () { this._store.state.save(this._seqState) }
411
+ }
@@ -0,0 +1,80 @@
1
+ /**
2
+ * src/identity.js — per-device Ed25519 key pair + display name
3
+ *
4
+ * On first run we ask for a display name, generate a key pair with
5
+ * DHT.keyPair(), and persist it to <dataDir>/identity.json (mode 0600).
6
+ *
7
+ * Stored format:
8
+ * { publicKey: "<hex>", secretKey: "<hex>", name: "<display name>" }
9
+ *
10
+ * Public API:
11
+ * loadOrCreate(store, promptName) → { publicKey<Buffer>, secretKey<Buffer>, name<string> }
12
+ * bufferToHex / hexToBuffer helpers
13
+ */
14
+ import { createInterface } from 'node:readline'
15
+ import b4a from 'b4a'
16
+ import DHT from 'hyperdht'
17
+
18
+ // ---------------------------------------------------------------------------
19
+ // Helpers
20
+ // ---------------------------------------------------------------------------
21
+
22
+ export function bufferToHex (buf) {
23
+ return b4a.toString(buf, 'hex')
24
+ }
25
+
26
+ export function hexToBuffer (hex) {
27
+ return b4a.from(hex, 'hex')
28
+ }
29
+
30
+ // ---------------------------------------------------------------------------
31
+ // Interactive name prompt (only used on first run, before Ink mounts)
32
+ // ---------------------------------------------------------------------------
33
+
34
+ function stdinPromptName () {
35
+ return new Promise((resolve) => {
36
+ const rl = createInterface({ input: process.stdin, output: process.stdout })
37
+ rl.question('Welcome to TerminalChat! Enter your display name: ', (answer) => {
38
+ rl.close()
39
+ resolve(answer.trim() || 'Anonymous')
40
+ })
41
+ })
42
+ }
43
+
44
+ // ---------------------------------------------------------------------------
45
+ // Load or create (called at startup before the TUI mounts)
46
+ // ---------------------------------------------------------------------------
47
+
48
+ /**
49
+ * Load the identity from the given store, or create a new one.
50
+ *
51
+ * @param {object} store A store instance from createStore().
52
+ * @param {Function} [namePrompt] async () → string. Defaults to stdin readline.
53
+ */
54
+ export async function loadOrCreate (store, namePrompt = stdinPromptName) {
55
+ store.ensure()
56
+
57
+ const raw = store.identity.load()
58
+ if (raw) {
59
+ return {
60
+ publicKey: hexToBuffer(raw.publicKey),
61
+ secretKey: hexToBuffer(raw.secretKey),
62
+ name: raw.name,
63
+ }
64
+ }
65
+
66
+ const name = await namePrompt()
67
+ const keyPair = DHT.keyPair()
68
+
69
+ store.identity.save({
70
+ publicKey: bufferToHex(keyPair.publicKey),
71
+ secretKey: bufferToHex(keyPair.secretKey),
72
+ name,
73
+ })
74
+
75
+ return {
76
+ publicKey: keyPair.publicKey,
77
+ secretKey: keyPair.secretKey,
78
+ name,
79
+ }
80
+ }