slicejs-cli 3.1.0 → 3.3.0

package/docs/superpowers/specs/2026-05-10-pwa-generate-design.md

@@ -0,0 +1,182 @@
+# Diseno de `slice generate-pwa` (V1)
+
+## Objetivo
+
+Agregar un comando dedicado de CLI, `slice generate-pwa`, que convierta un build de Slice en una PWA usable offline, con estrategia de cache configurable y exclusion explicita de dominios de backend para evitar cache accidental de APIs REST.
+
+El comando debe ser postbundle, operar sobre `dist/` y mantener una experiencia simple de V1.
+
+## Alcance V1
+
+- Nuevo comando `slice generate-pwa`.
+- Ejecutar `build` automaticamente antes del proceso PWA.
+- Generar `manifest.json` en `dist/`.
+- Generar `sw.js` en `dist/`.
+- Registrar Service Worker en el HTML de entrada de `dist`.
+- Soportar estrategias: `hybrid` (default), `offline-first`, `network-first`.
+- Persistir y leer configuracion desde `src/sliceConfig.json` en:
+  - `pwa.cache.excludeDomains`.
+- Aplicar exclusion efectiva de `localhost` y `127.0.0.1` en desarrollo.
+
+## Fuera de alcance V1
+
+- Exclusion por paths o headers (`excludePaths`, `excludeHeaders`).
+- UI interactiva avanzada para crear iconos PWA.
+- Soporte de push notifications, background sync o runtime caching avanzado por tipo de API.
+- Plugin system formal; se deja preparado para evolucion futura.
+
+## UX del comando
+
+### Sintaxis
+
+```bash
+slice generate-pwa
+slice generate-pwa --strategy hybrid
+slice generate-pwa --strategy offline-first
+slice generate-pwa --strategy network-first
+slice generate-pwa --name "Mi App" --short-name "MiApp"
+```
+
+### Flags V1
+
+- `--strategy <hybrid|offline-first|network-first>` (default: `hybrid`)
+- `--name <string>`
+- `--short-name <string>`
+
+### Flujo de ejecucion
+
+1. Ejecuta build de produccion.
+2. Lee y normaliza configuracion PWA en `src/sliceConfig.json`.
+3. Genera manifiesto de assets para precache desde `dist/`.
+4. Genera `dist/manifest.json`.
+5. Genera `dist/sw.js` con la estrategia seleccionada.
+6. Inyecta (o asegura) registro SW en HTML de entrada de `dist`.
+7. Imprime resumen final:
+   - estrategia usada,
+   - cantidad de assets precacheados,
+   - dominios excluidos efectivos.
+
+## Configuracion en `sliceConfig.json`
+
+Seccion minima V1:
+
+```json
+{
+  "pwa": {
+    "cache": {
+      "excludeDomains": []
+    }
+  }
+}
+```
+
+Reglas:
+
+- Si `pwa` no existe, el comando crea la seccion sin romper configuracion previa.
+- `excludeDomains` acepta hosts exactos (ej: `api.midominio.com`).
+- En ejecucion de desarrollo, se agregan de forma efectiva (no necesariamente persistida) `localhost` y `127.0.0.1`.
+
+## Arquitectura propuesta
+
+### Integracion CLI
+
+- Agregar comando en `client.js`:
+  - `generate-pwa`
+  - opcion `--strategy`
+  - opciones de nombre para manifest
+
+### Modulos nuevos
+
+- `commands/pwa/generatePwa.js`
+  - Orquestador del flujo completo.
+- `commands/pwa/ConfigResolver.js`
+  - Lee/crea/normaliza `pwa.cache.excludeDomains`.
+- `commands/pwa/AssetManifestBuilder.js`
+  - Recorre `dist/` y arma lista precache.
+- `commands/pwa/ManifestGenerator.js`
+  - Genera `manifest.json` con defaults y overrides por flags.
+- `commands/pwa/ServiceWorkerGenerator.js`
+  - Genera `sw.js` con estrategia seleccionada y exclusiones.
+
+## Diseno de cache
+
+### Reglas globales
+
+- Interceptar solo requests `GET`.
+- Si el host esta en `excludeDomains`, hacer `fetch` directo (sin cache).
+- Versionado de cache por build id (timestamp o hash de build).
+- Al activar nuevo SW, limpiar caches viejas automaticamente.
+
+### Estrategias
+
+- `hybrid` (default):
+  - assets estaticos -> `cache-first`.
+  - navegacion HTML -> `network-first` con fallback offline.
+- `offline-first`:
+  - navegacion + estaticos -> `cache-first`.
+  - update en background cuando haya red.
+- `network-first`:
+  - navegacion -> `network-first`.
+  - estaticos precacheados como respaldo.
+
+## Manejo de API REST y seguridad
+
+Para evitar cache de backend no deseado:
+
+- Exclusion por dominio con `excludeDomains` (regla principal de V1).
+- Limitar runtime cache a activos del frontend y navegacion segun estrategia.
+- No cachear metodos distintos de `GET`.
+
+Resultado: los assets del cliente se aceleran offline, pero el backend queda fuera de cache por configuracion explicita.
+
+## Error handling
+
+- Si build falla, abortar `generate-pwa` con mensaje claro.
+- Si `dist/` no existe tras build, abortar con diagnostico.
+- Si `sliceConfig.json` es invalido, mostrar error con sugerencia de reparacion.
+- Si no se puede inyectar registro SW en HTML, reportar warning y ruta objetivo.
+
+## Testing
+
+### Unit tests
+
+- `ConfigResolver`:
+  - crea seccion `pwa.cache.excludeDomains` cuando no existe,
+  - respeta config existente.
+- `AssetManifestBuilder`:
+  - incluye assets esperados,
+  - excluye archivos no aptos.
+- `ServiceWorkerGenerator`:
+  - genera logica correcta por estrategia,
+  - respeta `excludeDomains`.
+
+### Integracion
+
+- `slice generate-pwa` ejecuta build y crea `dist/manifest.json` + `dist/sw.js`.
+- registro SW presente en HTML de salida.
+- exclusiones de dominio aplicadas en codigo generado.
+
+### E2E manual minima
+
+- Build + generate-pwa.
+- Abrir app, validar installability (manifest).
+- Apagar red, validar navegacion offline en `hybrid`.
+- Verificar que requests a dominio excluido no se sirven desde cache SW.
+
+## Plan de evolucion (post V1)
+
+- `excludePaths` y `excludeHeaders`.
+- soporte de iconos y shortcuts PWA asistidos.
+- estrategia por ruta (ej: `/api/*` network-only).
+- extraer pipeline postbundle reusable para otras features.
+
+## Criterios de aceptacion
+
+- Existe comando `slice generate-pwa` funcional.
+- Ejecuta build antes de generar artefactos PWA.
+- Genera `manifest.json` y `sw.js` en `dist/`.
+- Registra SW en HTML principal de salida.
+- `hybrid` es default con HTML `network-first` y fallback offline.
+- Lee/escribe `pwa.cache.excludeDomains` en `src/sliceConfig.json`.
+- Excluye dominios configurados del cache runtime.
+- Muestra resumen final legible al usuario.

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "slicejs-cli",
-  "version": "3.1.0",
-  "description": "Command client for developing web applications with Slice.js framework",
-  "main": "client.js",
-  "bin": {
-    "slice": "./client.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/vkneider/slicejs-cli.git"
-  },
-  "scripts": {
-    "test": "node --test",
-    "postinstall": "node post.js"
-  },
-  "keywords": [
-    "framework",
-    "web",
-    "client",
-    "cli",
-    "slice",
-    "slicejs",
-    "component",
-    "development server"
-  ],
-  "author": "vkneider",
-  "type": "module",
-  "preferGlobal": false,
-  "license": "ISC",
-  "dependencies": {
-    "@babel/parser": "^7.28.5",
-    "@babel/traverse": "^7.28.5",
-    "chalk": "^5.6.2",
-    "chokidar": "^3.6.0",
-    "clean-css": "^5.3.3",
-    "cli-table3": "^0.6.5",
-    "commander": "^12.0.0",
-    "fs-extra": "^11.2.0",
-    "html-minifier-terser": "^7.2.0",
-    "inquirer": "^12.4.2",
-    "ora": "^8.2.0",
-    "slicejs-web-framework": "latest",
-    "terser": "^5.43.1"
-  }
-}
+{
+  "name": "slicejs-cli",
+  "version": "3.3.0",
+  "description": "Command client for developing web applications with Slice.js framework",
+  "main": "client.js",
+  "bin": {
+    "slice": "./client.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vkneider/slicejs-cli.git"
+  },
+  "scripts": {
+    "test": "node --test",
+    "postinstall": "node post.js"
+  },
+  "keywords": [
+    "framework",
+    "web",
+    "client",
+    "cli",
+    "slice",
+    "slicejs",
+    "component",
+    "development server"
+  ],
+  "author": "vkneider",
+  "type": "module",
+  "preferGlobal": false,
+  "license": "ISC",
+  "dependencies": {
+    "@babel/parser": "^7.28.5",
+    "@babel/traverse": "^7.28.5",
+    "chalk": "^5.6.2",
+    "chokidar": "^3.6.0",
+    "clean-css": "^5.3.3",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "html-minifier-terser": "^7.2.0",
+    "inquirer": "^12.4.2",
+    "ora": "^8.2.0",
+    "slicejs-web-framework": "latest",
+    "terser": "^5.43.1"
+  }
+}

