slicejs-cli 3.4.0 → 3.5.0

package/AGENTS.md

@@ -0,0 +1,247 @@
+# Slice.js CLI — Agent Context
+
+## Project Structure
+
+```
+slicejs-cli/
+├── client.js                          # CLI entry point (commander)
+├── commands/
+│   ├── init/init.js                   # slice init
+│   ├── startServer/startServer.js     # slice dev / slice start
+│   ├── build/build.js                 # slice build
+│   ├── getComponent/getComponent.js   # slice get / browse / sync
+│   ├── createComponent/               # slice component create
+│   ├── listComponents/                # slice component list
+│   ├── deleteComponent/                # slice component delete
+│   ├── doctor/doctor.js               # slice doctor
+│   ├── types/types.js                 # slice types generate
+│   ├── bundle/bundle.js               # bundling logic
+│   ├── utils/
+│   │   ├── PathHelper.js              # Path resolution (critical)
+│   │   ├── bundling/BundleGenerator.js
+│   │   ├── updateManager.js
+│   │   ├── VersionChecker.js
+│   │   └── LocalCliDelegation.js
+│   └── Print.js                       # Wrapper for console.log/error
+├── tests/
+│   ├── helpers/setup.js               # Shared test helper (createTestProject, withTestProject)
+│   ├── fixtures/                      # Minimal fixture files for tests
+│   ├── bundle-generator.test.js
+│   ├── bundle-v2-register-output.test.js
+│   ├── client-launcher-contract.test.js
+│   ├── client-update-flow-contract.test.js
+│   ├── component-registry-parse.test.js
+│   ├── dependency-analyzer.test.js
+│   ├── init-command-contract.test.js
+│   ├── local-cli-delegation.test.js
+│   ├── path-helper.test.js
+│   ├── postinstall-command.test.js
+│   ├── types-generator.test.js
+│   └── update-manager-notifications.test.js
+├── package.json                       # type: "module" — ES modules only
+└── AGENTS.md                          # This file
+```
+
+## Testing System
+
+### Runner
+- Uses Node.js built-in test runner: `node --test`
+- Run: `npm test`
+- Watch mode: `node --test --watch`
+
+### Shared Test Helper (`tests/helpers/setup.js`)
+Three exported functions:
+
+```js
+import { createTestProject, cleanupTestProject, withTestProject } from './helpers/setup.js';
+```
+
+**`createTestProject(options)`** — Creates a temp directory with full Slice.js project scaffold.
+- Copies real framework files from `../slice.js/` (sibling directory in monorepo)
+- Falls back to `tests/fixtures/` minimal scaffold if framework not available
+- Options:
+  - `visualComponents: ['Button']` — creates stub component files + rewrites `components.js` to include only those
+  - `frameworkDir` — custom framework source path
+- Returns the temp directory path
+- Temp dir path: `{os.tmpdir()}/slice-test-{PID}-{N}-{random}/`
+
+**`cleanupTestProject(dir)`** — Removes the temp directory recursively.
+
+**`withTestProject(fn, options)`** — Convenience wrapper that:
+1. Calls `createTestProject(options)`
+2. Saves and sets `process.env.INIT_CWD = dir`
+3. Runs `fn(dir)`
+4. Restores `process.env.INIT_CWD` to original value
+5. Calls `cleanupTestProject(dir)` in `finally`
+
+### Patterns
+
+**For tests that need INIT_CWD pointing to the project:**
+```js
+test('my test', async () => {
+  await withTestProject(async (tmpDir) => {
+    // process.env.INIT_CWD is already set to tmpDir
+    const result = someFunction(import.meta.url);
+    assert.ok(result);
+  });
+});
+```
+
+**For tests that pass projectRoot explicitly:**
+```js
+test('my test', async () => {
+  const tmpRoot = await createTestProject({ visualComponents: ['Button'] });
+  try {
+    const result = await someFunction({ projectRoot: tmpRoot });
+    assert.equal(result, 1);
+  } finally {
+    await cleanupTestProject(tmpRoot);
+  }
+});
+```
+
+**For tests with shared project setup across a describe block:**
+```js
+let tmpRoot;
+before(async () => {
+  tmpRoot = await createTestProject();
+  process.env.INIT_CWD = tmpRoot;
+});
+after(async () => {
+  delete process.env.INIT_CWD;
+  await cleanupTestProject(tmpRoot);
+});
+```
+
+### Test types
+
+1. **Contract tests** (`*-contract.test.js`) — Static analysis of `client.js` source code via `@babel/parser` + AST or regex. Verify command registration, option flags, and function calls. No runtime execution.
+2. **Unit tests** — Test individual functions/modules in isolation. Use temp dirs for filesystem-dependent code.
+3. **Snapshot/Integration tests** — Verify output files, generated declarations, bundle configs.
+
+### Rules
+- No external mocking libraries (sinon, jest, etc.). Use monkey-patching + try/finally restore.
+- All temp dirs MUST be cleaned up in `finally` blocks.
+- `process.env.INIT_CWD` must be saved before modification and restored in `finally`.
+- Dynamic `import()` is used where module caching matters, but PathHelper reads env vars at call time so cached modules work correctly.
+
+## PathHelper Rules (`commands/utils/PathHelper.js`)
+
+### Project Root Resolution
+`getProjectRoot(moduleUrl)` resolves in this order:
+1. `process.env.INIT_CWD` — set by npm or by `withTestProject` during tests
+2. `process.cwd()` — current working directory
+3. `candidates(moduleUrl)` — heuristic: walk up `../../` and `../../../../` from module location, check for `src/` or `api/`
+
+### Functions
+
+| Function | Returns | Notes |
+|---|---|---|
+| `getProjectRoot(moduleUrl)` | Resolved project root path | |
+| `getSrcPath(moduleUrl, ...seg)` | `<root>/src/[...seg]` | |
+| `getApiPath(moduleUrl, ...seg)` | `<root>/api/[...seg]` | |
+| `getDistPath(moduleUrl, ...seg)` | `<root>/dist/[...seg]` | |
+| `getPath(moduleUrl, ...seg)` | `<root>/[...seg]` | General purpose |
+| `getConfigPath(moduleUrl, root?)` | `src/sliceConfig.json` | Optional explicit root param |
+| `getComponentsJsPath(moduleUrl, root?)` | `src/Components/components.js` | Optional explicit root param |
+| `joinRoot(root, ...seg)` | `<root>/[...seg]` | No moduleUrl needed, pure path join |
+
+### Critical Rules
+
+1. **`import.meta.url` must be passed** as first argument to all PathHelper functions (except `joinRoot`).
+2. **Explicit root parameter** (`getConfigPath`, `getComponentsJsPath`) is used by `types/types.js` when generating types for a non-cwd project. This keeps functions testable without global state.
+3. **`INIT_CWD` is the primary mechanism** for project root resolution. It's set by npm lifecycle scripts and by `withTestProject`.
+4. **`candidates()` fallback** only works when the CLI is installed inside a project that has `src/` or `api/`. This is intentionally limited.
+
+## Code Quality Standards
+
+### ES Modules Only
+- `"type": "module"` in `package.json`
+- Use `import`/`export` everywhere
+- NO `require()`, NO `__dirname` at module scope (use `path.dirname(fileURLToPath(import.meta.url))` inline where needed)
+
+### No eval()
+- `eval()` has been fully replaced with `JSON.parse()` for reading `components.js` files
+- Components are written via `JSON.stringify()`, so content is always valid JSON
+- Use `JSON.parse()` or the AST-based `ComponentRegistry` for component registry parsing
+
+### Error Messages
+- Bare error messages (just the error message without context) must NOT be used
+- Always wrap errors with context: `Print.error('Context:', error.message)`
+- Use `Print.error()` / `Print.success()` / `Print.info()` / `Print.warning()` instead of raw `console.log`/`console.error`
+- EXCEPTION: Formatted help/command listing output can use `console.log` directly (avoids `ℹ️ Info:` prefix pollution)
+
+### Empty Catch Blocks
+- Silent catches are acceptable ONLY for:
+  - Non-critical operations (update checks, optional config reads)
+  - Graceful degradation paths
+- All silent catches MUST have a comment explaining why: `catch { /* intentional: non-critical */ }`
+
+### Port Resolution (startServer)
+Priority order:
+1. `--port` CLI flag (if provided by user)
+2. `config.server.port` from `sliceConfig.json`
+3. Hardcoded `3000` fallback
+
+Commander `.option()` defaults must NOT override config values. Pass `undefined` when flag is not provided:
+```js
+port: options.port ? parseInt(options.port) : undefined
+```
+
+### Dependency Injection for Testability
+- Functions that need a project root accept it as a parameter (`projectRoot`, `root`)
+- PathHelper functions that accept an explicit root param enable testing without INIT_CWD gymnastics
+- Avoid reading `process.env.INIT_CWD` or `process.cwd()` directly inside business logic; use PathHelper
+
+## CLI Architecture (client.js)
+
+### Command Registration Pattern
+```js
+sliceClient
+  .command("mycommand")
+  .description("...")
+  .option("-x, --flag <value>", "...")
+  .action(async (options) => {
+    // 1. Handle --yes / non-interactive flags before prompts
+    // 2. Prompt for missing required values
+    // 3. Delegate to command implementation
+    await runWithVersionCheck(async () => {
+      await myCommandImplementation(options);
+    });
+  });
+```
+
+### `runWithVersionCheck(commandFunction)`
+- Wraps every command action
+- Responsibilities:
+  1. Fire-and-forget update notification (`notifyAvailableUpdates().catch(() => {})`)
+  2. Execute the command
+  3. Background version check (`checkForUpdates(false)` after 100ms delay)
+- Does NOT block or prompt the user (pre-flight checks were removed)
+- Errors are caught and logged via `Print.error()`
+
+### Init Command (`slice init`)
+- Default project name: `my-slice-app`
+- `-y`/`--yes [name]` flag skips interactive prompts
+- Creates project directory, `chdir`s into it, sets `INIT_CWD`
+- Calls `initializeProject()` from `commands/init/init.js`
+- Name normalization: trim → lowercase → spaces to hyphens → strip non-alphanumeric → collapse hyphens → trim hyphens
+
+### Local CLI Delegation
+- `maybeDelegateToLocalCli()` runs at module level before command parsing
+- If a local `node_modules/slicejs-cli/` exists, spawns it instead of running the global CLI
+- Controlled by `SLICE_NO_LOCAL_DELEGATION` env var
+
+## Visual Component Registry
+- Components downloaded from GitHub: `https://raw.githubusercontent.com/VKneider/slice.js_visual_library/master/src/Components/{category}/{Name}/{file}`
+- Registry URL: same base + `src/Components/components.js`
+- Starter visual components on init: Button, Link, Loading, MultiRoute, Navbar, NotFound, Route
+- Components are registered by writing to `src/Components/components.js`
+
+### File Download Rules (in `getAvailableComponents`)
+- **Routing/navigation components** (`Route`, `MultiRoute`, `Link`): only `.js` file
+- **Other Visual components** (Button, Loading, Navbar, etc.): `.js`, `.html`, `.css`
+- **Service components** (FetchManager, etc.): only `.js` file
+- File list is determined by hardcoded rules, NOT by checking the remote server
+- If `.js` download fails → component install fails (fatal)
+- If `.html`/`.css` fails → component install succeeds with warning

