# pymchpshelfinstall

**Repository Path**: bellstudio/pymchpshelfinstall

## Basic Information

- **Project Name**: pymchpshelfinstall
- **Description**: CLI tool to download, install, and register applications from the Microchip MPLAB Pro Shelf manifest
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: macos_support
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-09
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pymchpshelfinstall

CLI tool to download, install, and register applications from the Microchip MPLAB Pro Shelf manifest (`shelf.json`).

Designed as a standalone alternative to the VS Code extension's built-in shelf handler, with full compatibility for the extension's version-cache format.

## Install

```bash
pip install -e .
```

Requires Python 3.10+. No external dependencies (stdlib only).

## Quick Start

```bash
# Fetch shelf.json from Microchip CDN
pymchpshelfinstall update

# List available apps
pymchpshelfinstall list

# Install an app (latest version)
pymchpshelfinstall install cmake

# Install a specific version and register it for MPLAB extensions
pymchpshelfinstall install node 18.20.6 --register

# Register all already-installed apps (local + shared)
pymchpshelfinstall register --all
```

## Commands

| Command | Description |
|---------|-------------|
| `list [app]` | List available apps, or versions of a specific app |
| `info <app>` | Show app metadata (detection method, install paths, supported versions) |
| `install <app> [version]` | Download and install an app |
| `download <app> [version]` | Download a package file without installing |
| `installed` | Show locally and system-installed apps |
| `remove <app> <version>` | Remove a local app installation |
| `register [app] [version]` | Generate version-cache entries for installed apps |
| `update` | Fetch/update shelf.json from Microchip CDN |

## The `register` Command

Generates version-cache entries compatible with the MPLAB VS Code extensions, so they immediately recognize installed apps without a full rescan.

```bash
# Register a specific shared app
pymchpshelfinstall register xc32

# Register a specific version
pymchpshelfinstall register xc32 5.00

# Register everything found on the system
pymchpshelfinstall register --all
```

This scans:
- **Local apps**: `~/.mplab/app-finder/apps/<name>/v*/`
- **Shared apps (Windows)**: `c:\Program Files\Microchip\<name>\v*/` and `c:\Program Files (x86)\Microchip\<name>\v*/`
- **Shared apps (Linux)**: `/opt/microchip/<name>/v*/`
- **Shared apps (macOS)**: `/Applications/microchip/<name>/v*/`

### Version-cache format

Each entry is written to `~/.mplab/app-finder/version-cache/{sha256(path)}.v1.json`:

```json
{
    "version": "5.00",
    "ctime": 1763173351849.5771,
    "path": "c:\\Program Files\\Microchip\\xc32\\v5.00\\bin\\xc32-gcc.exe"
}
```

- **path**: The executable/file the extension uses for version detection
- **ctime**: NTFS ChangeTime in ms, matching Node.js `statSync().ctimeMs` exactly (including float64 bit representation)
- **version**: The known installed version (not detected by running the executable, avoiding PATH pollution bugs)

## Common Options

| Option | Description |
|--------|-------------|
| `--root <path>` | Install root (default: `~/.mplab/app-finder`) |
| `--shelf <path>` | Path to shelf.json (default: fetched from CDN) |
| `--os {linux,win32,darwin}` | Override target OS |
| `--arch {x64,arm64}` | Override target architecture |

### Install-specific options

| Option | Description |
|--------|-------------|
| `--no-cache` | Force re-download (ignore cached archive) |
| `--force` | Reinstall even if already present |
| `--register` | Generate version-cache entry after install |
| `--from-file <path>` | Install from a local file instead of downloading |

### Download-specific options

| Option | Description |
|--------|-------------|
| `--no-cache` | Force re-download (ignore cached file) |
| `-o, --output <dir>` | Output directory (default: current directory) |

## Offline / Network-restricted Install

For environments without internet access, use the two-step workflow:

```bash
# On a connected machine: download the package
pymchpshelfinstall download xc32 4.40 -o ./packages/

# Transfer ./packages/ to the target machine, then install
pymchpshelfinstall install xc32 4.40 --from-file ./packages/xc32-v4.40-linux-installer.run
```

Both steps validate the SHA-256 checksum against shelf.json. The `--from-file` option also verifies the filename matches the expected package name.

## How It Works

1. **Download**: Multi-connection parallel download with resume support and automatic retry (3 attempts, exponential backoff, 30s timeout)
2. **Verify**: SHA-256 checksum validation
3. **Install**:
   - Local apps: extract archive to `~/.mplab/app-finder/apps/<name>/v<version>/`
   - Shared apps: launch the installer with appropriate elevation (UAC on Windows, pkexec on Linux)
4. **Register** (with `--register`): Write version-cache entry using the correct NTFS ChangeTime (Windows) or inode ctime (Unix)

## Platform Notes

### Windows ctime

On Windows, the MPLAB extension validates cache entries using Node.js `statSync().ctimeMs`, which maps to NTFS ChangeTime (metadata modification time). Python's `os.stat().st_ctime` returns CreationTime instead. This tool uses the Windows API (`GetFileInformationByHandleEx`) and replicates Node.js/libuv's exact float64 computation path to produce bit-identical values.

### Shared app paths

The extension uses lowercase drive letters (`c:\Program Files\Microchip\...`) for shared app paths. Since SHA-256 is case-sensitive, this tool matches that convention exactly.