kimu-cli 0.1.0

package/docs/command-kimu.md

@@ -0,0 +1,207 @@
+# The `kimu` Command Reference
+
+The `kimu` command is the main entry point for KIMU-CLI and provides access to all framework tools and utilities.
+
+## Basic Usage
+```bash
+kimu <command> [options]
+kimu <command> --help
+```
+
+## Global Options
+These options are available for all commands:
+- `--help, -h`: Show help for any command
+- `--verbose`: Enable verbose output for detailed information
+- `--version, -v`: Show KIMU-CLI version
+
+## Command Categories
+
+### 🚀 Project Management
+| Command | Description | Status |
+|---------|-------------|---------|
+| `create <name>` | Create a new KIMU project | ✅ **Available** |
+| `info` | Show project information and status | ✅ **Available** |
+| `doctor` | Run project health diagnostics | ⏳ **Planned** |
+
+### 📦 Package Management
+| Command | Description | Status |
+|---------|-------------|---------|
+| `install <name>` | Install modules and extensions | ⏳ **Planned** |
+| `remove <name>` | Remove modules and extensions | ⏳ **Planned** |
+| `list [type]` | List available/installed packages | ⏳ **Planned** |
+
+### 🔧 Development Workflow
+| Command | Description | Status |
+|---------|-------------|---------|
+| `dev` | Start development server | ⏳ **Planned** |
+| `build` | Build project for production | ⏳ **Planned** |
+| `serve` | Serve built project | ⏳ **Planned** |
+
+### ℹ️ Utilities
+| Command | Description | Status |
+|---------|-------------|---------|
+| `version` | Show version information | ✅ **Available** |
+| `help [command]` | Show help information | ✅ **Available** |
+
+## Available Commands (Current)
+
+### Project Creation
+```bash
+# Create a new project
+kimu create my-app
+
+# Create with git initialization
+kimu create my-app --git
+
+# Force overwrite existing directory
+kimu create my-app --force
+```
+
+### Project Information
+```bash
+# Show basic project info
+kimu info
+
+# Show detailed information
+kimu info --verbose
+
+# Output in JSON format
+kimu info --json
+```
+
+### Version and Help
+```bash
+# Show CLI version
+kimu version
+
+# Show detailed version info
+kimu version --verbose
+
+# Show general help
+kimu help
+
+# Show help for specific command
+kimu help create
+```
+
+## Planned Commands (Coming Soon)
+
+### Module Management
+```bash
+# Install a module
+kimu install module router
+
+# Install an extension
+kimu install extension dashboard
+
+# Remove a module/extension
+kimu remove router
+
+# List available modules
+kimu list modules
+
+# List installed packages
+kimu list installed
+```
+
+### Development Tools
+```bash
+# Start development server
+kimu dev --port 3000
+
+# Build for production
+kimu build --minify
+
+# Serve built project
+kimu serve --port 4000
+
+# Run diagnostics
+kimu doctor --fix
+```
+
+## Command Options Patterns
+
+### Common Patterns
+- `--verbose`: Detailed output (available for most commands)
+- `--json`: JSON output format (for automation)
+- `--force`: Skip confirmations and overwrite
+- `--help`: Command-specific help
+
+### Development Options
+- `--port <number>`: Server port configuration
+- `--host <string>`: Server host configuration
+- `--open`: Automatically open browser
+- `--watch`: Watch for file changes
+
+### Build Options
+- `--mode <mode>`: Build mode (development/production)
+- `--target <target>`: JavaScript target (es2020/es2022/esnext)
+- `--minify`: Enable minification
+- `--sourcemap`: Generate source maps
+
+## Examples by Use Case
+
+### Starting a New Project
+```bash
+# Basic project setup
+kimu create my-app
+cd my-app
+kimu info  # Verify project setup
+
+# Development workflow (when implemented)
+kimu dev   # Start development server
+kimu build # Build for production
+```
+
+### Working with Modules
+```bash
+# Module management (when implemented)
+kimu list modules              # Browse available modules
+kimu install module router     # Install a module
+kimu install extension dashboard  # Install an extension
+kimu list installed           # See what's installed
+```
+
+### Debugging and Maintenance
+```bash
+# Project health (when implemented)
+kimu doctor                   # Check project health
+kimu doctor --fix            # Auto-fix common issues
+kimu info --verbose          # Detailed project info
+```
+
+## Getting Help
+
+### Command-Specific Help
+Every command supports `--help`:
+```bash
+kimu create --help
+kimu info --help
+kimu version --help
+```
+
+### General Help
+```bash
+kimu help          # Show all commands
+kimu help create   # Show help for create command
+kimu --help        # Alternative syntax
+```
+
+### Verbose Information
+Add `--verbose` to most commands for detailed output:
+```bash
+kimu info --verbose
+kimu version --verbose
+```
+
+## Notes
+
+- **Current Status**: Basic commands are implemented, advanced features coming soon
+- **Project Context**: Some commands require being run from within a KIMU project directory
+- **Internet Required**: Package management commands require internet connectivity
+- **Node.js**: Requires Node.js >= 18.0.0 and npm >= 8.0.0
+- **Documentation**: Each command has detailed documentation in `docs/commands/`
+
+For detailed documentation on each command, see the individual files in the `docs/commands/` directory.
+
+---

