@syver_august/vowp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Syver-August Meyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# vowp (npm)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The npm package for **VOWP** — a local-first supervisor for AI coding agents.
+It installs the prebuilt `vowp` binary for your platform; Rust is not
+required.
+
+> **Status: early release (0.2.0).** The v0.2 command surface is complete, but
+> VOWP is young and interfaces may still change. The source, documentation and
+> issue tracker live at [github.com/syver777/vowp](https://github.com/syver777/vowp).
+
+## Install
+
+```sh
+npm install -g @syver_august/vowp
+vowp --version
+```
+
+Or run it without a global install:
+
+```sh
+npx vowp --version
+```
+
+Requires Node.js 18 or newer. `npm install` runs a postinstall step that
+downloads the archive for the current platform and verifies it before use.
+
+## Supported platforms
+
+| Platform | Architecture | Release target |
+|---|---|---|
+| Linux (glibc) | x86_64 | `x86_64-unknown-linux-gnu` |
+| Linux (glibc) | arm64 | `aarch64-unknown-linux-gnu` |
+| macOS | Intel | `x86_64-apple-darwin` |
+| macOS | Apple silicon | `aarch64-apple-darwin` |
+
+The Linux archives are built on Ubuntu 22.04 against glibc 2.35; older glibc
+and musl systems such as Alpine are not supported. The macOS archives are not
+code-signed or notarized. Windows is not supported. On any other platform the
+postinstall step stops with an error that names the platform and suggests
+building from source.
+
+## How the binary is installed and verified
+
+The package version is the release version. For version `X.Y.Z` the postinstall
+step downloads exactly two files:
+
+```text
+https://github.com/syver777/vowp/releases/download/vX.Y.Z/vowp-X.Y.Z-<target>.tar.gz
+https://github.com/syver777/vowp/releases/download/vX.Y.Z/vowp-X.Y.Z-<target>.tar.gz.sha256
+```
+
+Both are built by the repository's release workflow. The step:
+
+1. computes the SHA-256 of the downloaded archive;
+2. compares it with the hash in the `.sha256` file;
+3. fails without installing anything when the hashes differ;
+4. extracts only `vowp-X.Y.Z-<target>/vowp` from the archive, ignoring other
+   entries and rejecting absolute or `..` paths;
+5. installs it as `vendor/vowp` inside the package and marks it executable.
+
+`bin/vowp.js` then runs that binary with the arguments and standard
+input/output/error inherited from the caller, and exits with the binary's exit
+code. The install step makes no other network calls, and the package has no
+runtime dependencies beyond Node.js built-ins.
+
+## Skip the download
+
+Set `VOWP_SKIP_DOWNLOAD=1` to install the package without downloading the
+binary:
+
+```sh
+VOWP_SKIP_DOWNLOAD=1 npm install -g @syver_august/vowp
+```
+
+The launcher will then report that the binary is missing until you reinstall
+or run `npm rebuild -g vowp` (global install) / `npm rebuild vowp` (project
+install) without the variable.
+
+## Mirrors
+
+Point the download at a mirror with `VOWP_RELEASE_BASE_URL`. The mirror must
+serve the same release layout, with the version directory and the archive plus
+its `.sha256` file:
+
+```sh
+VOWP_RELEASE_BASE_URL=https://mirror.example/vowp/releases/download \
+  npm install -g @syver_august/vowp
+```
+
+That example resolves to
+`https://mirror.example/vowp/releases/download/vX.Y.Z/vowp-X.Y.Z-<target>.tar.gz`.
+HTTPS is required; plain HTTP is accepted only for loopback hosts, which is
+useful for a local test server. The checksum is always verified, so a mirror
+cannot substitute a different binary without changing the `.sha256` file too.
+
+## Troubleshooting
+
+Re-run the download after an interrupted install. For a global install:
+
+```sh
+npm rebuild -g vowp
+```
+
+For a package installed in a project:
+
+```sh
+npm rebuild vowp
+```
+
+If your npm configuration sets `ignore-scripts=true`, lifecycle scripts are
+disabled for that install; enable them or run `scripts/postinstall.js` from the
+installed package directory.
+
+## License
+
+MIT. See [LICENSE](https://github.com/syver777/vowp/blob/main/LICENSE).

package/bin/vowp.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const { targetFor, unsupportedMessage } = require("../lib/targets");
+
+const binary = path.join(__dirname, "..", "vendor", "vowp");
+
+if (!fs.existsSync(binary)) {
+  const target = targetFor(process.platform, process.arch);
+  let message = `vowp: the prebuilt binary is not installed at ${binary}.\n`;
+  if (target) {
+    message += `Target: ${process.platform}/${process.arch} (${target}).\n`;
+  } else {
+    message += `${unsupportedMessage(process.platform, process.arch)}\n`;
+  }
+  message +=
+    "Run `npm rebuild -g vowp` after a global install, or reinstall the package,\n" +
+    "to download it. If you installed with VOWP_SKIP_DOWNLOAD=1, run the\n" +
+    "install again without it.\n";
+  process.stderr.write(message);
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+
+child.on("error", (error) => {
+  process.stderr.write(`vowp: cannot run ${binary}: ${error.message}\n`);
+  process.exit(1);
+});
+
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => {
+    try {
+      child.kill(signal);
+    } catch {
+      // The child has already exited; the exit handler sets the final status.
+    }
+  });
+}
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    const number = os.constants.signals[signal];
+    process.exit(number ? 128 + number : 1);
+  }
+  process.exit(code === null ? 1 : code);
+});

