create-quiver 0.4.0

package/scripts/migrate-project.sh

@@ -0,0 +1,218 @@
+#!/bin/bash
+
+# Script de Migración de Proyecto Existente
+# Uso: ./migrate-project.sh
+# Propósito: Migrar proyecto existente a la nueva estructura de docs-template
+
+set -e
+
+# Colores para output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Función para imprimir mensajes
+print_info() {
+    echo -e "${BLUE}ℹ️  $1${NC}"
+}
+
+print_success() {
+    echo -e "${GREEN}✅ $1${NC}"
+}
+
+print_warning() {
+    echo -e "${YELLOW}⚠️  $1${NC}"
+}
+
+print_error() {
+    echo -e "${RED}❌ $1${NC}"
+}
+
+# Verificar que existe docs/ y docs-template/
+if [ ! -d "docs" ]; then
+    print_error "No se encontró docs/"
+    print_error "Este script es para migrar proyectos existentes"
+    exit 1
+fi
+
+if [ ! -d "docs-template" ]; then
+    print_error "No se encontró docs-template/"
+    print_error "Asegurate de estar en el directorio correcto"
+    exit 1
+fi
+
+print_info "Iniciando migración de documentación..."
+
+# Crear backup
+BACKUP_DIR="docs-backup-$(date +%Y%m%d-%H%M%S)"
+print_info "Creando backup en: $BACKUP_DIR"
+cp -r docs "$BACKUP_DIR"
+print_success "Backup creado: $BACKUP_DIR"
+
+# Crear directorios necesarios
+print_info "Creando nueva estructura..."
+mkdir -p "docs/tools/playwright"
+mkdir -p "docs/archive"
+mkdir -p "docs/archive/analysis"
+
+# ==========================================
+# FASE 1: Mover documentación de herramientas a docs/tools/
+# ==========================================
+print_info "Fase 1: Moviendo documentación de herramientas..."
+
+# Mover archivos de Playwright
+if [ -f "docs/PLAYWRIGHT_CLI_COMMANDS.md" ]; then
+    mv "docs/PLAYWRIGHT_CLI_COMMANDS.md" "docs/tools/playwright/CLI_COMMANDS.md"
+    print_success "Movido: PLAYWRIGHT_CLI_COMMANDS.md → tools/playwright/CLI_COMMANDS.md"
+fi
+
+if [ -f "docs/PLAYWRIGHT_CLI_QWEN_CODE.md" ]; then
+    mv "docs/PLAYWRIGHT_CLI_QWEN_CODE.md" "docs/tools/playwright/QWEN_CODE.md"
+    print_success "Movido: PLAYWRIGHT_CLI_QWEN_CODE.md → tools/playwright/QWEN_CODE.md"
+fi
+
+if [ -f "docs/PLAYWRIGHT_CLI_SKILL.md" ]; then
+    mv "docs/PLAYWRIGHT_CLI_SKILL.md" "docs/tools/playwright/SKILL.md"
+    print_success "Movido: PLAYWRIGHT_CLI_SKILL.md → tools/playwright/SKILL.md"
+fi
+
+if [ -f "docs/PLAYWRIGHT_BEST_PRACTICES.md" ]; then
+    mv "docs/PLAYWRIGHT_BEST_PRACTICES.md" "docs/tools/playwright/BEST_PRACTICES.md"
+    print_success "Movido: PLAYWRIGHT_BEST_PRACTICES.md → tools/playwright/BEST_PRACTICES.md"
+fi
+
+if [ -f "docs/PLAYWRIGHT_CLI_IMPLEMENTATION_PLAN.md" ]; then
+    mv "docs/PLAYWRIGHT_CLI_IMPLEMENTATION_PLAN.md" "docs/archive/PLAYWRIGHT_CLI_IMPLEMENTATION_PLAN.md"
+    print_success "Movido: PLAYWRIGHT_CLI_IMPLEMENTATION_PLAN.md → archive/"
+fi
+
+if [ -f "docs/PLAYWRIGHT_CLI_STATUS.md" ]; then
+    mv "docs/PLAYWRIGHT_CLI_STATUS.md" "docs/archive/PLAYWRIGHT_CLI_STATUS.md"
+    print_success "Movido: PLAYWRIGHT_CLI_STATUS.md → archive/"
+fi
+
+# ==========================================
+# FASE 2: Mover archivos históricos a archive/
+# ==========================================
+print_info "Fase 2: Moviendo archivos históricos a archive/..."
+
+if [ -f "docs/DOCUMENTATION_AUDIT.md" ]; then
+    mv "docs/DOCUMENTATION_AUDIT.md" "docs/archive/DOCUMENTATION_AUDIT.md"
+    print_success "Movido: DOCUMENTATION_AUDIT.md → archive/"
+fi
+
+if [ -f "docs/CLEANUP_SUMMARY.md" ]; then
+    mv "docs/CLEANUP_SUMMARY.md" "docs/archive/CLEANUP_SUMMARY.md"
+    print_success "Movido: CLEANUP_SUMMARY.md → archive/"
+fi
+
+# ==========================================
+# FASE 3: Actualizar INDEX.md con nueva estructura
+# ==========================================
+print_info "Fase 3: Actualizando INDEX.md..."
+
+if [ -f "docs/INDEX.md" ]; then
+    # Agregar sección de tools si no existe
+    if ! grep -q "Tools" "docs/INDEX.md"; then
+        # Buscar la línea de "Histórico" y agregar Tools antes
+        sed -i.bak '/Histórico/i\
+### Herramientas\
+\
+- **[Tools](./tools/)** - Documentación de herramientas (Playwright, ESLint, etc.)\
+' "docs/INDEX.md"
+        rm "docs/INDEX.md.bak" 2>/dev/null || true
+        print_success "Actualizado: INDEX.md (agregada sección Tools)"
+    fi
+fi
+
+# ==========================================
+# FASE 4: Crear README en tools/
+# ==========================================
+print_info "Fase 4: Creando README en tools/..."
+
+if [ ! -f "docs/tools/README.md" ]; then
+    cat > "docs/tools/README.md" << 'EOF'
+# Tools Documentation
+
+Documentación de herramientas específicas del proyecto.
+
+## Herramientas
+
+- **[Playwright](./playwright/)** - Testing E2E
+
+## Agregar Nueva Herramienta
+
+1. Crear directorio: `mkdir docs/tools/[nombre]`
+2. Agregar README.md con documentación
+3. Actualizar este archivo
+
+EOF
+    print_success "Creado: docs/tools/README.md"
+fi
+
+# ==========================================
+# FASE 5: Crear README en archive/
+# ==========================================
+print_info "Fase 5: Creando README en archive/..."
+
+if [ ! -f "docs/archive/README.md" ]; then
+    cat > "docs/archive/README.md" << 'EOF'
+# Archive
+
+Documentación histórica y planes que ya no están activos.
+
+**No leer a menos que sea necesario para contexto histórico.**
+
+## Contenido
+
+- **Analysis** - Análisis y auditorías históricas
+- **Plans** - Planes que ya se ejecutaron o cancelaron
+- **Old Specs** - Specs viejos reemplazados
+
+EOF
+    print_success "Creado: docs/archive/README.md"
+fi
+
+# ==========================================
+# FASE 6: Validar estructura
+# ==========================================
+print_info "Fase 6: Validando estructura..."
+
+echo ""
+print_info "Estructura final:"
+echo ""
+echo "docs/"
+echo "├── Core (activos)"
+echo "│   ├── INDEX.md"
+echo "│   ├── CONTEXTO.md"
+echo "│   ├── STATUS.md"
+echo "│   ├── WORKFLOW.md"
+echo "│   └── ai/"
+echo "├── Tools (herramientas)"
+echo "│   └── playwright/"
+echo "├── Archive (histórico)"
+echo "│   ├── analysis/"
+echo "│   └── [archivos históricos]"
+echo "└── [otros archivos específicos del proyecto]"
+echo ""
+
+# ==========================================
+# Resumen
+# ==========================================
+echo ""
+print_success "¡Migración completada!"
+echo ""
+echo "📁 Resumen de cambios:"
+echo "   - Documentación de herramientas → docs/tools/"
+echo "   - Archivos históricos → docs/archive/"
+echo "   - Backup creado → $BACKUP_DIR"
+echo ""
+echo "📝 Próximos pasos:"
+echo "   1. Verificar que todos los links en INDEX.md funcionen"
+echo "   2. Actualizar referencias a archivos movidos"
+echo "   3. Eliminar backup cuando estés seguro: rm -rf $BACKUP_DIR"
+echo ""
+print_warning "Importante: Verificar que no haya links rotos"
+echo ""

