pax8-cta 0.1.0

package/README.md

@@ -0,0 +1,659 @@
+# Pax8 CTA CLI
+
+Sync your Copilot Studio agents to all your tenants from the command line.
+
+## Try it in 30 seconds (no install)
+
+```bash
+npx -y pax8-cta demo on && npx -y pax8-cta tenants list
+```
+
+Mock-data mode, no credentials, no Azure setup. Then run `npx -y pax8-cta --help` to explore every command.
+
+## Quick Start
+
+```bash
+# Try demo mode first (no credentials needed)
+pax8-cta init --demo
+pax8-cta tenants list
+
+# When ready for production
+pax8-cta demo off
+pax8-cta init
+```
+
+## Interactive Shell Mode
+
+Run `pax8-cta` without arguments to enter interactive mode where you can run commands without typing "pax8-cta" each time:
+
+```bash
+$ pax8-cta
+
+   ___                   _   ____
+  /   |  ____ ____  ____(_) / __/_ ______  _____
+ / /| | / __  / _ \/ __ / / /_/ / / / __ \/ ___/
+/ ___ |/ /_/ /  __/ / / / /__/ /_/ / / / / /__
+/_/  |_|\__, /\___/_/ /_/\___/\__, /_/ /_/\___/
+       /____/                /____/
+
+Sync your agents to all your tenants | v0.1.0
+
+Interactive mode - Type 'help' for commands or 'exit' to quit
+
+Pax8 CTA> tenants list
+(displays tenants)
+
+Pax8 CTA> demo status
+Demo mode: ENABLED
+
+Pax8 CTA> exit
+Goodbye!
+$
+```
+
+## Installation
+
+### Quick Install (macOS/Linux)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/pax8labs/pax8-cta/main/install.sh | bash
+```
+
+### Homebrew (coming soon)
+
+```bash
+# Homebrew tap is not published yet.
+# Use install.sh or binary downloads from GitHub Releases.
+```
+
+### Download Binary
+
+Download the appropriate binary for your platform from the [latest release](https://github.com/pax8labs/pax8-cta/releases/latest):
+
+#### macOS
+
+```bash
+# Apple Silicon (M1/M2/M3)
+curl -fsSL https://github.com/pax8labs/pax8-cta/releases/latest/download/pax8-cta-macos-arm64 -o pax8-cta
+chmod +x pax8-cta
+sudo mv pax8-cta /usr/local/bin/
+
+# Intel
+curl -fsSL https://github.com/pax8labs/pax8-cta/releases/latest/download/pax8-cta-macos-x64 -o pax8-cta
+chmod +x pax8-cta
+sudo mv pax8-cta /usr/local/bin/
+```
+
+#### Linux
+
+```bash
+# x64
+curl -fsSL https://github.com/pax8labs/pax8-cta/releases/latest/download/pax8-cta-linux-x64 -o pax8-cta
+chmod +x pax8-cta
+sudo mv pax8-cta /usr/local/bin/
+
+# ARM64
+curl -fsSL https://github.com/pax8labs/pax8-cta/releases/latest/download/pax8-cta-linux-arm64 -o pax8-cta
+chmod +x pax8-cta
+sudo mv pax8-cta /usr/local/bin/
+```
+
+#### Windows
+
+1. Download [pax8-cta-windows-x64.exe](https://github.com/pax8labs/pax8-cta/releases/latest/download/pax8-cta-windows-x64.exe)
+2. Rename to `pax8-cta.exe`
+3. Add to your PATH or move to a directory in your PATH
+
+### npm/npx (Alternative)
+
+If you have Node.js installed:
+
+```bash
+# Global install
+npm install -g pax8-cta
+
+# Or run with npx (no install needed)
+npx pax8-cta --help
+```
+
+### Verify Installation
+
+```bash
+pax8-cta --version
+pax8-cta --help
+```
+
+## Quick Start
+
+### 1. Deploy an Agent to All Tenants
+
+```bash
+pax8-cta deploy --all --solution ./myagent.zip
+```
+
+### 2. Deploy to Specific Tenants (by tag)
+
+```bash
+pax8-cta deploy --tag production --solution ./myagent.zip
+```
+
+### 3. View Deployment History
+
+```bash
+# List recent deployments
+pax8-cta deployments list
+
+# Show a specific deployment history entry
+pax8-cta deployments show dep-abc123
+
+# Check setup/readiness status
+pax8-cta status --setup
+```
+
+### 4. List Your Tenants
+
+```bash
+pax8-cta tenants list
+```
+
+### 5. Validate Tenant Access
+
+```bash
+pax8-cta tenants inspect
+```
+
+## Commands
+
+### Init (Setup)
+
+Initialize Pax8 CTA with guided setup.
+
+```bash
+# Quick demo setup (no credentials needed)
+pax8-cta init --demo
+
+# Full production setup (interactive wizard)
+pax8-cta init
+
+# Custom config location
+pax8-cta init --config ./custom/config.yaml
+```
+
+The setup wizard will prompt for:
+
+- Partner Tenant ID (from Partner Center)
+- App Registration Client ID (Azure AD)
+- Environment variable instructions for client secret
+- Optional sample tenant configuration
+
+**Options**:
+
+- `-c, --config <path>` - Path to create config file (default: `./config/tenants.yaml`)
+- `--demo` - Set up in demo mode (skip credential prompts)
+
+### Demo (Toggle Demo Mode)
+
+Toggle demo mode for testing without credentials.
+
+```bash
+# Enable demo mode
+pax8-cta demo on
+
+# Disable demo mode
+pax8-cta demo off
+
+# Toggle (switch between on/off)
+pax8-cta demo
+
+# Check current status
+pax8-cta demo status
+```
+
+Demo mode persists across sessions and allows you to explore all CLI features with mock data.
+
+**Why use demo mode?**
+
+- Test workflows without setting up credentials
+- Demo the tool to prospects or team members
+- Learn commands before production use
+- Develop and test integrations
+
+### Analyze (Risk Analysis)
+
+Analyze deployment risk before deploying to identify potential issues.
+
+```bash
+# Analyze risk for all enabled tenants
+pax8-cta analyze --all --solution ./agent.zip
+
+# Analyze risk for tenants with specific tags
+pax8-cta analyze --tag production --solution ./agent.zip
+
+# Output results as JSON (for scripting)
+pax8-cta analyze --all --solution ./agent.zip --json
+
+# Use custom config file
+pax8-cta analyze --all --solution ./agent.zip --config ./my-config.yaml
+```
+
+The risk analyzer checks for:
+
+- **GDAP Permissions**: Missing Power Platform Admin role
+- **Connection Issues**: Expired connection references
+- **Tenant Health**: Recurring deployment failures (2+ times in 24h)
+- **Historical Success**: Low success rates (requires 20+ deployments for statistical confidence)
+
+**Risk Levels**:
+
+- 🟢 **Low**: All checks passed, ready to deploy
+- 🟡 **Medium**: Some warnings, proceed with caution
+- 🟠 **High**: Multiple issues detected, review carefully
+- 🔴 **Critical**: Blockers present, cannot deploy until fixed
+
+**Output includes**:
+
+- Risk score and confidence level
+- Success probability percentage
+- Estimated deployment duration
+- Detailed list of issues with resolutions
+- Actionable recommendations
+
+**Why use analyze?**
+
+- Catch permission issues before deployment
+- Avoid repeating known failures
+- Estimate deployment time for planning
+- Get confidence in deployment success
+
+**Options**:
+
+- `-s, --solution <path>` - Path to agent solution ZIP file (required)
+- `--all` - Analyze all enabled tenants
+- `-t, --tag <tags...>` - Analyze only tenants with these tags
+- `-c, --config <path>` - Path to config file (default: `./config/tenants.yaml`)
+- `--json` - Output results as JSON
+
+### Deploy
+
+Deploy agents to your tenants. (Alias: `ship`)
+
+```bash
+# Deploy to all enabled tenants
+pax8-cta deploy --all --solution ./agent.zip
+
+# Deploy to tenants with specific tags
+pax8-cta deploy --tag production --tag eu --solution ./agent.zip
+
+# Dry run (preview without deploying)
+pax8-cta deploy --all --solution ./agent.zip --dry-run
+
+# Use custom config file
+pax8-cta deploy --all --solution ./agent.zip --config ./my-config.yaml
+```
+
+**Aliases**: `deploy`
+
+**Options**:
+
+- `-s, --solution <path>` - Path to agent solution ZIP file (required)
+- `--all` - Deploy to all enabled tenants
+- `-t, --tag <tags...>` - Deploy only to tenants with these tags
+- `--dry-run` - Preview deployment without executing
+- `-c, --config <path>` - Path to config file (default: `./config/tenants.yaml`)
+
+### Status
+
+Check deployment history in demo mode and setup readiness in real mode. (Alias: `track`)
+
+```bash
+# List recent demo shipments
+pax8-cta status --list
+
+# Show setup/readiness status
+pax8-cta status --setup
+```
+
+**Aliases**: `status`
+
+**Options**:
+
+- `-l, --list` - List recent shipments (demo mode)
+- `--setup` - Show setup/readiness status
+
+### Tenants
+
+Manage your tenants. (Alias: `fleet`)
+
+```bash
+# List all tenants
+pax8-cta tenants list
+
+# List with filters
+pax8-cta tenants list --tag production
+pax8-cta tenants list --enabled
+pax8-cta tenants list --disabled
+
+# Validate tenant access (GDAP permissions)
+pax8-cta tenants inspect
+pax8-cta tenants inspect --tag production
+```
+
+**Aliases**: `tenants`
+
+**Commands**:
+
+- `list` - List all tenants
+- `inspect` - Validate tenant access and GDAP permissions
+
+### Export
+
+(Alias: `pack`)
+
+Export a Copilot Studio agent to a solution ZIP file.
+
+```bash
+# Export from source environment
+pax8-cta export --solution MyAgent --output ./myagent.zip
+
+# Export specific version
+pax8-cta export --solution MyAgent --version 1.0.0.0 --output ./myagent.zip
+
+# Include dependencies
+pax8-cta export --solution MyAgent --output ./myagent.zip --managed
+```
+
+**Aliases**: `export`
+
+**Options**:
+
+- `-s, --solution <name>` - Solution unique name (required)
+- `-o, --output <path>` - Output file path (required)
+- `-v, --version <version>` - Specific version to export
+- `--managed` - Export as managed solution
+- `-c, --config <path>` - Path to config file
+
+### Import
+
+(Alias: `deliver`)
+
+Deploy an agent to a single tenant (for testing).
+
+```bash
+# Deploy to specific tenant
+pax8-cta import --tenant <tenant-id> --solution ./agent.zip
+
+# Don't overwrite customizations
+pax8-cta import --tenant <tenant-id> --solution ./agent.zip --no-overwrite
+
+# Don't publish workflows
+pax8-cta import --tenant <tenant-id> --solution ./agent.zip --no-publish
+```
+
+**Aliases**: `import`
+
+**Options**:
+
+- `-t, --tenant <id>` - Target tenant ID (required)
+- `-s, --solution <path>` - Path to solution ZIP (required)
+- `--no-overwrite` - Don't overwrite existing customizations
+- `--no-publish` - Don't activate workflows after import
+- `-c, --config <path>` - Path to config file
+
+### Resolve URL
+
+Resolve an M365 agent URL and export the containing solution.
+
+```bash
+# Resolve and export
+pax8-cta resolve-url --url "https://..." --output ./agent.zip
+```
+
+**Options**:
+
+- `-u, --url <url>` - M365 agent URL (required)
+- `-o, --output <path>` - Output file path (required)
+- `-c, --config <path>` - Path to config file
+
+## Configuration
+
+Pax8 CTA uses a YAML configuration file to define your tenants and partner credentials.
+
+**Default location**: `./config/tenants.yaml`
+
+### Example Configuration
+
+```yaml
+# Partner/MSP Credentials
+partner:
+  tenantId: "your-partner-tenant-id"
+  clientId: "your-app-client-id"
+  # Client secret should be in PAX8_CTA_CLIENT_SECRET env var
+
+# Settings
+settings:
+  approval:
+    required: true
+    minApprovals: 2
+    timeout: "24h"
+    approvers:
+      - admin@partner.com
+      - manager@partner.com
+
+# Tenants
+tenants:
+  - tenantId: "customer-tenant-1"
+    name: "Contoso Corporation"
+    environmentUrl: "https://contoso.crm.dynamics.com"
+    enabled: true
+    tags:
+      - production
+      - us-west
+      - premium
+
+  - tenantId: "customer-tenant-2"
+    name: "Fabrikam Inc"
+    environmentUrl: "https://fabrikam.crm.dynamics.com"
+    enabled: true
+    tags:
+      - production
+      - eu
+      - standard
+
+  - tenantId: "customer-tenant-3"
+    name: "Staging Environment"
+    environmentUrl: "https://staging.crm.dynamics.com"
+    enabled: false
+    tags:
+      - staging
+      - test
+```
+
+## Environment Variables
+
+- `PAX8_CTA_CLIENT_SECRET` - Azure AD app client secret (required)
+- `PAX8_CTA_INSTALL_DIR` - Custom installation directory (default: `/usr/local/bin`)
+- `CONFIG_PATH` - Custom config file path (default: `./config/tenants.yaml`)
+
+## Authentication
+
+Pax8 CTA uses Azure AD with GDAP (Granular Delegated Admin Privileges) for secure multi-tenant access.
+
+### Setup
+
+1. **Create Azure AD App Registration**
+   - Go to Azure Portal > Azure Active Directory > App Registrations
+   - Create new registration
+   - Note the Application (client) ID and Directory (tenant) ID
+
+2. **Grant API Permissions**
+   - Microsoft Graph API: `User.Read.All`
+   - Dynamics CRM: `user_impersonation`
+
+3. **Create Client Secret**
+   - In app registration, go to Certificates & secrets
+   - Create new client secret
+   - Copy the secret value
+
+4. **Configure GDAP for Customer Tenants**
+   - Set up GDAP relationships in Partner Center
+   - Assign appropriate roles (e.g., Dynamics 365 Administrator)
+
+5. **Set Environment Variable**
+
+   ```bash
+   export PAX8_CTA_CLIENT_SECRET="your-client-secret"
+   ```
+
+6. **Update Configuration**
+   - Add partner credentials to `config/tenants.yaml`
+   - Add customer tenant details
+
+## Demo Mode
+
+For testing without Azure AD credentials:
+
+```bash
+# Set in .env file
+DEMO_MODE=true
+
+# Then use the CLI normally
+pax8-cta deploy --all --solution ./demo-agent.zip
+```
+
+Demo mode uses in-memory tenants and simulates deployments.
+
+## Troubleshooting
+
+### Command Not Found
+
+If `pax8-cta` is not found after installation:
+
+```bash
+# Add to PATH (add to ~/.bashrc or ~/.zshrc for persistence)
+export PATH="/usr/local/bin:$PATH"
+
+# Or install to a directory already in PATH
+curl -fsSL https://github.com/pax8labs/pax8-cta/releases/latest/download/pax8-cta-macos-arm64 -o ~/bin/pax8-cta
+chmod +x ~/bin/pax8-cta
+```
+
+### Authentication Errors
+
+```bash
+# Verify client secret is set
+echo $PARTNER_CLIENT_SECRET
+
+# Verify tenant IDs are correct
+pax8-cta tenants list
+
+# Validate GDAP access
+pax8-cta tenants inspect
+```
+
+### Connection Errors
+
+```bash
+# Run direct deployment mode
+pax8-cta deploy --all --direct --solution ./agent.zip
+
+# Verify tenant environment URLs
+pax8-cta tenants list
+```
+
+### Deployment Failures
+
+Pax8 CTA CLI deployments run directly now, so there is no worker process to start.
+If a deployment fails, inspect the tenant details and retry the command:
+
+```bash
+pax8-cta deployments list
+pax8-cta deployments show <deployment-id>
+pax8-cta deploy --all --direct --solution ./agent.zip
+```
+
+## Development
+
+### Build from Source
+
+```bash
+# Clone repository
+git clone https://github.com/pax8labs/pax8-cta.git
+cd pax8-cta
+
+# Install dependencies
+pnpm install
+
+# Build CLI
+cd packages/cli
+pnpm build
+
+# Run locally
+node dist/index.js --help
+```
+
+### Build Binaries
+
+```bash
+# Install Bun (required for binary compilation)
+curl -fsSL https://bun.sh/install | bash
+
+# Build for current platform
+pnpm build:binary
+
+# Build for all platforms
+pnpm build:all
+
+# Binaries will be in dist/binaries/
+```
+
+### Run Tests
+
+```bash
+pnpm test
+```
+
+## Binary Sizes
+
+- macOS ARM64: ~59 MB
+- macOS x64: ~64 MB
+- Linux x64: ~99 MB
+- Linux ARM64: ~94 MB
+- Windows x64: ~111 MB
+
+Binaries are standalone and include the Bun runtime and all dependencies.
+
+## Telemetry
+
+Pax8 CTA CLI collects anonymous usage analytics to help improve the tool. No personally identifiable information is collected.
+
+**What's collected:** command names, flags used, success/failure, duration, CLI version, OS type.
+
+**What's NOT collected:** tenant IDs, file paths, environment URLs, error details, IP addresses.
+
+**Opt out:**
+
+```bash
+pax8-cta telemetry off
+# or
+export PAX8_CTA_TELEMETRY_DISABLED=1
+```
+
+**Check status:**
+
+```bash
+pax8-cta telemetry status
+```
+
+## License
+
+Apache 2.0
+
+## Support
+
+- **Documentation**: https://github.com/pax8labs/pax8-cta
+- **Issues**: https://github.com/pax8labs/pax8-cta/issues
+- **Discussions**: https://github.com/pax8labs/pax8-cta/discussions
+
+## Related Projects
+
+- **Pax8 CTA Core**: Core library for Dataverse/Dynamics 365 operations

package/dist/commands/analyze.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright 2024 Pax8, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Command } from "commander";
+import { type PreconditionFailure } from "@pax8-cta/core";
+export declare const analyzeCommand: Command;
+/**
+ * After-action picker for preflight failures. TTY-only (matches the
+ * drift-after-action UX from #404). Renders a numbered list of failures
+ * and dispatches based on remediation kind:
+ *   - `link`     → print URL, optionally `open` it.
+ *   - `command`  → print the command and spawn it.
+ *   - `manual`   → print the substituted steps.
+ */
+export declare function maybePromptPreconditionFix(failures: PreconditionFailure[], jsonOutput: boolean): Promise<void>;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/commands/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/commands/analyze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,OAAO,EASL,KAAK,mBAAmB,EAEzB,MAAM,gBAAgB,CAAC;AAsBxB,eAAO,MAAM,cAAc,SAsNvB,CAAC;AAwVL;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,UAAU,EAAE,OAAO,GAClB,OAAO,CAAC,IAAI,CAAC,CAef"}