@shiva-fw/cli 1.0.0

package/src/generators/index.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATES_DIR = path.join(__dirname, 'templates');
+
+/**
+ * Render a template file, replacing {{KEY}} placeholders.
+ * @param {string} templateRelPath  Path relative to src/generators/templates/
+ * @param {object} vars             Key/value pairs for substitution
+ * @returns {string}
+ */
+function renderTemplate(templateRelPath, vars = {}) {
+  const fullPath = path.join(TEMPLATES_DIR, templateRelPath);
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(`Template not found: ${fullPath}`);
+  }
+  let content = fs.readFileSync(fullPath, 'utf-8');
+  for (const [key, value] of Object.entries(vars)) {
+    content = content.split(`{{${key}}}`).join(String(value));
+  }
+  return content;
+}
+
+/**
+ * Write a rendered template to a destination file.
+ * Creates parent directories automatically.
+ * @param {string} templateRelPath
+ * @param {string} destPath
+ * @param {object} vars
+ */
+function writeTemplate(templateRelPath, destPath, vars = {}) {
+  const content = renderTemplate(templateRelPath, vars);
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  fs.writeFileSync(destPath, content, 'utf-8');
+}
+
+/**
+ * Convert a name to PascalCase.
+ * e.g. "fishing-rod" → "FishingRod", "fishing_rod" → "FishingRod"
+ * @param {string} name
+ * @returns {string}
+ */
+function toPascalCase(name) {
+  return name
+    .replace(/[-_](.)/g, (_, c) => c.toUpperCase())
+    .replace(/^(.)/, c => c.toUpperCase());
+}
+
+/**
+ * Convert a name to snake_case.
+ * e.g. "FishingRod" → "fishing_rod"
+ * @param {string} name
+ * @returns {string}
+ */
+function toSnakeCase(name) {
+  return name
+    .replace(/([A-Z])/g, '_$1')
+    .toLowerCase()
+    .replace(/^[-_]/, '')
+    .replace(/[-]/g, '_');
+}
+
+/**
+ * Normalize a module name, ensuring "shiva-" prefix.
+ * @param {string} name
+ * @returns {string}
+ */
+function normalizeModuleName(name) {
+  name = name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  if (!name.startsWith('shiva-')) {
+    name = 'shiva-' + name;
+  }
+  return name;
+}
+
+module.exports = { renderTemplate, writeTemplate, toPascalCase, toSnakeCase, normalizeModuleName };

package/src/generators/templates/contract.lua.tpl

@@ -0,0 +1,12 @@
+return {
+    name   = '{{ContractName}}',
+    server = {
+        -- 'methodName',
+    },
+    client = {
+        -- 'methodName',
+    },
+    events = {
+        -- '{{module_short}}:eventName',
+    },
+}

package/src/generators/templates/migration.lua.tpl