package/docs/commands/build.md

@@ -0,0 +1,82 @@
+# kimu build
+
+Build your KIMU project for production.
+
+## Syntax
+```bash
+kimu build [options]
+```
+
+## Options
+- `--mode <mode>`: build mode (development|production) [default: production]
+- `--target <target>`: build target (es2020|es2022|esnext) [default: es2020]
+- `--format <format>`: output format (esm|iife|umd) [default: esm]
+- `--outdir <dir>`: output directory [default: dist]
+- `--sourcemap`: generate source maps
+- `--minify`: minify output
+- `--watch`: watch for changes and rebuild
+- `--clean`: clean output directory before build
+- `--verbose`: show detailed build progress
+
+## Examples
+```bash
+# Basic production build
+kimu build
+
+# Development build with source maps
+kimu build --mode development --sourcemap
+
+# Build with specific target and format
+kimu build --target es2022 --format esm
+
+# Build with custom output directory
+kimu build --outdir ./dist/prod
+
+# Watch mode for development
+kimu build --watch --mode development
+
+# Clean build with minification
+kimu build --clean --minify
+
+# Verbose build output
+kimu build --verbose
+```
+
+## Build Process
+The build command performs:
+1. **Validation**: Checks project configuration and dependencies
+2. **Compilation**: Compiles TypeScript to JavaScript
+3. **Bundling**: Bundles modules and extensions
+4. **Optimization**: Minifies and optimizes output (in production mode)
+5. **Asset Processing**: Copies and processes static assets
+6. **Output Generation**: Creates final build artifacts
+
+## Build Outputs
+- **JavaScript bundles**: Compiled and bundled application code
+- **CSS files**: Processed and optimized stylesheets  
+- **Static assets**: Images, fonts, and other resources
+- **HTML files**: Generated HTML with proper asset references
+- **Source maps**: For debugging (when enabled)
+- **Manifest files**: Build metadata and asset mapping
+
+## Configuration
+Build settings can be configured in:
+- `kimu.config.json`: Project-specific build settings
+- `vite.config.ts` or `webpack.config.js`: Build tool configuration
+- Command-line options (override config file settings)
+
+## Notes
+- Must be run from within a KIMU project directory
+- Requires all dependencies to be installed (`npm install`)
+- Output is optimized for production by default
+- Supports modern build tools (Vite, Webpack)
+- Automatically handles KIMU-Core integration
+
+## Build Modes
+- **Production**: Optimized for deployment (minified, tree-shaken)
+- **Development**: Optimized for debugging (source maps, unminified)
+
+## Status
+⚠️ **This command is planned but not yet implemented**
+- Current status: Command structure defined, implementation pending
+- Target: Full build pipeline with optimization and bundling

package/docs/commands/create.md

