@dotrino/terminal-agent 0.28.0 → 0.30.0

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/README.md CHANGED
@@ -16,9 +16,26 @@ npx @dotrino/terminal-agent enroll # re-enlaza y corre
16
16
  npx @dotrino/terminal-agent --name casa # otro agente en la misma máquina, con su enlace
17
17
  npx @dotrino/terminal-agent list # los enlazados aquí
18
18
  npx @dotrino/terminal-agent info # qué aparato es: su ID, su bóveda, sus permisos
19
+ npx @dotrino/terminal-agent update # cómo se actualiza: [--approval on|off] [--notify on|off]
19
20
  # [--proxy wss://…] [--shell /bin/zsh] [--dir /ruta]
20
21
  ```
21
22
 
23
+ ### Se actualiza solo
24
+
25
+ Instalado con `npm install -g` en un prefijo del usuario (nvm o similar), el agente mira una
26
+ vez al día si hay versión nueva, comprueba que el paquete de npm cuadra con lo que midió su
27
+ release de GitHub (`npm-integrity.json`) y la instala (`@dotrino/update/npm`, CONVENCIONES §15).
28
+ Corrido con `npx`, desde un checkout o en un prefijo de root no se toca: lo dice y, si hace
29
+ falta root, avisa a quien aprueba en tu cuenta.
30
+
31
+ - **Dos ajustes, de cada agente** (`update --approval on|off`, `update --notify on|off`): pedir
32
+ antes aprobación a tu bóveda (apagado) y avisar de que se actualizó (encendido).
33
+ - **Reiniciar cierra las consolas**, así que la versión nueva se instala al salir pero el
34
+ agente solo se reinicia cuando no queda ninguna consola abierta, y solo si hay quien lo
35
+ levante (systemd, pm2).
36
+ - `info` dice si hay una versión que se pidió y no se aprobó, o que necesita permisos de
37
+ administrador.
38
+
22
39
  Las ventanas de esta máquina:
23
40
 
24
41
  ```sh
package/bin/cli.js CHANGED
@@ -6,6 +6,8 @@
6
6
  * dotrino-terminal-agent enroll [--name <n>] # re-enlaza (sobrescribe) y corre el agente
7
7
  * dotrino-terminal-agent list # los agentes enlazados en esta máquina
8
8
  * dotrino-terminal-agent info [--name <n>] # qué aparato es: su ID, su bóveda, sus permisos
9
+ * dotrino-terminal-agent update [--name <n>] [--approval on|off] [--notify on|off]
10
+ * # cómo se actualiza este agente (CONVENCIONES §15)
9
11
  *
10
12
  * Las ventanas de esta máquina se abren con `dotrino-terminal` (bin/terminal.js), que habla
11
13
  * con este agente por un socket local y lo levanta si no está corriendo.
@@ -16,7 +18,7 @@
16
18
  * solo comando queda enlazado y aparece solo en terminal.dotrino.com.
17
19
  */
18
20
  import { createRequire } from 'node:module'
19
- import { watchForUpdate } from '@dotrino/update'
21
+ import { updatePrefsCommand, updateStatusText } from '@dotrino/update/npm'
20
22
  import { startAgent } from '../index.js'
21
23
  import { linkInteractive, loadLink, dataDir, LABEL } from '../link.js'
22
24
  import { listInstances, lockInstance, instancesRoot } from '@dotrino/remote-agent/instances'
