duckbrain-toolbox/README.org

Duckbrain toolbox

• Qué resuelve
• Conceptos
• Estructura del repositorio
• Instalación
• Comandos
  • duckbrain install [dir]
  • duckbrain add <componente|paquete>
  • duckbrain remove <componente>
  • duckbrain update [core|<componente>] [--dry-run]
  • duckbrain list / duckbrain doctor / duckbrain catalog / duckbrain adopt
• Manifiesto duckbrain.json
• Destino de los archivos
• Estado del proyecto
• Migrar un proyecto existente
• Compatibilidad
• Versionado y releases
• Pruebas
• Contacto

Instalador y catálogo de paquetes de Duckbrain. Trae el núcleo a un proyecto y gestiona sus addons con un solo comando, manteniendo la filosofía del núcleo: sin Composer obligatorio, código legible y copias reales desplegables (hosting compartido, FTP, etc.).

Qué resuelve

El núcleo Duckbrain mantiene su código simple y sin dependencias, y todo lo accesorio vive en addons. Antes, instalar un addon era copiar archivos a mano dentro de src/: cada proyecto quedaba con una versión distinta, las correcciones no se propagaban y se acumulaba código muerto.

El toolbox convierte eso en:

duckbrain install mi-proyecto
duckbrain add crypto
duckbrain update

Conceptos

Concepto	Qué es
Repositorio	Dónde vive el código (canal de distribución)
Paquete	Una familia de componentes (http, crypto, =text=…)
Componente	La unidad instalable (una clase o una familia)
Manifiesto	duckbrain.json: qué archivos aporta cada componente
Catálogo	Los paquetes disponibles en el toolbox
Lock	.duckbrain/lock.json: qué quedó instalado y con qué hash

La unidad que se pide con duckbrain add es el componente, no el paquete ni el repositorio.

Estructura del repositorio

duckbrain-toolbox/
  bin/duckbrain                 instalador global (bootstrap)
  scripts/release               escritor único de versión + tag
  packages/
    commands/  cli, migration, toolbox
    htmx/      htmlComponent, htmx
    http/      curlRequest, aria2, proxy, compreFace
    crypto/    crypto, nonce, twoFactor
    text/      filter, replacement
    cache/     apcache
    id/        ulid
    test/      harness

Cada paquete tiene su duckbrain.json. Sólo se copian los archivos declarados por el componente que pides; los metadatos del paquete no se instalan.

Instalación

El instalador global arranca un proyecto desde cero y no necesita nada previo:

git clone git@git.kj2.me:kj/duckbrain-toolbox.git
ln -s "$PWD/duckbrain-toolbox/bin/duckbrain" ~/.local/bin/duckbrain

duckbrain install mi-proyecto     # descarga el núcleo Duckbrain
cd mi-proyecto
duckbrain add crypto htmx         # copias reales, listas para commitear

Uso opcional dentro del proyecto: si quieres que el proyecto gestione sus propios addons sin el instalador global, instala el componente commands:toolbox (es un add más, no un requisito). A partir de ahí ./duckbrain funciona solo.

Comandos

duckbrain install [dir]

Descarga el núcleo Duckbrain en dir. Es sólo del instalador global.

duckbrain add <componente|paquete>

Instala componentes, resolviendo dependencias y copiando archivos.

duckbrain add crypto                 # la familia completa
duckbrain add http:aria2             # un solo componente
duckbrain add http@^0.1              # fijando restricción de versión
duckbrain add htmx --link            # enlaza en lugar de copiar (desarrollo)

duckbrain remove <componente>

Borra sólo los archivos de ese componente; si alguno fue editado localmente, se bloquea y pide --force, --backup o --keep-local.

duckbrain update [core|<componente>] [--dry-run]

duckbrain update core        # sólo el núcleo
duckbrain update http        # un paquete
duckbrain update             # todo: catálogo -> core -> componentes
duckbrain update --dry-run   # muestra el plan sin escribir

duckbrain list / duckbrain doctor / duckbrain catalog / duckbrain adopt

• list: core y componentes instalados con versión y modo.
• doctor: matriz de compatibilidad, sin efectos secundarios.
• catalog: paquetes y componentes disponibles.
• adopt: registra copias hechas a mano en proyectos antiguos.

