@glassnote/client 2.4.0

package/INSTALACION.md

@@ -0,0 +1,258 @@
+# Instalación del cliente GlassNote
+
+La vía oficial es **npm/npx**. Los instaladores nativos (NSIS firmado, DMG notarizado,
+tiendas) quedan **deprecados** desde 2026-09-05: el coste de certificados y validaciones
+no se justificaba para un cliente que se distribuye a clientes conocidos.
+
+```sh
+# probarlo sin instalar nada
+npx @glassnote/client
+
+# instalarlo de verdad
+npx @glassnote/client install
+```
+
+El paquete se llama `@glassnote/client`; el comando que queda instalado, `glassnote`.
+npm nombra el ejecutable por el `bin`, no por el paquete, y npx corre ese único `bin`
+aunque se llame distinto. Solo la línea de npx lleva el nombre largo.
+
+## Qué hace `install`
+
+1. `npm install -g --prefix ~/.glassnote/npm @glassnote/client@latest` — **sin root**.
+   npm baja el binario de electron (~100 MB la primera vez) en su `postinstall`.
+2. Enlaza el comando en `~/.glassnote/bin` (en Windows, los shims quedan en
+   `~/.glassnote/npm`). Ese directorio es **lo único** que se mete al `PATH`, así la
+   línea del rc no cambia aunque cambie lo de dentro.
+3. Agrega una línea idempotente en `~/.bashrc` / `~/.zshrc` (o `~/.profile` si no hay
+   ninguno) entre marcadores `# >>> glassnote >>>`. En Windows, el `PATH` de usuario, sin
+   administrador.
+4. Arranca el cliente en segundo plano. Al arrancar, la app registra el **arranque
+   automático** del usuario: acceso directo en Startup (Windows), LaunchAgent (macOS) o
+   `.desktop` en `~/.config/autostart` (Linux). Ninguno necesita permisos de admin.
+
+Todo vive bajo `~/.glassnote`. Desinstalar es borrar esa carpeta y quitar la línea del rc,
+que es justo lo que hace `glassnote uninstall`.
+
+## Comandos
+
+| | |
+|---|---|
+| `glassnote` | arranca el cliente |
+| `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 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 |
+
+Banderas de `install`: `--no-path` (no toca el rc, imprime la línea) y `--no-start`
+(instala y no arranca).
+
+`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:
+
+```sh
+npm pack
+node bin/glassnote.js install ./glassnote-client-2.2.6.tgz
+```
+
+## Sin Node instalado
+
+`install.sh` y `install.ps1` consiguen un Node y delegan el resto en el propio CLI, así la
+lógica de instalación vive en un solo sitio:
+
+```sh
+curl -fsSL https://glassnote.intermark.ec/install.sh | sh          # Linux y macOS
+irm https://glassnote.intermark.ec/install.ps1 | iex               # Windows
+```
+
+Si no hay Node ≥ 20, bajan el LTS a `~/.glassnote` (unos 25 MB, sin root) y enlazan
+`node`, `npm` y `npx` en `~/.glassnote/bin` — hace falta, porque sin intérprete el
+`#!/usr/bin/env node` del comando instalado no arranca.
+
+Los sirve el sitio de `glassnote-next`, que es un export estático: los dos archivos
+viven en su `public/`, así que salen publicados con el deploy normal de la web, sin
+infraestructura aparte.
+
+El original está **acá**, al lado del CLI que invocan. Después de tocar cualquiera de
+los dos hay que copiarlos y volver a desplegar la web:
+
+```sh
+npm run sync-installers   # copia install.sh e install.ps1 a ../glassnote-next/public/
+```
+
+Editarlos directamente en `glassnote-next` deja dos versiones que se separan, y la que
+se rompe en silencio es la que descarga la gente.
+
+## Actualizaciones
+
+Instalado por npm, el cliente comprueba el registry cada 3 horas y se actualiza solo:
+
+- lee `desiredVersion` de los datos de usuario (`lastest` = seguir la última, o una
+  versión exacta y clavada); son las mismas claves que usaba el updater de S3, para no
+  romper las instalaciones que ya están en la calle;
+- lanza un ayudante desprendido, cierra la app, corre `npm install -g` y la vuelve a
+  abrir. El npm **no** se corre con la app en marcha: en Windows el `electron.exe` en uso
+  está bloqueado y npm no podría reemplazarlo.
+
+Por `npx` no se actualiza nada: la caché es efímera y npx ya baja la última versión cada
+vez. Tampoco se registra el arranque automático — apuntaría a una carpeta que se limpia
+sola.
+
+El auto-update del **renderer** (zip desde S3 a los datos de usuario) sigue igual y es
+independiente de todo esto.
+
+## macOS y Windows: por qué ya no hace falta firmar
+
+El binario de electron lo baja **npm**, no el navegador. Sin descarga por navegador no hay
+atributo de cuarentena, así que Gatekeeper no lo bloquea y no hace falta notarizar. En
+Windows no hay instalador que ejecutar, así que no hay SmartScreen que avisar.
+
+Lo que sí cambia: la app aparece como *Electron* ante el sistema (no hay bundle propio) y
+en macOS el icono del Dock es el de electron.
+
+## Linux: el sandbox de Chromium
+
+Una instalación sin root no puede dejar `chrome-sandbox` en setuid root, y Chromium
+entonces **aborta** al arrancar. El lanzador lo detecta y elige, de más a menos seguro:
+
+1. `chrome-sandbox` es setuid root → nada que añadir;
+2. hay namespaces de usuario sin privilegios → `--disable-setuid-sandbox` (sigue habiendo
+   sandbox, el de namespaces);
+3. ni eso → `--no-sandbox`, y lo dice por pantalla.
+
+Ubuntu 24.04+ cae en el caso 3 aunque el kernel soporte namespaces, porque AppArmor los
+restringe a binarios con perfil. `glassnote fix-sandbox` pide sudo una vez y deja el
+binario como Chromium lo quiere; hay que repetirlo tras cada actualización, porque npm
+reinstala el binario.
+
+Las banderas van también en la entrada de arranque automático: sin ellas fallaría al
+iniciar sesión y nadie vería el error.
+
+En Debian/Ubuntu, si faltan librerías del sistema:
+
+```sh
+sudo apt-get install -y libgtk-3-0 libnss3 libasound2 libxss1 libgbm1
+```
+
+## Probar sin publicar: registry local
+
+Publicar en npmjs es irreversible (no se puede republicar una versión), así que el
+instalador se prueba entero contra un registry local:
+
+```sh
+npm run local-registry     # Verdaccio en http://localhost:4873, imprime los pasos
+```
+
+Levanta el registry, crea un usuario descartable y escribe un `.npmrc` propio. Ese
+`.npmrc` es lo que aísla la prueba: el `~/.npmrc` real —donde está la sesión de npmjs—
+no se lee, así no hay forma de publicar sin querer en el registry de verdad. Todo lo
+que no sea `@glassnote/*` se proxea a npmjs, así que electron y el resto se resuelven
+como en producción.
+
+Con eso se prueba el ciclo completo: publicar, instalar en un `GLASSNOTE_HOME` de
+mentira, actualizar a una versión nueva y desinstalar.
+
+Dos cosas que confunden y no son fallos del paquete:
+
+- `npx @glassnote/client` **dentro de este repo** falla con «glassnote no se reconoce
+  como un comando»: npm resuelve el proyecto local, cuyo `bin` no está enlazado en su
+  propio `node_modules/.bin`. Hay que correrlo desde cualquier otra carpeta.
+- `glassnote uninstall` borra el acceso directo de arranque **real** de la máquina, no
+  el del sandbox: el autoarranque no depende de `GLASSNOTE_HOME`. Se vuelve a crear al
+  abrir el cliente.
+
+## Publicar una versión
+
+```sh
+npm version patch          # o minor / major
+npm publish                # prepublishOnly construye el renderer y corre las comprobaciones
+```
+
+`scripts/check-publish.js` para la publicación si falta el renderer construido, si falta
+algún icono de bandeja, o si se coló algo que no debe salir (certificados, llaves,
+instaladores).
+
+Y para lo irreversible hay un candado aparte: publicar en **npmjs** exige decirlo,
+porque una versión que llegó ahí no se reemplaza ni se vuelve atrás.
+
+```sh
+GLASSNOTE_PUBLISH=PRODUCTION npm publish
+```
+
+Contra cualquier otro registry —el local— no pide nada: probar tiene que ser barato y
+publicar en serio, deliberado. No hay ambiente intermedio: se prueba local y de ahí va a
+producción.
+
+`.npmignore` existe para **anular** `.gitignore` al empaquetar: `.gitignore` excluye
+`dist`, que es justo el renderer construido. Sin él se publicaría un paquete sin app, y
+solo se notaría al abrirlo.
+
+### Publicar desde GitHub Actions
+
+`.github/workflows/publish-npm.yml` publica sin depender de la máquina de nadie. No se
+dispara por push a una rama —eso convertiría cualquier merge en una release— sino a mano
+(**Run workflow**, con dry-run disponible) o pusheando un tag:
+
+```sh
+npm version patch        # crea el commit y el tag vX.Y.Z
+git push --follow-tags
+```
+
+El workflow verifica que el tag coincida con la versión del `package.json` antes de
+publicar: un tag que dice otra cosa deja el repo mintiendo sobre lo que hay en npm.
+
+Hace falta un solo secret en el repo (o en el environment `PRODUCTION`):
+
+| secret | qué es |
+|---|---|
+| `NPM_TOKEN` | token **granular** de npm con *Bypass 2FA*, escritura sobre `@glassnote/*`. Sin el bypass npm rechaza con 403: la cuenta tiene 2FA en escrituras y un runner no puede tipear un OTP. |
+
+El mismo secret sirve en el repo del renderer, que tiene su propio workflow igual a este.
+
+Dos cosas que conviene saber:
+
+- **`workflow_dispatch` solo aparece en la UI si el archivo está en la rama por defecto**,
+  que hoy es `main` y está 42 commits atrás de `develop`. Mientras siga así, el tag es el
+  único disparador que funciona de verdad.
+- El environment `PRODUCTION` permite exigir **aprobación manual** antes de publicar
+  (*Settings > Environments > PRODUCTION > Required reviewers*). Para algo irreversible,
+  vale la pena.
+
+## El renderer: baseline y canal en caliente
+
+El renderer llega por **dos caminos distintos**, y conviene no confundirlos:
+
+| | qué es | cómo se actualiza |
+|---|---|---|
+| `@glassnote/renderer` | el **baseline**: lo que ve una instalación nueva antes de su primer update | publicando el paquete y subiendo la versión en el cliente |
+| zip en S3 → `userData/renderer` | el canal **en caliente** | subiendo el zip; llega sin republicar el cliente ni tocar el binario |
+
+`main.js` elige entre los dos comparando versiones: gana la más alta y, si empatan, gana
+userData. Por eso una versión nueva del renderer llega a todas las instalaciones sin que
+nadie reinstale nada ni vuelva a bajar electron — que es justamente el punto de tenerlo
+separado.
+
+De ahí sale una regla: **al publicar el baseline, subí S3 a la misma versión o más**. Si
+el baseline queda por encima, gana él y el canal en caliente queda mudo hasta que S3 lo
+pase.
+
+Para desarrollar el renderer, un clon en `./glassnote-renderer` **tiene precedencia** sobre
+la dependencia publicada: si no, editarlo no se vería nunca.
+
+### Orden para sacar una versión con renderer nuevo
+
+El lock es lo que se olvida y rompe el `npm ci` de CI:
+
+```sh
+# 1. en el repo del renderer
+npm version patch && git push --follow-tags       # publica @glassnote/renderer
+
+# 2. acá
+npm install @glassnote/renderer@<nueva>           # actualiza package.json Y package-lock
+git commit -am "Subir el baseline del renderer"
+npm version patch && git push --follow-tags       # publica el cliente
+```
+
+`check-publish.js` frena si el lock no tiene la dependencia, o si quedó apuntando al
+registry local después de una prueba.