@@ -0,0 +1,58 @@
+# kimu create
+
+Create a new KIMU project in a new folder.
+
+## Syntax
+```bash
+kimu create <project-name> [--no-install] [--git] [--force]
+```
+
+## Arguments
+- `<project-name>`: name of the folder to create (required)
+
+## Options
+- `--no-install`: skip npm install after project creation
+- `--git`: initialize a git repository in the project folder
+- `--force`: overwrite the folder if it already exists
+
+## Examples
+```bash
+# Create a basic project
+kimu create my-app
+
+# Create with git initialization
+kimu create my-app --git
+
+# Create without npm install
+kimu create my-app --no-install
+
+# Force overwrite existing folder
+kimu create my-app --force
+
+# Combine multiple options
+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
+
+## 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
+
+## 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

package/docs/commands/dev.md

@@ -0,0 +1,87 @@
+# kimu dev
+
+Start the development server for your KIMU project.
+
+## Syntax
+```bash
+kimu dev [options]
+```
+
+## Options
+- `--port <port>`: development server port [default: 3000]
+- `--host <host>`: development server host [default: localhost]
+- `--open`: automatically open browser
+- `--no-open`: don't open browser automatically
+- `--https`: use HTTPS (requires SSL setup)
+- `--cors`: enable CORS for cross-origin requests
+- `--verbose`: show detailed server logs
+
+## Examples
+```bash
+# Start development server with defaults
+kimu dev
+
+# Start on specific port
+kimu dev --port 8080
+
+# Start and open browser automatically
+kimu dev --open
+
+# Start with HTTPS
+kimu dev --https --port 443
+
+# Start with custom host (for network access)
+kimu dev --host 0.0.0.0 --port 3000
+
+# Verbose logging
+kimu dev --verbose
+```
+
+## Development Features
+The development server provides:
+- **Hot Module Replacement (HMR)**: Instant updates without page reload
+- **Live Reload**: Automatic page refresh on file changes
+- **Source Maps**: Full debugging support
+- **Error Overlay**: In-browser error display
+- **Module Resolution**: Automatic KIMU module and extension loading
+- **Asset Serving**: Static file serving with proper MIME types
+- **Proxy Support**: API proxying for backend integration
+
+## File Watching
+Automatically watches and reloads on changes to:
+- Source files (`.ts`, `.js`, `.html`, `.css`)
+- KIMU configuration (`kimu.config.json`)
+- Package dependencies (`package.json`)
+- Extension manifests (`extension-manifest.json`)
+
+## Development Workflow
+1. **Start server**: `kimu dev`
+2. **Edit files**: Make changes to your project
+3. **See updates**: Browser automatically reflects changes
+4. **Debug**: Use browser dev tools with source maps
+5. **Test**: Interactive development and testing
+
+## Configuration
+Development settings can be configured in:
+- `kimu.config.json`: Project development preferences
+- Command-line options (override config settings)
+- Environment variables (for CI/CD)
+
+## Network Access
+To allow access from other devices on your network:
+```bash
+kimu dev --host 0.0.0.0 --port 3000
+```
+Then access via `http://[your-ip]:3000`
+
+## Notes
+- Must be run from within a KIMU project directory
+- Requires all dependencies to be installed
+- Automatically detects available ports if default is busy
+- Supports both HTTP and HTTPS development
+- Optimized for fast rebuild times
+
+## Status
+⚠️ **This command is planned but not yet implemented**
+- Current status: Command structure defined, implementation pending
+- Target: Full development server with HMR and debugging support

package/docs/commands/doctor.md

