library.dr-conversion 0.2.9 → 0.3.1

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://badge.fury.io/js/library.dr-conversion.svg)](https://www.npmjs.com/package/library.dr-conversion)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Library.DR-Conversion** (v0.2.8) is a TypeScript library that provides a unified, platform-agnostic interface for building chat bots that work across multiple platforms like Discord, Root, and potentially others. Write your bot logic once, and deploy it anywhere!
+**Library.DR-Conversion** (v0.3.1) is a TypeScript library that provides a unified, platform-agnostic interface for building chat bots that work across multiple platforms like Discord, Root, and potentially others. Write your bot logic once, and deploy it anywhere!
 
 ## ✨ Features
 
@@ -79,6 +79,28 @@ npx library.dr-conversion init -p root-app -n my-root-app
 
 This creates a fully configured project with TypeScript, example code, and environment variables ready to go!
 
+**Generate Root Bot Manifest:**
+
+If you're building a Root bot, you'll need a `root-manifest.json` file:
+
+```bash
+# Quick generation with defaults
+npx library.dr-conversion generate-manifest
+# or simply
+npm run generate-manifest
+
+# Interactive mode with guided prompts
+npx library.dr-conversion generate-manifest -i
+```
+
+The generator will:
+- Create a proper UUID for your bot ID
+- Guide you through version and configuration options
+- Set up permissions for your bot
+- Generate a valid `root-manifest.json` file
+
+See the [Root Bot Manifest Guide](docs/ROOT_APP_MANIFEST.md) for details.
+
 ### Basic Usage
 
 ```typescript
@@ -273,11 +295,14 @@ await rootBot.connect();
 
 #### Building Root Apps with This Library
 
-**Prerequisites**: First install the Root client SDK:
+**Prerequisites**: 
 ```bash
+# Install the Root client SDK
 npm install @rootsdk/client-app
 ```
 
+**Note**: Root Apps (client-side) have different deployment requirements than Root Bots. They run in the Root client browser and don't require server-side manifest files. Configuration is done through the Root platform's app management interface.
+
 You can now create Root Apps (client-side) using the same unified interface:
 
 ```typescript