@@ -34,6 +36,10 @@ if (args.includes('-h') || args.includes('--help')) {
34
36
  dotrino-terminal-agent list los agentes enlazados en esta máquina
35
37
  dotrino-terminal-agent info [--name <n>] qué aparato es: su ID (el de «dotrino-vault members»),
36
38
  su bóveda y sus permisos. Sin red. [--json]
39
+ dotrino-terminal-agent update [--name <n>] cómo se actualiza este agente. Por defecto lo hace
40
+ solo y avisa de que lo hizo:
41
+ --approval on|off pedir antes aprobación a tu bóveda
42
+ --notify on|off avisar cuando se actualiza
37
43
  opciones: [--name <n>] [--proxy <wss://…>] [--shell <bin>] [--dir <ruta>]
38
44
  [--local] no enlazar ahora: atender solo a las ventanas de esta máquina
39
45
 
@@ -49,6 +55,20 @@ if (cmd === 'list') {
49
55
  process.exit(0)
50
56
  }
51
57
 
58
+ // `update`: los dos ajustes de ESTE agente (`@dotrino/update/npm`). Sin banderas, los enseña.
59
+ if (cmd === 'update') {
60
+ let r
61
+ try {
62
+ const dir = opt('--dir') || dataDir(opt('--name'))
63
+ // Solo las banderas de este comando: `--name`/`--dir` ya eligieron la carpeta.
64
+ const own = args.slice(1).filter((a, i, all) => !['--name', '--dir'].includes(a) && !['--name', '--dir'].includes(all[i - 1]))
65
+ r = updatePrefsCommand(own, { dir, lang: 'es' })
66
+ } catch (e) { console.error('error:', e.message); process.exit(1) }
67
+ if (!r.handled) { console.error('uso: dotrino-terminal-agent update [--name <n>] [--approval on|off] [--notify on|off]'); process.exit(2) }
68
+ ;(r.ok ? console.log : console.error)(r.text)
69
+ process.exit(r.ok ? 0 : 2)
70
+ }
71
+
52
72
  // `info`: la pieza común del ecosistema (`@dotrino/vault/device-info`). Lo que se viene a
53
73
  // mirar es el ID, para buscarlo en el acta.
54
74
  if (cmd === 'info') {
@@ -57,7 +77,11 @@ if (cmd === 'info') {
57
77
  const link = loadLink(dir)
58
78
  if (!link) { console.error(`Este agente no está enlazado (${dir}). Enlázalo con: dotrino-terminal-agent`); process.exit(1) }
59
79
  const info = await deviceInfo(link, { kind: LABEL, name: opt('--dir') ? null : dir.split(/[\\/]/).pop(), version: VERSION, dir })
60
- console.log(args.includes('--json') ? JSON.stringify(info, null, 2) : formatDeviceInfo(info))
80
+ // Lo pendiente de su actualización (se pidió y no se aprobó, o necesita permisos de
81
+ // administrador), si hay algo que decir. Sin red: sale de lo apuntado en su carpeta.
82
+ const pending = updateStatusText({ dir, current: VERSION, lang: 'es' })
83
+ if (args.includes('--json')) console.log(JSON.stringify(pending ? { ...info, update: pending } : info, null, 2))
84
+ else console.log(formatDeviceInfo(info) + (pending ? '\n' + pending : ''))
61
85
  } catch (e) { console.error('error:', e.message); process.exit(1) }
62
86
  process.exit(0)
63
87
  }
@@ -87,15 +111,14 @@ try {
87
111
  console.log(' ventanas de esta máquina:', agent.socket)
88
112
  if (agent.remote) console.log(' máquina:', agent.machineId, '(tus otros aparatos pueden abrir estas consolas)\n')
89
113
  else console.log(' sin enlazar: solo ventanas de esta máquina. Para abrirlas desde otros aparatos: dotrino-terminal-agent enroll\n')
90
- // §15: una vez al día mira si hay versión nueva y lo dice. Solo avisa: instalar lo decide una persona.
91
- watchForUpdate({
92
- current: VERSION, source: 'npm', pkg: '@dotrino/terminal-agent',
93
- onNewer: (r) => console.log(`[terminal-agent] version ${r.version} is available (running ${r.current}): npx @dotrino/terminal-agent@latest`)
94
- })
114
+ // §15: se actualiza solo. Mira al arrancar y una vez al día; pedir aprobación y avisar son
115
+ // ajustes de este agente (`dotrino-terminal-agent update`). Solo se reinicia sin consolas.
116
+ const { startSelfUpdate } = await import('../update.js')
117
+ const stopUpdates = startSelfUpdate({ dir, version: VERSION, agent })
95
118
  // Mantener vivo el servicio aunque stdin no sea una TTY (systemd/pm2/`nohup </dev/null`):
96
119
  // el socket del proxio va `unref`'d, así que sin esto el proceso saldría al arrancar.
97
120
  const keepAlive = setInterval(() => {}, 1 << 30)
98
- const bye = () => { clearInterval(keepAlive); agent.close(); process.exit(0) }
121
+ const bye = () => { clearInterval(keepAlive); stopUpdates(); agent.close(); process.exit(0) }
99
122
  process.on('SIGINT', bye); process.on('SIGTERM', bye)
100
123
  } catch (e) {
101
124
  console.error('error:', e.message)
package/consoles.js CHANGED
@@ -176,13 +176,14 @@ class Console {
176
176
  * de lo posterior.
177
177
  * @returns {Promise<string>} la pantalla serializada
178
178
  */
179
- attach (viewer) {
179
+ attach (viewer, { scrollback } = {}) {
180
180
  const pending = []
181
181
  const buffering = { onOut: (d) => pending.push(d), onExit: viewer.onExit }
182
182
  this.viewers.add(buffering)
183
183
  return new Promise((resolve) => {
184
184
  this.screen.write('', () => {
185
- const snapshot = this.serializer.serialize()
185
+ // `scrollback: 0` = solo lo que se ve ahora (ver `history`).
186
+ const snapshot = this.serializer.serialize(scrollback === undefined ? undefined : { scrollback })
186
187
  this.viewers.delete(buffering)
187
188
  this.viewers.add(viewer)
188
189
  this.doneAt = null // quien entra, la atiende (el `_meta` de abajo lo cuenta)
@@ -192,6 +193,33 @@ class Console {
192
193
  })
193
194
  }
194
195
 
196
+ /** ¿Hay líneas por encima de lo que se ve? Sin ellas, la pantalla sola ya es la foto entera. */
197
+ hasHistory () { return this.screen.buffer.normal.baseY > 0 }
198
+
199
+ /**
200
+ * LA FOTO ENTERA, PARA QUIEN YA ESTÁ MIRANDO. Quien se enganchó recibiendo solo la pantalla
201
+ * (`attach` con `scrollback: 0`) pide después el historial: lo que escribe la shell mientras
202
+ * se hace la foto se guarda y sale detrás, igual que en `attach`, así que no se pierde ni se
203
+ * repite nada. Empieza por un reinicio del terminal (`ESC c`): el cliente la pinta encima de
204
+ * lo que tenía sin saber que es una segunda foto.
205
+ * @returns {Promise<string|null>} `null` si ese mirón ya no está
206
+ */
207
+ history (viewer) {
208
+ if (!this.viewers.has(viewer)) return Promise.resolve(null)
209
+ const pending = []
210
+ const buffering = { onOut: (d) => pending.push(d), onExit: viewer.onExit }
211
+ this.viewers.delete(viewer)
212
+ this.viewers.add(buffering)
213
+ return new Promise((resolve) => {
214
+ this.screen.write('', () => {
215
+ const snapshot = this.serializer.serialize()
216
+ this.viewers.delete(buffering)
217
+ this.viewers.add(viewer)
218
+ resolve('\x1bc' + snapshot + pending.join(''))
219
+ })
220
+ })
221
+ }
222
+
195
223
  detach (viewer) {
196
224
  if (!this.viewers.has(viewer)) return
197
225
  // Quién decidía, ANTES de quitarlo: si era él, hay que pasar el tamaño a otro.
package/index.js CHANGED
@@ -37,6 +37,9 @@ import { makeGate } from './access.js'
37
37
 
38
38
  const require = createRequire(import.meta.url)
39
39
 
40
+ /** Cuánto se espera al canal directo antes de mandar el historial por el proxio. */
41
+ export const HISTORY_WAIT_MS = 8000
42
+
40
43
  export { LABEL }
41
44
 
42
45
  /** Cada cuánto mira un agente sin enlazar si ya lo enlazaron. */
@@ -121,7 +124,12 @@ export function serveSession (session, hub, { origin = 'remote', gate = null } =
121
124
  async function attachTo (c, { fresh }) {
122
125
  release()
123
126
  current = c
124
- const snapshot = await c.attach(viewer)
127
+ // SI EL CANAL DIRECTO AÚN NO ABRIÓ, PRIMERO SOLO LA PANTALLA. La foto con su historial
128
+ // son cientos de KB y, mandada ya, da toda la vuelta por el proxio (medido: 381 KB por el
129
+ // proxio en cada enganche). La pantalla sola son unos pocos KB y se ve igual de rápido; el
130
+ // historial sale en cuanto abre el directo (`sendHistory`). No se espera a nada para pintar.
131
+ const later = origin === 'remote' && typeof session.whenDirect === 'function' && !session.direct() && c.hasHistory()
132
+ const snapshot = await c.attach(viewer, later ? { scrollback: 0 } : {})
125
133
  // Mientras se hacía la foto la sesión se fue, soltó la consola o pidió otra: esta ya no es la
126
134
  // suya. Quedarse enganchado dejaba un mirón FANTASMA (la consola salía «abierta en otro
127
135
  // aparato» sin nadie mirando, y nadie la elegía como libre).
@@ -132,6 +140,22 @@ export function serveSession (session, hub, { origin = 'remote', gate = null } =
132
140
  await session.send({ type: 'replay', id: c.id, data: snapshot.slice(i, i + REPLAY_CHUNK), last: i + REPLAY_CHUNK >= snapshot.length })
133
141
  }
134
142
  await session.send({ type: 'attached', id: c.id, fresh, console: c.info() })
143
+ // Sin esperarlo (pintar no espera a nada), y un fallo aquí no puede tumbar el agente: se dice.
144
+ if (later) sendHistory(c).catch((e) => console.error('[terminal-agent] could not send the history of console', c.id, '-', e?.message || e))
145
+ }
146
+
147
+ /**
148
+ * El historial que `attachTo` dejó para después. Sale cuando abre el canal directo; si en
149
+ * `HISTORY_WAIT_MS` no abrió, sale igual por el proxio: llegar tarde es mejor que no llegar.
150
+ */
151
+ async function sendHistory (c) {
152
+ await session.whenDirect(HISTORY_WAIT_MS)
153
+ if (current !== c) return // ya mira otra, o se fue
154
+ const full = await c.history(viewer)
155
+ if (full == null || current !== c) return
156
+ for (let i = 0; i < full.length; i += REPLAY_CHUNK) {
157
+ await session.send({ type: 'replay', id: c.id, data: full.slice(i, i + REPLAY_CHUNK), last: i + REPLAY_CHUNK >= full.length })
158
+ }
135
159
  }
136
160
 
137
161
  session.on('message', (msg) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dotrino/terminal-agent",
3
- "version": "0.28.0",
3
+ "version": "0.30.0",
4
4
  "description": "Dotrino Terminal: las ventanas de esta máquina (dotrino-terminal) y su agente, que deja abrir esas mismas consolas desde los otros aparatos de tu cuenta, cifrado punto a punto.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -18,6 +18,7 @@
18
18
  "link.js",
19
19
  "local.js",
20
20
  "title.js",
21
+ "update.js",
21
22
  "bin"
22
23
  ],
23
24
  "scripts": {
@@ -27,10 +28,10 @@
27
28
  },
28
29
  "dependencies": {
29
30
  "@dotrino/identity": "0.107.2",
30
- "@dotrino/proxy-client": "0.30.0",
31
- "@dotrino/remote-agent": "0.17.0",
32
- "@dotrino/update": "0.2.2",
33
- "@dotrino/vault": "0.79.0",
31
+ "@dotrino/proxy-client": "0.30.3",
32
+ "@dotrino/remote-agent": "0.18.0",
33
+ "@dotrino/update": "0.5.0",
34
+ "@dotrino/vault": "0.82.0",
34
35
  "@xterm/addon-serialize": "0.13.0",
35
36
  "@xterm/headless": "5.5.0",
36
37
  "jsonc-parser": "3.3.1",
package/update.js ADDED
@@ -0,0 +1,98 @@
1
+ /**
2
+ * update.js — este agente SE ACTUALIZA SOLO (CONVENCIONES §15, dueño 2026-10-08).
3
+ *
4
+ * Lo que mira, verifica e instala es `@dotrino/update/npm`; a quién se pregunta y a quién se
5
+ * avisa es `@dotrino/vault/service`. Aquí solo se juntan las dos piezas con lo que es propio
6
+ * de este agente: dónde vive su enlace y cuándo puede reiniciarse.
7
+ *
8
+ * Los dos ajustes son de CADA agente (`dotrino-terminal-agent update --approval|--notify`),
9
+ * no de la bóveda: por defecto se actualiza sin preguntar y avisa de que lo hizo.
10
+ *
11
+ * REINICIAR MATA LAS CONSOLAS (viven en este proceso, `consoles.js`), así que la versión
12
+ * nueva se instala en cuanto sale pero el agente solo se va cuando no queda ninguna consola
13
+ * abierta. Tumbarle a alguien la shell en la que está trabajando para estrenar una versión
14
+ * es justo lo contrario de lo que se quiere.
15
+ */
16
+ import { watchSelfUpdateNpm } from '@dotrino/update/npm'
17
+ import { vaultUpdateHooks } from '@dotrino/vault/service'
18
+ import { loadLink } from './link.js'
19
+
20
+ export const PKG = '@dotrino/terminal-agent'
21
+ export const REPO = 'imdotrino/dotrino-terminal'
22
+ /** Este repo también lleva la PWA y el escritorio: las releases del agente van con prefijo. */
23
+ export const releaseTag = (version) => `agent-v${version}`
24
+
25
+ /** Cada cuánto se mira si ya no quedan consolas para reiniciar con la versión instalada. */
26
+ export const IDLE_CHECK_MS = 60_000
27
+
28
+ const fail = (code, message) => Object.assign(new Error(message), { code })
29
+
30
+ /**
31
+ * Lo que este agente le dice a SU bóveda sobre actualizarse: los tres ganchos de
32
+ * `vaultUpdateHooks` (`@dotrino/vault/service`), armados EN CADA LLAMADA con el enlace leído
33
+ * del disco. El papel se renueva mientras el agente corre, y el agente puede arrancar sin
34
+ * enlace y enlazarse después: una conexión fijada al arrancar se quedaría vieja.
35
+ *
36
+ * @param {{ dir: string, product?: string, log?: (m: string) => void, load?: (dir: string) => any, make?: (o: any) => any }} o
37
+ * @returns {{ mayUpdate: Function, onUpdated: Function, onNeedsRoot: Function }}
38
+ */
39
+ export function vaultHooks ({ dir, product = PKG, log = console.log, load = loadLink, make = vaultUpdateHooks }) {
40
+ const now = () => {
41
+ const link = load(dir)
42
+ if (!link?.device || !link.cert || !link.iss) return null
43
+ return make({ product, log, proxyUrl: link.proxy || 'wss://proxy.dotrino.com', masterPubkey: link.iss, device: link.device, cert: link.cert })
44
+ }
45
+ return {
46
+ // true = sí · false = no, o pasó el día sin respuesta · lanza = no se pudo preguntar.
47
+ async mayUpdate (u) {
48
+ const h = now()
49
+ // Sin enlace no hay a quién preguntar. No es un «no»: se dice y se reintenta.
50
+ if (!h) throw fail('not-linked', 'this agent is not linked to a vault, so there is nobody to ask')
51
+ return h.mayUpdate(u)
52
+ },
53
+ // Sin enlace no hay bóveda a la que contárselo: no es un fallo que reintentar.
54
+ async onUpdated (u) { await now()?.onUpdated(u) },
55
+ async onNeedsRoot (u) { await now()?.onNeedsRoot(u) }
56
+ }
57
+ }
58
+
59
+ /**
60
+ * Enciende la autoactualización del agente que ya corre.
61
+ *
62
+ * `dir` es la carpeta de datos de ESTA instancia (su enlace y sus ajustes) y `version` la
63
+ * que está en marcha. Lo demás es para las pruebas.
64
+ *
65
+ * @param { dir: string, version: string, agent: { consoles: { consoles: Map<string, unknown> }, close: () => void }, exit?: (code: number) => void,
66
+ * log?: (m: string) => void, watch?: (o: any) => (() => void), hooks?: object, idleCheckMs?: number } o
67
+ * @returns {() => void} para dejar de mirar
68
+ */
69
+ export function startSelfUpdate ({ dir, version, agent, exit = (code) => process.exit(code), log = console.log, watch = watchSelfUpdateNpm, hooks = vaultHooks({ dir, log }), idleCheckMs = IDLE_CHECK_MS }) {
70
+ let waiting = null
71
+ const open = () => agent.consoles.consoles.size
72
+ const restart = (v) => {
73
+ log(`[terminal-agent] restarting to run ${v}`)
74
+ agent.close()
75
+ exit(0)
76
+ }
77
+ const stop = watch({
78
+ pkg: PKG,
79
+ current: version,
80
+ repo: REPO,
81
+ tag: releaseTag,
82
+ dir,
83
+ ...hooks,
84
+ onInstalled: ({ version: v, restart: supervised }) => {
85
+ // Sin quien lo levante no se va: irse sería apagarle el servicio al usuario.
86
+ if (!supervised) return
87
+ if (!open()) return restart(v)
88
+ if (waiting) return
89
+ log(`[terminal-agent] ${v} is installed · ${open()} console(s) open, so it restarts when none is left`)
90
+ waiting = setInterval(() => { if (!open()) { clearInterval(waiting); waiting = null; restart(v) } }, idleCheckMs)
91
+ waiting.unref?.()
92
+ },
93
+ log
94
+ })
95
+ return () => { if (waiting) { clearInterval(waiting); waiting = null } stop?.() }
96
+ }
97
+
98
+ export default { startSelfUpdate, vaultHooks, PKG, REPO, releaseTag }