@shiva-fw/cli 1.0.0

package/src/commands/docs/api.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const fs    = require('fs');
+const path  = require('path');
+const chalk = require('chalk');
+
+const { findServerRoot, getResourcesDir } = require('../../utils/server-root');
+const { scanModules }                     = require('../../utils/lua-parser');
+const { scanModuleAnnotations, toMarkdown } = require('../../utils/lua-annotations');
+
+function docsApiCommand(program) {
+  program
+    .command('docs:api')
+    .description('Generate API reference from LuaLS annotations')
+    .option('-m, --module <name>', 'Generate for a specific module only')
+    .option('-o, --out <dir>',     'Output directory (default: ./docs/api)')
+    .action(async (options) => { await run(options); });
+}
+
+async function run(options) {
+  const serverRoot = findServerRoot(process.cwd());
+  if (!serverRoot) {
+    console.error(chalk.red('✖ Not in a Shiva server project. Run shiva init first.'));
+    process.exit(1);
+  }
+
+  let modules = scanModules(getResourcesDir(serverRoot));
+  if (options.module) {
+    const name = options.module.startsWith('shiva-') ? options.module : `shiva-${options.module}`;
+    modules    = modules.filter(m => m.name === name || m.name === options.module);
+    if (modules.length === 0) {
+      console.error(chalk.red(`✖ Module not found: ${options.module}`));
+      process.exit(1);
+    }
+  }
+
+  const outDir = options.out
+    ? path.resolve(options.out)
+    : path.join(serverRoot, 'docs', 'api');
+
+  fs.mkdirSync(outDir, { recursive: true });
+
+  console.log('');
+  console.log(chalk.bold(`Scanning ${modules.length} module(s) for LuaLS annotations...\n`));
+
+  let totalClasses = 0;
+  let totalFns     = 0;
+  let generated    = 0;
+
+  for (const mod of modules) {
+    const api = scanModuleAnnotations(mod.path);
+    if (api.classes.length === 0 && api.functions.length === 0) {
+      console.log(chalk.gray(`  ${mod.name}  — no annotations found, skipping`));
+      continue;
+    }
+
+    totalClasses += api.classes.length;
+    totalFns     += api.functions.length;
+
+    const markdown  = toMarkdown(mod.name, api);
+    const outFile   = path.join(outDir, `${mod.name}.md`);
+    fs.writeFileSync(outFile, markdown, 'utf-8');
+
+    console.log(
+      chalk.green(`  ✔ ${mod.name}`) +
+      chalk.gray(` — ${api.classes.length} classes, ${api.functions.length} functions → ${path.relative(serverRoot, outFile)}`)
+    );
+    generated++;
+  }
+
+  if (generated === 0) {
+    console.log(chalk.yellow('\n  No annotated modules found. Add ---@param / ---@return / ---@class to your Lua files.\n'));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold(`Generated ${generated} API doc file(s) in ${path.relative(process.cwd(), outDir)}/`));
+  console.log(chalk.gray(`  ${totalClasses} classes, ${totalFns} functions documented\n`));
+}
+
+module.exports = docsApiCommand;

package/src/commands/docs/build.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const chalk = require('chalk');
+
+function docsBuildCommand(program) {
+  program.command('docs:build').description('Build the VitePress documentation site').action(() => {
+    console.log('');
+    console.log(chalk.cyan('docs:build is managed in the shiva-docs repository.'));
+    console.log(chalk.gray('  cd shiva-docs && npm run build'));
+    console.log('');
+  });
+}
+
+module.exports = docsBuildCommand;

package/src/commands/docs/deploy.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const chalk = require('chalk');
+
+function docsDeployCommand(program) {
+  program.command('docs:deploy').description('Deploy documentation to hosting').action(() => {
+    console.log('');
+    console.log(chalk.cyan('docs:deploy is managed in the shiva-docs repository.'));
+    console.log(chalk.gray('  cd shiva-docs && npm run deploy'));
+    console.log('');
+  });
+}
+
+module.exports = docsDeployCommand;

package/src/commands/docs/serve.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const chalk = require('chalk');
+
+function docsServeCommand(program) {
+  program.command('docs:serve').description('Serve the documentation site locally').action(() => {
+    console.log('');
+    console.log(chalk.cyan('docs:serve is managed in the shiva-docs repository.'));
+    console.log(chalk.gray('  cd shiva-docs && npm run dev'));
+    console.log('');
+  });
+}
+
+module.exports = docsServeCommand;

