opencode-flema-engram-sidebar 0.1.8 → 0.3.0

package/README.md

@@ -1,20 +1,20 @@
-# Flema Engram para OpenCode
+# Flema Engram para OpenCode y Pi
 
 [![CI](https://github.com/oniricosistemas/flema-engram/actions/workflows/ci.yml/badge.svg)](https://github.com/oniricosistemas/flema-engram/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/opencode-flema-engram-sidebar?logo=npm)](https://www.npmjs.com/package/opencode-flema-engram-sidebar)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/github/license/oniricosistemas/flema-engram)](https://github.com/oniricosistemas/flema-engram/blob/main/LICENSE)
 
-Un sidebar local y de solo lectura que mantiene visible el contexto reciente de
-[Engram](https://github.com/Gentleman-Programming/engram) mientras trabajás dentro de OpenCode.
+Una integración local y de solo lectura que mantiene visible el contexto reciente de
+[Engram](https://github.com/Gentleman-Programming/engram) mientras trabajás dentro de OpenCode o Pi/Gentle Shell.
 
 La canción **“Y aún yo te recuerdo”** inspiró artísticamente la idea central: que la
 última memoria guardada siga presente en el contexto de desarrollo. Esta referencia
 es un homenaje a esa inspiración; no implica afiliación, patrocinio ni titularidad
 sobre la obra.
 
-> **English summary:** Flema Engram is a local-first, read-only OpenCode
-> plugin/sidebar that surfaces Engram health, project context, recent memories,
+> **English summary:** Flema Engram is a local-first, read-only OpenCode and Pi
+> integration that surfaces Engram health, project context, recent memories,
 > blockers, and ODD task progress by default. An MCP stdio adapter is included only as an optional
 > integration path.
 
@@ -36,18 +36,58 @@ Configuración mínima:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["opencode-flema-engram-sidebar"]
+  "plugin": ["opencode-flema-engram-sidebar@0.3.0"]
 }
 ```
 
-> Puedes encontrar la ruta completa de tu archivo `tui.json` ejecutando `opencode debug tui-path`.
+Fijá una versión exacta. OpenCode 1.18.x conserva paquetes npm en caché y una entrada
+sin versión o con `@latest` puede seguir resolviendo una release anterior después de
+que npm publique otra. El plugin no puede actualizarse a sí mismo porque OpenCode lo
+resuelve e importa antes de ejecutar su código.
 
-Una vez guardado el archivo, reinicia OpenCode para que el plugin se cargue.
+Para ubicar el archivo global, ejecutá `opencode debug paths` y abrí `tui.json` dentro
+de la ruta `config`. Una vez guardado, cerrá completamente OpenCode y abrí un proceso
+nuevo para que el plugin se cargue.
+
+#### Diagnosticar y actualizar una instalación
+
+La CLI de mantenimiento consulta las rutas que informa OpenCode, inspecciona la
+configuración y compara los wrappers de caché con npm sin mostrar opciones del plugin:
+
+```sh
+npx --yes --package opencode-flema-engram-sidebar@latest flema-engram doctor
+```
+
+Previsualizá siempre la actualización. `--dry-run` no cambia archivos:
+
+```sh
+npx --yes --package opencode-flema-engram-sidebar@latest \
+  flema-engram update --dry-run
+```
+
+Luego cerrá OpenCode y aplicá el mismo plan:
+
+```sh
+npx --yes --package opencode-flema-engram-sidebar@latest \
+  flema-engram update
+```
+
+La CLI pide una confirmación, respalda `tui.json`, invoca el instalador oficial con
+la versión npm exacta y un límite de 60 segundos, elimina solamente wrappers obsoletos
+que conservan el mismo manifiesto observado en el preview y verifica el resultado. Si
+el instalador agota ese límite, la CLI lo detiene por la fuerza e informa la ruta
+exacta del backup retenido. Para automatización
+controlada, `flema-engram update --yes` omite únicamente la pregunta: conserva el
+preview, las validaciones y el backup. `--json` produce una salida estructurada.
+
+OpenCode 1.18.x no actualiza confiablemente una entrada sin versión o con `@latest`.
+OpenCode 2 dispone además de `opencode plugin check` y `opencode plugin update`; la
+CLI usa la sintaxis nativa correspondiente a la versión detectada.
 
 #### Usando `opencode attach`
 Si vas a conectarte a una instancia remota de OpenCode mediante `opencode attach <url>`, el plugin funcionará siempre que:
 - El servicio Engram en la máquina remota sea accesible en el puerto 7437 (por defecto solo escucha en 127.0.0.1; se recomienda crear un puente TCP como se describe en los documentos internos o usar `engram-bridge.service`).
-- El plugin descargará automáticamente la versión más reciente desde NPM al iniciar el attach.
+- Usá una versión exacta del plugin y actualizala explícitamente; `opencode attach` puede reutilizar una copia npm ya resuelta en la caché local.
 - La detección automática usa el host recibido por `opencode attach`; si el puente de Engram usa otra URL, configurá `baseUrl` explícitamente en `tui.json`.
 - Verás en el sidebar la línea `🔌 Target: Local=<host>:7437 | Cloud=<URL>` para confirmar a qué endpoints se está conectando.
 
@@ -56,18 +96,53 @@ Si vas a conectarte a una instancia remota de OpenCode mediante `opencode attach
 El sidebar hace una carga inicial, vuelve a consultar cada 30 segundos de forma
 predeterminada y permite refrescar manualmente con <kbd>Alt</kbd>+<kbd>R</kbd>.
 
+## Viewer para Pi / Gentle Shell
+
+El mismo paquete incluye una extensión Pi de solo lectura. Instalá una versión exacta
+compatible con esta documentación:
+
+```sh
+pi install npm:opencode-flema-engram-sidebar@0.3.0
+```
+
+La extensión publica un status breve y un widget compacto debajo del editor. Refresca
+al iniciar, reanudar o recargar una sesión, después de que `mem_save` (o el alias
+`save_memory`) termina correctamente y mediante el comando:
+
+```text
+/engram-refresh
+```
+
+No usa polling periódico y no agrega herramientas para escribir memorias. En modos
+sin UI no consulta Engram ni intenta renderizar componentes terminales. En RPC usa
+solamente status y widgets de líneas de texto, sin iniciar una segunda TUI.
+
+La resolución del endpoint usa `ENGRAM_URL`, luego `ENGRAM_BASE_URL` y finalmente
+`http://127.0.0.1:7437`. `ENGRAM_PROJECT` puede fijar el candidato de proyecto; de lo
+contrario se valida el nombre del directorio actual contra Engram. Los fallos de
+inicialización se contienen en un estado `Engram unavailable` sin mostrar URLs,
+tokens ni diagnósticos con credenciales.
+
+Para desarrollo local, después de compilar el paquete:
+
+```sh
+npm run build
+pi --extension ./dist/pi.js
+```
+
 ## Qué es — y qué no es
 
 | Sí es | No es |
 | --- | --- |
-| Un plugin para el slot `sidebar_content` de OpenCode | Una TUI independiente |
+| Un plugin para `sidebar_content` de OpenCode y una extensión Pi | Una TUI independiente |
 | Una vista local y de solo lectura sobre Engram | Un reemplazo de Engram |
 | Project context, activity, and ODD task progress | A memory editor or manager |
 | Un cliente del HTTP local de Engram | Un servicio cloud o de sincronización |
 | Un paquete con un adaptador MCP stdio opcional | Un producto centrado en MCP |
 
-El sidebar es el producto principal. El comando MCP existe para integraciones
-avanzadas y puede ignorarse por completo al usar el plugin de OpenCode.
+Los viewers de OpenCode y Pi son las integraciones visuales principales. El comando
+MCP existe para integraciones avanzadas y puede ignorarse por completo al usar cualquiera
+de los viewers.
 
 ## Cómo funciona
 
@@ -108,7 +183,7 @@ Usá la forma `[plugin, options]` solamente cuando necesites opciones:
   "$schema": "https://opencode.ai/tui.json",
   "plugin": [
     [
-      "opencode-flema-engram-sidebar",
+      "opencode-flema-engram-sidebar@0.3.0",
       {
         "enabled": true,
         "project": "mi-proyecto",
@@ -263,7 +338,7 @@ Si Engram conoce `mi-proyecto`, el sidebar valida ese nombre y carga sus memoria
 {
   "$schema": "https://opencode.ai/tui.json",
   "plugin": [
-    ["opencode-flema-engram-sidebar", { "project": "backend-api" }]
+    ["opencode-flema-engram-sidebar@0.3.0", { "project": "backend-api" }]
   ]
 }
 ```
@@ -277,7 +352,7 @@ Engram. El valor debe coincidir; una configuración incorrecta queda como `unres
 {
   "$schema": "https://opencode.ai/tui.json",
   "plugin": [
-    ["opencode-flema-engram-sidebar", { "pollInterval": 60000 }]
+    ["opencode-flema-engram-sidebar@0.3.0", { "pollInterval": 60000 }]
   ]
 }
 ```
@@ -358,11 +433,57 @@ Preservá el resto de tus plugins y opciones al fusionar la configuración.
 - Cerrá y reiniciá OpenCode después de cambiar `tui.json`.
 - Validá el JSON y la ruta del plugin.
 - Confirmá Node.js 22+ y OpenCode 1.18.25+.
-- Para npm, usá el nombre exacto `opencode-flema-engram-sidebar`.
+- Para npm, usá `opencode-flema-engram-sidebar@<version>` con una versión publicada exacta.
 - Para fuente local, ejecutá `npm install` y comprobá que la ruta termine en
   `src/sidebar/plugin.tsx`.
 - Revisá la salida de arranque de OpenCode. El plugin no crea archivos de log propios.
 
+### El sidebar muestra una versión anterior
+
+1. Cerrá todos los procesos OpenCode.
+2. Ejecutá `opencode debug paths` y anotá las rutas `config` y `cache`.
+3. Confirmá que `config/tui.json` use `opencode-flema-engram-sidebar@<version>`.
+4. Instalá de nuevo esa versión exacta:
+
+   ```sh
+   opencode plugin opencode-flema-engram-sidebar@<version> --force --global
+   ```
+
+5. Si el sidebar todavía muestra la release anterior, inspeccioná dentro de
+   `cache/packages` los wrappers `opencode-flema-engram-sidebar@*`. Eliminá solamente
+   el wrapper obsoleto `opencode-flema-engram-sidebar@latest` después de confirmar que
+   su `node_modules/opencode-flema-engram-sidebar/package.json` contiene la versión
+   vieja. Conservá el wrapper exacto y repetí el comando anterior.
+6. Abrí un proceso OpenCode nuevo; los procesos existentes no recargan plugins.
+
+En PowerShell, reemplazá `<old-version>` por la versión anterior que esperás borrar.
+El comando se niega a eliminar el wrapper si su manifiesto contiene otro valor:
+
+```powershell
+$cache = (opencode debug paths | Select-String '^cache\s+').Line -replace '^cache\s+', ''
+$stale = Join-Path $cache 'packages\opencode-flema-engram-sidebar@latest'
+$manifest = Join-Path $stale 'node_modules\opencode-flema-engram-sidebar\package.json'
+$staleVersion = (Get-Content -LiteralPath $manifest -Raw | ConvertFrom-Json).version
+if ($staleVersion -ne '<old-version>') { throw "Refusing to remove wrapper: found $staleVersion" }
+Remove-Item -LiteralPath $stale -Recurse -Force
+```
+
+En shells POSIX, reemplazá `<cache>` y `<old-version>` por los valores confirmados:
+
+```sh
+stale='<cache>/packages/opencode-flema-engram-sidebar@latest'
+manifest="$stale/node_modules/opencode-flema-engram-sidebar/package.json"
+stale_version="$(node -e 'const fs = require("node:fs"); console.log(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).version)' "$manifest")"
+[ "$stale_version" = '<old-version>' ] || {
+  printf 'Refusing to remove wrapper: found %s\n' "$stale_version" >&2
+  exit 1
+}
+rm -rf -- "$stale"
+```
+
+No borres el directorio completo de caché: puede contener otros plugins, servidores de
+lenguaje y modelos descargados.
+
 ### OpenCode no encuentra el export del paquete
 
 - Confirmá que la versión instalada tiene un export raíz por defecto con `id` y `tui`.

package/dist/core.d.ts

@@ -0,0 +1,4 @@
+export * from "./adapters/types.js";
+export * from "./viewer/core.js";
+export { resolveProject, resolveProjectName, type ProjectResolution, type ProjectResolutionOptions, type ProjectValidation, } from "./utils/project-resolver.js";
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,GACvB,MAAM,6BAA6B,CAAC"}

package/dist/core.js

@@ -0,0 +1,4 @@
+export * from "./adapters/types.js";
+export * from "./viewer/core.js";
+export { resolveProject, resolveProjectName, } from "./utils/project-resolver.js";
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EACL,cAAc,EACd,kBAAkB,GAInB,MAAM,6BAA6B,CAAC"}

package/dist/maintenance/cli.d.ts

@@ -0,0 +1,21 @@
+export interface MaintenanceCommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface MaintenanceCommandOptions {
+    signal?: AbortSignal;
+}
+export type MaintenanceCommandRunner = (command: string, args: string[], options?: MaintenanceCommandOptions) => Promise<MaintenanceCommandResult>;
+export interface MaintenanceCliDependencies {
+    cwd?: string;
+    runCommand?: MaintenanceCommandRunner;
+    fetchLatestVersion?: () => Promise<string>;
+    confirm?: (message: string) => Promise<boolean>;
+    now?: () => Date;
+    installerTimeoutMs?: number;
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+}
+export declare function runMaintenanceCli(argv: string[], dependencies?: MaintenanceCliDependencies): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/maintenance/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/maintenance/cli.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,yBAAyB,KAChC,OAAO,CAAC,wBAAwB,CAAC,CAAC;AAEvC,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AA6dD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,EACd,YAAY,GAAE,0BAA+B,GAC5C,OAAO,CAAC,MAAM,CAAC,CA6IjB"}