wyvrnpm 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # wyvrnpm
 
-A simple, private C++ package manager that works with any static file hosting provider — Amazon S3, Azure Blob Storage, a plain nginx server, or anything that can serve files over HTTPS.
+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.
 
@@ -14,47 +14,121 @@ 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 (or the directory given by `--root`).
+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
-wyvrnpm install --source https://my-bucket.s3.amazonaws.com/cpp --platform win_x64
+# 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
-
-# Aliases
-wyvrnpm install -s https://pkg.example.com/cpp -s https://mirror.example.com/cpp
 ```
 
 **Options**
 
 | Option | Default | Description |
 |---|---|---|
-| `--source` / `-s` | — | Base URL of a package source. Repeat for multiple sources. |
-| `--platform` | `win_x64` | Target platform. One of: `win_x64`, `win_x86`, `linux_x64`, `linux_x86`, `osx_x64`, `osx_arm64` |
+| `--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}/` and a `wyvrn.lock` file is written alongside the manifest recording the exact resolved versions. On subsequent installs the lock pins all previously resolved versions — only newly added dependencies are resolved fresh.
+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`
 
@@ -66,25 +140,225 @@ 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 URL structure:
+Packages must be hosted at the following path structure relative to the source base:
 
 ```
-{source}/{platform}/{name}/{version}/wyvrn.json   <- package manifest (preferred)
-{source}/{platform}/{name}/{version}/wyvrn.zip    <- package archive (preferred)
+{source}/{platform}/{name}/{version}/wyvrn.json   <- package manifest
+{source}/{platform}/{name}/{version}/wyvrn.zip    <- package archive
 ```
 
