@vaernjs/vaern 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DEVLOGIX TECHNOLOGY (PRIVATE) LIMITED
+
+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,107 @@
-# Temporary Holding Version
+# vaern
 
-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.
+**An agent-native JavaScript & TypeScript runtime** — capability sandboxing, tool-calling, MCP, deterministic replay and sovereignty enforcement built into the engine, not bolted on as a library.
+
+A DevLogix project · licensed MIT
+
+---
+
+> ### Status: pre-release placeholder (v0.0.1)
+>
+> This version reserves the name and provides a working CLI entry point.
+>
+> Running `vaern` today prints the roadmap. That is expected, not a bug. Run `vaern doctor` for install diagnostics.
+
+---
+
+## Install
+
+```bash
+npm install -g @vaernjs/vaern      # global CLI
+npx @vaernjs/vaern --version       # without installing
+```
+
+From **v0.1.0** this pulls a single prebuilt binary for your platform via
+`optionalDependencies`, the same way `bun` and `esbuild` do. Nothing is
+downloaded in a `postinstall` script; the platform packages are ordinary npm
+packages gated by `os` and `cpu`.
+
+Supported platforms (v0.1.0+):
+
+| Platform | Package |
+|---|---|
+| Linux x86_64 | `vaern-linux-x64` |
+| Linux arm64 | `vaern-linux-arm64` |
+| macOS arm64 | `vaern-darwin-arm64` |
+| macOS x86_64 | `vaern-darwin-x64` |
+| Windows x86_64 | `vaern-win32-x64` |
+
+Install with `--no-optional` or on an unsupported platform and you get the JS
+fallback, which explains itself instead of failing silently.
+
+## What vaern will do
+
+```ts
+// courier.ts
+import { agent, tool } from "vaern:agent";
+
+const traffic = tool({
+  name: "traffic",
+  schema: { city: "string", at: "string" },
+  run: async ({ city, at }) =>
+    (await fetch(`https://api.example.pk/v2/${city}?at=${at}`)).json(),
+});
+
+const courier = agent({
+  name: "courier-copilot",
+  model: "any-openai-compatible-endpoint",
+  tools: [traffic],
+  sandbox: "vaern.toml",                 // capability policy, enforced by the engine
+  replay: "deterministic",               // every effect journalled at the engine boundary
+  budget: { tokens: 250_000, usd: 5 },   // hard stop — not an alert
+});
+
+console.log(await courier.run("Reroute today's Lahore deliveries around the fog."));
+```
+
+```bash
+vaern run courier.ts
+vaern audit export --run 7f3a --format sbp --sign
+vaern replay 7f3a --diff
+```
+
+## Programmatic use
+
+```js
+const { binaryPath, hasNativeBinary, vaern } = require("@vaernjs/vaern");
+
+if (hasNativeBinary()) vaern(["run", "app.ts"]);
+```
+
+## Roadmap
+
+| | Milestone |
+|---|---|
+| **M1** | `vaern run hello.ts` — TypeScript, `fetch`, timers, `console`, HTTP server |
+| **M2** | capability enforcer + `vaern.toml`; `node:fs` / `node:http` / `node:path` subset |
+| **M3** | `agent()`, `tool()`, MCP client/server, budgets, effect journal, `vaern replay` |
+| **M4** | residency egress guard, hash-chained audit, PK-PKI signing, `ur-PK` i18n |
+| **M5** | honest public benchmarks (including losses), docs site, external production users |
+
+We publish benchmarks we lose. A runtime that hides a benchmark is hiding something else.
+
+## Licence
+
+MIT License. Copyright (c) 2026 DEVLOGIX TECHNOLOGY (PRIVATE) LIMITED.
+See [`LICENSE`](./LICENSE).
+
+## Development
+
+```bash
+git clone https://github.com/vaernjs/vaern.git && cd vaern
+npm install
+npm run check          # pre-publish validation
+npm run pack:dry       # inspect exactly what would be published
+```
+
+Issues and pull requests welcome — we would rather be corrected now than wrong later.

package/bin/vaern.cjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * vaern — CLI entry point.
+ *
+ * Two modes, chosen at runtime:
+ *
+ *   NATIVE     A platform package (vaern-<os>-<arch>) shipped a real binary.
+ *              We exec it and get out of the way, forwarding stdio, signals
+ *              and the exit code. This is the normal path from v0.1.0.
+ *
+ *   FALLBACK   No binary for this platform yet (the v0.0.x placeholder
+ *              releases, an unsupported platform, or `npm i --no-optional`).
+ *              We serve a small built-in CLI so the command never dies with
+ *              "command not found".
+ *
+ * Resolution order for the native binary:
+ *   1. $VAERN_BINARY               (explicit override — used by CI and by `cargo run` during dev)
+ *   2. vaern-<os>-<arch> package   (the normal npm install path)
+ *   3. ../vendor/vaern             (repo-local build dropped in by `just build`)
+ *   4. FALLBACK
+ *
+ * NOTE ON STARTUP COST: this file is a Node script, so it costs ~40-70ms of
+ * interpreter startup before the native binary runs. `scripts/postinstall.cjs`
+ * removes that cost by re-pointing the bin link straight at the native binary
+ * when npm allows scripts to run. Both paths must stay working.
+ */
+
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const { createRequire } = require("node:module");
+
+const require_ = createRequire(__filename);
+const pkg = require_("../package.json");
+
+const EXE = process.platform === "win32" ? ".exe" : "";
+const PLATFORM_PKG = `vaern-${process.platform}-${process.arch}`;
+
+/* ------------------------------------------------------------------ */
+/* native binary resolution                                            */
+/* ------------------------------------------------------------------ */
+
+function firstExisting(candidates) {
+  for (const c of candidates) {
+    try {
+      if (c && fs.statSync(c).isFile()) return c;
+    } catch {
+      /* not there, keep looking */
+    }
+  }
+  return null;
+}
+
+function resolveNativeBinary() {
+  // 1. explicit override
+  if (process.env.VAERN_BINARY) {
+    const p = path.resolve(process.env.VAERN_BINARY);
+    if (fs.existsSync(p)) return p;
+    process.stderr.write(
+      `vaern: $VAERN_BINARY is set but does not exist: ${p}\n`
+    );
+  }
+
+  // 2. platform package installed by npm as an optionalDependency
+  try {
+    const manifest = require_.resolve(`${PLATFORM_PKG}/package.json`);
+    const dir = path.dirname(manifest);
+    const declared = require_(manifest).bin;
+    const rel =
+      typeof declared === "string"
+        ? declared
+        : declared && (declared.vaern || Object.values(declared)[0]);
+    const found = firstExisting([
+      rel ? path.join(dir, rel) : null,
+      path.join(dir, "bin", `vaern${EXE}`),
+      path.join(dir, `vaern${EXE}`),
+    ]);
+    if (found) return found;
+  } catch {
+    /* platform package not installed */
+  }
+
+  // 3. repo-local build (developer convenience)
+  return firstExisting([
+    path.join(__dirname, "..", "vendor", `vaern${EXE}`),
+    path.join(__dirname, "..", "..", "..", "target", "release", `vaern${EXE}`),
+  ]);
+}
+
+/* ------------------------------------------------------------------ */
+/* native mode                                                         */
+/* ------------------------------------------------------------------ */
+
+function execNative(binary, args) {
+  const child = spawn(binary, args, {
+    stdio: "inherit",
+    // Never let Node inject anything into the child's environment.
+    env: process.env,
+  });
+
+  // Forward termination signals so `vaern serve` shuts down cleanly on Ctrl-C.
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT", "SIGUSR1", "SIGUSR2"];
+  for (const sig of signals) {
+    if (sig in require("node:os").constants.signals || process.platform !== "win32") {
+      process.on(sig, () => {
+        try {
+          child.kill(sig);
+        } catch {
+          /* child already gone */
+        }
+      });
+    }
+  }
+
+  child.on("error", (err) => {
+    process.stderr.write(`vaern: failed to execute ${binary}: ${err.message}\n`);
+    process.exit(127);
+  });
+
+  child.on("close", (code, signal) => {
+    if (signal) {
+      // Die the way the child died so shells and CI see the right cause.
+      try {
+        process.kill(process.pid, signal);
+      } catch {
+        process.exit(1);
+      }
+      return;
+    }
+    process.exit(code === null ? 1 : code);
+  });
+}
+
+/* ------------------------------------------------------------------ */
+/* fallback mode                                                       */
+/* ------------------------------------------------------------------ */
+
+const BANNER = `vaern ${pkg.version} — an agent-native JavaScript & TypeScript runtime
+A DevLogix project · licensed MIT
+`;
+
+const ROADMAP = `
+vaern is in active development.
+
+  M1  weeks 3-6     vaern run hello.ts — TypeScript, fetch, timers, console, HTTP server
+  M2  weeks 7-10    capability enforcer + vaern.toml (deny by default)
+  M3  weeks 11-14   agent(), tool(), MCP client/server, budgets, effect journal, vaern replay
+  M4  weeks 15-20   sovereignty: residency guard, hash-chained audit, PK-PKI signing, ur-PK i18n
+  M5  weeks 21-26   honest public benchmarks, docs, first external production users
+
+Manifesto:   https://github.com/vaernjs/vaern
+Repository:  ${pkg.repository ? String(pkg.repository.url).replace(/^git\+/, "") : "https://github.com/vaernjs/vaern"}
+Issues:      ${pkg.bugs ? pkg.bugs.url : ""}
+
+This placeholder release exists to reserve the name on npm and to give the CLI
+a working entry point. The native runtime binary lands in M1 (v0.1.0).
+`;
+
+function fallback(args) {
+  const a = args[0];
+
+  if (a === undefined || a === "--help" || a === "-h" || a === "help") {
+    process.stdout.write(`${BANNER}\nUsage: vaern <command> [options]\n${ROADMAP}`);
+    process.exit(0);
+  }
+  if (a === "--version" || a === "-v" || a === "-V" || a === "version") {
+    process.stdout.write(`${pkg.version}\n`);
+    process.exit(0);
+  }
+  if (a === "roadmap") {
+    process.stdout.write(ROADMAP);
+    process.exit(0);
+  }
+  if (a === "doctor") {
+    process.stdout.write(`${BANNER}
+platform:        ${process.platform}-${process.arch}
+expected package: ${PLATFORM_PKG}
+node:            ${process.version}
+native binary:   NOT PRESENT (placeholder release)
+$VAERN_BINARY:   ${process.env.VAERN_BINARY || "(unset)"}
+
+Nothing is wrong. The native binary ships in v0.1.0 (milestone M1).
+Until then, install is expected to fall back to this message.
+`);
+    process.exit(0);
+  }
+
+  process.stderr.write(
+    `${BANNER}
+vaern: unknown command '${a}'
+
+The native runtime binary is not available for ${process.platform}-${process.arch}
+in this release. Expected platform package: ${PLATFORM_PKG}.
+
+Try:   vaern doctor      show install diagnostics
+       vaern roadmap     what is being built and when
+       vaern --help      usage
+`
+  );
+  process.exit(1);
+}
+
+/* ------------------------------------------------------------------ */
+
+const binary = resolveNativeBinary();
+if (binary) execNative(binary, process.argv.slice(2));
+else fallback(process.argv.slice(2));

package/index.d.ts

@@ -0,0 +1,18 @@
+import type { ChildProcess, SpawnOptions } from "node:child_process";
+
+/** Package version, e.g. "0.0.1". */
+export declare const version: string;
+
+/** Name of the platform package that carries the binary for this host, e.g. "vaern-linux-x64". */
+export declare const platformPackage: string;
+
+/** Absolute path to the native vaern binary, or null when this release has none. */
+export declare function binaryPath(): string | null;
+
+/** True when a native binary is available for the current platform. */
+export declare function hasNativeBinary(): boolean;
+
+/**
+ * Spawn the vaern binary. Throws if no native binary is present for this platform.
+ */
+export declare function vaern(args?: string[], options?: SpawnOptions): ChildProcess;

package/index.js

@@ -0,0 +1,64 @@
+"use strict";
+
+/**
+ * Programmatic API (minimal by design for v0).
+ *
+ * Most consumers want the CLI. This module exists so tools, editors and CI can
+ * locate the native binary without re-implementing the resolution logic.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const { createRequire } = require("node:module");
+
+const require_ = createRequire(__filename);
+const pkg = require_("./package.json");
+
+const EXE = process.platform === "win32" ? ".exe" : "";
+const PLATFORM_PKG = `vaern-${process.platform}-${process.arch}`;
+
+/** Package name that should carry the binary for this platform, e.g. `vaern-linux-x64`. */
+const platformPackage = PLATFORM_PKG;
+
+/** Absolute path to the native binary, or null if this release has none. */
+function binaryPath() {
+  if (process.env.VAERN_BINARY && fs.existsSync(process.env.VAERN_BINARY)) {
+    return path.resolve(process.env.VAERN_BINARY);
+  }
+  try {
+    const manifest = require_.resolve(`${PLATFORM_PKG}/package.json`);
+    const dir = path.dirname(manifest);
+    const declared = require_(manifest).bin;
+    const rel =
+      typeof declared === "string"
+        ? declared
+        : declared && (declared.vaern || Object.values(declared)[0]);
+    const candidate = rel ? path.join(dir, rel) : path.join(dir, "bin", `vaern${EXE}`);
+    return fs.existsSync(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when a native binary is available for this platform. */
+function hasNativeBinary() {
+  return binaryPath() !== null;
+}
+
+/**
+ * Spawn the vaern binary. Returns the ChildProcess so callers control stdio.
+ * Throws if no native binary is present.
+ */
+function vaern(args = [], options = {}) {
+  const bin = binaryPath();
+  if (!bin) {
+    throw new Error(
+      `vaern: no native binary for ${process.platform}-${process.arch}. ` +
+        `Install the optional platform package \`${PLATFORM_PKG}\`, or set $VAERN_BINARY.`
+    );
+  }
+  return spawn(bin, args, { stdio: "inherit", ...options });
+}
+
+module.exports = { version: pkg.version, platformPackage, binaryPath, hasNativeBinary, vaern };

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@vaernjs/vaern",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Vaern — an agent-native JavaScript & TypeScript runtime with capability sandboxing, deterministic replay and sovereignty enforcement.",
+  "keywords": [
+    "runtime",
+    "javascript",
+    "typescript",
+    "agent",
+    "agents",
+    "mcp",
+    "sandbox",
+    "cli",
+    "vaern",
+    "devlogix"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "DEVLOGIX TECHNOLOGY (PRIVATE) LIMITED"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vaernjs/vaern.git",
+    "directory": "packages/vaern"
+  },
+  "bugs": {
+    "url": "https://github.com/vaernjs/vaern/issues"
+  },
+  "type": "commonjs",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "vaern": "bin/vaern.cjs"
+  },
+  "files": [
+    "bin/",
+    "index.js",
+    "index.d.ts",
+    "scripts/postinstall.cjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.cjs",
+    "prepublishOnly": "node ../../scripts/check-publish.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  }
+}

