@glassnote/client 2.4.10 → 2.4.11

package/INSTALACION.md

@@ -41,6 +41,7 @@ que es justo lo que hace `glassnote uninstall`.
 | `glassnote start --detach` | lo arranca y libera la terminal |
 | `glassnote install [version]` | instala o reinstala (`latest` por defecto) |
 | `glassnote update [version]` | actualiza a la última publicada |
+| `glassnote pair` | da de alta el equipo con la API key de la organización |
 | `glassnote uninstall` | quita autoarranque, `~/.glassnote` y la línea del rc |
 | `glassnote status` | versión, modo, rutas, autoarranque y estado del sandbox |
 | `glassnote fix-sandbox` | (Linux) restaura el sandbox de Chromium; pide sudo una vez |
@@ -48,6 +49,89 @@ que es justo lo que hace `glassnote uninstall`.
 Banderas de `install`: `--no-path` (no toca el rc, imprime la línea) y `--no-start`
 (instala y no arranca).
 
+## Alta masiva: emparejar sin que nadie mire la pantalla
+
+El emparejamiento normal es a dos manos: el cliente muestra un código y una persona lo
+escribe en la web. Para un equipo está bien. Para trescientos —una cadena que abre
+locales, un parque que se reinstala entero— es una tarde entera y un error de tipeo cada
+veinte equipos.
+
+Con la **API key de la organización**, el equipo se da de alta solo durante la
+instalación. La API contesta con el servidor y el token, el instalador los deja escritos
+donde la app los busca, y el cliente arranca ya conectado.
+
+```sh
+# Linux / macOS — ojo con el `-s --`, es lo que hace que sh le pase las banderas al script
+curl -fsSL https://glassnote.intermark.ec/install.sh | sh -s -- \
+  --org-id 55 --api-key <clave> --device-name "Caja 01" --user-name "Santiago"
+```
+
+```powershell
+# Windows
+& ([scriptblock]::Create((irm https://glassnote.intermark.ec/install.ps1))) `
+  -OrgId 55 -ApiKey <clave> -DeviceName 'Caja 01' -UserName 'Santiago'
+```
+
+| bandera | variable de entorno | por defecto |
+|---|---|---|
+| `--org-id` | `GLASSNOTE_ORG_ID` | — (obligatoria) |
+| `--api-key` | `GLASSNOTE_API_KEY` | — (obligatoria) |
+| `--device-name` | `GLASSNOTE_DEVICE_NAME` | el hostname del equipo |
+| `--user-name` | `GLASSNOTE_USER_NAME` | el usuario del sistema |
+| `--api-url` | `GLASSNOTE_API_URL` | `https://glassnoteapi.intermark.ec` |
+| `--ws-url` | `GLASSNOTE_WS_URL` | el que anuncie la API |
+
+Las variables de entorno existen porque un despliegue por GPO o por MDM muchas veces no
+puede pasar argumentos pero sí poner entorno.
+
+### Otro servidor
+
+**El websocket no se elige en el instalador: lo decide la API que atiende el alta.** El
+token que emite sólo vale en su propio websocket, así que apuntar a otro sitio no daría
+un equipo conectado a otro servidor, daría un equipo dado de alta que no conecta. Para
+instalar contra otra API se cambia `--api-url` y el websocket viene de vuelta en la
+respuesta:
+
+```sh
+curl -fsSL https://glassnote.intermark.ec/install.sh | sh -s -- \
+  --api-url https://api.otrocliente.com --org-id 12 --api-key <clave>
+```
+
+Esa URL de websocket es además de donde el cliente saca el origen HTTP de la API para
+reportar su versión, así que es **el único dato de servidor** que el equipo guarda.
+
+`--ws-url` cubre el único caso que lo anterior no: que la API anuncie una dirección a la
+que el equipo no llega —una IP de LAN detrás de un NAT, un proxy inverso publicado con
+otro nombre, DNS partido—. Ahí el alta sale bien y los equipos guardan una URL muerta sin
+ninguna señal en el momento de instalar. Por eso, cuando el host que anuncia la API no es
+el mismo al que se pidió el alta, el instalador lo dice en pantalla. **Lo correcto es
+arreglar `WEBSOCKET_URL` en la API**; `--ws-url` es la salida cuando no se puede.
+
+```sh
+glassnote pair --org-id 12 --api-key <clave> \
+  --api-url https://api.cliente.local --ws-url wss://glassnote.cliente.com/ws
+```
+
+**El nombre por defecto es el del propio equipo, no uno genérico.** Es lo que hace que el
+*mismo* comando sirva para todo el parque: sin eso, el tablero termina con trescientos
+"Unnamed Device" y hay que renombrarlos a mano, que es justo el trabajo que esto viene a
+evitar.
+
+La API key se saca en la web, en las claves de la organización. **Da de alta equipos en
+esa organización**: es un secreto de despliegue, no algo que se reparta. Caduca a los 30
+días, lo que acota lo que se puede hacer con una que se filtre.
+
+Un equipo ya instalado se empareja sin reinstalar:
+
+```sh
+glassnote pair --org-id 55 --api-key <clave> --device-name "Caja 01"
+```
+
+Si el alta falla, el comando **sale con código distinto de cero** y dice por qué (la
+clave no sirve, la organización no es la de esa clave, el plan llegó a su tope de
+equipos). El cliente queda instalado igual: se reintenta con `glassnote pair`. Emparejar
+dos veces el mismo equipo no lo duplica ni gasta un cupo extra; solo le renueva el token.
+
 `install` y `update` también aceptan un *spec* de npm en vez de una versión: un `.tgz`,
 una ruta local o una URL. Es lo que permite probar un paquete antes de publicarlo:
 