package/README.md

@@ -0,0 +1,228 @@
+# GlassNote - Transparent Overlay Notes Application
+
+GlassNote is a sophisticated desktop application built with Electron that provides transparent overlay notes and interactive content display capabilities. The application runs as a system tray application with full-screen transparent windows for displaying HTML, SVG, images, and interactive forms.
+
+## Features
+
+### Core Functionality
+- **Transparent Overlay Display**: Full-screen transparent windows that overlay on top of other applications
+- **Multi-format Content Support**: HTML, SVG, images, and interactive forms
+- **Position Management**: Configurable display positions with grid-based layout system
+- **Interactive Forms**: Support for form submissions with validation and response handling
+- **Configuration Menu**: System tray accessible configuration interface
+
+### Technical Architecture
+- **Electron Main Process**: Manages window creation, system tray, auto-start, and IPC communication
+- **Vue.js Renderer**: Modern frontend built with Vue 3 and TypeScript
+- **Service Architecture**: Modular service system for sound, user data, WebSocket management, and window visibility
+- **Auto-update System**: Both main application and renderer can be updated independently
+- **Local WebSocket Server**: Built-in server for communication with external systems
+
+### Security Features
+- **Context Isolation**: Secure IPC communication with whitelisted channels
+- **Code Signing**: Windows CodeSign with eSigner and Apple Developer signing
+- **Auto-start Management**: Secure startup configuration
+- **Log Management**: Comprehensive logging with automatic cleanup
+- **User Data Encryption**: Secure storage of user preferences and configuration
+
+## Project Structure
+
+```
+glassnote-electron/
+├── main.js                    # Electron main process
+├── preload.js                 # Secure IPC bridge
+├── package.json              # Main application configuration
+├── glassnote-renderer/       # Frontend application
+│   ├── src/
+│   │   ├── App.vue           # Main Vue component
+│   │   ├── systems/          # Core systems (glass, config, etc.)
+│   │   ├── services/         # Service layer
+│   │   └── utils/            # Utility functions
+│   └── vite.config.ts        # Build configuration
+├── images/                   # Application icons and assets
+├── installer/               # Built installers
+├── cert/                    # Code signing certificates
+└── scripts/                 # Build and deployment scripts
+```
+
+## Installation
+
+**The supported way to install the client is npm/npx** (see `INSTALACION.md` for the full
+story, in Spanish):
+
+```sh
+npx @glassnote/client            # run it once, nothing gets installed
+npx @glassnote/client install    # real install under ~/.glassnote, no root, no signing
+```
+
+The package is `@glassnote/client`; the installed command is `glassnote` — npm names
+the executable after `bin`, and npx runs that single `bin` even when the names differ.
+
+```sh
+```
+
+Native installers (signed NSIS, notarized DMG, app stores) are **deprecated as of
+2026-09-05**. The certificates and store validations cost more than they were worth for a
+client shipped to known customers. `electron-builder`, `build-with-esigner.ps1` and
+`buildOSX*.sh` are kept for legacy builds only and are no longer the release path.
+
+### Development Setup
+1. Clone this repository
+2. Install dependencies — this pulls `@glassnote/renderer`, the baseline renderer:
+   ```bash
+   npm install
+   ```
+3. Only if you work **on the renderer**, clone it into this directory. A local clone
+   takes precedence over the published dependency, so `npm run watch-renderer` keeps
+   working as before:
+   ```bash
+   git clone git@intermarkec:intermarkec/glassnote-renderer.git
+   cd glassnote-renderer && npm install
+   ```
+4. Run in development mode:
+   ```bash
+   npm run dev
+   ```
+
+### Publishing a release (npm)
+```bash
+npm version patch    # or minor / major
+npm publish          # prepublishOnly builds the renderer and runs scripts/check-publish.js
+```
+
+### Production Build (deprecated — legacy native installers)
+1. Build the renderer:
+   ```bash
+   npm run build-renderer
+   ```
+2. Build the Electron application:
+   ```bash
+   npm run build
+   ```
+3. For signed Windows builds:
+   ```bash
+   .\build-with-esigner.ps1
+   ```
+
+## Configuration
+
+### Application Settings
+- **Renderer origin**: the production S3 bucket, always. Override it for local
+  testing with `GLASSNOTE_S3_BASE_URL`.
+- **Logging**: Enable/disable renderer logging via `logRenderer` flag
+- **Auto-start**: Configured automatically on first run
+- **Update Channels**: production only — there is no develop environment
+
+### Build Configuration
+- **Windows**: NSIS installer with code signing
+- **macOS**: DMG package with hardened runtime
+- **Cross-platform**: Electron Builder configuration supports multiple platforms
+
+## Usage
+
+### Basic Operation
+1. Application starts minimized to system tray
+2. Right-click tray icon for configuration menu
+3. Content is displayed via WebSocket connections or local server
+4. Interactive elements support form submissions and confirmation buttons
+
+### Content Display
+- **HTML Content**: Full HTML rendering with CSS and JavaScript support
+- **SVG Graphics**: Vector graphics with transparency support
+- **Images**: PNG, JPG, and other image formats
+- **Forms**: Interactive forms with submission handling
+
+### Position Management
+Content can be positioned using a grid system:
+- Horizontal positions: 1-3 (left, center, right)
+- Vertical positions: 1-3 (top, middle, bottom)
+
+## Development
+
+### Code Standards
+- **TypeScript**: Strict typing throughout the codebase
+- **Vue 3 Composition API**: Modern Vue patterns
+- **Service Pattern**: Modular, testable service architecture
+- **Error Handling**: Comprehensive error logging and recovery
+
+### Key Systems
+1. **Glass System**: Manages transparent overlay display
+2. **Config Menu**: System tray configuration interface
+3. **User Data Manager**: Persistent storage management
+4. **WebSocket Manager**: External communication handling
+
+### Testing
+- Development mode with hot reload
+- Comprehensive logging for debugging
+- Auto-update testing in development environment
+
+## Deployment
+
+### Build Process
+1. **Renderer Build**: Vite-based TypeScript compilation
+2. **Main Build**: Electron Builder packaging
+3. **Code Signing**: Digital signature application
+4. **Installer Creation**: NSIS (Windows) or DMG (macOS)
+
+### Update System
+- **Main Updates (npm install)**: checks the npm registry every 3 hours and updates with
+  `npm install -g`, then relaunches. npm is never run while the app is up: on Windows the
+  running `electron.exe` is locked and could not be replaced.
+- **Main Updates (legacy native)**: S3 installer download + execute (`autoupdate.js`),
+  only used by the deprecated native builds.
+- **Renderer Updates**: Independent update system for frontend (unchanged, S3 zip)
+- **Version Management**: Semantic versioning with hash verification
+
+### Distribution
+- **npm registry**: `@glassnote/client` — `npx @glassnote/client install`, no root, no
+  code signing. The installed command is still `glassnote`.
+- **Bootstrap without Node**: `install.sh` / `install.ps1` fetch Node into
+  `~/.glassnote` and hand off to the package CLI
+- **S3 Storage (legacy)**: native installers, deprecated
+- **Publishing guard**: publishing to npmjs needs `GLASSNOTE_PUBLISH=PRODUCTION`;
+  any other registry (the local one) does not
+
+## Security Considerations
+
+### Application Security
+- **Context Isolation**: Prevents renderer access to Node.js APIs
+- **IPC Whitelisting**: Only approved channels can communicate
+- **Code Signing**: Verifies application integrity
+- **Auto-start Security**: Secure startup configuration
+
+### Data Security
+- **User Data Encryption**: Secure storage of preferences
+- **Log Protection**: Automatic cleanup of sensitive data
+- **Network Security**: Secure WebSocket connections
+
+### Platform Security
+- **macOS**: with the npm install there is no notarization step — npm downloads the
+  electron binary, so nothing is quarantined by the browser and Gatekeeper does not block
+  it. Hardened runtime / Apple signing only applied to the deprecated DMG.
+- **Windows**: no installer to run means no SmartScreen prompt. eSigner code signing only
+  applied to the deprecated NSIS build.
+- **Linux sandbox**: a rootless install cannot make `chrome-sandbox` setuid root, so the
+  launcher picks the best available option (setuid → user namespaces → `--no-sandbox`)
+  and says so. `glassnote fix-sandbox` restores the full sandbox with one sudo.
+- **Sandboxing**: Limited renderer process capabilities
+
+## Troubleshooting
+
+### Common Issues
+1. **Transparency Issues**: Ensure graphics drivers are updated
+2. **Sound Not Playing**: Check system audio settings
+3. **Auto-start Failure**: Verify user permissions
+4. **Update Problems**: Check network connectivity and S3 access
+
+### Logs
+- Application logs stored in `%APPDATA%/glassnote/logs/` (Windows)
+- Automatic cleanup of logs older than 30 days
+- Detailed renderer logging available in development mode
+
+## License
+
+Proprietary software - All rights reserved.
+
+## Support
+
+For technical support and documentation, contact the development team.