slicejs-cli 3.5.1 → 3.6.1

package/README.md

@@ -28,9 +28,9 @@ This repository contains the Slice.js CLI (`slicejs-cli`), the command-line tool
    cd slicejs-cli
    ```
 
-2. **Install dependencies**
+2. **Install dependencies** (the repo pins pnpm via the `packageManager` field)
    ```bash
-   npm install
+   pnpm install --frozen-lockfile
    ```
 
 3. **Test changes locally**
@@ -50,20 +50,58 @@ This repository contains the Slice.js CLI (`slicejs-cli`), the command-line tool
 
 ## Installation (for users)
 
-### Local (Recommended)
+For a **new project** you don't install anything manually — `slice init` (see Quick
+start below) installs the CLI locally in the project it creates.
+
+### Local in an existing project (Recommended)
 
 ```bash
-npm install slicejs-cli --save-dev
+npm install slicejs-cli --save-dev    # or: pnpm add -D slicejs-cli
 ```
 
-### Global (Not recommended)
+### Global launcher (optional)
 
 ```bash
-npm install -g slicejs-cli
+npm install -g slicejs-cli            # or: pnpm add -g slicejs-cli
 ```
 
+The launcher delegates to the nearest project-local `node_modules/slicejs-cli`,
+so each project keeps its pinned CLI version.
+
 ## Main commands
 
+Inside initialized projects, prefer package scripts (`pnpm run ...`, `npm run ...`)
+over direct binary calls.
+
+Common script workflow:
+
+```bash
+pnpm run dev
+pnpm run build
+pnpm run start
+pnpm run browse
+pnpm run get -- Button
+pnpm run sync
+```
+
+Alternative with local devDependency resolution:
+
+```bash
+pnpm exec slice dev
+```
+
+If `slicejs-cli` is installed globally, `slice` can be executed directly from PATH.
+
+For pnpm v10+, if build scripts are restricted, configure `allowBuilds` in
+`pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  slicejs-cli: true
+```
+
+`slice init --pm pnpm` now writes this automatically.
+
 | Command | Description |
 |---------|-------------|
 | `slice init` | Initialize a Slice.js project |
@@ -83,17 +121,21 @@ When you install `slicejs-cli`, the `postinstall` script automatically configure
 ```json
 {
   "scripts": {
-    "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"
+    "slice:init": "node ./node_modules/slicejs-cli/client.js init",
+    "slice:dev": "node ./node_modules/slicejs-cli/client.js dev",
+    "slice:build": "node ./node_modules/slicejs-cli/client.js build",
+    "slice:start": "node ./node_modules/slicejs-cli/client.js start",
+    "slice:create": "node ./node_modules/slicejs-cli/client.js component create",
+    "slice:list": "node ./node_modules/slicejs-cli/client.js component list",
+    "slice:delete": "node ./node_modules/slicejs-cli/client.js component delete",
+    "slice:get": "node ./node_modules/slicejs-cli/client.js get",
+    "slice:browse": "node ./node_modules/slicejs-cli/client.js browse",
+    "slice:sync": "node ./node_modules/slicejs-cli/client.js sync",
+    "slice:doctor": "node ./node_modules/slicejs-cli/client.js doctor",
+    "slice:version": "node ./node_modules/slicejs-cli/client.js version",
+    "slice:help": "node ./node_modules/slicejs-cli/client.js --help",
+    "slice:update": "node ./node_modules/slicejs-cli/client.js update",
+    "slice:types": "node ./node_modules/slicejs-cli/client.js types generate"
   }
 }
 ```
@@ -106,21 +148,34 @@ npx slicejs-cli postinstall
 
 ## Quick start
 
+`slice init` creates the project folder itself — no `mkdir` or `npm init` needed.
+Everything (package.json, node_modules, lockfile, src/, api/) lives inside the new folder.
+
 ```bash