package/bin/glassnote.js

@@ -17,6 +17,7 @@ const os = require('os');
 const { spawn, spawnSync } = require('child_process');
 
 const mode = require('../npmMode');
+const pairing = require('../pairing');
 const pkg = require('../package.json');
 
 const IS_WIN = process.platform === 'win32';
@@ -140,6 +141,78 @@ function esperarAQueCierre(maxMs) {
 	return false;
 }
 
+// Windows no deja reemplazar los archivos de un proceso vivo. Reinstalar encima del
+// cliente abierto muere con «EBUSY: resource busy or locked, rename ...\electron\dist\
+// icudtl.dat», y muere A MITAD: npm ya apartó parte del árbol viejo, así que la
+// instalación que había queda rota además de no haber instalado la nueva. Es el fallo
+// que se lleva puesto a cualquiera que corra el `irm | iex` una segunda vez, que es
+// justo lo que se le pide a la gente para actualizar.
+//
+// Se cierra por RUTA del ejecutable, nunca por nombre: "electron.exe" es también el
+// VS Code y el Slack de quien esté delante, y cerrarle eso para instalar esto sería
+// bastante peor que el fallo que se viene a arreglar. Sólo se toca lo que vive dentro
+// de ~/.glassnote, que es nuestro por definición.
+// El guion de PowerShell, aparte: decidir QUE se le pide al sistema es una funcion pura
+// y se puede comprobar desde cualquier maquina; matar procesos de verdad, no. Y la parte
+// que mas silenciosamente se rompe es justo esta, el entrecomillado de la ruta.
+//
+// Comillas SIMPLES de PowerShell: son literales y no interpretan la barra invertida. Con
+// comillas dobles habria que escapar, y una ruta escapada a la manera de JSON le llega a
+// PowerShell con las barras duplicadas y no coincide con nada: el filtro no encontraria
+// un solo proceso y el EBUSY volveria, mudo.
+//
+// El filtro apunta a `<home>\npm\node_modules`, NO a `<home>` entero. La diferencia no es
+// cosmetica: cuando el equipo no tenia Node, el instalador se baja el suyo a
+// `<home>\node-v20.18.1-win-x64\node.exe` —que es el caso normal en Windows— y ese
+// node.exe es el que esta ejecutando ESTE codigo. Filtrando por `<home>` el instalador se
+// mataba a si mismo a mitad, salia con codigo -1 y no instalaba nada. Se vio en la VM de
+// Windows el 2026-09-07; en Linux no pasa porque alli no hay nada que cerrar.
+//
+// Se excluye ademas el pid propio, por si algun dia el CLI viviera dentro de esa carpeta.
+// Donde viven los binarios del cliente YA INSTALADO. Es lo unico que npm va a
+// reemplazar, y por tanto lo unico que hay que cerrar.
+function rutaDelClienteInstalado() {
+	return path.join(mode.NPM_PREFIX, 'node_modules');
+}
+
+function guionCerrarCliente(raizDir, pidPropio) {
+	const raiz = `'${String(raizDir).replace(/'/g, "''")}'`;
+	const pid = Number(pidPropio) || 0;
+	return [
+		`$raiz = ${raiz}`,
+		`$yo = ${pid}`,
+		'$procs = @(Get-CimInstance Win32_Process | Where-Object { $_.ProcessId -ne $yo -and $_.ExecutablePath -and $_.ExecutablePath.StartsWith($raiz, [System.StringComparison]::OrdinalIgnoreCase) })',
+		'$procs | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }',
+		'Write-Output $procs.Count',
+	].join('; ');
+}
+
+function cerrarClienteWindows() {
+	if (!IS_WIN) return true; // en POSIX se puede reemplazar un archivo abierto
+
+	const res = spawnSync(
+		'powershell.exe',
+		['-NoProfile', '-NonInteractive', '-Command', guionCerrarCliente(rutaDelClienteInstalado(), process.pid)],
+		{ encoding: 'utf8', timeout: 20000 }
+	);
+
+	// Si PowerShell no está o falló, no se sigue a ciegas: se mira si el cliente
+	// contesta, que es la señal barata de que sigue vivo.
+	if (res.error || res.status !== 0) {
+		if (!clienteEnMarcha()) return true;
+		console.error('glassnote: no pude cerrar el cliente automáticamente.');
+		return false;
+	}
+
+	const cerrados = parseInt(String(res.stdout || '').trim(), 10) || 0;
+	if (cerrados === 0) return true;
+
+	step(`el cliente estaba abierto: cerrados ${cerrados} procesos suyos`);
+	// El proceso desaparece de la lista antes de que el SO suelte los handles de sus
+	// archivos, y npm necesita los handles, no la lista.
+	return esperarAQueCierre(15000);
+}
+
 const log = (...args) => console.log(...args);
 // Cada paso se dice EN CUANTO EMPIEZA: lo que hace que un instalador parezca colgado
 // no es que tarde, es que tarde sin decir en qué está.