package/post.js

@@ -1,25 +1,65 @@
-import fs from 'fs';
-import { fileURLToPath } from 'url';
-import path from 'path';
-import Print from './commands/Print.js';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const isGlobal = process.env.npm_config_global === 'true';
-const initCwd = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : null;
-const targetRoot = initCwd || path.resolve(__dirname, '../../');
-const projectPackageJsonPath = path.join(targetRoot, 'package.json');
-
-if (isGlobal) {
-    console.log('⚠️  Global installation of slicejs-cli detected.');
-    console.log('   We strongly recommend using a local installation to avoid version mismatches.');
-    console.log('   Uninstall global: npm uninstall -g slicejs-cli');
-    process.exit(0);
-}
-
-console.log('✅  slicejs-cli installed successfully.');
-console.log('   Add the CLI to your package.json scripts:');
-console.log('     "dev": "slice dev"');
-console.log('   Then run: npm run dev');
-process.exit(0);
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { getProjectRoot } from './commands/utils/PathHelper.js';
+
+const __filename = fileURLToPath(import.meta.url);
+
+const isGlobal = process.env.npm_config_global === 'true';
+
+if (isGlobal) {
+    console.log('⚠️  Global installation of slicejs-cli detected.');
+    console.log('   We strongly recommend using a local installation to avoid version mismatches.');
+    console.log('   Uninstall global: npm uninstall -g slicejs-cli');
+    process.exit(0);
+}
+
+const projectRoot = getProjectRoot(import.meta.url);
+const pkgPath = path.join(projectRoot, 'package.json');
+
+const sliceScripts = {
+    'slice:dev': 'slice dev',
+    'slice:start': 'slice start',
+    'slice:create': 'slice component create',
+    'slice:list': 'slice component list',
+    'slice:delete': 'slice component delete',
+    'slice:init': 'slice init',
+    'slice:get': 'slice get',
+    'slice:browse': 'slice browse',
+    'slice:sync': 'slice sync',
+    'slice:version': 'slice version',
+    'slice:update': 'slice update',
+};
+
+try {
+    let pkg = {};
+    if (fs.existsSync(pkgPath)) {
+        pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    } else {
+        pkg = {
+            name: path.basename(projectRoot),
+            version: '1.0.0',
+            description: 'Slice.js project',
+            scripts: {}
+        };
+    }
+
+    pkg.scripts = pkg.scripts || {};
+    let addedCount = 0;
+    for (const [script, command] of Object.entries(sliceScripts)) {
+        if (!pkg.scripts[script]) {
+            pkg.scripts[script] = command;
+            addedCount++;
+        }
+    }
+
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2), 'utf-8');
+    console.log(`✅  slicejs-cli installed successfully. Added ${addedCount} npm scripts to package.json.`);
+    console.log('   Run: npm run slice:dev');
+} catch (err) {
+    console.log('✅  slicejs-cli installed successfully.');
+    console.log('   Could not auto-configure scripts:', err.message);
+    console.log('   Run: npx slice dev');
+}
+
+process.exit(0);