kimu-cli 0.1.0

package/docs/commands/install.md

@@ -0,0 +1,67 @@
+# kimu install
+
+Install modules and extensions for your KIMU project.
+
+## Syntax
+```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
+
+## Options
+- `--save-dev`: install as development dependency
+- `--registry <url>`: use custom registry URL
+- `--version <version>`: install specific version
+- `--force`: force reinstall if already installed
+- `--verbose`: show detailed installation progress
+
+## Examples
+```bash
+# Install a module
+kimu install module router
+
+# Install an extension
+kimu install extension dashboard
+
+# Auto-detect and install
+kimu install analytics
+
+# Install specific version
+kimu install module router --version 1.2.0
+
+# Install from custom registry
+kimu install module router --registry https://custom-registry.com
+
+# Force reinstall
+kimu install module router --force
+```
+
+## What it does
+- Downloads the specified module or extension from the registry
+- Resolves and installs dependencies
+- Updates kimu.config.json with the new installation
+- Verifies compatibility with current KIMU-Core version
+- Sets up module/extension in the correct project structure
+
+## Notes
+- Must be run from within a KIMU project directory
+- Automatically resolves dependencies and compatibility
+- Updates project configuration files
+- Supports both official and community packages
+- Requires internet connection to access registries
+
+## Registry Sources
+- Official KIMU modules: `https://github.com/unicoverso/kimu-modules`
+- Community extensions: `https://github.com/unicoverso/kimu-extensions`
+- 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

package/docs/commands/list.md

@@ -0,0 +1,85 @@
+# kimu list
+
+List available and installed modules and extensions.
+
+## Syntax
+```bash
+kimu list [type] [options]
+```
+
+## 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
+
+## 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
+
+## Examples
+```bash
+# List all available modules
+kimu list modules
+
+# List all available extensions
+kimu list extensions
+
+# List installed packages
+kimu list installed
+
+# List available templates
+kimu list templates
+
+# Output in JSON format
+kimu list modules --json
+
+# Show detailed information
+kimu list installed --verbose
+
+# Filter by pattern
+kimu list modules --filter "router*"
+
+# Check for updates
+kimu list installed --updates
+```
+
+## Output Information
+
+### Basic listing shows:
+- 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
+
+## 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
+
+## Registry Sources
+- Official modules and extensions from KIMU repositories
+- Community packages from verified sources
+- Custom registries via `--registry` option
+
+## Status
+⚠️ **This command is planned but not yet implemented**
+- Current status: Command structure defined, implementation pending
+- Target: Full registry browsing and package discovery

package/docs/commands/remove.md

@@ -0,0 +1,67 @@
+# kimu remove
+
+Remove modules and extensions from your KIMU project.
+
+## Syntax
+```bash
+kimu remove <name> [options]
+kimu remove module <name> [options]
+kimu remove extension <name> [options]
+```
+
+## Arguments
+- `<name>`: name of the module or extension to remove (auto-detected)
+- `module <name>`: explicitly remove a module
+- `extension <name>`: explicitly remove an extension
+
+## Options
+- `--force`: force removal without confirmation
+- `--keep-config`: remove files but keep configuration entries
+- `--cleanup`: also remove unused dependencies
+- `--verbose`: show detailed removal progress
+
+## Examples
+```bash
+# Remove a module or extension (auto-detect)
+kimu remove router
+
+# Explicitly remove a module
+kimu remove module analytics
+
+# Explicitly remove an extension
+kimu remove extension dashboard
+
+# Force removal without confirmation
+kimu remove router --force
+
+# Remove but keep configuration
+kimu remove router --keep-config
+
+# Remove with dependency cleanup
+kimu remove router --cleanup
+```
+
+## What it does
+- Removes module/extension files from the project
+- Updates kimu.config.json to remove configuration entries
+- Optionally removes unused dependencies
+- Cleans up build configuration references
+- Provides confirmation prompts for safety
+
+## Notes
+- Must be run from within a KIMU project directory
+- Prompts for confirmation unless `--force` is used
+- Can detect and remove orphaned dependencies with `--cleanup`
+- Updates all relevant configuration files
+- Preserves project integrity during removal
+
+## Safety Features
+- Confirmation prompts for destructive operations
+- Backup suggestions for important removals
+- Dependency impact analysis
+- Rollback instructions provided
+
+## Status
+⚠️ **This command is planned but not yet implemented**
+- Current status: Command structure defined, implementation pending
+- Target: Safe removal with dependency management

package/docs/commands/serve.md

