electerm-data-tool 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 electerm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# Electerm Data Tool
+
+A command-line utility for managing Electerm application data, including database migration from v1 (NeDB) to v2 (SQLite) and data export functionality.
+
+## Features
+
+- 🔄 **Database Migration**: Migrate Electerm data from v1 (NeDB) to v2 (SQLite)
+- 📤 **Data Export**: Export all Electerm data to a single JSON file with decrypted passwords
+- 📊 **Database Info**: Display information about your current Electerm database
+- 🔐 **Password Decryption**: Automatically decrypt passwords during export for readable backups
+
+## Installation
+
+### Quick Start with npx (Recommended)
+
+No installation required! Run the tool directly using `npx`:
+
+```bash
+npx electerm-data-tool migrate
+npx electerm-data-tool export ~/backup.json
+npx electerm-data-tool info
+```
+
+### Global Installation
+
+```bash
+npm install -g electerm-data-tool
+```
+
+## Usage
+
+### Command Overview
+
+**Using npx (no installation required):**
+```bash
+npx electerm-data-tool [command] [options]
+```
+
+**Using globally installed version:**
+```bash
+electerm-data-tool [command] [options]
+```
+
+Available commands:
+
+- `migrate` - Migrate database from v1 to v2
+- `export <path>` - Export all data to JSON file  
+- `info` - Display database information
+- `--help` - Show help information
+- `--version` - Show version number
+
+### 1. Database Migration
+
+Migrate your Electerm database from v1 (NeDB) to v2 (SQLite):
+
+```bash
+electerm-data-tool migrate
+```
+
+This command will:
+- Check if migration is needed
+- Migrate all data from NeDB files to SQLite database
+- Create backups of original NeDB files with timestamp
+- Perform any necessary data upgrades
+
+**Note**: Requires Node.js 22.0.0 or higher for SQLite support.
+
+### 2. Data Export
+
+Export all Electerm data to a JSON file with decrypted passwords:
+
+```bash
+electerm-data-tool export /path/to/backup.json
+```
+
+Example:
+```bash
+electerm-data-tool export ~/electerm-backup-2025-09-03.json
+```
+
+The exported JSON will contain:
+- All bookmarks with decrypted passwords
+- Bookmark groups and folder structure
+- Terminal themes
+- Quick commands
+- Profiles
+- Configuration settings
+- And all other Electerm data
+
+**Important**: The exported file contains plain-text passwords. Store it securely and delete when no longer needed.
+
+### 3. Database Information
+
+View information about your current Electerm database:
+
+```bash
+electerm-data-tool info
+```
+
+This will show:
+- Database type (v1 NeDB or v2 SQLite)
+- Number of records in each table
+- Migration recommendations if applicable
+
+## Database Detection
+
+The tool automatically detects whether you're using:
+
+- **v1 Database (NeDB)**: Original file-based database format
+- **v2 Database (SQLite)**: New SQLite-based format (Node.js 22+ required)
+
+When exporting data:
+- If v1 database is detected, uses NeDB module for data access
+- If v2 database is detected, uses SQLite module for data access
+- Passwords are automatically decrypted in both cases
+
+## Data Structure
+
+### Export Format
+
+The exported JSON follows this structure:
+
+```json
+{
+  "bookmarks": [...],
+  "bookmarkGroups": [...],
+  "terminalThemes": [...],
+  "quickCommands": [...],
+  "profiles": [...],
+  "config": {...},
+  "addressBookmarks": [...],
+  "lastStates": [...],
+  "data": [...],
+  "log": [...],
+  "dbUpgradeLog": [...]
+}
+```
+
+### Password Handling
+
+- Passwords stored in Electerm are encrypted using a simple character-based encryption
+- During export, passwords are automatically decrypted to plain text
+- The `passwordEncrypted` flag is removed from exported data
+- Exported passwords are human-readable for backup purposes
+
+## Requirements
+
+- **Node.js**: 16.0.0 or higher
+- **For SQLite (v2)**: Node.js 22.0.0 or higher
+- **Dependencies**: 
+  - `commander` - CLI framework
+  - `@yetzt/nedb` - NeDB database support
+  - `nanoid` - ID generation
+
+## File Locations
+
+The tool operates on Electerm data stored in the standard locations:
+
+**Database Files:**
+- NeDB (v1): `~/.electerm/users/{username}/electerm.{table}.nedb`
+- SQLite (v2): `~/.electerm/users/{username}/electerm.db`
+
+**Backup Files:**
+During migration, original NeDB files are renamed with timestamp:
+- `electerm.bookmarks.nedb-{timestamp}.bak`
+
+## Examples
+
+### Complete Migration Workflow
+
+**Using npx (recommended):**
+```bash
+# 1. Check current database status
+npx electerm-data-tool info
+
+# 2. Export current data as backup
+npx electerm-data-tool export ~/electerm-backup-before-migration.json
+
+# 3. Perform migration
+npx electerm-data-tool migrate
+
+# 4. Verify migration succeeded
+npx electerm-data-tool info
+
+# 5. Export migrated data to verify
+npx electerm-data-tool export ~/electerm-backup-after-migration.json
+```
+
+**Using globally installed version:**
+```bash
+# 1. Check current database status
+electerm-data-tool info
+
+# 2. Export current data as backup
+electerm-data-tool export ~/electerm-backup-before-migration.json
+
+# 3. Perform migration
+electerm-data-tool migrate
+
+# 4. Verify migration succeeded
+electerm-data-tool info
+
+# 5. Export migrated data to verify
+electerm-data-tool export ~/electerm-backup-after-migration.json
+```
+
+### Using with npm scripts
+
+```bash
+# Quick migration
+npm run migrate
+
+# Quick export  
+npm run export ~/backup.json
+
+# Quick info
+npm run info
+```
+
+## Troubleshooting
+
+### Migration Issues
+
+**"Migration not needed"**: Your database is already v2 or no v1 files exist.
+
+**SQLite errors**: Ensure you're using Node.js 22.0.0 or higher.
+
+**Permission errors**: Ensure you have read/write access to Electerm data directory.
+
+### Export Issues
+
+**Empty export**: Check that Electerm has been run and contains data.
+
+**Encrypted passwords in export**: The tool should automatically decrypt passwords. If you see encrypted text, there may be an issue with the decryption module.
+
+### General Issues
+
+**Command not found**: If installed globally, ensure npm global bin directory is in your PATH.
+
+**Module errors**: Run `npm install` to ensure all dependencies are installed.
+
+## Security Considerations
+
+- **Exported files contain plain-text passwords** - store securely
+- **Delete export files** after use if they're temporary backups
+- **File permissions** - exported files inherit system default permissions
+- **Local processing only** - no data is transmitted over network
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Related Projects
+
+- [Electerm](https://github.com/electerm/electerm) - The main Electerm terminal application
+- [Electerm Documentation](https://electerm.html5beta.com/) - Official documentation
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "electerm-data-tool",
+  "version": "1.0.0",
+  "description": "electerm data export/migrate tool",
+  "main": "src/index.js",
+  "bin": {
+    "electerm-data-tool": "./src/index.js"
+  },
+  "scripts": {
+    "migrate": "node src/index.js migrate",
+    "export": "node src/index.js export",
+    "info": "node src/index.js info",
+    "update": "node -r dotenv/config bin/update-version.js",
+    "lint": "standard",
+    "fix": "standard --fix"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/electerm/electerm-data-tool.git"
+  },
+  "keywords": [
+    "electerm",
+    "data",
+    "tool",
+    "migrate",
+    "export"
+  ],
+  "author": "ZHAO Xudong <zxdong@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/electerm/electerm-data-tool/issues"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "homepage": "https://github.com/electerm/electerm-data-tool#readme",
+  "dependencies": {
+    "@yetzt/nedb": "^1.8.0",
+    "commander": "^14.0.0",
+    "lodash": "^4.17.21",
+    "nanoid": "^3.3.8"
+  },
+  "standard": {
+    "ignore": [
+      "*.html",
+      "/res/",
+      "/temp",
+      "/data",
+      "/public"
+    ],
+    "parserOptions": {
+      "requireConfigFile": false,
+      "sourceType": "module"
+    }
+  },
+  "devDependencies": {
+    "axios": "^1.11.0",
+    "dotenv": "^17.2.2",
+    "standard": "^17.1.2"
+  }
+}

package/src/common/app-props.js

@@ -0,0 +1,24 @@
+const path = require('path')
+const os = require('os')
+const version = '1.101.16'
+
+function getAppPath () {
+  const home = os.homedir()
+  const platform = process.platform
+  if (platform === 'darwin') {
+    // macOS
+    return path.join(home, 'Library', 'Application Support')
+  } else if (platform === 'win32') {
+    // Windows
+    return process.env.APPDATA || path.join(home, 'AppData', 'Roaming')
+  } else {
+    // Linux and others
+    return path.join(home, '.config')
+  }
+}
+
+exports.appPath = process.env.APP_PATH || getAppPath()
+exports.defaultUserName = 'default_user'
+exports.packInfo = {
+  version
+}

package/src/common/log.js

@@ -0,0 +1 @@
+module.exports = console

package/src/common/pass-enc.js

@@ -0,0 +1,53 @@
+/**
+ * Password encryption/decryption utilities
+ * Based on electerm's pass-enc.js
+ */
+
+const enc = (str) => {
+  if (typeof str !== 'string') {
+    return str
+  }
+  return str.split('').map((s, i) => {
+    return String.fromCharCode((s.charCodeAt(0) + i + 1) % 65536)
+  }).join('')
+}
+
+const dec = (str) => {
+  if (typeof str !== 'string') {
+    return str
+  }
+  return str.split('').map((s, i) => {
+    return String.fromCharCode((s.charCodeAt(0) - i - 1 + 65536) % 65536)
+  }).join('')
+}
+
+/**
+ * Decrypt password in an object
+ * @param {object} obj
+ */
+function decObj (obj) {
+  if (obj.passwordEncrypted && obj.password) {
+    obj.password = dec(obj.password)
+    delete obj.passwordEncrypted
+  }
+  return obj
+}
+
+/**
+ * Encrypt password in an object
+ * @param {object} obj
+ */
+function encObj (obj) {
+  if (!obj.passwordEncrypted && obj.password) {
+    obj.password = enc(obj.password)
+    obj.passwordEncrypted = true
+  }
+  return obj
+}
+
+module.exports = {
+  enc,
+  dec,
+  encObj,
+  decObj
+}

package/src/common/uid.js

@@ -0,0 +1,5 @@
+const { nanoid } = require('nanoid')
+
+module.exports = () => {
+  return nanoid(7)
+}

package/src/common/version-compare.js

@@ -0,0 +1,25 @@
+/**
+ * version compare
+ * @param {string} a
+ * @param {string} b
+ * @return {number}
+ */
+// compare version '1.0.0' '12.0.3'
+// return 1 when a > b
+// return -1 when a < b
+// return 0 when a === b
+module.exports = exports.default = function (a, b) {
+  const ar = a.split('.').map(n => Number(n.replace('v', '')))
+  const br = b.split('.').map(n => Number(n.replace('v', '')))
+  let res = 0
+  for (let i = 0, len = br.length; i < len; i++) {
+    if (br[i] < ar[i]) {
+      res = 1
+      break
+    } else if (br[i] > ar[i]) {
+      res = -1
+      break
+    }
+  }
+  return res
+}

package/src/index.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+
+/**
+ * Electerm Data Tool - Command Line Interface
+ * Provides tools to migrate and export electerm data
+ */
+
+const { Command } = require('commander')
+const { writeFileSync } = require('fs')
+const { resolve } = require('path')
+const { migrate } = require('./migrate/migrate-1-to-2')
+const log = require('./common/log')
+const pkg = require('../package.json')
+
+const program = new Command()
+
+/**
+ * Get the major version number from Node.js version string
+ * @returns {number} Major version number
+ */
+function getNodeMajorVersion () {
+  const nodeVersion = process.version
+  return parseInt(nodeVersion.slice(1).split('.')[0])
+}
+
+program
+  .name('electerm-data-tool')
+  .description('CLI tool for electerm data migration and export')
+  .version(pkg.version)
+
+/**
+ * Migration command - migrates from NeDB (v1) to SQLite (v2)
+ */
+program
+  .command('migrate')
+  .description('Migrate electerm database from v1 (NeDB) to v2 (SQLite)')
+  .action(async () => {
+    try {
+      // Check Node.js version requirement for SQLite
+      const majorVersion = getNodeMajorVersion()
+
+      if (majorVersion < 22) {
+        console.error('❌ Migration requires Node.js v22.0.0 or higher for SQLite support')
+        console.error(`   Current version: ${process.version}`)
+        console.error('   Please upgrade Node.js and try again.')
+        console.error('   You can still use the export function with your current Node.js version.')
+        process.exit(1)
+      }
+
+      log.info('Starting migration process...')
+      await migrate()
+      log.info('Migration completed successfully!')
+      console.log('✅ Migration from NeDB to SQLite completed successfully!')
+    } catch (error) {
+      log.error('Migration failed:', error)
+      console.error('❌ Migration failed:', error.message)
+      process.exit(1)
+    }
+  })
+
+/**
+ * Export command - exports all electerm data to a JSON file
+ */
+program
+  .command('export')
+  .description('Export all electerm data to a JSON file')
+  .argument('<output-path>', 'Path to the output JSON file')
+  .action(async (outputPath) => {
+    try {
+      log.info('Starting data export...')
+
+      // Check if migration is needed to determine which database to use
+      const { checkMigrate } = require('./migrate/migrate-1-to-2')
+      const shouldMigrate = checkMigrate()
+
+      let dbModule
+      let dbType
+
+      if (shouldMigrate) {
+        // v1 database (NeDB) detected
+        dbModule = require('./nedb')
+        dbType = 'NeDB (v1)'
+        log.info('Detected v1 database, using NeDB for export')
+      } else {
+        // v2 database (SQLite) or no data
+        try {
+          dbModule = require('./sqlite')
+          dbType = 'SQLite (v2)'
+          log.info('Using SQLite database for export')
+        } catch (error) {
+          log.error('Failed to load SQLite module:', error.message)
+          console.error('❌ Failed to load database module')
+          process.exit(1)
+        }
+      }
+
+      const { dbAction, tables } = dbModule
+      const exportData = {}
+
+      // Import password decryption utilities
+      const { decObj } = require('./common/pass-enc')
+
+      // Helper function to decrypt passwords in data objects
+      const decryptPasswords = (data) => {
+        if (Array.isArray(data)) {
+          return data.map(item => {
+            if (item && typeof item === 'object') {
+              return decObj({ ...item })
+            }
+            return item
+          })
+        }
+        return data
+      }
+
+      // Export all tables
+      for (const table of tables) {
+        try {
+          log.info(`Exporting table: ${table}`)
+          const data = await dbAction(table, 'find', {})
+
+          // Decrypt passwords in the data
+          const decryptedData = decryptPasswords(data)
+
+          exportData[table] = decryptedData || []
+          log.info(`Exported ${decryptedData?.length || 0} records from ${table}`)
+        } catch (error) {
+          log.warn(`Failed to export table ${table}:`, error.message)
+          exportData[table] = []
+        }
+      }
+
+      // Also try to export config if it exists in the data table
+      try {
+        const configData = await dbAction('data', 'findOne', { _id: 'config' })
+        if (configData && configData.value) {
+          exportData.config = configData.value
+          log.info('Exported config data')
+        }
+      } catch (error) {
+        log.warn('Failed to export config data:', error.message)
+      }
+
+      console.log(`📊 Database Type: ${dbType}`)
+
+      // Resolve the output path
+      const resolvedPath = resolve(process.cwd(), outputPath)
+
+      // Write the JSON file
+      const jsonString = JSON.stringify(exportData, null, 2)
+      writeFileSync(resolvedPath, jsonString, 'utf8')
+
+      const totalRecords = Object.values(exportData).reduce((sum, table) => {
+        return sum + (Array.isArray(table) ? table.length : 0)
+      }, 0)
+
+      log.info(`Export completed. ${totalRecords} total records exported to ${resolvedPath}`)
+      console.log('✅ Export completed successfully!')
+      console.log(`📄 ${totalRecords} total records exported to: ${resolvedPath}`)
+    } catch (error) {
+      log.error('Export failed:', error)
+      console.error('❌ Export failed:', error.message)
+      process.exit(1)
+    }
+  })
+
+/**
+ * Info command - displays information about the current electerm data
+ */
+program
+  .command('info')
+  .description('Display information about the current electerm data')
+  .action(async () => {
+    try {
+      // Check if migration is needed to determine which database to use
+      const { checkMigrate } = require('./migrate/migrate-1-to-2')
+      const shouldMigrate = checkMigrate()
+
+      let dbModule
+      let dbType
+
+      if (shouldMigrate) {
+        // v1 database (NeDB) detected
+        dbModule = require('./nedb')
+        dbType = 'NeDB (v1) - Migration recommended'
+
+        // Check Node.js version for migration capability
+        const majorVersion = getNodeMajorVersion()
+
+        console.log('⚠️  v1 database detected.')
+        if (majorVersion >= 22) {
+          console.log('   Run \'electerm-data-tool migrate\' to upgrade to v2')
+        } else {
+          console.log(`   Migration requires Node.js v22.0.0+ (current: ${process.version})`)
+          console.log('   Please upgrade Node.js to enable migration to v2')
+        }
+      } else {
+        // v2 database (SQLite) or no data
+        try {
+          dbModule = require('./sqlite')
+          dbType = 'SQLite (v2)'
+        } catch (error) {
+          console.error('❌ Failed to read database:', error.message)
+          process.exit(1)
+        }
+      }
+
+      const { dbAction, tables } = dbModule
+      console.log('📊 Electerm Data Information')
+      console.log(`Database Type: ${dbType}`)
+      console.log('='.repeat(40))
+
+      let totalRecords = 0
+      for (const table of tables) {
+        try {
+          const data = await dbAction(table, 'find', {})
+          const count = data?.length || 0
+          totalRecords += count
+          console.log(`${table.padEnd(20)}: ${count} records`)
+        } catch (error) {
+          console.log(`${table.padEnd(20)}: Error reading table`)
+        }
+      }
+
+      console.log('='.repeat(40))
+      console.log(`Total Records: ${totalRecords}`)
+    } catch (error) {
+      console.error('❌ Failed to read data:', error.message)
+      process.exit(1)
+    }
+  })
+
+// Parse command line arguments
+program.parse()