@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.
- package/LICENSE +21 -0
- package/README.md +220 -2
- package/bin/lifecode-rag.mjs +449 -0
- package/client.js +3515 -0
- package/cordis.patch.yml +3 -0
- package/docs/ARCHITECTURE-v0.2.md +269 -0
- package/docs/AUTO-DISCOVERY.md +111 -0
- package/docs/AUTOMATION-POLICIES.md +232 -0
- package/docs/CONTRATO-v0.1.md +195 -0
- package/docs/EMBEDDING-PROVIDERS.md +105 -0
- package/docs/OBSERVABILITY.md +241 -0
- package/docs/PA-UI-0-API-CONTRACT.md +887 -0
- package/docs/PERFORMANCE-BUDGETS.md +118 -0
- package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
- package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
- package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
- package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
- package/docs/WORKSPACE-API.md +239 -0
- package/icon.svg +7 -0
- package/index.js +198 -0
- package/lib/audit-export.mjs +70 -0
- package/lib/audit.mjs +120 -0
- package/lib/auto-context.mjs +322 -0
- package/lib/automation.mjs +214 -0
- package/lib/chunk.mjs +100 -0
- package/lib/config-resolve.mjs +119 -0
- package/lib/context.mjs +150 -0
- package/lib/conversation-events.mjs +145 -0
- package/lib/db.mjs +309 -0
- package/lib/diagnose.mjs +197 -0
- package/lib/discovery.mjs +402 -0
- package/lib/doctor.mjs +82 -0
- package/lib/embed.mjs +96 -0
- package/lib/embedders.mjs +103 -0
- package/lib/errors.mjs +231 -0
- package/lib/exec-context.mjs +238 -0
- package/lib/extract.mjs +260 -0
- package/lib/harness-workspaces.mjs +85 -0
- package/lib/hash.mjs +34 -0
- package/lib/ingest.mjs +239 -0
- package/lib/inputs.mjs +67 -0
- package/lib/library-state.mjs +252 -0
- package/lib/maintenance.mjs +113 -0
- package/lib/metrics.mjs +164 -0
- package/lib/migrate.mjs +373 -0
- package/lib/operations.mjs +132 -0
- package/lib/pa-api.mjs +946 -0
- package/lib/paths.mjs +345 -0
- package/lib/policy.mjs +125 -0
- package/lib/profile.mjs +128 -0
- package/lib/readmodel.mjs +159 -0
- package/lib/recovery.mjs +557 -0
- package/lib/registry-schema.mjs +206 -0
- package/lib/registry.mjs +606 -0
- package/lib/resolve.mjs +318 -0
- package/lib/retention.mjs +143 -0
- package/lib/revocation.mjs +124 -0
- package/lib/roots-structure.mjs +224 -0
- package/lib/schema.mjs +173 -0
- package/lib/scope-ops.mjs +379 -0
- package/lib/scope-stores.mjs +128 -0
- package/lib/search.mjs +345 -0
- package/lib/selection.mjs +225 -0
- package/lib/server.mjs +340 -0
- package/lib/session-identity.mjs +51 -0
- package/lib/sessions.mjs +343 -0
- package/lib/sync-scheduler.mjs +354 -0
- package/lib/sync.mjs +755 -0
- package/lib/tags.mjs +45 -0
- package/lib/tools.mjs +364 -0
- package/lib/trusted-roots.mjs +149 -0
- package/lib/worker-context.mjs +22 -0
- 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
|
-
#
|
|
1
|
+
# LifeCode RAG
|
|
2
2
|
|
|
3
|
-
|
|
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).
|