@@ -0,0 +1,91 @@
+# kimu serve
+
+Serve the built KIMU project for testing and preview.
+
+## Syntax
+```bash
+kimu serve [options]
+```
+
+## Options
+- `--port <port>`: server port [default: 4000]
+- `--host <host>`: server host [default: localhost]
+- `--open`: automatically open browser
+- `--dist <dir>`: directory to serve [default: dist]
+- `--spa`: enable single-page application mode
+- `--cors`: enable CORS headers
+- `--verbose`: show detailed server logs
+
+## Examples
+```bash
+# Serve built project with defaults
+kimu serve
+
+# Serve on specific port
+kimu serve --port 8080
+
+# Serve and open browser
+kimu serve --open
+
+# Serve custom directory
+kimu serve --dist ./build
+
+# Enable SPA mode for client-side routing
+kimu serve --spa
+
+# Enable CORS for API testing
+kimu serve --cors
+
+# Network access with custom host
+kimu serve --host 0.0.0.0 --port 4000
+```
+
+## When to Use
+Use `kimu serve` to:
+- **Preview production builds** before deployment
+- **Test built applications** locally
+- **Share builds** with team members on local network
+- **Validate build output** and asset loading
+- **Debug production issues** in development environment
+
+## Server Features
+- **Static file serving**: Serves all built assets correctly
+- **SPA support**: Handles client-side routing with fallback to index.html
+- **CORS support**: Enables cross-origin requests for API testing
+- **Gzip compression**: Automatically compresses responses
+- **Cache headers**: Appropriate caching for static assets
+- **MIME type detection**: Proper content types for all file types
+
+## Difference from `kimu dev`
+| Feature | `kimu dev` | `kimu serve` |
+|---------|------------|--------------|
+| Purpose | Development | Preview built app |
+| Source | Live TypeScript compilation | Pre-built files |
+| Hot Reload | ✅ Yes | ❌ No |
+| Build Speed | Fast incremental | No building |
+| Optimization | Development mode | Production ready |
+| Use Case | Active development | Testing/Preview |
+
+## Prerequisites
+Before running `kimu serve`:
+1. Build your project: `kimu build`
+2. Ensure the dist directory exists and contains built files
+
+## Network Sharing
+To share with other devices:
+```bash
+kimu serve --host 0.0.0.0 --port 4000
+```
+Then access via `http://[your-ip]:4000`
+
+## Notes
+- Must have built the project first (`kimu build`)
+- Serves static files only (no compilation)
+- Ideal for production build testing
+- Supports all modern web features (ES modules, service workers, etc.)
+- Automatically handles asset paths and routing
+
+## Status
+⚠️ **This command is planned but not yet implemented**
+- Current status: Command structure defined, implementation pending
+- Target: Static file server with SPA and production preview support

package/docs/commands/version.md

@@ -0,0 +1,31 @@
+# kimu version
+
+Show the current version of KIMU-CLI.
+
+## Syntax
+```bash
+kimu version [--verbose]
+```
+
+## Options
+- `--verbose`: show additional version information and system details
+
+## Examples
+```bash
+# Show basic version
+kimu version
+
+# Show verbose version information
+kimu version --verbose
+```
+
+## Output
+The basic version command shows:
+- KIMU-CLI version number
+
+The verbose version command shows:
+- KIMU-CLI version number
+- Node.js version
+- NPM version
+- Operating system information
+- Additional system details

package/docs/distribution.md

@@ -0,0 +1,93 @@
+# Distributing and Installing KIMU-CLI
+
+KIMU-CLI can be used as a global or local command-line tool.
+
+## Global Installation (Recommended)
+Install globally to use `kimu` from anywhere:
+```bash
+npm install -g kimu-cli
+```
+
+## Local Installation (Project Dev Dependency)
+Install locally in your project:
+```bash
+npm install --save-dev kimu-cli
+```
+
+## Usage as a Command
+After installation, you can run:
+```bash
+kimu --help
+```
+
+## Development: Using npm link
+For local development and testing, you can link the CLI globally:
+```bash
+npm link
+```
+This makes the `kimu` command available globally on your machine for testing and development.
+
+To remove the link:
+```bash
+npm unlink -g kimu-cli
+```
+
+## Build and Compilation
+Before publishing or distributing, you need to compile the project:
+```bash
+npm run build      # Compile TypeScript to JavaScript
+npm run lint       # Check code quality (optional)
+npm run test       # Run tests (optional)
+```
+
+## Publishing and Distribution
+
+### Test Package Creation
+Before publishing, test the package creation:
+```bash
+npm pack          # Creates kimu-cli-X.X.X.tgz file
+```
+
+### Publishing to NPM
+1. Login to npm (if not already logged in):
+   ```bash
+   npm login
+   ```
+
+2. Publish the package:
+   ```bash
+   npm publish
+   ```
+
+### Version Management
+To update version and publish:
+```bash
+npm version patch    # Increment patch version (0.0.1 -> 0.0.2)
+npm version minor    # Increment minor version (0.0.1 -> 0.1.0)
+npm version major    # Increment major version (0.0.1 -> 1.0.0)
+npm publish          # Publish the new version
+```
+
+### Automated Release Scripts
+The project includes automated scripts:
+```bash
+npm run release     # Build and publish in one command
+npm run package     # Build and create package file
+```
+
+## Installation Verification
+After publishing, anyone can install and verify:
+```bash
+npm install -g kimu-cli  # Global installation
+kimu --version           # Verify installation
+kimu --help             # Test basic functionality
+```
+
+## Notes
+- Node.js >= 18 required for development and usage
+- Always run `npm run build` before publishing
+- Use `npm link` for local development and testing
+- The package includes all necessary files in `dist/`, `bin/`, and documentation
+- For CI/CD automation, see the provided GitHub Actions workflow in `.github/workflows/`
+
+---

