kimu-cli 0.1.1 → 1.0.0

package/docs/configuration-files.md

@@ -0,0 +1,192 @@
+# Configuration Files
+
+This directory contains various configuration files to ensure consistency across different development environments and tools.
+
+## Files Overview
+
+### `.editorconfig`
+**Purpose**: Defines consistent coding styles across different editors and IDEs.
+
+**Key settings**:
+- Line endings: LF (Unix-style)
+- Charset: UTF-8
+- Indentation: 2 spaces
+- Trim trailing whitespace
+- Insert final newline
+
+**Supported editors**: VSCode, IntelliJ IDEA, Sublime Text, Vim, Emacs, and many others with EditorConfig plugins.
+
+### `.gitattributes`
+**Purpose**: Git attributes for consistent line endings and file handling across different operating systems.
+
+**Key features**:
+- Enforces LF line endings for all text files
+- Special handling for Windows-specific files (.bat, .cmd with CRLF)
+- Binary file detection
+- Linguist settings for GitHub language statistics
+- Custom merge strategies for lock files
+
+### `.prettierrc`
+**Purpose**: Prettier code formatter configuration.
+
+**Key settings**:
+- Single quotes
+- Semicolons enabled
+- Line width: 80 characters
+- Tab width: 2 spaces
+- End of line: LF
+- Arrow function parentheses: avoid
+- Trailing commas: ES5 compatible
+
+### `.prettierignore`
+**Purpose**: Files and directories that Prettier should ignore.
+
+**Ignored**:
+- Build outputs (dist/, build/)
+- Dependencies (node_modules/)
+- Lock files
+- Temporary files
+- Generated files
+
+### `.nvmrc`
+**Purpose**: Specifies the Node.js version required for this project.
+
+**Value**: `18` (Node.js 18.x)
+
+**Usage**:
+```bash
+# If you have nvm installed
+nvm use
+
+# Or install the specified version
+nvm install
+```
+
+## Why These Files Matter
+
+### Consistency Across Environments
+These files ensure that:
+- **Line endings are consistent** (LF) regardless of OS (Windows, macOS, Linux)
+- **Character encoding is UTF-8** everywhere
+- **Code style is uniform** across team members
+- **Git handles files correctly** across platforms
+
+### Common Problems Prevented
+
+1. **Line Ending Issues**
+   - Without `.editorconfig` + `.gitattributes`: Windows uses CRLF, Unix uses LF
+   - This causes: Git showing entire files as changed, merge conflicts, linter errors
+   - **Solution**: Both files enforce LF for all text files
+
+2. **Character Encoding Issues**
+   - Without `.editorconfig`: Different default encodings (ISO-8859-1, Windows-1252, UTF-8)
+   - This causes: Special characters broken, emoji not working, accented letters corrupted
+   - **Solution**: UTF-8 everywhere
+
+3. **Formatting Inconsistencies**
+   - Without `.prettierrc`: Different tab/space settings, line lengths, quote styles
+   - This causes: Merge conflicts, noisy diffs, readability issues
+   - **Solution**: Automated consistent formatting
+
+4. **Node Version Mismatches**
+   - Without `.nvmrc`: Team members use different Node versions
+   - This causes: "Works on my machine", package incompatibilities
+   - **Solution**: Documented and enforceable Node version
+
+## Setup Recommendations
+
+### For VSCode Users
+Install these extensions:
+```json
+{
+  "recommendations": [
+    "editorconfig.editorconfig",
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint"
+  ]
+}
+```
+
+### For Git Users
+Ensure line endings are normalized:
+```bash
+# Check current setting
+git config --global core.autocrlf
+
+# Recommended settings:
+# On Windows: git config --global core.autocrlf true
+# On macOS/Linux: git config --global core.autocrlf input
+```
+
+### For Team Consistency
+**Before first commit**:
+```bash
+# Install dependencies
+npm install
+
+# Format all files
+npm run format
+
+# Verify linting
+npm run lint
+
+# Build to verify everything works
+npm run build
+```
+
+## Integration with CI/CD
+
+These configurations work with our GitHub Actions workflows:
+- Linting checks enforce `.prettierrc` rules
+- Build process validates `.editorconfig` compliance
+- Tests run on Node version specified in `.nvmrc`
+
+## Troubleshooting
+
+### Issue: "Delete ␍" errors in ESLint
+**Cause**: CRLF line endings instead of LF
+
+**Solution**:
+```bash
+# Fix with Prettier
+npm run format
+
+# Or manually convert line endings
+git add --renormalize .
+git commit -m "Normalize line endings"
+```
+
+### Issue: Files showing as modified after checkout
+**Cause**: Git autocrlf settings conflict with repository settings
+
+**Solution**:
+```bash
+# Re-normalize repository
+git rm --cached -r .
+git reset --hard
+```
+
+### Issue: Different formatting from team members
+**Cause**: Editor not respecting `.editorconfig` or `.prettierrc`
+
+**Solution**:
+- Install EditorConfig plugin for your editor
+- Install Prettier plugin and enable "Format on Save"
+- Run `npm run format` before committing
+
+## References
+
+- [EditorConfig Documentation](https://editorconfig.org/)
+- [Git Attributes Documentation](https://git-scm.com/docs/gitattributes)
+- [Prettier Documentation](https://prettier.io/)
+- [nvm Documentation](https://github.com/nvm-sh/nvm)
+
+## Maintenance
+
+These files should be:
+- ✅ Committed to version control
+- ✅ Kept in sync across all project repositories
+- ✅ Updated when project conventions change
+- ✅ Referenced in CONTRIBUTING.md
+
+Last updated: December 2025

package/docs/getting-started.md

@@ -0,0 +1,386 @@
+# Getting Started with KIMU-CLI
+
+This guide will help you install KIMU-CLI and create your first KIMU application in just a few minutes.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+- **Node.js** >= 18.0.0 ([Download here](https://nodejs.org/))
+- **NPM** >= 8.0.0 (comes with Node.js)
+- A terminal/command prompt
+
+Check your versions:
+```bash
+node --version
+npm --version
+```
+
+## Installation
+
+### Option 1: Global Installation (Recommended)
+
+Install KIMU-CLI globally to use the `kimu` command anywhere:
+
+```bash
+npm install -g kimu-cli
+```
+
+Verify the installation:
+```bash
+kimu --version
+# Output: 0.1.1 (or current version)
+
+kimu --help
+# Shows all available commands
+```
+
+### Option 2: Using npx (No Installation Required)
+
+You can use KIMU-CLI without installing it globally by using `npx`:
+
+```bash
+npx kimu-cli create my-app
+```
+
+This downloads and runs the latest version of KIMU-CLI temporarily.
+
+## Creating Your First Project
+
+### Step 1: Create a New Project
+
+```bash
+kimu create my-first-app
+```
+
+You'll be prompted to:
+- Confirm the project name
+- Choose whether to initialize git
+- Optionally select a template (coming soon)
+
+The CLI will:
+1. Create a new folder `my-first-app/`
+2. Initialize npm with `package.json`
+3. Install `kimu-core` and copy all framework files
+4. Install all dependencies
+5. Generate configuration files
+
+### Step 2: Navigate to Your Project
+
+```bash
+cd my-first-app
+```
+
+### Step 3: Explore Your Project Structure
+
+```
+my-first-app/
+├── src/                    # Source code
+│   ├── core/              # KIMU core framework files
+│   ├── extensions/        # Your custom extensions
+│   ├── modules/           # Modules (router, i18n, etc.)
+│   └── main.ts            # Application entry point
+├── public/                # Static assets
+├── scripts/               # Build and utility scripts
+├── dist/                  # Build output
+├── kimu.config.json       # KIMU configuration
+├── kimu-build-config.ts   # Build configuration
+├── package.json           # NPM dependencies
+├── tsconfig.json          # TypeScript configuration
+├── vite.config.ts         # Vite bundler configuration
+└── README.md              # Project documentation
+```
+
+### Step 4: Start Development Server
+
+```bash
+npm run dev
+```
+
+This will:
+- Start the Vite development server
+- Enable hot module replacement (HMR)
+- Open your app at `http://localhost:5173/`
+
+You should see your KIMU application running! 🎉
+
+### Step 5: Make Your First Change
+
+Open `src/extensions/kimu-home/component.ts` and modify the `getData()` method:
+
+```typescript
+getData() {
+  return {
+    title: 'My First KIMU App!', // Change this
+    version: this.version,
+    kimuLogo: this.getKimuLogo(),
+  };
+}
+```
+
+Save the file and watch the browser update automatically!
+
+## Understanding Key Files
+
+### `src/main.ts`
+The main entry point that initializes the KIMU application:
+```typescript
+import { KimuApp } from './core/kimu-app';
+import { KimuExtensionManager } from './core/kimu-extension-manager';
+
+async function main() {
+  const app = await KimuApp.getInstance();
+  const extensionManager = KimuExtensionManager.getInstance();
+  
+  await extensionManager.init();
+  await extensionManager.load('kimu-home');
+}
+```
+
+### `kimu.config.json`
+Project configuration file:
+```json
+{
+  "name": "my-first-app",
+  "version": "1.0.0",
+  "kimuCore": "^0.4.0",
+  "modules": {
+    "installed": [],
+    "registry": "https://github.com/unicoverso/kimu-modules"
+  },
+  "extensions": {
+    "installed": ["kimu-home"],
+    "main": "kimu-home"
+  }
+}
+```
+
+### `package.json`
+NPM package configuration with scripts:
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint src/**/*.ts",
+    "generate-config:dev": "node scripts/generate-build-config.js dev",
+    "generate-config:prod": "node scripts/generate-build-config.js prod"
+  }
+}
+```
+
+## Development Commands
+
+### Start Development Server
+```bash
+npm run dev
+```
+- Hot reload enabled
+- Access at `http://localhost:5173/`
+
+### Build for Production
+```bash
+npm run build
+```
+- Optimized production bundle
+- Output in `dist/` folder
+
+### Preview Production Build
+```bash
+npm run preview
+```
+- Test production build locally
+
+### Lint Your Code
+```bash
+npm run lint
+```
+- Check code quality with ESLint
+
+## KIMU-CLI Commands
+
+### Get Project Information
+```bash
+kimu info
+```
+Shows basic project details.
+
+```bash
+kimu info --verbose
+```
+Shows detailed information including dependencies and configuration.
+
+### Check CLI Version
+```bash
+kimu --version
+```
+Shows KIMU-CLI version.
+
+```bash
+kimu version --verbose
+```
+Shows detailed version information including Node.js and platform.
+
+### Get Help
+```bash
+kimu --help
+```
+Shows all available commands.
+
+```bash
+kimu create --help
+```
+Shows help for a specific command.
+
+## Creating Extensions
+
+KIMU applications are built using extensions. Here's how to create your first extension:
+
+### Using the CLI (Recommended)
+
+The easiest way is to use the `kimu new` command:
+
+```bash
+# Create a new extension
+kimu new extension my-first-extension
+```
+
+This automatically creates:
+- `component.ts` - Logic and lifecycle methods
+- `style.css` - Component styles
+- `view.html` - HTML template
+- Registers in `extension-manifest.json`
+
+### Manual Creation
+
+Alternatively, create the structure manually:
+
+### 1. Create Extension Folder
+```bash
+mkdir -p src/extensions/my-first-extension
+```
+
+### 2. Create Required Files
+Each extension needs three files:
+- `component.ts` - Logic and data
+- `style.css` - Styles
+- `view.html` - Template
+
+Example `component.ts`:
+```typescript
+import { KimuComponent } from '../../core/kimu-component';
+import { KimuComponentElement } from '../../core/kimu-component-element';
+
+@KimuComponent({
+  tag: 'my-first-extension',
+  name: 'My First Extension',
+  version: '1.0.0',
+  description: 'My first KIMU extension',
+  author: 'Your Name',
+  icon: '🎨',
+  internal: false,
+  path: 'my-first-extension',
+  dependencies: []
+})
+export class MyFirstExtension extends KimuComponentElement {
+  async onInit() {
+    console.log('Extension initialized!');
+  }
+
+  getData() {
+    return {
+      message: 'Hello from my first extension!'
+    };
+  }
+}
+```
+
+Example `view.html`:
+```html
+<div class="extension-container">
+  <h1>${message}</h1>
+</div>
+```
+
+Example `style.css`:
+```css
+.extension-container {
+  padding: 20px;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  border-radius: 10px;
+}
+```
+
+### 3. Register Your Extension
+
+Add to `extension-manifest.json`:
+```json
+{
+  "tag": "my-first-extension",
+  "name": "My First Extension",
+  "version": "1.0.0",
+  "description": "My first KIMU extension",
+  "author": "Your Name",
+  "icon": "🎨",
+  "internal": false,
+  "path": "my-first-extension",
+  "dependencies": []
+}
+```
+
+### 4. Load Your Extension
+
+In `src/main.ts`:
+```typescript
+await extensionManager.load('my-first-extension');
+```
+
+## Next Steps
+
+- **Read the Documentation**: Explore the [full command reference](command-kimu.md)
+- **Learn About Extensions**: Check the [KIMU-Core documentation](https://github.com/UnicoVerso/kimu-core)
+- **Join the Community**: Visit the [KIMU GitHub](https://github.com/UnicoVerso)
+- **Explore Examples**: Check out [example projects](https://github.com/UnicoVerso/kimu-extensions-example)
+
+## Troubleshooting
+
+### "Command not found: kimu"
+If you get this error after global installation:
+```bash
+# Check if npm global bin is in PATH
+npm config get prefix
+
+# Add to PATH (example for bash/zsh)
+echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### Port 5173 Already in Use
+If the dev server fails to start:
+```bash
+# Kill the process using port 5173
+lsof -ti:5173 | xargs kill -9
+
+# Or use a different port
+vite --port 3000
+```
+
+### Build Errors
+If you encounter build errors:
+```bash
+# Clean and rebuild
+rm -rf node_modules dist
+npm install
+npm run build
+```
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/UnicoVerso/kimu-cli/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/UnicoVerso/kimu-cli/discussions)
+- **Documentation**: [Full Docs](https://github.com/UnicoVerso/kimu-cli/docs)
+
+---
+
+**Happy coding with KIMU!** 🚀