@majkapp/plugin-kit 3.3.0 → 3.3.2

package/bin/promptable-cli.js

@@ -16,20 +16,76 @@ const cli = createPromptable({
   title: '@majkapp/plugin-kit',
   description: 'Build MAJK plugins with functions, UI screens, and services',
   docsDir: join(__dirname, '../docs'),
-  packageCommand: 'npx @majkapp/plugin-kit',
-  views: {
-    llm: 'INDEX.md',
-    functions: 'FUNCTIONS.md',
-    screens: 'SCREENS.md',
-    hooks: 'HOOKS.md',
-    context: 'CONTEXT.md',
-    services: 'SERVICES.md',
-    lifecycle: 'LIFECYCLE.md',
-    testing: 'TESTING.md',
-    config: 'CONFIG.md',
-    api: 'API.md',
-    full: 'FULL.md'
-  }
+  packageCommand: 'npx @majkapp/plugin-kit'
 });
 
-cli.parse(process.argv);
+// Main entry point - quick start
+cli.addCommand('--llm',
+  cli.createFullDocCommand('INDEX.md'),
+  {
+    description: 'Quick start: Build your first plugin',
+    aliases: ['--start', '--quick']
+  }
+);
+
+// Function patterns
+cli.addCommand('--functions',
+  cli.createFullDocCommand('FUNCTIONS.md'),
+  { description: 'Function patterns with examples' }
+);
+
+// Screen configuration
+cli.addCommand('--screens',
+  cli.createFullDocCommand('SCREENS.md'),
+  { description: 'Configure UI screens' }
+);
+
+// Generated React hooks
+cli.addCommand('--hooks',
+  cli.createFullDocCommand('HOOKS.md'),
+  { description: 'Auto-generated React hooks' }
+);
+
+// Context API
+cli.addCommand('--context',
+  cli.createFullDocCommand('CONTEXT.md'),
+  { description: 'Context API reference' }
+);
+
+// Service grouping
+cli.addCommand('--services',
+  cli.createFullDocCommand('SERVICES.md'),
+  { description: 'Organize functions by service' }
+);
+
+// Lifecycle hooks
+cli.addCommand('--lifecycle',
+  cli.createFullDocCommand('LIFECYCLE.md'),
+  { description: 'Plugin lifecycle hooks' }
+);
+
+// Testing guide
+cli.addCommand('--testing',
+  cli.createFullDocCommand('TESTING.md'),
+  { description: 'Testing guide' }
+);
+
+// Configuration
+cli.addCommand('--config',
+  cli.createFullDocCommand('CONFIG.md'),
+  { description: 'Project configuration' }
+);
+
+// API reference
+cli.addCommand('--api',
+  cli.createFullDocCommand('API.md'),
+  { description: 'Complete API reference' }
+);
+
+// Full documentation
+cli.addCommand('--full',
+  cli.createFullDocCommand('FULL.md'),
+  { description: 'Complete documentation' }
+);
+
+cli.run();

package/dist/generator/cli.js

@@ -39,6 +39,43 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const child_process_1 = require("child_process");
 const generator_1 = require("./generator");
+// Check args BEFORE commander parses to intercept for documentation
+const args = process.argv.slice(2);
+// If -h or --help, let commander handle it normally (show generator help)
+const isHelpRequest = args.includes('-h') || args.includes('--help');
+if (!isHelpRequest) {
+    // Check if this is a documentation request
+    const llmArg = args.find(arg => arg.startsWith('--llm'));
+    const isDefaultDocs = args.length === 0; // No args = show docs by default
+    if (isDefaultDocs || llmArg) {
+        // Delegate to promptable CLI for documentation
+        const promptablePath = path.join(__dirname, '../../bin/promptable-cli.js');
+        let promptableArgs;
+        if (isDefaultDocs || llmArg === '--llm') {
+            // Default to quick start
+            promptableArgs = ['--llm'];
+        }
+        else if (llmArg && llmArg.startsWith('--llm:')) {
+            // Extract view name: --llm:functions -> --functions
+            const view = llmArg.split(':')[1];
+            promptableArgs = [`--${view}`];
+        }
+        else {
+            promptableArgs = ['--llm'];
+        }
+        try {
+            (0, child_process_1.execSync)(`node "${promptablePath}" ${promptableArgs.join(' ')}`, {
+                stdio: 'inherit',
+                cwd: process.cwd()
+            });
+            process.exit(0);
+        }
+        catch (error) {
+            process.exit(1);
+        }
+    }
+}
+// Normal commander behavior (generator commands)
 commander_1.program
     .name('plugin-kit')
     .version('1.0.20')
@@ -126,6 +163,19 @@ commander_1.program
         await generate();
     }
 });
