slicejs-cli 3.2.0 → 3.3.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug Report
+about: Report a bug in a component or the parser
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Description
+A clear description of the bug.
+
+## Reproduction
+Steps to reproduce:
+1. Go to '...'
+2. Click on '...'
+3. Error: '...'
+
+## Expected behavior
+What should have happened.
+
+## Environment
+- Browser/Node version:
+- OS:
+- slice.js_visual_library version:
+
+## Screenshots / Console output
+If applicable.
+
+## Additional context

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature Request
+about: Suggest a new component or improvement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+What problem does this solve? (e.g. "I need a component that...")
+
+## Proposed solution
+How should it work? Include props, behavior, and visual details if applicable.
+
+## Alternatives considered
+What other approaches have you considered?
+
+## Example usage
+```javascript
+const component = await slice.build('ComponentName', {
+  // props here
+});
+```
+
+## Additional context

package/.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## Summary
+- 
+
+## Docs Scope
+- [ ] Visual library docs pages (`src/markdown/` and generated outputs)
+- [ ] Parser logic (`parser/`)
+- [ ] Routes/index sync (`documentationRoutes.generated.js`, `docsIndex.js`, `components.js`)
+
+## Verification
+- [ ] `npm run docs:lint-md`
+- [ ] `npm run docs:generate`
+- [ ] `node --test parser/tests/index.test.js`
+
+## Screenshots / UI Notes
+- 
+
+## Breaking Changes
+- [ ] None
+- [ ] Yes (describe below)
+
+## Additional Context
+- 

package/.github/workflows/docs-render-cicd.yml