package/scripts/package-quiver.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+temp_root="$(mktemp -d "${TMPDIR:-/tmp}/quiver-pack.XXXXXX")"
+pack_dir="$temp_root/pack"
+npm_cache="$temp_root/npm-cache"
+
+cleanup() {
+  rm -rf "$temp_root"
+}
+
+trap cleanup EXIT
+
+mkdir -p "$pack_dir"
+mkdir -p "$npm_cache"
+
+pack_json="$(
+  cd "$repo_root" && npm_config_cache="$npm_cache" npm pack --json --pack-destination "$pack_dir"
+)"
+
+tarball_name="$(
+  node -e 'const data = JSON.parse(process.argv[1]); process.stdout.write(data[0].filename);' "$pack_json"
+)"
+tarball_path="$pack_dir/$tarball_name"
+
+if [[ ! -f "$tarball_path" ]]; then
+  echo "FAIL: no se encontró el tarball generado en $tarball_path" >&2
+  exit 1
+fi
+
+contents="$(
+  tar -tzf "$tarball_path"
+)"
+
+require_present() {
+  local path="$1"
+
+  if ! printf '%s\n' "$contents" | grep -Fxq "$path"; then
+    echo "FAIL: falta '$path' en el paquete" >&2
+    exit 1
+  fi
+}
+
+require_absent() {
+  local path="$1"
+
+  if printf '%s\n' "$contents" | grep -Fxq "$path"; then
+    echo "FAIL: '$path' no debería publicarse en el paquete" >&2
+    exit 1
+  fi
+}
+
+required_paths=(
+  "package/package.json"
+  "package/bin/create-quiver.js"
+  "package/src/create-quiver/index.js"
+  "package/README.md"
+  "package/README_FOR_AI.md"
+  "package/TEMPLATE.md"
+  "package/LICENSE"
+  "package/CONTRIBUTING.md"
+  "package/CODE_OF_CONDUCT.md"
+  "package/SECURITY.md"
+  "package/CHANGELOG.md"
+  "package/ROADMAP.md"
+  "package/.github/pull_request_template.md"
+  "package/.github/ISSUE_TEMPLATE/bug_report.md"
+  "package/.github/ISSUE_TEMPLATE/feature_request.md"
+  "package/.github/workflows/ci.yml"
+  "package/docs/INDEX.md.template"
+  "package/docs/DOCUMENTATION_GUIDE.md.template"
+  "package/docs/WORKFLOW.md.template"
+  "package/docs/SUPPORT_MATRIX.md.template"
+  "package/docs/TROUBLESHOOTING.md.template"
+  "package/docs/TESTING_GUIDE_FOR_AI.md.template"
+  "package/docs/ai/PRINCIPLES.md"
+  "package/docs/ai/RULES.yaml"
+  "package/docs/ai/LESSONS.md.template"
+  "package/specs/[project-name]/SPEC.md.template"
+  "package/specs/[project-name]/STATUS.md.template"
+  "package/specs/[project-name]/EVIDENCE_REPORT.md.template"
+  "package/specs/[project-name]/slices/pr.md.template"
+  "package/specs/[project-name]/slices/slice-template/slice.json"
+  "package/scripts/init-docs.sh"
+  "package/scripts/start-slice.sh"
+  "package/scripts/check-slice-readiness.sh"
+  "package/scripts/check-pr-readiness.sh"
+  "package/scripts/check-scope.sh"
+  "package/scripts/cleanup-slice.sh"
+  "package/scripts/release-quiver.sh"
+  "package/scripts/refresh-active-slices.sh"
+  "package/scripts/migrate-project.sh"
+  "package/scripts/package-quiver.sh"
+  "package/i18n/es/README.md"
+  "package/i18n/es/README_FOR_AI.md"
+  "package/i18n/es/TEMPLATE.md"
+)
+
+for path in "${required_paths[@]}"; do
+  require_present "$path"
+done
+
+excluded_paths=(
+  "package/package-lock.json"
+  "package/tests/"
+  "package/examples/"
+  "package/.worktrees/"
+  "package/specs/quiver-v01/"
+  "package/specs/quiver-v02-bootstrap-hardening/"
+  "package/specs/quiver-v03-adoption-verification/"
+  "package/specs/quiver-v04-zero-friction-installation/"
+  "package/scripts/ci/"
+)
+
+for path in "${excluded_paths[@]}"; do
+  if printf '%s\n' "$contents" | grep -Fq "$path"; then
+    echo "FAIL: el paquete incluye contenido fuera del contrato: $path" >&2
+    exit 1
+  fi
+done
+
+printf 'Package smoke passed: %s\n' "$tarball_name"

