npm package: @processmagic/pm
Description: A powerful project configuration management CLI that seamlessly integrates with your development workflow
Author: Process Magic LTD
Latest version: 3.0.0

# @processmagic/pm

[![npm version](https://img.shields.io/npm/v/@processmagic/pm.svg)](https://www.npmjs.com/package/@processmagic/pm)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful project configuration management CLI that seamlessly integrates with your development workflow. Track project metadata, user associations, and machine-specific configurations with zero friction.

## 🚀 Quick Start

```bash
# Install globally
npm install -g @processmagic/pm

# Initialize in your project
cd your-project
pm install
```

## 🎯 Why Process Magic PM?

- **Zero Configuration** - Automatically detects Git and package.json information
- **Project-Scoped** - Each project maintains its own isolated configuration
- **Developer-Friendly** - Simple commands, clear output, no learning curve
- **Secure by Design** - Configurations are automatically gitignored
- **Multi-Format Support** - Access your config as .env variables or JSON
- **Cross-Platform** - Works on Windows, macOS, and Linux

## 📦 Installation

### Global Installation (Recommended)

```bash
npm install -g @processmagic/pm
```

### Local Installation

```bash
# Add as a dev dependency
npm install --save-dev @processmagic/pm

# Run with npx
npx pm install
```

## 🔧 Core Commands

```bash
pm install    # Initialize project configuration
pm show       # Display current configuration
pm update     # Update configuration (email, org ID, or refresh project info)
pm help       # Show available commands
pm --version  # Display version information
```

## 💡 How It Works

### Initialize (`pm install`)

1. **Auto-Detection** - Scans your project for:
   - Git repository information (remote URL, branch, latest commit)
   - Package.json metadata (name, version, dependencies)
   
2. **User Input** - Prompts for:
   - Email
   - Organization ID
   
3. **Auto-Generation**:
   - Unique machine ID (based on system hardware)
   - Installation timestamp
   
4. **File Creation**:
   ```
   your-project/
   └── .pm/
       ├── .env         # Environment variables
       └── config.json  # Full configuration object
   ```

### Configuration Storage

#### `.pm/.env`
```bash
PM_EMAIL=john@example.com
PM_ORG_ID=org123
PM_MACHINE_ID=a1b2c3d4e5f6g7h8
PM_PROJECT_NAME=my-app
PM_PROJECT_VERSION=1.0.0
PM_GIT_REPO=my-app
PM_GIT_OWNER=johndoe
PM_INSTALL_DATE=2025-08-06T12:00:00.000Z
```

#### `.pm/config.json`
```json
{
  "email": "john@example.com",
  "orgId": "org123",
  "machineId": "a1b2c3d4e5f6g7h8",
  "installDate": "2025-08-06T12:00:00.000Z",
  "project": {
    "name": "my-app",
    "version": "1.0.0",
    "dependencies": 5,
    "devDependencies": 3,
    "git": {
      "owner": "johndoe",
      "repo": "my-app",
      "branch": "main",
      "lastCommit": "a1b2c3d4"
    }
  }
}
```

## 📸 Example Workflow

### Initial Setup
```bash
$ cd my-awesome-project
$ pm install

=== PM Project Setup ===

Detected Project Information:
──────────────────────────────────────────────────
Project Name:     my-awesome-project
Version:          2.1.0
Description:      A revolutionary app
Author:           Jane Developer
License:          MIT
Dependencies:     12
Dev Dependencies: 8

Git Repository Information:
Repository:       jane-dev/my-awesome-project
Remote URL:       https://github.com/jane-dev/my-awesome-project.git
Current Branch:   feature/new-ui
Latest Commit:    f3a4b5c6
──────────────────────────────────────────────────

Enter your email: jane@example.com
Enter your organization ID: tech-corp

Machine ID: 7f3d9e2a1b4c8d6e

✓ Configuration saved to .pm/.env
✓ Configuration also saved to .pm/config.json
✓ Added .pm/ to .gitignore
✓ PM installation completed successfully!
```

### View Configuration
```bash
$ pm show

=== PM Project Configuration ===

User Configuration:
──────────────────────────────────────────────────
Email:            jane@example.com
Organization ID:  tech-corp
Machine ID:       7f3d9e2a1b4c8d6e
Install Date:     8/6/2025, 2:30:00 PM

Project Information:
──────────────────────────────────────────────────
Project Name:     my-awesome-project
Version:          2.1.0
...
```

### Update Configuration
```bash
$ pm update

What would you like to update? (email/orgid/refresh/all/cancel): refresh
Refreshing project information...
✓ Configuration updated successfully!
```

## 🛡️ Security & Privacy

- **Local Storage Only** - All configurations are stored locally in your project
- **Auto-Gitignore** - The `.pm/` directory is automatically added to `.gitignore`
- **No Network Calls** - PM operates entirely offline
- **No Telemetry** - We don't collect any usage data

## 🔍 Use Cases

### Development Teams
- Track which developer worked on which project
- Maintain consistent project metadata across team members
- Easily identify machine-specific configurations

### CI/CD Integration
- Use `.pm/.env` variables in your build scripts
- Track deployment environments
- Maintain project metadata through the pipeline

### Multi-Machine Development
- Work on the same project from different machines
- Track machine-specific configurations
- Maintain user identity across workstations

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/processmagic/pm-cli/blob/main/CONTRIBUTING.md) for details.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/processmagic/pm-cli.git
cd pm-cli

# Install dependencies
npm install

# Link for local development
npm link

# Run tests
npm test
```

## 📝 License

MIT © [Process Magic LTD](https://processmagic.com)

## 🔗 Links

- [GitHub Repository](https://github.com/processmagic/pm-cli)
- [NPM Package](https://www.npmjs.com/package/@processmagic/pm)
- [Report Issues](https://github.com/processmagic/pm-cli/issues)
- [Process Magic](https://processmagic.com)

## 🏷️ Keywords

`cli` `project-management` `configuration` `git` `developer-tools` `devops` `nodejs` `npm`