@shiva-fw/cli 1.0.0

package/src/mcp/resources/examples.js

@@ -0,0 +1,235 @@
+'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:examples/{pattern}';
+
+// Built-in code examples derived from shiva-core patterns
+const BUILTIN_EXAMPLES = [
+  {
+    pattern:  'service',
+    name:     'Service registration',
+    mimeType: 'text/x-lua',
+    text: `-- Register a service into the container
+Container.register('Economy', {
+    getBalance = function(source)
+        local char = State.getPlayer(source, 'character')
+        return DB.table('accounts'):where('character_id', char.id):first()
+    end,
+
+    addMoney = function(source, amount, reason)
+        local char    = State.getPlayer(source, 'character')
+        local account = DB.table('accounts'):where('character_id', char.id):first()
+        DB.table('accounts'):where('id', account.id):update({ balance = account.balance + amount })
+        EventBus.emit('economy:balanceChanged', source, { delta = amount, reason = reason })
+    end,
+})`,
+  },
+  {
+    pattern:  'migration',
+    name:     'Database migration',
+    mimeType: 'text/x-lua',
+    text: `-- migrations/001_create_accounts.lua
+return {
+    up = function(DB)
+        DB.execute([[
+            CREATE TABLE IF NOT EXISTS accounts (
+                id           INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+                character_id INT UNSIGNED NOT NULL,
+                balance      INT UNSIGNED NOT NULL DEFAULT 0,
+                created_at   DATETIME DEFAULT CURRENT_TIMESTAMP,
+                INDEX idx_character_id (character_id)
+            )
+        ]])
+    end,
+    down = function(DB)
+        DB.execute('DROP TABLE IF EXISTS accounts')
+    end,
+}`,
+  },
+  {
+    pattern:  'model',
+    name:     'Model definition',
+    mimeType: 'text/x-lua',
+    text: `-- server/models/Account.lua
+local Account = Model.define('accounts', {
+    primaryKey = 'id',
+    fillable   = { 'character_id', 'balance' },
+    casts      = { metadata = 'json' },
+})
+
+-- Usage
+local acc = Account:where('character_id', charId):first()
+acc:update({ balance = acc.balance + 100 })`,
+  },
+  {
+    pattern:  'event',
+    name:     'EventBus usage',
+    mimeType: 'text/x-lua',
+    text: `-- Listen for an event
+EventBus.on('economy:balanceChanged', function(source, payload)
+    Log.info('economy', 'Balance changed', { source = source, delta = payload.delta })
+end, 10)
+
+-- Before plugin (can halt)
+EventBus.before('Economy', 'transfer', function(from, to, amount)
+    if amount < 0 then
+        return EventBus.halt({ success = false, error = 'Amount must be positive' })
+    end
+end)
+
+-- After plugin (chain result)
+EventBus.after('Economy', 'transfer', function(result, from, to, amount)
+    Log.info('audit', 'Transfer completed', { from = from, to = to, amount = amount })
+    return result
+end)`,
+  },
+  {
+    pattern:  'command',
+    name:     'Command registration',
+    mimeType: 'text/x-lua',
+    text: `-- Register a command via the Commands contract
+Commands.register('givemoney', {
+    description = 'Give money to a player',
+    permission  = 'admin',
+    params      = {
+        { name = 'target', type = 'number',  help = 'Target player ID' },
+        { name = 'amount', type = 'number',  help = 'Amount to give' },
+        { name = 'reason', type = 'string',  help = 'Reason', optional = true },
+    },
+}, function(source, args)
+    local Economy = Container.resolve('Economy')
+    Economy.addMoney(args.target, args.amount, args.reason or 'admin_grant')
+end)`,
+  },
+  {
+    pattern:  'contract',
+    name:     'Contract definition',
+    mimeType: 'text/x-lua',
+    text: `-- shared/sh_contracts/sh_economy.lua
+return {
+    name   = 'Economy',
+    server = {
+        'getBalance',
+        'addMoney',
+        'removeMoney',
+        'transfer',
+    },
+    client = {
+        'getBalance',
+    },
+    events = {
+        'economy:balanceChanged',
+        'economy:transfer',
+    },
+}`,
+  },
+  {
+    pattern:  'module',
+    name:     'Module manifest',
+    mimeType: 'text/x-lua',
+    text: `-- module.lua
+return {
+    name    = 'shiva-economy',
+    version = '1.0.0',
+    description = 'Player economy with cash, bank, and transfers',
+
+    dependencies = {
+        'shiva-player',
+    },
+
+    optionalDependencies = {
+        'shiva-discord',
+    },
+
+    provides = {
+        'Economy',
+    },
+
+    metadata = {
+        accounts = { type = 'table', default = {} },
+    },
+
+    events = {
+        'economy:balanceChanged',
+        'economy:transfer',
+    },
+}`,
+  },
+];
+
+/**
+ * List all available example patterns, plus any from installed modules.
+ * @param {string} serverRoot
+ * @returns {Array<{uri, name, description, mimeType}>}
+ */
+function listExamples(serverRoot) {
+  const resources = BUILTIN_EXAMPLES.map(ex => ({
+    uri:         `shiva:examples/${ex.pattern}`,
+    name:        ex.name,
+    description: `Example: ${ex.name}`,
+    mimeType:    ex.mimeType,
+  }));
+
+  // Also surface example files from installed modules (examples/ directories)
+  if (serverRoot) {
+    try {
+      const modules = scanModules(getResourcesDir(serverRoot));
+      for (const mod of modules) {
+        const examplesDir = path.join(mod.path, 'examples');
+        if (!fs.existsSync(examplesDir)) continue;
+        for (const file of fs.readdirSync(examplesDir)) {
+          if (!file.endsWith('.lua')) continue;
+          const slug = `${mod.name}/${file.replace(/\.lua$/, '')}`;
+          resources.push({
+            uri:         `shiva:examples/${slug}`,
+            name:        `${mod.name}: ${file}`,
+            description: `Example from ${mod.name}`,
+            mimeType:    'text/x-lua',
+          });
+        }
+      }
+    } catch {
+      // modules not found — skip
+    }
+  }
+
+  return resources;
+}
+
+/**
+ * Read an example resource by URI.
+ * @param {string} uri   e.g. "shiva:examples/service"
+ * @param {string} serverRoot
+ * @returns {{uri, mimeType, text}|null}
+ */
+function readExample(uri, serverRoot) {
+  const pattern = uri.replace(/^shiva:examples\//, '');
+
+  // Built-in examples
+  const builtin = BUILTIN_EXAMPLES.find(ex => ex.pattern === pattern);
+  if (builtin) return { uri, mimeType: builtin.mimeType, text: builtin.text };
+
+  // Module-sourced examples (e.g. "shiva-economy/transfer")
+  if (serverRoot) {
+    const parts  = pattern.split('/');
+    const modName = parts.slice(0, -1).join('/');
+    const file    = parts[parts.length - 1] + '.lua';
+    const modules = scanModules(getResourcesDir(serverRoot));
+    const mod     = modules.find(m => m.name === modName);
+    if (mod) {
+      const filePath = path.join(mod.path, 'examples', file);
+      if (fs.existsSync(filePath)) {
+        return { uri, mimeType: 'text/x-lua', text: fs.readFileSync(filePath, 'utf-8') };
+      }
+    }
+  }
+
+  return null;
+}
+
+module.exports = { TEMPLATE_URI, listExamples, readExample };

package/src/mcp/server.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const { Server }               = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ReadResourceRequestSchema,
+} = require('@modelcontextprotocol/sdk/types.js');
+
+const { findServerRoot } = require('../utils/server-root');
+
+// ─── Load tools ───────────────────────────────────────────────────────────────
+
+const contractsTool = require('./tools/contracts');
+const modulesTool   = require('./tools/modules');
+const databaseTools = require('./tools/database');   // array
+const configTool    = require('./tools/config');
+const eventsTool    = require('./tools/events');
+const docsTool      = require('./tools/docs');
+const itemsTools    = require('./tools/items');       // array
+
+const TOOLS = [
+  contractsTool,
+  modulesTool,
+  ...databaseTools,
+  configTool,
+  eventsTool,
+  docsTool,
+  ...itemsTools,
+];
+
+// ─── Load resources ───────────────────────────────────────────────────────────
+
+const docsResource      = require('./resources/docs');
+const contractsResource = require('./resources/contracts');
+const examplesResource  = require('./resources/examples');
+
+const RESOURCE_TEMPLATES = [
+  { uriTemplate: docsResource.TEMPLATE_URI,      name: 'Module docs',     description: 'AGENTS.md content for an installed module',   mimeType: 'text/markdown' },
+  { uriTemplate: contractsResource.TEMPLATE_URI, name: 'Contract',        description: 'Shiva contract interface definition',          mimeType: 'text/x-lua'   },
+  { uriTemplate: examplesResource.TEMPLATE_URI,  name: 'Code example',    description: 'Example Lua code for common Shiva patterns',   mimeType: 'text/x-lua'   },
+];
+
+// ─── Server factory ───────────────────────────────────────────────────────────
+
+async function startMcpServer() {
+  const serverRoot = findServerRoot(process.cwd());
+
+  const server = new Server(
+    { name: 'shiva', version: '1.0.0' },
+    { capabilities: { tools: {}, resources: {} } }
+  );
+
+  // ── Tools ──────────────────────────────────────────────────────────────────
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = TOOLS.find(t => t.name === request.params.name);
+    if (!tool) {
+      return { content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }], isError: true };
+    }
+    try {
+      const result = await tool.handler(request.params.arguments || {}, serverRoot);
+      return {
+        content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+  });
+
+  // ── Resources ──────────────────────────────────────────────────────────────
+
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates: RESOURCE_TEMPLATES,
+  }));
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    if (!serverRoot) return { resources: [] };
+    const resources = [
+      ...docsResource.listDocs(serverRoot),
+      ...contractsResource.listContracts(serverRoot),
+      ...examplesResource.listExamples(serverRoot),
+    ];
+    return { resources };
+  });
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    if (!serverRoot) {
+      return { contents: [{ uri, mimeType: 'text/plain', text: 'Not in a Shiva project directory.' }] };
+    }
+
+    let resource = null;
+
+    if (uri.startsWith('shiva:docs/')) {
+      resource = docsResource.readDoc(uri, serverRoot);
+    } else if (uri.startsWith('shiva:contracts/')) {
+      resource = contractsResource.readContract(uri, serverRoot);
+    } else if (uri.startsWith('shiva:examples/')) {
+      resource = examplesResource.readExample(uri, serverRoot);
+    }
+
+    if (!resource) {
+      return { contents: [{ uri, mimeType: 'text/plain', text: `Resource not found: ${uri}` }] };
+    }
+
+    return { contents: [{ uri: resource.uri, mimeType: resource.mimeType, text: resource.text }] };
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+module.exports = { startMcpServer };

