@envisiongroup/create-ditto

Bootstrap CLI (fase núcleo) para materializar shells cliente de Ditto desde un blueprint ya generado.

Uso

create-ditto <nombre-del-proyecto> [opciones]
create-ditto --help

Sin flags suficientes y en una terminal interactiva, el CLI muestra el logo ASCII y abre un wizard navegable con ↑/↓ y Enter (ES/EN según LANG, respeta NO_COLOR, exige Node >= 22). Con --yes, --no-input o --config corre en modo no interactivo.

Opciones

Proyecto:

• --package-name <nombre> — nombre npm del paquete generado (privado).
• --target-directory <ruta> — carpeta destino (por defecto: slug del nombre).
• --package-manager <pnpm|npm> — gestor de paquetes (por defecto: pnpm).
• --auth-mode <none|microsoft|custom> — modo de auth del shell.
• --locale <es|en> — locale del shell generado (metadato del proyecto; no cambia el idioma de los mensajes del CLI).
• --dry-run — previsualiza sin escribir archivos.
• --config <ruta> — archivo JSON de configuración.

Interacción / validación:

• --yes / -y — acepta defaults, sin wizard.
• --no-input / --non-interactive — fuerza modo no interactivo.
• --verify — corre el pipeline de validación install→typecheck→test→build tras generar (opt-in; por defecto el CLI solo scaffoldea y queda NO verificada).

Registry / NPM_TOKEN:

• --registry <url> — registry del paquete privado Ditto (por defecto: npm público).
• --blueprint-registry <url> — registry del blueprint (por defecto: npm público).
• --scope <@scope> — scope privado (por defecto: @envisiongroup).
• --npm-token-mode <required|optional|disabled> (por defecto: optional).
• --require-npm-token / --optional-npm-token / --no-npm-token — atajos.
• --blueprint-version <x.y.z> — fija la versión del blueprint a descargar (por defecto usa la misma versión del CLI).

Además soporta --blueprint-root para apuntar al artifact local del blueprint durante el desarrollo interno (si no se provee y no hay artifact local, el CLI descarga el blueprint público desde --blueprint-registry).

Descarga segura del blueprint (ADR 0021)

El blueprint (@envisiongroup/ditto-blueprint) es público, así que su descarga no requiere token. Cuando el blueprint no está disponible localmente, el CLI:

1. Si hay NPM_TOKEN en el entorno, crea un userconfig npm temporal con el token real y lo elimina siempre (incluso ante error); nunca toca el ~/.npmrc global. Sin token, descarga el blueprint público sin auth.
2. Descarga desde --blueprint-registry y verifica la versión del blueprint. Por defecto fija la misma versión del CLI para evitar que un CLI antiguo consuma accidentalmente un schema latest incompatible. El CLI no sondea @envisiongroup/ditto: como solo scaffoldea, el acceso real al paquete privado lo valida el npm install del desarrollador.)
3. Redacta cualquier token en logs, errores y diagnósticos.

El token no se necesita para generar la shell: se difiere al pnpm install del proyecto generado (que instala el paquete privado @envisiongroup/ditto).

Pipeline de validación de cierre (Fase 6)

Por defecto el CLI solo scaffoldea el directorio del proyecto (estilo create-mastra): no instala dependencias ni corre scripts. El desarrollador hace el npm install/pnpm install a mano después. El estado queda NO verificada.

Si querés que el CLI valide el proyecto generado end-to-end (p. ej. en CI), pasá --verify: corre install → assets → typecheck → test → build (según los scripts presentes). Si un paso falla: conserva la salida, marca NO verificada y muestra el comando exacto para reintentar.

Política de NPM_TOKEN

Por defecto (optional) el CLI no exige NPM_TOKEN para generar la shell: lo difiere al pnpm install del proyecto generado, que sí lo necesita para instalar el paquete privado @envisiongroup/ditto. El token nunca se persiste: el .npmrc generado usa el placeholder ${NPM_TOKEN}, que se resuelve desde el entorno al instalar.

• optional (default): no pide token durante el wizard; genera el .npmrc con el placeholder. Ideal para distribuir la shell y que el dev complete el token al instalar.
• required: exige el token (env o wizard con entrada oculta) antes de generar. Útil si querés asegurar que el dev tiene acceso antes de empezar.
• disabled: no genera línea de token (Ditto público).

.npmrc generado según el escenario:

| Modo | Registry | .npmrc generado | | ----------------- | -------------- | --------------------------------------------- | | required/optional | privado | scope→registry + :_authToken=${NPM_TOKEN} | | required/optional | npm público | igual (flujo normal: Ditto restricted en npm) | | disabled | privado/custom | scope→registry (sin auth) | | disabled | npm público | no se genera .npmrc (instala directo) |

El warning “registry público + token” solo aparece en modo required (allí sí es sospechoso). En optional es el flujo esperado.

Si Ditto llega a publicarse público, podés deshabilitar el token:

create-ditto "Mi Shell" --no-npm-token

Nunca incluyas NPM_TOKEN dentro del archivo de --config: el CLI lo rechaza.