package/scripts/postinstall.cjs

@@ -0,0 +1,89 @@
+"use strict";
+
+/**
+ * postinstall — OPTIONAL fast path. Never fails the install.
+ *
+ * npm links `bin/vaern` to our Node shim, which costs ~40-70ms of interpreter
+ * startup before the native binary runs. For a runtime CLI that is a real tax.
+ *
+ * When npm permits scripts to run, we re-point the bin link directly at the
+ * native binary so `vaern` starts at native speed. When scripts are disabled
+ * (`npm i --ignore-scripts`), nothing happens and the shim path still works.
+ *
+ * Guarantees:
+ *   - exits 0 no matter what. A failed postinstall breaks the user's install.
+ *   - POSIX only (symlink replacement). Windows keeps the shim; creating
+ *     symlinks there needs privileges we will not assume.
+ *   - opt out with VAERN_NO_LINK=1
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { createRequire } = require("node:module");
+
+function done(reason) {
+  if (process.env.VAERN_DEBUG_INSTALL) {
+    process.stdout.write(`vaern postinstall: ${reason}\n`);
+  }
+  process.exit(0);
+}
+
+function main() {
+  if (process.env.VAERN_NO_LINK === "1") return done("disabled via VAERN_NO_LINK");
+  if (process.platform === "win32") return done("windows — keeping the JS shim");
+
+  const require_ = createRequire(__filename);
+  const platformPkg = `vaern-${process.platform}-${process.arch}`;
+
+  let binary;
+  try {
+    const manifest = require_.resolve(`${platformPkg}/package.json`);
+    const dir = path.dirname(manifest);
+    const declared = require_(manifest).bin;
+    const rel =
+      typeof declared === "string"
+        ? declared
+        : declared && (declared.vaern || Object.values(declared)[0]);
+    const candidate = rel ? path.join(dir, rel) : path.join(dir, "bin", "vaern");
+    if (!fs.existsSync(candidate)) return done(`no binary in ${platformPkg}`);
+    binary = candidate;
+  } catch {
+    return done(`platform package ${platformPkg} not installed`);
+  }
+
+  fs.chmodSync(binary, 0o755);
+
+  // Candidate bin directories: local install, then global prefix.
+  const candidates = [
+    path.resolve(__dirname, "..", "..", "..", ".bin"), // node_modules/.bin
+  ];
+  if (process.env.npm_config_prefix) {
+    candidates.push(path.join(process.env.npm_config_prefix, "bin"));
+  }
+
+  let linked = false;
+  for (const binDir of candidates) {
+    const link = path.join(binDir, "vaern");
+    try {
+      if (!fs.existsSync(binDir)) continue;
+      const stat = fs.lstatSync(link);
+      // Only replace something that currently points at OUR shim.
+      const target = stat.isSymbolicLink() ? fs.readlinkSync(link) : link;
+      if (!/vaern\.cjs$/.test(target) && !/vaern\.cjs$/.test(path.resolve(binDir, target))) {
+        continue;
+      }
+      fs.rmSync(link, { force: true });
+      fs.symlinkSync(binary, link);
+      linked = true;
+    } catch {
+      continue; // read-only fs, permissions, race — all fine, the shim still works
+    }
+  }
+  return done(linked ? `linked ${binary}` : "no replaceable bin link found");
+}
+
+try {
+  main();
+} catch {
+  process.exit(0);
+}