wyvrnpm 1.3.2 → 2.0.2

package/README.md

@@ -1,413 +1,704 @@
-# wyvrnpm
-
-A simple, private C++ package manager that works with any static file hosting provider — Amazon S3, a plain HTTP/HTTPS server, a local directory, or an SMB/UNC network share.
-
-There is no central registry. You control where packages are hosted.
-
----
-
-## Install
-
-```bash
-npm install -g wyvrnpm
-```
-
-Requires Node.js >= 18.
-
-For S3 publishing, also install the AWS SDK:
-
-```bash
-npm install -g @aws-sdk/client-s3 @aws-sdk/credential-providers
-```
-
----
-
-## Quick Start
-
-```bash
-# 1. Initialise a manifest in your project
-wyvrnpm init
-
-# 2. Configure your package sources once
-wyvrnpm configure add-source --kind install --name corp-s3 --url s3://my-bucket/packages --profile my-sso
-wyvrnpm configure add-source --kind publish --name default  --url s3://my-bucket/packages --profile my-sso
-
-# 3. Install dependencies (uses configured sources automatically)
-wyvrnpm install --platform win_x64
-
-# 4. Publish your package
-wyvrnpm publish --platform win_x64
-```
-
----
-
-## Commands
-
-### `wyvrnpm init`
-
-Creates a `wyvrn.json` manifest in the current directory.
-
-```bash
-wyvrnpm init
-wyvrnpm init --root ./my-project
-```
-
----
-
-### `wyvrnpm install`
-
-Resolves the full dependency graph and downloads all packages.
-
-**Source priority:** CLI `--source` values are used if provided. If omitted, sources are loaded from the [configuration file](#configuration-file).
-
-```bash
-# Use configured sources (set up via wyvrnpm configure)
-wyvrnpm install --platform win_x64
-
-# Override with explicit sources — ignores config
-wyvrnpm install --source https://pkg.example.com/cpp --platform win_x64
-
-# Multiple sources — tried in order, first to respond wins
-wyvrnpm install \
-  --source https://primary.example.com/cpp \
-  --source https://mirror.example.com/cpp \
-  --platform linux_x64
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--source` / `-s` | *(config)* | Base URL of a package source. Repeat for multiple. Overrides config when provided. |
-| `--platform` | `win_x64` | Target platform: `win_x64` `win_x86` `linux_x64` `linux_x86` `osx_x64` `osx_arm64` |
-| `--timeout` | `300` | HTTP request timeout in seconds |
-| `--manifest` | `./wyvrn.json` | Path to the manifest file |
-| `--root` | `./` | Project root (packages extracted to `{root}/wyvrn_internal/`) |
-
-Packages are extracted to `wyvrn_internal/{name}/`. A `wyvrn.lock` file is written alongside the manifest recording the exact resolved versions. On subsequent installs the lock file pins all previously resolved versions — only newly added dependencies are resolved fresh.
-
----
-
-### `wyvrnpm publish`
-
-Zips the project directory and uploads `wyvrn.json` + `wyvrn.zip` to the destination source.
-
-**Source priority:** CLI `--source` is used if provided (as a URL/URI or a configured source name). If omitted, the first configured publish source is used.
-
-```bash
-# Use the first configured publish source
-wyvrnpm publish --platform win_x64
-
-# Reference a configured source by name
-wyvrnpm publish --source default --platform win_x64
-
-# Explicit destination URL — ignores config
-wyvrnpm publish --source s3://my-bucket/packages --profile my-sso --platform win_x64
-
-# HTTP server with token auth
-wyvrnpm publish --source https://pkg.corp.com --token mytoken --platform linux_x64
-
-# Local directory or SMB share
-wyvrnpm publish --source \\fileserver\packages --platform win_x64
-wyvrnpm publish --source /mnt/packages --platform linux_x64
-
-# Publish build artifacts from a specific directory
-wyvrnpm publish --path ./dist --platform win_x64
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--source` / `-s` | *(config)* | Destination URL/URI or configured source name. Overrides config when provided. |
-| `--profile` / `-p` | *(config)* | AWS SSO profile for S3 authentication. Overrides config when provided. |
-| `--token` | *(config)* | Bearer token for HTTP server authentication. Overrides config when provided. |
-| `--platform` | `common` | Target platform sub-path: `win_x64` `win_x86` `linux_x64` `linux_x86` `osx_x64` `osx_arm64` `common` |
-| `--path` | `.` | Directory to zip and publish |
-| `--manifest` | `./wyvrn.json` | Path to the manifest file |
-
-Files are uploaded to `{source}/{platform}/{name}/{version}/wyvrn.json` and `wyvrn.zip`.
-
----
-
-### `wyvrnpm clean`
-
-Removes the `wyvrn_internal/` package cache and `wyvrn.lock`.
-
-```bash
-wyvrnpm clean
-```
-
----
-
-### `wyvrnpm configure`
-
-Manages the [configuration file](#configuration-file). All sub-commands read and write `config.json` in the platform config directory.
-
-#### `wyvrnpm configure list`
-
-Prints all configured sources.
-
-```
-Config: C:\Users\you\AppData\Local\wyvrnpm\config.json
-
-Install Sources:
-  corp-s3              s3://my-bucket/packages  [profile: my-sso]
-  fallback             https://pkg.corp.com      [token: ***]
-
-Publish Sources:
-  default              s3://my-bucket/packages  [profile: my-sso]
-```
-
-#### `wyvrnpm configure add-source`
-
-Adds a new source or updates an existing one with the same name.
-
-```bash
-# S3 with AWS SSO profile (install)
-wyvrnpm configure add-source \
-  --kind install \
-  --name corp-s3 \
-  --url s3://my-bucket/packages \
-  --profile my-sso-profile
-
-# HTTPS server with token auth (install)
-wyvrnpm configure add-source \
-  --kind install \
-  --name fallback \
-  --url https://pkg.corp.com \
-  --token mytoken
-
-# Local or SMB path (no auth required)
-wyvrnpm configure add-source \
-  --kind install \
-  --name local \
-  --url \\fileserver\packages
-
-# Publish destination
-wyvrnpm configure add-source \
-  --kind publish \
-  --name default \
-  --url s3://my-bucket/packages \
-  --profile my-sso-profile
-```
-
-**Options**
-
-| Option | Required | Description |
-|---|---|---|
-| `--kind` | Yes | `install` or `publish` |
-| `--name` | Yes | Unique name for this source |
-| `--url` | Yes | Destination URL, URI, or file path |
-| `--profile` | No | AWS SSO profile (S3 sources) |
-| `--token` | No | Bearer token (HTTP sources) |
-
-#### `wyvrnpm configure remove-source`
-
-Removes a source by name.
-
-```bash
-wyvrnpm configure remove-source --kind install --name fallback
-wyvrnpm configure remove-source --kind publish --name default
-```
-
----
-
-## Configuration File
-
-wyvrnpm stores persistent configuration in a `config.json` file:
-
-| Platform | Path |
-|---|---|
-| Windows | `%LOCALAPPDATA%\wyvrnpm\config.json` |
-| Linux / macOS | `~/.config/wyvrnpm/config.json` |
-
-**Example config.json**
-
-```json
-{
-  "installSources": [
-    {
-      "name": "corp-s3",
-      "url": "s3://my-bucket/packages",
-      "profile": "my-sso-profile"
-    },
-    {
-      "name": "fallback",
-      "url": "https://pkg.corp.com",
-      "token": "mytoken"
-    }
-  ],
-  "publishSources": [
-    {
-      "name": "default",
-      "url": "s3://my-bucket/packages",
-      "profile": "my-sso-profile"
-    }
-  ]
-}
-```
-
-**CLI options always take priority over config.** Config values are only used when the corresponding CLI option is not provided.
-
----
-
-## Publish Providers
-
-wyvrnpm uses a provider architecture to support different destination types. The correct provider is selected automatically based on the source URL format.
-
-| Provider | Detected from | Auth |
-|---|---|---|
-| **S3** | `s3://` URI, or S3 HTTPS endpoint | `--profile` (AWS SSO) |
-| **HTTP** | `http://` or `https://` | `--token` (Bearer) |
-| **File** | Local path or UNC/SMB share | none |
-
-### S3 Provider
-
-Accepts any of these source formats:
-
-```
-s3://bucket-name/optional/prefix
-https://bucket-name.s3.amazonaws.com/prefix
-https://bucket-name.s3.us-east-1.amazonaws.com/prefix
-https://s3.amazonaws.com/bucket-name/prefix
-https://s3.us-east-1.amazonaws.com/bucket-name/prefix
-```
-
-Authentication uses AWS SSO via `--profile`. If no profile is given, the default AWS credential chain is used.
-
-### HTTP Provider
-
-Accepts `http://` and `https://` URLs. Uploads files via HTTP `PUT`. Optionally authenticates with a Bearer token via `--token`.
-
-### File Provider
-
-Accepts local directory paths and SMB/UNC network shares. Files are copied with no authentication required.
-
-```
-/absolute/unix/path
-./relative/path
-C:\Windows\path
-\\server\share\path
-//server/share/path
-file:///absolute/path
-```
-
-### Adding a Custom Provider
-
-1. Create `src/providers/myprovider.js` extending `BaseProvider`:
-
-```js
-'use strict';
-const BaseProvider = require('./base');
-
-class MyProvider extends BaseProvider {
-  static canHandle(source) {
-    return source.startsWith('myscheme://');
-  }
-
-  static get providerName() { return 'MyProvider'; }
-
-  async publish(files, options) {
-    // files.manifest — path to wyvrn.json
-    // files.zip      — path to wyvrn.zip
-    // options.source, options.platform, options.name, options.version
-  }
-}
-
-module.exports = MyProvider;
-```
-
-2. Register it in `src/providers/index.js`:
-
-```js
-const MyProvider = require('./myprovider');
-
-const PROVIDERS = [
-  S3Provider,
-  HttpProvider,
-  FileProvider,
-  MyProvider,   // add here
-];
-```
-
----
-
-## Registry Layout
-
-Packages must be hosted at the following path structure relative to the source base:
-
-```
-{source}/{platform}/{name}/{version}/wyvrn.json   <- package manifest
-{source}/{platform}/{name}/{version}/wyvrn.zip    <- package archive
-```
-
-The tool also falls back to `razer.json` / `razer.zip` and a `common/` platform path for backwards compatibility.
-
-**Example (S3):**
-
-```
-s3://my-bucket/packages/win_x64/OpenSSL/3.0.0.0/wyvrn.json
-s3://my-bucket/packages/win_x64/OpenSSL/3.0.0.0/wyvrn.zip
-```
-
-**Example (HTTP):**
-
-```
-https://pkg.corp.com/win_x64/OpenSSL/3.0.0.0/wyvrn.json
-https://pkg.corp.com/win_x64/OpenSSL/3.0.0.0/wyvrn.zip
-```
-
-### Package manifest (wyvrn.json hosted on source)
-
-```json
-{
-  "Name": "OpenSSL",
-  "Version": "3.0.0.0",
-  "Description": "TLS/SSL toolkit",
-  "Dependencies": [
-    { "Name": "zlib", "Version": "1.3.0.0" }
-  ]
-}
-```
-
-Fields use PascalCase. `Dependencies` is an array — transitive dependencies are resolved automatically.
-
----
-
-## Project Manifest (wyvrn.json)
-
-```json
-{
-  "name": "my-app",
-  "version": "1.0.0.0",
-  "description": "My C++ application",
-  "kind": "ConsoleApp",
-  "dependencies": {
-    "OpenSSL": "3.0.0.0",
-    "zlib": "1.3.0.0"
-  }
-}
-```
-
-**`kind` values:** `ConsoleApp`, `StaticLib`, `DynamicLib`, `HeaderOnlyLib`, `WebApp`, `Utility`, `Service`, `TestProject`
-
-**`dependencies`** maps package names to version strings (`"major.minor.patch.build"`).
-
----
-
-## Version Conflict Resolution
-
-When the dependency graph requires the same package at multiple versions, the highest version wins. If a `wyvrn.lock` exists, locked versions always take priority over any conflicting transitive request. A warning is printed for every conflict detected.
-
----
-
-## Ignoring generated files
-
-Add the following to your `.gitignore`:
-
-```
-wyvrn_internal/
-wyvrn.lock
-*.zip
-```
+# wyvrnpm
+
+A simple, private C++ package manager that works with any static file hosting provider — Amazon S3, a plain HTTP/HTTPS server, a local directory, or an SMB/UNC network share.
+
+There is no central registry. You control where packages are hosted.
+
+> **README version: 2.0.1** — Last updated to reflect the v2 build-profile system.
+
+---
+
+## Install
+
+```bash
+npm install -g wyvrnpm
+```
+
+Requires Node.js >= 18.
+
+For S3 publishing, also install the AWS SDK:
+
+```bash
+npm install -g @aws-sdk/client-s3 @aws-sdk/credential-providers
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialise a manifest in your project
+wyvrnpm init
+
+# 2. Configure your package sources once
+wyvrnpm configure add-source --kind install --name corp-s3 --url s3://my-bucket/packages --profile my-sso
+wyvrnpm configure add-source --kind publish --name default  --url s3://my-bucket/packages --profile my-sso
+
+# 3. Detect and save your build environment as the default profile
+wyvrnpm configure profile detect
+
+# 4. Install dependencies (resolved against your build profile)
+wyvrnpm install
+
+# 5. Publish your package (uses the active profile automatically)
+wyvrnpm publish
+
+# 6. (Optional) Link local packages for development
+cd ../my-local-lib && wyvrnpm link
+cd ../my-app && wyvrnpm link my-local-lib
+```
+
+---
+
+## Build Profiles
+
+v2 introduces **build profiles** — named snapshots of your build environment (OS, architecture, compiler, C++ standard, runtime linkage). Each published binary is tagged with a profile hash so installs can resolve the correct prebuilt binary automatically.
+
+Profile fields mirror Conan 2.0 settings:
+
+| Field | Example values |
+|---|---|
+| `os` | `Windows` `Linux` `Macos` |
+| `arch` | `x86_64` `x86` `armv8` |
+| `compiler` | `msvc` `gcc` `clang` `apple-clang` |
+| `compiler.version` | `193` `13` `17` |
+| `compiler.cppstd` | `14` `17` `20` `23` |
+| `compiler.runtime` | `dynamic` `static` *(MSVC only)* |
+
+Profiles are stored in the platform config directory:
+
+| Platform | Path |
+|---|---|
+| Windows | `%LOCALAPPDATA%\wyvrnpm\profiles\` |
+| Linux / macOS | `~/.config/wyvrnpm/profiles/` |
+
+### Typical profile workflow
+
+```bash
+# Auto-detect your current environment and save it as "default"
+wyvrnpm configure profile detect
+
+# Or save under a specific name (e.g. for a release build with static runtime)
+wyvrnpm configure profile detect --name release
+wyvrnpm configure profile set --name release --runtime static
+
+# List all saved profiles (* marks the default)
+wyvrnpm configure profile list
+
+# Switch the default profile
+wyvrnpm configure profile set-default release
+```
+
+Once a default profile is saved, `install` and `publish` use it automatically — no flags required.
+
+---
+
+## Commands
+
+### `wyvrnpm init`
+
+Creates a `wyvrn.json` manifest in the current directory.
+
+```bash
+wyvrnpm init
+wyvrnpm init --root ./my-project
+```
+
+---
+
+### `wyvrnpm install`
+
+Resolves the full dependency graph and downloads all packages.
+
+**Source priority:** CLI `--source` values are used if provided. If omitted, sources are loaded from the [configuration file](#configuration-file).
+
+**Profile resolution:** `--profile` selects the named build profile. If omitted, `config.defaultProfile` is used, falling back to `"default"`. v2 binaries are matched first by exact profile hash; if no exact match is found, the tool looks for a compatible build (same OS + arch, any compiler), then falls back to the v1 legacy path.
+
+```bash
+# Use configured sources and the default build profile
+wyvrnpm install
+
+# Use a specific named profile
+wyvrnpm install --profile release
+
+# Override with explicit sources
+wyvrnpm install --source https://pkg.example.com/cpp
+
+# Multiple sources — tried in order, first to respond wins
+wyvrnpm install \
+  --source https://primary.example.com/cpp \
+  --source https://mirror.example.com/cpp
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--source` / `-s` | *(config)* | Base URL of a package source. Repeat for multiple. Overrides config when provided. |
+| `--profile` / `-p` | *(config / "default")* | Named build profile to use for v2 binary resolution. |
+| `--platform` | `win_x64` | v1 legacy platform sub-path (used as a fallback when no v2 binary is found). |
+| `--timeout` | `300` | HTTP request timeout in seconds. |
+| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
+| `--root` | `./` | Project root (packages extracted to `{root}/wyvrn_internal/`). |
+
+Packages are extracted to `wyvrn_internal/{name}/`. A `wyvrn.lock` file is written alongside the manifest recording the exact resolved versions, profile, and per-package SHA256. On subsequent installs the lock file pins all previously resolved versions — only newly added dependencies are resolved fresh.
+
+---
+
+### `wyvrnpm publish`
+
+Zips the project directory and uploads `wyvrn.json` + `wyvrn.zip` to the destination source, tagged with the active build profile.
+
+**Source priority:** CLI `--source` is used if provided (as a URL/URI or a configured source name). If omitted, the first configured publish source is used.
+
+**Profile:** `--profile` selects the named build profile to publish under. If omitted, `config.defaultProfile` is used, falling back to `"default"`. The profile hash is included in the upload path so multiple builds of the same version (different compilers, runtimes, etc.) can coexist.
+
+```bash
+# Use configured source and default profile
+wyvrnpm publish
+
+# Use a specific profile
+wyvrnpm publish --profile release
+
+# Reference a configured source by name
+wyvrnpm publish --source default
+
+# Explicit destination URL
+wyvrnpm publish --source s3://my-bucket/packages --aws-profile my-sso
+
+# HTTP server with token auth
+wyvrnpm publish --source https://pkg.corp.com --token mytoken
+
+# Local directory or SMB share
+wyvrnpm publish --source \\fileserver\packages
+wyvrnpm publish --source /mnt/packages
+
+# Publish build artifacts from a specific directory
+wyvrnpm publish --path ./dist
+
+# Overwrite an existing build (same version + profile hash)
+wyvrnpm publish --force
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--source` / `-s` | *(config)* | Destination URL/URI or configured source name. |
+| `--profile` / `-p` | *(config / "default")* | Named build profile to publish under. |
+| `--aws-profile` | *(config)* | AWS SSO profile for S3 authentication. |
+| `--token` | *(config)* | Bearer token for HTTP server authentication. |
+| `--path` | `.` | Directory to zip and publish. |
+| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
+| `--force` / `-f` | `false` | Overwrite an existing published version (same version + profile hash). |
+
+During publish the tool also:
+- reads `wyvrn.lock` to pin locked dependency versions into the uploaded manifest
+- captures the current git commit SHA and remote URL as metadata
+- computes a SHA256 of the zip and stores it in the upload metadata
+
+---
+
+### `.wyvrnignore`
+
+Place a `.wyvrnignore` file in the directory being published to exclude files from the zip. Uses the same glob syntax as `.gitignore`:
+
+```
+# Build artefacts that shouldn't ship
+build/
+*.obj
+*.pdb
+
+# Anchored to root with leading /
+/CMakeCache.txt
+/CMakeFiles/
+```
+
+---
+
+### `wyvrnpm clean`
+
+Removes the `wyvrn_internal/` package cache and `wyvrn.lock`.
+
+```bash
+wyvrnpm clean
+```
+
+---
+
+### `wyvrnpm link`
+
+Links a local package for development, similar to `npm link`. This allows you to test packages from local source directories without publishing to the registry.
+
+#### Register a package globally
+
+Run `wyvrnpm link` in a package directory to register it for linking:
+
+```bash
+cd C:\Dev\my-library
+wyvrnpm link
+# [wyvrn] Registered "my-library" -> C:\Dev\my-library
+```
+
+For CMake packages where the installable content is in a subdirectory:
+
+```bash
+cd C:\Dev\my-cmake-lib
+wyvrnpm link --subdir output/install
+# [wyvrn] Registered "my-cmake-lib" -> C:\Dev\my-cmake-lib\output\install
+```
+
+#### Link a package into your project
+
+Link a globally registered package:
+
+```bash
+cd C:\Projects\my-app
+wyvrnpm link my-library
+# [wyvrn] Linked: my-library -> C:\Dev\my-library
+```
+
+Or link directly from a path (skip global registration):
+
+```bash
+wyvrnpm link my-library C:\Dev\my-library
+wyvrnpm link my-library C:\Dev\my-library --subdir output/install
+```
+
+#### List registered packages
+
+```bash
+wyvrnpm link --list
+# [wyvrn] Globally registered packages:
+#   my-library -> C:\Dev\my-library
+#   my-cmake-lib -> C:\Dev\my-cmake-lib\output\install [subdir: output/install]
+```
+
+**Options**
+
+| Option | Description |
+|---|---|
+| `--list` | List all globally registered packages. |
+| `--subdir` | Subdirectory within the package to link (e.g., `output/install` for CMake packages). |
+
+**How it works:**
+- Creates a symlink (Unix) or junction (Windows) in `wyvrn_internal/`
+- Junctions on Windows don't require admin rights
+- Linked packages are recorded in `wyvrn.lock` with a `linked:` prefix
+- `wyvrnpm install` automatically skips downloading linked packages
+
+---
+
+### `wyvrnpm unlink`
+
+Removes a linked package from the current project.
+
+```bash
+wyvrnpm unlink my-library
+# [wyvrn] Unlinked: my-library
+```
+
+To unlink and re-download from the registry:
+
+```bash
+wyvrnpm unlink my-library --restore
+# [wyvrn] Unlinked: my-library
+# [wyvrn] Downloading: my-library@1.0.0.0
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--restore` | `false` | Re-download the package from registry after unlinking. |
+| `--source` | *(config)* | Package source for `--restore`. |
+| `--platform` | `win_x64` | Target platform for v1 fallback when using `--restore`. |
+
+---
+
+### `wyvrnpm configure`
+
+Manages the [configuration file](#configuration-file). All sub-commands read and write `config.json` in the platform config directory.
+
+#### `wyvrnpm configure list`
+
+Prints all configured sources.
+
+```
+Config: C:\Users\you\AppData\Local\wyvrnpm\config.json
+
+Install Sources:
+  corp-s3              s3://my-bucket/packages  [profile: my-sso]
+  fallback             https://pkg.corp.com      [token: ***]
+
+Publish Sources:
+  default              s3://my-bucket/packages  [profile: my-sso]
+```
+
+#### `wyvrnpm configure add-source`
+
+Adds a new source or updates an existing one with the same name.
+
+```bash
+# S3 with AWS SSO profile (install)
+wyvrnpm configure add-source \
+  --kind install \
+  --name corp-s3 \
+  --url s3://my-bucket/packages \
+  --profile my-sso-profile
+
+# HTTPS server with token auth (install)
+wyvrnpm configure add-source \
+  --kind install \
+  --name fallback \
+  --url https://pkg.corp.com \
+  --token mytoken
+
+# Local or SMB path (no auth required)
+wyvrnpm configure add-source \
+  --kind install \
+  --name local \
+  --url \\fileserver\packages
+
+# Publish destination
+wyvrnpm configure add-source \
+  --kind publish \
+  --name default \
+  --url s3://my-bucket/packages \
+  --profile my-sso-profile
+```
+
+**Options**
+
+| Option | Required | Description |
+|---|---|---|
+| `--kind` | Yes | `install` or `publish`. |
+| `--name` | Yes | Unique name for this source. |
+| `--url` | Yes | Destination URL, URI, or file path. |
+| `--profile` | No | AWS SSO profile (S3 sources). |
+| `--token` | No | Bearer token (HTTP sources). |
+
+#### `wyvrnpm configure remove-source`
+
+Removes a source by name.
+
+```bash
+wyvrnpm configure remove-source --kind install --name fallback
+wyvrnpm configure remove-source --kind publish --name default
+```
+
+#### `wyvrnpm configure profile`
+
+Manages named build profiles stored in the profiles directory.
+
+```bash
+# Auto-detect the current build environment and save it
+wyvrnpm configure profile detect
+wyvrnpm configure profile detect --name msvc_release --dry-run
+
+# List all saved profiles (* = default)
+wyvrnpm configure profile list
+
+# Show a saved profile
+wyvrnpm configure profile show
+wyvrnpm configure profile show --name msvc_release
+
+# Manually set individual fields in a profile
+wyvrnpm configure profile set --name msvc_release --runtime static --cppstd 20
+
+# Change which profile is the default
+wyvrnpm configure profile set-default msvc_release
+
+# Delete a profile
+wyvrnpm configure profile delete msvc_release
+```
+
+**`configure profile detect` options**
+
+| Option | Description |
+|---|---|
+| `--name` / `-n` | Profile name to save to (default: `"default"`). |
+| `--dry-run` | Print detected values without saving. |
+
+**`configure profile set` options**
+
+| Option | Description |
+|---|---|
+| `--name` / `-n` | Profile name to update (default: `"default"`). |
+| `--os` | OS (`Windows` \| `Linux` \| `Macos`). |
+| `--arch` | Architecture (`x86_64` \| `x86` \| `armv8` \| ...). |
+| `--compiler` | Compiler (`msvc` \| `gcc` \| `clang` \| `apple-clang`). |
+| `--compiler-version` | Compiler version (`193` \| `13` \| `17` \| ...). |
+| `--cppstd` | C++ standard (`14` \| `17` \| `20` \| `23`). |
+| `--runtime` | Runtime linkage (`static` \| `dynamic`). |
+
+---
+
+## Configuration File
+
+wyvrnpm stores persistent configuration in a `config.json` file:
+
+| Platform | Path |
+|---|---|
+| Windows | `%LOCALAPPDATA%\wyvrnpm\config.json` |
+| Linux / macOS | `~/.config/wyvrnpm/config.json` |
+
+**Example config.json**
+
+```json
+{
+  "defaultProfile": "default",
+  "installSources": [
+    {
+      "name": "corp-s3",
+      "url": "s3://my-bucket/packages",
+      "profile": "my-sso-profile"
+    },
+    {
+      "name": "fallback",
+      "url": "https://pkg.corp.com",
+      "token": "mytoken"
+    }
+  ],
+  "publishSources": [
+    {
+      "name": "default",
+      "url": "s3://my-bucket/packages",
+      "profile": "my-sso-profile"
+    }
+  ],
+  "linkedPackages": {
+    "my-library": { "path": "C:\\Dev\\my-library" },
+    "my-cmake-lib": { "path": "C:\\Dev\\my-cmake-lib", "subdir": "output/install" }
+  }
+}
+```
+
+The `defaultProfile` field sets which named build profile is used when `--profile` is not provided on the CLI.
+
+The `linkedPackages` field stores globally registered packages for `wyvrnpm link`. Each entry maps a package name to its local path and optional subdirectory.
+
+**CLI options always take priority over config.** Config values are only used when the corresponding CLI option is not provided.
+
+---
+
+## Publish Providers
+
+wyvrnpm uses a provider architecture to support different destination types. The correct provider is selected automatically based on the source URL format.
+
+| Provider | Detected from | Auth |
+|---|---|---|
+| **S3** | `s3://` URI, or S3 HTTPS endpoint | `--aws-profile` (AWS SSO) |
+| **HTTP** | `http://` or `https://` | `--token` (Bearer) |
+| **File** | Local path or UNC/SMB share | none |
+
+### S3 Provider
+
+Accepts any of these source formats:
+
+```
+s3://bucket-name/optional/prefix
+https://bucket-name.s3.amazonaws.com/prefix
+https://bucket-name.s3.us-east-1.amazonaws.com/prefix
+https://s3.amazonaws.com/bucket-name/prefix
+https://s3.us-east-1.amazonaws.com/bucket-name/prefix
+```
+
+Authentication uses AWS SSO via `--aws-profile`. If no profile is given, the default AWS credential chain is used.
+
+### HTTP Provider
+
+Accepts `http://` and `https://` URLs. Uploads files via HTTP `PUT`. Optionally authenticates with a Bearer token via `--token`.
+
+### File Provider
+
+Accepts local directory paths and SMB/UNC network shares. Files are copied with no authentication required.
+
+```
+/absolute/unix/path
+./relative/path
+C:\Windows\path
+\\server\share\path
+//server/share/path
+file:///absolute/path
+```
+
+### Adding a Custom Provider
+
+1. Create `src/providers/myprovider.js` extending `BaseProvider`:
+
+```js
+'use strict';
+const BaseProvider = require('./base');
+
+class MyProvider extends BaseProvider {
+  static canHandle(source) {
+    return source.startsWith('myscheme://');
+  }
+
+  static get providerName() { return 'MyProvider'; }
+
+  async v2Publish(files, options) {
+    // files.manifest — path to wyvrn.json
+    // files.zip      — path to wyvrn.zip
+    // options.source, options.name, options.version, options.profileHash
+    // options.contentSha256, options.gitSha, options.gitRepo
+    // options.buildSettings, options.lockedDependencies
+  }
+
+  async v2Exists(options) {
+    // Return true if this version+profileHash already exists
+    return false;
+  }
+}
+
+module.exports = MyProvider;
+```
+
+2. Register it in `src/providers/index.js`:
+
+```js
+const MyProvider = require('./myprovider');
+
+const PROVIDERS = [
+  S3Provider,
+  HttpProvider,
+  FileProvider,
+  MyProvider,   // add here
+];
+```
+
+---
+
+## Registry Layout
+
+### v2 layout (current)
+
+Packages published by v2 tooling are stored under a `v2/` prefix, with the profile hash as a sub-directory:
+
+```
+{source}/v2/{name}/{version}/{profileHash}/wyvrn.json   <- package manifest + metadata
+{source}/v2/{name}/{version}/{profileHash}/wyvrn.zip    <- package archive
+{source}/v2/{name}/versions.json                        <- version index
+{source}/v2/{name}/latest.json                          <- latest version pointer
+```
+
+The profile hash is a 16-character SHA256 prefix computed from the build profile fields. This allows multiple compiler/platform variants of the same version to coexist in the same registry.
+
+**Example (S3):**
+
+```
+s3://my-bucket/packages/v2/OpenSSL/3.0.0.0/a1b2c3d4e5f60718/wyvrn.json
+s3://my-bucket/packages/v2/OpenSSL/3.0.0.0/a1b2c3d4e5f60718/wyvrn.zip
+```
+
+### v1 layout (legacy)
+
+v2 tooling also dual-publishes to the v1 path so that older clients can still consume packages:
+
+```
+{source}/{platform}/{name}/{version}/wyvrn.json
+{source}/{platform}/{name}/{version}/wyvrn.zip
+```
+
+**Example (HTTP):**
+
+```
+https://pkg.corp.com/win_x64/OpenSSL/3.0.0.0/wyvrn.json
+https://pkg.corp.com/win_x64/OpenSSL/3.0.0.0/wyvrn.zip
+```
+
+The tool also falls back to `razer.json` / `razer.zip` for legacy compatibility.
+
+### Package manifest (wyvrn.json hosted on source)
+
+```json
+{
+  "Name": "OpenSSL",
+  "Version": "3.0.0.0",
+  "Description": "TLS/SSL toolkit",
+  "Dependencies": [
+    { "Name": "zlib", "Version": "1.3.0.0" }
+  ]
+}
+```
+
+Fields use PascalCase. `Dependencies` is an array — transitive dependencies are resolved automatically.
+
+---
+
+## Project Manifest (wyvrn.json)
+
+```json
+{
+  "name": "my-app",
+  "version": "1.0.0.0",
+  "description": "My C++ application",
+  "kind": "ConsoleApp",
+  "dependencies": {
+    "OpenSSL": "3.0.0.0",
+    "zlib": {
+      "version": "1.3.0.0",
+      "settings": {
+        "compiler.runtime": "static"
+      }
+    }
+  }
+}
+```
+
+**`kind` values:** `ConsoleApp`, `StaticLib`, `DynamicLib`, `HeaderOnlyLib`, `WebApp`, `Utility`, `Service`, `TestProject`
+
+**`dependencies`** can be either a plain version string (`"major.minor.patch.build"`) or an object with `version` and an optional `settings` map. The `settings` map overrides individual build profile fields for that specific dependency — useful when a dependency must be consumed with a different runtime linkage or C++ standard than your default profile.
+
+---
+
+## Lock File (wyvrn.lock)
+
+The v2 lock file records the full build profile alongside the resolved packages:
+
+```json
+{
+  "wyvrnVersion": 2,
+  "generatedAt": "2025-01-01T00:00:00.000Z",
+  "platform": "win_x64",
+  "profileName": "default",
+  "profile": {
+    "os": "Windows",
+    "arch": "x86_64",
+    "compiler": "msvc",
+    "compiler.version": "193",
+    "compiler.cppstd": "20",
+    "compiler.runtime": "dynamic"
+  },
+  "profileHash": "a1b2c3d4e5f60718",
+  "packages": {
+    "OpenSSL": {
+      "version": "3.0.0.0",
+      "profileHash": "a1b2c3d4e5f60718",
+      "contentSha256": "abc123...",
+      "gitSha": "def456..."
+    }
+  }
+}
+```
+
+Locked versions always take priority over transitive requests. A warning is printed for every version conflict detected.
+
+---
+
+## Version Conflict Resolution
+
+When the dependency graph requires the same package at multiple versions, the highest version wins. If a `wyvrn.lock` exists, locked versions always take priority over any conflicting transitive request. A warning is printed for every conflict detected.
+
+---
+
+## Ignoring generated files
+
+Add the following to your `.gitignore`:
+
+```
+wyvrn_internal/
+wyvrn.lock
+*.zip
+```