@@ -0,0 +1,129 @@
+# kimu doctor
+
+Run diagnostics and health checks for your KIMU project.
+
+## Syntax
+```bash
+kimu doctor [options]
+```
+
+## Options
+- `--verbose`: show detailed diagnostic information
+- `--json`: output results in JSON format
+- `--fix`: automatically fix common issues where possible
+- `--skip <checks>`: skip specific diagnostic checks
+- `--only <checks>`: run only specific diagnostic checks
+
+## Examples
+```bash
+# Run all diagnostics
+kimu doctor
+
+# Verbose output with details
+kimu doctor --verbose
+
+# Output in JSON format
+kimu doctor --json
+
+# Auto-fix issues where possible
+kimu doctor --fix
+
+# Skip specific checks
+kimu doctor --skip "dependencies,permissions"
+
+# Run only specific checks
+kimu doctor --only "config,modules"
+```
+
+## Diagnostic Checks
+
+### System Requirements
+- ✅ Node.js version compatibility (>= 18.0.0)
+- ✅ NPM version compatibility (>= 8.0.0)
+- ✅ Operating system compatibility
+- ✅ Available disk space
+- ✅ Network connectivity
+
+### Project Structure
+- ✅ KIMU project detection (`kimu.config.json` exists)
+- ✅ Required directories exist (`src/`, `dist/`, etc.)
+- ✅ Package.json validity and KIMU dependencies
+- ✅ TypeScript configuration (`tsconfig.json`)
+- ✅ Build configuration files
+
+### Dependencies
+- ✅ KIMU-Core version compatibility
+- ✅ Module dependency resolution
+- ✅ Extension compatibility
+- ✅ Node modules integrity
+- ✅ Security vulnerabilities scan
+
+### Configuration
+- ✅ KIMU configuration syntax and validity
+- ✅ Build configuration consistency
+- ✅ Development server settings
+- ✅ Registry connectivity
+- ✅ Environment variables
+
+### Performance
+- ✅ Bundle size analysis
+- ✅ Build time optimization opportunities
+- ✅ Module resolution efficiency
+- ✅ Asset optimization status
+
+## Auto-Fix Capabilities
+When using `--fix`, doctor can automatically:
+- Update outdated dependencies
+- Fix common configuration issues
+- Create missing directories
+- Repair corrupted node_modules
+- Update deprecated configuration syntax
+
+## Output Format
+### Standard Output
+```
+✅ System Requirements: All checks passed
+⚠️  Dependencies: 2 updates available
+❌ Configuration: Invalid kimu.config.json syntax
+ℹ️  Performance: Bundle size could be optimized
+```
+
+### JSON Output
+```json
+{
+  "status": "warning",
+  "checks": {
+    "system": { "status": "pass", "issues": [] },
+    "dependencies": { "status": "warning", "issues": ["outdated-packages"] },
+    "configuration": { "status": "error", "issues": ["invalid-syntax"] }
+  },
+  "summary": {
+    "total": 15,
+    "passed": 12,
+    "warnings": 2,
+    "errors": 1
+  }
+}
+```
+
+## Check Categories
+Available check categories for `--skip` and `--only`:
+- `system`: System requirements and environment
+- `dependencies`: Package and module dependencies
+- `config`: Configuration files and settings
+- `modules`: KIMU modules and extensions
+- `performance`: Performance and optimization
+- `security`: Security vulnerabilities
+- `build`: Build system and tools
+
+## Notes
+- Can be run from any directory (will detect KIMU projects)
+- Provides actionable recommendations
+- Safe to run multiple times
+- Helps identify common development issues
+- Useful for CI/CD pipeline health checks
+
+## Status
+⚠️ **This command is planned but not yet implemented**
+- Current status: Command structure defined, implementation pending
+- Target: Comprehensive project health analysis with auto-fix capabilities

package/docs/commands/help.md

@@ -0,0 +1,37 @@
+# kimu help
+
+Show general help or help for a specific command.
+
+## Syntax
+```bash
+kimu help [command]
+kimu <command> --help
+```
+
+## Arguments
+- `[command]`: optional command name to get specific help for
+
+## Examples
+```bash
+# Show general help
+kimu help
+
+# Show help for specific command
+kimu help create
+
+# Alternative syntax for command help
+kimu create --help
+kimu version --help
+```
+
+## Available Commands
+When running `kimu help`, you'll see all available commands:
+- `create` - Create a new KIMU project
+- `version` - Show version information
+- `info` - Show project information
+- `help` - Show this help message
+
+## Notes
+- Running `kimu` without any arguments also shows the help
+- Each command supports the `--help` flag for specific help
+- Use `--verbose` with many commands for more detailed output

package/docs/commands/info.md

@@ -0,0 +1,46 @@
+# kimu info
+
+Show information about the current KIMU project.
+
+## Syntax
+```bash
+kimu info [--verbose] [--json]
+```
+
+## Options
+- `--verbose`: show detailed project information
+- `--json`: output in JSON format for machine processing
+
+## Examples
+```bash
+# Show basic project info
+kimu info
+
+# Show detailed project information
+kimu info --verbose
+
+# Output in JSON format
+kimu info --json
+
+# Combine options
+kimu info --verbose --json
+```
+
+## Output Information
+The basic info command shows:
+- Project name and version
+- KIMU-Core version (if detected)
+- Project type and template
+
+The verbose info command additionally shows:
+- Installed modules and extensions
+- Build configuration
+- Development settings
+- Project dependencies
+- System requirements status
+
+## Notes
+- Must be run from within a KIMU project directory
+- JSON output is useful for automation and scripting
+- If no kimu.config.json is found, shows detection results
+- Use this command to verify project setup and configuration