@shiva-fw/cli 1.0.0

package/src/mcp/tools/items.js

@@ -0,0 +1,280 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { scanModules }     = require('../../utils/lua-parser');
+const { getResourcesDir } = require('../../utils/server-root');
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Recursively collect all .lua files under a directory.
+ * @param {string} dir
+ * @param {string[]} [results]
+ * @returns {string[]}
+ */
+function collectLuaFiles(dir, results = []) {
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectLuaFiles(full, results);
+    } else if (entry.isFile() && entry.name.endsWith('.lua')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Extract inline string values from a Lua table field, e.g.
+ *   label = 'Bread'  →  'Bread'
+ * @param {string} block
+ * @param {string} field
+ * @returns {string|null}
+ */
+function extractField(block, field) {
+  const re    = new RegExp(`${field}\\s*=\\s*['"]([^'"]+)['"]`);
+  const match = block.match(re);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract a numeric field from a Lua table block.
+ * @param {string} block
+ * @param {string} field
+ * @returns {number|null}
+ */
+function extractNumber(block, field) {
+  const re    = new RegExp(`${field}\\s*=\\s*(\\d+(?:\\.\\d+)?)`);
+  const match = block.match(re);
+  return match ? parseFloat(match[1]) : null;
+}
+
+// ─── Tools ────────────────────────────────────────────────────────────────────
+
+const getItemDefinitions = {
+  name: 'shiva:getItemDefinitions',
+  description: 'Get all registered inventory item definitions from 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 items   = [];
+
+    for (const mod of modules) {
+      const luaFiles = collectLuaFiles(mod.path);
+      for (const file of luaFiles) {
+        const content = fs.readFileSync(file, 'utf-8');
+
+        // Pattern 1: Config.Items['key'] = { label = '...', weight = ..., type = '...' }
+        const cfgItemRe = /Config\.Items\s*\[\s*['"]([^'"]+)['"]\s*\]\s*=\s*\{([^}]+)\}/g;
+        let m;
+        while ((m = cfgItemRe.exec(content)) !== null) {
+          const [, name, body] = m;
+          items.push({
+            name,
+            module:  mod.name,
+            label:   extractField(body, 'label'),
+            weight:  extractNumber(body, 'weight'),
+            type:    extractField(body, 'type') || 'item',
+            usable:  /usable\s*=\s*true/.test(body),
+          });
+        }
+
+        // Pattern 2: items['key'] = { ... } (local table)
+        const localItemRe = /\bitems\s*\[\s*['"]([^'"]+)['"]\s*\]\s*=\s*\{([^}]+)\}/g;
+        while ((m = localItemRe.exec(content)) !== null) {
+          const [, name, body] = m;
+          if (items.find(i => i.name === name && i.module === mod.name)) continue;
+          items.push({
+            name,
+            module:  mod.name,
+            label:   extractField(body, 'label'),
+            weight:  extractNumber(body, 'weight'),
+            type:    extractField(body, 'type') || 'item',
+            usable:  /usable\s*=\s*true/.test(body),
+          });
+        }
+
+        // Pattern 3: Inventory.registerItem('key', { ... }) or Item.register(...)
+        const registerRe = /(?:Inventory\.registerItem|Item\.register)\s*\(\s*['"]([^'"]+)['"]\s*,\s*\{([^}]+)\}/g;
+        while ((m = registerRe.exec(content)) !== null) {
+          const [, name, body] = m;
+          if (items.find(i => i.name === name && i.module === mod.name)) continue;
+          items.push({
+            name,
+            module:  mod.name,
+            label:   extractField(body, 'label'),
+            weight:  extractNumber(body, 'weight'),
+            type:    extractField(body, 'type') || 'item',
+            usable:  /usable\s*=\s*true/.test(body),
+          });
+        }
+      }
+    }
+
+    if (items.length === 0) return 'No item definitions found in installed modules.';
+    return items;
+  },
+};
+
+const getJobDefinitions = {
+  name: 'shiva:getJobDefinitions',
+  description: 'Get all registered job definitions from 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 jobs    = [];
+
+    for (const mod of modules) {
+      const luaFiles = collectLuaFiles(mod.path);
+      for (const file of luaFiles) {
+        const content = fs.readFileSync(file, 'utf-8');
+
+        // Pattern 1: Config.Jobs['key'] = { label = '...', grades = {...} }
+        const cfgJobRe = /Config\.Jobs\s*\[\s*['"]([^'"]+)['"]\s*\]\s*=\s*\{([\s\S]*?)(?=\n\s*\}[\s\n]*(?:--|\[|Config|$))/g;
+        let m;
+        while ((m = cfgJobRe.exec(content)) !== null) {
+          const [, name, body] = m;
+          const grades = [];
+          const gradeRe = /\[(\d+)\]\s*=\s*\{([^}]+)\}/g;
+          let gm;
+          while ((gm = gradeRe.exec(body)) !== null) {
+            grades.push({
+              grade:  parseInt(gm[1], 10),
+              label:  extractField(gm[2], 'label'),
+              salary: extractNumber(gm[2], 'salary'),
+            });
+          }
+          jobs.push({ name, module: mod.name, label: extractField(body, 'label'), grades });
+        }
+
+        // Pattern 2: Job.register('key', { ... }) or Jobs.register(...)
+        const registerRe = /(?:Job\.register|Jobs\.register)\s*\(\s*['"]([^'"]+)['"]\s*,\s*\{([^}]+)\}/g;
+        while ((m = registerRe.exec(content)) !== null) {
+          const [, name, body] = m;
+          if (jobs.find(j => j.name === name && j.module === mod.name)) continue;
+          jobs.push({ name, module: mod.name, label: extractField(body, 'label'), grades: [] });
+        }
+      }
+    }
+
+    if (jobs.length === 0) return 'No job definitions found in installed modules.';
+    return jobs;
+  },
+};
+
+const getAvailableCommands = {
+  name: 'shiva:getAvailableCommands',
+  description: 'Get all registered commands from 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 commands = [];
+
+    for (const mod of modules) {
+      const luaFiles = collectLuaFiles(mod.path);
+      for (const file of luaFiles) {
+        const content = fs.readFileSync(file, 'utf-8');
+        const side    = path.basename(file).startsWith('sv_') ? 'server'
+                      : path.basename(file).startsWith('cl_') ? 'client'
+                      : 'shared';
+
+        // Pattern 1: Commands.register('name', { description, permission, params }, fn)
+        const cmdRe = /Commands\.register\s*\(\s*['"]([^'"]+)['"]\s*,\s*\{([^}]*)\}/g;
+        let m;
+        while ((m = cmdRe.exec(content)) !== null) {
+          const [, name, body] = m;
+          commands.push({
+            name,
+            module:      mod.name,
+            side,
+            description: extractField(body, 'description'),
+            permission:  extractField(body, 'permission'),
+          });
+        }
+
+        // Pattern 2: RegisterCommand('name', fn, restricted)
+        const regCmdRe = /RegisterCommand\s*\(\s*['"]([^'"]+)['"]/g;
+        while ((m = regCmdRe.exec(content)) !== null) {
+          const [, name] = m;
+          if (commands.find(c => c.name === name && c.module === mod.name)) continue;
+          commands.push({ name, module: mod.name, side, description: null, permission: null });
+        }
+      }
+    }
+
+    if (commands.length === 0) return 'No commands found in installed modules.';
+    return commands;
+  },
+};
+
+const getServiceMethods = {
+  name: 'shiva:getServiceMethods',
+  description: 'Get all service methods from installed modules (including contract extensions)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      service: { type: 'string', description: 'Service/contract name to filter, e.g. Economy. Omit for all.' },
+    },
+    required: [],
+  },
+
+  async handler({ service } = {}, serverRoot) {
+    if (!serverRoot) return 'Not in a Shiva project directory.';
+
+    const modules  = scanModules(getResourcesDir(serverRoot));
+    const services = {};
+
+    for (const mod of modules) {
+      const luaFiles = collectLuaFiles(path.join(mod.path, 'server')).concat(
+        collectLuaFiles(path.join(mod.path, 'shared'))
+      );
+
+      for (const file of luaFiles) {
+        const content = fs.readFileSync(file, 'utf-8');
+
+        // Pattern 1: Container.register('ServiceName', { method = function ... })
+        const regRe = /Container\.register\s*\(\s*['"]([^'"]+)['"]/g;
+        let m;
+        while ((m = regRe.exec(content)) !== null) {
+          const svcName = m[1];
+          if (!services[svcName]) services[svcName] = { module: mod.name, methods: [] };
+        }
+
+        // Pattern 2: ServiceName.methodName = function(...) or function ServiceName.methodName(...)
+        const methodRe = /(?:^|\n)\s*(?:function\s+(\w+)\.(\w+)\s*\(|(\w+)\.(\w+)\s*=\s*function\s*\()/g;
+        while ((m = methodRe.exec(content)) !== null) {
+          const svcName    = m[1] || m[3];
+          const methodName = m[2] || m[4];
+          if (!svcName || methodName === 'new') continue;
+          if (service && svcName.toLowerCase() !== service.toLowerCase()) continue;
+          if (!services[svcName]) services[svcName] = { module: mod.name, methods: [] };
+          if (!services[svcName].methods.includes(methodName)) {
+            services[svcName].methods.push(methodName);
+          }
+        }
+      }
+    }
+
+    if (service) {
+      const key = Object.keys(services).find(k => k.toLowerCase() === service.toLowerCase());
+      return key ? { [key]: services[key] } : `Service not found: ${service}`;
+    }
+
+    if (Object.keys(services).length === 0) return 'No services found in installed modules.';
+    return services;
+  },
+};
+
+module.exports = [getItemDefinitions, getJobDefinitions, getAvailableCommands, getServiceMethods];

package/src/mcp/tools/modules.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { scanModules } = require('../../utils/lua-parser');
+const { getResourcesDir } = require('../../utils/server-root');
+
+module.exports = {
+  name: 'shiva:getInstalledModules',
+  description: 'List all installed Shiva modules with version, dependencies, and provided contracts',
+  inputSchema: { type: 'object', properties: {}, required: [] },
+
+  async handler(_, serverRoot) {
+    if (!serverRoot) return 'Not in a Shiva project directory.';
+    const modules = scanModules(getResourcesDir(serverRoot));
+    if (modules.length === 0) return 'No Shiva modules found in resources/[shiva]/';
+    return modules.map(m => ({
+      name:         m.name,
+      version:      m.manifest.version,
+      description:  m.manifest.description,
+      dependencies: m.manifest.dependencies || [],
+      provides:     m.manifest.provides || [],
+      events:       m.manifest.events || [],
+      migrations:   (m.manifest.migrations || []).length,
+    }));
+  },
+};

package/src/packages/lockfile.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+
+const LOCKFILE_NAME = 'shiva.lock';
+
+/**
+ * Read the lockfile from server root.
+ * @param {string} serverRoot
+ * @returns {object}
+ */
+function readLockfile(serverRoot) {
+  const p = path.join(serverRoot, LOCKFILE_NAME);
+  if (!fs.existsSync(p)) return { version: 1, modules: {} };
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); } catch { return { version: 1, modules: {} }; }
+}
+
+/**
+ * Write the lockfile.
+ * @param {string} serverRoot
+ * @param {object} data
+ */
+function writeLockfile(serverRoot, data) {
+  const p = path.join(serverRoot, LOCKFILE_NAME);
+  data.updatedAt = new Date().toISOString();
+  fs.writeFileSync(p, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Update a single module entry in the lockfile.
+ * @param {string} serverRoot
+ * @param {string} name
+ * @param {object} entry  { version, resolved, integrity? }
+ */
+function lockModule(serverRoot, name, entry) {
+  const lock = readLockfile(serverRoot);
+  lock.modules[name] = { ...entry, lockedAt: new Date().toISOString() };
+  writeLockfile(serverRoot, lock);
+}
+
+/**
+ * Remove a module from the lockfile.
+ * @param {string} serverRoot
+ * @param {string} name
+ */
+function unlockModule(serverRoot, name) {
+  const lock = readLockfile(serverRoot);
+  delete lock.modules[name];
+  writeLockfile(serverRoot, lock);
+}
+
+module.exports = { readLockfile, writeLockfile, lockModule, unlockModule };

package/src/packages/registry.js

@@ -0,0 +1,99 @@
+'use strict';
+
+const https = require('https');
+const http  = require('http');
+const path  = require('path');
+const fs    = require('fs');
+
+const DEFAULT_REGISTRY = 'https://registry.shiva.dev';
+
+/**
+ * Get registry URL from config or default.
+ * @param {object} config  shiva.json contents
+ * @returns {string}
+ */
+function getRegistryUrl(config) {
+  return (config && config.registry) || DEFAULT_REGISTRY;
+}
+
+/**
+ * Perform a simple GET request returning parsed JSON.
+ * @param {string} url
+ * @returns {Promise<object>}
+ */
+function fetchJson(url) {
+  return new Promise((resolve, reject) => {
+    const mod = url.startsWith('https') ? https : http;
+    mod.get(url, { headers: { 'User-Agent': 'shiva-cli/1.0', 'Accept': 'application/json' } }, (res) => {
+      let data = '';
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => {
+        if (res.statusCode >= 400) {
+          reject(new Error(`Registry returned ${res.statusCode} for ${url}`));
+          return;
+        }
+        try { resolve(JSON.parse(data)); } catch (e) { reject(new Error(`Invalid JSON from registry: ${e.message}`)); }
+      });
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Fetch available versions for a module from the registry.
+ * @param {string} registryUrl
+ * @param {string} name
+ * @returns {Promise<string[]>}
+ */
+async function fetchVersions(registryUrl, name) {
+  const data = await fetchJson(`${registryUrl}/modules/${encodeURIComponent(name)}`);
+  return data.versions || [];
+}
+
+/**
+ * Fetch module metadata (including deps) for a specific version.
+ * @param {string} registryUrl
+ * @param {string} name
+ * @param {string} version
+ * @returns {Promise<object>}  { name, version, dependencies, downloadUrl, integrity }
+ */
+async function fetchModuleMeta(registryUrl, name, version) {
+  return fetchJson(`${registryUrl}/modules/${encodeURIComponent(name)}/${encodeURIComponent(version)}`);
+}
+
+/**
+ * Download a module tarball and extract it to destDir.
+ * @param {string} downloadUrl
+ * @param {string} destDir
+ * @returns {Promise<void>}
+ */
+async function downloadModule(downloadUrl, destDir) {
+  const { pipeline } = require('stream/promises');
+  const zlib = require('zlib');
+
+  return new Promise((resolve, reject) => {
+    const mod = downloadUrl.startsWith('https') ? https : http;
+    mod.get(downloadUrl, async (res) => {
+      if (res.statusCode >= 400) {
+        reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+        return;
+      }
+      try {
+        fs.mkdirSync(destDir, { recursive: true });
+        try {
+          const tar = require('tar');
+          await pipeline(res, zlib.createGunzip(), tar.extract({ cwd: destDir, strip: 1 }));
+        } catch {
+          // Fallback: save raw bytes when tar is not available
+          const outPath = path.join(destDir, '_downloaded.tar.gz');
+          const out = fs.createWriteStream(outPath);
+          await pipeline(res, out);
+        }
+        resolve();
+      } catch (e) {
+        reject(e);
+      }
+    }).on('error', reject);
+  });
+}
+
+module.exports = { getRegistryUrl, fetchJson, fetchVersions, fetchModuleMeta, downloadModule };

package/src/packages/resolver.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const semver = require('semver');
+
+/**
+ * Check if a version satisfies a constraint.
+ * @param {string} version
+ * @param {string} constraint  e.g. "^1.0.0", "~1.2.0", ">=1.0.0 <2.0.0"
+ * @returns {boolean}
+ */
+function satisfies(version, constraint) {
+  if (!constraint || constraint === '*' || constraint === 'latest') return true;
+  if (constraint.startsWith('file:')) return true;
+  try {
+    return semver.satisfies(version, constraint);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Find the best matching version from a list given a constraint.
+ * @param {string[]} versions   Sorted list of available versions
+ * @param {string}  constraint
+ * @returns {string|null}
+ */
+function resolveVersion(versions, constraint) {
+  if (!constraint || constraint === 'latest') {
+    return versions[versions.length - 1] || null;
+  }
+  if (constraint.startsWith('file:')) return constraint;
+
+  const valid = versions
+    .filter(v => semver.valid(v) && semver.satisfies(v, constraint))
+    .sort(semver.compare);
+
+  return valid[valid.length - 1] || null;
+}
+
+/**
+ * Build a flat install plan by resolving transitive dependencies.
+ * @param {object} directDeps   { name: constraint }
+ * @param {Function} fetchVersions  async (name) => string[]
+ * @param {Function} fetchDeps      async (name, version) => { name: constraint }
+ * @returns {Promise<Map<string, string>>}  name → resolved version
+ */
+async function buildInstallPlan(directDeps, fetchVersions, fetchDeps) {
+  const plan    = new Map();
+  const queue   = Object.entries(directDeps);
+  const visited = new Set();
+
+  while (queue.length > 0) {
+    const [name, constraint] = queue.shift();
+
+    if (visited.has(name)) continue;
+    visited.add(name);
+
+    if (constraint.startsWith('file:')) {
+      plan.set(name, constraint);
+      continue;
+    }
+
+    const versions = await fetchVersions(name);
+    const resolved = resolveVersion(versions, constraint);
+
+    if (!resolved) {
+      throw new Error(`Cannot resolve ${name}@${constraint} — no matching version found.`);
+    }
+
+    plan.set(name, resolved);
+
+    const transitive = await fetchDeps(name, resolved);
+    for (const [depName, depConstraint] of Object.entries(transitive || {})) {
+      if (!visited.has(depName)) {
+        queue.push([depName, depConstraint]);
+      }
+    }
+  }
+
+  return plan;
+}
+
+module.exports = { satisfies, resolveVersion, buildInstallPlan };

package/src/utils/config-reader.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Read shiva.json from the given server root.
+ * @param {string} serverRoot
+ * @returns {object}
+ */
+function readShivaConfig(serverRoot) {
+  const configPath = path.join(serverRoot, 'shiva.json');
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`shiva.json not found at ${configPath}`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Failed to parse shiva.json: ${err.message}`);
+  }
+}
+
+/**
+ * Write shiva.json to the given server root.
+ * @param {string} serverRoot
+ * @param {object} config
+ */
+function writeShivaConfig(serverRoot, config) {
+  const configPath = path.join(serverRoot, 'shiva.json');
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Read shiva.lock from the given server root.
+ * @param {string} serverRoot
+ * @returns {object}
+ */
+function readLockfile(serverRoot) {
+  const lockPath = path.join(serverRoot, 'shiva.lock');
+  if (!fs.existsSync(lockPath)) {
+    return { version: 1, modules: {} };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+  } catch {
+    return { version: 1, modules: {} };
+  }
+}
+
+/**
+ * Write shiva.lock to the given server root.
+ * @param {string} serverRoot
+ * @param {object} lockData
+ */
+function writeLockfile(serverRoot, lockData) {
+  const lockPath = path.join(serverRoot, 'shiva.lock');
+  fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Get database connection config from shiva.json.
+ * @param {string} serverRoot
+ * @returns {object|null}
+ */
+function getDatabaseConfig(serverRoot) {
+  try {
+    const config = readShivaConfig(serverRoot);
+    return config.database || null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { readShivaConfig, writeShivaConfig, readLockfile, writeLockfile, getDatabaseConfig };