Manifiesto duckbrain.json

{
  "name": "http",
  "version": "0.1.0",
  "description": "Utilidades HTTP",
  "core": { "requires": ">=0.1", "tested": "0.1" },
  "php": ">=8.1",
  "components": {
    "curlRequest": { "files": ["src/Libs/CurlRequest.php"] },
    "aria2":       { "files": ["src/Libs/Aria2.php"] },
    "compreFace": {
      "files": ["src/Libs/CompreFace.php"],
      "require": { "http:curlRequest": ">=0.1" }
    }
  },
  "default": ["curlRequest", "aria2", "compreFace"]
}

• files: archivos (o directorios) que aporta el componente.
• require: dependencias entre componentes, con rangos semver.
• core.requires / core.tested: compatibilidad con el núcleo.
• post-install: comandos de configuración (se muestran y confirman).

Destino de los archivos

• un archivo bajo src/ → ROOT_CORE/ (quitando el prefijo src/);
• cualquier otro archivo → ROOT_DIR/.

Así crypto/src/Libs/Crypto.php → src/Libs/Crypto.php y commands/duckbrain → duckbrain.

Estado del proyecto

• .duckbrain/manifest.json: lo que quieres (restricciones de versión).
• .duckbrain/lock.json: lo que tienes (core y componentes, con versión, commit del toolbox y hash por archivo).

Los hashes permiten detectar ediciones locales. La actualización respeta lo que editaste y te pregunta antes de pisarlo.

Migrar un proyecto existente

Un proyecto que ya tenía Duckbrain y addons copiados a mano entra al toolbox sin perder nada. Clave: adopt no modifica archivos; sólo registra en .duckbrain/lock.json lo que encuentra. Los cambios de contenido los hace update, y sólo cuando tú lo pides.

# 0. Red de seguridad
git add -A && git commit -m "antes de migrar a duckbrain-toolbox"

# 1. Registrar el core y las copias existentes (NO toca archivos)
duckbrain adopt

# 2. Traer lo canónico (y respaldar antes de pisar)
duckbrain update core --backup
duckbrain add http crypto text --backup

# 3. Estado y compatibilidad
duckbrain list
duckbrain doctor

# 4. Commitear la migración
git add -A && git commit -m "migrado a duckbrain-toolbox"

Cómo trata adopt cada archivo:

Caso del archivo	Qué hace adopt	¿Actualiza?
Coincide con el catálogo	Lo registra como adopted	No
Existe pero difiere	Lo registra con origin: local	No
Del core (existe en el core)	Registra el hash actual en lock.core	No
Ajeno al core/addons	No lo toca	No

Las copias divergentes quedan marcadas como edición local: un update posterior te avisa y no las pisa salvo --force o --backup. Así puedes revisar el git diff con calma (por ejemplo, el arreglo de Replacement en multipaste-vip) y decidir cuándo reconciliar. Como un proyecto heredado no tiene hashes previos, --backup respalda también la primera escritura.

Compatibilidad

Cada componente declara hasta qué versión del núcleo fue probado:

  core < requires        avisa "requiere core >=X"
  requires ≤ core ≤ tested   compatible
  core > tested          avisa "no probado"
  sin datos              avisa "sin datos"

Nunca bloquea: se confirma con --yes. Al core se le sigue la pista por sus tags semver (vX.Y.Z, empezando por v0.1.0); si no hay tags, la versión es desconocida y se fija por commit.

Versionado y releases

Cada paquete se versiona de forma independiente con tags prefijados (http-v0.1.0, =crypto-v0.1.0=…). El tag es el descubrimiento; el commit es la identidad, así que el lock pinea commits y no se rompe si un tag se mueve.

El release lo hace un único script:

scripts/release <paquete> <patch|minor|major>

Bumpea la versión del manifiesto, commitea, crea el tag y publica. Las versiones retiradas se listan en yanked.json; las prereleases se omiten salvo --pre.

Pruebas

php tests/run.php

Contacto

Puedes encontrarme en Telegram como @keyjay o por correo: webmaster@outcontrol.net