@@ -0,0 +1,65 @@
+name: Docs Parse + Render CD
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  docs-pipeline:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate markdown docs
+        run: npm run docs:lint-md
+
+      - name: Generate documentation artifacts
+        run: npm run docs:generate
+
+      - name: Check generated changes (PR)
+        if: github.event_name == 'pull_request'
+        run: |
+          if ! git diff --quiet; then
+            echo "Generated files are out of date. Run 'npm run docs:generate' and commit changes."
+            git status --short
+            exit 1
+          fi
+
+      - name: Commit generated docs (main)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          if ! git diff --quiet; then
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git add src/Components src/Styles src/routes.js
+            git commit -m "chore(docs): auto-generate docs artifacts from markdown"
+            git push
+          else
+            echo "No generated changes to commit."
+          fi
+
+      - name: Trigger Render deploy
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && secrets.RENDER_DEPLOY_HOOK_URL != ''
+        run: |
+          curl --fail --silent --show-error --request POST "$RENDER_DEPLOY_HOOK_URL"
+        env:
+          RENDER_DEPLOY_HOOK_URL: ${{ secrets.RENDER_DEPLOY_HOOK_URL }}

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,126 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to Victor Kneider at vkneider.dev@gmail.com or via LinkedIn
+(https://www.linkedin.com/in/vkneider/). All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/ECOSYSTEM.md

@@ -0,0 +1,9 @@
+# Slice.js Ecosystem
+
+| Repository | Description | URL |
+|---|---|---|
+| slice.js | Core web framework | https://github.com/VKneider/slice.js |
+| slice-cli | CLI tool for project management | https://github.com/VKneider/slicejs-cli |
+| slice.js_visual_library | Official visual components and docs | https://github.com/VKneider/slice.js_visual_library |
+| sliceDocs | Framework documentation site | https://github.com/VKneider/slicejs_docs |
+| PortfolioVK2 | Portfolio and demo app | https://github.com/VKneider/portfolio |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Victor Jose Kneider Alnahi and Julio Antonio Graterol Bracho
+
+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,375 +1,171 @@
-<div align="center">
-
-# Slice.js CLI
-<img src="./assets/Slice.js-logo.png" alt="Slice.js logo" width="200" />
-<br/>
-
-<div style="display: flex; justify-content: center; align-items: center; gap: 10px; align-content: center;">
-<a href="https://www.npmjs.com/package/slicejs-cli"><img src="https://img.shields.io/npm/v/slicejs-cli.svg?label=CLI" alt="npm version" /></a>
-<img src="https://img.shields.io/badge/Node-%E2%89%A5%2020.0.0-339933?logo=node.js" alt="node requirement" />
-<a href="#license"><img src="https://img.shields.io/badge/License-ISC-blue.svg" alt="license" /></a>
-</div>
-
-
-<p>CLI for building web applications with the Slice.js framework</p>
-
-</div>
-
-## Installation
-
-### Local (Recommended)
-
-1. Install as a development dependency:
-
-```bash
-npm install slicejs-cli --save-dev
-```
-
-2. Add to your `package.json` scripts:
-
-```json
-{
-  "scripts": {
-    "dev": "slice dev",
-    "build": "slice build",
-    "slice": "slice"
-  }
-}
-```
-
-3. usage:
-
-```bash
-npm run dev
-# or pass arguments
-npm run slice -- get Button
-```
-
-4. Use `slice` directly when the launcher command is available on your system
-   (commonly after a global install that puts `slice` in your PATH).
-   The launcher delegates to your nearest project-local `node_modules/slicejs-cli`
-   so project-pinned behavior is used from the project root and subdirectories.
-
-```bash
-slice dev
-slice build
-slice version
-```
-
-If `slice` is not available in your shell, use:
-
-```bash
-npx slicejs-cli dev
-```
-
-You can disable launcher delegation for a command when needed:
-
-```bash
-SLICE_NO_LOCAL_DELEGATION=1 slice version
-```
-
-### Global (Not Recommended)
-
-Global installations can lead to version mismatches and "works on my machine" issues.
-
-```bash
-npm install -g slicejs-cli
-```
-
-## Usage
-
-After installation, prefer your project-local CLI. When the `slice` launcher command is
-available, it automatically delegates to the nearest local `slicejs-cli` install.
-
-Use the `slice` command directly:
-
-```bash
-slice [command] [options]
-```
-
-Or with npx (without global install):
-
-```bash
-npx slicejs-cli [command]
-```
-
-Use `npx slicejs-cli [command]` as a fallback when the `slice` launcher command is unavailable.
-
-## Essential Commands
-
-### Initialize a project
-
-```bash
-slice init
-```
-
-Initializes a Slice.js project with the full structure (`src/` and `api/`), installs initial Visual components, and configures npm scripts.
-
-### Development server
-
-```bash
-# Default port (3000)
-slice dev
-
-# Custom port
-slice dev -p 8080
-```
-
-### Production build + server
-
-```bash
-# Build production output (minified + obfuscated by default)
-slice build
-
-# Disable minification or obfuscation
-slice build --no-minify
-slice build --no-obfuscate
-
-# Start production server (serves /dist)
-slice start
-slice start -p 8080
-```
-
-### Component management (local)
-
-```bash
-# Create a component (interactive)
-slice component create
-
-# List local components
-slice component list
-
-# Delete a component (interactive)
-slice component delete
-```
-
-Shortcuts:
-```bash
-slice comp create
-slice comp ls
-slice comp remove
-```
-
-### Official component registry
-
-```bash
-# Install Visual components
-slice get Button Card Input
-
-# Install a Service component
-slice get FetchManager --service
-
-# Force overwrite
-slice get Button --force
-
-# Browse available components
-slice browse
-
-# Update all local components
-slice sync
-slice sync --force
-```
-
-Shortcuts:
-```bash
-slice get Button
-slice browse
-slice sync
-```
-
-### Utilities
-
-```bash
-# Version info
-slice version
-slice v
-
-# Updates (CLI and Framework)
-slice update              # Check and prompt to update
-slice update --yes        # Update everything automatically
-slice update --cli        # CLI only
-slice update --framework  # Framework only
-
-# Help
-slice --help
-slice [command] --help
-```
-
-## npm Scripts
-
-`slice init` automatically configures the recommended scripts in your `package.json`:
-
-```json
-{
-  "scripts": {
-    "dev": "slice dev",
-    "start": "slice start",
-    "get": "slice get",
-    "browse": "slice browse",
-    "sync": "slice sync",
-    "component:create": "slice component create",
-    "component:list": "slice component list",
-    "component:delete": "slice component delete"
-  }
-}
-```
-
-Usage:
-```bash
-npm run dev
-npm run get
-npm run browse
-```
-
-## Quick Start
-
-```bash
-# 1. Create a new project directory
-mkdir my-slice-project
-cd my-slice-project
-
-# 2. Initialize npm and install Slice CLI
-npm init -y
-npm install slicejs-cli --save-dev
-
-# 3. Initialize Slice.js project
-slice init
-
-# 4. Start development server
-slice dev
-
-# 5. Open browser at http://localhost:3000
-```
-
-## Common Workflows
-
-### Starting a New Project
-
-```bash
-slice init
-slice dev
-```
-
-### Production Build + Start
-
-```bash
-slice build
-slice start
-```
-
-### Adding Components
-
-```bash
-# Browse available components
-slice browse
-
-# Install specific components
-slice get Button Card Input
-
-# Create custom component
-slice component create
-```
-
-### Keeping Components Updated
-
-```bash
-# Check what needs updating
-slice browse
-
-# Update all components
-slice sync
-```
-
-## Development Mode
-
-The development server (`slice dev`) provides:
-
-- ✅ Hot reload
-- ✅ Serves directly from `/src`
-- ✅ No build step
-- ✅ Port validation
-- ✅ Clear error messages
-
-## Production Mode
-
-The production workflow uses `slice build` + `slice start`:
-
-- ✅ Builds to `/dist`
-- ✅ Generates bundles into `/dist/bundles`
-- ✅ Generates a dedicated framework bundle for Structural components (`slice-bundle.framework.js`)
-- ✅ Minifies + obfuscates by default
-- ✅ Serves production assets only
-
-## Requirements
-
-- Node.js >= 20.0.0
-- npm or yarn
-
-## Configuration
-
-Project configuration is stored in `src/sliceConfig.json` and is created automatically by `slice init`.
-
-In production, `publicFolders` defines **public asset folders** served by the server (defaults to
-`/Themes`, `/Styles`, `/assets`). This keeps source-only folders private while exposing the assets
-your app needs.
-
-## Features
-
-- 🚀 Development server with hot reload
-- 📦 Official component registry
-- 🎨 Visual and Service component types
-- ✨ Interactive component creation
-- 🔄 Automatic component synchronization
-- 🛠️ Built-in validation and error handling
-
-### Smart Updates
-
-- Detects whether the CLI in use is global or local
-- Shows an update plan (GLOBAL/PROJECT) before execution
-- Offers to include global CLI update interactively
-- Applies `uninstall` + `install @latest` to ensure latest versions
-
-### Cross-platform Paths
-
-- Centralized path helper avoids `../../..`
-- Windows/Linux/Mac compatibility using `import.meta.url` and `fileURLToPath`
-
-## Troubleshooting
-
-### Port already in use
-
-```bash
-# Use a different port
-slice dev -p 8080
-```
-
-### Project not initialized
-
-```bash
-# Make sure to run init first
-slice init
-```
-
-### Command not found
-
-```bash
-# If the launcher command is unavailable, run the local CLI via npx
-npx slicejs-cli dev
-
-# Optional: install globally to expose the slice launcher command
-npm install -g slicejs-cli
-```
-
-## Links
-
-- 📘 CLI Documentation: https://slice-js-docs.vercel.app/Documentation/CLI
-- 🐙 GitHub: https://github.com/VKneider/slice-cli
-- 📦 npm: https://www.npmjs.com/package/slicejs-cli
-
-## License
-
-ISC
-
-## Author
-
-vkneider
+<div align="center">
+  <img src="./assets/Slice.js-logo.png" alt="Slice.js logo" width="150" />
+  <h1>Slice.js CLI</h1>
+  <p>Command-line client for building web applications with the Slice.js framework</p>
+  <p>
+    <a href="https://slice-js-docs.vercel.app/Documentation/CLI"><strong>Explore the docs »</strong></a>
+    <br />
+    <a href="https://www.npmjs.com/package/slicejs-cli"><img src="https://img.shields.io/npm/v/slicejs-cli.svg?label=CLI" alt="npm version" /></a>
+    <img src="https://img.shields.io/badge/Node-%E2%89%A5%2020.0.0-339933?logo=node.js" alt="node requirement" />
+    <a href="#license"><img src="https://img.shields.io/badge/License-ISC-blue.svg" alt="license" /></a>
+  </p>
+</div>
+
+## About this repository
+
+This repository contains the Slice.js CLI (`slicejs-cli`), the command-line tool for developing applications with the Slice.js framework. It includes a development server, build system, component management, and more.
+
+## Prerequisites
+
+- Node.js >= 20
+- npm or pnpm
+
+## Local development
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/VKneider/slicejs-cli.git
+   cd slicejs-cli
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Test changes locally**
+   ```bash
+   node client.js --help
+   ```
+
+   To bypass delegation to a global installation:
+   ```bash
+   SLICE_NO_LOCAL_DELEGATION=1 node client.js --help
+   ```
+
+4. **Run tests**
+   ```bash
+   npm test
+   ```
+
+## Installation (for users)
+
+### Local (Recommended)
+
+```bash
+npm install slicejs-cli --save-dev
+```
+
+### Global (Not recommended)
+
+```bash
+npm install -g slicejs-cli
+```
+
+## Main commands
+
+| Command | Description |
+|---------|-------------|
+| `slice init` | Initialize a Slice.js project |
+| `slice dev` | Development server with hot reload |
+| `slice build` | Build for production |
+| `slice start` | Serve production build |
+| `slice get <component>` | Install components from the official registry |
+| `slice browse` | Browse available components |
+| `slice component create` | Create a local component |
+| `slice doctor` | Run project diagnostics |
+| `slice postinstall` | Configure npm scripts (alternative to postinstall) |
+
+## Postinstall Scripts
+
+When you install `slicejs-cli`, the `postinstall` script automatically configures `slice:*` npm scripts in your `package.json`:
+
+```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"
+  }
+}
+```
+
+If you installed with `--ignore-scripts`, run manually:
+
+```bash
+npx slicejs-cli postinstall
+```
+
+## Quick start
+
+```bash
+# 1. Create project
+mkdir my-project && cd my-project
+npm init -y
+
+# 2. Install CLI
+npm install slicejs-cli --save-dev
+
+# 3. Initialize
+npx slicejs-cli init
+
+# 4. Development
+npx slicejs-cli dev
+```
+
+## Tests
+
+The CLI uses Node.js native test runner:
+
+```bash
+# All tests
+node --test
+
+# Specific tests
+node --test tests/postinstall-command.test.js
+```
+
+## Project structure
+
+```
+slicejs-cli/
+├── client.js              # CLI entry point
+├── commands/              # Command implementations
+│   ├── init/              # slice init
+│   ├── build/             # slice build
+│   ├── startServer/       # slice dev / slice start
+│   ├── createComponent/   # slice component create
+│   └── utils/             # PathHelper, VersionChecker, etc.
+├── tests/                 # Tests
+└── post.js                # Postinstall hook
+```
+
+## Local delegation
+
+When the `slice` command is globally available, it automatically delegates to the project-local CLI (`node_modules/slicejs-cli`). To disable:
+
+```bash
+SLICE_NO_LOCAL_DELEGATION=1 slice version
+```
+
+## Contributing
+
+We welcome contributions. Please review the guidelines in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before submitting changes.
+
+## License
+
+Distributed under the ISC License. See `LICENSE` for more information.
+
+## Links
+
+- 📘 Documentation: https://slice-js-docs.vercel.app/Documentation/CLI
+- 🐙 GitHub: https://github.com/VKneider/slicejs-cli
+- 📦 npm: https://www.npmjs.com/package/slicejs-cli

package/client.js

@@ -528,6 +528,68 @@ sliceClient
     });
   });
 