package/lib/download.js

@@ -0,0 +1,145 @@
+"use strict";
+
+const http = require("node:http");
+const https = require("node:https");
+const zlib = require("node:zlib");
+
+const MAX_REDIRECTS = 5;
+const TIMEOUT_MS = 30_000;
+const USER_AGENT = "vowp-npm";
+
+function isLoopback(hostname) {
+  return (
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "::1" ||
+    hostname === "[::1]"
+  );
+}
+
+function checkUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`invalid release URL: ${value}`);
+  }
+  if (url.username || url.password) {
+    throw new Error("invalid release URL: credentials are not allowed");
+  }
+  if (url.protocol === "https:") return url;
+  if (url.protocol === "http:" && isLoopback(url.hostname)) return url;
+  throw new Error(
+    `refusing an insecure release URL: ${value}; use https:// ` +
+      "(http:// is allowed only for localhost)",
+  );
+}
+
+/**
+ * Download a URL into memory, following redirects.
+ *
+ * HTTPS is required except for loopback hosts, so tests and local mirrors can
+ * use a plain HTTP server. A redirect may not downgrade to an insecure host.
+ *
+ * @param {string} value absolute URL
+ * @param {number} maxBytes maximum accepted body size
+ * @returns {Promise<Buffer>}
+ */
+function getBuffer(value, maxBytes) {
+  return request(value, maxBytes, MAX_REDIRECTS);
+}
+
+function request(value, maxBytes, redirectsLeft) {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      url = checkUrl(value);
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    const client = url.protocol === "https:" ? https : http;
+    const req = client.get(
+      url,
+      { headers: { "user-agent": USER_AGENT, accept: "*/*" } },
+      (response) => {
+        const status = response.statusCode || 0;
+        const location = response.headers.location;
+
+        if (status >= 300 && status < 400 && location) {
+          response.resume();
+          if (redirectsLeft <= 0) {
+            reject(new Error(`download failed: too many redirects for ${value}`));
+            return;
+          }
+          let next;
+          try {
+            next = new URL(location, url).toString();
+          } catch {
+            reject(new Error(`download failed: invalid redirect from ${value}`));
+            return;
+          }
+          request(next, maxBytes, redirectsLeft - 1).then(resolve, reject);
+          return;
+        }
+
+        if (status !== 200) {
+          response.resume();
+          reject(new Error(`download failed: ${value} returned HTTP ${status}`));
+          return;
+        }
+
+        const encoding = String(response.headers["content-encoding"] || "")
+          .trim()
+          .toLowerCase();
+        const chunks = [];
+        let total = 0;
+
+        response.on("data", (chunk) => {
+          total += chunk.length;
+          if (total > maxBytes) {
+            response.destroy(
+              new Error(`download is larger than ${maxBytes} bytes: ${value}`),
+            );
+            return;
+          }
+          chunks.push(chunk);
+        });
+        response.on("error", (error) => {
+          reject(new Error(`download failed: ${value}: ${error.message}`));
+        });
+        response.on("end", () => {
+          let body = Buffer.concat(chunks);
+          if (encoding === "gzip" || encoding === "x-gzip") {
+            try {
+              body = zlib.gunzipSync(body, { maxOutputLength: maxBytes });
+            } catch {
+              reject(new Error(`download failed: cannot decompress ${value}`));
+              return;
+            }
+          } else if (encoding !== "" && encoding !== "identity") {
+            reject(
+              new Error(
+                `download failed: unsupported content encoding '${encoding}' for ${value}`,
+              ),
+            );
+            return;
+          }
+          resolve(body);
+        });
+      },
+    );
+
+    req.setTimeout(TIMEOUT_MS, () => {
+      req.destroy(
+        new Error(`download timed out after ${TIMEOUT_MS / 1000}s: ${value}`),
+      );
+    });
+    req.on("error", (error) => {
+      reject(new Error(`download failed: ${value}: ${error.message}`));
+    });
+  });
+}
+
+module.exports = { getBuffer, checkUrl };