package/src/commands/init.js

@@ -0,0 +1,167 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+
+const { writeShivaConfig } = require('../utils/config-reader');
+
+const RECIPES = {
+  minimal: require('../../recipes/minimal.json'),
+  standard: require('../../recipes/standard.json'),
+  'full-rp': require('../../recipes/full-rp.json'),
+};
+
+/**
+ * Register the `shiva init` command.
+ * @param {import('commander').Command} program
+ */
+function initCommand(program) {
+  program
+    .command('init')
+    .description('Initialise a new Shiva server project in the current directory')
+    .option('-r, --recipe <name>', 'Use a preset recipe (minimal | standard | full-rp)')
+    .option('-y, --yes', 'Skip prompts and use defaults')
+    .action(async (options) => {
+      await run(options);
+    });
+}
+
+async function run(options) {
+  const cwd = process.cwd();
+  const existingConfig = path.join(cwd, 'shiva.json');
+
+  if (fs.existsSync(existingConfig) && !options.yes) {
+    const { overwrite } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'overwrite',
+        message: chalk.yellow('shiva.json already exists. Overwrite?'),
+        default: false,
+      },
+    ]);
+    if (!overwrite) {
+      console.log(chalk.gray('Aborted.'));
+      return;
+    }
+  }
+
+  let answers;
+
+  if (options.yes) {
+    answers = {
+      serverName: path.basename(cwd),
+      recipe: options.recipe || 'minimal',
+      dbHost: '127.0.0.1',
+      dbPort: 3306,
+      dbUser: 'root',
+      dbPassword: '',
+      dbName: 'shiva',
+    };
+  } else {
+    answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'serverName',
+        message: 'Server name:',
+        default: path.basename(cwd),
+        validate: (v) => v.trim().length > 0 || 'Server name cannot be empty',
+      },
+      {
+        type: 'list',
+        name: 'recipe',
+        message: 'Choose a starter recipe:',
+        default: options.recipe || 'minimal',
+        choices: [
+          { name: 'minimal     — 24 essential modules', value: 'minimal' },
+          { name: 'standard    — 40 modules (recommended)', value: 'standard' },
+          { name: 'full-rp     — 71 modules, full RP experience', value: 'full-rp' },
+          { name: 'none        — start with no modules', value: 'none' },
+        ],
+      },
+      {
+        type: 'input',
+        name: 'dbHost',
+        message: 'Database host:',
+        default: '127.0.0.1',
+      },
+      {
+        type: 'number',
+        name: 'dbPort',
+        message: 'Database port:',
+        default: 3306,
+      },
+      {
+        type: 'input',
+        name: 'dbUser',
+        message: 'Database user:',
+        default: 'root',
+      },
+      {
+        type: 'password',
+        name: 'dbPassword',
+        message: 'Database password:',
+        mask: '*',
+      },
+      {
+        type: 'input',
+        name: 'dbName',
+        message: 'Database name:',
+        default: 'shiva',
+      },
+    ]);
+  }
+
+  const recipeModules =
+    answers.recipe !== 'none' && RECIPES[answers.recipe]
+      ? RECIPES[answers.recipe].modules
+      : {};
+
+  const config = {
+    name: answers.serverName,
+    framework: 'shiva-core@^1.0.0',
+    modules: recipeModules,
+    database: {
+      host: answers.dbHost,
+      port: Number(answers.dbPort),
+      user: answers.dbUser,
+      password: answers.dbPassword,
+      database: answers.dbName,
+    },
+  };
+
+  writeShivaConfig(cwd, config);
+
+  // Create resources/[shiva] directory structure
+  const shivaDir = path.join(cwd, 'resources', '[shiva]');
+  fs.mkdirSync(shivaDir, { recursive: true });
+
+  const lockData = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    modules: {},
+  };
+  fs.writeFileSync(path.join(cwd, 'shiva.lock'), JSON.stringify(lockData, null, 2) + '\n', 'utf-8');
+
+  console.log('');
+  console.log(chalk.green('✔ Created shiva.json'));
+  console.log(chalk.green('✔ Created shiva.lock'));
+  console.log(chalk.green('✔ Created resources/[shiva]/'));
+  console.log('');
+
+  if (answers.recipe !== 'none') {
+    const moduleCount = Object.keys(recipeModules).length;
+    console.log(chalk.cyan(`  Recipe: ${answers.recipe} (${moduleCount} modules)`));
+    console.log(chalk.gray('  Run `shiva install` to download and install the modules.'));
+  }
+
+  console.log('');
+  console.log(chalk.bold('Next steps:'));
+  console.log(chalk.gray('  shiva install        # Install modules from shiva.json'));
+  console.log(chalk.gray('  shiva migrate        # Run database migrations'));
+  console.log(chalk.gray('  shiva module:list    # List installed modules'));
+  console.log('');
+}
+
+module.exports = initCommand;