+// POSTINSTALL COMMAND - Manual alternative to postinstall
+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';
+    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');
+      return;
+    }
+
+    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');
+    }
+  });
+
 // Enhanced help
 sliceClient
   .option("--no-version-check", "Skip version check for this command")
@@ -550,8 +612,9 @@ Common Usage Examples:
   slice sync                     - Update local components to latest versions
   slice component create         - Create new local component
   slice list                     - List all local components
-  slice doctor                   - Run project diagnostics
-  slice types generate           - Generate TypeScript typings for slice.build
+  slice doctor                   - Run project diagnostics
+  slice types generate           - Generate TypeScript typings for slice.build
+  slice postinstall              - Show post-install setup guide
 
 Command Categories:
   • init, dev, start             - Project lifecycle (development only)
@@ -559,7 +622,7 @@ Command Categories:
   • component <cmd>              - Local component management
   • registry <cmd>               - Official repository operations
   • types generate               - Type declarations from static props
-  • version, update, doctor      - Maintenance commands
+  • version, update, doctor, setup - Maintenance commands
 
 Development Workflow:
   • slice init          - Initialize project

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slicejs-cli",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Command client for developing web applications with Slice.js framework",
   "main": "client.js",
   "bin": {

package/post.js

@@ -1,15 +1,11 @@
 import fs from 'fs';
-import { fileURLToPath } from 'url';
 import path from 'path';
-import Print from './commands/Print.js';
+import { fileURLToPath } from 'url';
+import { getProjectRoot } from './commands/utils/PathHelper.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.');
@@ -18,8 +14,52 @@ if (isGlobal) {
     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');
+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);