package/scripts/refresh-active-slices.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+output_path="$repo_root/ACTIVE_SLICES.md"
+
+append_unique_line() {
+  local file_path="$1"
+  local line="$2"
+
+  touch "$file_path"
+
+  if ! grep -Fxq "$line" "$file_path"; then
+    printf '%s\n' "$line" >> "$file_path"
+  fi
+}
+
+exclude_path="$(git -C "$repo_root" rev-parse --git-path info/exclude)"
+append_unique_line "$exclude_path" "ACTIVE_SLICES.md"
+
+node - "$repo_root" "$output_path" <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const cp = require('child_process');
+
+const [repoRoot, outputPath] = process.argv.slice(2);
+
+function run(cmd) {
+  return cp.execSync(cmd, {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+}
+
+function walkSlices(rootDir, acc) {
+  if (!fs.existsSync(rootDir)) {
+    return;
+  }
+
+  for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+    const fullPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      walkSlices(fullPath, acc);
+      continue;
+    }
+
+    if (entry.isFile() && entry.name === 'slice.json' && fullPath.includes(`${path.sep}slices${path.sep}`)) {
+      const json = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+      const relPath = path.relative(repoRoot, fullPath);
+      const parts = relPath.split(path.sep);
+      const specFamily = parts[0];
+      const specSlug = parts[1];
+      const branchName = json.git?.branch_name;
+      if (!branchName) {
+        continue;
+      }
+
+      acc.set(branchName, {
+        specFamily,
+        specSlug,
+        relPath,
+        sliceId: json.slice_id || path.basename(path.dirname(fullPath)),
+        title: json.title || json.slice_id || path.basename(path.dirname(fullPath)),
+        ticket: json.ticket || '',
+        status: json.status || 'pending'
+      });
+    }
+  }
+}
+
+function parseWorktrees(text) {
+  const entries = [];
+  const chunks = text.trim().split('\n\n').filter(Boolean);
+  for (const chunk of chunks) {
+    const lines = chunk.split('\n');
+    const entry = {};
+    for (const line of lines) {
+      const idx = line.indexOf(' ');
+      if (idx === -1) {
+        continue;
+      }
+      const key = line.slice(0, idx);
+      const value = line.slice(idx + 1);
+      entry[key] = value;
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+
+function toAlias(ticket) {
+  const parts = String(ticket || '').split('-').filter(Boolean);
+  const prefix = (parts[0] || 'GEN').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
+  const suffix = (parts[parts.length - 1] || '00').replace(/[^A-Za-z0-9]/g, '').toUpperCase();
+  const short = prefix.length <= 3 ? prefix : prefix.slice(0, 3);
+  return `${short || 'GEN'}-${suffix || '00'}`;
+}
+
+function mdEscape(value) {
+  return String(value ?? '').replace(/\|/g, '\\|');
+}
+
+const sliceMap = new Map();
+walkSlices(path.join(repoRoot, 'specs'), sliceMap);
+walkSlices(path.join(repoRoot, 'specs-fix'), sliceMap);
+
+const worktrees = parseWorktrees(run('git worktree list --porcelain'));
+
+const primary = [];
+const active = [];
+const frozen = [];
+const auxiliary = [];
+
+for (const entry of worktrees) {
+  const worktreePath = entry.worktree;
+  const branchRef = entry.branch || '';
+  const branchName = branchRef.replace('refs/heads/', '');
+
+  if (worktreePath === repoRoot) {
+    primary.push({
+      branch: branchName || '(detached)',
+      path: worktreePath
+    });
+    continue;
+  }
+
+  const slice = sliceMap.get(branchName);
+  if (!slice) {
+    auxiliary.push({
+      branch: branchName || '(detached)',
+      path: worktreePath
+    });
+    continue;
+  }
+
+  let liveStatus = slice.status;
+  const liveSlicePath = path.join(worktreePath, slice.relPath);
+  if (fs.existsSync(liveSlicePath)) {
+    try {
+      const liveJson = JSON.parse(fs.readFileSync(liveSlicePath, 'utf8'));
+      liveStatus = liveJson.status || liveStatus;
+    } catch {}
+  }
+
+  const row = {
+    alias: toAlias(slice.ticket),
+    spec: slice.specSlug,
+    slice: slice.sliceId,
+    branch: branchName,
+    path: worktreePath,
+    status: liveStatus,
+    title: slice.title
+  };
+
+  if (slice.sliceId.startsWith('slice-00')) {
+    frozen.push(row);
+  } else {
+    active.push(row);
+  }
+}
+
+active.sort((a, b) => a.alias.localeCompare(b.alias));
+frozen.sort((a, b) => a.alias.localeCompare(b.alias));
+auxiliary.sort((a, b) => a.branch.localeCompare(b.branch));
+
+const lines = [
+  '# Active Slices',
+  '',
+  '> Archivo local generado por `tools/scripts/refresh-active-slices.sh`.',
+  '> No se trackea en git.',
+  '',
+  `**Actualizado:** ${new Date().toISOString()}`,
+  '',
+  '## Convencion',
+  '',
+  '- `Alias`: identificador corto para hablar del slice sin ambiguedad',
+  '- `Spec`: directorio del spec',
+  '- `slice-00`: baseline congelado, solo referencia',
+  '- `slice-01+`: implementacion o revalidacion',
+  '',
+  '## Checkout Principal',
+  '',
+  '| Branch | Path |',
+  '|--------|------|'
+];
+
+for (const row of primary) {
+  lines.push(`| ${mdEscape(row.branch)} | ${mdEscape(row.path)} |`);
+}
+
+lines.push('', '## Implementacion Activa', '', '| Alias | Spec | Slice | Branch | Estado | Path |', '|-------|------|-------|--------|--------|------|');
+if (active.length === 0) {
+  lines.push('| - | - | - | - | - | - |');
+} else {
+  for (const row of active) {
+    lines.push(`| ${mdEscape(row.alias)} | ${mdEscape(row.spec)} | ${mdEscape(row.slice)} | ${mdEscape(row.branch)} | ${mdEscape(row.status)} | ${mdEscape(row.path)} |`);
+  }
+}
+
+lines.push('', '## Baselines Congelados', '', '| Alias | Spec | Slice | Branch | Estado | Path |', '|-------|------|-------|--------|--------|------|');
+if (frozen.length === 0) {
+  lines.push('| - | - | - | - | - | - |');
+} else {
+  for (const row of frozen) {
+    lines.push(`| ${mdEscape(row.alias)} | ${mdEscape(row.spec)} | ${mdEscape(row.slice)} | ${mdEscape(row.branch)} | congelado | ${mdEscape(row.path)} |`);
+  }
+}
+
+lines.push('', '## Worktrees Auxiliares', '', '| Branch | Path |', '|--------|------|');
+if (auxiliary.length === 0) {
+  lines.push('| - | - |');
+} else {
+  for (const row of auxiliary) {
+    lines.push(`| ${mdEscape(row.branch)} | ${mdEscape(row.path)} |`);
+  }
+}
+
+lines.push(
+  '',
+  '## Recomendacion Operativa',
+  '',
+  '- En VS Code, dejar visibles solo `develop` y la tabla de `Implementacion Activa`.',
+  '- Tratar la tabla de `Baselines Congelados` como solo lectura.',
+  '- Cerrar visualmente los `Worktrees Auxiliares` salvo cuando estes trabajando ese PR o esa tarea de proceso.'
+);
+
+fs.writeFileSync(outputPath, `${lines.join('\n')}\n`);
+NODE
+
+printf 'Active slices refreshed: %s\n' "$output_path"

package/scripts/release-quiver.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+release_type="patch"
+publish="false"
+publish_current="false"
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/release-quiver.sh [patch|minor|major|x.y.z] [--publish | --publish-current]
+
+By default the script performs a release dry run:
+  - validates the installer smoke
+  - validates the package artifact
+  - prints the versioning and publish commands to run next
+
+Pass --publish to run npm version and npm publish after the smoke checks pass.
+Pass --publish-current to publish the current package version without forcing a patch bump.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --publish)
+      publish="true"
+      shift
+      ;;
+    --publish-current)
+      publish_current="true"
+      publish="true"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      release_type="$1"
+      shift
+      ;;
+  esac
+done
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "FAIL: release requires a clean worktree" >&2
+  exit 1
+fi
+
+bash scripts/ci/smoke-create-quiver.sh
+bash scripts/package-quiver.sh
+
+if [[ "$publish" == "false" ]]; then
+  echo "Release dry run passed."
+  echo "Next commands:"
+  if [[ "$publish_current" == "true" ]]; then
+    echo "  npm publish --access public"
+  else
+    echo "  npm version $release_type -m \"chore(release): %s\""
+    echo "  npm publish --access public"
+  fi
+  echo "  git push origin HEAD --tags"
+  exit 0
+fi
+
+if [[ "$publish_current" == "true" ]]; then
+  npm publish --access public
+  git push origin HEAD --tags
+  exit 0
+fi
+
+npm version "$release_type" -m "chore(release): %s"
+npm publish --access public
+git push origin HEAD --tags