package/docs/index.md

@@ -0,0 +1,127 @@
+# KIMU-CLI Documentation Index
+
+Welcome to the complete documentation for KIMU-CLI, the official command-line interface for the KIMU framework ecosystem.
+
+## 📖 Getting Started
+
+### Essential Reading
+- [Introduction to KIMU-CLI](intro.md) - Overview and core concepts
+- [Distribution & Installation Guide](distribution.md) - Installation, building, and publishing
+- [Command Reference](command-kimu.md) - Complete command overview and usage
+
+## ⚡ Quick References
+
+### Available Commands (Ready to Use)
+| Command | Description | Documentation |
+|---------|-------------|---------------|
+| `create` | Create new KIMU projects | [📖 docs](commands/create.md) |
+| `info` | Show project information | [📖 docs](commands/info.md) |
+| `version` | Show version information | [📖 docs](commands/version.md) |
+| `help` | Command help system | [📖 docs](commands/help.md) |
+
+### Planned Commands (Coming Soon)
+| Command | Description | Documentation |
+|---------|-------------|---------------|
+| `install` | Install modules and extensions | [📖 docs](commands/install.md) ⏳ |
+| `remove` | Remove modules and extensions | [📖 docs](commands/remove.md) ⏳ |
+| `list` | Browse available packages | [📖 docs](commands/list.md) ⏳ |
+| `build` | Build for production | [📖 docs](commands/build.md) ⏳ |
+| `dev` | Development server | [📖 docs](commands/dev.md) ⏳ |
+| `serve` | Serve built project | [📖 docs](commands/serve.md) ⏳ |
+| `doctor` | Project diagnostics | [📖 docs](commands/doctor.md) ⏳ |
+
+## 🎯 Use Case Guides
+
+### For New Users
+1. **First Time Setup**: Start with [Introduction](intro.md) to understand KIMU-CLI
+2. **Installation**: Follow the [Distribution Guide](distribution.md) for installation
+3. **Create Your First Project**: Use [`kimu create`](commands/create.md)
+4. **Learn the Commands**: Browse the [Command Reference](command-kimu.md)
+
+### For Developers
+1. **Project Setup**: Use [`kimu create`](commands/create.md) and [`kimu info`](commands/info.md)
+2. **Development Workflow**: Plan ahead with [`kimu dev`](commands/dev.md) and [`kimu build`](commands/build.md) docs
+3. **Package Management**: Understand future [`kimu install`](commands/install.md) and [`kimu list`](commands/list.md)
+4. **Troubleshooting**: Prepare for [`kimu doctor`](commands/doctor.md) diagnostics
+
+### For Maintainers
+1. **Building and Distribution**: Follow [Distribution Guide](distribution.md)
+2. **Command Implementation**: Study existing command patterns in `src/commands/`
+3. **Documentation**: Keep docs in sync with implementation
+
+## 📂 Documentation Structure
+
+```
+docs/
+├── index.md                 # This file - documentation index
+├── intro.md                 # Introduction and overview  
+├── command-kimu.md         # Complete command reference
+├── distribution.md         # Installation and distribution
+└── commands/               # Individual command documentation
+    ├── create.md           # ✅ Available
+    ├── info.md             # ✅ Available  
+    ├── version.md          # ✅ Available
+    ├── help.md             # ✅ Available
+    ├── install.md          # ⏳ Planned
+    ├── remove.md           # ⏳ Planned
+    ├── list.md             # ⏳ Planned
+    ├── build.md            # ⏳ Planned
+    ├── dev.md              # ⏳ Planned
+    ├── serve.md            # ⏳ Planned
+    └── doctor.md           # ⏳ Planned
+```
+
+## 🚀 Quick Start Examples
+
+### Create and Setup New Project
+```bash
+# Install KIMU-CLI globally
+npm install -g kimu-cli
+
+# Create new project
+kimu create my-awesome-app --git
+
+# Navigate and check project
+cd my-awesome-app
+kimu info --verbose
+```
+
+### Get Help and Information
+```bash
+# Show all commands
+kimu help
+
+# Get specific command help
+kimu create --help
+
+# Check versions
+kimu version --verbose
+```
+
+## 🔄 Status Legend
+
+- ✅ **Available**: Command is implemented and ready to use
+- ⏳ **Planned**: Command is documented but not yet implemented
+- 🚧 **In Progress**: Command is being developed
+- ❌ **Deprecated**: Command is no longer supported
+
+## 🤝 Contributing to Documentation
+
+When contributing to KIMU-CLI documentation:
+
+1. **Keep it current**: Update docs when implementation changes
+2. **Use examples**: Include practical, working examples
+3. **Follow patterns**: Match the style and structure of existing docs
+4. **Test commands**: Verify examples work before documenting
+5. **Update index**: Add new docs to this index file
+
+## 📞 Support and Resources
+
+- **GitHub Repository**: [KIMU-CLI](https://github.com/UnicoVerso/kimu-cli)
+- **KIMU Framework**: [Main Project](https://github.com/UnicoVerso/kimu)
+- **Community**: [UnicòVerso](https://unicoverso.org)
+- **Issues**: [Bug Reports & Feature Requests](https://github.com/UnicoVerso/kimu-cli/issues)
+
+---
+
+**Ready to start building with KIMU-CLI?** Begin with the [Introduction](intro.md) and then dive into creating your first project with [`kimu create`](commands/create.md)! 🚀

package/docs/intro.md

@@ -0,0 +1,86 @@
+# Introduction to KIMU-CLI
+
+KIMU-CLI is the official command-line tool for the KIMU framework ecosystem. It provides a unified interface to create, manage, build, and deploy KIMU projects with simple, intuitive commands.
+
+## What is KIMU-CLI?
+
+KIMU-CLI is designed to streamline the entire KIMU development workflow by providing:
+
+- 🚀 **Project Scaffolding**: Create new KIMU applications from templates
+- 📦 **Module Management**: Install, update, and remove modules from the registry
+- 🧩 **Extension Management**: Manage UI extensions and components
+- 🔧 **Build Pipeline**: Build, optimize, and bundle KIMU applications
+- 🌐 **Development Server**: Fast development with hot module replacement
+- 🔍 **Project Diagnostics**: Health checks and troubleshooting tools
+- 📊 **Registry Integration**: Discover and explore the KIMU ecosystem
+
+## Core Philosophy
+
+KIMU-CLI follows these principles:
+- **Developer Productivity**: Minimize setup time, maximize development efficiency
+- **Modularity**: Support for the modular KIMU architecture
+- **Simplicity**: Intuitive commands that work out of the box
+- **Extensibility**: Plugin system for custom workflows
+- **Community**: Integration with the broader KIMU ecosystem
+
+## Command Categories
+
+### Project Management
+- `kimu create` - Create new KIMU projects
+- `kimu info` - Show project information and status
+- `kimu doctor` - Run project health diagnostics
+
+### Package Management  
+- `kimu install` - Install modules and extensions
+- `kimu remove` - Remove modules and extensions
+- `kimu list` - Browse available and installed packages
+
+### Development Workflow
+- `kimu dev` - Start development server with hot reload
+- `kimu build` - Build project for production
+- `kimu serve` - Serve built project for testing
+
+### Utilities
+- `kimu version` - Show version information
+- `kimu help` - Get help for any command
+
+## Getting Started
+
+1. **Install KIMU-CLI globally**:
+   ```bash
+   npm install -g kimu-cli
+   ```
+
+2. **Create your first project**:
+   ```bash
+   kimu create my-first-app
+   cd my-first-app
+   ```
+
+3. **Start developing**:
+   ```bash
+   kimu dev
+   ```
+
+4. **Build for production**:
+   ```bash
+   kimu build
+   ```
+
+## System Requirements
+
+- **Node.js**: >= 18.0.0
+- **NPM**: >= 8.0.0
+- **Operating System**: macOS, Linux, Windows
+- **Internet Connection**: Required for registry access
+
+## Next Steps
+
+- Read the [Command Reference](command-kimu.md) for detailed command usage
+- Check out individual command documentation in the `commands/` directory
+- See the [Distribution Guide](distribution.md) for installation and deployment
+- Explore the [KIMU Framework](https://github.com/UnicoVerso/kimu) ecosystem
+
+---
+
+**Ready to build amazing web applications with KIMU? Let's get started!** 🚀