@designerbyron/lifecode-rag 0.0.0-stage → 1.1.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.
Files changed (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +220 -2
  3. package/bin/lifecode-rag.mjs +449 -0
  4. package/client.js +3515 -0
  5. package/cordis.patch.yml +3 -0
  6. package/docs/ARCHITECTURE-v0.2.md +269 -0
  7. package/docs/AUTO-DISCOVERY.md +111 -0
  8. package/docs/AUTOMATION-POLICIES.md +232 -0
  9. package/docs/CONTRATO-v0.1.md +195 -0
  10. package/docs/EMBEDDING-PROVIDERS.md +105 -0
  11. package/docs/OBSERVABILITY.md +241 -0
  12. package/docs/PA-UI-0-API-CONTRACT.md +887 -0
  13. package/docs/PERFORMANCE-BUDGETS.md +118 -0
  14. package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
  15. package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
  16. package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
  17. package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
  18. package/docs/WORKSPACE-API.md +239 -0
  19. package/icon.svg +7 -0
  20. package/index.js +198 -0
  21. package/lib/audit-export.mjs +70 -0
  22. package/lib/audit.mjs +120 -0
  23. package/lib/auto-context.mjs +322 -0
  24. package/lib/automation.mjs +214 -0
  25. package/lib/chunk.mjs +100 -0
  26. package/lib/config-resolve.mjs +119 -0
  27. package/lib/context.mjs +150 -0
  28. package/lib/conversation-events.mjs +145 -0
  29. package/lib/db.mjs +309 -0
  30. package/lib/diagnose.mjs +197 -0
  31. package/lib/discovery.mjs +402 -0
  32. package/lib/doctor.mjs +82 -0
  33. package/lib/embed.mjs +96 -0
  34. package/lib/embedders.mjs +103 -0
  35. package/lib/errors.mjs +231 -0
  36. package/lib/exec-context.mjs +238 -0
  37. package/lib/extract.mjs +260 -0
  38. package/lib/harness-workspaces.mjs +85 -0
  39. package/lib/hash.mjs +34 -0
  40. package/lib/ingest.mjs +239 -0
  41. package/lib/inputs.mjs +67 -0
  42. package/lib/library-state.mjs +252 -0
  43. package/lib/maintenance.mjs +113 -0
  44. package/lib/metrics.mjs +164 -0
  45. package/lib/migrate.mjs +373 -0
  46. package/lib/operations.mjs +132 -0
  47. package/lib/pa-api.mjs +946 -0
  48. package/lib/paths.mjs +345 -0
  49. package/lib/policy.mjs +125 -0
  50. package/lib/profile.mjs +128 -0
  51. package/lib/readmodel.mjs +159 -0
  52. package/lib/recovery.mjs +557 -0
  53. package/lib/registry-schema.mjs +206 -0
  54. package/lib/registry.mjs +606 -0
  55. package/lib/resolve.mjs +318 -0
  56. package/lib/retention.mjs +143 -0
  57. package/lib/revocation.mjs +124 -0
  58. package/lib/roots-structure.mjs +224 -0
  59. package/lib/schema.mjs +173 -0
  60. package/lib/scope-ops.mjs +379 -0
  61. package/lib/scope-stores.mjs +128 -0
  62. package/lib/search.mjs +345 -0
  63. package/lib/selection.mjs +225 -0
  64. package/lib/server.mjs +340 -0
  65. package/lib/session-identity.mjs +51 -0
  66. package/lib/sessions.mjs +343 -0
  67. package/lib/sync-scheduler.mjs +354 -0
  68. package/lib/sync.mjs +755 -0
  69. package/lib/tags.mjs +45 -0
  70. package/lib/tools.mjs +364 -0
  71. package/lib/trusted-roots.mjs +149 -0
  72. package/lib/worker-context.mjs +22 -0
  73. package/package.json +67 -5
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Byron Vanegas
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,221 @@
1
- # Temporary Holding Version
1
+ # LifeCode RAG
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Plugin independiente de recuperación aumentada para DeepSeek Harness. Indexa conocimiento local
4
+ (proyectos, documentación, decisiones) en almacenes **propios** —uno por ámbito— y lo devuelve al modelo en
5
+ fragmentos compactos, citables y con presupuesto de tokens.
6
+
7
+ No depende de `@deepseek-ai/*`, no usa el almacén del Skill Center y no comparte rutas privadas con él.
8
+
9
+ **Paquete:** `@designerbyron/lifecode-rag` · **versión 1.1.0** · contrato público de herramientas
10
+ **v0.1.0** (congelado) · API del panel `pa/1.3.0`.
11
+
12
+ Identificadores internos que **no** cambian con el nombre del paquete: id del plugin `lifecode-rag`,
13
+ herramientas `lifecode_rag_*` y rutas `/lifecode-rag/pa/*`.
14
+
15
+ **Requisitos:** Node.js ≥ 22.5 (usa `node:sqlite`) y DeepSeek Harness ≥ 0.2.2-rc.3 y < 0.3.0.
16
+
17
+ ## Modelo Project-Aware
18
+
19
+ - **Perfil** → un registro `registry.sqlite3` con proyectos, bibliotecas, raíces autorizadas, grants,
20
+ selecciones de sesión, operaciones y auditoría encadenada.
21
+ - **Ámbito** (`prj_…` proyecto, `lib_…` biblioteca) → su propio almacén `scopes/<id>/rag.sqlite3`.
22
+ - **Sesión** → selecciona un proyecto (explícita o por directorio de trabajo). Máximo **8 ámbitos**
23
+ (1 proyecto + 7 bibliotecas) por selección.
24
+ - **Autorización** → se comprueba antes de abrir cada almacén y se revalida en puntos de control antes de
25
+ devolver resultados. Si se revoca un grant a mitad de una operación, la operación **falla en cerrado**
26
+ (`grant-revoked`) y no entrega contenido del ámbito revocado.
27
+ - **Ausencia ≠ vacío** → un almacén ausente o corrupto se declara y no se crea ni se sobrescribe solo.
28
+
29
+ Rutas por perfil (`<profile_root>` = `$DSH_HOME/lifecode-rag/profiles/<profile>`):
30
+
31
+ | Ruta | Contenido |
32
+ |---|---|
33
+ | `<profile_root>/registry.sqlite3` | registro Project-Aware del perfil |
34
+ | `<profile_root>/scopes/<scope_id>/rag.sqlite3` | almacén de un proyecto o biblioteca |
35
+ | `<profile_root>/config.json` | configuración efectiva (opcional; si falta se usan los valores por defecto sin escribir) |
36
+
37
+ El almacén **heredado v0.2** (`$DSH_HOME/lifecode-rag/rag.sqlite3`, o `LIFECODE_RAG_ROOT`) sigue
38
+ funcionando para quien ya lo tenga; el panel lateral sigue sirviendo ese almacén.
39
+
40
+ ## Herramientas (contrato v0.1.0)
41
+
42
+ | Herramienta | Qué hace | Aprobación |
43
+ |---|---|---|
44
+ | `lifecode_rag_ingest` | Indexa ficheros o directorios de texto | Sólo si la ruta está fuera del proyecto |
45
+ | `lifecode_rag_search` | Búsqueda híbrida (FTS + vectores) | No |
46
+ | `lifecode_rag_context` | Contexto con MMR, presupuesto y citas | No |
47
+ | `lifecode_rag_get` | Lee una fuente y sus fragmentos | No |
48
+ | `lifecode_rag_list` | Lista fuentes | No |
49
+ | `lifecode_rag_forget` | Elimina una fuente | Siempre |
50
+ | `lifecode_rag_reindex` | Reconstruye el índice | Siempre |
51
+
52
+ Ninguna herramienta acepta `project_id`, `scope_id` ni `session_id`: la selección es humana y vive en la
53
+ sesión, no en el prompt.
54
+
55
+ ## Instalación
56
+
57
+ Instalación desde el registro público, en el directorio del perfil de DSH:
58
+
59
+ ```sh
60
+ npm install @designerbyron/lifecode-rag@1.0.0
61
+ ```
62
+
63
+ `package.json` del perfil:
64
+
65
+ ```json
66
+ {
67
+ "dependencies": { "@designerbyron/lifecode-rag": "1.0.0" },
68
+ "dsh": { "profile": { "bundles": ["lifecode-rag"] } }
69
+ }
70
+ ```
71
+
72
+ Reinicia DeepSeek Harness: el plugin carga su `cordis.patch.yml`, registra las siete herramientas y monta
73
+ el panel lateral **LifeCode RAG**.
74
+
75
+ Para desarrollo se puede enlazar un checkout en lugar de instalar:
76
+
77
+ ```sh
78
+ dsh plugin --profile <perfil> add "link:C:/ruta/al/checkout" --offline
79
+ ```
80
+
81
+ Tras cambiar el código del plugin, basta recargarlo con el gestor de plugins (desactivar y activar) o
82
+ reiniciar la aplicación; no hace falta reinstalar.
83
+
84
+ ## Primer proyecto
85
+
86
+ El registro del perfil se inicializa con `--create` (sin ese indicador la CLI **no** inventa un perfil):
87
+
88
+ ```sh
89
+ # 1. Crear el proyecto (imprime el prj_…)
90
+ node bin/lifecode-rag.mjs project create --name "Mi proyecto" --create
91
+
92
+ # 2. Autorizar la carpeta de documentos como raíz del proyecto
93
+ node bin/lifecode-rag.mjs root add --project prj_… --path "C:/ruta/a/mi/proyecto"
94
+
95
+ # 3. (Opcional) Fijar la selección de una sesión concreta; sin selección, el proyecto
96
+ # se resuelve por el directorio de trabajo de la sesión contra las raíces autorizadas
97
+ node bin/lifecode-rag.mjs select --session <session-id> --project prj_…
98
+
99
+ # Comprobación
100
+ node bin/lifecode-rag.mjs project list
101
+ node bin/lifecode-rag.mjs root list
102
+ node bin/lifecode-rag.mjs session show --session <session-id>
103
+ ```
104
+
105
+ Desde ese momento el agente usa las siete herramientas con datos reales: `ingest` sobre esa carpeta,
106
+ `search`, `context`, `get`, `list`, y `forget`/`reindex` con aprobación.
107
+
108
+ ## Administración de proyectos
109
+
110
+ Desde la 1.1.0 los proyectos se administran de forma explícita: crear, renombrar, archivar, restaurar y
111
+ gestionar sus raíces. Desaparece el registro automático —resolver un directorio ya **no** crea un
112
+ proyecto—, de modo que un candidato y un proyecto registrado nunca se confunden.
113
+
114
+ ```sh
115
+ node bin/lifecode-rag.mjs project create --name "Mi proyecto" --create
116
+ node bin/lifecode-rag.mjs project list
117
+ node bin/lifecode-rag.mjs root add --project prj_… --path "C:/ruta"
118
+ node bin/lifecode-rag.mjs root list
119
+ node bin/lifecode-rag.mjs discover scan --path "C:/workspace" # sólo lee
120
+ node bin/lifecode-rag.mjs discover register --path "C:/workspace/app"
121
+ ```
122
+
123
+ Cuando el agente resuelve un proyecto que no está registrado, devuelve `scope-unresolved` con
124
+ `action: register-project` y el comando exacto que hay que ejecutar. Nada se registra solo.
125
+
126
+ El panel añade dos secciones —**Proyectos** y **Candidatos**—. Cubre las mismas operaciones, más la
127
+ retirada de una raíz concreta, que hoy sólo está en el panel y en la API. El descubrimiento sólo corre
128
+ cuando se pide, y registrar es un botón que pulsa una persona. Archivar es lógico: el almacén y las
129
+ fuentes se conservan y el proyecto se puede restaurar.
130
+
131
+ Rutas de administración (`pa/1.3.0`): `POST|PATCH /pa/projects`, `POST /pa/projects/archive`,
132
+ `POST /pa/projects/restore`, `POST /pa/roots`, `POST /pa/roots/remove`, `GET /pa/candidates`,
133
+ `POST /pa/projects/register`. Todas exigen la compuerta del host: sin credencial responden `401` y sin
134
+ servicio de conexión `503`. **No existe ninguna ruta que borre proyectos, raíces, archivos o almacenes.**
135
+
136
+ ## Diagnóstico
137
+
138
+ ```sh
139
+ node bin/lifecode-rag.mjs diagnose # perfil, registro, almacenes, sincronización y auditoría
140
+ node bin/lifecode-rag.mjs diagnose --json # lo mismo, para scripts
141
+ node bin/lifecode-rag.mjs doctor # runtime, configuración y almacén heredado
142
+ node bin/lifecode-rag.mjs library status # estado de los almacenes por ámbito
143
+ node bin/lifecode-rag.mjs sync status # filas de sincronización por ámbito
144
+ node bin/lifecode-rag.mjs sync report # últimas pasadas y ticks auditados
145
+ ```
146
+
147
+ Todo el diagnóstico es de **sólo lectura**: no repara, no crea y no migra nada.
148
+
149
+ ## Sincronización
150
+
151
+ Manual por defecto: `sync run [--scope <id>] [--dry-run] [--limit n]`. La sincronización periódica está
152
+ **desactivada** (`automation.enabled=false`) y, cuando se activa, corre con presupuesto por tick
153
+ (`tickBudgetMs`, 2 000 ms por defecto) y límite de ficheros (`maxFilesPerRun`, 25). Nunca borra fuentes:
154
+ una desaparición se marca `missing` y se revierte si el fichero vuelve con el mismo hash. Los secretos
155
+ evidentes (`.env`, claves, `.pem`, `secrets.json`…) se excluyen por nombre.
156
+
157
+ ## Contexto automático
158
+
159
+ Desactivado por defecto (`autoContext.enabled=false`). Si se activa, el hook `agent/pre-step` añade un
160
+ mensaje con contexto recuperado, sólo en el primer paso de un turno con prompt humano, con presupuesto de
161
+ tiempo (2 000 ms), sin egreso de red y sin compartir estado entre sesiones.
162
+
163
+ ## Modos del panel: REAL y DEMO
164
+
165
+ - **REAL** (`Modo de datos: api`) — el panel lee `/lifecode-rag/pa/*` del host. Toda cifra mostrada sale
166
+ del almacén del perfil. Si la API no responde, el panel **no inventa**: pasa a DEMO y lo dice.
167
+ - **DEMO** (`Modo de datos: demo`) — fixtures sintéticos, marcados como tales en la cabecera; nunca
168
+ muestra datos del proyecto real ni cifras del almacén.
169
+ - Las escrituras (ingesta, olvido, reindexación) **no** se ejecutan desde el panel: la API responde `403`
170
+ y remite a las herramientas, que pasan por la aprobación del host.
171
+
172
+ ## Seguridad
173
+
174
+ - La autorización no se cachea: cada apertura y cada punto de control releen el registro.
175
+ - `forget` y `reindex` exigen aprobación humana; una aprobación denegada o no disponible falla en cerrado.
176
+ - Enlaces duros, enlaces simbólicos y rutas fuera de las raíces autorizadas se rechazan al registrar y al
177
+ ingerir.
178
+ - La ingesta es atómica por fichero: si falla la sustitución, la versión anterior queda intacta.
179
+ - Las auditorías (registro y almacén) son cadenas SHA-256 verificables; se comprueban al abrir y en el
180
+ diagnóstico.
181
+
182
+ ## Pruebas
183
+
184
+ ```sh
185
+ npm test # node --test --test-concurrency=1
186
+ npm run test:hermetic # la suite + huella del almacén real antes y después
187
+ npm run check # estructura, cero dependencias, red acotada
188
+ ```
189
+
190
+ Las pruebas y las herramientas de desarrollo viven en el repositorio, no en el paquete publicado
191
+ (`files` excluye `tests/` y `tools/`). La suite de la 1.1.0 tiene **475 casos** y cubre las siete
192
+ herramientas, la administración por API, la interfaz y los 54 códigos de error con su mapa HTTP.
193
+
194
+ ## Documentación
195
+
196
+ - [`docs/PROJECT-AWARE-ARCHITECTURE.md`](docs/PROJECT-AWARE-ARCHITECTURE.md) — arquitectura y decisiones.
197
+ - [`docs/PROJECT-AWARE-DATA-CONTRACT.md`](docs/PROJECT-AWARE-DATA-CONTRACT.md) — esquema y rutas.
198
+ - [`docs/PROJECT-AWARE-SESSION-CONTRACT.md`](docs/PROJECT-AWARE-SESSION-CONTRACT.md) — sesión y selección.
199
+ - [`docs/PROJECT-AWARE-ERROR-CONTRACT.md`](docs/PROJECT-AWARE-ERROR-CONTRACT.md) — códigos y semántica.
200
+ - [`docs/CONTRATO-v0.1.md`](docs/CONTRATO-v0.1.md) — contrato público de las siete herramientas.
201
+ - [`docs/PA-UI-0-API-CONTRACT.md`](docs/PA-UI-0-API-CONTRACT.md) — contrato de la API del panel.
202
+ - [`docs/AUTO-DISCOVERY.md`](docs/AUTO-DISCOVERY.md) — descubrimiento automático.
203
+ - [`docs/AUTOMATION-POLICIES.md`](docs/AUTOMATION-POLICIES.md) — sincronización y presupuesto.
204
+ - [`docs/EMBEDDING-PROVIDERS.md`](docs/EMBEDDING-PROVIDERS.md) — proveedores de embeddings.
205
+ - [`docs/OBSERVABILITY.md`](docs/OBSERVABILITY.md) — métricas y trazas.
206
+ - [`docs/PERFORMANCE-BUDGETS.md`](docs/PERFORMANCE-BUDGETS.md) — presupuestos medidos.
207
+ - [`docs/WORKSPACE-API.md`](docs/WORKSPACE-API.md) — API del espacio de trabajo.
208
+ - [`docs/ARCHITECTURE-v0.2.md`](docs/ARCHITECTURE-v0.2.md) — arquitectura del almacén heredado.
209
+
210
+ La evidencia de cada acto de ingeniería (planes K1, auditorías `eval/`, matrices de aceptación) vive en
211
+ el repositorio de desarrollo y **no** se distribuye en el paquete.
212
+
213
+ ## Licencia
214
+
215
+ **MIT** — Copyright (c) 2026 Byron Vanegas.
216
+
217
+ Se concede permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y de
218
+ sus ficheros de documentación, para usarlo, copiarlo, modificarlo, fusionarlo, publicarlo, distribuirlo,
219
+ sublicenciarlo y/o vender copias, con la única condición de incluir este aviso de copyright y esta
220
+ licencia en todas las copias o partes sustanciales del software. El software se entrega «tal cual», sin
221
+ garantía de ningún tipo. Texto completo en [`LICENSE`](LICENSE).