create-arriero 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 picito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# create-arriero
+
+Asistente que arma el flujo gobernado de Arriero en un proyecto nuevo o existente: escribe la configuración, el
+registro de lecciones, los roles de agentes y los git hooks.
+
+## Instalación
+
+```
+npm create arriero@latest
+# o
+npx create-arriero
+```
+
+Después, en el repo de docs del proyecto, la CLI queda como dependencia de desarrollo:
+
+```
+npm install -D arriero
+```
+
+## Requisitos
+
+- Node 20 o superior.
+- git.
+- La CLI de [OpenSpec](https://github.com/Fission-AI/OpenSpec).
+
+## Más información
+
+El detalle del flujo, la configuración (`arriero.config.json`) y los comandos está en el README del repositorio de
+Arriero.

package/index.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// Asistente: arma el flujo gobernado de arriero en un proyecto nuevo o existente.
+// Escribe arriero.config.json en el repo de docs, crea el registro de lecciones e instala los git hooks
+// en los repos de código (o en el propio repo, en un proyecto de un solo repo). No toca nada sin confirmación.
+//
+// Sin terminal (CI, un agente), `--si` responde cada pregunta con su flag o con el valor por defecto:
+//   npx create-arriero --si --docs ../demo-docs --repos demo-api,demo-web --herramientas claude
+//   npx create-arriero --si --unico --docs .     (proyecto de un solo repo: docs y código juntos)
+//   flags: --docs --proyecto --repos --integracion --produccion --registro --herramientas --unico --sin-carril --reemplazar
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { execSync } from 'node:child_process';
+import * as p from '@clack/prompts';
+import {
+  ARCHIVO, DEFECTOS, conDefectos, validarConfig, cargarContexto, git, instalarHooks, PLANTILLA_REGISTRO,
+  STACKS, HERRAMIENTAS, detectarStack, leerManifiestos, planAgentes, escribirAgentes,
+} from 'arriero';
+
+const salir = (v) => { if (p.isCancel(v)) { p.cancel('Sin cambios.'); process.exit(0); } return v; };
+const lista = (t) => t.split(',').map((x) => x.trim()).filter(Boolean);
+
+const { values: F } = parseArgs({
+  options: Object.fromEntries([
+    ...['docs', 'proyecto', 'repos', 'integracion', 'produccion', 'registro', 'herramientas'].map((k) => [k, { type: 'string' }]),
+    ...['si', 'unico', 'sin-carril', 'reemplazar'].map((k) => [k, { type: 'boolean' }]),
+  ]),
+});
+
+/**
+ * Las preguntas del asistente. Con `--si` no pregunta: usa el valor del flag (si lo hay) o el inicial,
+ * y lo valida igual que en la terminal.
+ */
+const preguntar = {
+  async text(o, flag) {
+    if (!F.si) return p.text(o);
+    const v = flag ?? o.initialValue ?? '';
+    const error = o.validate?.(v);
+    if (error) { p.cancel(`${o.message}: ${error} ("${v}")`); process.exit(1); }
+    p.log.step(`${o.message}: ${v || '—'}`);
+    return v;
+  },
+  async confirm(o, flag) {
+    if (!F.si) return p.confirm(o);
+    const v = flag ?? o.initialValue ?? true;
+    p.log.step(`${o.message} ${v ? 'sí' : 'no'}`);
+    return v;
+  },
+  async select(o, flag) {
+    if (!F.si) return p.select(o);
+    const v = flag ?? o.initialValue ?? o.options[0].value;
+    p.log.step(`${o.message}: ${o.options.find((x) => x.value === v)?.label ?? v}`);
+    return v;
+  },
+  async multiselect(o, flag) {
+    if (!F.si) return p.multiselect(o);
+    const v = flag ?? o.initialValues ?? [];
+    p.log.step(`${o.message}: ${v.join(', ') || '—'}`);
+    return v;
+  },
+};
+
+/** Comandos de verificación sugeridos a partir de los scripts del package.json del repo. */
+function verificarSugerido(dir) {
+  try {
+    const { scripts = {} } = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return ['lint', 'test', 'build'].filter((s) => scripts[s]).map((s) => ({ nombre: s, comando: s === 'test' ? 'npm test --silent' : `npm run ${s}` }));
+  } catch { return []; }
+}
+
+/** Comandos de verificación y tecnologías de un repo con código (`dir`), preguntados con su `nombre`. */
+async function datosDeCodigo(dir, nombre) {
+  const comandos = salir(await preguntar.text({
+    message: `Comandos que ${nombre} debe pasar al verificar (separados por coma; vacío = ninguno)`,
+    initialValue: verificarSugerido(dir).map((v) => v.comando).join(', '),
+  }));
+  const detectado = detectarStack(leerManifiestos(dir));
+  const stack = salir(await preguntar.multiselect({
+    message: `Tecnologías de ${nombre} (detectadas: ${detectado.join(', ') || 'ninguna'}). Arman sus roles; ajusta si hace falta`,
+    options: STACKS.map((s) => ({ value: s.id, label: s.nombre, hint: s.capa ?? undefined })),
+    initialValues: detectado,
+    required: false,
+  }));
+  return { stack, verificar: lista(comandos || '').map((comando) => ({ nombre: comando.replace(/^npm (run )?/, '').replace(/ --silent$/, ''), comando })) };
+}
+
+// Instrucciones y permisos de los agentes de IA, de cualquier herramienta: un agente no se afloja sus propias reglas.
+const AGENTES = { regla: 'instrucciones y permisos de los agentes', rutas: ['AGENTS.md', '**/AGENTS.md', 'agents/**', 'CLAUDE.md', '.claude/**', 'GEMINI.md', '.gemini/**', '.cursor/**', '.cursorrules', '.windsurf/**', '.clinerules', '.github/copilot-instructions.md'] };
+const PROHIBIDO_CODIGO = [{ regla: 'dependencias, entorno y CI', rutas: ['package.json', 'package-lock.json', '.env*', '.githooks/**', '.github/**'] }, AGENTES];
+// Rutas de riesgo de cada repo de código: nunca entran por el carril rápido ni las cubre la preautorización.
+const RIESGO_CODIGO = [
+  { regla: 'base de datos', rutas: ['**/migrations/**', '**/migraciones/**', '**/*.sql', '**/schema.prisma'] },
+  { regla: 'autenticación y permisos', rutas: ['**/auth/**', '**/autenticacion/**'] },
+  { regla: 'pagos', rutas: ['**/pagos/**', '**/payments/**', '**/billing/**', '**/facturacion/**'] },
+];
+const PROHIBIDO_DOCS = [{ regla: 'flujo, decisiones y reglas', rutas: [ARCHIVO, 'openspec/specs/**', 'releases/**'] }, AGENTES];
+
+async function main() {
+  p.intro('create-arriero · flujo gobernado para agentes de IA');
+  if (F.unico && F.repos) { p.cancel('--repos no aplica en un proyecto de un solo repo'); process.exit(1); }
+
+  const docs = path.resolve(salir(await preguntar.text({
+    message: 'Carpeta del repo de docs, o del repo único (donde viven openspec/ y arriero.config.json)',
+    initialValue: process.cwd(),
+    validate: (v) => (v && fs.existsSync(v) ? undefined : 'No existe esa carpeta'),
+  }, F.docs)));
+  const raiz = path.dirname(docs);
+  if (!git(docs, 'rev-parse --git-dir')) {
+    if (!salir(await preguntar.confirm({ message: `${docs} no es un repo git. ¿Lo inicializo (git init)?` }))) return p.cancel('El repo de docs tiene que ser un repo git.');
+    execSync('git init -q', { cwd: docs });
+  }
+  const previo = fs.existsSync(path.join(docs, ARCHIVO));
+  if (previo && !salir(await preguntar.confirm({ message: `Ya existe ${ARCHIVO}. ¿Lo reemplazo?`, initialValue: false }, F.reemplazar))) return p.cancel('Sin cambios.');
+
+  const hermanas = fs.readdirSync(raiz, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name !== path.basename(docs) && fs.existsSync(path.join(raiz, e.name, '.git')))
+    .map((e) => e.name);
+  // Lo habitual son varios repos (docs, BE, FE): es el valor inicial aunque aún no haya hermanas, porque el repo de
+  // docs suele crearse antes que los de código. El modo único se elige a propósito.
+  const unico = salir(await preguntar.select({
+    message: '¿Cómo está organizado el proyecto?',
+    options: [
+      { value: 'varios', label: `Varios repos: docs y repos de código hermanos en ${raiz}, p. ej. BE y FE` },
+      { value: 'unico', label: 'Un solo repo: docs y código juntos' },
+    ],
+    initialValue: F.unico ? 'unico' : 'varios',
+  }, F.unico ? 'unico' : undefined)) === 'unico';
+
+  const proyecto = salir(await preguntar.text({ message: 'Nombre del proyecto', initialValue: path.basename(docs).replace(/[-_]?docs$/i, '') || path.basename(docs) }, F.proyecto));
+  const claveDocs = salir(await preguntar.text({
+    message: unico ? 'Clave del repo (mayúsculas)' : 'Clave del repo de docs (mayúsculas)',
+    initialValue: unico ? 'APP' : 'DOCS',
+    validate: (v) => (/^[A-Z][A-Z0-9_]*$/.test(v) ? undefined : 'Mayúsculas, números o _'),
+  }));
+  const repos = { [claveDocs]: unico
+    ? { tipo: 'unico', carpetas: [path.basename(docs)], ...await datosDeCodigo(docs, path.basename(docs)) }
+    : { tipo: 'docs', carpetas: [path.basename(docs)] } };
+
+  const noEsta = F.repos ? lista(F.repos).filter((r) => !hermanas.includes(r)) : [];
+  if (noEsta.length) { p.cancel(`--repos: ${noEsta.join(', ')} no es un repo git hermano en ${raiz}`); process.exit(1); }
+  const elegidas = !unico && hermanas.length
+    ? salir(await preguntar.multiselect({ message: `Repos de código (carpetas hermanas en ${raiz})`, options: hermanas.map((h) => ({ value: h, label: h })), required: false }, F.repos && lista(F.repos)))
+    : [];
+  for (const carpeta of elegidas) {
+    const sugerida = carpeta.replace(/^.*[-_]/, '').toUpperCase().replace(/[^A-Z0-9_]/g, '').slice(0, 12) || 'APP';
+    const clave = salir(await preguntar.text({
+      message: `Clave de ${carpeta}`,
+      initialValue: repos[sugerida] ? `${sugerida}2` : sugerida,
+      validate: (v) => (!/^[A-Z][A-Z0-9_]*$/.test(v) ? 'Mayúsculas, números o _' : repos[v] ? 'Clave repetida' : undefined),
+    }));
+    repos[clave] = { carpetas: [carpeta], ...await datosDeCodigo(path.join(raiz, carpeta), carpeta) };
+  }
+
+  const integracion = salir(await preguntar.text({ message: 'Rama de integración (a la que entra cada slice aprobado)', initialValue: DEFECTOS.ramas.integracion }, F.integracion));
+  const produccion = lista(salir(await preguntar.text({ message: 'Ramas de producción (separadas por coma)', initialValue: DEFECTOS.ramas.produccion.join(', ') }, F.produccion)));
+  // El carril rápido aún no está disponible en un proyecto de un solo repo.
+  const conCarril = !unico && salir(await preguntar.confirm({ message: '¿Activar el carril rápido para cambios pequeños (textos, estilos)?', initialValue: true }, F['sin-carril'] ? false : undefined));
+  const registro = salir(await preguntar.text({ message: 'Registro de lecciones (ruta dentro del repo de docs)', initialValue: DEFECTOS.lecciones.registro }, F.registro));
+  const herramientas = salir(await preguntar.multiselect({
+    message: 'Herramientas de IA del equipo que necesitan adaptador (AGENTS.md ya lo leen Codex, Cursor, Copilot y otras)',
+    options: Object.entries(HERRAMIENTAS).map(([id, h]) => ({ value: id, label: h.nombre })),
+    required: false,
+  }, F.herramientas && lista(F.herramientas)));
+
+  const cfg = {
+    $schema: './node_modules/arriero/arriero.config.schema.json',
+    proyecto,
+    repos,
+    ramas: { integracion, produccion, prefijos: DEFECTOS.ramas.prefijos },
+    lecciones: { registro },
+    agentes: { herramientas },
+    // En modo único el repo único es el de código.
+    riesgo: Object.fromEntries(Object.keys(repos).filter((k) => unico || k !== claveDocs).map((k) => [k, RIESGO_CODIGO])),
+    ...(conCarril && {
+      carrilRapido: {
+        limites: DEFECTOS.limitesCarril,
+        prohibido: Object.fromEntries(Object.keys(repos).map((k) => [k, k === claveDocs ? PROHIBIDO_DOCS : PROHIBIDO_CODIGO])),
+      },
+    }),
+  };
+  const errores = validarConfig(conDefectos(cfg));
+  if (errores.length) return p.cancel(`La configuración no es válida:\n  - ${errores.join('\n  - ')}`);
+
+  const codigo = Object.keys(repos).filter((k) => k !== claveDocs);
+  p.note(`${Object.entries(repos).map(([k, r]) => `${k.padEnd(6)} ${r.carpetas[0]}${r.tipo === 'docs' ? ' (docs)' : `${r.tipo === 'unico' ? ' (un solo repo)' : ''} · ${r.stack.join(', ') || 'sin stack'}`}`).join('\n')}\n\nIntegración: ${integracion} · Producción: ${produccion.join(', ')}\nCarril rápido: ${conCarril ? 'sí' : 'no'} · Lecciones: ${registro}\nAdaptadores: ${herramientas.map((h) => HERRAMIENTAS[h].nombre).join(', ') || 'solo AGENTS.md'}`, 'Resumen');
+  const confirmacion = unico
+    ? `¿Escribo ${ARCHIVO} y los roles de agentes, e instalo los git hooks en este repo? (no reemplazo archivos que ya existan)`
+    : `¿Escribo ${ARCHIVO} y los roles de agentes${codigo.length ? ', e instalo los git hooks en los repos de código' : ''}? (no reemplazo archivos que ya existan)`;
+  if (!salir(await preguntar.confirm({ message: confirmacion }))) return p.cancel('Sin cambios.');
+
+  fs.writeFileSync(path.join(docs, ARCHIVO), JSON.stringify(cfg, null, 2) + '\n');
+  p.log.success(`${ARCHIVO} escrito`);
+  const fRegistro = path.join(docs, registro);
+  if (!fs.existsSync(fRegistro)) {
+    fs.mkdirSync(path.dirname(fRegistro), { recursive: true });
+    fs.writeFileSync(fRegistro, PLANTILLA_REGISTRO);
+    p.log.success(`${registro} creado`);
+  }
+
+  // En modo único los hooks van en el propio repo (ARRIERO_DOCS=".").
+  const destinos = unico
+    ? [{ dir: docs, nombre: path.basename(docs) }]
+    : codigo.map((k) => ({ dir: path.join(raiz, repos[k].carpetas[0]), nombre: repos[k].carpetas[0] }));
+  for (const { dir, nombre } of destinos) {
+    const { instalados, saltados, otroHooksPath, errores } = unico ? instalarHooks(dir, docs, integracion) : instalarHooks(dir, docs);
+    if (otroHooksPath) { p.log.warn(`${nombre}: core.hooksPath ya es "${otroHooksPath}"; no instalé los hooks. Llama a "arriero hook <modo>" desde los tuyos.`); continue; }
+    if (instalados.length) p.log.success(errores.length
+      ? `${nombre}: hooks escritos en .githooks (${instalados.join(', ')})`
+      : `${nombre}: hooks instalados (${instalados.join(', ')}) y en el stage con bit de ejecución; .gitattributes con LF para .githooks`);
+    for (const e of errores) p.log.error(`${nombre}: ${e}`);
+    if (saltados.length) p.log.warn(`${nombre}: ya tenía ${saltados.join(', ')} en .githooks; no los reemplacé. Agrega "arriero hook <modo>" a mano.`);
+  }
+
+  const { creados, existentes } = escribirAgentes(planAgentes(cargarContexto({ desde: docs, env: {} })));
+  p.log.success(`Agentes: ${creados.length} archivos creados (AGENTS.md, agents/*.md${herramientas.length ? ' y adaptadores' : ''})`);
+  if (existentes.length) p.log.info(`Ya existían y no los toqué: ${existentes.join(', ')}`);
+
+  const q = (s) => (/\s/.test(s) ? `"${s}"` : s); // rutas con espacios, para copiar y pegar
+  const adaptadores = herramientas.map((h) => HERRAMIENTAS[h].raiz.archivo);
+  const instalacion = ['.githooks', '.gitattributes', 'AGENTS.md', 'agents', ...adaptadores, ...(herramientas.includes('claude') ? ['.claude'] : [])];
+  const sinVerificar = `git commit --no-verify -m "chore: instalar arriero"   # única excepción: los hooks rechazan commits en ${integracion}`;
+
+  if (unico) {
+    const prefijo = DEFECTOS.ramas.prefijos[0];
+    // Sin commits, HEAD ya puede ser la rama de integración (git init -b develop): ahí no hace falta cambiar de rama.
+    const enIntegracion = git(docs, 'symbolic-ref --short HEAD') === integracion;
+    const existe = git(docs, `rev-parse --verify --quiet refs/heads/${integracion}`) !== null;
+    const pasos = [
+      `cd ${q(docs)}`,
+      'npm install -D arriero        # los hooks lo buscan en node_modules de este repo',
+      ...(git(docs, 'check-ignore -q node_modules') === null ? ['agregar node_modules/ al .gitignore'] : []),
+      ...(fs.existsSync(path.join(docs, 'openspec')) ? [] : ['openspec init                  # el flujo usa OpenSpec para las propuestas']),
+      ...(enIntegracion ? [] : [`git switch ${existe ? '' : '-c '}${integracion}`]),
+      'completar "## Propio del proyecto" en AGENTS.md y en cada agents/*.md',
+      `git add ${[ARCHIVO, q(registro), ...instalacion].join(' ')}`,
+      sinVerificar,
+      `git switch -c ${prefijo}/<cambio> ${integracion}        # cada slice vive en su rama`,
+      'arriero                       # guía del día a día',
+    ];
+    p.note(pasos.join('\n'), 'Siguientes pasos');
+    return p.outro('Listo. Regla del camino: nada se programa sin una propuesta aprobada.');
+  }
+
+  const pasos = [
+    `cd ${q(docs)}`,
+    'npm install -D arriero        # los hooks lo buscan en node_modules del repo de docs',
+    ...(fs.existsSync(path.join(docs, 'openspec')) ? [] : ['openspec init                  # el flujo usa OpenSpec para las propuestas']),
+    'completar "## Propio del proyecto" en cada agents/*.md',
+    // Con claude, docs lleva .claude/settings.json del orquestador (acceso a los repos de código y permisos del loop).
+    `git add ${[ARCHIVO, q(registro), 'AGENTS.md', ...adaptadores, ...(herramientas.includes('claude') ? ['.claude'] : [])].join(' ')}`,
+    'git commit -m "chore: instalar arriero"',
+    // Rutas relativas al repo de docs: los repos de código son sus hermanos, así que cada línea vale tras la anterior.
+    ...codigo.map((k) => `cd ${q(`../${repos[k].carpetas[0]}`)} && git add ${instalacion.join(' ')} && ${sinVerificar}`),
+    ...(codigo.length ? [`cd ${q(`../${path.basename(docs)}`)}`] : []),
+    'arriero                       # guía del día a día',
+  ];
+  p.note(pasos.join('\n'), 'Siguientes pasos');
+  p.outro('Listo. Regla del camino: nada se programa sin una propuesta aprobada.');
+}
+
+await main();

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "create-arriero",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Asistente que arma el flujo gobernado de Arriero en un proyecto nuevo o existente.",
+  "keywords": [
+    "agents",
+    "ai",
+    "workflow",
+    "openspec",
+    "git-hooks",
+    "create"
+  ],
+  "author": "picito <csanchezrive@gmail.com>",
+  "type": "module",
+  "bin": {
+    "create-arriero": "index.mjs"
+  },
+  "files": [
+    "index.mjs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "arriero": "0.1.0"
+  }
+}