package/client.js

@@ -13,9 +13,9 @@ import updateManager from "./commands/utils/updateManager.js";
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
-import { getConfigPath, getProjectRoot } from "./commands/utils/PathHelper.js";
-import { exec, spawnSync } from "node:child_process";
-import { promisify } from "util";
+import { getProjectRoot, getSrcPath, getPath } from "./commands/utils/PathHelper.js";
+import { loadConfigSync as sharedLoadConfigSync } from "./commands/utils/loadConfig.js";
+import { spawnSync } from "node:child_process";
 import validations from "./commands/Validations.js";
 import Print from "./commands/Print.js";
 import build from './commands/build/build.js';
@@ -30,67 +30,14 @@ import {
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-const loadConfig = () => {
-  try {
-    const configPath = getConfigPath(import.meta.url);
-    const rawData = fs.readFileSync(configPath, "utf-8");
-    return JSON.parse(rawData);
-  } catch {
-    return null;
-  }
-};
-
 const getCategories = () => {
-  const config = loadConfig();
+  const config = sharedLoadConfigSync(import.meta.url);
   return config && config.paths?.components ? Object.keys(config.paths.components) : [];
 };
 
 // Function to run version check for all commands
 async function runWithVersionCheck(commandFunction, ...args) {
   try {
-    const execAsync = promisify(exec);
-    await (async () => {
-      try {
-        const info = await updateManager.detectCliInstall();
-        if (info && info.type === 'global') {
-          const projectRoot = getProjectRoot(import.meta.url);
-          const pkgPath = path.join(projectRoot, 'package.json');
-          let hasPkg = fs.existsSync(pkgPath);
-          if (!hasPkg) {
-            const { confirmInit } = await inquirer.prompt([
-              {
-                type: 'confirm',
-                name: 'confirmInit',
-                message: 'No package.json found. Initialize npm in this project now?',
-                default: true
-              }
-            ]);
-            if (confirmInit) {
-              await execAsync('npm init -y', { cwd: projectRoot });
-              hasPkg = true;
-            }
-          }
-          if (hasPkg) {
-            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-            const hasFramework = pkg.dependencies?.['slicejs-web-framework'];
-            if (!hasFramework) {
-              const { confirm } = await inquirer.prompt([
-                {
-                  type: 'confirm',
-                  name: 'confirm',
-                  message: 'slicejs-web-framework is not installed in this project. Install it now?',
-                  default: true
-                }
-              ]);
-              if (confirm) {
-                await updateManager.updatePackage('slicejs-web-framework');
-              }
-            }
-          }
-        }
-      } catch {}
-    })();
-
     updateManager.notifyAvailableUpdates().catch(() => {});
 
     const result = await commandFunction(...args);
@@ -148,7 +95,59 @@ try {
 sliceClient
   .command("init")
   .description("Initialize a new Slice.js project")
-  .action(async () => {
+  .option("-y, --yes [name]", "Skip prompts and initialize with project name")
+  .action(async (options) => {
+    let projectName = 'my-slice-app';
+    if (options.yes) {
+      projectName = typeof options.yes === 'string' ? options.yes : projectName;
+    } else {
+      const answers = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'projectName',
+          message: 'What is the name of your project?',
+          default: projectName,
+          filter: (input) => input.trim()
+            .toLowerCase()
+            .replace(/\s+/g, '-')
+            .replace(/[^a-z0-9-]/g, '')
+            .replace(/-+/g, '-')
+            .replace(/^-|-$/g, ''),
+          validate: (input) => {
+            if (!input || !input.trim()) return 'Project name cannot be empty';
+            if (input.includes('/') || input.includes('\\')) return 'Use a simple name, not a path';
+            return true;
+          }
+        }
+      ]);
+      projectName = answers.projectName;
+    }
+
+    const projectDir = path.resolve(projectName);
+
+    if (fs.existsSync(projectDir)) {
+      const contents = fs.readdirSync(projectDir);
+      if (contents.length > 0) {
+        const { overwrite } = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'overwrite',
+            message: `Directory "${answers.projectName}" already exists and is not empty. Continue?`,
+            default: false
+          }
+        ]);
+        if (!overwrite) {
+          Print.info('Initialization cancelled.');
+          return;
+        }
+      }
+    } else {
+      fs.mkdirSync(projectDir, { recursive: true });
+    }
+
+    process.chdir(projectDir);
+    process.env.INIT_CWD = projectDir;
+
     await runWithVersionCheck(() => {
       initializeProject();
       return Promise.resolve();
@@ -206,7 +205,7 @@ buildCommand
 sliceClient
   .command("dev")
   .description("Start development server with hot reload enabled by default")
-  .option("-p, --port <port>", "Port for development server", 3000)
+  .option("-p, --port <port>", "Port for development server")
   .option("--no-hmr", "Disable hot module reload (enabled by default)")
   .action(async (options) => {
     const prevEnv = process.env.NODE_ENV;
@@ -215,7 +214,7 @@ sliceClient
       await runWithVersionCheck(async () => {
         await startServer({
           mode: 'development',
-          port: parseInt(options.port),
+          port: options.port ? parseInt(options.port) : undefined,
           watch: options.hmr
         });
       });
@@ -228,7 +227,7 @@ sliceClient
 sliceClient
   .command("start")
   .description("Serve production files from dist/ (requires prior slice build)")
-  .option("-p, --port <port>", "Port for server", 3000)
+  .option("-p, --port <port>", "Port for server")
   .action(async (options) => {
     const prevEnv = process.env.NODE_ENV;
     process.env.NODE_ENV = 'production';
@@ -236,7 +235,7 @@ sliceClient
       await runWithVersionCheck(async () => {
         await startServer({
           mode: 'production',
-          port: parseInt(options.port)
+          port: options.port ? parseInt(options.port) : undefined
         });
       });
     } finally {
@@ -367,7 +366,7 @@ componentCommand
         }
 
         const categoryPath = config.paths.components[category].path;
-        const fullPath = path.join(__dirname, "../../src", categoryPath);
+        const fullPath = getSrcPath(import.meta.url, categoryPath);
 
         if (!fs.existsSync(fullPath)) {
           Print.error(`Category path does not exist: ${categoryPath}`);
@@ -637,7 +636,7 @@ sliceClient
   });
 
 
-// Custom help - SIMPLIFICADO para development only
+// Custom help - SIMPLIFIED for development only
 sliceClient.addHelpText('after', `
 Common Usage Examples:
   slice init                     - Initialize new Slice.js project

package/commands/Print.js

@@ -43,7 +43,7 @@ export default class Print {
         console.log(chalk.gray('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
     }
 
-    // Métodos para el contexto específico del CLI
+    // Methods for CLI-specific context
     static componentSuccess(componentName, action = 'processed') {
         console.log(chalk.green(`✅ ${componentName} ${action} successfully!`));
     }
@@ -56,12 +56,8 @@ export default class Print {
         console.log(chalk.cyan(`  📥 Downloading ${fileName}...`));
     }
 
-    static downloadSuccess(fileName) {
-        console.log(chalk.green(`  ✅ ${fileName}`));
-    }
-
-    static downloadError(fileName, error) {
-        console.error(chalk.red(`  ❌ Error downloading ${fileName}: ${error}`));
+    static downloadError(fileName) {
+        console.error(chalk.red(`  ❌ ${fileName}`));
     }
 
     static registryUpdate(message) {
@@ -93,7 +89,7 @@ export default class Print {
         Print.separator();
     }
 
-    // Método para mostrar resultados de minificación
+    // Method to show minification results
     static minificationResult(filename, originalSize, minifiedSize, savingsPercent) {
         const originalKB = (originalSize / 1024).toFixed(1);
         const minifiedKB = (minifiedSize / 1024).toFixed(1);
@@ -102,12 +98,12 @@ export default class Print {
         console.log(chalk.gray(`     ${originalKB}KB → ${minifiedKB}KB (${savingsPercent}% saved)`));
     }
 
-    // Método para mostrar progreso de build
+    // Method to show build progress
     static buildProgress(message) {
         console.log(chalk.cyan(`🔄 ${message}`));
     }
 
-    // Método para mostrar estadísticas de servidor
+    // Method to show server statistics
     static serverStats(mode, port, directory) {
         Print.newLine();
         console.log(chalk.magenta(`🌐 Server Configuration:`));
@@ -117,7 +113,7 @@ export default class Print {
         Print.newLine();
     }
 
-    // Método para mostrar que el servidor está listo con URL destacada
+    // Method to show the server is ready with highlighted URL
     static serverReady(port) {
         Print.newLine();
         console.log(chalk.bgGreen.black.bold(' ✓ SERVER READY '));
@@ -129,7 +125,7 @@ export default class Print {
         Print.newLine();
     }
 
-    // Método para mostrar el estado del servidor durante inicio
+    // Method to show server status during startup
     static serverStatus(status, message = '') {
         const icons = {
             checking: '🔍',
@@ -151,17 +147,17 @@ export default class Print {
         console.log(color(`${icon} ${displayMessage}`));
     }
 
-    // Método para mostrar que se está verificando el puerto
+    // Method to show port checking status
     static checkingPort(port) {
         console.log(chalk.cyan(`🔍 Checking port ${port}...`));
     }
 
-    // Nuevo: Método para debug
+    // New: Debug method
     static debug(message) {
         console.log(chalk.gray(`🐛 DEBUG: ${message}`));
     }
 
-    // Nuevo: Método para logs verbosos
+    // New: Verbose logging method
     static verbose(message) {
         console.log(chalk.gray(`📝 ${message}`));
     }

package/commands/Validations.js

@@ -1,9 +1,8 @@
 import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
-import { getConfigPath, getComponentsJsPath } from './utils/PathHelper.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import Print from './Print.js';
+import { getComponentsJsPath } from './utils/PathHelper.js';
+import { loadConfigSync } from './utils/loadConfig.js';
 
 class Validations {
     constructor() {
@@ -26,25 +25,13 @@ class Validations {
     }
 
     isValidComponentName(componentName) {
-        // Expresión regular para verificar si el nombre contiene caracteres especiales
+        // Regex to check if the name contains special characters
         const regex = /^[a-zA-Z][a-zA-Z0-9]*$/;
         return regex.test(componentName);
     }
 
     loadConfig() {
-        try {
-            const configPath = getConfigPath(import.meta.url);
-            if (!fs.existsSync(configPath)) {
-                // Return null silently - let commands handle missing config if needed
-                return null;
-            }
-            const rawData = fs.readFileSync(configPath, 'utf-8');
-
-            return JSON.parse(rawData);
-        } catch (error) {
-            console.error('\x1b[31m', `❌ Error loading configuration: ${error.message}`, '\x1b[0m');
-            return null;
-        }
+        return loadConfigSync(import.meta.url);
     }
 
     getCategories() {
@@ -80,19 +67,21 @@ class Validations {
             const componentFilePath = getComponentsJsPath(import.meta.url);
 
             if (!fs.existsSync(componentFilePath)) {
-                console.error('\x1b[31m', '❌ Error: components.js not found in expected path', '\x1b[0m');
-                console.log('\x1b[36m', 'ℹ️  Info: Run "slice component list" to generate components.js', '\x1b[0m');
+                Print.error('components.js not found in expected path');
+                Print.info('Run "slice component list" to generate components.js');
                 return false;
             }
 
             const fileContent = fs.readFileSync(componentFilePath, 'utf-8');
-            const components = eval(fileContent.replace('export default', '')); // Evalúa el contenido como objeto
+            const match = fileContent.match(/const components = ({[\s\S]*?});/);
+            if (!match) return false;
+            const components = JSON.parse(match[1]);
 
             return components.hasOwnProperty(componentName);
 
         } catch (error) {
-            console.error('\x1b[31m', `❌ Error checking component existence: ${error.message}`, '\x1b[0m');
-            console.log('\x1b[36m', 'ℹ️  Info: The components.js file may be corrupted', '\x1b[0m');
+            Print.error(`Error checking component existence: ${error.message}`);
+            Print.info('The components.js file may be corrupted');
             return false;
         }
     }