@memberjunction/cli 2.43.0 → 2.44.0

package/README.md

@@ -1,188 +1,237 @@
-MemberJunction CLI
-==================
-
-<!-- toc -->
-* [Usage](#usage)
-* [Commands](#commands)
-<!-- tocstop -->
-# Usage
-<!-- usage -->
-```sh-session
-$ npm install -g @memberjunction/cli
-$ mj COMMAND
-running command...
-$ mj (--version)
-@memberjunction/cli/2.43.0 linux-x64 node-v20.19.1
-$ mj --help [COMMAND]
-USAGE
-  $ mj COMMAND
-...
-```
-<!-- usagestop -->
-# Commands
-<!-- commands -->
-* [`mj bump`](#mj-bump)
-* [`mj clean`](#mj-clean)
-* [`mj codegen`](#mj-codegen)
-* [`mj help [COMMAND]`](#mj-help-command)
-* [`mj install`](#mj-install)
-* [`mj migrate`](#mj-migrate)
-* [`mj version`](#mj-version)
+# @memberjunction/cli
 
-## `mj bump`
+The official command-line interface (CLI) for MemberJunction, providing essential tools for installation, database management, code generation, and dependency management.
 
-Bumps MemberJunction dependency versions
+## Overview
 
-```
-USAGE
-  $ mj bump [-v] [-r] [-t <value>] [-q] [-d]
+The MemberJunction CLI (`mj`) is a comprehensive toolset designed to streamline the development and maintenance of MemberJunction applications. It handles everything from initial installation to ongoing database migrations and code generation.
 
-FLAGS
-  -d, --dry          Dry run, do not write changes to package.json files
-  -q, --quiet        Only output paths for updated packages
-  -r, --recursive    Bump version in current directory and all subdirectories
-  -t, --tag=<value>  Version tag to bump target for bump (e.g. v2.10.0), defaults to the CLI version
-  -v, --verbose      Enable additional logging
+## Installation
 
-DESCRIPTION
-  Bumps MemberJunction dependency versions
+### Global Installation (Recommended)
+```bash
+npm install -g @memberjunction/cli
+```
 
-EXAMPLES
-  Bump all @memberjunction/* dependencies in the current directory's package.json to the CLI version
+### Local Installation
+```bash
+npm install --save-dev @memberjunction/cli
+```
 
-    $ mj bump
+## Prerequisites
+
+- **Node.js**: Version 20.0.0 or higher
+- **SQL Server**: Access to a SQL Server instance for database operations
+- **Disk Space**: At least 2GB of free disk space for installation
+
+## Configuration
+
+The CLI uses a configuration file system powered by [cosmiconfig](https://github.com/davidtheclark/cosmiconfig). It searches for configuration in the following locations:
+
+- `.mjrc`
+- `.mjrc.json`
+- `.mjrc.yaml`
+- `.mjrc.yml`
+- `.mjrc.js`
+- `.mjrc.cjs`
+- `mj.config.js`
+- `mj.config.cjs`
+- `package.json` (in a `"mj"` property)
+
+### Configuration Schema
+
+```typescript
+interface MJConfig {
+  dbHost: string;              // Database server hostname (default: 'localhost')
+  dbDatabase: string;          // Database name
+  dbPort: number;              // Database port (default: 1433)
+  codeGenLogin: string;        // Database login for CodeGen operations
+  codeGenPassword: string;     // Database password for CodeGen operations
+  migrationsLocation?: string; // Location of migration files (default: 'filesystem:./migrations')
+  dbTrustServerCertificate?: boolean; // Trust server certificate (default: false)
+  coreSchema?: string;         // Core schema name (default: '__mj')
+  cleanDisabled?: boolean;     // Disable database cleaning (default: true)
+  mjRepoUrl?: string;          // MemberJunction repository URL
+}
+```
 
-  Preview all recursive packages bumps without writing any changes.
+### Example Configuration
+
+```javascript
+// mj.config.cjs
+module.exports = {
+  dbHost: 'localhost',
+  dbDatabase: 'MemberJunction',
+  dbPort: 1433,
+  codeGenLogin: 'sa',
+  codeGenPassword: 'YourPassword123!',
+  dbTrustServerCertificate: true,
+  coreSchema: '__mj'
+};
+```
 
-    $ mj bump -rdv
+## Commands
 
-  Recursively bump all @memberjunction/* dependencies in all packages to version v2.10.0 and output only the paths
-  containing the updated package.json files. Pipe the output to xargs to run npm install in each directory and update
-  the package-lock.json files as well.
+### `mj install`
 
-    $ mj bump -rqt v2.10.0 | xargs -n1 -I{} npm install --prefix {}
+Performs a complete installation of MemberJunction, including:
+- Database setup
+- Generated entities configuration
+- API server configuration
+- Explorer UI configuration
+
+```bash
+mj install [--verbose]
 ```
 
-_See code: [src/commands/bump/index.ts](https://github.com/MemberJunction/MJ/blob/v2.43.0/src/commands/bump/index.ts)_
+The install command will:
+1. Verify Node.js version and disk space requirements
+2. Check for required directories (GeneratedEntities, SQL Scripts, MJAPI, MJExplorer)
+3. Prompt for configuration values or read from `install.config.json`
+4. Create `.env` files with database and authentication settings
+5. Run npm installations and link packages
+6. Execute CodeGen to generate initial code
 
-## `mj clean`
+### `mj codegen`
 
-Resets the MemberJunction database to a pre-installation state
+Runs the MemberJunction code generation process to create TypeScript entities and metadata from your database schema.
 
+```bash
+mj codegen [--skipdb]
 ```
-USAGE
-  $ mj clean [-v]
 
-FLAGS
-  -v, --verbose  Enable additional logging
+Options:
+- `--skipdb`: Skip database migration before running code generation
+
+### `mj migrate`
 
-DESCRIPTION
-  Resets the MemberJunction database to a pre-installation state
+Applies database migrations to update your MemberJunction schema to the latest version.
 
-EXAMPLES
-  $ mj clean
+```bash
+mj migrate [--verbose] [--tag <version>]
 ```
 
-_See code: [src/commands/clean/index.ts](https://github.com/MemberJunction/MJ/blob/v2.43.0/src/commands/clean/index.ts)_
+Options:
+- `--verbose`: Enable detailed logging
+- `--tag <version>`: Specify a version tag for migrations (e.g., 'v2.10.0')
+
+### `mj bump`
 
-## `mj codegen`
+Updates all @memberjunction/* package dependencies to a specified version.
+
+```bash
+mj bump [--recursive] [--dry] [--quiet] [--tag <version>] [--verbose]
+```
 
-Run CodeGen to generate code and update metadata for MemberJunction
+Options:
+- `-r, --recursive`: Update dependencies in all subdirectories
+- `-d, --dry`: Preview changes without writing to files
+- `-q, --quiet`: Only output paths of updated packages
+- `-t, --tag <version>`: Target version (defaults to CLI version)
+- `-v, --verbose`: Enable detailed logging
 
+Example - Update all packages recursively and run npm install:
+```bash
+mj bump -rqt v2.10.0 | xargs -n1 -I{} npm install --prefix {}
 ```
-USAGE
-  $ mj codegen [--skipdb]
 
-FLAGS
-  --skipdb  Skip database migration
+### `mj clean`
 
-DESCRIPTION
-  Run CodeGen to generate code and update metadata for MemberJunction
+Resets the MemberJunction database to a pre-installation state. **Use with caution!**
 
-EXAMPLES
-  $ mj codegen
+```bash
+mj clean [--verbose]
 ```
 
-_See code: [src/commands/codegen/index.ts](https://github.com/MemberJunction/MJ/blob/v2.43.0/src/commands/codegen/index.ts)_
+Note: This command is disabled by default. Set `cleanDisabled: false` in your configuration to enable it.
 
-## `mj help [COMMAND]`
+### `mj help`
 
-Display help for mj.
+Display help information for any command.
 
+```bash
+mj help [COMMAND]
 ```
-USAGE
-  $ mj help [COMMAND...] [-n]
 
-ARGUMENTS
-  COMMAND...  Command to show help for.
+### `mj version`
 
-FLAGS
-  -n, --nested-commands  Include all nested commands in the output.
+Display the CLI version and additional system information.
 
-DESCRIPTION
-  Display help for mj.
+```bash
+mj version [--verbose] [--json]
 ```
 
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.3/src/commands/help.ts)_
+## Environment Variables
 
-## `mj install`
+The CLI respects the following environment variables:
 
-Install MemberJunction
+- Standard Node.js environment variables
+- Database connection variables set in `.env` files
+- Authentication provider settings (MSAL, Auth0)
 
-```
-USAGE
-  $ mj install [-v]
+## Integration with MemberJunction Packages
 
-FLAGS
-  -v, --verbose  Enable additional logging
+The CLI integrates seamlessly with other MemberJunction packages:
 
-DESCRIPTION
-  Install MemberJunction
+- **@memberjunction/codegen-lib**: Powers the code generation functionality
+- **Generated Entities**: Automatically linked during installation
+- **MJAPI**: Configured and linked during installation
+- **MJExplorer**: UI configuration handled during installation
 
-EXAMPLES
-  $ mj install
-```
+## Hooks
+
+The CLI implements the following hooks:
 
-_See code: [src/commands/install/index.ts](https://github.com/MemberJunction/MJ/blob/v2.43.0/src/commands/install/index.ts)_
+- **prerun**: Displays the MemberJunction ASCII banner and version information
 
-## `mj migrate`
+## Development
 
-Migrate MemberJunction database to latest version
+### Building from Source
 
+```bash
+npm run build
 ```
-USAGE
-  $ mj migrate [-v] [-t <value>]
 
-FLAGS
-  -t, --tag=<value>  Version tag to use for running remote migrations
-  -v, --verbose      Enable additional logging
+### Scripts
 
-DESCRIPTION
-  Migrate MemberJunction database to latest version
+- `build`: Compile TypeScript to JavaScript
+- `prepack`: Build and generate oclif manifest
+- `postpack`: Clean up generated files
 
-EXAMPLES
-  $ mj migrate
-```
+## Technical Details
 
-_See code: [src/commands/migrate/index.ts](https://github.com/MemberJunction/MJ/blob/v2.43.0/src/commands/migrate/index.ts)_
+- Built with [oclif](https://oclif.io/) framework
+- Uses TypeScript for type safety
+- Implements Flyway for database migrations
+- Supports both global and project-specific configurations
+- Includes comprehensive error handling and validation
 
-## `mj version`
+## Troubleshooting
 
-```
-USAGE
-  $ mj version [--json] [--verbose]
+### Common Issues
 
-FLAGS
-  --verbose  Show additional information about the CLI.
+1. **Node Version Error**: Ensure you're using Node.js 20 or higher
+2. **Database Connection**: Verify your database credentials and network access
+3. **Disk Space**: The installation requires at least 2GB of free space
+4. **Configuration Not Found**: Check that your config file is in a supported location
 
-GLOBAL FLAGS
-  --json  Format output as json.
+### Debug Mode
 
-FLAG DESCRIPTIONS
-  --verbose  Show additional information about the CLI.
+Run any command with the `--verbose` flag for detailed logging:
 
-    Additionally shows the architecture, node version, operating system, and versions of plugins that the CLI is using.
+```bash
+mj install --verbose
+mj codegen --verbose
 ```
 
-_See code: [@oclif/plugin-version](https://github.com/oclif/plugin-version/blob/v2.2.4/src/commands/version.ts)_
-<!-- commandsstop -->
+## License
+
+ISC License - see the [LICENSE](https://github.com/MemberJunction/MJ/blob/main/LICENSE) file for details.
+
+## Repository
+
+[https://github.com/MemberJunction/MJ](https://github.com/MemberJunction/MJ)
+
+## Support
+
+For issues and feature requests, please visit the [GitHub Issues](https://github.com/MemberJunction/MJ/issues) page.

package/oclif.manifest.json

@@ -208,5 +208,5 @@
       ]
     }
   },
-  "version": "2.43.0"
+  "version": "2.44.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/cli",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "MemberJunction command line tools",
   "keywords": [
     "oclif"
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^5.0.1",
-    "@memberjunction/codegen-lib": "2.43.0",
+    "@memberjunction/codegen-lib": "2.44.0",
     "@oclif/core": "^3",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-version": "^2.0.17",