package/src/mcp/tools/config.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { scanModules }     = require('../../utils/lua-parser');
+const { getResourcesDir } = require('../../utils/server-root');
+
+module.exports = {
+  name: 'shiva:getModuleConfig',
+  description: 'Get the configuration file and schema for a module',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      module: { type: 'string', description: 'Module name, e.g. shiva-economy or economy' },
+    },
+    required: ['module'],
+  },
+
+  async handler({ module: moduleName }, serverRoot) {
+    if (!serverRoot) return 'Not in a Shiva project directory.';
+
+    const modules = scanModules(getResourcesDir(serverRoot));
+    const mod     = modules.find(m =>
+      m.name === moduleName ||
+      m.name === `shiva-${moduleName}` ||
+      m.name.endsWith(`-${moduleName}`)
+    );
+    if (!mod) return `Module not found: ${moduleName}`;
+
+    const configFile  = path.join(mod.path, 'config', 'config.lua');
+    const schemaFile  = path.join(mod.path, 'config', 'config.schema.lua');
+    const result      = { module: mod.name, path: mod.path };
+
+    if (fs.existsSync(configFile)) {
+      result.config = fs.readFileSync(configFile, 'utf-8');
+    } else {
+      result.config = null;
+    }
+
+    if (fs.existsSync(schemaFile)) {
+      result.schema = fs.readFileSync(schemaFile, 'utf-8');
+    } else {
+      result.schema = null;
+    }
+
+    if (!result.config && !result.schema) {
+      return `No config files found for ${moduleName}`;
+    }
+
+    return result;
+  },
+};

