npm: the gitagent command and binary through @open-gitagent/gitagent

The package installs the prebuilt binary for the platform as an optional
dependency (@open-gitagent/gitagent-<os>-<cpu>) and a gitagent command that
runs it, so 2.x users update with npm as before. The ./cli export is kept,
and the other 2.x exports remain importable as deprecated names that throw
with the replacement. The release workflow publishes the platform packages,
then the main package, with provenance.

Author: chandan25809-lyzr

.github/workflows/ci.yml

@@ -80,4 +80,9 @@ jobs:
           node-version: "22"
       - name: TypeScript client
         working-directory: clients/typescript
-        run: npm install --no-audit --no-fund && npm run check
+        run: npm install --no-audit --no-fund --omit=optional && npm run build
+      - name: The npm launcher runs the binary
+        working-directory: clients/typescript
+        run: |
+          GITAGENT_BIN=../../target/debug/gitagent node bin/gitagent.js --version
+          node --input-type=module -e "const m = await import('./dist/index.js'); if (typeof m.query !== 'function' || typeof m.loadAgent !== 'function') process.exit(1);"

.github/workflows/release.yml

@@ -49,3 +49,44 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --title "$GITHUB_REF_NAME" --generate-notes
+
+  npm:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+      - name: Platform packages
+        run: scripts/npm-packages.sh "$GITHUB_REF_NAME"
+      - name: Main package
+        working-directory: clients/typescript
+        run: npm install --no-audit --no-fund --omit=optional && npm run build
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          # A version with a pre-release part (3.1.0-rc.1) goes to the "next" tag, not "latest".
+          tag=latest
+          case "$GITHUB_REF_NAME" in *-*) tag=next ;; esac
+          publish() {
+            name=$(node -p "require('./$1/package.json').name")
+            version=$(node -p "require('./$1/package.json').version")
+            if npm view "$name@$version" version >/dev/null 2>&1; then
+              echo "$name@$version is already published"
+            else
+              npm publish "./$1" --access public --provenance --tag "$tag"
+            fi
+          }
+          # The platform packages first, so the main package's optional dependencies resolve.
+          for dir in npm/*/; do publish "${dir%/}"; done
+          publish clients/typescript

.gitignore

@@ -7,6 +7,8 @@ bench/jobs/
 __pycache__/
 *.pyc
 dist/
+/npm/
+node_modules/
 
 # The full run log, the dev/held-out split, the round history, the published
 # scores and the lesson store stay on the benchmark machine; the public proof

README.md

@@ -57,7 +57,13 @@ Fork an agent. Branch a personality. `git log` its memory. Diff its rules. Revie
 curl -fsSL https://raw.githubusercontent.com/open-gitagent/gitagent/main/scripts/install.sh | sh
 ```
 
-This installs the binary for your system (Linux x86_64/arm64, macOS arm64/x86_64) into `~/.local/bin`; set `INSTALL_DIR` to change that. To build from source you need Rust (the version is pinned in `rust-toolchain.toml`):
+Or with npm, which also gives you the TypeScript SDK:
+
+```sh
+npm install -g @open-gitagent/gitagent
+```
+
+Either way you get the same binary for your system (Linux x86_64/arm64, macOS arm64/x86_64). The script puts it in `~/.local/bin` (set `INSTALL_DIR` to change that); npm installs the package for your platform, `@open-gitagent/gitagent-<os>-<cpu>`, and a `gitagent` command that runs it. To build from source you need Rust (the version is pinned in `rust-toolchain.toml`):
 
 ```sh
 cargo build --release            # ./target/release/gitagent

clients/typescript/README.md

@@ -1,8 +1,17 @@
 # gitagent for TypeScript
 
-Drives the gitagent binary from Node. The agent runs in the binary
-(`GITAGENT_BIN`, or `gitagent` on the PATH); this package only translates
-calls and messages over the IPC protocol (`gitagent --ipc`).
+The `gitagent` command and its TypeScript SDK.
+
+```sh
+npm install -g @open-gitagent/gitagent   # the gitagent command
+npm install @open-gitagent/gitagent      # the SDK, in a project
+```
+
+npm also installs the prebuilt binary for your platform
+(`@open-gitagent/gitagent-linux-x64`, `-linux-arm64`, `-darwin-arm64` or
+`-darwin-x64`). The agent runs in that binary; this package translates calls
+and messages over the IPC protocol (`gitagent --ipc`). To use another binary,
+set `GITAGENT_BIN` or pass `binary` to `query()`.
 
 ```ts
 import { query, tool } from "@open-gitagent/gitagent";

clients/typescript/bin/gitagent.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// The `gitagent` command of the npm package: runs the binary installed for
+// this platform with the same arguments, and exits as it does.
+
+import { spawn } from "node:child_process";
+import { findBinary, PLATFORM_PACKAGES } from "../dist/binary.js";
+
+const binary = findBinary();
+if (!binary) {
+  const platform = `${process.platform}-${process.arch}`;
+  const pkg = PLATFORM_PACKAGES[platform];
+  console.error(
+    pkg
+      ? `gitagent: the binary package ${pkg} is not installed.\n` +
+          "Reinstall without --omit=optional (or --no-optional), or set GITAGENT_BIN to a gitagent binary."
+      : `gitagent: there is no prebuilt binary for ${platform}.\n` +
+          `Prebuilt: ${Object.keys(PLATFORM_PACKAGES).join(", ")}. Build from source and set GITAGENT_BIN.`,
+  );
+  process.exit(2);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
+
+// Ctrl-C and Ctrl-\ reach the binary directly from the terminal, so the
+// launcher only waits; signals sent to the launcher alone are passed on.
+for (const signal of ["SIGINT", "SIGQUIT"]) process.on(signal, () => {});
+for (const signal of ["SIGTERM", "SIGHUP"]) process.on(signal, () => child.kill(signal));
+
+child.on("error", (e) => {
+  console.error(`gitagent: cannot start ${binary}: ${e.message}`);
+  process.exit(2);
+});
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 1);
+  }
+});

clients/typescript/package.json

@@ -1,25 +1,45 @@
 {
   "name": "@open-gitagent/gitagent",
   "version": "3.0.0",
-  "description": "Drives the gitagent binary from TypeScript over its IPC protocol.",
+  "description": "The gitagent command and its TypeScript SDK: the agent that lives in a git repository.",
+  "author": "shreyaskapale",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-gitagent/gitagent.git",
+    "directory": "clients/typescript"
+  },
+  "homepage": "https://github.com/open-gitagent/gitagent",
+  "keywords": ["ai", "agent", "git", "cli", "sdk", "llm"],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "gitagent": "./bin/gitagent.js"
+  },
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": "./bin/gitagent.js",
+    "./package.json": "./package.json"
   },
-  "files": ["dist", "README.md"],
+  "files": ["dist", "bin", "README.md"],
   "scripts": {
     "build": "tsc",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
   },
   "engines": {
     "node": ">=20"
   },
-  "license": "MIT",
+  "optionalDependencies": {
+    "@open-gitagent/gitagent-linux-x64": "3.0.0",
+    "@open-gitagent/gitagent-linux-arm64": "3.0.0",
+    "@open-gitagent/gitagent-darwin-arm64": "3.0.0",
+    "@open-gitagent/gitagent-darwin-x64": "3.0.0"
+  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0"

clients/typescript/src/binary.ts

@@ -0,0 +1,39 @@
+/**
+ * Where the gitagent binary comes from. `npm install @open-gitagent/gitagent`
+ * also installs the one platform package below that matches the machine,
+ * which carries the prebuilt binary in `bin/gitagent`.
+ */
+
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** The npm package with the prebuilt binary, by `${process.platform}-${process.arch}`. */
+export const PLATFORM_PACKAGES: Record<string, string> = {
+  "linux-x64": "@open-gitagent/gitagent-linux-x64",
+  "linux-arm64": "@open-gitagent/gitagent-linux-arm64",
+  "darwin-arm64": "@open-gitagent/gitagent-darwin-arm64",
+  "darwin-x64": "@open-gitagent/gitagent-darwin-x64",
+};
+
+/**
+ * The binary to run: `GITAGENT_BIN`, else the platform package installed
+ * with this one, else the install script's `~/.local/bin/gitagent`.
+ * Undefined when none of them exists.
+ */
+export function findBinary(): string | undefined {
+  const fromEnv = process.env.GITAGENT_BIN;
+  if (fromEnv) return fromEnv;
+  const pkg = PLATFORM_PACKAGES[`${process.platform}-${process.arch}`];
+  if (pkg) {
+    try {
+      const path = createRequire(import.meta.url).resolve(`${pkg}/bin/gitagent`);
+      if (existsSync(path)) return path;
+    } catch {
+      // Not installed, for example with --omit=optional.
+    }
+  }
+  const installed = join(homedir(), ".local", "bin", "gitagent");
+  return existsSync(installed) ? installed : undefined;
+}