-# 1. Create project
-mkdir my-project && cd my-project
-npm init -y
+# With npm
+npx slicejs-cli init
+cd my-app
+npm run dev
+```
 
-# 2. Install CLI
-npm install slicejs-cli --save-dev
+```bash
+# With pnpm
+pnpm dlx slicejs-cli init
+cd my-app
+pnpm run dev
+```
 
-# 3. Initialize
-npx slicejs-cli init
+Non-interactive (for scripts/CI):
 
-# 4. Development
-npx slicejs-cli dev
+```bash
+npx slicejs-cli init -y my-app --pm pnpm
 ```
 
+init pins the chosen package manager in the `packageManager` field, installs
+`slicejs-web-framework` as a dependency and `slicejs-cli` as a devDependency of
+the new project. Versions are never hard-pinned at install time, so hardened pnpm
+setups (`minimumReleaseAge` quarantine, `ignore-scripts`) work out of the box.
+
 ## Tests
 
 The CLI uses Node.js native test runner:

package/client.js

@@ -27,6 +27,15 @@ import {
   resolveLocalCliCandidate,
   shouldDelegateToLocalCli
 } from './commands/utils/LocalCliDelegation.js';
+import {
+  detectPackageManager,
+  getAvailablePackageManagers,
+  isPackageManagerAvailable,
+  resolvePackageManager,
+  runScriptCommand,
+  SUPPORTED_PACKAGE_MANAGERS
+} from './commands/utils/PackageManager.js';
+import { SLICE_SCRIPTS } from './commands/utils/sliceScripts.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -96,6 +105,7 @@ sliceClient
   .command("init")
   .description("Initialize a new Slice.js project")
   .option("-y, --yes [name]", "Skip prompts and initialize with project name")
+  .option("--pm <packageManager>", "Package manager to use (pnpm or npm). Auto-detected when omitted")
   .action(async (options) => {
     let projectName = 'my-slice-app';
     if (options.yes) {
@@ -123,16 +133,62 @@ sliceClient
       projectName = answers.projectName;
     }
 
+    // Resolve the package manager: --pm flag → detection → interactive prompt.
+    // Detection here has no project root yet (the folder is new), so it relies on
+    // npm_config_user_agent (npx / pnpm dlx / PM scripts) or a single available binary.
+    let packageManager = options.pm;
+    if (packageManager && !SUPPORTED_PACKAGE_MANAGERS.includes(packageManager)) {
+      Print.error(`Unsupported package manager "${packageManager}". Use one of: ${SUPPORTED_PACKAGE_MANAGERS.join(', ')}`);
+      return;
+    }
+    if (packageManager && !isPackageManagerAvailable(packageManager)) {
+      Print.error(`Package manager "${packageManager}" is not available on this system`);
+      return;
+    }
+    if (!packageManager) {
+      const detected = detectPackageManager(null);
+      if (detected) {
+        packageManager = detected.name;
+      } else if (!options.yes) {
+        const available = getAvailablePackageManagers();
+        if (available.length === 0) {
+          Print.error('No package manager found (pnpm or npm). Install one and retry.');
+          return;
+        }
+        const { pm } = await inquirer.prompt([
+          {
+            type: 'list',
+            name: 'pm',
+            message: 'Which package manager do you want to use?',
+            choices: available,
+            default: available.includes('pnpm') ? 'pnpm' : available[0]
+          }
+        ]);
+        packageManager = pm;
+      } else {
+        const available = getAvailablePackageManagers();
+        packageManager = available.includes('pnpm') ? 'pnpm' : available[0];
+        if (!packageManager) {
+          Print.error('No package manager found (pnpm or npm). Install one and retry.');
+          return;
+        }
+      }
+    }
+
     const projectDir = path.resolve(projectName);
 
     if (fs.existsSync(projectDir)) {
       const contents = fs.readdirSync(projectDir);
       if (contents.length > 0) {
+        if (options.yes) {
+          Print.error(`Directory "${projectName}" already exists and is not empty. Aborting.`);
+          return;
+        }
         const { overwrite } = await inquirer.prompt([
           {
             type: 'confirm',
             name: 'overwrite',
-            message: `Directory "${answers.projectName}" already exists and is not empty. Continue?`,
+            message: `Directory "${projectName}" already exists and is not empty. Continue?`,
             default: false
           }
         ]);
@@ -148,9 +204,8 @@ sliceClient
     process.chdir(projectDir);
     process.env.INIT_CWD = projectDir;
 
-    await runWithVersionCheck(() => {
-      initializeProject();
-      return Promise.resolve();
+    await runWithVersionCheck(async () => {
+      await initializeProject({ packageManager });
     });
   });
 
@@ -353,7 +408,7 @@ componentCommand
           category = categoryAnswer.category;
         }
 
-        const config = loadConfig();
+        const config = sharedLoadConfigSync(import.meta.url);
         if (!config) {
           Print.error("Could not load configuration");
           return;
@@ -550,6 +605,7 @@ sliceClient
   .option("-y, --yes", "Skip confirmation and update all packages automatically")
   .option("--cli", "Update only the Slice.js CLI")
   .option("-f, --framework", "Update only the Slice.js Framework")
+  .option("--update-api", "Also overwrite api/index.js with the framework version (never done by default; creates a .bak backup)")
   .action(async (options) => {
     await updateManager.checkAndPromptUpdates(options);
   });
@@ -570,30 +626,24 @@ sliceClient
   .command("postinstall")
   .description("Configure npm scripts in package.json (alternative to postinstall for --ignore-scripts users)")
   .action(() => {
-    const isGlobal = process.env.npm_config_global === 'true';
+    // npm sets npm_config_global; pnpm global installs are detected via PNPM_HOME.
+    const pnpmHome = process.env.PNPM_HOME;
+    const cliEntryPath = fileURLToPath(import.meta.url);
+    const isGlobal = process.env.npm_config_global === 'true'
+      || (pnpmHome && cliEntryPath.startsWith(pnpmHome));
     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');
+      console.log(`   Uninstall global: ${pnpmHome ? 'pnpm remove -g slicejs-cli' : 'npm uninstall -g slicejs-cli'}`);
       return;
     }
 
     const projectRoot = getProjectRoot(import.meta.url);
     const pkgPath = path.join(projectRoot, 'package.json');
+    const packageManager = resolvePackageManager(projectRoot).name;
 
-    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',
-    };
+    // Shared with post.js and slice init — see commands/utils/sliceScripts.js
+    const sliceScripts = SLICE_SCRIPTS;
 
     try {
       let pkg = {};
@@ -618,12 +668,12 @@ sliceClient
       }
 
       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');
+      console.log(`✅  slicejs-cli installed successfully. Added ${addedCount} package scripts to package.json.`);
+      console.log(`   Run: ${runScriptCommand(packageManager, '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');
+      console.log(`   Configure scripts manually and run: ${runScriptCommand(packageManager, 'slice:dev')}`);
     }
   });
 