package/src/commands/install.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const path  = require('path');
+const fs    = require('fs');
+const chalk = require('chalk');
+
+const { requireServerRoot, getShivaModulesDir } = require('../utils/server-root');
+const { readShivaConfig, writeShivaConfig }      = require('../utils/config-reader');
+const { lockModule }                             = require('../packages/lockfile');
+const { buildInstallPlan }                       = require('../packages/resolver');
+const registry                                   = require('../packages/registry');
+
+function installCommand(program) {
+  program
+    .command('install [module]')
+    .description('Install a module (or all modules from shiva.json)')
+    .option('--no-lock', 'Skip updating shiva.lock')
+    .action(async (moduleName, options) => { await run(moduleName, options); });
+}
+
+async function run(moduleName, options) {
+  const serverRoot = requireServerRoot();
+  const config     = readShivaConfig(serverRoot);
+  const regUrl     = registry.getRegistryUrl(config);
+
+  let toInstall;
+
+  if (moduleName) {
+    const [name, version] = moduleName.split('@');
+    toInstall = { [name]: version ? version : 'latest' };
+  } else {
+    toInstall = config.modules || {};
+    if (Object.keys(toInstall).length === 0) {
+      console.log(chalk.gray('  No modules declared in shiva.json.'));
+      return;
+    }
+  }
+
+  console.log('');
+  console.log(chalk.bold('Resolving dependencies...'));
+
+  let plan;
+  try {
+    plan = await buildInstallPlan(
+      toInstall,
+      (name) => registry.fetchVersions(regUrl, name),
+      async (name, version) => {
+        const meta = await registry.fetchModuleMeta(regUrl, name, version);
+        return meta.dependencies || {};
+      }
+    );
+  } catch (err) {
+    console.error(chalk.red(`✖ Resolution failed: ${err.message}`));
+    console.error(chalk.gray('  Is the registry reachable? Check your network or set "registry" in shiva.json.'));
+    process.exit(1);
+  }
+
+  const modulesDir = getShivaModulesDir(serverRoot);
+  fs.mkdirSync(modulesDir, { recursive: true });
+
+  console.log('');
+  for (const [name, version] of plan.entries()) {
+    const destDir = path.join(modulesDir, name);
+
+    if (version.startsWith('file:')) {
+      const src = path.resolve(serverRoot, version.slice(5));
+      console.log(chalk.gray(`  Linking ${name} → ${src}`));
+      if (!fs.existsSync(destDir)) {
+        fs.symlinkSync(src, destDir, 'dir');
+      }
+      continue;
+    }
+
+    if (fs.existsSync(destDir)) {
+      console.log(chalk.gray(`  ${name}@${version} already installed, skipping`));
+      continue;
+    }
+
+    process.stdout.write(chalk.gray(`  Installing ${name}@${version} ...`));
+    try {
+      const meta = await registry.fetchModuleMeta(regUrl, name, version);
+      await registry.downloadModule(meta.downloadUrl, destDir);
+      if (options.lock !== false) {
+        lockModule(serverRoot, name, { version, resolved: meta.downloadUrl });
+      }
+      console.log(chalk.green(' done'));
+    } catch (err) {
+      console.log(chalk.red(' failed'));
+      console.error(chalk.red(`    ${err.message}`));
+    }
+  }
+
+  if (moduleName) {
+    const [name] = moduleName.split('@');
+    const resolved = plan.get(name);
+    if (resolved && !config.modules[name]) {
+      config.modules[name] = `^${resolved}`;
+      writeShivaConfig(serverRoot, config);
+      console.log(chalk.green(`\n✔ Added ${name}@^${resolved} to shiva.json`));
+    }
+  }
+
+  console.log('');
+  console.log(chalk.green(`✔ Done. ${plan.size} module(s) processed.`));
+  console.log('');
+}
+
+module.exports = installCommand;

package/src/commands/locale/missing.js

