@rivet-dev/agentos-toolchain 0.0.0-nathan-agentos-package-resolution.efc374f → 0.2.5-rc.4

package/dist/cli.js

@@ -1,76 +1,182 @@
 #!/usr/bin/env node
 import {
-  pack
-} from "./chunk-CSSRRHDX.js";
+  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 agentOS packages
+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.
 
-Options:
-  --agent <command>   mark a bin command as the package's ACP entrypoint
-  --out <dir>         output dir for the package itself (FLAT;
-                      default: ./<input-name>-package)
-  --prune-native      delete unreachable native .node addons from the flat closure
   -h, --help          show this help
 `;
 function defaultOutName(source) {
   if (existsSync(source) && statSync(source).isDirectory()) {
-    return `./${basename(resolve(source))}-package`;
+    return `./${basename(resolve(source))}-package.tar`;
   }
   const at = source.lastIndexOf("@");
   const name = at > 0 ? source.slice(0, at) : source;
-  return `./${name.replace(/^@[^/]+\//, "")}-package`;
+  return `./${name.replace(/^@[^/]+\//, "")}-package.tar`;
 }
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--agent",
+  "--out",
+  "--commands-dir",
+  "--if-missing",
+  "--tag",
+  "--set-version"
+]);
 function parseArgs(argv) {
-  const [cmd, ...rest] = argv;
-  let source;
-  let agent;
-  let out;
-  let pruneNative = false;
-  for (let i = 0; i < rest.length; i++) {
-    const a = rest[i];
-    if (a === "--agent") agent = rest[++i];
-    else if (a === "--out") out = rest[++i];
-    else if (a === "--prune-native") pruneNative = true;
-    else if (a === "-h" || a === "--help") {
+  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 (!a.startsWith("-") && source === void 0) source = a;
-    else throw new Error(`unexpected argument: ${a}`);
+    } 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}`);
   }
-  return { cmd, source, agent, out, pruneNative };
 }
 function main() {
-  const args = parseArgs(process.argv.slice(2));
-  if (args.cmd === void 0 || args.cmd === "-h" || args.cmd === "--help") {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (cmd === void 0) {
     process.stdout.write(USAGE);
-    process.exit(args.cmd === void 0 ? 1 : 0);
+    process.exit(1);
   }
-  if (args.cmd !== "pack") {
-    throw new Error(`unknown command "${args.cmd}" (only "pack" is supported)`);
+  if (cmd === "-h" || cmd === "--help") {
+    process.stdout.write(USAGE);
+    process.exit(0);
   }
-  if (!args.source) throw new Error("pack requires a <npm-pkg | ./local-dir> argument");
-  const result = pack({
-    source: args.source,
-    out: resolve(args.out ?? defaultOutName(args.source)),
-    agent: args.agent,
-    pruneNative: args.pruneNative
-  });
-  process.stdout.write(
-    `packed ${result.name}@${result.version} \u2192 ${result.packageDir}
+  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.stderr.write(
+    `error: ${error instanceof Error ? error.message : String(error)}
+`
+  );
   process.exit(1);
 }

package/dist/index.d.ts

@@ -2,10 +2,10 @@ interface PackOptions {
     /** npm package spec (`name`, `name@version`) or a local directory path. */
     source: string;
     /**
-     * Output dir for the package itself (FLAT): the package lands directly at
-     * `<out>/{bin/, node_modules/, package.json}`. The versioned
+     * 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 from the descriptor, version from this package.json).
+     * projection's job (name/version from `agentos-package.json`).
      */
     out: string;
     /** Mark a bin command as the package's ACP entrypoint (validated against bin/). */
@@ -23,7 +23,9 @@ interface PackOptions {
 interface PackResult {
     name: string;
     version: string;
-    packageDir: string;
+    packageTar: string;
+    /** The packed `.aospkg` runtime artifact (empty when `out` was a directory). */
+    packageAospkg?: string;
     commands: string[];
 }
 /**
@@ -47,4 +49,154 @@ 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;
 
-export { type ExecutableKind, type PackOptions, type PackResult, detectExecutableKind, isNativeKind, pack, parseShebangInterpreter, verifyPackageDir };
+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

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

package/package.json

@@ -1,34 +1,38 @@
 {
-  "name": "@rivet-dev/agentos-toolchain",
-  "version": "0.0.0-nathan-agentos-package-resolution.efc374f",
-  "description": "Build toolchain for agentOS packages (pack npm packages/scripts into self-contained agentOS packages).",
-  "type": "module",
-  "license": "Apache-2.0",
-  "bin": {
-    "agentos-toolchain": "./dist/cli.js"
-  },
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
-    }
-  },
-  "files": [
-    "dist",
-    "package.json",
-    "README.md"
-  ],
-  "devDependencies": {
-    "@types/node": "^22.10.2",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.9"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts src/cli.ts --format esm --dts",
-    "check-types": "tsc --noEmit",
-    "test": "vitest run"
-  }
-}
+	"name": "@rivet-dev/agentos-toolchain",
+	"version": "0.2.5-rc.4",
+	"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"
+	}
+}