package/src/mcp/tools/contracts.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+module.exports = {
+  name: 'shiva:getContractMethods',
+  description: 'Get methods defined in a Shiva contract file',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      contract: { type: 'string', description: 'Contract name, e.g. Economy' },
+    },
+    required: ['contract'],
+  },
+
+  async handler({ contract }, serverRoot) {
+    if (!serverRoot) return 'Not in a Shiva project directory.';
+
+    // Check project-level contracts first, then shiva-core contracts
+    const slug  = contract.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+    const tries = [
+      path.join(serverRoot, 'shared', 'contracts', `sh_${slug}.lua`),
+      path.join(serverRoot, 'shared', 'sh_contracts', `sh_${slug}.lua`),
+      path.join(serverRoot, 'resources', '[shiva]', 'shiva-core', 'shared', 'sh_contracts', `sh_${slug}.lua`),
+    ];
+
+    for (const file of tries) {
+      if (fs.existsSync(file)) {
+        const raw = fs.readFileSync(file, 'utf-8');
+        return { file: path.relative(serverRoot, file), content: raw };
+      }
+    }
+
+    return `Contract not found: sh_${slug}.lua — tried ${tries.map(t => path.relative(serverRoot, t)).join(', ')}`;
+  },
+};

package/src/mcp/tools/database.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { getDatabaseConfig } = require('../../utils/config-reader');
+const { scanModules }       = require('../../utils/lua-parser');
+const { getResourcesDir }   = require('../../utils/server-root');
+
+async function openConnection(dbConfig) {
+  const mysql = require('mysql2/promise');
+  return mysql.createConnection({
+    host:     dbConfig.host     || '127.0.0.1',
+    port:     dbConfig.port     || 3306,
+    user:     dbConfig.user,
+    password: dbConfig.password,
+    database: dbConfig.database,
+  });
+}
+
+module.exports = [
+  {
+    name: 'shiva:getDatabaseSchema',
+    description: 'Get all tables and columns from the live database',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+
+    async handler(_, serverRoot) {
+      if (!serverRoot) return 'Not in a Shiva project directory.';
+      const dbConfig = getDatabaseConfig(serverRoot);
+      if (!dbConfig) return 'No database configuration found in shiva.json';
+
+      const conn = await openConnection(dbConfig);
+      try {
+        const [rows] = await conn.execute(
+          `SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_DEFAULT, COLUMN_KEY
+           FROM information_schema.COLUMNS
+           WHERE TABLE_SCHEMA = ?
+           ORDER BY TABLE_NAME, ORDINAL_POSITION`,
+          [dbConfig.database]
+        );
+        const schema = {};
+        for (const row of rows) {
+          if (!schema[row.TABLE_NAME]) schema[row.TABLE_NAME] = [];
+          schema[row.TABLE_NAME].push({
+            column:   row.COLUMN_NAME,
+            type:     row.COLUMN_TYPE,
+            nullable: row.IS_NULLABLE === 'YES',
+            default:  row.COLUMN_DEFAULT,
+            key:      row.COLUMN_KEY || null,
+          });
+        }
+        return schema;
+      } finally {
+        await conn.end();
+      }
+    },
+  },
+
+  {
+    name: 'shiva:getMigrationStatus',
+    description: 'Show which migrations have run and which are pending',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+
+    async handler(_, serverRoot) {
+      if (!serverRoot) return 'Not in a Shiva project directory.';
+      const dbConfig = getDatabaseConfig(serverRoot);
+      if (!dbConfig) return 'No database configuration found in shiva.json';
+
+      const conn = await openConnection(dbConfig);
+      try {
+        const [rows] = await conn.execute(
+          'SELECT migration, ran_at FROM shiva_migrations ORDER BY id'
+        ).catch(() => [[]]);
+
+        const ran     = new Set(rows.map(r => r.migration));
+        const modules = scanModules(getResourcesDir(serverRoot));
+        const all     = [];
+
+        for (const mod of modules) {
+          for (const mig of (mod.manifest.migrations || [])) {
+            const id = `${mod.name}/${mig}`;
+            const ranAt = rows.find(r => r.migration === id);
+            all.push({
+              migration: id,
+              status:    ran.has(id) ? 'ran' : 'pending',
+              ran_at:    ranAt ? ranAt.ran_at : null,
+            });
+          }
+        }
+        return all;
+      } finally {
+        await conn.end();
+      }
+    },
+  },
+];