@@ -0,0 +1,83 @@
+'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 localeMissingCommand(program) {
+  program
+    .command('locale:missing')
+    .description('Find missing translation keys across module locales')
+    .option('-l, --lang <lang>', 'Language to check against en', 'all')
+    .action((options) => { run(options); });
+}
+
+function run(options) {
+  const serverRoot   = requireServerRoot();
+  const resourcesDir = getResourcesDir(serverRoot);
+  const modules      = scanModules(resourcesDir);
+
+  let totalMissing = 0;
+  console.log('');
+
+  for (const mod of modules) {
+    const localesDir = path.join(mod.path, 'locales');
+    if (!fs.existsSync(localesDir)) continue;
+
+    const localeFiles = fs.readdirSync(localesDir).filter(f => f.endsWith('.lua'));
+    if (localeFiles.length === 0) continue;
+
+    const enFile = path.join(localesDir, 'en.lua');
+    if (!fs.existsSync(enFile)) continue;
+
+    const enKeys = extractLocaleKeys(fs.readFileSync(enFile, 'utf-8'));
+    if (enKeys.size === 0) continue;
+
+    const otherFiles = localeFiles.filter(f => f !== 'en.lua');
+    if (otherFiles.length === 0) continue;
+
+    let modMissing = 0;
+    for (const file of otherFiles) {
+      const lang = file.replace('.lua', '');
+      if (options.lang !== 'all' && lang !== options.lang) continue;
+
+      const content = fs.readFileSync(path.join(localesDir, file), 'utf-8');
+      const keys    = extractLocaleKeys(content);
+      const missing = [...enKeys].filter(k => !keys.has(k));
+
+      if (missing.length > 0) {
+        if (modMissing === 0) {
+          console.log(chalk.bold.cyan(`  ${mod.name}`));
+        }
+        console.log(chalk.yellow(`    [${lang}] ${missing.length} missing key(s):`));
+        missing.forEach(k => console.log(chalk.gray(`      - ${k}`)));
+        modMissing += missing.length;
+        totalMissing += missing.length;
+      }
+    }
+  }
+
+  if (totalMissing === 0) {
+    console.log(chalk.green('✔ All locale keys are present across all modules.'));
+  } else {
+    console.log('');
+    console.log(chalk.yellow(`  ${totalMissing} missing key(s) found.`));
+    process.exit(1);
+  }
+  console.log('');
+}
+
+function extractLocaleKeys(content) {
+  const keys = new Set();
+  const re   = /\['([^']+)'\]\s*=/g;
+  let match;
+  while ((match = re.exec(content)) !== null) {
+    keys.add(match[1]);
+  }
+  return keys;
+}
+
+module.exports = localeMissingCommand;

package/src/commands/make/contract.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+
+const { requireServerRoot } = require('../../utils/server-root');
+const { writeTemplate, toPascalCase, toSnakeCase } = require('../../generators/index');
+
+function makeContractCommand(program) {
+  program
+    .command('make:contract <name>')
+    .description('Scaffold a new service contract')
+    .action((name) => { run(name); });
+}
+
+function run(rawName) {
+  const ContractName = toPascalCase(rawName);
+  const contractSlug = toSnakeCase(rawName).replace(/-/g, '_');
+  const moduleShort  = contractSlug;
+  const fileName     = `sh_${contractSlug}.lua`;
+
+  const serverRoot   = requireServerRoot();
+  const contractsDir = path.join(serverRoot, 'shared', 'contracts');
+  const destFile     = path.join(contractsDir, fileName);
+
+  if (fs.existsSync(destFile)) {
+    console.error(chalk.red(`✖ Contract already exists: ${destFile}`));
+    process.exit(1);
+  }
+
+  writeTemplate('contract.lua.tpl', destFile, {
+    ContractName,
+    module_short: moduleShort,
+  });
+
+  console.log('');
+  console.log(chalk.green(`✔ Created contract: ${chalk.bold(ContractName)}`));
+  console.log(chalk.gray(`  Path: ${path.relative(process.cwd(), destFile)}`));
+  console.log('');
+  console.log(chalk.gray('  Register it in your fxmanifest shared_scripts and module.lua provides.'));
+  console.log('');
+}
+
+module.exports = makeContractCommand;

