@shiva-fw/cli 1.0.0

package/.editorconfig

@@ -0,0 +1,38 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{json,xml}]
+indent_size = 2
+
+[*.{js,ts,jsx,tsx}]
+indent_size = 2
+
+[*.{css,scss}]
+indent_size = 2
+
+[*.lua]
+indent_size = 4
+
+[*.lua.tpl]
+indent_size = 4
+
+[*.{sh,bash}]
+indent_style = tab
+indent_size = 4
+
+[{Makefile,**.mk}]
+indent_style = tab
+indent_size = 4

package/.gitattributes

@@ -0,0 +1,18 @@
+* text=auto eol=lf
+
+*.css diff=css
+*.html diff=html
+*.md diff=markdown
+*.lua diff=lua
+*.tsx diff=typescriptreact
+*.ts diff=typescript
+*.yml diff=yaml
+*.sh diff=bash
+*.js diff=javascript
+*.json diff=json
+
+# Mark generated files
+package-lock.json linguist-generated=true
+
+/.github export-ignore
+CHANGELOG.md export-ignore

package/.nvmrc

@@ -0,0 +1 @@
+24

package/README.md

@@ -0,0 +1,179 @@
+# shiva-cli
+
+> Developer CLI for the [Shiva](https://github.com/adrianmejias/shiva-core) FiveM framework — scaffolding, migrations, package management, AI integration, and an MCP server.
+
+Think of it as Artisan for FiveM. Generate modules, run database migrations, manage packages with lockfile support, produce AI context files, and expose live framework data to AI tools via the Model Context Protocol.
+
+## Installation
+
+```bash
+npm install -g @shiva-fw/cli
+# or run without installing
+npx @shiva-fw/cli init
+```
+
+After installing, the `shiva` command is available globally.
+
+## Quick Start
+
+```bash
+# Initialise a new server project
+shiva init
+
+# Scaffold a module
+shiva make:module fishing
+shiva make:service FishingService --module shiva-fishing
+shiva make:model Fish --module shiva-fishing
+shiva make:migration create_fish_table --module shiva-fishing
+
+# Run migrations
+shiva migrate
+
+# Start the MCP server (for Claude Code, Cursor, etc.)
+shiva mcp start
+```
+
+## Commands
+
+### Scaffolding
+```bash
+shiva init                                        # Interactive setup
+shiva init --recipe full-rp                       # Use a preset recipe (minimal | standard | full-rp)
+
+shiva make:module <name>                          # Scaffold a new module
+shiva make:service <name> --module <module>       # Add a service
+shiva make:model <name> --module <module>         # Add a model
+shiva make:migration <name> --module <module>     # Add a migration
+shiva make:seed <name> --module <module>          # Add a seeder
+shiva make:test <name> --module <module>          # Add a test spec
+shiva make:contract <name>                        # Add a shared contract
+```
+
+### Database
+```bash
+shiva migrate                       # Run all pending migrations
+shiva migrate:rollback              # Roll back the last batch
+shiva migrate:rollback --steps=3    # Roll back 3 batches
+shiva migrate:status                # Show migration status table
+shiva seed                          # Run all seeders
+shiva seed --module shiva-economy   # Seed a specific module
+```
+
+### Modules
+```bash
+shiva module:list     # List all installed modules with status
+shiva module:status   # Detailed view (version, deps, health)
+```
+
+### Packages
+```bash
+shiva install shiva-fishing          # Install from registry
+shiva install shiva-fishing@1.2.0   # Install a specific version
+shiva update                         # Update all modules
+shiva update shiva-economy           # Update one module
+shiva outdated                       # Show available updates
+shiva remove shiva-fishing           # Remove a module
+```
+
+### Testing
+```bash
+shiva test                           # Run all module test suites
+shiva test --module shiva-economy    # Test a specific module
+shiva test --filter "transfer"       # Filter by test name
+```
+
+### Config & Locale
+```bash
+shiva config:validate   # Validate all module configs
+shiva locale:missing    # Find missing translation keys
+```
+
+### AI Integration
+```bash
+shiva ai:context                    # Generate AGENTS.md from installed modules
+shiva ai:context --module economy   # For a specific module
+shiva ai:link                       # Create CLAUDE.md and GEMINI.md symlinks
+shiva ai:mcp                        # Generate .mcp.json for AI tool connections
+shiva mcp start                     # Start the MCP server (stdio)
+```
+
+### Documentation
+```bash
+shiva docs:api               # Generate API reference from LuaLS annotations
+shiva docs:build             # Build docs site (delegates to shiva-docs)
+shiva docs:serve             # Local dev server (delegates to shiva-docs)
+shiva docs:deploy            # Deploy docs (delegates to shiva-docs)
+```
+
+## Package Management
+
+Projects use `shiva.json` (like `package.json`) and `shiva.lock`:
+
+```json
+{
+  "name": "my-rp-server",
+  "framework": "shiva-core@1.0.0",
+  "modules": {
+    "shiva-player":   "^1.0.0",
+    "shiva-economy":  "^1.0.0",
+    "shiva-police":   "^1.0.0",
+    "my-fishing":     "file:./custom-modules/fishing"
+  },
+  "database": {
+    "host": "127.0.0.1",
+    "user": "root",
+    "password": "",
+    "database": "shiva"
+  }
+}
+```
+
+Version constraints follow semver: `^1.0.0` (compatible), `~1.0.0` (patch only), `1.0.0` (exact), `>=1.0.0 <2.0.0` (range).
+
+## MCP Server
+
+The MCP server exposes live framework context to AI assistants (Claude Code, Cursor, Windsurf, etc.):
+
+```bash
+shiva mcp start
+# Listening on stdio — add to your editor's MCP config
+```
+
+| Tool | Description |
+|------|-------------|
+| `shiva:getContractMethods` | Methods, args, and return types for a contract |
+| `shiva:getModuleConfig` | Config schema with defaults and current values |
+| `shiva:getRegisteredEvents` | All events across modules with payload shapes |
+| `shiva:getInstalledModules` | Installed modules, versions, dependency tree |
+| `shiva:getServiceMethods` | Service methods including extensions |
+| `shiva:getDatabaseSchema` | All tables, columns, and types |
+| `shiva:getMigrationStatus` | Which migrations have run |
+| `shiva:getAvailableCommands` | Registered commands with args and permissions |
+| `shiva:getItemDefinitions` | All registered inventory items |
+| `shiva:getJobDefinitions` | All jobs, grades, and salaries |
+| `shiva:searchDocs` | Full-text search across framework docs |
+
+## Requirements
+
+- Node.js 18+
+- Lua 5.4 (for `shiva test`)
+- MySQL/MariaDB (for migration commands)
+
+## Related Repositories
+
+| Repo | Purpose |
+|------|---------|
+| [shiva-core](https://github.com/adrianmejias/shiva-core) | FiveM framework engine |
+| [shiva-fw](https://github.com/adrianmejias/shiva-fw) | Shared Lua foundation |
+| [shiva-modules](https://github.com/adrianmejias/shiva-modules) | 71 default RP modules |
+| [shiva-test](https://github.com/adrianmejias/shiva-test) | Lua testing framework |
+| [shiva-api](https://github.com/adrianmejias/shiva-api) | External REST API server |
+| [shiva-docs](https://github.com/adrianmejias/shiva-docs) | Documentation site |
+| [shiva-panel](https://github.com/adrianmejias/shiva-panel) | Admin panel |
+| [shiva](https://github.com/adrianmejias/shiva) | FiveM Docker boilerplate |
+| [shiva-boot](https://github.com/adrianmejias/shiva-boot) | Server boot scripts |
+| [shiva-db](https://github.com/adrianmejias/shiva-db) | Database utilities |
+
+## License
+
+MIT

package/bin/shiva.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/index');

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@shiva-fw/cli",
+  "version": "1.0.0",
+  "description": "Developer CLI for the Shiva FiveM framework",
+  "main": "src/index.js",
+  "bin": {
+    "shiva": "bin/shiva.js"
+  },
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint src/**/*.js bin/**/*.js"
+  },
+  "keywords": [
+    "fivem",
+    "shiva",
+    "cli",
+    "framework"
+  ],
+  "author": "Adrian Mejias",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "glob": "^8.1.0",
+    "inquirer": "^8.2.6",
+    "mysql2": "^3.9.7",
+    "semver": "^7.6.2"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1",
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "testMatch": [
+      "**/tests/**/*.test.js"
+    ],
+    "testEnvironment": "node"
+  }
+}

package/recipes/full-rp.json

@@ -0,0 +1,77 @@
+{
+  "name": "full-rp",
+  "description": "Full RP experience — 71 modules",
+  "modules": {
+    "shiva-player": "^1.0.0",
+    "shiva-identity": "^1.0.0",
+    "shiva-jobs": "^1.0.0",
+    "shiva-economy": "^1.0.0",
+    "shiva-inventory": "^1.0.0",
+    "shiva-vehicles": "^1.0.0",
+    "shiva-housing": "^1.0.0",
+    "shiva-phone": "^1.0.0",
+    "shiva-hud": "^1.0.0",
+    "shiva-map": "^1.0.0",
+    "shiva-chat": "^1.0.0",
+    "shiva-permissions": "^1.0.0",
+    "shiva-admin": "^1.0.0",
+    "shiva-ban": "^1.0.0",
+    "shiva-logs": "^1.0.0",
+    "shiva-spawn": "^1.0.0",
+    "shiva-death": "^1.0.0",
+    "shiva-hunger": "^1.0.0",
+    "shiva-shops": "^1.0.0",
+    "shiva-garage": "^1.0.0",
+    "shiva-fuel": "^1.0.0",
+    "shiva-atm": "^1.0.0",
+    "shiva-crafting": "^1.0.0",
+    "shiva-notifications": "^1.0.0",
+    "shiva-police": "^1.0.0",
+    "shiva-ems": "^1.0.0",
+    "shiva-mechanic": "^1.0.0",
+    "shiva-trucker": "^1.0.0",
+    "shiva-taxi": "^1.0.0",
+    "shiva-restaurant": "^1.0.0",
+    "shiva-drugs": "^1.0.0",
+    "shiva-robbery": "^1.0.0",
+    "shiva-casino": "^1.0.0",
+    "shiva-racing": "^1.0.0",
+    "shiva-fishing": "^1.0.0",
+    "shiva-hunting": "^1.0.0",
+    "shiva-farming": "^1.0.0",
+    "shiva-realtor": "^1.0.0",
+    "shiva-tattoo": "^1.0.0",
+    "shiva-barbershop": "^1.0.0",
+    "shiva-cardealer": "^1.0.0",
+    "shiva-weapons": "^1.0.0",
+    "shiva-ammo": "^1.0.0",
+    "shiva-shooting-range": "^1.0.0",
+    "shiva-prison": "^1.0.0",
+    "shiva-court": "^1.0.0",
+    "shiva-lawyer": "^1.0.0",
+    "shiva-judge": "^1.0.0",
+    "shiva-bank": "^1.0.0",
+    "shiva-loan": "^1.0.0",
+    "shiva-insurance": "^1.0.0",
+    "shiva-business": "^1.0.0",
+    "shiva-billboard": "^1.0.0",
+    "shiva-news": "^1.0.0",
+    "shiva-radio": "^1.0.0",
+    "shiva-mayor": "^1.0.0",
+    "shiva-election": "^1.0.0",
+    "shiva-gang": "^1.0.0",
+    "shiva-turf": "^1.0.0",
+    "shiva-black-market": "^1.0.0",
+    "shiva-carjack": "^1.0.0",
+    "shiva-heist": "^1.0.0",
+    "shiva-kidnap": "^1.0.0",
+    "shiva-hitman": "^1.0.0",
+    "shiva-taxi-dispatch": "^1.0.0",
+    "shiva-ambulance-dispatch": "^1.0.0",
+    "shiva-police-dispatch": "^1.0.0",
+    "shiva-towing": "^1.0.0",
+    "shiva-impound": "^1.0.0",
+    "shiva-evidence": "^1.0.0",
+    "shiva-forensics": "^1.0.0"
+  }
+}

package/recipes/minimal.json

@@ -0,0 +1,30 @@
+{
+  "name": "minimal",
+  "description": "Essential modules for a minimal FiveM server — 24 modules",
+  "modules": {
+    "shiva-player": "^1.0.0",
+    "shiva-identity": "^1.0.0",
+    "shiva-jobs": "^1.0.0",
+    "shiva-economy": "^1.0.0",
+    "shiva-inventory": "^1.0.0",
+    "shiva-vehicles": "^1.0.0",
+    "shiva-housing": "^1.0.0",
+    "shiva-phone": "^1.0.0",
+    "shiva-hud": "^1.0.0",
+    "shiva-map": "^1.0.0",
+    "shiva-chat": "^1.0.0",
+    "shiva-permissions": "^1.0.0",
+    "shiva-admin": "^1.0.0",
+    "shiva-ban": "^1.0.0",
+    "shiva-logs": "^1.0.0",
+    "shiva-spawn": "^1.0.0",
+    "shiva-death": "^1.0.0",
+    "shiva-hunger": "^1.0.0",
+    "shiva-shops": "^1.0.0",
+    "shiva-garage": "^1.0.0",
+    "shiva-fuel": "^1.0.0",
+    "shiva-atm": "^1.0.0",
+    "shiva-crafting": "^1.0.0",
+    "shiva-notifications": "^1.0.0"
+  }
+}

package/recipes/standard.json

@@ -0,0 +1,46 @@
+{
+  "name": "standard",
+  "description": "Standard RP server — 40 modules (recommended starting point)",
+  "modules": {
+    "shiva-player": "^1.0.0",
+    "shiva-identity": "^1.0.0",
+    "shiva-jobs": "^1.0.0",
+    "shiva-economy": "^1.0.0",
+    "shiva-inventory": "^1.0.0",
+    "shiva-vehicles": "^1.0.0",
+    "shiva-housing": "^1.0.0",
+    "shiva-phone": "^1.0.0",
+    "shiva-hud": "^1.0.0",
+    "shiva-map": "^1.0.0",
+    "shiva-chat": "^1.0.0",
+    "shiva-permissions": "^1.0.0",
+    "shiva-admin": "^1.0.0",
+    "shiva-ban": "^1.0.0",
+    "shiva-logs": "^1.0.0",
+    "shiva-spawn": "^1.0.0",
+    "shiva-death": "^1.0.0",
+    "shiva-hunger": "^1.0.0",
+    "shiva-shops": "^1.0.0",
+    "shiva-garage": "^1.0.0",
+    "shiva-fuel": "^1.0.0",
+    "shiva-atm": "^1.0.0",
+    "shiva-crafting": "^1.0.0",
+    "shiva-notifications": "^1.0.0",
+    "shiva-police": "^1.0.0",
+    "shiva-ems": "^1.0.0",
+    "shiva-mechanic": "^1.0.0",
+    "shiva-trucker": "^1.0.0",
+    "shiva-taxi": "^1.0.0",
+    "shiva-restaurant": "^1.0.0",
+    "shiva-drugs": "^1.0.0",
+    "shiva-robbery": "^1.0.0",
+    "shiva-casino": "^1.0.0",
+    "shiva-racing": "^1.0.0",
+    "shiva-fishing": "^1.0.0",
+    "shiva-hunting": "^1.0.0",
+    "shiva-farming": "^1.0.0",
+    "shiva-realtor": "^1.0.0",
+    "shiva-tattoo": "^1.0.0",
+    "shiva-barbershop": "^1.0.0"
+  }
+}

package/src/commands/ai/context.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+const chalk = require('chalk');
+
+const { requireServerRoot, getResourcesDir } = require('../../utils/server-root');
+const { scanModules } = require('../../utils/lua-parser');
+const { normalizeModuleName } = require('../../generators/index');
+
+function aiContextCommand(program) {
+  program
+    .command('ai:context')
+    .description('Generate AGENTS.md from installed modules')
+    .option('-m, --module <module>', 'Generate context for a specific module only')
+    .option('-o, --output <path>',   'Output file path', 'AGENTS.md')
+    .action((options) => { run(options); });
+}
+
+function run(options) {
+  const serverRoot   = requireServerRoot();
+  const resourcesDir = getResourcesDir(serverRoot);
+  let   modules      = scanModules(resourcesDir);
+
+  if (options.module) {
+    const name = normalizeModuleName(options.module);
+    modules    = modules.filter(m => m.name === name);
+    if (modules.length === 0) {
+      console.error(chalk.red(`✖ Module not found: ${name}`));
+      process.exit(1);
+    }
+  }
+
+  const lines = [];
+  lines.push('# Shiva Server — AI Agent Context');
+  lines.push('');
+  lines.push('> Auto-generated by `shiva ai:context`. Do not edit manually.');
+  lines.push('');
+  lines.push(`Generated: ${new Date().toISOString()}`);
+  lines.push('');
+  lines.push('## Installed Modules');
+  lines.push('');
+  lines.push(`${modules.length} module(s) installed.`);
+  lines.push('');
+
+  for (const mod of modules) {
+    const m = mod.manifest;
+    lines.push(`### ${mod.name}`);
+    lines.push('');
+    if (m.description) lines.push(m.description);
+    lines.push('');
+    lines.push(`- **Version**: ${m.version || '?'}`);
+    if ((m.dependencies || []).length > 0) {
+      lines.push(`- **Dependencies**: ${m.dependencies.join(', ')}`);
+    }
+    if ((m.provides || []).length > 0) {
+      lines.push(`- **Provides**: ${m.provides.join(', ')}`);
+    }
+    if ((m.events || []).length > 0) {
+      lines.push('- **Events**:');
+      m.events.forEach(e => lines.push(`  - \`${e}\``));
+    }
+    if ((m.migrations || []).length > 0) {
+      lines.push(`- **Migrations**: ${m.migrations.length}`);
+    }
+    lines.push('');
+  }
+
+  const contractsDir = path.join(serverRoot, 'shared', 'contracts');
+  if (fs.existsSync(contractsDir)) {
+    const contracts = fs.readdirSync(contractsDir).filter(f => f.endsWith('.lua'));
+    if (contracts.length > 0) {
+      lines.push('## Contracts');
+      lines.push('');
+      contracts.forEach(f => lines.push(`- \`${f.replace('.lua', '')}\``));
+      lines.push('');
+    }
+  }
+
+  const outPath = path.resolve(serverRoot, options.output);
+  fs.writeFileSync(outPath, lines.join('\n'), 'utf-8');
+
+  console.log('');
+  console.log(chalk.green(`✔ Generated ${path.relative(process.cwd(), outPath)}`));
+  console.log(chalk.gray(`  ${modules.length} modules documented.`));
+  console.log('');
+}
+
+module.exports = aiContextCommand;

package/src/commands/ai/link.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+const chalk = require('chalk');
+const { requireServerRoot } = require('../../utils/server-root');
+
+function aiLinkCommand(program) {
+  program
+    .command('ai:link')
+    .description('Create CLAUDE.md and GEMINI.md symlinks pointing at AGENTS.md')
+    .action(() => { run(); });
+}
+
+function run() {
+  const serverRoot = requireServerRoot();
+  const agentsFile = path.join(serverRoot, 'AGENTS.md');
+  const targets    = ['CLAUDE.md', 'GEMINI.md'];
+
+  if (!fs.existsSync(agentsFile)) {
+    console.error(chalk.red('✖ AGENTS.md not found. Run `shiva ai:context` first.'));
+    process.exit(1);
+  }
+
+  console.log('');
+  for (const target of targets) {
+    const linkPath = path.join(serverRoot, target);
+    try {
+      const stat = fs.lstatSync(linkPath);
+      if (stat) fs.unlinkSync(linkPath);
+    } catch {}
+    fs.symlinkSync('AGENTS.md', linkPath);
+    console.log(chalk.green(`✔ ${target} → AGENTS.md`));
+  }
+  console.log('');
+}
+
+module.exports = aiLinkCommand;

package/src/commands/ai/mcp.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+const chalk = require('chalk');
+const { requireServerRoot } = require('../../utils/server-root');
+const { readShivaConfig }   = require('../../utils/config-reader');
+
+function aiMcpCommand(program) {
+  program
+    .command('ai:mcp')
+    .description('Generate .mcp.json for AI tool integrations')
+    .option('-p, --port <port>', 'MCP server port', '3100')
+    .action((options) => { run(options); });
+}
+
+function run(options) {
+  const serverRoot = requireServerRoot();
+  const mcpJson    = {
+    mcpServers: {
+      shiva: {
+        command: 'shiva',
+        args:    ['mcp', 'start'],
+        env:     {},
+      },
+    },
+  };
+
+  const outPath = path.join(serverRoot, '.mcp.json');
+  fs.writeFileSync(outPath, JSON.stringify(mcpJson, null, 2) + '\n', 'utf-8');
+
+  console.log('');
+  console.log(chalk.green('✔ Created .mcp.json'));
+  console.log(chalk.gray('  Add this to your Claude Code / Cursor / Windsurf MCP config.'));
+  console.log(chalk.gray('  Start the server with: shiva mcp start'));
+  console.log('');
+}
+
+module.exports = aiMcpCommand;

package/src/commands/config/validate.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+const chalk = require('chalk');
+
+const { requireServerRoot, getResourcesDir } = require('../../utils/server-root');
+const { scanModules } = require('../../utils/lua-parser');
+
+function configValidateCommand(program) {
+  program
+    .command('config:validate')
+    .description('Validate module configuration files')
+    .action(() => { run(); });
+}
+
+function run() {
+  const serverRoot   = requireServerRoot();
+  const resourcesDir = getResourcesDir(serverRoot);
+  const modules      = scanModules(resourcesDir);
+
+  let passed = 0;
+  let warned = 0;
+  let failed = 0;
+
+  console.log('');
+  console.log(chalk.bold('Config Validation'));
+  console.log(chalk.gray('─'.repeat(60)));
+
+  for (const mod of modules) {
+    const configFile = path.join(mod.path, 'config', 'config.lua');
+
+    if (!fs.existsSync(configFile)) {
+      console.log(chalk.yellow(`  ⚠  ${mod.name.padEnd(28)} no config/config.lua`));
+      warned++;
+      continue;
+    }
+
+    const content = fs.readFileSync(configFile, 'utf-8');
+
+    if (!content.includes('Config.register(')) {
+      console.log(chalk.yellow(`  ⚠  ${mod.name.padEnd(28)} Config.register() not found`));
+      warned++;
+      continue;
+    }
+
+    const hasPlaceholder = /--\s*TODO/.test(content) && !/Config\.register\([^)]+,\s*\{[^}]+\}/.test(content);
+    if (hasPlaceholder) {
+      console.log(chalk.yellow(`  ⚠  ${mod.name.padEnd(28)} config appears to be a stub`));
+      warned++;
+      continue;
+    }
+
+    console.log(chalk.green(`  ✔  ${mod.name}`));
+    passed++;
+  }
+
+  console.log(chalk.gray('─'.repeat(60)));
+  console.log(`  ${chalk.green(passed + ' passed')}  ·  ${chalk.yellow(warned + ' warnings')}  ·  ${chalk.red(failed + ' failed')}`);
+  console.log('');
+
+  if (failed > 0) process.exit(1);
+}
+
+module.exports = configValidateCommand;