kimu-cli 0.1.0 → 1.0.0

package/docs/README.md

@@ -0,0 +1,126 @@
+# KIMU-CLI Documentation
+
+Welcome to the official documentation for KIMU-CLI, the command-line interface for the KIMU framework ecosystem.
+
+## 🚀 Quick Links
+
+### **New to KIMU-CLI?**
+Start here: [**Getting Started Guide**](getting-started.md) ⭐
+
+This comprehensive guide walks you through:
+- Installing KIMU-CLI
+- Creating your first project
+- Understanding the project structure
+- Making your first changes
+- Building and deploying
+
+### **Need Quick Reference?**
+Common commands: [**Quick Reference**](quick-reference.md) 🚀
+
+One-page guide with:
+- Most used commands
+- Common workflows
+- Troubleshooting tips
+- Configuration examples
+
+### Documentation Index
+- [**Documentation Index**](index.md) - Complete documentation map
+- [**Introduction**](intro.md) - What is KIMU-CLI and why use it
+- [**Command Reference**](command-kimu.md) - All available commands
+- [**Distribution Guide**](distribution.md) - Advanced installation and publishing
+
+## 📚 Available Commands
+
+### ✅ Ready to Use
+- [`kimu create`](commands/create.md) - Create new KIMU projects
+- [`kimu new`](commands/new.md) - Create components from templates
+- [`kimu info`](commands/info.md) - Show project information
+- [`kimu version`](commands/version.md) - Display version information
+- [`kimu help`](commands/help.md) - Get command help
+
+### ⏳ Coming Soon
+- [`kimu install`](commands/install.md) - Install modules and extensions
+- [`kimu remove`](commands/remove.md) - Remove packages
+- [`kimu list`](commands/list.md) - List available/installed packages
+- [`kimu build`](commands/build.md) - Build for production
+- [`kimu dev`](commands/dev.md) - Start development server
+- [`kimu serve`](commands/serve.md) - Serve built project
+- [`kimu doctor`](commands/doctor.md) - Project diagnostics
+
+## 🎯 Quick Start
+
+### Installation
+```bash
+# Global installation
+npm install -g kimu-cli
+
+# Or use with npx
+npx kimu-cli create my-app
+```
+
+### Create a Project
+```bash
+# Create new project
+kimu create my-awesome-app
+
+# Navigate to it
+cd my-awesome-app
+
+# Start developing
+npm run dev
+```
+
+### Get Help
+```bash
+# General help
+kimu --help
+
+# Command-specific help
+kimu create --help
+
+# Check version
+kimu --version
+```
+
+## 📖 Documentation Structure
+
+```
+docs/
+├── README.md              # This file
+├── index.md               # Documentation index and navigation
+├── getting-started.md     # Complete tutorial for beginners
+├── intro.md               # Introduction to KIMU-CLI
+├── command-kimu.md        # Complete command reference
+├── distribution.md        # Installation and publishing guide
+└── commands/              # Detailed command documentation
+    ├── create.md
+    ├── info.md
+    ├── version.md
+    ├── help.md
+    └── ... (more commands)
+```
+
+## 🔗 External Resources
+
+- **NPM Package**: [kimu-cli on npm](https://www.npmjs.com/package/kimu-cli)
+- **GitHub Repository**: [UnicoVerso/kimu-cli](https://github.com/UnicoVerso/kimu-cli)
+- **KIMU Core Framework**: [kimu-core on npm](https://www.npmjs.com/package/kimu-core)
+- **KIMU Core Repo**: [UnicoVerso/kimu-core](https://github.com/UnicoVerso/kimu-core)
+
+## 💡 Need Help?
+
+- **Documentation**: You're reading it! Browse the links above
+- **GitHub Issues**: [Report bugs or request features](https://github.com/UnicoVerso/kimu-cli/issues)
+- **GitHub Discussions**: [Ask questions and share ideas](https://github.com/UnicoVerso/kimu-cli/discussions)
+
+## 📝 Contributing to Documentation
+
+Found an error or want to improve the docs? Contributions are welcome!
+
+1. Fork the repository
+2. Edit the markdown files in `/docs/`
+3. Submit a pull request
+
+---
+
+**Ready to start building with KIMU?** Begin with the [Getting Started Guide](getting-started.md)! 🚀

package/docs/command-kimu.md

@@ -2,10 +2,23 @@
 
 The `kimu` command is the main entry point for KIMU-CLI and provides access to all framework tools and utilities.
 
+## Installation
+
+### Global Installation
+```bash
+npm install -g kimu-cli
+```
+
+### Using npx (No Installation)
+```bash
+npx kimu-cli <command> [options]
+```
+
 ## Basic Usage
 ```bash
 kimu <command> [options]
 kimu <command> --help
+kimu --version
 ```
 
 ## Global Options
@@ -20,6 +33,7 @@ These options are available for all commands:
 | Command | Description | Status |
 |---------|-------------|---------|
 | `create <name>` | Create a new KIMU project | ✅ **Available** |
+| `new <type> <name>` | Create components from templates | ✅ **Available** |
 | `info` | Show project information and status | ✅ **Available** |
 | `doctor` | Run project health diagnostics | ⏳ **Planned** |
 

package/docs/commands/create.md

@@ -35,24 +35,69 @@ kimu create my-app --git --no-install
 
 ## What it creates
 The command performs the following steps:
-1. **Clones kimu-core repository** from GitHub (https://github.com/UnicoVerso/kimu-core.git)
-2. **Removes .git directory** to clean the project from the original repository history
-3. **Updates package.json** with the new project name
-4. **Installs npm dependencies** (unless `--no-install` is used)
-5. **Initializes new git repository** (if `--git` flag is used) with an initial commit
-6. **Provides next steps** for the user to continue development
+1. **Creates project folder** and validates it doesn't exist (or confirms overwrite)
+2. **Initializes npm** with `npm init -y` creating `package.json`
+3. **Installs kimu-core** via `npm install kimu-core` from npm registry
+4. **Copies all files** from `node_modules/kimu-core` to the project root:
+   - `src/` - Source code with core framework, extensions, and modules
+   - `scripts/` - Build and utility scripts
+   - `public/` - Static assets
+   - `README.md`, `LICENSE`, configuration files, etc.
+   - Excludes: `node_modules/`, `dist/`, `.git/`, `.env`, `package-lock.json`
+5. **Removes kimu-core** from `node_modules` after copying
+6. **Installs dependencies** with `npm install` (unless `--no-install` is used)
+7. **Generates build config** by running `npm run generate-config:dev`
+8. **Updates package.json** with the project name
+9. **Initializes git repository** (if `--git` flag is used) with initial commit
+10. **Displays success message** with next steps
+
+## Project Structure Created
+```
+my-app/
+├── src/                    # Source code
+│   ├── core/              # KIMU core framework
+│   ├── extensions/        # UI extensions
+│   ├── modules/           # Modules (router, i18n, etc.)
+│   └── main.ts            # Application entry point
+├── public/                # Static assets
+├── scripts/               # Build scripts
+├── dist/                  # Build output (created on build)
+├── kimu.config.json       # KIMU configuration
+├── kimu-build-config.ts   # Build configuration (generated)
+├── package.json           # NPM dependencies
+├── tsconfig.json          # TypeScript configuration
+├── vite.config.ts         # Vite bundler config
+└── README.md              # Project documentation
+```
 
 ## Notes
 - The project name must contain only lowercase letters, numbers, and hyphens
-- The command will fail if the target folder already exists (unless `--force` is used)
-- Requires git to be installed on the system for repository cloning
-- Internet connection is required to clone the kimu-core repository
-- If cloning fails, the command will clean up any partial files created
-- The original kimu-core git history is completely removed from the new project
+- The command will ask for confirmation if the target folder already exists (unless `--force` is used)
+- Requires Node.js >= 18.0.0 and npm >= 8.0.0
+- Internet connection is required to download kimu-core from npm
+- Uses kimu-core from npm registry (https://www.npmjs.com/package/kimu-core)
+- All framework files are copied locally, making the project fully independent
+- The `kimu-build-config.ts` is auto-generated based on your environment
+
+## Next Steps After Creation
+```bash
+# Navigate to project
+cd my-app
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Check project info
+kimu info --verbose
+```
 
 ## Future features (planned)
 - Template support (`--template basic|dashboard|chat`)
-- Custom repository URLs for cloning different project templates
-- Offline mode with cached project templates
-- Configuration file customization options
-- Integration with KIMU module and extension marketplace
+- Interactive prompts for project configuration
+- Offline mode with cached templates
+- Custom npm registry support
+- Module pre-selection during creation
+- Extension marketplace integration

package/docs/commands/install.md

@@ -6,13 +6,21 @@ Install modules and extensions for your KIMU project.
 ```bash
 kimu install module <name> [options]
 kimu install extension <name> [options]
-kimu install <name> [options]
 ```
 
 ## Arguments
 - `module <name>`: install a specific module from the KIMU modules registry
 - `extension <name>`: install a specific extension from the KIMU extensions registry
-- `<name>`: auto-detect type and install module or extension
+
+> ⚠️ **It is strongly recommended to always specify `module` or `extension` explicitly.**
+> The generic `kimu install <name>` syntax is discouraged to avoid ambiguity with third-party or similarly named packages.
+
+## Abbreviations
+
+You can use short aliases for install commands:
+
+- `kimu i m <name>` → `kimu install module <name>`
+- `kimu i e <name>` → `kimu install extension <name>`
 
 ## Options
 - `--save-dev`: install as development dependency
@@ -25,12 +33,13 @@ kimu install <name> [options]
 ```bash
 # Install a module
 kimu install module router
+# Or using abbreviation
+kimu i m router
 
 # Install an extension
 kimu install extension dashboard
-
-# Auto-detect and install
-kimu install analytics
+# Or using abbreviation
+kimu i e dashboard
 
 # Install specific version
 kimu install module router --version 1.2.0
@@ -40,8 +49,29 @@ kimu install module router --registry https://custom-registry.com
 
 # Force reinstall
 kimu install module router --force
+
+# Verbose output
+kimu install module analytics --verbose
 ```
 
+## Listing available and installed modules/extensions
+
+To list available modules/extensions from the registry:
+```bash
+kimu list modules      # Shows all modules with [installed] marker
+kimu list extensions   # Shows all extensions with [installed] marker
+```
+
+To list only installed modules/extensions in your project:
+```bash
+kimu list installed    # Shows installed modules and extensions
+```
+
+The `list modules` and `list extensions` commands show:
+- ✓ Green checkmark for installed packages
+- ○ Gray circle for available packages
+- `[installed]` label for clarity
+
 ## What it does
 - Downloads the specified module or extension from the registry
 - Resolves and installs dependencies
@@ -62,6 +92,20 @@ kimu install module router --force
 - Custom registries supported via `--registry` option
 
 ## Status
-⚠️ **This command is planned but not yet implemented**
-- Current status: Command structure defined, implementation pending
-- Target: Full registry integration with dependency resolution
+✅ **Command available (mock version)**
+- Current status: The install command is available and simulates the installation of modules or extensions from the registry (mock). The real logic for download and integration will be added in future releases.
+- Target: Full registry integration and dependency resolution coming soon.
+
+### Current behavior (December 2025)
+- The command accepts the name of a module or extension and shows a simulated installation.
+- You must specify `module` or `extension` explicitly.
+- Example:
+  ```bash
+  kimu install module router
+  kimu i m router
+  kimu install extension kimu-home
+  kimu i e kimu-dashboard
+  kimu install module analytics --verbose
+  ```
+- Simulated success or error output.
+- The structure is ready to be connected to a real registry.

package/docs/commands/list.md

@@ -4,82 +4,70 @@ List available and installed modules and extensions.
 
 ## Syntax
 ```bash
-kimu list [type] [options]
+kimu list modules [options]
+kimu list extensions [options]
+kimu list installed [options]
 ```
 
+## Abbreviations
+
+You can use short aliases for list commands:
+
+- `kimu l m` → `kimu list modules`
+- `kimu l e` → `kimu list extensions`
+- `kimu l i` → `kimu list installed`
+
 ## Arguments
 - `modules`: list available modules from registry
 - `extensions`: list available extensions from registry
-- `installed`: list currently installed modules and extensions
-- `templates`: list available project templates
+- `installed`: list currently installed modules and extensions in your project
 
 ## Options
-- `--json`: output in JSON format
-- `--verbose`: show detailed information
-- `--registry <url>`: use custom registry URL
-- `--filter <pattern>`: filter results by name pattern
-- `--updates`: show available updates for installed packages
+- `--verbose`: show detailed information (descriptions, etc.)
 
 ## Examples
 ```bash
 # List all available modules
 kimu list modules
+# Or using abbreviation
+kimu l m
 
 # List all available extensions
 kimu list extensions
+# Or using abbreviation
+kimu l e
 
-# List installed packages
+# List installed packages in current project
 kimu list installed
-
-# List available templates
-kimu list templates
-
-# Output in JSON format
-kimu list modules --json
+# Or using abbreviation
+kimu l i
 
 # Show detailed information
-kimu list installed --verbose
-
-# Filter by pattern
-kimu list modules --filter "router*"
-
-# Check for updates
-kimu list installed --updates
+kimu list modules --verbose
+kimu l e --verbose
 ```
 
 ## Output Information
 
-### Basic listing shows:
+### `kimu list modules` and `kimu list extensions` show:
 - Package name and version
-- Short description
-- Installation status (for installed packages)
-
-### Verbose listing additionally shows:
-- Full description
-- Author information
-- Dependencies
-- Compatibility requirements
-- Last update date
-- Download statistics
-
-### Update checking shows:
-- Current installed version
-- Latest available version
-- Update priority (patch/minor/major)
-- Changelog summary
+- Installation status with visual indicators:
+  - ✓ (green checkmark) for installed packages
+  - ○ (gray circle) for available packages
+  - `[installed]` label for clarity
+- With `--verbose`: full description
 
-## Notes
-- Requires internet connection for registry listings
-- Cached results are used when possible for performance
-- Updates can be checked for compatibility before installation
-- Supports filtering and search functionality
+### `kimu list installed` shows:
+- All modules and extensions currently installed in your project
+- Read from `kimu.config.json`
+- Grouped by type (Modules and Extensions)
 
-## Registry Sources
-- Official modules and extensions from KIMU repositories
-- Community packages from verified sources
-- Custom registries via `--registry` option
+## Notes
+- `list modules` and `list extensions` read from registry and check installation status from `kimu.config.json`
+- `list installed` only shows packages actually installed in your project
+- Must be run from within a KIMU project directory (for installation status)
 
 ## Status
-⚠️ **This command is planned but not yet implemented**
-- Current status: Command structure defined, implementation pending
-- Target: Full registry browsing and package discovery
+✅ **Command available (mock version)**
+- Current status: The list command is available and reads installation status from kimu.config.json. Registry data is mocked, real registry integration coming soon.
+- Target: Full registry integration with real-time data and search functionality.