-The tool tries `wyvrn.json` / `wyvrn.zip` first and falls back to `razer.json` / `razer.zip` if not found, for backwards compatibility.
+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:**
+**Example (HTTP):**
 
 ```
-https://my-bucket.s3.amazonaws.com/cpp/win_x64/OpenSSL/3.0.0.0/wyvrn.json
-https://my-bucket.s3.amazonaws.com/cpp/win_x64/OpenSSL/3.0.0.0/wyvrn.zip
+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 format (wyvrn.json / razer.json)
+### Package manifest (wyvrn.json hosted on source)
 
 ```json
 {

package/bin/wyvrn.js

@@ -6,6 +6,8 @@ const yargs = require('yargs');
 const init = require('../src/commands/init');
 const install = require('../src/commands/install');
 const clean = require('../src/commands/clean');
+const publish = require('../src/commands/publish');
+const configure = require('../src/commands/configure');
 
 yargs
   .option('manifest', {
@@ -55,6 +57,101 @@ yargs
     () => {},
     (argv) => clean(argv),
   )
+  .command(
+    'publish',
+    'Package and publish the project to a source (S3 or HTTP server)',
+    (yargs) => {
+      yargs
+        .option('source', {
+          alias: 's',
+          type: 'string',
+          description: 'Publish destination URL/URI or a configured source name (falls back to config)',
+        })
+        .option('profile', {
+          alias: 'p',
+          type: 'string',
+          description: 'AWS SSO profile to use for authentication (S3 only)',
+        })
+        .option('platform', {
+          type: 'string',
+          description: 'Target platform sub-path (e.g. win_x64). Defaults to "common"',
+          choices: ['win_x64', 'win_x86', 'linux_x64', 'linux_x86', 'osx_x64', 'osx_arm64', 'common'],
+          default: 'common',
+        })
+        .option('path', {
+          type: 'string',
+          description: 'Directory to zip and publish (defaults to current directory)',
+          default: '.',
+        })
+        .option('token', {
+          type: 'string',
+          description: 'Bearer token for HTTP server authentication (HTTP only)',
+        });
+    },
+    (argv) => publish(argv),
+  )
+  .command(
+    'configure',
+    'Manage wyvrnpm configuration (sources, authentication)',
+    (yargs) => {
+      yargs
+        .command('list', 'List all configured sources', () => {}, () => configure.list())
+        .command(
+          'add-source',
+          'Add or update an install/publish source',
+          (yargs) => {
+            yargs
+              .option('kind', {
+                type: 'string',
+                description: 'Source kind',
+                choices: ['install', 'publish'],
+                demandOption: true,
+              })
+              .option('name', {
+                type: 'string',
+                description: 'Unique name for this source',
+                demandOption: true,
+              })
+              .option('url', {
+                type: 'string',
+                description: 'Source URL or URI (s3://, https://, UNC path, etc.)',
+                demandOption: true,
+              })
+              .option('profile', {
+                type: 'string',
+                description: 'AWS SSO profile for this source (S3 only)',
+              })
+              .option('token', {
+                type: 'string',
+                description: 'Bearer token for this source (HTTP only)',
+              });
+          },
+          (argv) => configure.addSource(argv),
+        )
+        .command(
+          'remove-source',
+          'Remove a configured source by name',
+          (yargs) => {
+            yargs
+              .option('kind', {
+                type: 'string',
+                description: 'Source kind',
+                choices: ['install', 'publish'],
+                demandOption: true,
+              })
+              .option('name', {
+                type: 'string',
+                description: 'Name of the source to remove',
+                demandOption: true,
+              });
+          },
+          (argv) => configure.removeSource(argv),
+        )
+        .demandCommand(1)
+        .help();
+    },
+    () => {},
+  )
   .demandCommand(1)
   .strict()
   .help()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyvrnpm",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A simple, static-hosting-compatible C++ package manager",
   "keywords": [
     "c++",
@@ -26,7 +26,10 @@
   },
   "dependencies": {
     "adm-zip": "^0.5.16",
-    "yargs": "^17.7.2"
+    "node-stream-zip": "^1.15.0",
+    "yargs": "^17.7.2",
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/credential-providers": "^3.0.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/commands/configure.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const { readConfig, writeConfig, getConfigPath } = require('../config');
+
+/** wyvrnpm configure list */
+function list() {
+  const config = readConfig();
+
+  console.log(`Config: ${getConfigPath()}\n`);
+
+  printSection('Install Sources', config.installSources);
+  console.log('');
+  printSection('Publish Sources', config.publishSources);
+}
+
+function printSection(title, sources) {
+  console.log(`${title}:`);
+  if (sources.length === 0) {
+    console.log('  (none)');
+    return;
+  }
+  for (const src of sources) {
+    const auth = authLabel(src);
+    console.log(`  ${src.name.padEnd(20)} ${src.url}${auth ? '  ' + auth : ''}`);
+  }
+}
+
+function authLabel(src) {
+  if (src.profile) return `[profile: ${src.profile}]`;
+  if (src.token)   return '[token: ***]';
+  return '';
+}
+
+/**
+ * wyvrnpm configure add-source --kind install|publish --name <name> --url <url>
+ *                               [--profile <profile>] [--token <token>]
+ */
+function addSource(argv) {
+  const { kind, name, url, profile, token } = argv;
+  const config = readConfig();
+  const key = kind === 'install' ? 'installSources' : 'publishSources';
+
+  const entry = { name, url };
+  if (profile) entry.profile = profile;
+  if (token)   entry.token   = token;
+
+  const idx = config[key].findIndex((s) => s.name === name);
+  if (idx !== -1) {
+    config[key][idx] = entry;
+    console.log(`[wyvrn] Updated ${kind} source "${name}"`);
+  } else {
+    config[key].push(entry);
+    console.log(`[wyvrn] Added ${kind} source "${name}"`);
+  }
+
+  writeConfig(config);
+  console.log(`[wyvrn] Saved to ${getConfigPath()}`);
+}
+
+/**
+ * wyvrnpm configure remove-source --kind install|publish --name <name>
+ */
+function removeSource(argv) {
+  const { kind, name } = argv;
+  const config = readConfig();
+  const key = kind === 'install' ? 'installSources' : 'publishSources';
+
+  const before = config[key].length;
+  config[key] = config[key].filter((s) => s.name !== name);
+
+  if (config[key].length === before) {
+    console.error(`[wyvrn] Error: No ${kind} source named "${name}"`);
+    process.exit(1);
+  }
+
+  writeConfig(config);
+  console.log(`[wyvrn] Removed ${kind} source "${name}"`);
+}
+
+module.exports = { list, addSource, removeSource };

package/src/commands/install.js

@@ -5,6 +5,7 @@ const path = require('path');
 const { readManifest } = require('../manifest');
 const { resolveDependencies } = require('../resolve');
 const { downloadDependencies } = require('../download');
+const { readConfig } = require('../config');
 
 /**
  * Resolves and downloads all dependencies declared in the manifest, then writes
@@ -22,12 +23,22 @@ async function install(argv) {
   const manifestPath = path.resolve(argv.manifest);
   const rootDir = path.resolve(argv.root);
 
-  // Validate that at least one source is provided.
-  const packageSources = argv.source && argv.source.length > 0 ? argv.source : [];
+  // CLI --source takes priority; fall back to config installSources.
+  let packageSources;
+  if (argv.source && argv.source.length > 0) {
+    packageSources = argv.source;
+  } else {
+    const config = readConfig();
+    packageSources = config.installSources.map((s) => s.url);
+    if (packageSources.length > 0) {
+      console.log(`[wyvrn] Using ${packageSources.length} source(s) from config`);
+    }
+  }
+
   if (packageSources.length === 0) {
     console.warn(
-      '[wyvrn] Warning: no --source URLs provided. ' +
-        'Pass at least one with --source <url> or -s <url>.',
+      '[wyvrn] Warning: no sources configured. ' +
+        'Pass --source <url> or run: wyvrnpm configure add-source --kind install ...',
     );
   }
 

package/src/commands/publish.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const AdmZip = require('adm-zip');
+const { readManifest } = require('../manifest');
+const { getProvider } = require('../providers');
+const { readConfig } = require('../config');
+
+async function publish(argv) {
+  let { source, profile, platform, path: publishPath, token, manifest: manifestArg } = argv;
+
+  // Resolve source + auth: CLI > config entry by name > first config entry > raw URL
+  if (source) {
+    // Check if --source matches a named config entry rather than a raw URL/URI
+    const config = readConfig();
+    const named = config.publishSources.find((s) => s.name === source);
+    if (named) {
+      console.log(`[wyvrn] Using publish source "${named.name}" from config`);
+      source  = named.url;
+      profile = profile ?? named.profile;
+      token   = token   ?? named.token;
+    }
+  } else {
+    // No --source given — fall back to first configured publish source
+    const config = readConfig();
+    if (config.publishSources.length === 0) {
+      console.error(
+        '[wyvrn] Error: --source is required (or configure one with: ' +
+          'wyvrnpm configure add-source --kind publish ...)',
+      );
+      process.exit(1);
+    }
+    const first = config.publishSources[0];
+    console.log(`[wyvrn] Using publish source "${first.name}" from config`);
+    source  = first.url;
+    profile = profile ?? first.profile;
+    token   = token   ?? first.token;
+  }
+
+  // Resolve and read the manifest
+  const manifestPath = path.resolve(manifestArg || './wyvrn.json');
+  const manifest = await readManifest(manifestPath);
+  if (!manifest) {
+    console.error(`[wyvrn] Error: Could not read manifest at ${manifestPath}`);
+    process.exit(1);
+  }
+
+  const { name, version } = manifest;
+  if (!name || !version) {
+    console.error('[wyvrn] Error: Manifest must have "name" and "version" fields');
+    process.exit(1);
+  }
+
+  const targetPlatform = platform || 'common';
+  const srcDir = path.resolve(publishPath || '.');
+
+  if (!fs.existsSync(srcDir)) {
+    console.error(`[wyvrn] Error: Publish path does not exist: ${srcDir}`);
+    process.exit(1);
+  }
+
+  // Resolve provider from source URL/URI
+  let provider;
+  try {
+    provider = getProvider(source);
+  } catch (err) {
+    console.error(`[wyvrn] Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  console.log(
+    `[wyvrn] Publishing ${name}@${version} (${targetPlatform}) via ${provider.constructor.providerName} provider`,
+  );
+
+  // Build a temporary zip of the publish directory
+  const tmpZipPath = path.join(os.tmpdir(), `wyvrnpm-${name}-${version}-${Date.now()}.zip`);
+  try {
+    console.log(`[wyvrn] Zipping ${srcDir} ...`);
+    const zip = new AdmZip();
+    zip.addLocalFolder(srcDir);
+    zip.writeZip(tmpZipPath);
+
+    await provider.publish(
+      { manifest: manifestPath, zip: tmpZipPath },
+      { source, platform: targetPlatform, name, version, profile, token },
+    );
+
+    console.log(`[wyvrn] Successfully published ${name}@${version} to ${source}`);
+  } finally {
+    if (fs.existsSync(tmpZipPath)) fs.unlinkSync(tmpZipPath);
+  }
+}
+
+module.exports = publish;

package/src/config.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Returns the directory where wyvrnpm stores its config.
+ *   Windows : %LOCALAPPDATA%\wyvrnpm
+ *   Other   : ~/.config/wyvrnpm
+ */
+function getConfigDir() {
+  if (process.env.LOCALAPPDATA) {
+    return path.join(process.env.LOCALAPPDATA, 'wyvrnpm');
+  }
+  return path.join(os.homedir(), '.config', 'wyvrnpm');
+}
+
+/** Full path to config.json. */
+function getConfigPath() {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+/**
+ * Read and parse config.json.
+ * Returns a default empty config if the file doesn't exist yet.
+ * @returns {{ installSources: SourceEntry[], publishSources: SourceEntry[] }}
+ */
+function readConfig() {
+  const configPath = getConfigPath();
+  if (!fs.existsSync(configPath)) {
+    return { installSources: [], publishSources: [] };
+  }
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return {
+      installSources: raw.installSources ?? [],
+      publishSources: raw.publishSources ?? [],
+    };
+  } catch {
+    console.warn('[wyvrn] Warning: could not parse config.json — using defaults');
+    return { installSources: [], publishSources: [] };
+  }
+}
+
+/**
+ * Persist a config object to disk.
+ * @param {{ installSources: SourceEntry[], publishSources: SourceEntry[] }} config
+ */
+function writeConfig(config) {
+  const dir = getConfigDir();
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+module.exports = { getConfigDir, getConfigPath, readConfig, writeConfig };
+
+/**
+ * @typedef {{ name: string, url: string, profile?: string, token?: string }} SourceEntry
+ */

package/src/download.js

@@ -2,7 +2,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const AdmZip = require('adm-zip');
+const { pipeline } = require('stream/promises');
+const { Readable } = require('stream');
+const StreamZip = require('node-stream-zip');
 
 /**
  * Downloads a single URL to a local file path, respecting the given timeout.
@@ -29,8 +31,9 @@ async function downloadFile(url, destPath, httpClient, timeoutMs) {
     throw new Error(`HTTP ${response.status} for ${url}`);
   }
 
-  const arrayBuffer = await response.arrayBuffer();
-  fs.writeFileSync(destPath, Buffer.from(arrayBuffer));
+  // Stream the response body directly to disk — avoids loading large files into RAM.
+  const fileStream = fs.createWriteStream(destPath);
+  await pipeline(Readable.fromWeb(response.body), fileStream);
 }
 
 /**
@@ -59,6 +62,8 @@ async function tryDownloadFromSources(
     const candidates = [
       `${base}/${platform}/${name}/${version}/wyvrn.zip`,
       `${base}/${platform}/${name}/${version}/razer.zip`,
+      `${base}/common/${name}/${version}/wyvrn.zip`,
+      `${base}/common/${name}/${version}/razer.zip`,
     ];
     for (const url of candidates) {
       try {
@@ -135,8 +140,10 @@ async function downloadDependencies(
     }
 
     try {
-      const zip = new AdmZip(destZipPath);
-      zip.extractAllTo(extractDir, /* overwrite */ true);
+      fs.mkdirSync(extractDir, { recursive: true });
+      const zip = new StreamZip.async({ file: destZipPath });
+      await zip.extract(null, extractDir);
+      await zip.close();
       fs.writeFileSync(versionFile, version, 'utf8');
       console.log(`[wyvrn] Extracted: ${name}@${version} → ${extractDir}`);
     } catch (err) {

package/src/index.js

@@ -4,4 +4,6 @@ module.exports = {
   init: require('./commands/init'),
   install: require('./commands/install'),
   clean: require('./commands/clean'),
+  publish: require('./commands/publish'),
+  configure: require('./commands/configure'),
 };

package/src/providers/base.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Base provider class. All publish providers must extend this.
+ *
+ * To add a new provider:
+ *   1. Create src/providers/<name>.js that extends BaseProvider
+ *   2. Register it in src/providers/index.js
+ */
+class BaseProvider {
+  /**
+   * Returns true if this provider can handle the given source string.
+   * Checked in registration order; first match wins.
+   * @param {string} _source
+   * @returns {boolean}
+   */
+  static canHandle(_source) {
+    return false;
+  }
+
+  /**
+   * Publish package files to the destination.
+   *
+   * @param {{ manifest: string, zip: string }} files
+   *   Absolute paths to the local wyvrn.json and wyvrn.zip to upload.
+   * @param {{ source: string, platform: string, name: string, version: string, profile?: string, token?: string }} options
+   *   `source`   – the raw --source value (URL / URI)
+   *   `platform` – target platform string (e.g. win_x64)
+   *   `name`     – package name from manifest
+   *   `version`  – package version from manifest
+   *   `profile`  – AWS SSO profile (S3 provider)
+   *   `token`    – Bearer token (HTTP provider)
+   * @returns {Promise<void>}
+   */
+  async publish(_files, _options) {
+    throw new Error(`publish() is not implemented in ${this.constructor.name}`);
+  }
+
+  /** Human-readable provider name shown in log output. */
+  static get providerName() {
+    return 'BaseProvider';
+  }
+}
+
+module.exports = BaseProvider;

package/src/providers/file.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const BaseProvider = require('./base');
+
+/**
+ * File system provider — handles local directories and SMB/UNC shares.
+ *
+ * Recognised source formats:
+ *   /abs/unix/path
+ *   ./relative/path   ../relative/path
+ *   C:\Windows\path   C:/Windows/path   (drive-letter)
+ *   \\server\share\path                 (SMB UNC — backslash)
+ *   //server/share/path                 (SMB UNC — forward slash)
+ *   file:///path                        (file URI)
+ */
+class FileProvider extends BaseProvider {
+  static canHandle(source) {
+    return (
+      source.startsWith('file://') ||
+      source.startsWith('//') ||
+      source.startsWith('\\\\') ||
+      source.startsWith('/') ||
+      source.startsWith('./') ||
+      source.startsWith('../') ||
+      /^[a-zA-Z]:[/\\]/.test(source) // Windows drive letter
+    );
+  }
+
+  static get providerName() {
+    return 'File';
+  }
+
+  /** Normalise a source string to an absolute file system path. */
+  _resolvePath(source) {
+    if (source.startsWith('file://')) {
+      return path.resolve(new URL(source).pathname);
+    }
+    return path.resolve(source);
+  }
+
+  async publish(files, options) {
+    const { source, platform, name, version } = options;
+
+    const destDir = path.join(this._resolvePath(source), platform, name, version);
+    fs.mkdirSync(destDir, { recursive: true });
+
+    this._copy(files.manifest, path.join(destDir, 'wyvrn.json'));
+    this._copy(files.zip, path.join(destDir, 'wyvrn.zip'));
+  }
+
+  _copy(src, dest) {
+    console.log(`[wyvrn]   → ${dest}`);
+    fs.copyFileSync(src, dest);
+  }
+}
+
+module.exports = FileProvider;

package/src/providers/http.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const BaseProvider = require('./base');
+
+class HttpProvider extends BaseProvider {
+  static canHandle(source) {
+    return /^https?:\/\//.test(source);
+  }
+
+  static get providerName() {
+    return 'HTTP';
+  }
+
+  async publish(files, options) {
+    const { source, platform, name, version, token } = options;
+    const base = source.replace(/\/$/, '');
+    const urlBase = `${base}/${platform}/${name}/${version}`;
+
+    await this._put(`${urlBase}/wyvrn.json`, files.manifest, 'application/json', token);
+    await this._put(`${urlBase}/wyvrn.zip`, files.zip, 'application/zip', token);
+  }
+
+  _put(url, filePath, contentType, token) {
+    return new Promise((resolve, reject) => {
+      const body = fs.readFileSync(filePath);
+      const parsed = new URL(url);
+      const lib = parsed.protocol === 'https:' ? https : http;
+
+      const headers = {
+        'Content-Type': contentType,
+        'Content-Length': body.length,
+      };
+      if (token) headers['Authorization'] = `Bearer ${token}`;
+
+      console.log(`[wyvrn]   → PUT ${url}`);
+      const req = lib.request(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port || undefined,
+          path: parsed.pathname,
+          method: 'PUT',
+          headers,
+        },
+        (res) => {
+          res.resume(); // drain the response
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve();
+          } else {
+            reject(new Error(`HTTP PUT ${url} failed: ${res.statusCode} ${res.statusMessage}`));
+          }
+        },
+      );
+      req.on('error', reject);
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+module.exports = HttpProvider;

package/src/providers/index.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const S3Provider = require('./s3');
+const HttpProvider = require('./http');
+const FileProvider = require('./file');
+
+/**
+ * Ordered list of providers. Detection runs top-to-bottom; first match wins.
+ * Add new providers here (or call registerProvider() at runtime).
+ */
+const PROVIDERS = [
+  S3Provider,   // must come before HttpProvider — S3 HTTPS URLs also match http://
+  HttpProvider,
+  FileProvider, // local paths and SMB UNC shares (\\server\share or //server/share)
+];
+
+/**
+ * Return an instantiated provider that can handle the given source string.
+ * @param {string} source
+ * @returns {import('./base')}
+ */
+function getProvider(source) {
+  for (const Provider of PROVIDERS) {
+    if (Provider.canHandle(source)) {
+      return new Provider();
+    }
+  }
+  throw new Error(
+    `No provider found for source: "${source}"\n` +
+      'Supported schemes: s3://, http://, https://, file://, local path, \\\\server\\share (SMB)',
+  );
+}
+
+/**
+ * Register a custom provider at the front of the detection list
+ * (giving it higher priority than built-ins).
+ * @param {typeof import('./base')} Provider
+ */
+function registerProvider(Provider) {
+  PROVIDERS.unshift(Provider);
+}
+
+module.exports = { getProvider, registerProvider, PROVIDERS };

package/src/providers/s3.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const fs = require('fs');
+const BaseProvider = require('./base');
+
+// Matches:  s3://bucket/...
+const RE_S3_URI = /^s3:\/\//;
+// Matches:  https://bucket.s3.amazonaws.com/...  or  https://bucket.s3.us-east-1.amazonaws.com/...
+const RE_S3_VIRTUAL_HOSTED = /^https?:\/\/([^.]+)\.s3[.-][^/]*\.amazonaws\.com/;
+// Matches:  https://s3.amazonaws.com/bucket/...  or  https://s3.us-east-1.amazonaws.com/bucket/...
+const RE_S3_PATH_STYLE = /^https?:\/\/s3[.-][^/]*\.amazonaws\.com\/([^/]+)/;
+
+class S3Provider extends BaseProvider {
+  static canHandle(source) {
+    return (
+      RE_S3_URI.test(source) ||
+      RE_S3_VIRTUAL_HOSTED.test(source) ||
+      RE_S3_PATH_STYLE.test(source)
+    );
+  }
+
+  static get providerName() {
+    return 'S3';
+  }
+
+  /** Parse source into { bucket, prefix }. prefix has no leading/trailing slashes. */
+  _parseSource(source) {
+    if (RE_S3_URI.test(source)) {
+      const rest = source.slice(5); // strip "s3://"
+      const slash = rest.indexOf('/');
+      if (slash === -1) return { bucket: rest, prefix: '' };
+      return {
+        bucket: rest.slice(0, slash),
+        prefix: rest.slice(slash + 1).replace(/\/$/, ''),
+      };
+    }
+
+    const url = new URL(source);
+    const vhMatch = url.hostname.match(/^([^.]+)\.s3/);
+    if (vhMatch) {
+      return { bucket: vhMatch[1], prefix: url.pathname.slice(1).replace(/\/$/, '') };
+    }
+
+    // path-style: first path segment is the bucket
+    const parts = url.pathname.slice(1).split('/');
+    return {
+      bucket: parts[0],
+      prefix: parts.slice(1).join('/').replace(/\/$/, ''),
+    };
+  }
+
+  async publish(files, options) {
+    // Lazy-load AWS SDK so the tool works without it when only HTTP is used.
+    let S3Client, PutObjectCommand, fromSSO;
+    try {
+      ({ S3Client, PutObjectCommand } = require('@aws-sdk/client-s3'));
+      ({ fromSSO } = require('@aws-sdk/credential-providers'));
+    } catch {
+      throw new Error(
+        'AWS SDK packages are required for S3 publishing.\n' +
+          'Run: npm install @aws-sdk/client-s3 @aws-sdk/credential-providers',
+      );
+    }
+
+    const { source, platform, name, version, profile } = options;
+    const { bucket, prefix } = this._parseSource(source);
+
+    // Destination key base:  [prefix/]platform/name/version
+    const keyBase = [prefix, platform, name, version].filter(Boolean).join('/');
+
+    const clientConfig = profile ? { credentials: fromSSO({ profile }) } : {};
+    const client = new S3Client(clientConfig);
+
+    await this._put(client, bucket, `${keyBase}/wyvrn.json`, files.manifest, 'application/json', PutObjectCommand);
+    await this._put(client, bucket, `${keyBase}/wyvrn.zip`, files.zip, 'application/zip', PutObjectCommand);
+  }
+
+  async _put(client, bucket, key, filePath, contentType, PutObjectCommand) {
+    console.log(`[wyvrn]   → s3://${bucket}/${key}`);
+    await client.send(
+      new PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        Body: fs.readFileSync(filePath),
+        ContentType: contentType,
+      }),
+    );
+  }
+}
+
+module.exports = S3Provider;

package/src/resolve.js

@@ -44,6 +44,8 @@ async function fetchPackageManifest(name, version, packageSources, platform, htt
     const candidates = [
       `${base}/${platform}/${name}/${version}/wyvrn.json`,
       `${base}/${platform}/${name}/${version}/razer.json`,
+      `${base}/common/${name}/${version}/wyvrn.json`,
+      `${base}/common/${name}/${version}/razer.json`,
     ];
     for (const url of candidates) {
       try {