+// Add documentation options to help
+commander_1.program
+    .option('--llm', 'Show plugin development documentation (quick start)')
+    .option('--llm:functions', 'Show function patterns documentation')
+    .option('--llm:screens', 'Show screen configuration documentation')
+    .option('--llm:hooks', 'Show generated hooks documentation')
+    .option('--llm:context', 'Show context API documentation')
+    .option('--llm:services', 'Show service grouping documentation')
+    .option('--llm:lifecycle', 'Show lifecycle hooks documentation')
+    .option('--llm:testing', 'Show testing guide')
+    .option('--llm:config', 'Show project configuration guide')
+    .option('--llm:api', 'Show API reference')
+    .option('--llm:full', 'Show complete reference');
 commander_1.program.parse();
 async function extractMetadata(entryPath) {
     // Create a temp file for the output

package/docs/INDEX.md

@@ -104,11 +104,130 @@ my-plugin/
 │   └── plugin/
 │       ├── functions/unit/   # Function tests
 │       └── ui/unit/          # UI tests with bot
-├── vite.config.js            # EXACT format required (see CONFIG.md)
-├── package.json
+├── vite.config.js            # EXACT format required (see below)
+├── package.json              # REQUIRED: majk metadata section
 └── tsconfig.json
 ```
 
+## package.json (REQUIRED)
+
+**CRITICAL:** Your package.json MUST include the `majk` metadata section and use an npm organization scope:
+
+```json
+{
+  "name": "@yourorg/my-plugin",
+  "version": "1.0.0",
+  "description": "My awesome MAJK plugin",
+  "main": "index.js",
+  "keywords": ["majk", "plugin"],
+  "majk": {
+    "type": "in-process",
+    "entry": "index.js"
+  },
+  "scripts": {
+    "generate": "npx plugin-kit generate -e ./index.js -o ./ui/src/generated",
+    "dev": "vite",
+    "build": "tsc && npm run generate && vite build",
+    "preview": "vite preview",
+    "test": "npm run test:plugin",
+    "test:plugin": "npm run test:plugin:functions && npm run test:plugin:ui",
+    "test:plugin:functions": "npx majk-test --type functions",
+    "test:plugin:ui": "node tests/plugin/ui/unit/basic-navigation.test.js",
+    "clean": "rm -rf dist index.js index.d.ts ui/src/generated"
+  },
+  "dependencies": {
+    "@majkapp/plugin-kit": "^3.3.0",
+    "@majkapp/plugin-theme": "^1.0.0",
+    "@majkapp/plugin-ui": "^1.4.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@majkapp/plugin-test": "^1.0.2",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.3.3",
+    "vite": "^6.0.3"
+  }
+}
+```
+
+### Package Naming (REQUIRED)
+
+**Your plugin name MUST use an npm organization scope** (format: `@org/plugin-name`).
+
+Replace `@yourorg` with your organization:
+- If you have an npm organization: `@mycompany/my-plugin`
+- If you don't have one: Use `@majkical/my-plugin`
+
+Example: `@majkical/weather-widget`
+
+### majk Metadata Section
+
+The `majk` object tells MAJK how to load your plugin:
+
+**`type`**: `"in-process"` or `"remote"`
+- `"in-process"` - Plugin runs in MAJK's Node.js process (most common)
+- `"remote"` - Plugin runs in separate process (for isolation)
+
+**`entry`**: Path to compiled plugin file (relative to package root)
+- Usually `"index.js"` (compiled from `src/index.ts`)
+- MAJK loads this file to get your plugin definition
+
+### Important Scripts
+
+**`generate`** - Generate TypeScript client from plugin
+```bash
+npm run generate  # Regenerate after adding/changing functions
+```
+
+**`build`** - Complete build pipeline
+```bash
+npm run build     # 1. Compile TS → index.js
+                  # 2. Generate client
+                  # 3. Build React UI → dist/
+```
+
+**`test:plugin:functions`** - Test plugin functions
+```bash
+npm run test:plugin:functions  # Run all function tests
+```
+
+**`test:plugin:ui`** - Test plugin UI with bot
+```bash
+npm run test:plugin:ui        # Run UI tests with browser automation
+```
+
+## vite.config.js (REQUIRED FORMAT)
+
+**CRITICAL:** Use this EXACT format for your vite.config.js:
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  root: 'ui',                    // React source is in ui/ directory
+  base: '',                      // IMPORTANT: Empty string, NOT './'
+  server: {
+    port: 3000,
+    strictPort: false,
+  },
+  build: {
+    outDir: '../dist',           // Build output to dist/ (parent of ui/)
+    assetsDir: 'assets',
+    emptyOutDir: true,
+  },
+});
+```
+
+**Why `base: ''`?**
+- MAJK loads plugins in iframes with dynamic paths
+- Empty base ensures assets load correctly
+- `base: './'` will cause 404 errors for assets
+
 ## Best Practice: Decoupled Business Logic
 
 **ALWAYS separate business logic from plugin code.** This makes testing easier and allows logic reuse.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@majkapp/plugin-kit",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "description": "Pure plugin definition library for MAJK - outputs plugin definitions, not HTTP servers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "plugin-kit": "./bin/promptable-cli.js",
+    "plugin-kit": "./dist/generator/cli.js",
     "majk-plugin-kit": "./dist/generator/cli.js"
   },
   "repository": {