@@ -464,16 +537,29 @@ function borrarAppMac() {
 	}
 }
 
-function cmdInstall(args) {
-	const version = args.find((a) => !a.startsWith('-')) || 'latest';
+async function cmdInstall(args) {
+	// El argumento suelto es la version, pero las banderas de emparejamiento traen valor
+	// propio: sin saltarlo, `install --api-key abc` intentaba instalar la version "abc".
+	const version = pairing.argumentoPosicional(args) || 'latest';
 	const noPath = args.includes('--no-path');
 	const noStart = args.includes('--no-start');
+	const emparejamiento = pairing.leerOpciones(args, process.env);
 
 	const spec = toSpec(version);
 	log(`glassnote — instalando ${spec}`);
 	fs.mkdirSync(mode.NPM_PREFIX, { recursive: true });
 	fs.mkdirSync(mode.BIN_DIR, { recursive: true });
 
+	// ANTES de que npm mueva un solo archivo: si el cliente está abierto, npm apartaría
+	// el árbol viejo a medias y dejaría rota la instalación que ya funcionaba.
+	if (!cerrarClienteWindows()) {
+		fail(
+			'el cliente sigue abierto y Windows no deja reemplazar sus archivos.\n' +
+				'  Cerralo desde el ícono de la bandeja (clic derecho → Salir) y volvé a correr esto.\n' +
+				'  No se tocó nada: la instalación que tenías sigue como estaba.'
+		);
+	}
+
 	// Los scripts de instalación van ACTIVADOS a propósito: el binario de electron se
 	// baja en un postinstall. Con --ignore-scripts quedaría instalado y roto.
 	step(`npm install -g --prefix ${mode.NPM_PREFIX} (sin root, la primera vez tarda: baja electron)`);
@@ -530,6 +616,14 @@ function cmdInstall(args) {
 	log('Para actualizar más adelante: glassnote update (o correr esto mismo otra vez).');
 	log('');
 
+	// Antes de arrancar: si la instalacion trae credenciales de organizacion, el equipo se
+	// da de alta ahora. Arrancarlo primero solo consigue que aparezca la pantalla del
+	// keycode un instante antes de quedar emparejado igual.
+	if (pairing.pidenEmparejar(emparejamiento)) {
+		const codigo = await emparejar(emparejamiento, { reciénInstalado: true });
+		if (codigo !== 0) return codigo;
+	}
+
 	if (noStart) {
 		log('Arrancalo cuando quieras:  glassnote');
 		return 0;
@@ -549,6 +643,66 @@ function cmdInstall(args) {
 	return 0;
 }
 
+// Alta desatendida contra la API. Devuelve codigo de salida y no lanza: un despliegue
+// masivo se guia por el codigo, no por lo que aparezca en pantalla.
+async function emparejar(opciones, { reciénInstalado = false } = {}) {
+	const userData = conUserData((u) => u);
+	if (!userData) {
+		console.error('glassnote: no pude leer los datos de usuario para emparejar.');
+		return 1;
+	}
+
+	step(`dando de alta el equipo en la organizacion ${opciones.orgId || '(sin id)'}`);
+
+	try {
+		const alta = await pairing.emparejar(opciones, userData);
+		log('');
+		log(
+			alta.yaEstaba
+				? 'El equipo ya estaba en la organizacion; se le renovo el token.'
+				: 'Equipo dado de alta.'
+		);
+		log(`  nombre:       ${alta.name}`);
+		log(`  organizacion: ${alta.organizationId}`);
+		log(`  servidor:     ${alta.server}${alta.servidorForzado ? ' (forzado con --ws-url)' : ''}`);
+		log(`  uuid:         ${alta.uuid}`);
+		log('');
+		// El equipo va a hablar SOLO con este websocket, y de él saca también el origen
+		// HTTP de la API. Si no es el mismo host al que se acaba de pedir el alta, la API
+		// está anunciando otra dirección: puede ser a propósito, o puede ser un
+		// WEBSOCKET_URL mal puesto que deja al parque entero conectando a la nada. Se
+		// dice acá, que es el único momento en que alguien está mirando.
+		if (!alta.mismoOrigenQueLaApi) {
+			log(`Ojo: la API contestó que el equipo se conecte a ${alta.servidorAnunciado || alta.server},`);
+			log('que no es el host al que le pediste el alta. Si el equipo no llega ahí, se');
+			log('arregla WEBSOCKET_URL en la API, o se fuerza acá con --ws-url.');
+			log('');
+		}
+		return 0;
+	} catch (error) {
+		console.error('');
+		console.error(`glassnote: no se pudo dar de alta el equipo: ${error.message}`);
+		if (reciénInstalado) {
+			console.error('El cliente quedó instalado igual. Cuando esto se resuelva:');
+		} else {
+			console.error('El equipo sigue como estaba. Para reintentar:');
+		}
+		console.error('  glassnote pair --org-id <id> --api-key <clave> --device-name <nombre>');
+		console.error('');
+		return 1;
+	}
+}
+
+async function cmdPair(args) {
+	const opciones = pairing.leerOpciones(args, process.env);
+	if (!pairing.pidenEmparejar(opciones)) {
+		console.error('glassnote pair: falta --api-key (o la variable GLASSNOTE_API_KEY).\n');
+		cmdHelp();
+		return 2;
+	}
+	return emparejar(opciones);
+}
+
 function cmdUpdate(args) {
 	if (mode.isEphemeral()) {
 		log('Estás corriendo por npx: npx ya baja la última versión cada vez.');
@@ -571,6 +725,16 @@ function cmdUpdate(args) {
 
 	if (waitMs > 0) esperarAQueCierre(waitMs);
 
+	// Sin `--wait` esto lo está corriendo una persona a mano, con el cliente abierto: el
+	// mismo EBUSY de Windows que en install, y con el mismo remedio.
+	else if (!cerrarClienteWindows()) {
+		fail(
+			'el cliente sigue abierto y Windows no deja reemplazar sus archivos.\n' +
+				'  Cerralo desde el ícono de la bandeja (clic derecho → Salir) y volvé a intentar.\n' +
+				'  No se tocó nada: la versión que tenías sigue como estaba.'
+		);
+	}
+
 	// El cwd no puede estar dentro de lo que npm va a borrar: en Windows un directorio
 	// que es el cwd de un proceso vivo no se puede eliminar, y ese proceso es este.
 	try {
@@ -731,6 +895,7 @@ function cmdHelp() {
   glassnote                     arranca el cliente
   glassnote start --detach      lo arranca y libera la terminal
   glassnote update [version]    actualiza (por defecto, la última)
+  glassnote pair                da de alta el equipo con la API key de la organización
   glassnote uninstall           quita autoarranque, ~/.glassnote y la línea del rc
   glassnote status              versión, modo, rutas y estado del autoarranque
   glassnote fix-sandbox         (Linux) restaura el sandbox de Chromium; pide sudo una vez
@@ -738,6 +903,26 @@ function cmdHelp() {
 Banderas de install:
   --no-path       no toca el rc; imprime la línea para pegarla
   --no-start      instala y no arranca el cliente
+
+Emparejamiento desatendido (install y pair) — para dar de alta muchos equipos sin que
+nadie escriba el código en la web:
+  --org-id <id>        organización a la que entra el equipo
+  --api-key <clave>    API key de esa organización
+  --device-name <n>    nombre del equipo (por defecto, el hostname)
+  --user-name <n>      persona a cargo (por defecto, el usuario del sistema)
+  --api-url <url>      otra API (por defecto, ${pairing.API_URL_POR_DEFECTO})
+  --ws-url <url>       fuerza el websocket que guarda el equipo
+
+El websocket NO se elige acá: lo decide la API que atiende el alta, porque el token que
+emite sólo vale en el suyo. Para dar de alta contra otro servidor se cambia --api-url y el
+websocket viene de vuelta solo. --ws-url es para el caso en que la API anuncia una
+dirección a la que el equipo no llega (IP de LAN, proxy inverso con otro nombre).
+
+Las mismas se pueden pasar por entorno, para despliegues que no admiten argumentos:
+GLASSNOTE_ORG_ID, GLASSNOTE_API_KEY, GLASSNOTE_DEVICE_NAME, GLASSNOTE_USER_NAME,
+GLASSNOTE_API_URL, GLASSNOTE_WS_URL.
+
+  npx @glassnote/client install --org-id 55 --api-key abc123 --device-name "Caja 01"
 `);
 	return 0;
 }
@@ -762,6 +947,9 @@ function main() {
 			});
 		case 'install':
 			return cmdInstall(rest);
+		case 'pair':
+		case 'enroll':
+			return cmdPair(rest);
 		case 'update':
 		case 'upgrade':
 			return cmdUpdate(rest);
@@ -787,7 +975,20 @@ function main() {
 // Requerido desde un test, el archivo NO debe correr nada: solo expone las piezas que
 // se comprueban. Como CLI se comporta igual que siempre.
 if (require.main === module) {
-	process.exit(main());
+	// `install` y `pair` hablan con la API, asi que main() puede devolver una promesa.
+	// Salir con process.exit() sin esperarla cortaria el alta a la mitad.
+	const resultado = main();
+	if (resultado && typeof resultado.then === 'function') {
+		resultado.then(
+			(codigo) => process.exit(codigo),
+			(error) => {
+				console.error(`glassnote: ${error && error.message ? error.message : error}`);
+				process.exit(1);
+			}
+		);
+	} else {
+		process.exit(resultado);
+	}
 } else {
-	module.exports = { npmInvocation, npmEnv, toSpec };
+	module.exports = { npmInvocation, npmEnv, toSpec, guionCerrarCliente, cerrarClienteWindows };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glassnote/client",
-  "version": "2.4.10",
+  "version": "2.4.11",
   "description": "GlassNote — cliente de escritorio de notas superpuestas. Se instala con npx, sin instaladores nativos ni firmas.",
   "main": "main.js",
   "publishConfig": {
@@ -36,6 +36,7 @@
     "localserver.js",
     "logUtilities.js",
     "userData.js",
+    "pairing.js",
     "INSTALACION.md",
     "README.md"
   ],
@@ -54,7 +55,9 @@
     "prepublishOnly": "node scripts/check-publish.js",
     "start-electron": "electron .",
     "test-update": "node scripts/test-update.js",
-    "test": "node scripts/test-update.js"
+    "test-pairing": "node scripts/test-pairing.js",
+    "test-cli": "node scripts/test-cli.js",
+    "test": "node scripts/test-cli.js && node scripts/test-pairing.js && node scripts/test-update.js"
   },
   "keywords": [
     "glassnote",

package/pairing.js

@@ -0,0 +1,338 @@
+// Emparejamiento desatendido: el equipo se da de alta solo con la API key de la
+// organizacion, sin que nadie mire la pantalla.
+//
+// El emparejamiento de siempre es a dos manos: el cliente muestra un keycode y una
+// persona lo escribe en la web. Para un equipo esta bien. Para trescientos —una cadena
+// que abre locales, un parque que se reinstala entero— no es un flujo, es una tarde
+// entera y un error de tipeo cada veinte equipos. Aca el instalador ya trae la API key
+// de la organizacion, asi que el propio cliente pide su alta a la API y se guarda el
+// token con el que se conecta. La instalacion termina con el equipo ya en el tablero.
+//
+// Vive fuera de bin/glassnote.js a proposito: decidir QUE se le pide a la API es una
+// funcion pura y se puede comprobar en cualquier maquina; hacerlo de verdad, no.
+'use strict';
+
+const os = require('os');
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+const API_URL_POR_DEFECTO = 'https://glassnoteapi.intermark.ec';
+const TIMEOUT_MS = 20000;
+
+// Un solo sitio donde vive la correspondencia bandera <-> variable de entorno. Las
+// variables existen porque un despliegue por GPO o por MDM muchas veces no puede pasar
+// argumentos, pero si puede poner entorno.
+const OPCIONES = [
+	{ clave: 'orgId', banderas: ['--org-id', '--organization-id'], env: 'GLASSNOTE_ORG_ID' },
+	{ clave: 'apiKey', banderas: ['--api-key', '--apikey'], env: 'GLASSNOTE_API_KEY' },
+	{ clave: 'deviceName', banderas: ['--device-name', '--name'], env: 'GLASSNOTE_DEVICE_NAME' },
+	{ clave: 'userName', banderas: ['--user-name', '--owner-name', '--owner'], env: 'GLASSNOTE_USER_NAME' },
+	{ clave: 'apiUrl', banderas: ['--api-url'], env: 'GLASSNOTE_API_URL' },
+	{ clave: 'wsUrl', banderas: ['--ws-url', '--server'], env: 'GLASSNOTE_WS_URL' },
+];
+
+// Acepta `--org-id 55` y `--org-id=55`: los dos aparecen en los scripts de despliegue que
+// escribe la gente, y fallar por la forma del signo igual es una perdida de tiempo.
+function leerOpciones(args, env) {
+	const argv = Array.isArray(args) ? args : [];
+	const entorno = env || {};
+	const opciones = {};
+
+	for (const { clave, banderas, env: nombreEnv } of OPCIONES) {
+		let valor;
+		for (let i = 0; i < argv.length; i++) {
+			const a = argv[i];
+			const conIgual = banderas.find((b) => a.startsWith(`${b}=`));
+			if (conIgual) {
+				valor = a.slice(conIgual.length + 1);
+				continue;
+			}
+			if (banderas.includes(a) && i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+				valor = argv[i + 1];
+			}
+		}
+		if (valor === undefined && entorno[nombreEnv]) valor = entorno[nombreEnv];
+		if (valor !== undefined) opciones[clave] = String(valor).trim();
+	}
+
+	return opciones;
+}
+
+// ¿Pidieron emparejar? Basta con que venga la API key: sin ella no hay nada que hacer, y
+// con ella el resto tiene valores por defecto razonables.
+function pidenEmparejar(opciones) {
+	return !!(opciones && opciones.apiKey);
+}
+
+// El nombre por defecto es el del equipo, no uno generico. En un despliegue masivo el
+// mismo comando corre en todas las maquinas: si el nombre no sale del propio equipo, el
+// tablero termina con trescientos "Unnamed Device" y hay que renombrarlos a mano, que es
+// justo el trabajo que esto viene a evitar.
+function nombrePorDefecto() {
+	try {
+		return os.hostname();
+	} catch (error) {
+		return '';
+	}
+}
+
+function usuarioPorDefecto() {
+	try {
+		return os.userInfo().username;
+	} catch (error) {
+		return '';
+	}
+}
+
+function ipsLocales() {
+	const ips = [];
+	try {
+		const interfaces = os.networkInterfaces();
+		for (const nombre of Object.keys(interfaces)) {
+			for (const iface of interfaces[nombre] || []) {
+				if (!iface.internal && iface.address) ips.push(iface.address);
+			}
+		}
+	} catch (error) {
+		/* sin red que enumerar: se manda vacio */
+	}
+	return ips;
+}
+
+// Lo que se le manda a POST /devices/enroll. Separado del envio para poder comprobarlo.
+function cuerpoDeAlta(opciones, uuid) {
+	return {
+		organizationId: opciones.orgId,
+		uuid,
+		name: opciones.deviceName || nombrePorDefecto() || uuid,
+		ownerName: opciones.userName || usuarioPorDefecto() || undefined,
+		os: process.platform,
+		localIps: JSON.stringify(ipsLocales()),
+	};
+}
+
+function urlDeAlta(opciones) {
+	const base = (opciones.apiUrl || API_URL_POR_DEFECTO).replace(/\/+$/, '');
+	return `${base}/devices/enroll`;
+}
+
+function postJson(url, headers, cuerpo) {
+	return new Promise((resolve, reject) => {
+		let destino;
+		try {
+			destino = new URL(url);
+		} catch (error) {
+			return reject(new Error(`la URL de la API no es valida: ${url}`));
+		}
+
+		const datos = Buffer.from(JSON.stringify(cuerpo), 'utf8');
+		const transporte = destino.protocol === 'http:' ? http : https;
+		const req = transporte.request(
+			destino,
+			{
+				method: 'POST',
+				headers: Object.assign(
+					{
+						'content-type': 'application/json',
+						'content-length': datos.length,
+					},
+					headers
+				),
+			},
+			(res) => {
+				const trozos = [];
+				res.on('data', (t) => trozos.push(t));
+				res.on('end', () => {
+					const texto = Buffer.concat(trozos).toString('utf8');
+					let json = null;
+					try {
+						json = JSON.parse(texto);
+					} catch (error) {
+						/* la API contesto algo que no es JSON; se conserva el texto */
+					}
+					resolve({ status: res.statusCode, json, texto });
+				});
+			}
+		);
+
+		req.setTimeout(TIMEOUT_MS, () => {
+			req.destroy(new Error(`la API no contesto en ${TIMEOUT_MS / 1000} segundos`));
+		});
+		req.on('error', reject);
+		req.end(datos);
+	});
+}
+
+// La API contesta el error dentro del JSON y `message` puede ser texto o lista (las
+// validaciones de Nest vienen en lista). Un instalador que dice "fallo con 403" y nada
+// mas obliga a abrir el codigo; se saca el motivo de donde este.
+function motivoDelError(respuesta) {
+	const m = respuesta.json && respuesta.json.message;
+	let motivo = '';
+	if (Array.isArray(m)) motivo = m.join('; ');
+	else if (typeof m === 'string') motivo = m;
+
+	// Cuando el guard rechaza la clave, Nest contesta su "Forbidden resource" generico,
+	// que no le dice nada a quien esta desplegando. El unico motivo posible aca es la
+	// clave, asi que se dice cual es.
+	if (respuesta.status === 401 || (respuesta.status === 403 && /forbidden resource/i.test(motivo))) {
+		return 'la API key no es valida o ya expiro';
+	}
+
+	if (motivo) return motivo;
+	if (respuesta.texto) return respuesta.texto.slice(0, 300);
+	return `la API contesto ${respuesta.status}`;
+}
+
+/**
+ * Da de alta el equipo y deja escrito en el archivo de usuario todo lo que la app
+ * necesita para conectarse sola en el primer arranque: el servidor y su token.
+ *
+ * `userData` entra por parametro y no por require: este archivo se carga desde el CLI,
+ * que corre tambien donde el arbol de dependencias esta a medias.
+ */
+async function emparejar(opciones, userData) {
+	if (!opciones.apiKey) throw new Error('falta la API key de la organizacion (--api-key)');
+	if (!opciones.orgId) throw new Error('falta el id de la organizacion (--org-id)');
+
+	const uuid = userData.deviceUUID();
+	const respuesta = await postJson(
+		urlDeAlta(opciones),
+		{ 'x-api-key': opciones.apiKey },
+		cuerpoDeAlta(opciones, uuid)
+	);
+
+	if (respuesta.status !== 200 && respuesta.status !== 201) {
+		throw new Error(motivoDelError(respuesta));
+	}
+
+	const datos = respuesta.json || {};
+	if (!datos.refreshToken) {
+		throw new Error('la API acepto el alta pero no devolvio token');
+	}
+
+	const server = servidorEfectivo(opciones, datos.server);
+	guardarAlta(userData, datos, server);
+
+	return {
+		uuid,
+		deviceId: datos.deviceId,
+		organizationId: datos.organizationId,
+		name: datos.name,
+		server,
+		servidorAnunciado: datos.server || '',
+		servidorForzado: !!opciones.wsUrl,
+		mismoOrigenQueLaApi: mismoOrigen(urlDeAlta(opciones), server),
+		yaEstaba: !!datos.alreadyEnrolled,
+	};
+}
+
+/**
+ * A que websocket se conecta el equipo.
+ *
+ * Normalmente lo decide la API, no el instalador: el token que acaba de emitir solo vale
+ * en SU websocket, asi que apuntar a otro sitio solo consigue un equipo dado de alta que
+ * no conecta. Por eso para hablar con otro servidor lo que se cambia es `--api-url`, y el
+ * websocket viene de vuelta solo.
+ *
+ * El override existe para el unico caso que eso no cubre: que la API anuncie una
+ * direccion a la que el equipo no llega —una IP de LAN detras de un NAT, un proxy inverso
+ * publicado con otro nombre, DNS partido—. Ahi el alta sale bien y los trescientos
+ * equipos guardan una URL muerta, sin ninguna senal en el momento de instalar. Lo
+ * correcto es arreglar WEBSOCKET_URL en la API; esto es la salida cuando no se puede.
+ */
+function servidorEfectivo(opciones, servidorDeLaApi) {
+	const forzado = (opciones.wsUrl || '').trim();
+	if (forzado) {
+		if (!/^wss?:\/\//i.test(forzado)) {
+			throw new Error(`--ws-url tiene que empezar por ws:// o wss:// (llego "${forzado}")`);
+		}
+		return forzado;
+	}
+	if (!servidorDeLaApi) {
+		throw new Error(
+			'la API no devolvio websocket (le falta WEBSOCKET_URL); se puede forzar con --ws-url'
+		);
+	}
+	return servidorDeLaApi;
+}
+
+// El cliente saca el origen HTTP de la API a partir de esta misma URL de websocket
+// (cambiandole el esquema), asi que cuando el host no coincide con el de --api-url hay
+// algo raro y conviene decirlo. No es un error: un despliegue puede separarlos a
+// proposito.
+function mismoOrigen(urlApi, urlWebsocket) {
+	try {
+		return new URL(urlApi).host === new URL(urlWebsocket).host;
+	} catch (error) {
+		return true; // si no se puede comparar, no se avisa de nada
+	}
+}
+
+// Se escribe exactamente lo mismo que dejaba el emparejamiento por keycode, y por las
+// mismas claves: para la app las dos altas son indistinguibles, asi que no hay un segundo
+// camino de conexion que mantener.
+function guardarAlta(userData, datos, servidor) {
+	// El servidor va aparte del resto de la respuesta porque puede venir forzado desde la
+	// linea de comandos. Y tiene que ser EL MISMO en las tres claves: la app busca el
+	// token por la URL con la que se conecta, asi que guardarlo bajo otra lo deja
+	// arrancando y sin sesion, que es un fallo mudo.
+	const server = servidor || datos.server;
+
+	const servers = userData.get('servers');
+	const lista = Array.isArray(servers) ? servers.slice() : [];
+	if (!lista.includes(server)) lista.push(server);
+	userData.set('servers', lista);
+
+	userData.set('refreshTokens', server, datos.refreshToken);
+	if (datos.refreshTokenHash) {
+		userData.set('refreshTokenHashes', server, datos.refreshTokenHash);
+	}
+
+	// El token de acceso viejo pertenece al alta anterior: si se queda, la app intenta
+	// conectarse con el antes que con el refresh nuevo y le rebota.
+	const accessTokens = userData.get('accessTokens');
+	if (accessTokens && typeof accessTokens === 'object' && accessTokens[server]) {
+		userData.remove('accessTokens', server);
+	}
+}
+
+// Todas las banderas de emparejamiento llevan valor. El CLI lo necesita para no
+// confundir ese valor con un argumento suelto: `install --org-id 55` no instala la
+// version "55".
+const BANDERAS_CON_VALOR = OPCIONES.reduce((todas, o) => todas.concat(o.banderas), []);
+
+// El primer argumento suelto, saltando banderas y los valores que se llevan. Sin esto,
+// `glassnote install --api-key abc` intentaba instalar la version "abc".
+function argumentoPosicional(args) {
+	const argv = Array.isArray(args) ? args : [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a.startsWith('-')) {
+			if (BANDERAS_CON_VALOR.includes(a)) i++; // el valor va aparte, se salta
+			continue;
+		}
+		return a;
+	}
+	return undefined;
+}
+
+module.exports = {
+	API_URL_POR_DEFECTO,
+	BANDERAS_CON_VALOR,
+	argumentoPosicional,
+	OPCIONES,
+	leerOpciones,
+	pidenEmparejar,
+	cuerpoDeAlta,
+	urlDeAlta,
+	motivoDelError,
+	guardarAlta,
+	servidorEfectivo,
+	mismoOrigen,
+	emparejar,
+	nombrePorDefecto,
+	usuarioPorDefecto,
+	ipsLocales,
+};