package/commands/buildProduction/buildProduction.js

@@ -6,7 +6,8 @@ import { minify as terserMinify } from 'terser';
 import { minify } from 'html-minifier-terser';
 import CleanCSS from 'clean-css';
 import Print from '../Print.js';
-import { getSrcPath, getDistPath, getConfigPath } from '../utils/PathHelper.js';
+import { getSrcPath, getDistPath, getConfigPath, getProjectRoot } from '../utils/PathHelper.js';
+import { resolvePackageManager, runScriptCommand } from '../utils/PackageManager.js';
 
 /**
  * Loads configuration from sliceConfig.json
@@ -441,6 +442,7 @@ async function analyzeBuild() {
  */
 export default async function buildProduction(options = {}) {
   const startTime = Date.now();
+  const packageManager = resolvePackageManager(getProjectRoot(import.meta.url)).name;
   
   try {
     Print.title('🔨 Building Slice.js project for production...');
@@ -483,7 +485,7 @@ export default async function buildProduction(options = {}) {
     Print.info('Your optimized project is ready in the /dist directory');
     Print.newLine();
     Print.info('Next steps:');
-    console.log('  • Use "npm run slice:start" to test the production build');
+    console.log(`  • Use "${runScriptCommand(packageManager, 'start')}" to test the production build`);
     console.log('  • All Slice.js components and architecture preserved');
     
     return true;
@@ -499,6 +501,7 @@ export default async function buildProduction(options = {}) {
  */
 export async function serveProductionBuild(port) {
   try {
+    const packageManager = resolvePackageManager(getProjectRoot(import.meta.url)).name;
     const config = loadConfig();
     const defaultPort = config?.server?.port || 3001;
     const finalPort = port || defaultPort;
@@ -533,7 +536,7 @@ export async function serveProductionBuild(port) {
       Print.success(`Production preview server running at http://localhost:${finalPort}`);
       Print.info('Press Ctrl+C to stop the server');
       Print.info('This server previews your production build from /dist');
-      Print.warning('This is a preview server - use "npm run slice:start" for the full production server');
+      Print.warning(`This is a preview server - use "${runScriptCommand(packageManager, 'start')}" for the full production server`);
     });
     
   } catch (error) {

package/commands/doctor/doctor.js

@@ -8,6 +8,7 @@ import inquirer from 'inquirer';
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import { getProjectRoot, getSrcPath, getApiPath, getConfigPath, getPath } from '../utils/PathHelper.js';
+import { resolvePackageManager, installCommand } from '../utils/PackageManager.js';
 import updateManager from '../utils/updateManager.js';
 
 /**
@@ -142,6 +143,68 @@ async function checkPort() {
     });
 }
 
+/**
+ * Checks the package manager setup: mixed lockfiles, packageManager field
+ * consistency, and a project-local CLI install (required for local delegation).
+ * Exported for tests.
+ */
+export async function checkPackageManagerSetup(projectRoot = getProjectRoot(import.meta.url)) {
+    const issues = [];
+    const suggestions = [];
+
+    const LOCKFILE_PM = {
+        'package-lock.json': 'npm',
+        'pnpm-lock.yaml': 'pnpm'
+    };
+    const lockfiles = [];
+    for (const lockfile of Object.keys(LOCKFILE_PM)) {
+        if (await fs.pathExists(path.join(projectRoot, lockfile))) {
+            lockfiles.push(lockfile);
+        }
+    }
+
+    let pkg = null;
+    const pkgPath = path.join(projectRoot, 'package.json');
+    if (await fs.pathExists(pkgPath)) {
+        try { pkg = await fs.readJson(pkgPath); } catch { /* reported by Dependencies check */ }
+    }
+    const pmField = typeof pkg?.packageManager === 'string' ? pkg.packageManager.split('@')[0] : null;
+    const pm = resolvePackageManager(projectRoot).name;
+
+    if (lockfiles.length > 1) {
+        issues.push(`Mixed lockfiles found: ${lockfiles.join(', ')}`);
+        const keep = pmField || pm;
+        const keepLockfile = Object.entries(LOCKFILE_PM).find(([, name]) => name === keep)?.[0];
+        suggestions.push(`Keep only ${keepLockfile ?? 'the lockfile of your package manager'} and delete the rest`);
+    }
+
+    if (pkg && !pmField) {
+        issues.push('No "packageManager" field in package.json');
+        suggestions.push(`Pin it (e.g. "packageManager": "${pm}@<version>") so every tool resolves the same package manager`);
+    } else if (pmField && lockfiles.length === 1 && LOCKFILE_PM[lockfiles[0]] !== pmField) {
+        issues.push(`packageManager is "${pmField}" but the lockfile is ${lockfiles[0]}`);
+        suggestions.push(`Reinstall with ${pmField} (or update the packageManager field) so they agree`);
+    }
+
+    const localCliPath = path.join(projectRoot, 'node_modules', 'slicejs-cli', 'package.json');
+    if (pkg && !(await fs.pathExists(localCliPath))) {
+        issues.push('slicejs-cli is not installed locally');
+        suggestions.push(`Run "${installCommand(pm, 'slicejs-cli', { dev: true })}" so the launcher delegates to a version pinned per project`);
+    }
+
+    if (issues.length === 0) {
+        return {
+            pass: true,
+            message: `Package manager setup is consistent (${pmField || pm})`
+        };
+    }
+    return {
+        warn: true,
+        message: issues.join(' | '),
+        suggestion: suggestions.join(' | ')
+    };
+}
+
 /**
  * Checks dependencies in package.json
  */
@@ -176,8 +239,8 @@ async function checkDependencies() {
                 warn: true,
                 message: `Missing dependencies: ${missing.join(', ')}`,
                 suggestion: missing.includes('slicejs-web-framework')
-                    ? 'Run "npm install slicejs-web-framework@latest" in your project'
-                    : 'Run "npm install -D slicejs-cli@latest" in your project',
+                    ? `Run "${installCommand(resolvePackageManager(getProjectRoot(import.meta.url)).name, 'slicejs-web-framework@latest')}" in your project`
+                    : `Run "${installCommand(resolvePackageManager(getProjectRoot(import.meta.url)).name, 'slicejs-cli@latest', { dev: true })}" in your project`,
                 missing
             };
         }
@@ -278,6 +341,7 @@ export default async function runDiagnostics() {
         { name: 'Project Structure', fn: checkDirectoryStructure },
         { name: 'Configuration', fn: checkConfig },
         { name: 'Port Availability', fn: checkPort },
+        { name: 'Package Manager', fn: checkPackageManagerSetup },
         { name: 'Dependencies', fn: checkDependencies },
         { name: 'Components', fn: checkComponents }
     ];
@@ -340,9 +404,10 @@ export default async function runDiagnostics() {
             }
         ]);
         if (confirmInstall) {
+            const pm = resolvePackageManager(projectRoot).name;
             for (const pkg of depsResult.missing) {
                 try {
-                    const cmd = 'npm install slicejs-web-framework@latest';
+                    const cmd = installCommand(pm, `${pkg}@latest`);
                     Print.info(`Installing ${pkg}...`);
                     await execAsync(cmd, { cwd: projectRoot });
                     Print.success(`${pkg} installed`);

package/commands/getComponent/getComponent.js

@@ -50,6 +50,10 @@ class ComponentRegistry {
     this.componentsRegistry = null;
     this.config = null;
     this._configPromise = null;
+    // Serializes read-modify-write cycles on components.js: installs run
+    // concurrently (runConcurrent), and parallel writers corrupt the file
+    // (partial reads) or silently drop registrations (lost updates).
+    this._registryLock = Promise.resolve();
   }
 
   async _ensureConfig() {
@@ -249,31 +253,35 @@ filterOfficialComponents(allComponents) {
   }
 
   async updateLocalRegistrySafe(componentName, category) {
+    // Queue behind any in-flight registry update; keep the chain alive even
+    // when an update throws so later updates still run.
+    const run = this._registryLock.then(() => this._updateLocalRegistry(componentName, category));
+    this._registryLock = run.catch(() => {});
+    return run;
+  }
+
+  async _updateLocalRegistry(componentName, category) {
     const componentsPath = getComponentsJsPath(import.meta.url);
-    try {
-      if (!await fs.pathExists(componentsPath)) {
-        const dir = path.dirname(componentsPath);
-        await fs.ensureDir(dir);
-        const initial = `const components = {};\n\nexport default components;\n`;
-        await fs.writeFile(componentsPath, initial, 'utf8');
-      }
-      const content = await fs.readFile(componentsPath, 'utf8');
-      const match = content.match(/const components = ({[\s\S]*?});/);
-      if (!match) throw new Error('Invalid components.js format in local project');
-      const componentsObj = JSON.parse(match[1]);
-      if (!componentsObj[componentName]) {
-        componentsObj[componentName] = category;
-        const sorted = Object.keys(componentsObj)
-          .sort()
-          .reduce((obj, key) => { obj[key] = componentsObj[key]; return obj; }, {});
-        const newContent = `const components = ${JSON.stringify(sorted, null, 2)};\n\nexport default components;\n`;
-        await fs.writeFile(componentsPath, newContent, 'utf8');
-        Print.registryUpdate(`Registered ${componentName} in local components.js`);
-      } else {
-        Print.info(`${componentName} already exists in local registry`);
-      }
-    } catch (error) {
-      throw error;
+    if (!await fs.pathExists(componentsPath)) {
+      const dir = path.dirname(componentsPath);
+      await fs.ensureDir(dir);
+      const initial = `const components = {};\n\nexport default components;\n`;
+      await fs.writeFile(componentsPath, initial, 'utf8');
+    }
+    const content = await fs.readFile(componentsPath, 'utf8');
+    const match = content.match(/const components = ({[\s\S]*?});/);
+    if (!match) throw new Error('Invalid components.js format in local project');
+    const componentsObj = JSON.parse(match[1]);
+    if (!componentsObj[componentName]) {
+      componentsObj[componentName] = category;
+      const sorted = Object.keys(componentsObj)
+        .sort()
+        .reduce((obj, key) => { obj[key] = componentsObj[key]; return obj; }, {});
+      const newContent = `const components = ${JSON.stringify(sorted, null, 2)};\n\nexport default components;\n`;
+      await fs.writeFile(componentsPath, newContent, 'utf8');
+      Print.registryUpdate(`Registered ${componentName} in local components.js`);
+    } else {
+      Print.info(`${componentName} already exists in local registry`);
     }
   }
 
@@ -339,7 +347,7 @@ filterOfficialComponents(allComponents) {
       await this.updateLocalRegistrySafe(componentName, category);
 
       Print.success(`${componentName} installed successfully from official repository!`);
-      console.log(`📁 Location: ${folderSuffix}/${categoryPath}/${componentName}/`);
+      console.log(`📁 Location: ${[folderSuffix, categoryPath, componentName].join('/').replace(/\/+/g, '/')}/`);
       console.log(`📄 Files: ${downloadedFiles.join(', ')}`);
 
       return true;