wyvrnpm 1.2.1 → 2.0.1

package/README.md

@@ -1,413 +1,513 @@
-# 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.
+
+---
+
+## 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
+
+# 5. (Optional) Link local packages for development
+cd ../my-local-lib && wyvrnpm link
+cd ../my-app && wyvrnpm link my-local-lib
+```
+
+---
+
+## 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 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 `--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
+```
+
+---
+
+## 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"
+    }
+  ],
+  "linkedPackages": {
+    "my-library": { "path": "C:\\Dev\\my-library" },
+    "my-cmake-lib": { "path": "C:\\Dev\\my-cmake-lib", "subdir": "output/install" }
+  }
+}
+```
+
+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 | `--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
+```