@@ -0,0 +1,15 @@
+return {
+    up = function(DB)
+        DB.execute([[
+            -- TODO: Write your migration SQL
+            --
+            -- Example:
+            -- CREATE TABLE IF NOT EXISTS `{{snake_name}}` (
+            --     `id`         INT UNSIGNED NOT NULL AUTO_INCREMENT,
+            --     `created_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            --     `updated_at` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+            --     PRIMARY KEY (`id`)
+            -- ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+        ]])
+    end,
+}

package/src/generators/templates/model.lua.tpl

@@ -0,0 +1,14 @@
+---@class {{ModelName}} : ModelClass
+{{ModelName}} = Model.define('{{table_name}}')
+
+---@param id integer
+---@return table|nil
+function {{ModelName}}.findById(id)
+    return DB.table('{{table_name}}'):where('id', id):first()
+end
+
+-- TODO: Add custom query methods
+-- Example:
+-- function {{ModelName}}.findByField(value)
+--     return DB.table('{{table_name}}'):where('field', value):get()
+-- end

package/src/generators/templates/module/client/init.lua.tpl

@@ -0,0 +1,5 @@
+-- Request initial state from server when character is ready.
+EventBus.on('player:characterReady', function()
+    -- TriggerServerEvent('{{module_short}}:requestState')
+end)
+Log.info('[{{module_short}}] Client ready.')

package/src/generators/templates/module/config/config.lua.tpl

@@ -0,0 +1,4 @@
+Config.register('{{module_short}}', {
+    -- TODO: Add module configuration options
+    -- enabled = true,
+})

package/src/generators/templates/module/fxmanifest.lua.tpl

@@ -0,0 +1,41 @@
+fx_version 'cerulean'
+game 'gta5'
+lua54 'yes'
+
+name        '{{module_name}}'
+description '{{description}}'
+version     '1.0.0'
+author      '{{author}}'
+
+dependencies {
+    'shiva-core',
+}
+
+shared_scripts {
+    'module.lua',
+    'config/config.lua',
+    'locales/en.lua',
+    'shared/sh_{{module_short}}.lua',
+}
+
+server_scripts {
+    -- Migrations — add entries here as you create them:
+    -- 'migrations/YYYY_MM_DD_HHMMSS_create_example.lua',
+
+    -- Models
+    -- 'server/models/Example.lua',
+
+    -- Services
+    -- 'server/services/ExampleService.lua',
+
+    -- Events
+    -- 'server/events/handlers.lua',
+
+    'server/boot.lua',
+}
+
+client_scripts {
+    -- 'client/services/ExampleClient.lua',
+    -- 'client/events/handlers.lua',
+    'client/boot.lua',
+}

package/src/generators/templates/module/locales/en.lua.tpl

@@ -0,0 +1,4 @@
+Locale.register('{{module_short}}', 'en', {
+    -- TODO: Add locale strings
+    -- ['error.notFound'] = 'Not found.',
+})

package/src/generators/templates/module/module.lua.tpl

@@ -0,0 +1,10 @@
+return {
+    name         = '{{module_name}}',
+    version      = '1.0.0',
+    description  = '{{description}}',
+    author       = '{{author}}',
+    dependencies = {},
+    provides     = {},
+    migrations   = {},
+    events       = {},
+}

package/src/generators/templates/module/server/init.lua.tpl

@@ -0,0 +1,2 @@
+Container.bind('{{PascalName}}', {{PascalName}}Service)
+Log.info('[{{module_short}}] {{PascalName}}Service ready.')

package/src/generators/templates/module/shared/init.lua.tpl

@@ -0,0 +1,5 @@
+---@enum {{PascalName}}Type
+{{PascalName}}Type = {
+    -- TODO: define enum values
+    -- EXAMPLE = 'example',
+}

package/src/generators/templates/seed.lua.tpl

@@ -0,0 +1,10 @@
+return {
+    run = function(db)
+        -- TODO: Insert seed data
+        -- Example:
+        -- db.execute([[
+        --     INSERT IGNORE INTO `{{table_name}}` (`id`, `name`) VALUES
+        --     (1, 'example')
+        -- ]])
+    end,
+}

package/src/generators/templates/service.lua.tpl

@@ -0,0 +1,7 @@
+{{ServiceName}} = {}
+
+---@return any
+function {{ServiceName}}.example()
+    -- TODO: Implement
+    -- Available globals: Container, Locale, Config, EventBus, Log, DB
+end

package/src/generators/templates/test.lua.tpl

@@ -0,0 +1,39 @@
+---@diagnostic disable: undefined-field, duplicate-set-field, need-check-nil
+-- tests/{{test_name}}_spec.lua
+-- Unit tests for {{describe_name}}.
+-- Run with: shiva test --module {{module_name}}
+
+-- Resolve shiva-test relative to this file (both modules live in the same [category] folder)
+package.path = '../../shiva-test/?.lua;../../shiva-test/?/init.lua;' .. package.path
+
+local Test = require('src.init')
+
+Test.setup({ mode = 'server' })
+
+local describe   = Test.describe
+local it         = Test.it
+local expect     = Test.expect
+local beforeEach = Test.beforeEach
+
+describe('{{describe_name}}', function()
+    beforeEach(function()
+        -- Stub Shiva globals used by {{describe_name}}
+        Container = { resolve = function() end, bind = function() end }
+        Config    = { get = function() end, register = function() end }
+        Locale    = { t = function(_, key) return key end, register = function() end }
+        EventBus  = { emit = function() end, on = function() end }
+        DB        = { table = function() return DB end, execute = function() end }
+        Log       = { info = function() end, debug = function() end, warn = function() end }
+    end)
+
+    it('passes a basic sanity check', function()
+        expect(true):toBeTrue()
+    end)
+
+    -- it('should ...', function()
+    --     local actual = ...
+    --     expect(actual):toBe(expected)
+    -- end)
+end)
+
+Test.run()

package/src/index.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const pkg = require('../package.json');
+
+// Scaffolding
+const initCommand          = require('./commands/init');
+const makeModuleCommand    = require('./commands/make/module');
+const makeServiceCommand   = require('./commands/make/service');
+const makeModelCommand     = require('./commands/make/model');
+const makeMigrationCommand = require('./commands/make/migration');
+const makeTestCommand      = require('./commands/make/test');
+const makeContractCommand  = require('./commands/make/contract');
+const makeSeedCommand      = require('./commands/make/seed');
+
+// Migrations
+const migrateRunCommand      = require('./commands/migrate/run');
+const migrateRollbackCommand = require('./commands/migrate/rollback');
+const migrateStatusCommand   = require('./commands/migrate/status');
+
+// Seeding
+const seedCommand = require('./commands/seed');
+
+// Module inspection
+const moduleListCommand   = require('./commands/module/list');
+const moduleStatusCommand = require('./commands/module/status');
+
+// Config & locale
+const configValidateCommand = require('./commands/config/validate');
+const localeMissingCommand  = require('./commands/locale/missing');
+
+// Package management
+const installCommand  = require('./commands/install');
+const updateCommand   = require('./commands/update');
+const outdatedCommand = require('./commands/outdated');
+const removeCommand   = require('./commands/remove');
+
+// Testing
+const testCommand = require('./commands/test');
+
+// AI integration
+const aiContextCommand = require('./commands/ai/context');
+const aiLinkCommand    = require('./commands/ai/link');
+const aiMcpCommand     = require('./commands/ai/mcp');
+
+// MCP server
+const mcpCommand = require('./commands/mcp');
+
+// Docs
+const docsBuildCommand  = require('./commands/docs/build');
+const docsServeCommand  = require('./commands/docs/serve');
+const docsApiCommand    = require('./commands/docs/api');
+const docsDeployCommand = require('./commands/docs/deploy');
+
+program
+  .name('shiva')
+  .description(chalk.cyan('Developer CLI for the Shiva FiveM framework'))
+  .version(pkg.version, '-v, --version', 'Output the current version');
+
+initCommand(program);
+
+makeModuleCommand(program);
+makeServiceCommand(program);
+makeModelCommand(program);
+makeMigrationCommand(program);
+makeTestCommand(program);
+makeContractCommand(program);
+makeSeedCommand(program);
+
+migrateRunCommand(program);
+migrateRollbackCommand(program);
+migrateStatusCommand(program);
+
+seedCommand(program);
+
+moduleListCommand(program);
+moduleStatusCommand(program);
+
+configValidateCommand(program);
+localeMissingCommand(program);
+
+installCommand(program);
+updateCommand(program);
+outdatedCommand(program);
+removeCommand(program);
+
+testCommand(program);
+
+aiContextCommand(program);
+aiLinkCommand(program);
+aiMcpCommand(program);
+
+mcpCommand(program);
+
+docsBuildCommand(program);
+docsServeCommand(program);
+docsApiCommand(program);
+docsDeployCommand(program);
+
+program.addHelpText('after', `
+${chalk.bold('Examples:')}
+  $ shiva init
+  $ shiva make:module fishing
+  $ shiva make:service FishingService --module shiva-fishing
+  $ shiva make:migration create_fish_catches --module shiva-fishing
+  $ shiva migrate
+  $ shiva module:list
+  $ shiva install shiva-fishing
+  $ shiva mcp start
+`);
+
+program.parse(process.argv);

package/src/mcp/resources/contracts.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { findServerRoot } = require('../../utils/server-root');
+
+const TEMPLATE_URI = 'shiva:contracts/{name}';
+
+/**
+ * Resolve the contracts directory — checks project-level then shiva-core submodule.
+ * @param {string} serverRoot
+ * @returns {string|null}
+ */
+function findContractsDir(serverRoot) {
+  const candidates = [
+    path.join(serverRoot, 'shared', 'contracts'),
+    path.join(serverRoot, 'shared', 'sh_contracts'),
+    path.join(serverRoot, 'resources', '[shiva]', 'shiva-core', 'shared', 'sh_contracts'),
+  ];
+  return candidates.find(d => fs.existsSync(d)) || null;
+}
+
+/**
+ * List all available contracts.
+ * @param {string} serverRoot
+ * @returns {Array<{uri, name, description, mimeType}>}
+ */
+function listContracts(serverRoot) {
+  const dir = findContractsDir(serverRoot);
+  if (!dir) return [];
+
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.lua'))
+    .map(f => {
+      const slug = f.replace(/^sh_/, '').replace(/\.lua$/, '');
+      const name = slug.charAt(0).toUpperCase() + slug.slice(1);
+      return {
+        uri:         `shiva:contracts/${slug}`,
+        name:        `${name} contract`,
+        description: `Contract interface: ${name}`,
+        mimeType:    'text/x-lua',
+      };
+    });
+}
+
+/**
+ * Read a contract resource by URI.
+ * @param {string} uri   e.g. "shiva:contracts/economy"
+ * @param {string} serverRoot
+ * @returns {{uri, mimeType, text}|null}
+ */
+function readContract(uri, serverRoot) {
+  const slug = uri.replace(/^shiva:contracts\//, '');
+  const dir  = findContractsDir(serverRoot);
+  if (!dir) return null;
+
+  const file = path.join(dir, `sh_${slug}.lua`);
+  if (!fs.existsSync(file)) return null;
+
+  return {
+    uri,
+    mimeType: 'text/x-lua',
+    text:     fs.readFileSync(file, 'utf-8'),
+  };
+}
+
+module.exports = { TEMPLATE_URI, listContracts, readContract };

package/src/mcp/resources/docs.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { scanModules }     = require('../../utils/lua-parser');
+const { getResourcesDir } = require('../../utils/server-root');
+
+const TEMPLATE_URI = 'shiva:docs/{topic}';
+
+/**
+ * List all available doc topics (module AGENTS.md files).
+ * @param {string} serverRoot
+ * @returns {Array<{uri, name, description, mimeType}>}
+ */
+function listDocs(serverRoot) {
+  const modules   = scanModules(getResourcesDir(serverRoot));
+  const resources = [];
+
+  for (const mod of modules) {
+    const agentsFile = path.join(mod.path, 'AGENTS.md');
+    if (!fs.existsSync(agentsFile)) continue;
+    resources.push({
+      uri:         `shiva:docs/${mod.name}`,
+      name:        `${mod.name} documentation`,
+      description: mod.manifest.description || `AGENTS.md for ${mod.name}`,
+      mimeType:    'text/markdown',
+    });
+  }
+
+  return resources;
+}
+
+/**
+ * Read a doc resource by URI.
+ * @param {string} uri   e.g. "shiva:docs/shiva-economy"
+ * @param {string} serverRoot
+ * @returns {{uri, mimeType, text}|null}
+ */
+function readDoc(uri, serverRoot) {
+  const topic   = uri.replace(/^shiva:docs\//, '');
+  const modules = scanModules(getResourcesDir(serverRoot));
+  const mod     = modules.find(m => m.name === topic);
+  if (!mod) return null;
+
+  const agentsFile = path.join(mod.path, 'AGENTS.md');
+  if (!fs.existsSync(agentsFile)) return null;
+
+  return {
+    uri,
+    mimeType: 'text/markdown',
+    text:     fs.readFileSync(agentsFile, 'utf-8'),
+  };
+}
+
+module.exports = { TEMPLATE_URI, listDocs, readDoc };