ozali 0.1.0

package/cli/lib/util.mjs

@@ -0,0 +1,131 @@
+// util.mjs — helpers de bajo nivel, CERO dependencias (solo node:*).
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+// ---- rutas del paquete ------------------------------------------------------
+// Este archivo vive en <root>/cli/lib/util.mjs → la raíz del paquete es ../../..
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const PKG_ROOT = path.resolve(HERE, "..", "..");
+export const SKILL_SRC = path.join(PKG_ROOT, "skill");
+
+export function pkgVersion() {
+  try {
+    const p = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+    return p.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// ---- colores (sin deps; respeta NO_COLOR y no-TTY) --------------------------
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+export const c = {
+  bold: wrap("1"),
+  dim: wrap("2"),
+  red: wrap("31"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  blue: wrap("34"),
+  magenta: wrap("35"),
+  cyan: wrap("36"),
+};
+
+export const ok = (m) => console.log(`${c.green("✔")} ${m}`);
+export const warn = (m) => console.log(`${c.yellow("⚠")} ${m}`);
+export const err = (m) => console.error(`${c.red("✖")} ${m}`);
+export const info = (m) => console.log(`${c.cyan("•")} ${m}`);
+export const step = (m) => console.log(`\n${c.bold(c.magenta("▸ " + m))}`);
+
+// ---- filesystem -------------------------------------------------------------
+export function exists(p) {
+  try { fs.accessSync(p); return true; } catch { return false; }
+}
+
+export function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+/** Copia recursiva de un directorio (zero-dep). */
+export function copyDir(src, dst) {
+  ensureDir(dst);
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+export function readJSON(p, fallback = null) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fallback; }
+}
+
+export function writeJSON(p, obj) {
+  ensureDir(path.dirname(p));
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + "\n");
+}
+
+// ---- ejecución de comandos (read-only / git) --------------------------------
+/** Ejecuta un binario y devuelve stdout recortado, o null si falla. */
+export function tryExec(cmd, args = [], opts = {}) {
+  try {
+    return execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], ...opts }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function which(bin) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  return tryExec(finder, [bin]);
+}
+
+// ---- git --------------------------------------------------------------------
+export function gitInfo(cwd) {
+  const inside = tryExec("git", ["rev-parse", "--is-inside-work-tree"], { cwd }) === "true";
+  if (!inside) return { isRepo: false };
+  return {
+    isRepo: true,
+    branch: tryExec("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd }),
+    commit: tryExec("git", ["rev-parse", "--short", "HEAD"], { cwd }),
+    remote: tryExec("git", ["remote", "get-url", "origin"], { cwd }),
+    userName: tryExec("git", ["config", "user.name"], { cwd }),
+    userEmail: tryExec("git", ["config", "user.email"], { cwd }),
+  };
+}
+
+/** Nombre de proyecto normalizado (remoto git → minúsculas; si no, carpeta). */
+export function projectName(cwd) {
+  const g = gitInfo(cwd);
+  if (g.isRepo && g.remote) {
+    const m = g.remote.replace(/\.git$/, "").match(/([^/:]+)$/);
+    if (m) return m[1].toLowerCase();
+  }
+  return path.basename(cwd).toLowerCase();
+}
+
+// ---- .gitignore idempotente -------------------------------------------------
+export function ensureGitignore(cwd, entries) {
+  const gi = path.join(cwd, ".gitignore");
+  let body = exists(gi) ? fs.readFileSync(gi, "utf8") : "";
+  const lines = new Set(body.split(/\r?\n/));
+  const missing = entries.filter((e) => !lines.has(e));
+  if (missing.length === 0) return { added: [] };
+  const block = (body && !body.endsWith("\n") ? "\n" : "") +
+    "\n# ozali — histórico aislado (no commitear en el repo principal)\n" +
+    missing.join("\n") + "\n";
+  fs.writeFileSync(gi, body + block);
+  return { added: missing };
+}
+
+// ---- node version -----------------------------------------------------------
+export function nodeMajor() {
+  return parseInt(process.versions.node.split(".")[0], 10);
+}
+
+export const HOME = os.homedir();
+export const DEFAULT_KNOWLEDGE = path.join(HOME, ".ozali", "knowledge");

package/cli/test/smoke.test.mjs

@@ -0,0 +1,88 @@
+// smoke.test.mjs — pruebas básicas del CLI (node:test, sin dependencias).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(HERE, "..", "bin", "ozali.mjs");
+const PKG_ROOT = path.resolve(HERE, "..", "..");
+
+function run(args, cwd, expectFail = false) {
+  try {
+    const stdout = execFileSync(process.execPath, [BIN, ...args], { cwd, encoding: "utf8" });
+    return { code: 0, stdout };
+  } catch (e) {
+    if (!expectFail) throw e;
+    return { code: e.status, stdout: (e.stdout || "") + (e.stderr || "") };
+  }
+}
+
+function tmpProject() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ozali-test-"));
+  execFileSync("git", ["init", "-q"], { cwd: dir });
+  return dir;
+}
+
+test("--version imprime la versión del package.json", () => {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+  const { stdout } = run(["--version"]);
+  assert.equal(stdout.trim(), pkg.version);
+});
+
+test("--help menciona los 4 comandos", () => {
+  const { stdout } = run(["--help"]);
+  for (const cmd of ["init", "doctor", "update", "sync"]) assert.match(stdout, new RegExp(cmd));
+});
+
+test("comando desconocido sale con código 1", () => {
+  const { code } = run(["frobnicate"], process.cwd(), true);
+  assert.equal(code, 1);
+});
+
+test("doctor en proyecto vacío reporta pendientes (exit 1)", () => {
+  const dir = tmpProject();
+  try {
+    const { code, stdout } = run(["doctor"], dir, true);
+    assert.equal(code, 1);
+    assert.match(stdout, /health-check/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("init --yes instala la skill, aísla el histórico y escribe config", () => {
+  const dir = tmpProject();
+  try {
+    run(["init", "--yes", "--agent", "claude-code", "--scope", "project", "--knowledge-repo", path.join(dir, ".k")], dir);
+    assert.ok(fs.existsSync(path.join(dir, ".claude", "skills", "ozali", "SKILL.md")), "SKILL.md instalada");
+    assert.ok(fs.existsSync(path.join(dir, ".ozali", "config.json")), "config escrita");
+    const gi = fs.readFileSync(path.join(dir, ".gitignore"), "utf8");
+    assert.match(gi, /\.ozali\//);
+    assert.match(gi, /\.engram\//);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("init --dry-run no escribe nada", () => {
+  const dir = tmpProject();
+  try {
+    run(["init", "--dry-run", "--yes"], dir);
+    assert.ok(!fs.existsSync(path.join(dir, ".ozali")), "no debe crear .ozali en dry-run");
+    assert.ok(!fs.existsSync(path.join(dir, ".claude")), "no debe crear .claude en dry-run");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("el paquete NO tiene dependencias ni lifecycle scripts (seguridad)", () => {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+  assert.equal(Object.keys(pkg.dependencies || {}).length, 0, "cero dependencias");
+  for (const s of ["preinstall", "install", "postinstall", "preuninstall", "postuninstall", "prepare"]) {
+    assert.ok(!(pkg.scripts && pkg.scripts[s]), `sin script de ciclo de vida: ${s}`);
+  }
+});

package/docs/intended-usage.md

@@ -0,0 +1,43 @@
+# Uso previsto (modelo mental)
+
+← [README](../README.md)
+
+Esta página explica **cómo se usa ozali**, no los flags. Si lees una sola página además del README, que sea esta.
+
+## La idea en una frase
+
+`ozali` toma un repo existente y le instala un **método de trabajo con IA**: calibra el proyecto,
+genera una skill de ejecución (`cdk`) con TDD/SDD, y mantiene **memoria de equipo** con el
+histórico aislado del repo principal.
+
+## Las dos capas
+
+| Capa | Quién la corre | Qué hace |
+|---|---|---|
+| **CLI `ozali`** | tú, en la terminal | instala/actualiza la skill, aísla el histórico, configura Engram (`init`/`doctor`/`update`/`sync`) |
+| **Skill `ozali` → genera `cdk`** | tu agente (Claude Code/opencode) | diagnostica, calibra, y con tu aprobación (GATE) ejecuta el trabajo con 8 subagentes |
+
+## Flujo típico (primera vez en un repo)
+
+1. **`pnpm dlx ozali@<versión> init`** — el CLI detecta tu agente, instala la skill, aísla
+   `.ozali/` y `.engram/` en el `.gitignore`, y configura el repo de conocimiento.
+2. **Abre tu agente** y escribe `"diagnostica el proyecto"` (o `ozali`). La skill:
+   - valida/genera la fuente de verdad `AI.md` + `.ai/`;
+   - **calibra testing y resuelve Strict TDD** (Fase 3.5);
+   - te presenta un **plan** (🛑 GATE) y, al aprobarlo, genera la skill `cdk` con sus 8 subagentes.
+3. **Trabaja con `cdk`**: cada solicitud/hito produce 6 documentos legibles **y** se espeja a
+   Engram (modo híbrido). El plan aprobado se congela; la bitácora es append-only.
+4. **`ozali sync`** — lleva el histórico (docs + Engram) al repo de conocimiento de equipo.
+
+## Día a día
+
+- Pídele cosas a `cdk` en tu agente (`"crea el endpoint X"`, `"corrige el bug Y"`,
+  `cdk --auto "refactor Z"`). El GATE del plan es el único punto donde siempre paras a aprobar.
+- Si instalaste Engram, `cdk` **recuerda** lo que el equipo hizo antes y reanuda hitos a medias.
+- Corre `ozali doctor` cuando quieras un chequeo de salud read-only.
+
+## La regla de oro
+
+El histórico **crece sin tocar el repo principal**. El cerebro (`.ai/`) viaja con el código; el
+registro y la memoria viven aislados y se comparten con `ozali sync`. Así el equipo acumula
+conocimiento sin inflar los repos de producto.

package/docs/security.md

@@ -0,0 +1,47 @@
+# Seguridad del instalador (npx / pnpm / supply-chain)
+
+← [README](../README.md)
+
+`ozali` se distribuye como un CLI **Node de cero dependencias y sin lifecycle scripts**
+(`preinstall`/`install`/`postinstall`). Esa decisión es deliberada: **elimina de raíz** el vector
+de ataque de cadena de suministro que abusaron incidentes recientes del registro npm.
+
+## El problema: lifecycle scripts en `npm`/`npx`
+
+`npx <pkg>` descarga el paquete **y todo su árbol de dependencias** a un caché temporal y ejecuta
+su `bin`. Por defecto, npm/npx **ejecutan los lifecycle scripts** del paquete y de **cada
+dependencia transitiva** durante la instalación — *antes* de que tú corras nada. Un `postinstall`
+malicioso en una dependencia popular (o comprometida) corre código arbitrario en tu máquina:
+roba tokens/variables de entorno y, en los gusanos recientes, se auto-propaga.
+
+## Las tres palancas de mitigación
+
+1. **Cero dependencias + cero scripts propios.** Si el paquete no tiene dependencias ni
+   `postinstall`, el vector **no existe**, corras como corras. ← Es lo que hace `ozali`.
+2. **`--ignore-scripts`.** npm/npx/pnpm lo soportan; se puede fijar global en `.npmrc`
+   (`ignore-scripts=true`).
+3. **pnpm v10+.** Deshabilita los lifecycle scripts de las dependencias **por defecto**; hay que
+   aprobarlos explícitamente (`pnpm.onlyBuiltDependencies` o `pnpm approve-builds`). `pnpm dlx`
+   (el equivalente de `npx`) hereda ese default seguro.
+
+## Cómo instalar/ejecutar ozali de forma segura
+
+| Método | Comando | Notas |
+|---|---|---|
+| **pnpm (recomendado)** | `pnpm dlx ozali@<versión> init` | pnpm 10 no corre postinstall de deps; pinea la versión |
+| **npm con scripts off** | `npx --ignore-scripts ozali@<versión> init` | desactiva lifecycle scripts explícitamente |
+| **git (máxima auditabilidad)** | `git clone <repo> && node ozali/cli/bin/ozali.mjs init` | sin registry, sin árbol de deps; el equipo lee el script antes de correrlo |
+
+> **Siempre pinea la versión** (`@x.y.z`) en vez de `@latest`, y usa lockfile. Al publicar en npm
+> se firmará con **provenance** (sigstore) para verificar origen.
+
+## Por qué NO un `curl … | bash` como camino primario
+
+El `curl … | bash` estilo de otros instaladores ejecuta un script remoto **a ciegas**. Lo dejamos
+solo como espejo opcional, **pineado a un tag + checksum** verificable, nunca como ruta por defecto.
+
+## Disciplina interna
+
+- El harness `verify-structure.mjs` que genera `cdk` es también **cero deps, Node 16+**.
+- El CLI no escribe fuera del proyecto destino sin confirmación, salvo el repo de conocimiento
+  que el usuario configura explícitamente en `ozali init`.

package/docs/team-history.md

@@ -0,0 +1,66 @@
+# Histórico aislado y memoria de equipo
+
+← [README](../README.md)
+
+Objetivo: que el **histórico de documentación y memoria crezca sin sobrecargar el repo principal**
+del proyecto, y que el conocimiento sea **compartible por el equipo**.
+
+## Tres capas, tres destinos
+
+| Capa | Qué es | Dónde vive | Por qué |
+|---|---|---|---|
+| **Cerebro** (fuente de verdad) | `.ai/` + `AI.md` | **repo principal** (commiteado) | son las reglas; chico, crece lento, debe viajar con el código |
+| **Histórico** (docs) | docs por hito (6) + por corrida (3) | **repo de conocimiento aparte** (gitignored en el principal) | esto es lo que crece sin límite |
+| **Memoria** (Engram) | chunks/manifest buscables | store local de Engram + export al repo de conocimiento | Engram ya aísla por defecto; solo el export `.engram/` necesita casa |
+
+## Modelo recomendado: un repo de conocimiento de equipo
+
+Un único repo `ozali-knowledge` guarda el histórico de **todos** los proyectos (Engram y las
+carpetas de docs ya son multi-proyecto por naming determinista):
+
+```
+ozali-knowledge/                 (repo GitHub aparte, compartido por el equipo)
+  engram/                        ← export de Engram (multi-proyecto: chunks + manifest)
+  projects/
+    quattro-auto-api/
+      runs/                      ← corridas de bootstrap de ozali (3 docs c/u)
+      milestones/<hito>/         ← 6 docs por hito
+    otro-proyecto/
+      ...
+```
+
+El repo principal solo gana `.ai/` (cerebro) + las skills bajo `.claude/skills/`. Su `.gitignore`
+excluye `.ozali/` y `.engram/`.
+
+## Cómo lo cablea el CLI
+
+- `ozali init` → detecta/clona el repo de conocimiento (default `~/.ozali/knowledge`), añade
+  `.ozali/` y `.engram/` al `.gitignore` del repo principal, apunta el export de Engram ahí.
+- `cdk` (durante el trabajo) → escribe docs en el repo de conocimiento, no en el working tree
+  del repo principal.
+- `ozali sync` → commit + push del repo de conocimiento; el equipo hace pull para compartir.
+
+## Trazabilidad (enlace código ↔ histórico)
+
+Cada documento lleva en su encabezado: autor, rama, **commit SHA del repo principal**, proyecto y
+fecha/hora (Fase 0 de `ozali`). Así, desde un commit encuentras su histórico y cada entrada del
+histórico apunta a un commit exacto.
+
+## Opciones del enlace físico (rankeadas)
+
+1. **Gitignore + clon aparte gestionado por el CLI (RECOMENDADO).** Modelo mental simple, sin
+   dolor de submódulos. El histórico nunca pesa en el repo principal. El enlace es por SHA en el
+   header (no forzado por git) — aceptable.
+2. **Worktree de una rama huérfana** (`ozali-history`) en el mismo remoto, montada en `.ozali/`
+   (gitignored en main). Un solo remoto; el histórico nunca ensucia los diffs de main. El
+   object-DB crece pero el checkout queda liviano. Ideal si NO quieren un segundo repo.
+3. **Submódulo git.** Acoplamiento estricto (pin por commit) pero con fricción (clone recursivo,
+   detached HEAD). Solo si quieren pin forzado.
+4. **Store externo no-git** (S3/Notion/drive). Desacopla del todo pero pierde auditoría git; más
+   infra. No recomendado.
+
+> Engram aporta además el `engram sync` / `engram sync --import` ya probado: lo retargeteamos al
+> repo de conocimiento en lugar del repo principal.
+
+El contrato concreto de qué se espeja a Engram, cuándo, y el algoritmo de `ozali sync` está en
+[skill/references/engram-convention.md](../skill/references/engram-convention.md) (§3 y §6).

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "ozali",
+  "version": "0.1.0",
+  "description": "Bootstrap interactivo de IA por equipo: calibra el proyecto, genera la skill de ejecución (cdk) con TDD/SDD, y mantiene memoria de equipo (Engram) con histórico aislado.",
+  "type": "module",
+  "bin": {
+    "ozali": "cli/bin/ozali.mjs"
+  },
+  "scripts": {
+    "test": "node --test cli/test/*.test.mjs"
+  },
+  "files": [
+    "cli/",
+    "skill/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "tdd",
+    "sdd",
+    "claude-code",
+    "opencode",
+    "engram",
+    "bootstrap",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "MIT",
+  "author": "Jaime Baños",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jimmybathrooms/ozali.git"
+  },
+  "dependencies": {}
+}