native-update 1.0.9 → 1.1.0

package/cli/index.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+/**
+ * Native Update CLI
+ * 
+ * Provides command-line tools for managing Capacitor Native Update plugin
+ * Can be used with npx, global install, or local install
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import fs from 'fs/promises';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packagePath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(await fs.readFile(packagePath, 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('native-update')
+  .description(`CLI tools for Capacitor Native Update plugin
+
+${chalk.bold('Quick Start:')}
+  ${chalk.gray('npx native-update init --example')}          # Initialize with examples
+  ${chalk.gray('npx native-update backend create express')}  # Create backend server
+  ${chalk.gray('npx native-update bundle create ./www')}     # Create update bundle
+
+${chalk.bold('Documentation:')}
+  ${chalk.blue('https://github.com/aoneahsan/native-update/blob/main/docs/cli-reference.md')}`)
+  .version(packageJson.version)
+  .configureHelp({
+    sortSubcommands: true,
+    subcommandTerm: (cmd) => cmd.name() + ' ' + cmd.aliases().join(', ')
+  });
+
+// Bundle Management Commands
+program
+  .command('bundle')
+  .description('Bundle management commands')
+  .command('create <webDir>')
+  .alias('create-bundle')
+  .description(`Create an update bundle from your web directory
+  
+${chalk.bold('Examples:')}
+  ${chalk.gray('# Create bundle from default build directory')}
+  ${chalk.green('npx native-update bundle create ./www')}
+  
+  ${chalk.gray('# Create with specific version and channel')}
+  ${chalk.green('npx native-update bundle create ./dist --version 1.2.0 --channel staging')}
+  
+  ${chalk.gray('# Add metadata like release notes')}
+  ${chalk.green(`npx native-update bundle create ./www --metadata '{"releaseNotes":"Bug fixes"}'`)}`)
+  .option('-o, --output <path>', 'Output directory for the bundle', './update-bundles')
+  .option('-v, --version <version>', 'Bundle version (defaults to package.json version)')
+  .option('-c, --channel <channel>', 'Release channel', 'production')
+  .option('-m, --metadata <json>', 'Additional metadata as JSON string')
+  .action(async (webDir, options) => {
+    const { createBundle } = await import('./commands/bundle-create.js');
+    await createBundle(webDir, options);
+  });
+
+program
+  .command('bundle')
+  .command('sign <bundlePath>')
+  .alias('sign-bundle')
+  .description(`Sign an update bundle with your private key
+  
+${chalk.bold('Examples:')}
+  ${chalk.gray('# Sign a bundle with your private key')}
+  ${chalk.green('npx native-update bundle sign ./bundle.zip --key ./keys/private.pem')}
+  
+  ${chalk.gray('# Specify output path for signed bundle')}
+  ${chalk.green('npx native-update bundle sign ./bundle.zip --key private.pem --output ./signed-bundle.zip')}`)
+  .requiredOption('-k, --key <path>', 'Path to private key file')
+  .option('-o, --output <path>', 'Output path for signed bundle')
+  .action(async (bundlePath, options) => {
+    const { signBundle } = await import('./commands/bundle-sign.js');
+    await signBundle(bundlePath, options);
+  });
+
+program
+  .command('bundle')
+  .command('verify <bundlePath>')
+  .alias('verify-bundle')
+  .description(`Verify a signed bundle with public key
+  
+${chalk.bold('Example:')}
+  ${chalk.green('npx native-update bundle verify ./signed-bundle.zip --key ./keys/public.pem')}`)
+  .requiredOption('-k, --key <path>', 'Path to public key file')
+  .action(async (bundlePath, options) => {
+    const { verifyBundle } = await import('./commands/bundle-verify.js');
+    await verifyBundle(bundlePath, options);
+  });
+
+// Key Management Commands
+program
+  .command('keys')
+  .description('Key management commands')
+  .command('generate')
+  .alias('generate-keys')
+  .description(`Generate a new key pair for bundle signing
+  
+${chalk.bold('Examples:')}
+  ${chalk.gray('# Generate default RSA 2048-bit keys')}
+  ${chalk.green('npx native-update keys generate')}
+  
+  ${chalk.gray('# Generate strong RSA 4096-bit keys for production')}
+  ${chalk.green('npx native-update keys generate --type rsa --size 4096')}
+  
+  ${chalk.gray('# Generate EC keys for smaller signatures')}
+  ${chalk.green('npx native-update keys generate --type ec --size 256 --output ./my-keys')}`)
+  .option('-o, --output <dir>', 'Output directory for keys', './keys')
+  .option('-t, --type <type>', 'Key type (rsa or ec)', 'rsa')
+  .option('-s, --size <size>', 'Key size (RSA: 2048/4096, EC: 256/384)', '2048')
+  .action(async (options) => {
+    const { generateKeys } = await import('./commands/keys-generate.js');
+    await generateKeys(options);
+  });
+
+// Server Commands
+program
+  .command('server')
+  .description('Development server commands')
+  .command('start')
+  .alias('start-server')
+  .description('Start a local update server for testing')
+  .option('-p, --port <port>', 'Server port', '3000')
+  .option('-d, --dir <dir>', 'Directory containing update bundles', './update-bundles')
+  .option('--cors', 'Enable CORS for testing', true)
+  .action(async (options) => {
+    const { startServer } = await import('./commands/server-start.js');
+    await startServer(options);
+  });
+
+// Init Commands
+program
+  .command('init')
+  .description(`Initialize native-update in your project
+  
+${chalk.bold('Examples:')}
+  ${chalk.gray('# Basic initialization')}
+  ${chalk.green('npx native-update init')}
+  
+  ${chalk.gray('# Initialize with example code and configuration')}
+  ${chalk.green('npx native-update init --example')}
+  
+  ${chalk.gray('# Initialize for Firebase backend')}
+  ${chalk.green('npx native-update init --backend firebase --example')}`)
+  .option('--example', 'Include example configuration')
+  .option('--backend <type>', 'Backend type (firebase, express, custom)', 'custom')
+  .action(async (options) => {
+    const { init } = await import('./commands/init.js');
+    await init(options);
+  });
+
+// Backend Commands
+program
+  .command('backend')
+  .description('Backend template commands')
+  .command('create <type>')
+  .alias('create-backend')
+  .description(`Create a backend template (express, firebase, vercel)
+  
+${chalk.bold('Examples:')}
+  ${chalk.gray('# Create Express.js backend with admin dashboard')}
+  ${chalk.green('npx native-update backend create express --with-admin')}
+  
+  ${chalk.gray('# Create Firebase Functions backend with monitoring')}
+  ${chalk.green('npx native-update backend create firebase --with-monitoring')}
+  
+  ${chalk.gray('# Create Vercel serverless backend')}
+  ${chalk.green('npx native-update backend create vercel --output my-backend')}`)
+  .option('-o, --output <dir>', 'Output directory', './native-update-backend')
+  .option('--with-monitoring', 'Include monitoring setup', false)
+  .option('--with-admin', 'Include admin dashboard', false)
+  .action(async (type, options) => {
+    const { createBackend } = await import('./commands/backend-create.js');
+    await createBackend(type, options);
+  });
+
+// Config Commands
+program
+  .command('config')
+  .description('Configuration commands')
+  .command('check')
+  .description('Validate your native-update configuration')
+  .action(async () => {
+    const { checkConfig } = await import('./commands/config-check.js');
+    await checkConfig();
+  });
+
+// Migration Commands
+program
+  .command('migrate')
+  .description('Migrate from other OTA solutions')
+  .option('--from <solution>', 'Source solution (codepush, appflow)', 'codepush')
+  .action(async (options) => {
+    const { migrate } = await import('./commands/migrate.js');
+    await migrate(options);
+  });
+
+// Monitoring Commands
+program
+  .command('monitor')
+  .description('Monitor update deployments')
+  .option('-s, --server <url>', 'Backend server URL')
+  .option('-k, --key <key>', 'API key for authentication')
+  .action(async (options) => {
+    const { monitor } = await import('./commands/monitor.js');
+    await monitor(options);
+  });
+
+// Add helpful examples
+program.on('--help', () => {
+  console.log('');
+  console.log('Examples:');
+  console.log('');
+  console.log('  Quick Start:');
+  console.log('    $ npx native-update init --example');
+  console.log('    $ npx native-update backend create express --with-admin');
+  console.log('');
+  console.log('  Bundle Management:');
+  console.log('    $ npx native-update bundle create ./www');
+  console.log('    $ npx native-update bundle sign ./bundle.zip --key ./keys/private.pem');
+  console.log('    $ npx native-update bundle verify ./bundle.zip --key ./keys/public.pem');
+  console.log('');
+  console.log('  Key Management:');
+  console.log('    $ npx native-update keys generate --type rsa --size 4096');
+  console.log('');
+  console.log('  Development:');
+  console.log('    $ npx native-update server start --port 3000');
+  console.log('    $ npx native-update monitor --server http://localhost:3000');
+  console.log('');
+  console.log('  Backend Templates:');
+  console.log('    $ npx native-update backend create express');
+  console.log('    $ npx native-update backend create firebase --with-monitoring');
+  console.log('    $ npx native-update backend create vercel --with-admin');
+  console.log('');
+  console.log(chalk.bold('Resources:'));
+  console.log('  Documentation: ' + chalk.blue('https://github.com/aoneahsan/native-update/blob/main/docs/'));
+  console.log('  CLI Reference: ' + chalk.blue('https://github.com/aoneahsan/native-update/blob/main/docs/cli-reference.md'));
+  console.log('  Quick Start:   ' + chalk.blue('https://github.com/aoneahsan/native-update/blob/main/docs/getting-started/quick-start.md'));
+  console.log('');
+  console.log(chalk.bold('Support:'));
+  console.log('  Issues:  ' + chalk.blue('https://github.com/aoneahsan/native-update/issues'));
+  console.log('  Author:  Ahsan Mahmood (' + chalk.blue('https://aoneahsan.com') + ')');
+  console.log('  Email:   ' + chalk.blue('aoneahsan@gmail.com'));
+});
+
+// Error handling
+program.exitOverride();
+
+try {
+  await program.parseAsync(process.argv);
+} catch (error) {
+  if (error.code === 'commander.missingArgument') {
+    console.error(chalk.red(`Error: ${error.message}`));
+  } else if (error.code === 'commander.unknownCommand') {
+    console.error(chalk.red(`Error: Unknown command`));
+    program.outputHelp();
+  } else {
+    console.error(chalk.red(`Error: ${error.message}`));
+  }
+  process.exit(1);
+}

package/cli/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "native-update-cli",
+  "version": "1.0.0",
+  "description": "CLI for Native Update",
+  "type": "module",
+  "bin": {
+    "cap-update": "./cap-update.js"
+  },
+  "dependencies": {
+    "commander": "^11.0.0"
+  }
+}

package/docs/BUNDLE_SIGNING.md

@@ -14,16 +14,23 @@ Bundle signing uses RSA-2048 with SHA-256 to create digital signatures that veri
 
 ### 1. Generate RSA Key Pair
 
+The easiest way is using our CLI tool:
+
 ```bash
-cd server-example
-node bundle-signer.js generate-keys
+# Generate strong RSA keys for production
+npx native-update keys generate --type rsa --size 4096
+
+# Or generate EC keys for smaller signatures
+npx native-update keys generate --type ec --size 256
 ```
 
 This creates:
 
-- `private.key` - Keep secure on your server
-- `public.key` - Include in your app
-- `public.key.b64` - Base64 version for app config
+- `private-{timestamp}.pem` - Keep secure on your server (NEVER commit to git!)
+- `public-{timestamp}.pem` - Include in your app
+- Proper file permissions (600) are set automatically
+
+For detailed key management instructions, see the [Key Management Guide](./guides/key-management.md).
 
 ### 2. Secure Private Key
 
@@ -55,7 +62,7 @@ const signature = signBundle(fileBuffer, privateKey);
 Sign bundles manually:
 
 ```bash
-node bundle-signer.js sign bundle-1.0.0.zip /secure/keys/private.key
+npx native-update bundle sign bundle-1.0.0.zip --key /secure/keys/private.key
 ```
 
 This creates `bundle-1.0.0.zip.sig` containing the base64 signature.
@@ -161,7 +168,7 @@ async function verifyBundle(
     PRIVATE_KEY: ${{ secrets.BUNDLE_SIGNING_KEY }}
   run: |
     echo "$PRIVATE_KEY" > private.key
-    node bundle-signer.js sign dist/bundle.zip
+    npx native-update bundle sign dist/bundle.zip --key private.key
     rm private.key
 ```
 
@@ -169,7 +176,7 @@ async function verifyBundle(
 
 ```groovy
 withCredentials([file(credentialsId: 'bundle-signing-key', variable: 'KEY_FILE')]) {
-    sh 'node bundle-signer.js sign dist/bundle.zip $KEY_FILE'
+    sh 'npx native-update bundle sign dist/bundle.zip --key $KEY_FILE'
 }
 ```
 
@@ -198,7 +205,7 @@ Test signature verification:
 
 ```bash
 # Verify manually
-node bundle-signer.js verify bundle.zip bundle.zip.sig public.key
+npx native-update bundle verify bundle.zip --key public.key
 
 # Check signature format
 cat bundle.zip.sig | base64 -d | xxd | head

package/docs/LIVE_UPDATES_GUIDE.md

@@ -397,7 +397,7 @@ zip -r ../bundle-1.0.1.zip www/
 
 # 3. Sign the bundle (optional but recommended)
 cd ..
-node server-example/bundle-signer.js sign bundle-1.0.1.zip
+npx native-update bundle sign bundle-1.0.1.zip --key private.key
 
 # 4. Upload to server
 curl -X POST https://updates.example.com/api/v1/bundles \

package/docs/README.md

@@ -33,6 +33,7 @@ Created by **Ahsan Mahmood** and open-sourced for the developer community, this
 ### Guides
 
 - [**Security Best Practices**](./guides/security-best-practices.md) - Implement secure updates
+- [**Key Management**](./guides/key-management.md) - Generate and manage signing keys
 - [**Migration from CodePush**](./guides/migration-from-codepush.md) - Migrate from CodePush
 - [**Testing Guide**](./guides/testing-guide.md) - Testing your update implementation
 - [**Deployment Guide**](./guides/deployment-guide.md) - Deploy to production

package/docs/cli-reference.md

@@ -0,0 +1,321 @@
+# CLI Reference
+
+The Native Update CLI provides comprehensive tools for managing your update workflow.
+
+## Installation
+
+The CLI is included with the native-update package. You can use it via npx without any additional installation:
+
+```bash
+# Use directly with npx (recommended)
+npx native-update <command>
+
+# Or install globally
+npm install -g native-update
+
+# Or use locally in your project
+npm install native-update
+npx native-update <command>
+```
+
+## Commands
+
+### Bundle Management
+
+#### `bundle create <webDir>`
+
+Creates an update bundle from your web build directory.
+
+```bash
+npx native-update bundle create ./www
+
+# Options:
+#   -o, --output <path>     Output directory (default: ./update-bundles)
+#   -v, --version <version> Bundle version (default: from package.json)
+#   -c, --channel <channel> Release channel (default: production)
+#   -m, --metadata <json>   Additional metadata as JSON string
+```
+
+**Example:**
+```bash
+npx native-update bundle create ./dist \
+  --version 1.2.0 \
+  --channel staging \
+  --metadata '{"releaseNotes":"Bug fixes"}'
+```
+
+#### `bundle sign <bundlePath>`
+
+Signs a bundle with your private key for security verification.
+
+```bash
+npx native-update bundle sign ./bundle.zip --key ./keys/private.pem
+
+# Options:
+#   -k, --key <path>    Path to private key file (required)
+#   -o, --output <path> Output path for signed bundle
+```
+
+#### `bundle verify <bundlePath>`
+
+Verifies a signed bundle with the public key.
+
+```bash
+npx native-update bundle verify ./bundle.zip --key ./keys/public.pem
+
+# Options:
+#   -k, --key <path> Path to public key file (required)
+```
+
+### Key Management
+
+#### `keys generate`
+
+Generates a new cryptographic key pair for bundle signing. This is the recommended way to create keys for the Native Update plugin.
+
+```bash
+npx native-update keys generate
+
+# Options:
+#   -o, --output <dir>  Output directory (default: ./keys)
+#   -t, --type <type>   Key type: rsa or ec (default: rsa)
+#   -s, --size <size>   Key size - RSA: 2048/4096, EC: 256/384 (default: 2048)
+```
+
+**What it creates:**
+- `private-{timestamp}.pem` - Private key for signing (keep SECRET on server)
+- `public-{timestamp}.pem` - Public key for verification (include in app)
+- Sets proper file permissions (600) on private key
+- Timestamps prevent accidental overwriting
+
+**Example:**
+```bash
+# Generate strong RSA keys for production (recommended)
+npx native-update keys generate --type rsa --size 4096
+
+# Generate EC keys for smaller signature size
+npx native-update keys generate --type ec --size 256
+
+# Generate in custom directory
+npx native-update keys generate --output ./my-keys --type rsa --size 4096
+```
+
+**Security Notes:**
+- NEVER commit private keys to version control
+- Store private keys in secure locations with restricted access
+- Use environment variables or key management services in production
+- See [Key Management Guide](./guides/key-management.md) for best practices
+
+### Backend Templates
+
+#### `backend create <type>`
+
+Creates a backend server template for hosting updates.
+
+```bash
+npx native-update backend create express
+
+# Types available:
+#   express  - Node.js Express server
+#   firebase - Firebase Functions
+#   vercel   - Vercel serverless functions
+
+# Options:
+#   -o, --output <dir>    Output directory (default: ./native-update-backend)
+#   --with-monitoring     Include monitoring setup
+#   --with-admin         Include admin dashboard
+```
+
+**Examples:**
+```bash
+# Express server with admin dashboard
+npx native-update backend create express --with-admin
+
+# Firebase Functions with monitoring
+npx native-update backend create firebase --with-monitoring
+
+# Vercel deployment ready backend
+npx native-update backend create vercel
+```
+
+### Development Tools
+
+#### `server start`
+
+Starts a local update server for development and testing.
+
+```bash
+npx native-update server start
+
+# Options:
+#   -p, --port <port> Server port (default: 3000)
+#   -d, --dir <dir>   Directory containing bundles (default: ./update-bundles)
+#   --cors            Enable CORS (default: true)
+```
+
+#### `init`
+
+Initializes Native Update configuration in your project.
+
+```bash
+npx native-update init
+
+# Options:
+#   --example              Include example code
+#   --backend <type>       Backend type: firebase, express, custom (default: custom)
+```
+
+### Monitoring
+
+#### `monitor`
+
+Monitors update deployment statistics in real-time.
+
+```bash
+npx native-update monitor --server https://your-update-server.com
+
+# Options:
+#   -s, --server <url> Backend server URL (required)
+#   -k, --key <key>    API key for authentication
+```
+
+### Configuration
+
+#### `config check`
+
+Validates your Native Update configuration.
+
+```bash
+npx native-update config check
+```
+
+### Migration
+
+#### `migrate`
+
+Helps migrate from other OTA solutions.
+
+```bash
+npx native-update migrate --from codepush
+
+# Options:
+#   --from <solution> Source solution: codepush, appflow (default: codepush)
+```
+
+## Complete Workflow Example
+
+Here's a typical workflow using the CLI:
+
+```bash
+# 1. Initialize in your project
+npx native-update init --example
+
+# 2. Generate signing keys
+npx native-update keys generate --type rsa --size 4096
+
+# 3. Create a backend
+npx native-update backend create express --with-admin
+
+# 4. Start the backend (in another terminal)
+cd native-update-backend
+npm install
+npm run dev
+
+# 5. Build your app
+npm run build
+
+# 6. Create and sign a bundle
+npx native-update bundle create ./www --version 1.0.1
+npx native-update bundle sign ./update-bundles/bundle-*.zip --key ./keys/private-*.pem
+
+# 7. Upload to your server (use the admin dashboard or API)
+
+# 8. Monitor deployments
+npx native-update monitor --server http://localhost:3000
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Create Update Bundle
+  run: |
+    npx native-update bundle create ./dist \
+      --version ${{ github.event.release.tag_name }}
+      --channel production
+
+- name: Sign Bundle
+  run: |
+    npx native-update bundle sign ./update-bundles/*.zip \
+      --key ${{ secrets.PRIVATE_KEY }}
+```
+
+### Jenkins
+
+```groovy
+stage('Create Update') {
+    steps {
+        sh 'npx native-update bundle create ./www --version ${BUILD_NUMBER}'
+        sh 'npx native-update bundle sign ./update-bundles/*.zip --key ${PRIVATE_KEY_PATH}'
+    }
+}
+```
+
+## Environment Variables
+
+The CLI respects these environment variables:
+
+- `NATIVE_UPDATE_SERVER` - Default server URL for commands
+- `NATIVE_UPDATE_API_KEY` - Default API key for authentication
+- `NATIVE_UPDATE_CHANNEL` - Default release channel
+- `NO_COLOR` - Disable colored output
+
+## Troubleshooting
+
+### "Command not found"
+
+Make sure you're using `npx` or have installed the package:
+```bash
+npx native-update <command>
+```
+
+### "EACCES: permission denied"
+
+Key files need proper permissions:
+```bash
+chmod 600 ./keys/private-*.pem
+```
+
+### Bundle creation fails
+
+Ensure your web directory contains built files:
+```bash
+# Build first
+npm run build
+
+# Then create bundle
+npx native-update bundle create ./www
+```
+
+## Best Practices
+
+1. **Security**
+   - Keep private keys secure and never commit them
+   - Use strong RSA 4096 keys for production
+   - Always sign bundles before deployment
+
+2. **Versioning**
+   - Use semantic versioning (1.0.0, 1.0.1, etc.)
+   - Increment versions for each update
+   - Use channels for staged rollouts
+
+3. **Testing**
+   - Test updates locally first using `server start`
+   - Verify bundles before deployment
+   - Use staging channel before production
+
+4. **Monitoring**
+   - Always monitor deployments
+   - Set up alerts for failed updates
+   - Track adoption rates

package/docs/getting-started/configuration.md

@@ -66,8 +66,9 @@ liveUpdate: {
   serverUrl: 'https://updates.yourserver.com',
   channel: 'production',
 
-  // Security
-  publicKey: 'YOUR_RSA_PUBLIC_KEY',
+  // Security (see Key Management Guide for generating keys)
+  // Generate keys: npx native-update keys generate --type rsa --size 4096
+  publicKey: 'YOUR_RSA_PUBLIC_KEY', // Base64 encoded public key
   requireSignature: true,
   checksumAlgorithm: 'SHA-256', // or 'SHA-512'