package/src/mcp/tools/docs.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { scanModules }     = require('../../utils/lua-parser');
+const { getResourcesDir } = require('../../utils/server-root');
+
+module.exports = {
+  name: 'shiva:searchDocs',
+  description: 'Full-text search across AGENTS.md files in installed modules',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query' },
+    },
+    required: ['query'],
+  },
+
+  async handler({ query }, serverRoot) {
+    if (!serverRoot) return 'Not in a Shiva project directory.';
+
+    const modules = scanModules(getResourcesDir(serverRoot));
+    const results = [];
+    const q       = query.toLowerCase();
+
+    for (const mod of modules) {
+      const agentsFile = path.join(mod.path, 'AGENTS.md');
+      if (!fs.existsSync(agentsFile)) continue;
+      const content = fs.readFileSync(agentsFile, 'utf-8');
+      if (!content.toLowerCase().includes(q)) continue;
+      const lines = content.split('\n').filter(l => l.toLowerCase().includes(q));
+      results.push({ module: mod.name, matches: lines.slice(0, 5) });
+    }
+
+    return results.length > 0 ? results : `No documentation matches for "${query}"`;
+  },
+};

package/src/mcp/tools/events.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const { scanModules }     = require('../../utils/lua-parser');
+const { getResourcesDir } = require('../../utils/server-root');
+
+module.exports = {
+  name: 'shiva:getRegisteredEvents',
+  description: 'Get all events declared across installed modules',
+  inputSchema: { type: 'object', properties: {}, required: [] },
+
+  async handler(_, serverRoot) {
+    if (!serverRoot) return 'Not in a Shiva project directory.';
+
+    const modules = scanModules(getResourcesDir(serverRoot));
+    const events  = [];
+
+    for (const mod of modules) {
+      for (const event of (mod.manifest.events || [])) {
+        events.push({ module: mod.name, event });
+      }
+    }
+
+    if (events.length === 0) return 'No events declared in installed modules.';
+    return events;
+  },
+};