@rivet-dev/agentos-toolchain 0.0.0-main.ab2ce7c

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import {
+  build,
+  pack,
+  packAospkgFromTar,
+  publish,
+  stage
+} from "./chunk-YTYFSDXW.js";
+
+// src/cli.ts
+import { existsSync, statSync } from "fs";
+import { basename, resolve } from "path";
+var USAGE = `agentos-toolchain \u2014 build, stage, and publish agentOS packages
+
+Usage:
+  agentos-toolchain pack <npm-pkg | ./local-dir> [options]
+      Pack an npm package or local script dir into a self-contained agentOS
+      package tar (JS agents / node closures).
+        --agent <command>   mark a bin command as the package's ACP entrypoint
+        --out <tar>         output tar (default: ./<input-name>-package.tar)
+        --prune-native      delete unreachable native .node addons
+
+  agentos-toolchain stage [<packageDir>] --commands-dir <dir> [--if-missing skip|error]
+      Populate <packageDir>/bin/ from a compiled commands directory, per the
+      commands/aliases/stubs lists in agentos-package.json. --if-missing skip
+      leaves a valid empty placeholder when binaries are absent (default: error).
+
+  agentos-toolchain build [<packageDir>]
+      Assemble the clean runtime tar dist/package.tar (bin/ + share/ +
+      agentos-package.json) from <packageDir> (default: cwd).
+
+  agentos-toolchain publish [<packageDir>] [--tag <t> | --latest] [--dry-run] [--set-version <v>]
+      Publish the built package to npm. Default dist-tag is "dev"; the latest
+      pointer only moves with an explicit --latest.
+
+  -h, --help          show this help
+`;
+function defaultOutName(source) {
+  if (existsSync(source) && statSync(source).isDirectory()) {
+    return `./${basename(resolve(source))}-package.tar`;
+  }
+  const at = source.lastIndexOf("@");
+  const name = at > 0 ? source.slice(0, at) : source;
+  return `./${name.replace(/^@[^/]+\//, "")}-package.tar`;
+}
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--agent",
+  "--out",
+  "--commands-dir",
+  "--if-missing",
+  "--tag",
+  "--set-version"
+]);
+function parseArgs(argv) {
+  const positional = [];
+  const flags = /* @__PURE__ */ new Map();
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    } else if (VALUE_FLAGS.has(a)) {
+      const value = argv[++i];
+      if (value === void 0) throw new Error(`${a} requires a value`);
+      flags.set(a, value);
+    } else if (a.startsWith("-")) {
+      flags.set(a, true);
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+function requireKnownFlags(args, known) {
+  for (const flag of args.flags.keys()) {
+    if (!known.includes(flag)) throw new Error(`unexpected argument: ${flag}`);
+  }
+}
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (cmd === void 0) {
+    process.stdout.write(USAGE);
+    process.exit(1);
+  }
+  if (cmd === "-h" || cmd === "--help") {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+  const args = parseArgs(rest);
+  switch (cmd) {
+    case "pack-aospkg": {
+      requireKnownFlags(args, []);
+      const sourceTar = args.positional[0];
+      const dest = args.positional[1];
+      if (!sourceTar || !dest) {
+        throw new Error("pack-aospkg requires <source-tar> <dest-aospkg> arguments");
+      }
+      const summary = packAospkgFromTar(resolve(sourceTar), resolve(dest));
+      process.stdout.write(
+        `packed ${summary.name}@${summary.version} \u2192 ${dest}
+`
+      );
+      return;
+    }
+    case "pack": {
+      requireKnownFlags(args, ["--agent", "--out", "--prune-native"]);
+      const source = args.positional[0];
+      if (!source) {
+        throw new Error("pack requires a <npm-pkg | ./local-dir> argument");
+      }
+      const result = pack({
+        source,
+        out: resolve(
+          args.flags.get("--out") ?? defaultOutName(source)
+        ),
+        agent: args.flags.get("--agent"),
+        pruneNative: args.flags.get("--prune-native") === true
+      });
+      process.stdout.write(
+        `packed ${result.name}@${result.version} \u2192 ${result.packageTar}
+  commands: ${result.commands.join(", ")}
+`
+      );
+      return;
+    }
+    case "stage": {
+      requireKnownFlags(args, ["--commands-dir", "--if-missing"]);
+      const commandsDir = args.flags.get("--commands-dir");
+      if (!commandsDir) throw new Error("stage requires --commands-dir <dir>");
+      const ifMissing = args.flags.get("--if-missing") ?? "error";
+      if (ifMissing !== "error" && ifMissing !== "skip") {
+        throw new Error(
+          `--if-missing must be "skip" or "error", got "${ifMissing}"`
+        );
+      }
+      stage({
+        packageDir: args.positional[0] ?? process.cwd(),
+        commandsDir,
+        ifMissing
+      });
+      return;
+    }
+    case "build": {
+      requireKnownFlags(args, []);
+      build(args.positional[0]);
+      return;
+    }
+    case "publish": {
+      requireKnownFlags(args, [
+        "--tag",
+        "--latest",
+        "--dry-run",
+        "--set-version"
+      ]);
+      const result = publish({
+        packageDir: args.positional[0] ?? process.cwd(),
+        tag: args.flags.get("--tag"),
+        latest: args.flags.get("--latest") === true,
+        dryRun: args.flags.get("--dry-run") === true,
+        setVersion: args.flags.get("--set-version")
+      });
+      process.stdout.write(
+        `published ${result.name}@${result.version} (dist-tag: ${result.tag})
+`
+      );
+      return;
+    }
+    default:
+      throw new Error(
+        `unknown command "${cmd}" (expected pack, stage, build, or publish)`
+      );
+  }
+}
+try {
+  main();
+} catch (error) {
+  process.stderr.write(
+    `error: ${error instanceof Error ? error.message : String(error)}
+`
+  );
+  process.exit(1);
+}

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+interface PackOptions {
+    /** npm package spec (`name`, `name@version`) or a local directory path. */
+    source: string;
+    /**
+     * Output tar for the package itself. The tar contains
+     * `{bin/, node_modules/, agentos-package.json}` at its root. The versioned
+     * `/opt/agentos/<name>/<version>` + `current` layout is the sidecar
+     * projection's job (name/version from `agentos-package.json`).
+     */
+    out: string;
+    /** Mark a bin command as the package's ACP entrypoint (validated against bin/). */
+    agent?: string;
+    /**
+     * Delete native `.node` addons from the flat closure instead of failing.
+     * Use when a package's dependency tree contains optional/platform native
+     * addons (e.g. `koffi`, `clipboard-*`) that are never loaded on the code path
+     * that runs in V8. The JS closure (including dynamically-required modules) is
+     * kept; only the V8-incompatible `.node` files are removed. If a pruned addon
+     * IS reached at runtime it fails then — so this is opt-in.
+     */
+    pruneNative?: boolean;
+}
+interface PackResult {
+    name: string;
+    version: string;
+    packageTar: string;
+    /** The packed `.aospkg` runtime artifact (empty when `out` was a directory). */
+    packageAospkg?: string;
+    commands: string[];
+}
+/**
+ * Verify a finished package directory satisfies the agentOS package format:
+ * every `bin/` entry has a recognized, non-native header, and the tree has no
+ * native `.node` addons. Throws with a clear message on the first violation.
+ */
+declare function verifyPackageDir(packageDir: string): void;
+declare function pack(options: PackOptions): PackResult;
+
+/**
+ * Executable header detection — the same binfmt rules the runtime uses.
+ *
+ * Runtime is decided by the file's leading bytes, never its name or extension:
+ * a `#!` shebang, the `\0asm` WebAssembly magic, or a native object-file magic
+ * (ELF / Mach-O / PE) which agentOS cannot execute (no native-arch handler).
+ */
+type ExecutableKind = "shebang" | "wasm" | "native-elf" | "native-macho" | "native-pe" | "unknown";
+declare function detectExecutableKind(head: Buffer): ExecutableKind;
+declare function isNativeKind(kind: ExecutableKind): boolean;
+/** The interpreter named on a shebang line, taken literally (no PATH search). */
+declare function parseShebangInterpreter(head: Buffer): string | null;
+
+interface StageOptions {
+    /** Package root holding `agentos-package.json`; `bin/` is (re)created here. */
+    packageDir: string;
+    /** Directory of compiled command binaries (e.g. the native wasm build output). */
+    commandsDir: string;
+    /**
+     * What to do when the commands dir or a declared binary is absent.
+     * `"error"` (default) fails the stage; `"skip"` warns and leaves the package
+     * a valid empty placeholder — used by in-repo builds so `pnpm build` works
+     * on checkouts that have not run the native build.
+     */
+    ifMissing?: "error" | "skip";
+}
+interface StageResult {
+    staged: string[];
+    missing: string[];
+}
+/**
+ * Populate a package's `bin/` from a commands directory, per the `commands` /
+ * `aliases` / `stubs` lists declared in its `agentos-package.json`.
+ *
+ * `bin/` is wiped and rebuilt on every run. Sources are copied dereferenced
+ * (`copyFileSync` follows symlinks), so alias/stub symlink farms in the
+ * commands dir land as real files that survive npm packing.
+ */
+declare function stage(options: StageOptions): StageResult;
+
+interface BuildResult {
+    name: string;
+    version: string;
+    commands: string[];
+    outDir: string;
+    outTar: string;
+    /** The packed `.aospkg` (header + vbare manifest + mount index + mount tar). */
+    outAospkg: string;
+}
+/**
+ * Assemble a clean `dist/package/` for a WASM / command registry package.
+ *
+ * Why this exists: a package's `src/index.ts` sets the descriptor `dir` that the
+ * sidecar projects read-only under `/opt/agentos/<name>/<version>`. The sidecar
+ * copies that WHOLE directory verbatim. If `dir` pointed at the package source
+ * root it would drag `src/`, dev `node_modules/`, `tsconfig.json`, `.turbo/`
+ * into every VM. The descriptor must instead point at a CLEAN runtime dir that
+ * holds ONLY what the package ships at runtime:
+ *
+ *   dist/package/
+ *     agentos-package.json   pack-time manifest input (name, version, agent,
+ *                            provides) — consumed by the `.aospkg` packer and
+ *                            STRIPPED from the packed mount tar; the vbare
+ *                            chunk1 manifest is the single runtime manifest
+ *     bin/<cmd>              the compiled command binaries (copied verbatim)
+ *     share/...              (optional) man pages, if the source package ships them
+ *
+ * The runtime artifact is `dist/package.aospkg` (see aospkg.ts); the plain
+ * `dist/package.tar` is kept as the pack intermediate.
+ *
+ * Commands are derived from the source `bin/` directory's files (populate it
+ * with `stage`); `name`/`version` come from the source `package.json`. A package
+ * with NO (or an empty) `bin/` ships a valid, empty placeholder — it picks up
+ * its commands automatically once `stage` can populate `bin/`.
+ *
+ * This handles the COMMON case (compiled command packages). JS agent packages
+ * whose `dist/package` is a self-contained node runtime closure use `pack`
+ * instead; meta packages that default-export an ARRAY of descriptors have no
+ * `dir`/`bin` and never run this.
+ *
+ * Idempotent: `dist/package/` is removed and rebuilt on every run.
+ */
+declare function build(packageDirInput?: string): BuildResult;
+
+interface PublishOptions {
+    packageDir: string;
+    /** npm dist-tag. Defaults to `dev` so a publish NEVER moves `latest`. */
+    tag?: string;
+    /** Explicit opt-in to the `latest` dist-tag. */
+    latest?: boolean;
+    dryRun?: boolean;
+    /** Rewrite package.json `version` before publishing. */
+    setVersion?: string;
+}
+interface PublishResult {
+    name: string;
+    version: string;
+    tag: string;
+}
+/**
+ * `latest` is opt-in only: consumers installing `@agentos-software/<x>` with no
+ * tag must keep resolving a deliberate release, never whatever was published
+ * last from a dev machine or CI branch.
+ */
+declare function resolveTag(options: Pick<PublishOptions, "tag" | "latest">): string;
+/**
+ * Publish a built agentOS package to npm.
+ *
+ * Uses `pnpm publish` when the package lives in a pnpm workspace (so any
+ * `workspace:*` deps are rewritten to real versions), plain `npm publish`
+ * otherwise — 3rd-party repos need no pnpm.
+ */
+declare function publish(options: PublishOptions): PublishResult;
+
+/**
+ * The agentOS package manifest (`agentos-package.json`) at a package root.
+ *
+ * `name` / `agent` / `provides` describe the package to the runtime (they are
+ * copied into `dist/package/agentos-package.json` by `build`). `commands` /
+ * `aliases` / `stubs` describe how `stage` populates `bin/` from a compiled
+ * commands directory.
+ */
+interface AgentosPackageManifest {
+    name?: string;
+    agent?: unknown;
+    provides?: unknown;
+    /** Command binaries copied from the commands dir into `bin/<name>`. */
+    commands?: string[];
+    /** alias -> command: staged as a copy of an already-staged `bin/<command>`. */
+    aliases?: Record<string, string>;
+    /** Commands staged as copies of the commands dir's `_stubs` binary. */
+    stubs?: string[];
+}
+declare function readManifest(packageDir: string): AgentosPackageManifest | undefined;
+
+/**
+ * `.aospkg` packer — the toolchain half of the canonical packer in
+ * `crates/vfs/src/package_format/pack.rs` (both encode the schema in
+ * `crates/vfs/package-format/v1.bare`; the TS codecs are generated from it by
+ * `pnpm --dir packages/build-tools build:package-format`).
+ *
+ * Container layout: `16-byte header + vbare PackageManifest + vbare MountIndex
+ * + mount.tar` where each vbare chunk is `[u16 LE schema version] ++ BARE`.
+ *
+ * `agentos-package.json` is a pack-time INPUT only: it is parsed to build the
+ * chunk1 vbare manifest and stripped from the packed mount tar. The vbare
+ * manifest is the single runtime manifest; nothing re-materializes JSON into
+ * the guest. A root `package.json` stays in the mount tar (Node module
+ * resolution may need it) and its `bin` map is consulted for command targets.
+ */
+interface AospkgSummary {
+    name: string;
+    version: string;
+    commands: string[];
+}
+/** Pack `sourceTar` into a `.aospkg` at `dest`. The source
+ * `agentos-package.json` must carry `name` and `version`. */
+declare function packAospkgFromTar(sourceTar: string, dest: string): AospkgSummary;
+declare function packAospkgFromTarBytes(source: Buffer): {
+    bytes: Buffer;
+    summary: AospkgSummary;
+};
+
+export { type AgentosPackageManifest, type AospkgSummary, type BuildResult, type ExecutableKind, type PackOptions, type PackResult, type PublishOptions, type PublishResult, type StageOptions, type StageResult, build, detectExecutableKind, isNativeKind, pack, packAospkgFromTar, packAospkgFromTarBytes, parseShebangInterpreter, publish, readManifest, resolveTag, stage, verifyPackageDir };

package/dist/index.js

@@ -0,0 +1,28 @@
+import {
+  build,
+  detectExecutableKind,
+  isNativeKind,
+  pack,
+  packAospkgFromTar,
+  packAospkgFromTarBytes,
+  parseShebangInterpreter,
+  publish,
+  readManifest,
+  resolveTag,
+  stage,
+  verifyPackageDir
+} from "./chunk-YTYFSDXW.js";
+export {
+  build,
+  detectExecutableKind,
+  isNativeKind,
+  pack,
+  packAospkgFromTar,
+  packAospkgFromTarBytes,
+  parseShebangInterpreter,
+  publish,
+  readManifest,
+  resolveTag,
+  stage,
+  verifyPackageDir
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@rivet-dev/agentos-toolchain",
+	"version": "0.0.0-main.ab2ce7c",
+	"description": "Build toolchain for agentOS packages (pack npm packages/scripts into self-contained agentOS packages).",
+	"type": "module",
+	"license": "Apache-2.0",
+	"bin": {
+		"agentos-toolchain": "./bin/agentos-toolchain.mjs"
+	},
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			}
+		}
+	},
+	"files": [
+		"bin",
+		"dist",
+		"package.json",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsup src/index.ts src/cli.ts --format esm --dts",
+		"check-types": "tsc --noEmit",
+		"test": "vitest run"
+	},
+	"devDependencies": {
+		"@types/node": "^22.10.2",
+		"tsup": "^8.3.5",
+		"typescript": "^5.7.2",
+		"vitest": "^2.1.9"
+	},
+	"dependencies": {
+		"@rivetkit/bare-ts": "^0.6.2"
+	}
+}