package/tests/postinstall-command.test.js

@@ -0,0 +1,72 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const clientPath = path.join(__dirname, '..', 'client.js');
+const source = fs.readFileSync(clientPath, 'utf-8');
+
+test('postinstall command is registered in client.js', () => {
+  const hasSetupCommand = source.includes('.command("postinstall")');
+  assert.ok(hasSetupCommand, 'client.js must register a "postinstall" command');
+});
+
+test('postinstall command has a description', () => {
+  const match = source.match(/\.command\(["']postinstall["']\)\s*\.description\(["']([^"']+)["']\)/);
+  assert.ok(match, 'postinstall command must have a .description() call');
+  assert.ok(match[1].length > 0, 'postinstall command description must not be empty');
+});
+
+test('postinstall command checks npm_config_global environment variable', () => {
+  const hasGlobalCheck = source.includes('npm_config_global');
+  assert.ok(hasGlobalCheck, 'postinstall command must check npm_config_global to detect global installation');
+});
+
+test('postinstall command prints global install warning', () => {
+  const hasGlobalWarning = source.includes('Global installation');
+  assert.ok(hasGlobalWarning, 'postinstall command must warn about global installation');
+});
+
+test('postinstall command prints local install success message', () => {
+  const hasSuccessMsg = source.includes('installed successfully');
+  assert.ok(hasSuccessMsg, 'postinstall command must show success message for local installs');
+});
+
+test('postinstall command uses getProjectRoot from PathHelper', () => {
+  const hasPathHelper = source.includes("getProjectRoot(import.meta.url)");
+  assert.ok(hasPathHelper, 'postinstall command must use getProjectRoot resolver');
+});
+
+test('postinstall command writes npm scripts to package.json via fs', () => {
+  const hasFsWrite = source.includes('writeFileSync(pkgPath');
+  assert.ok(hasFsWrite, 'postinstall command must write scripts to package.json');
+});
+
+test('postinstall command writes slice:dev script to package.json', () => {
+  const hasDevScript = source.includes("'slice:dev': 'slice dev'");
+  assert.ok(hasDevScript, 'postinstall command must add "slice:dev" script to package.json');
+});
+
+test('postinstall command writes all slice:* scripts to package.json', () => {
+  const scripts = [
+    'slice:dev', 'slice:start', 'slice:create', 'slice:list',
+    'slice:delete', 'slice:init', 'slice:get', 'slice:browse',
+    'slice:sync', 'slice:version', 'slice:update'
+  ];
+  for (const script of scripts) {
+    assert.ok(source.includes(script), `postinstall command must configure ${script} script`);
+  }
+});
+
+test('postinstall command action is a function', () => {
+  const SetupActionPattern = /\.command\(["']postinstall["']\)[\s\S]*?\.action\(\(\)\s*=>\s*\{[\s\S]*?\}\)/;
+  const match = source.match(SetupActionPattern);
+  assert.ok(match, 'postinstall command must have an .action() with arrow function');
+});
+
+test('postinstall command provides npm uninstall -g instruction for global installs', () => {
+  const hasUninstallInstruction = source.includes('npm uninstall -g slicejs-cli');
+  assert.ok(hasUninstallInstruction, 'postinstall command must tell users how to uninstall global CLI');
+});

package/refactor.md

@@ -1,271 +0,0 @@
-# Plan de Refactorización del CLI para MCP
-
-## Objetivo
-Separar la lógica de negocio de la presentación CLI para permitir importación directa desde el MCP server, manteniendo **100% de compatibilidad** con el CLI actual.
-
----
-
-## Estructura Propuesta
-
-```
-commands/
-├── createComponent/
-│   ├── createComponent.js        # CLI wrapper (presentación)
-│   ├── core.js                   # ⭐ NUEVO - Lógica pura exportable
-│   └── VisualComponentTemplate.js
-│
-├── listComponents/
-│   ├── listComponents.js         # CLI wrapper (presentación)
-│   └── core.js                   # ⭐ NUEVO - Lógica pura exportable
-│
-├── deleteComponent/
-│   ├── deleteComponent.js        # CLI wrapper (presentación)
-│   └── core.js                   # ⭐ NUEVO - Lógica pura exportable
-│
-├── getComponent/
-│   ├── getComponent.js           # CLI wrapper (presentación)
-│   └── core.js                   # ⭐ NUEVO - Lógica pura exportable
-│
-└── init/
-    ├── init.js                   # CLI wrapper (presentación)
-    └── core.js                   # ⭐ NUEVO - Lógica pura exportable
-```
-
----
-
-## Principios de Refactorización
-
-### 1. Separación de Responsabilidades
-- **core.js**: Lógica pura sin dependencias de CLI (Print, chalk, Table, inquirer)
-- **[comando].js**: Solo presentación CLI, usa funciones del core
-
-### 2. Funciones Puras en Core
-- Reciben parámetros explícitos (no usan import.meta.url implícitamente)
-- Retornan objetos con estructura `{ success: boolean, data?, error? }`
-- No imprimen a consola directamente
-- Son agnósticas del entorno (CLI vs MCP)
-
-### 3. Compatibilidad Total
-- Los archivos CLI actuales se mantienen funcionales
-- Misma API de comandos
-- Mismo comportamiento observable
-- No romper ningún test existente
-
----
-
-## Pasos de Refactorización por Comando
-
-### Fase 1: List Components
-
-#### Paso 1.1: Análisis del Código Actual
-- Identificar toda la lógica de negocio en `listComponents.js`
-- Separar mentalmente: lógica vs presentación
-- Funciones a extraer: `loadConfig`, `getComponents`, `countComponentFiles`, `listComponentDirectories`
-
-#### Paso 1.2: Crear core.js
-- Crear archivo `commands/listComponents/core.js`
-- Extraer funciones de lógica pura
-- Modificar para que acepten `projectPath` como parámetro opcional
-- Retornar objetos estructurados en lugar de imprimir
-
-#### Paso 1.3: Adaptar listComponents.js
-- Importar funciones desde `core.js`
-- Mantener solo la lógica de presentación (Print, Table, chalk)
-- Re-exportar funciones del core: `export { getComponents, ... } from './core.js'`
-
-#### Paso 1.4: Verificación
-- Ejecutar `slice list` - debe funcionar idéntico
-- Probar importación directa: `import { getComponents } from './commands/listComponents/core.js'`
-- Verificar que retorna datos correctos sin CLI
-
----
-
-### Fase 2: Create Component
-
-#### Paso 2.1: Análisis
-- Identificar lógica: validaciones, generación de templates, creación de archivos
-- Identificar presentación: mensajes de error, comandos de ejemplo
-
-#### Paso 2.2: Crear core.js
-- Crear `commands/createComponent/core.js`
-- Extraer: `validateComponentName`, `validateCategory`, `generateTemplate`, `createComponentFiles`
-- Cada función retorna `{ success, data, error }`
-
-#### Paso 2.3: Adaptar createComponent.js
-- Importar funciones del core
-- Mantener solo los Print y mensajes de ayuda
-- Re-exportar funciones del core
-
-#### Paso 2.4: Verificación
-- Ejecutar `slice component create` - debe funcionar igual
-- Probar importación directa y creación programática
-
----
-
-### Fase 3: Delete Component
-
-#### Paso 3.1: Análisis
-- Identificar lógica: validaciones, verificación de existencia, eliminación de archivos
-- Identificar presentación: mensajes de confirmación, errores
-
-#### Paso 3.2: Crear core.js
-- Crear `commands/deleteComponent/core.js`
-- Extraer: `deleteComponentFiles` (con validaciones integradas)
-
-#### Paso 3.3: Adaptar deleteComponent.js
-- Importar del core
-- Mantener presentación CLI
-- Re-exportar funciones
-
-#### Paso 3.4: Verificación
-- Ejecutar `slice component delete`
-- Verificar funcionamiento idéntico
-
----
-
-### Fase 4: Get Component (Registry)
-
-#### Paso 4.1: Análisis
-- Identificar lógica: descarga de registry, instalación de componentes, actualización
-- Es el más complejo - tiene clase ComponentRegistry
-
-#### Paso 4.2: Crear core.js
-- Crear `commands/getComponent/core.js`
-- Extraer clase `ComponentRegistry` limpia (sin inquirer, sin Print)
-- Métodos retornan objetos estructurados
-
-#### Paso 4.3: Adaptar getComponent.js
-- Importar ComponentRegistry del core
-- Envolver con lógica interactiva (inquirer) solo en CLI
-- Mantener funciones: `getComponents`, `listComponents`, `syncComponents`
-
-#### Paso 4.4: Verificación
-- Probar: `slice get Button`, `slice browse`, `slice sync`
-- Verificar descarga y registro correctos
-
----
-
-### Fase 5: Init Project
-
-#### Paso 5.1: Análisis
-- Identificar lógica: copia de estructuras, configuración de package.json
-- Separar spinners y mensajes visuales
-
-#### Paso 5.2: Crear core.js
-- Crear `commands/init/core.js`
-- Extraer: funciones de scaffolding, configuración
-
-#### Paso 5.3: Adaptar init.js
-- Importar del core
-- Mantener spinners y presentación
-- Re-exportar funciones
-
-#### Paso 5.4: Verificación
-- Ejecutar `slice init` en proyecto nuevo
-- Verificar estructura completa creada
-
----
-
-## Patrón de Estructura de Funciones Core
-
-### Firma de Función Estándar
-```
-function operationName({ param1, param2, projectPath = null }) {
-    // Validaciones
-    // Lógica de negocio
-    return { success: boolean, data?, error? }
-}
-```
-
-### Objeto de Retorno Estándar
-```javascript
-// Éxito
-{
-    success: true,
-    data: { ... },
-    // Campos adicionales específicos
-}
-
-// Error
-{
-    success: false,
-    error: "mensaje descriptivo"
-}
-```
-
----
-
-## Estrategia de Dependencias
-
-### Dependencias Permitidas en core.js
-- ✅ `fs`, `fs-extra`
-- ✅ `path`
-- ✅ `Validations.js` (lógica pura)
-- ✅ Helpers de PathHelper (refactorizar para aceptar projectPath)
-
-### Dependencias NO Permitidas en core.js
-- ❌ `Print.js` (específico de CLI)
-- ❌ `chalk` (presentación)
-- ❌ `cli-table3` (presentación)
-- ❌ `inquirer` (interacción CLI)
-- ❌ `ora` (spinners CLI)
-
----
-
-## Refactorización de PathHelper
-
-### Problema Actual
-PathHelper usa `import.meta.url` internamente, asumiendo que se llama desde dentro del CLI
-
-### Solución
-Crear versiones alternativas que acepten `projectPath`:
-
-```
-// Versión CLI (actual)
-getSrcPath(import.meta.url, ...paths)
-
-// Versión core (nueva)
-getProjectSrcPath(projectPath, ...paths)
-```
-
-O mejor: modificar funciones existentes para aceptar ambos modos:
-```
-getSrcPath(importMetaUrlOrProjectPath, ...paths)
-```
-
----
-
-## Testing de la Refactorización
-
-### Test 1: CLI Functionality
-Para cada comando refactorizado:
-- Ejecutar comando CLI
-- Verificar output idéntico al anterior
-- Verificar archivos creados/modificados
-
-### Test 2: Importación Directa
-```javascript
-// test-mcp-import.js
-import { getComponents } from './commands/listComponents/core.js';
-
-const result = getComponents('/ruta/proyecto');
-console.log(result); // Debe retornar objeto con componentes
-```
-
-### Test 3: Sin Dependencias CLI
-Verificar que core.js no tiene imports de Print, chalk, etc:
-```bash
-grep -r "from.*Print" commands/*/core.js  # debe estar vacío
-grep -r "from.*chalk" commands/*/core.js  # debe estar vacío
-```
-
----
-
-## Orden de Implementación Recomendado
-
-1. **listComponents** (más simple, establece patrón)
-2. **createComponent** (complejidad media)
-3. **deleteComponent** (similar a create)
-4. **getComponent** (más complejo, tiene clase)
-5. **init** (el más complejo)
-