package/src/commands/make/migration.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+
+const { requireServerRoot, getShivaModulesDir } = require('../../utils/server-root');
+const { writeTemplate, toSnakeCase, normalizeModuleName } = require('../../generators/index');
+
+/**
+ * Register the `shiva make:migration` command.
+ * @param {import('commander').Command} program
+ */
+function makeMigrationCommand(program) {
+  program
+    .command('make:migration <name>')
+    .description('Create a new database migration file inside a module')
+    .requiredOption('-m, --module <module>', 'Target module name')
+    .action((name, options) => {
+      run(name, options);
+    });
+}
+
+function run(rawName, options) {
+  const snakeName = toSnakeCase(rawName).replace(/-/g, '_');
+  const moduleName = normalizeModuleName(options.module);
+  const now = new Date();
+  const pad = n => String(n).padStart(2, '0');
+  const timestamp = `${now.getFullYear()}_${pad(now.getMonth() + 1)}_${pad(now.getDate())}_${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  const fileName = `${timestamp}_${snakeName}.lua`;
+  const migrationName = `${timestamp}_${snakeName}`;
+  const createdAt = new Date().toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC');
+
+  const serverRoot = requireServerRoot();
+  const modulesDir = getShivaModulesDir(serverRoot);
+  const moduleDir = path.join(modulesDir, moduleName);
+
+  if (!fs.existsSync(moduleDir)) {
+    console.error(chalk.red(`✖ Module not found: ${moduleName}`));
+    console.error(chalk.gray(`  Run \`shiva make:module ${moduleName}\` first.`));
+    process.exit(1);
+  }
+
+  const migrationsDir = path.join(moduleDir, 'migrations');
+  fs.mkdirSync(migrationsDir, { recursive: true });
+
+  const destFile = path.join(migrationsDir, fileName);
+
+  if (fs.existsSync(destFile)) {
+    console.error(chalk.red(`✖ Migration already exists: ${destFile}`));
+    process.exit(1);
+  }
+
+  const vars = {
+    migration_name: migrationName,
+    module_name: moduleName,
+    snake_name: snakeName,
+    created_at: createdAt,
+  };
+
+  writeTemplate('migration.lua.tpl', destFile, vars);
+
+  console.log('');
+  console.log(chalk.green(`✔ Created migration: ${chalk.bold(fileName)}`));
+  console.log(chalk.gray(`  Path: ${path.relative(process.cwd(), destFile)}`));
+  console.log('');
+}
+
+module.exports = makeMigrationCommand;

package/src/commands/make/model.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+
+const { requireServerRoot, getShivaModulesDir } = require('../../utils/server-root');
+const { writeTemplate, toPascalCase, toSnakeCase, normalizeModuleName } = require('../../generators/index');
+
+/**
+ * Register the `shiva make:model` command.
+ * @param {import('commander').Command} program
+ */
+function makeModelCommand(program) {
+  program
+    .command('make:model <name>')
+    .description('Scaffold a new model inside a module')
+    .requiredOption('-m, --module <module>', 'Target module name')
+    .option('-t, --table <table>', 'Override database table name')
+    .action((name, options) => {
+      run(name, options);
+    });
+}
+
+function run(rawName, options) {
+  const ModelName = toPascalCase(rawName);
+  const moduleName = normalizeModuleName(options.module);
+  const tableName = options.table || toSnakeCase(rawName) + 's';
+
+  const serverRoot = requireServerRoot();
+  const modulesDir = getShivaModulesDir(serverRoot);
+  const moduleDir = path.join(modulesDir, moduleName);
+
+  if (!fs.existsSync(moduleDir)) {
+    console.error(chalk.red(`✖ Module not found: ${moduleName}`));
+    console.error(chalk.gray(`  Run \`shiva make:module ${moduleName}\` first.`));
+    process.exit(1);
+  }
+
+  const destDir = path.join(moduleDir, 'server', 'models');
+  const destFile = path.join(destDir, `${ModelName}.lua`);
+
+  if (fs.existsSync(destFile)) {
+    console.error(chalk.red(`✖ Model already exists: ${destFile}`));
+    process.exit(1);
+  }
+
+  const vars = {
+    ModelName,
+    module_name: moduleName,
+    table_name: tableName,
+  };
+
+  writeTemplate('model.lua.tpl', destFile, vars);
+
+  console.log('');
+  console.log(chalk.green(`✔ Created model: ${chalk.bold(ModelName)}`));
+  console.log(chalk.gray(`  Table:  ${tableName}`));
+  console.log(chalk.gray(`  Path:   ${path.relative(process.cwd(), destFile)}`));
+  console.log('');
+}
+
+module.exports = makeModelCommand;