tawasuyu/brahman

1//! `brahman-cards` — brazo unificado de Cards.
2//!
3//! Brahman maneja varios formatos legítimos de "Card" (la unidad
4//! declarativa que describe identidad, datos, módulos, widgets, ...).
5//! Cada formato vive en su propio crate de origen y conserva su shape
6//! público; lo que este crate aporta es **un único punto de entrada**
7//! que sabe interpretar cada uno de ellos y proyectarlos a una sola
8//! estructura interna canónica [`Card`].
9//!
10//! Diseño:
11//!
12//! ```text
13//! ┌─────────────┐  ┌──────────────┐  ┌─────────────┐
14//! │ Ente JSON   │  │ Monad JSON   │  │ UiModule    │ … futuro
15//! │ (brahman-   │  │ (nouser-     │  │ (nakui-ui-  │
16//! │  card)      │  │  card)       │  │  schema)    │
17//! └─────┬───────┘  └──────┬───────┘  └──────┬──────┘
18//!       │                 │                 │
19//!       └────────┬────────┴────────┬────────┘
20//!                │  brahman-cards  │
21//!                │   (este crate)  │
22//!                └────────┬────────┘
23//!                         │
24//!                  ┌──────▼──────┐
25//!                  │   `Card`    │ ← único tipo canónico
26//!                  │   wrapper   │   que consumen UI runtime,
27//!                  │   común +   │   storage, DHT, wire.
28//!                  │   variant   │
29//!                  │   body      │
30//!                  └─────────────┘
31//! ```
32//!
33//! Los formatos NO se disuelven. Si en el futuro hay que soportar un
34//! formato simplificado nuevo, se agrega un reader acá y nadie aguas
35//! abajo se entera — siguen recibiendo `Card`.
36//!
37//! V1 (este commit) sólo soporta inputs JSON. La extensión a Nickel
38//! (con templates de defaults vía merge nativo de Nickel) llega en un
39//! commit separado para aislar la dependencia `nickel-lang-core`.
40
41#![forbid(unsafe_code)]
42
43use std::collections::BTreeMap;
44use std::path::{Path, PathBuf};
45
46use serde::{Deserialize, Serialize};
47use serde_json::Value;
48use thiserror::Error;
49
50pub use brahman_card::Card as EnteCard;
51pub use nouser_card::MonadManifest;
52pub use yahweh_meta_schema::Module as UiModuleSpec;
53
54/// Estructura canónica única que consumen los downstream del sistema
55/// (UI runtime, storage, DHT, wire). Cada formato input se proyecta
56/// a ésta vía un reader del brazo.
57///
58/// El wrapper común agrupa lo que TODOS los formatos comparten
59/// (identidad legible + extensiones forward-compat); el body preserva
60/// el typing rico de cada dominio sin colapsarlos.
61// PartialEq se omite porque algunos body variants vienen de crates
62// que no lo implementan (MonadManifest, yahweh_meta_schema::Module).
63// Si downstream necesita igualdad, comparar via JSON round-trip o
64// agregar PartialEq en los crates origen.
65#[derive(Debug, Clone, Serialize, Deserialize)]
66pub struct Card {
67    /// Identificador opaco. String en el wrapper para no obligar a
68    /// los formatos a un mismo tipo concreto (Ente/Monad usan ULID,
69    /// UiModule usa slug human-friendly como `"sales_engine"`).
70    /// Cada reader documenta qué formato exige.
71    pub id: String,
72
73    /// Versión del schema canónico de este wrapper. Bump = romper
74    /// compat de los consumers downstream. Distinto de los
75    /// `schema_version` internos de cada body variant, que siguen
76    /// su propio versioning.
77    pub schema_version: u16,
78
79    /// Ancestro del que esta Card desciende (si aplica). Significado
80    /// específico al body variant (Ente: lineage del proceso; Monad:
81    /// split/merge de Mónada padre; UiModule: típicamente None).
82    #[serde(default)]
83    pub lineage: Option<String>,
84
85    /// Etiqueta humana legible. Cada reader la deriva del campo
86    /// equivalente del input (label/title/etc.).
87    pub label: String,
88
89    /// Campos no reconocidos del input se preservan acá. Permite
90    /// forward-compat: leer un input con campos nuevos no rompe la
91    /// carga, y volver a serializar conserva el extra.
92    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
93    pub extensions: BTreeMap<String, Value>,
94
95    /// Cuerpo tipado por dominio. La elección del variant es
96    /// responsabilidad del reader (basada en el input shape).
97    pub body: CardBody,
98}
99
100/// Versión actual del schema canónico de [`Card`]. Bump cuando cambie
101/// la shape del wrapper o las invariantes que comparten todos los
102/// variants.
103pub const CARD_SCHEMA_VERSION: u16 = 1;
104
105/// Variantes tipadas del body de [`Card`]. Una por dominio.
106///
107/// **Convención de extensión**: agregar un variant nuevo aquí + un
108/// reader que produzca ese variant. Los consumers que sólo manejen
109/// algunos variants pueden hacer `match { Ente(..) => ..., _ => skip }`.
110#[derive(Debug, Clone, Serialize, Deserialize)]
111#[serde(tag = "kind", rename_all = "snake_case")]
112pub enum CardBody {
113    /// Entidad runtime con proceso/payload/supervision (lo que era
114    /// `brahman_card::Card` directo).
115    Ente(EnteCard),
116
117    /// Agrupación semántica de archivos (Mónada de Nouser). No tiene
118    /// proceso; describe membership + signals semánticas (centroid,
119    /// keywords, lens).
120    Monad(MonadManifest),
121
122    /// Descriptor de módulo de UI: entities + views + menu + actions.
123    /// Lo que hoy lee la metainterface de Nakui desde
124    /// `examples/nakui-modules/<id>/module.json`.
125    UiModule(UiModuleSpec),
126}
127
128impl CardBody {
129    /// Etiqueta corta del variant — útil para mensajes de error y
130    /// dispatch en la UI sin necesitar match exhaustivo.
131    pub fn kind_name(&self) -> &'static str {
132        match self {
133            CardBody::Ente(_) => "ente",
134            CardBody::Monad(_) => "monad",
135            CardBody::UiModule(_) => "ui_module",
136        }
137    }
138}
139
140/// Errores de carga del brazo.
141#[derive(Debug, Error)]
142pub enum CardLoadError {
143    #[error("io: {0}")]
144    Io(#[from] std::io::Error),
145
146    #[error("parse JSON: {0}")]
147    JsonParse(#[from] serde_json::Error),
148
149    #[error("ningún reader registrado matcheó el input (shape no reconocido)")]
150    NoMatchingReader,
151
152    #[error("reader '{reader}' falló: {message}")]
153    ReaderFailed { reader: &'static str, message: String },
154
155    #[error("formato no soportado: extensión '{ext}'. Soportadas: {supported:?}")]
156    UnsupportedExtension {
157        ext: String,
158        supported: Vec<&'static str>,
159    },
160
161    #[error("evaluación Nickel: {0}")]
162    Nickel(#[from] NickelEvalError),
163}
164
165/// Trait de reader. Cada formato implementa una instancia.
166///
167/// El dispatcher del brazo (`load_card`) prueba los readers en el
168/// orden registrado y se queda con el primero cuyo `can_read`
169/// devuelve `true`. Por eso el orden importa: poner los más
170/// específicos antes que los más laxos.
171pub trait CardReader: Send + Sync {
172    /// Nombre del reader, para mensajes de error.
173    fn name(&self) -> &'static str;
174
175    /// Dado un JSON Value (el input ya parseado a serde Value),
176    /// decide si este reader puede manejarlo. Heurística estructural
177    /// — el shape del input identifica el formato, no flags
178    /// explícitos (los inputs legacy no los tienen).
179    fn can_read(&self, input: &Value) -> bool;
180
181    /// Produce el [`Card`] canónico. Sólo se llama si `can_read`
182    /// devolvió `true`.
183    fn read(&self, input: Value) -> Result<Card, CardLoadError>;
184}
185
186mod nickel_eval;
187mod readers;
188pub use nickel_eval::{eval_nickel_file, NickelEvalError, BRAHMAN_CARDS_TEMPLATES_ENV};
189pub use readers::{EnteJsonReader, MonadJsonReader, UiModuleJsonReader};
190
191/// Path al directorio de templates Nickel canónicos shipped con el
192/// crate (`crates/core/brahman-cards/templates/` en el repo).
193///
194/// Este directorio contiene los `*_basic.ncl` para cada body kind:
195/// - `ente_basic.ncl`
196/// - `monad_basic.ncl`
197/// - `ui_module_basic.ncl`
198///
199/// Usar como path para [`BRAHMAN_CARDS_TEMPLATES_ENV`] o pasarlo
200/// directo a Nickel via env. Resuelto via `CARGO_MANIFEST_DIR` —
201/// funciona en `cargo test`/`cargo run` desde el workspace. Para
202/// distribución del binary standalone (cuando emerja el caso de
203/// uso), incluir los templates como recursos via `include_dir!` o
204/// instalar el directorio junto al ejecutable.
205pub fn canonical_templates_dir() -> PathBuf {
206    PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("templates")
207}
208
209/// Construye el set default de readers para inputs JSON. El orden
210/// es deliberado: el más específico (UiModule, que tiene `entities`
211/// y `views` simultáneamente) antes que el más laxo. Si dos readers
212/// matchean, gana el primero.
213pub fn default_readers() -> Vec<Box<dyn CardReader>> {
214    vec![
215        Box::new(UiModuleJsonReader),
216        Box::new(MonadJsonReader),
217        Box::new(EnteJsonReader),
218    ]
219}
220
221/// Carga un Card desde una ruta. Detecta formato por extensión, y
222/// dentro de JSON detecta el shape probando los readers default en
223/// orden.
224///
225/// Para custom reader sets, usar [`load_card_with`].
226pub fn load_card(path: impl AsRef<Path>) -> Result<Card, CardLoadError> {
227    load_card_with(path, &default_readers())
228}
229
230/// Variante de [`load_card`] con readers custom. Útil para tests o
231/// para apps que quieren restringir formatos soportados.
232pub fn load_card_with(
233    path: impl AsRef<Path>,
234    readers: &[Box<dyn CardReader>],
235) -> Result<Card, CardLoadError> {
236    let path = path.as_ref();
237    let ext = path
238        .extension()
239        .and_then(|e| e.to_str())
240        .unwrap_or("")
241        .to_ascii_lowercase();
242    match ext.as_str() {
243        "json" => {
244            let bytes = std::fs::read(path)?;
245            let value: Value = serde_json::from_slice(&bytes)?;
246            dispatch_to_reader(value, readers)
247        }
248        "ncl" => {
249            // Nickel pipeline: leer archivo → evaluar deeply → exportar
250            // a JSON → parsear como Value → dispatch a los readers JSON
251            // estándar. Templates funcionan via los `import` nativos de
252            // Nickel; el evaluator resuelve relativo al input y al
253            // `BRAHMAN_CARDS_TEMPLATES_DIR` env (si está set).
254            let value = eval_nickel_file(path)?;
255            dispatch_to_reader(value, readers)
256        }
257        other => Err(CardLoadError::UnsupportedExtension {
258            ext: other.to_string(),
259            supported: vec!["json", "ncl"],
260        }),
261    }
262}
263
264/// Recorre los readers en orden, se queda con el primero que matchea
265/// y delega la conversión.
266fn dispatch_to_reader(
267    input: Value,
268    readers: &[Box<dyn CardReader>],
269) -> Result<Card, CardLoadError> {
270    for r in readers {
271        if r.can_read(&input) {
272            return r.read(input);
273        }
274    }
275    Err(CardLoadError::NoMatchingReader)
276}
277
278/// Filenames convencionales que [`load_cards_from_dir`] busca dentro
279/// de cada subdir, en orden de preferencia. Si `card.ncl` existe se
280/// usa ese; sino `card.json`; sino los aliases legacy `module.*`. Los
281/// últimos dos son por compat con el layout actual de
282/// `examples/nakui-modules/<id>/module.json`.
283pub const DEFAULT_CARD_FILENAMES: &[&str] =
284    &["card.ncl", "card.json", "module.ncl", "module.json"];
285
286/// Carga todas las Cards encontradas como subdirs inmediatos de
287/// `dir`. Por cada subdir, busca los filenames convencionales (ver
288/// [`DEFAULT_CARD_FILENAMES`]) y carga el primero que existe. Subdirs
289/// sin ningún filename matching se skipean silenciosamente — permite
290/// que un dir contenga subdirs auxiliares (assets, fixtures, etc.).
291///
292/// Devuelve las Cards en orden lexicográfico por subdir name (estable
293/// across runs). NO ordena por `Card.id` — el caller decide si quiere
294/// re-ordenar y/o dedupar.
295///
296/// Errores: cualquier I/O al leer el `dir` mismo, o cualquier
297/// `CardLoadError` de un archivo encontrado (NO continúa tras el
298/// primer fallo — fallo loud > corrupción silenciosa).
299pub fn load_cards_from_dir(dir: impl AsRef<Path>) -> Result<Vec<Card>, CardLoadError> {
300    load_cards_from_dir_with(dir, DEFAULT_CARD_FILENAMES, &default_readers())
301}
302
303/// Variante de [`load_cards_from_dir`] con filenames y readers
304/// custom. Útil para apps que quieren restringir formatos o usar un
305/// nombre canónico distinto.
306pub fn load_cards_from_dir_with(
307    dir: impl AsRef<Path>,
308    filenames: &[&str],
309    readers: &[Box<dyn CardReader>],
310) -> Result<Vec<Card>, CardLoadError> {
311    let dir = dir.as_ref();
312    let mut subdir_paths: Vec<std::path::PathBuf> = std::fs::read_dir(dir)?
313        .flatten()
314        .filter_map(|e| {
315            let p = e.path();
316            if p.is_dir() { Some(p) } else { None }
317        })
318        .collect();
319    // Orden estable por subdir name — el output del brazo no debería
320    // depender del orden de read_dir (que varía por filesystem).
321    subdir_paths.sort();
322
323    let mut out: Vec<Card> = Vec::new();
324    for sub in subdir_paths {
325        for fname in filenames {
326            let candidate = sub.join(fname);
327            if candidate.exists() {
328                out.push(load_card_with(&candidate, readers)?);
329                break;
330            }
331        }
332    }
333    Ok(out)
334}