package/lib/install.js

@@ -0,0 +1,155 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const fsp = require("node:fs/promises");
+const path = require("node:path");
+
+const { getBuffer } = require("./download");
+const { extractFile } = require("./tar");
+const { isMusl, targetFor, unsupportedMessage } = require("./targets");
+
+const DEFAULT_RELEASE_BASE_URL =
+  "https://github.com/syver777/vowp/releases/download";
+const MAX_ARCHIVE_BYTES = 256 * 1024 * 1024;
+const MAX_CHECKSUM_BYTES = 64 * 1024;
+const VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/;
+
+function readPackage(packageDir) {
+  const file = path.join(packageDir, "package.json");
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(`cannot read ${file}: ${error.message}`);
+  }
+}
+
+function releaseBaseUrl(env) {
+  const value = env.VOWP_RELEASE_BASE_URL || DEFAULT_RELEASE_BASE_URL;
+  return value.replace(/\/+$/, "");
+}
+
+function hashesEqual(left, right) {
+  const a = Buffer.from(left, "hex");
+  const b = Buffer.from(right, "hex");
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+function parseChecksum(text, archiveName) {
+  const lines = text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+  const hashes = [];
+  for (const line of lines) {
+    const match = /^([0-9a-fA-F]{64})(?:[ \t]+\*?(.+))?$/.exec(line);
+    if (!match) continue;
+    const file = match[2] ? path.basename(match[2].trim()) : null;
+    if (file !== null && file !== archiveName) continue;
+    hashes.push(match[1].toLowerCase());
+  }
+  if (hashes.length !== 1) {
+    throw new Error(
+      `invalid checksum file for ${archiveName}: expected one SHA256 line`,
+    );
+  }
+  return hashes[0];
+}
+
+/**
+ * Download, verify and install the prebuilt `vowp` binary into the package's
+ * `vendor/` directory.
+ *
+ * @param {object} [options]
+ * @param {string} [options.packageDir] package root (default: this module's parent)
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {string} [options.platform]
+ * @param {string} [options.arch]
+ * @param {(message: string) => void} [options.log]
+ * @returns {Promise<object>} a summary with `skipped: true` when the download was skipped
+ */
+async function install(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const packageDir = options.packageDir || path.resolve(__dirname, "..");
+  const log = options.log || ((message) => process.stdout.write(`vowp: ${message}\n`));
+
+  if (env.VOWP_SKIP_DOWNLOAD === "1") {
+    log("skipping the prebuilt binary download (VOWP_SKIP_DOWNLOAD=1)");
+    return { skipped: true };
+  }
+
+  if (platform === "linux" && isMusl(platform)) {
+    throw new Error(unsupportedMessage(platform, arch, { musl: true }));
+  }
+
+  const target = targetFor(platform, arch);
+  if (!target) {
+    throw new Error(unsupportedMessage(platform, arch));
+  }
+
+  const pkg = readPackage(packageDir);
+  const version = options.version || pkg.version;
+  if (typeof version !== "string" || !VERSION_PATTERN.test(version)) {
+    throw new Error(`invalid package version: ${String(version)}`);
+  }
+
+  const base = releaseBaseUrl(env);
+  const archiveName = `vowp-${version}-${target}.tar.gz`;
+  const archiveUrl = `${base}/v${version}/${archiveName}`;
+  const checksumUrl = `${archiveUrl}.sha256`;
+  const archiveRoot = `vowp-${version}-${target}`;
+  const binaryEntry = `${archiveRoot}/vowp`;
+
+  log(`downloading ${checksumUrl}`);
+  const checksumText = (
+    await getBuffer(checksumUrl, MAX_CHECKSUM_BYTES)
+  ).toString("utf8");
+  const expected = parseChecksum(checksumText, archiveName);
+
+  log(`downloading ${archiveUrl}`);
+  const archive = await getBuffer(archiveUrl, MAX_ARCHIVE_BYTES);
+  const actual = crypto.createHash("sha256").update(archive).digest("hex");
+  if (!hashesEqual(actual, expected)) {
+    throw new Error(
+      `SHA256 mismatch for ${archiveName} (expected ${expected}, got ${actual})`,
+    );
+  }
+  log(`verified SHA256 ${actual}`);
+
+  let file;
+  try {
+    file = extractFile(archive, binaryEntry);
+  } catch (error) {
+    throw new Error(`cannot extract ${archiveName}: ${error.message}`);
+  }
+  const vendorDir = path.join(packageDir, "vendor");
+  const binaryPath = path.join(vendorDir, "vowp");
+  const temporary = path.join(
+    vendorDir,
+    `.vowp-${process.pid}-${Date.now().toString(36)}`,
+  );
+
+  await fsp.mkdir(vendorDir, { recursive: true });
+  try {
+    await fsp.writeFile(temporary, file.data, { mode: 0o755 });
+    await fsp.chmod(temporary, 0o755);
+    await fsp.rename(temporary, binaryPath);
+  } catch (error) {
+    await fsp.rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+  await fsp.chmod(binaryPath, 0o755);
+
+  log(`installed ${binaryPath}`);
+  return { skipped: false, version, target, sha256: actual, binary: binaryPath };
+}
+
+module.exports = {
+  DEFAULT_RELEASE_BASE_URL,
+  install,
+  parseChecksum,
+  readPackage,
+  releaseBaseUrl,
+};

package/lib/tar.js

@@ -0,0 +1,157 @@
+"use strict";
+
+const zlib = require("node:zlib");
+
+const BLOCK_SIZE = 512;
+const MAX_ENTRY_BYTES = 512 * 1024 * 1024;
+const MAX_TAR_BYTES = 512 * 1024 * 1024;
+
+function readString(buffer, offset, length) {
+  const slice = buffer.subarray(offset, offset + length);
+  const end = slice.indexOf(0);
+  return (end === -1 ? slice : slice.subarray(0, end)).toString("utf8");
+}
+
+function readOctal(buffer, offset, length, what) {
+  const text = readString(buffer, offset, length).trim();
+  if (text === "") return 0;
+  if (!/^[0-7]+$/.test(text)) {
+    throw new Error(`invalid tar archive: ${what} is not octal`);
+  }
+  return Number.parseInt(text, 8);
+}
+
+function verifyChecksum(header) {
+  const stored = readOctal(header, 148, 8, "header checksum");
+  let sum = 0;
+  for (let i = 0; i < BLOCK_SIZE; i += 1) {
+    sum += i >= 148 && i < 156 ? 0x20 : header[i];
+  }
+  if (stored !== sum) {
+    throw new Error("invalid tar archive: header checksum mismatch");
+  }
+}
+
+function isZeroBlock(block) {
+  for (const byte of block) {
+    if (byte !== 0) return false;
+  }
+  return true;
+}
+
+// Parse a POSIX pax extended header ("<length> <key>=<value>\n" records). The
+// release archives only use the path and size records, but values are kept so
+// the caller can apply the ones it understands.
+function parsePax(data) {
+  const entries = {};
+  let offset = 0;
+  while (offset < data.length) {
+    const space = data.indexOf(0x20, offset);
+    if (space === -1) break;
+    const lengthText = data.subarray(offset, space).toString("ascii");
+    if (!/^[0-9]+$/.test(lengthText)) {
+      throw new Error("invalid tar archive: bad pax header length");
+    }
+    const length = Number.parseInt(lengthText, 10);
+    if (length <= 0 || offset + length > data.length) {
+      throw new Error("invalid tar archive: bad pax header record");
+    }
+    const record = data.subarray(space + 1, offset + length - 1).toString("utf8");
+    const equals = record.indexOf("=");
+    if (equals !== -1) {
+      entries[record.slice(0, equals)] = record.slice(equals + 1);
+    }
+    offset += length;
+  }
+  return entries;
+}
+
+function safePath(name) {
+  if (name.startsWith("/")) {
+    throw new Error(`invalid tar archive: absolute path ${JSON.stringify(name)}`);
+  }
+  const parts = name.split("/").filter((part) => part !== "" && part !== ".");
+  if (parts.some((part) => part === "..")) {
+    throw new Error(`invalid tar archive: unsafe path ${JSON.stringify(name)}`);
+  }
+  if (parts.length === 0) {
+    throw new Error("invalid tar archive: empty entry name");
+  }
+  return parts.join("/");
+}
+
+function joinName(prefix, name) {
+  return prefix ? `${prefix}/${name}` : name;
+}
+
+/**
+ * Extract one regular file from a gzipped tar archive.
+ *
+ * Only the requested entry is returned; nothing is written to disk. The
+ * archive is validated (header checksums and safe entry names) even for entries
+ * that are not the requested one.
+ *
+ * @param {Buffer} archive gzipped tar bytes
+ * @param {string} wantedPath normalized path of the file to return
+ * @returns {{data: Buffer, mode: number}}
+ */
+function extractFile(archive, wantedPath) {
+  let tar;
+  try {
+    tar = zlib.gunzipSync(archive, { maxOutputLength: MAX_TAR_BYTES });
+  } catch (error) {
+    throw new Error(`invalid tar archive: ${error.message}`);
+  }
+  let offset = 0;
+  let pendingName = null;
+  let pendingPax = null;
+
+  while (offset + BLOCK_SIZE <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK_SIZE);
+    if (isZeroBlock(header)) break;
+    verifyChecksum(header);
+
+    const size = readOctal(header, 124, 12, "entry size");
+    if (size > MAX_ENTRY_BYTES) {
+      throw new Error(`invalid tar archive: entry is larger than ${MAX_ENTRY_BYTES} bytes`);
+    }
+    const type = header[156] === 0 ? "0" : String.fromCharCode(header[156]);
+    const dataStart = offset + BLOCK_SIZE;
+    const dataEnd = dataStart + size;
+    if (dataEnd > tar.length) {
+      throw new Error("invalid tar archive: truncated entry");
+    }
+    const data = tar.subarray(dataStart, dataEnd);
+
+    if (type === "L") {
+      pendingName = readString(data, 0, data.length);
+    } else if (type === "x") {
+      pendingPax = parsePax(data);
+    } else if (type === "g") {
+      // Global pax attributes do not affect the entries we need.
+    } else {
+      const paxPath = pendingPax && pendingPax.path ? pendingPax.path : null;
+      const rawName = paxPath || pendingName || joinName(
+        readString(header, 345, 155),
+        readString(header, 0, 100),
+      );
+      const name = safePath(rawName);
+      if (name === wantedPath) {
+        if (type !== "0") {
+          throw new Error(
+            `invalid tar archive: ${wantedPath} is not a regular file`,
+          );
+        }
+        return { data: Buffer.from(data), mode: readOctal(header, 100, 8, "mode") };
+      }
+      pendingName = null;
+      pendingPax = null;
+    }
+
+    offset = dataStart + Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+  }
+
+  throw new Error(`invalid tar archive: it does not contain ${wantedPath}`);
+}
+
+module.exports = { extractFile };

package/lib/targets.js

@@ -0,0 +1,64 @@
+"use strict";
+
+// The four targets that .github/workflows/release.yml builds. The keys are
+// Node's process.platform and process.arch values; the values are the Rust
+// target triples used in the release archive names.
+const TARGETS = Object.freeze({
+  "linux-x64": "x86_64-unknown-linux-gnu",
+  "linux-arm64": "aarch64-unknown-linux-gnu",
+  "darwin-x64": "x86_64-apple-darwin",
+  "darwin-arm64": "aarch64-apple-darwin",
+});
+
+const SUPPORTED = Object.freeze(
+  Object.entries(TARGETS).map(([id, target]) => {
+    const [platform, arch] = id.split("-");
+    return Object.freeze({ platform, arch, target });
+  }),
+);
+
+/**
+ * Return the release target triple for a Node platform/arch pair, or null when
+ * the pair has no prebuilt archive.
+ */
+function targetFor(platform, arch) {
+  return TARGETS[`${platform}-${arch}`] || null;
+}
+
+/**
+ * True when Node is running against musl libc. The Linux release archives are
+ * linked against glibc, so musl systems have no compatible archive.
+ */
+function isMusl(platform = process.platform) {
+  if (platform !== "linux") return false;
+  if (!process.report || typeof process.report.getReport !== "function") return false;
+  try {
+    const report = process.report.getReport();
+    return Boolean(report && report.header && !report.header.glibcVersionRuntime);
+  } catch {
+    // Without a report there is no reliable libc answer; assume the common
+    // glibc case and let the launcher report an exec failure if it is wrong.
+    return false;
+  }
+}
+
+/** Build the error text used for platforms without a prebuilt archive. */
+function unsupportedMessage(platform, arch, options = {}) {
+  const id = `${platform}/${arch}`;
+  if (options.musl) {
+    return (
+      `unsupported platform: ${id} uses musl libc, but the Linux release ` +
+      `archives are built against glibc (Ubuntu 22.04, glibc 2.35). ` +
+      `Build from source with Cargo instead: https://github.com/syver777/vowp`
+    );
+  }
+  const supported = SUPPORTED.map(
+    ({ platform: p, arch: a, target }) => `${p}/${a} (${target})`,
+  ).join(", ");
+  return (
+    `unsupported platform: ${id}; supported platforms: ${supported}. ` +
+    `Build from source with Cargo instead: https://github.com/syver777/vowp`
+  );
+}
+
+module.exports = { TARGETS, SUPPORTED, targetFor, isMusl, unsupportedMessage };

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@syver_august/vowp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Local-first supervisor for AI coding agents",
+  "keywords": [
+    "ai",
+    "agents",
+    "agent-orchestration",
+    "claude-code",
+    "opencode",
+    "supervisor",
+    "cli",
+    "tmux"
+  ],
+  "homepage": "https://github.com/syver777/vowp#readme",
+  "bugs": {
+    "url": "https://github.com/syver777/vowp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/syver777/vowp.git"
+  },
+  "license": "MIT",
+  "author": "Syver-August Meyer",
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "bin": {
+    "vowp": "bin/vowp.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/postinstall.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test test/*.test.js"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+"use strict";
+
+const { install } = require("../lib/install");
+
+install().catch((error) => {
+  process.stderr.write(`vowp: error: ${error.message}\n`);
+  process.exitCode = 1;
+});