82a358f18d
ontoref-derive: #[onto_mcp_tool] attribute macro registers MCP tool unit-structs in
the catalog at link time via inventory::submit!; annotated item is emitted unchanged,
ToolBase/AsyncTool impls stay on the struct. All 34 tools migrated from manual wiring
(net +5: ontoref_list_projects, ontoref_search, ontoref_describe,
ontoref_list_ontology_extensions, ontoref_get_ontology_extension).
validate modes (ADR-018): reads level_hierarchy from workflow.ncl and checks every
.ncl mode for level declared, strategy declared, delegate chain coherent, compose
extends valid. mode resolve <id> shows which hierarchy level handles a mode and why.
--self-test generates synthetic fixtures in a temp dir for CI smoke-testing.
validate run-cargo: two-step Cargo.toml resolution — workspace layout first
(crates/<check.crate>/Cargo.toml), single-crate fallback by package name or repo
basename. Lets the same ADR constraint shape apply to workspace and single-crate repos.
ontology/schemas/manifest.ncl: registry_topology_type contract — multi-registry
coordination, push targets, participant scopes, per-namespace capability.
reflection/requirements/base.ncl: oras ≥1.2.0, cosign ≥2.0.0, sops ≥3.9.0, age
≥1.1.0, restic declared as Hard/Soft requirements with version_min, check_cmd, and
install_hint (ADR-017 toolchain surface).
ADR-019: per-file recipient routing for tenant isolation without multi-vault. Schema
additions: sops.recipient_groups + sops.recipient_rules in ontoref-project.ncl.
secrets-bootstrap generates .sops.yaml from project.ncl in declarative mode. Three
new secrets-audit checks: recipient-routing-coherent, recipient-routing-coverage,
no-multi-vault. Adoption templates: single-team/, multi-tenant/, agent-first/.
Integration templates: domain-producer/, mode-producer/, mode-consumer/.
UI: project_picker surfaces registry badge (⟳ participant) and vault badge
(⛁ vault_id · N, green=declarative / amber=legacy) per project card. Expanded panel
adds collapsible Registry section with namespace, endpoint, and push/pull capability.
manage.html gains Runtime Services card — MCP and GraphQL toggleable without restart
via HTMX POST /ui/manage/services/{service}/toggle.
describe.nu: capabilities JSON includes registry_topology and vault_state per project.
sync.nu: drift check extended to detect //! absence on newly registered crates.
qa.ncl: six entries — credential-vault-best-practice (layered data-flow diagram),
credential-vault-templates (paths A/B/C), credential-vault-troubleshooting (15 named
errors), integration-what-and-why (ADR-042 OCI federation), integration-how-to-implement,
integration-troubleshooting.
on+re: core.ncl + manifest.ncl updated to reflect OCI, MCP, and mode-hierarchy nodes.
Deleted stale presentation assets (2026-02 slides + voice notes).
125 lines
3.5 KiB
Markdown
125 lines
3.5 KiB
Markdown
# Setup — Working Group OntoRef
|
|
|
|
Lo que tenéis que tener instalado y preparado **antes** de la sesión 1 del
|
|
working group. Tiempo estimado: 20-30 minutos si todo va bien, 1 hora si toca
|
|
debuggear instalación.
|
|
|
|
## Requisitos previos
|
|
|
|
- macOS o Linux (ambos probados; Windows no soportado en este ciclo)
|
|
- Acceso a terminal y editor de texto cualquiera (vim, neovim, vscode, zed,
|
|
helix, lo que uséis)
|
|
- Conexión a internet en la sesión (para clonar repos)
|
|
|
|
## 1. Instalar Nickel
|
|
|
|
Nickel es el lenguaje de contratos. Se instala como un binario único.
|
|
|
|
### macOS
|
|
|
|
```bash
|
|
brew install nickel-lang
|
|
```
|
|
|
|
Si no usáis brew:
|
|
|
|
```bash
|
|
curl -L https://github.com/tweag/nickel/releases/latest/download/nickel-x86_64-apple-darwin --output ~/.local/bin/nickel
|
|
chmod +x ~/.local/bin/nickel
|
|
```
|
|
|
|
### Linux
|
|
|
|
```bash
|
|
curl -L https://github.com/tweag/nickel/releases/latest/download/nickel-x86_64-unknown-linux-gnu --output ~/.local/bin/nickel
|
|
chmod +x ~/.local/bin/nickel
|
|
```
|
|
|
|
(Asegúrate de que `~/.local/bin` está en tu `$PATH`.)
|
|
|
|
### Verificar
|
|
|
|
```bash
|
|
nickel --version
|
|
```
|
|
|
|
Debe mostrar `nickel 1.16.0` o superior.
|
|
|
|
## 2. Instalar la CLI de OntoRef
|
|
|
|
OntoRef es la herramienta que opera sobre `.ontology/` y se construye con
|
|
`cargo`. Necesitáis tener Rust instalado (`rustup` si no lo tenéis).
|
|
|
|
```bash
|
|
git clone https://github.com/jesusperez-pro/ontoref.git ~/dev/ontoref
|
|
cd ~/dev/ontoref
|
|
cargo install --path . --bin ontoref
|
|
```
|
|
|
|
(El path del repo y la URL son orientativos — si Jesús os da uno distinto,
|
|
usad el que os pase.)
|
|
|
|
### Verificar
|
|
|
|
```bash
|
|
ontoref --version
|
|
ontoref describe --help
|
|
```
|
|
|
|
Si `ontoref describe --help` devuelve la lista de subcomandos, está listo.
|
|
|
|
## 3. Preparar lo que traéis a la sesión
|
|
|
|
### Un proyecto vuestro
|
|
|
|
Cualquier proyecto que tengáis vivo y conozcáis bien. **Rust o no, da igual.**
|
|
Lo que importa es que sepáis hablar de él. Si tenéis varios, traed UNO — el
|
|
que más os duela en términos de coherencia perdida.
|
|
|
|
### Una decisión arquitectónica recordada
|
|
|
|
Algo que decidisteis en su momento y que sigue vivo en el código:
|
|
|
|
- "Usamos PostgreSQL en vez de SQLite porque…"
|
|
- "Todas las APIs públicas tienen rate-limiting porque…"
|
|
- "El módulo de auth no importa de billing porque…"
|
|
- "Cualquier campo público de la API tiene que estar versionado porque…"
|
|
|
|
No necesita ser sofisticada. Necesita ser **vuestra** y **viva**.
|
|
|
|
### Disposición a romperla
|
|
|
|
Vamos a modelar esa decisión como contrato y luego vamos a intentar violarla
|
|
en vivo para ver el typecheck rechazándola. Si sois posesivos con vuestras
|
|
decisiones, el ejercicio se hace cuesta arriba.
|
|
|
|
## 4. Comprobaciones finales (24h antes)
|
|
|
|
Ejecutad esto en una terminal limpia:
|
|
|
|
```bash
|
|
nickel --version # debe responder
|
|
ontoref --version # debe responder
|
|
mkdir -p ~/tmp/wg-test && cd ~/tmp/wg-test
|
|
echo '{ x = 1 }' > test.ncl
|
|
nickel export test.ncl # debe imprimir {"x": 1}
|
|
```
|
|
|
|
Si los cuatro comandos pasan, estáis listos.
|
|
|
|
## Si algo falla
|
|
|
|
- **Antes de la sesión**: avisad por el grupo de Telegram. Es mejor 30 minutos
|
|
de troubleshooting compartido que perder 30 minutos de la sesión.
|
|
- **Durante la sesión**: pareja con quien sí tiene el setup hasta que se
|
|
resuelva. La sesión no espera, pero tampoco se deja a nadie atrás.
|
|
|
|
## Recursos opcionales (no necesarios para la sesión 1)
|
|
|
|
- [Nickel Documentation](https://nickel-lang.org/) — para hojearlo si queréis
|
|
contexto
|
|
- [OntoRef README](https://github.com/jesusperez-pro/ontoref) — la herramienta
|
|
por dentro
|
|
|
|
No hace falta leerlos antes. Lo que se necesita aprender, se aprende en
|
|
sesión.
|