@@ -565,6 +590,7 @@ const client = new UnifiedClient({
 - 📗 **[API Reference](API.md)** - Detailed API documentation
 - 📙 **[Migration Guide](docs/MIGRATION.md)** - Upgrade and migration guides
 - 📕 **[Contributing Guide](CONTRIBUTING.md)** - How to contribute
+- 📋 **[Root Bot Manifest Guide](docs/ROOT_APP_MANIFEST.md)** - Creating root-manifest.json for Root Bots (server-side)
 
 ### Creating Rich Messages
 

package/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * CLI tool for Library.DR-Conversion
@@ -10,11 +10,96 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 const readline = require('readline');
+const crypto = require('crypto');
+
+// Generate a UUID v4
+function generateUUID() {
+  return crypto.randomUUID();
+}
+
+// Detect platform from package.json dependencies
+function detectPlatform() {
+  try {
+    const pkgPath = path.join(process.cwd(), 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      return null;
+    }
+    
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const allDeps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+      ...pkg.peerDependencies
+    };
+    
+    // Check for Root platforms
+    if (allDeps['@rootsdk/server-bot']) {
+      return 'root';
+    }
+    if (allDeps['@rootsdk/client-app']) {
+      return 'root-app';
+    }
+    if (allDeps['discord.js']) {
+      return 'discord';
+    }
+    
+    return null;
+  } catch (error) {
+    return null;
+  }
+}
+
+// Validate a root manifest object against minimal Root requirements
+function validateManifestObject(manifest) {
+  const errors = [];
+  if (!manifest || typeof manifest !== 'object') {
+    errors.push('Manifest must be a JSON object');
+    return { valid: false, errors };
+  }
+
+  if (!manifest.id || typeof manifest.id !== 'string') {
+    errors.push('Missing or invalid "id" (string)');
+  }
+
+  if (!manifest.version || typeof manifest.version !== 'string') {
+    errors.push('Missing or invalid "version" (string)');
+  }
+
+  if (!manifest.package || typeof manifest.package !== 'object') {
+    errors.push('Missing "package" object');
+  } else {
+    if (manifest.package.server) {
+      const server = manifest.package.server;
+      if (!server.launch || typeof server.launch !== 'string') {
+        errors.push('package.server.launch is required and must be a string');
+      }
+      if (!Array.isArray(server.deploy) || server.deploy.length === 0) {
+        errors.push('package.server.deploy must be a non-empty array');
+      }
+      if (!Array.isArray(server.node_modules) || server.node_modules.length === 0) {
+        errors.push('package.server.node_modules must be a non-empty array');
+      }
+    }
+
+    if (manifest.package.client) {
+      const client = manifest.package.client;
+      // accept either entry or deploy
+      if (!client.entry && (!Array.isArray(client.deploy) || client.deploy.length === 0)) {
+        errors.push('package.client.entry or package.client.deploy is required');
+      }
+      if (client.assets && !Array.isArray(client.assets)) {
+        errors.push('package.client.assets must be an array if provided');
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
 
 program
   .name('library.dr-conversion')
-  .description('CLI tools for Library.DR-Conversion v0.2.8')
-  .version('0.2.8');
+  .description('CLI tools for Library.DR-Conversion v0.2.9')
+  .version('0.2.9');
 
 program
   .command('init')
@@ -192,12 +277,128 @@ client.connect();
     
     fs.writeFileSync(path.join(projectDir, 'src', 'index.ts'), botCode);
     
+    // Create root-manifest.json for Root Bots
+    if (options.platform === 'root') {
+      const manifest = {
+        id: generateUUID(),
+        version: '1.0.0',
+        package: {
+          server: {
+            launch: 'dist/index.js',
+            deploy: ['dist'],
+            node_modules: ['node_modules']
+          }
+        },
+        settings: {
+          groups: []
+        },
+        permissions: {
+          community: {},
+          channel: {
+            CreateMessage: true,
+            ReadMessage: true
+          }
+        }
+      };
+      
+      fs.writeFileSync(
+        path.join(projectDir, 'root-manifest.json'),
+        JSON.stringify(manifest, null, 2)
+      );
+      
+      // Create README explaining manifest
+      const manifestReadme = `# Root Bot Manifest
+
+Your bot's root-manifest.json defines how it integrates with Root.
+
+## Important:
+- The 'id' field is unique to your bot - don't change it after publishing
+- Update 'version' following semantic versioning when you make changes
+- Add permissions your bot needs to 'permissions.community' or 'permissions.channel'
+- See docs/ROOT_BOT_MANIFEST.md for full documentation
+
+## Publishing:
+\`\`\`bash
+npm run build
+npx @rootsdk/cli publish
+\`\`\`
+`;
+      fs.writeFileSync(path.join(projectDir, 'MANIFEST.md'), manifestReadme);
+    }
+    
+    // Create root-app-manifest.json for Root Apps (client-side)
+    if (options.platform === 'root-app') {
+      const appManifest = {
+        id: generateUUID(),
+        version: '1.0.0',
+        name: options.name,
+        description: `${options.name} - Root App`,
+        author: '',
+        homepage: '',
+        package: {
+          client: {
+            entry: 'dist/index.html',
+            assets: ['dist'],
+            node_modules: ['node_modules']
+          }
+        },
+        settings: {
+          ui: []
+        },
+        permissions: {
+          channel: {
+            CreateMessage: true,
+            ReadMessage: true
+          }
+        }
+      };
+
+      fs.writeFileSync(
+        path.join(projectDir, 'root-manifest.json'),
+        JSON.stringify(appManifest, null, 2)
+      );
+
+      const appManifestReadme = `# Root App Manifest
+
+This project includes a generated root-manifest.json to help document your app.
+
+This manifest follows the Root App manifest overview and provides the basic fields used by the Root platform:
+- 'id': Unique UUID for the app
+- 'version': Semver version
+- 'package.client.entry': The client entry HTML for the app
+- 'package.client.assets': Client assets to include in the upload
+- 'permissions': Channel-level permissions used by the app
+
+Notes:
+- Update 'version' following semantic versioning when you make changes.
+- Review permissions and remove any that aren't needed.
+- Configure UI settings in the 'settings.ui' array (see Root docs for details):
+  https://docs.rootapp.com/docs/app-docs/configure/manifest-overview/
+
+Deployment:
+Build your app and follow the Root platform instructions to upload or register it.
+`;
+
+      fs.writeFileSync(path.join(projectDir, 'MANIFEST.md'), appManifestReadme);
+    }
+    
     console.log(`✅ Created ${options.name}`);
     console.log(`\n📝 Next steps:`);
     console.log(`  cd ${options.name}`);
     console.log(`  npm install`);
-    console.log(`  cp .env.example .env`);
-    console.log(`  # Edit .env with your bot token`);
+    
+    if (options.platform === 'root') {
+      console.log(`  cp .env.example .env`);
+      console.log(`  # Edit .env with your bot token`);
+      console.log(`  # Edit root-manifest.json - change the 'id' to a unique value`);
+      console.log(`  # See MANIFEST.md for manifest documentation`);
+    } else if (options.platform === 'discord') {
+      console.log(`  cp .env.example .env`);
+      console.log(`  # Edit .env with your bot token`);
+    } else if (options.platform === 'root-app') {
+      console.log(`  # Root Apps run in the Root client - no token needed`);
+      console.log(`  # Configure your app in the Root platform`);
+    }
     console.log(`  npm run dev`);
   });
 
@@ -226,6 +427,287 @@ program
     console.log('✅ Configuration is valid');
   });
 
+program
+  .command('validate-manifest')
+  .description('Validate root-manifest.json in the current folder')
+  .option('-f, --file <path>', 'Manifest file path', 'root-manifest.json')
+  .action((options) => {
+    const file = options.file || 'root-manifest.json';
+    if (!fs.existsSync(file)) {
+      console.error(`❌ Manifest not found: ${file}`);
+      process.exit(1);
+    }
+
+    let raw;
+    try {
+      raw = fs.readFileSync(file, 'utf8');
+    } catch (err) {
+      console.error('❌ Failed to read manifest:', err.message);
+      process.exit(1);
+    }
+
+    let manifest;
+    try {
+      manifest = JSON.parse(raw);
+    } catch (err) {
+      console.error('❌ Manifest is not valid JSON:', err.message);
+      process.exit(1);
+    }
+
+    const result = validateManifestObject(manifest);
+    if (!result.valid) {
+      console.error('❌ Manifest validation failed:');
+      for (const e of result.errors) console.error(' -', e);
+      process.exit(1);
+    }
+
+    console.log('✅ Manifest is valid');
+  });
+
+program
+  .command('generate-manifest')
+  .description('Generate a manifest file for Root Bots or Root Apps (auto-detects platform)')
+  .option('-i, --interactive', 'Interactive mode with prompts')
+  .option('-p, --platform <type>', 'Platform type (root, root-app) - auto-detected if not specified')
+  .action(async (options) => {
+    // Auto-detect platform if not specified
+    const platform = options.platform || detectPlatform();
+    
+    if (!platform || (platform !== 'root' && platform !== 'root-app')) {
+      console.error('❌ Could not detect Root platform.');
+      console.error('   Make sure you have @rootsdk/server-bot or @rootsdk/client-app installed,');
+      console.error('   or specify the platform: --platform root or --platform root-app');
+      process.exit(1);
+    }
+    
+    const isRootBot = platform === 'root';
+    const manifestFile = 'root-manifest.json';
+    
+    console.log(`\n🔍 Detected platform: ${isRootBot ? 'Root Bot (server-side)' : 'Root App (client-side)'}`);
+    
+    // Check if manifest already exists
+    if (fs.existsSync(manifestFile)) {
+      console.log(`⚠️  ${manifestFile} already exists in this directory.`);
+      if (!options.interactive) {
+        console.log('Use --interactive to configure a new one anyway.');
+        return;
+      }
+    }
+    
+    let manifest;
+    
+    if (isRootBot) {
+      // Root Bot manifest (server-side)
+      manifest = {
+        id: generateUUID(),
+        version: '1.0.0',
+        package: {
+          server: {
+            launch: 'dist/index.js',
+            deploy: ['dist'],
+            node_modules: ['node_modules']
+          }
+        },
+        settings: {
+          groups: []
+        },
+        permissions: {
+          community: {},
+          channel: {}
+        }
+      };
+    } else {
+      // Root App manifest (client-side)
+      manifest = {
+        id: generateUUID(),
+        version: '1.0.0',
+        name: '',
+        description: '',
+        author: '',
+        homepage: '',
+        package: {
+          client: {
+            entry: 'dist/index.html',
+            assets: ['dist'],
+            node_modules: ['node_modules']
+          }
+        },
+        settings: {
+          ui: []
+        },
+        permissions: {
+          channel: {}
+        }
+      };
+    }
+    
+    if (options.interactive) {
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+      
+      function question(prompt) {
+        return new Promise((resolve) => {
+          rl.question(prompt, resolve);
+        });
+      }
+      
+      console.log('\n╔════════════════════════════════════════════════════════╗');
+      console.log(`║   Root ${isRootBot ? 'Bot' : 'App'} Manifest Generator${' '.repeat(isRootBot ? 25 : 24)}║`);
+      console.log('╚════════════════════════════════════════════════════════╝\n');
+      
+      // Version
+      const version = await question('Version (default: 1.0.0): ');
+      if (version.trim()) manifest.version = version.trim();
+      
+      if (isRootBot) {
+        // Root Bot specific fields
+        // Launch file
+        const launch = await question('Launch file (default: dist/index.js): ');
+        if (launch.trim()) manifest.package.server.launch = launch.trim();
+        
+        // Permissions
+        console.log('\n📋 Bot Permissions:\n');
+        console.log('Community permissions:');
+      } else {
+        // Root App specific fields
+        const name = await question('App name: ');
+        if (name.trim()) manifest.name = name.trim();
+        
+        const description = await question('App description: ');
+        if (description.trim()) manifest.description = description.trim();
+        
+        const author = await question('Author: ');
+        if (author.trim()) manifest.author = author.trim();
+        
+        const homepage = await question('Homepage URL (optional): ');
+        if (homepage.trim()) manifest.homepage = homepage.trim();
+        
+        console.log('\n📋 App Permissions:\n');
+        console.log('Channel permissions (Root Apps run in browser):');
+      }
+      
+      if (isRootBot) {
+        // Community permissions only for Root Bots
+        console.log('Community permissions:');
+      const manageRoles = await question('  Need to manage roles? (y/n): ');
+      if (manageRoles.toLowerCase() === 'y') {
+        manifest.permissions.community.ManageRoles = true;
+      }
+      
+      const manageCommunity = await question('  Need to manage community settings? (y/n): ');
+      if (manageCommunity.toLowerCase() === 'y') {
+        manifest.permissions.community.ManageCommunity = true;
+      }
+      
+      const manageChannels = await question('  Need to manage channels? (y/n): ');
+      if (manageChannels.toLowerCase() === 'y') {
+        manifest.permissions.community.ManageChannels = true;
+      }
+      
+        console.log('\nChannel permissions:');
+      }
+      
+      // Channel permissions (both Root Bot and Root App)
+      const createMsg = await question('  Need to send messages? (y/n): ');
+      if (createMsg.toLowerCase() === 'y') {
+        manifest.permissions.channel.CreateMessage = true;
+      }
+      
+      const readMsg = await question('  Need to read messages? (y/n): ');
+      if (readMsg.toLowerCase() === 'y') {
+        manifest.permissions.channel.ReadMessage = true;
+      }
+      
+      const deleteMsg = await question('  Need to delete messages? (y/n): ');
+      if (deleteMsg.toLowerCase() === 'y') {
+        manifest.permissions.channel.DeleteMessage = true;
+      }
+      
+      const managePins = await question('  Need to manage pins? (y/n): ');
+      if (managePins.toLowerCase() === 'y') {
+        manifest.permissions.channel.ManagePins = true;
+      }
+      
+      rl.close();
+    }
+    
+    // Write manifest file
+    fs.writeFileSync(
+      manifestFile,
+      JSON.stringify(manifest, null, 2)
+    );
+    
+    console.log(`\n✅ Generated ${manifestFile} successfully!\n`);
+    console.log('📋 Manifest Details:');
+    console.log(`   Platform: ${isRootBot ? 'Root Bot (server-side)' : 'Root App (client-side)'}`);
+    console.log(`   ID: ${manifest.id}`);
+    console.log(`   Version: ${manifest.version}`);
+    if (isRootBot) {
+      console.log(`   Launch: ${manifest.package.server.launch}`);
+    } else {
+      console.log(`   Name: ${manifest.name || '(not set)'}`);
+    }
+    console.log('');
+    console.log('⚠️  Important:');
+    console.log('   - The ID is unique to your ' + (isRootBot ? 'bot' : 'app') + ' - never change it after publishing');
+    console.log('   - Update version when you make changes (follow semver)');
+    if (isRootBot) {
+      console.log('   - See docs/ROOT_APP_MANIFEST.md for full documentation');
+    }
+    console.log('');
+    console.log('📝 Next steps:');
+    console.log(`   1. Review and customize ${manifestFile}`);
+    if (isRootBot) {
+      console.log('   2. Build your bot: npm run build');
+      console.log('   3. Publish: npx @rootsdk/cli publish');
+    } else {
+      console.log('   2. Build your app: npm run build');
+      console.log('   3. Deploy through Root platform interface');
+    }
+    console.log('');
+  });
+
+program
+  .command('publish')
+  .description('Validate and publish the current root-manifest.json using @rootsdk/cli')
+  .option('-f, --file <path>', 'Manifest file to publish', 'root-manifest.json')
+  .option('--no-validate', 'Skip manifest validation step')
+  .action((options) => {
+    const file = options.file || 'root-manifest.json';
+    if (!fs.existsSync(file)) {
+      console.error(`❌ Manifest not found: ${file}`);
+      process.exit(1);
+    }
+
+    if (options.validate !== false) {
+      let manifest;
+      try {
+        manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+      } catch (err) {
+        console.error('❌ Failed to parse manifest:', err.message);
+        process.exit(1);
+      }
+
+      const result = validateManifestObject(manifest);
+      if (!result.valid) {
+        console.error('❌ Manifest validation failed:');
+        for (const e of result.errors) console.error(' -', e);
+        process.exit(1);
+      }
+      console.log('✅ Manifest validation passed');
+    }
+
+    try {
+      console.log('🔁 Running publish via @rootsdk/cli...');
+      execSync('npx @rootsdk/cli publish', { stdio: 'inherit' });
+    } catch (err) {
+      console.error('❌ Publish failed:', err.message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('setup')
   .description('Interactive setup wizard to install only the dependencies you need')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "library.dr-conversion",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "Unified interface for building multi-platform chat bots (Discord, Root, and more)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,6 +19,7 @@
     "typecheck": "tsc --noEmit",
     "dev": "tsc --watch",
     "setup": "node cli.js setup",
+    "generate-manifest": "node cli.js generate-manifest",
     "example:simple": "ts-node examples/simple-bot.ts",
     "example:discord": "ts-node examples/discord-bot.ts",
     "example:root": "ts-node examples/root-bot.ts",