ai2rules-harness 0.1.1 → 0.2.0

package/README.md

@@ -3,18 +3,39 @@
 **Govern a local coding agent in one command.**
 
 ```bash
-npx ai2rules-harness init
+npm install -g ai2rules-harness
+harness init
 ```
 
 That writes a governance manifest, a `PreToolUse` shim, and the host settings entry
 into the current project. It is safe to run twice, it never replaces a manifest you
 have tuned, and turning it off is one file.
 
-> **Not on npm yet.** The prebuilt binaries this wrapper downloads **do** exist —
-> `v0.1.1`, four platforms, each with a published checksum — but the package
-> itself has not been pushed to the registry. Until it is:
-> `cargo install --git https://github.com/sv-pro/ai2rules cli-harness`, then
-> `harness init`. See `DECISIONS.md` D56.
+> **Install it globally, not into a project.** `harness init` **refuses** to run
+> when the binary lives inside the project it would govern — a local
+> `node_modules` install puts the kernel in the agent's own writable root, where
+> replacing one file turns governance off silently. `npx ai2rules-harness init`
+> is fine: its cache is outside your project.
+
+## How it installs — and why there is no install script
+
+The binary arrives as a **platform package** (`ai2rules-harness-linux-x64` and
+friends), listed in `optionalDependencies`. npm resolves exactly one by `os`/`cpu`
+and skips the rest.
+
+That means installing this package runs **no install script, makes no network
+request, executes no shell, and chmods nothing**. Earlier versions downloaded a
+binary in a `postinstall` and verified a checksum fetched from the same host — which
+proves the file arrived intact, not that it is the right file. Now the binary is
+covered by the integrity hash npm writes into *your* lockfile, and the tarballs
+carry [npm provenance](https://docs.npmjs.com/generating-provenance-statements)
+signed against the workflow and commit that built them.
+
+Practical upshots: installs are reproducible, work offline from a cache, and work
+behind a proxy or a mirrored registry — none of which was true before.
+
+If your platform has no prebuilt binary, nothing silently breaks: the CLI tells you
+how to build one, or you point `AI2RULES_HARNESS` at an existing binary.
 
 ## What it does
 
@@ -54,10 +75,12 @@ looks like.
 Effective on the very next tool call, no restart:
 
 ```bash
-touch .claude/gate-off      # this project
-touch ~/.claude/gate-off    # everywhere
+touch ~/.claude/ai2rules/off/<your-project>   # this project
+touch ~/.claude/gate-off                      # everywhere
 ```
 
+`harness init` prints the exact per-project path. Both live **outside** the
+governed project on purpose: a switch inside it is one the agent can throw itself.
 Delete the file to re-enable. The shim runs per call, so the toggle is immediate.
 
 ## Honest boundaries

package/bin/harness.js

@@ -1,26 +1,58 @@
 #!/usr/bin/env node
-// Thin launcher: exec the real Rust binary, pass through argv, exit with its code.
+// Launcher: find the prebuilt binary and exec it, passing argv through.
 //
-// No logic lives here. This file exists so `npx ai2rules-harness init` works, and
-// so a missing binary produces one clear sentence instead of a stack trace.
+// There is no install script. The binary arrives as an `optionalDependencies`
+// entry that npm resolves by `os`/`cpu` — exactly one matches, the rest are
+// skipped — so installing this package performs **no network access, no shell
+// execution, and no chmod**. That is not a score optimisation: it means the
+// binary you run is covered by the integrity hash npm already wrote into your
+// lockfile, rather than by a checksum this package fetched from the same host it
+// fetched the binary from. The old design proved integrity; this one has
+// provenance.
+//
+// Escape hatch for unsupported platforms and for development: set
+// AI2RULES_HARNESS to an absolute path and it is used verbatim.
 
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
-const vendored = path.join(
-  __dirname,
-  '..',
-  'vendor',
-  process.platform === 'win32' ? 'harness.exe' : 'harness'
-);
-const bin = process.env.AI2RULES_HARNESS || vendored;
+const PKG = {
+  'linux-x64': 'ai2rules-harness-linux-x64',
+  'darwin-x64': 'ai2rules-harness-darwin-x64',
+  'darwin-arm64': 'ai2rules-harness-darwin-arm64',
+  'win32-x64': 'ai2rules-harness-windows-x64', // `win32` in an unscoped
+  // package name is rejected by npm's spam filter; the platform key is unchanged
+};
+
+function resolveBinary() {
+  const override = process.env.AI2RULES_HARNESS;
+  if (override) return { bin: override, how: 'AI2RULES_HARNESS' };
+
+  const key = `${process.platform}-${process.arch}`;
+  const pkg = PKG[key];
+  if (!pkg) return { bin: null, why: `no prebuilt binary is published for ${key}` };
+
+  const exe = process.platform === 'win32' ? 'harness.exe' : 'harness';
+  try {
+    // Resolve through the package's own manifest so this works with npm,
+    // pnpm and yarn layouts alike rather than assuming node_modules is flat.
+    const manifest = require.resolve(`${pkg}/package.json`);
+    return { bin: path.join(path.dirname(manifest), exe), how: pkg };
+  } catch {
+    return {
+      bin: null,
+      why: `the optional dependency ${pkg} is not installed (it may have been skipped by --no-optional, or filtered by a lockfile from a different platform)`,
+    };
+  }
+}
+
+const { bin, why, how } = resolveBinary();
 
-if (!fs.existsSync(bin)) {
-  console.error(`ai2rules-harness: no binary at ${bin}
+if (!bin || !fs.existsSync(bin)) {
+  console.error(`ai2rules-harness: no usable binary — ${why || `${bin} is missing`}
 
-The postinstall step did not install one for ${process.platform}-${process.arch}.
-Build it, or point at an existing binary:
+Build one, or point at an existing binary:
 
     cargo install --git https://github.com/sv-pro/ai2rules cli-harness
     export AI2RULES_HARNESS=/absolute/path/to/harness
@@ -30,7 +62,7 @@ Build it, or point at an existing binary:
 
 const res = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });
 if (res.error) {
-  console.error(`ai2rules-harness: cannot execute ${bin}: ${res.error.message}`);
+  console.error(`ai2rules-harness: cannot execute ${bin} (via ${how}): ${res.error.message}`);
   process.exit(126);
 }
 process.exit(res.status === null ? 1 : res.status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai2rules-harness",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Deterministic governance for local CLI coding agents. `npx ai2rules-harness init` governs a project in one command.",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -22,17 +22,19 @@
   "bin": {
     "harness": "bin/harness.js"
   },
-  "scripts": {
-    "postinstall": "node install.js"
-  },
   "files": [
     "bin/harness.js",
-    "install.js",
     "README.md",
     "LICENSE-MIT",
     "LICENSE-APACHE"
   ],
   "engines": {
     "node": ">=18"
+  },
+  "optionalDependencies": {
+    "ai2rules-harness-darwin-arm64": "0.2.0",
+    "ai2rules-harness-darwin-x64": "0.2.0",
+    "ai2rules-harness-linux-x64": "0.2.0",
+    "ai2rules-harness-windows-x64": "0.2.0"
   }
 }

package/install.js

@@ -1,144 +0,0 @@
-#!/usr/bin/env node
-// postinstall — fetch the prebuilt `harness` for this platform.
-//
-// The asset names, targets and archive formats here mirror
-// `.github/workflows/release.yml` exactly. If that matrix changes, this map has
-// to change with it; `npm/verify-targets.js` fails the build when they drift.
-//
-// Deliberate properties, because this runs on other people's machines as part of
-// installing a *security* tool:
-//
-//   * One file, one host, and the URL derives from this package's version —
-//     never from anything in the user's project.
-//   * The SHA-256 is verified against the digest published beside the asset. A
-//     missing or mismatched checksum is a hard failure, not a warning.
-//   * On any failure it exits 0 with instructions rather than breaking the
-//     install of whatever depends on it. `bin/harness.js` reports the missing
-//     binary if and when someone actually runs it.
-//
-// Offline / air-gapped: set AI2RULES_HARNESS to an existing binary and nothing
-// is downloaded at all.
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const crypto = require('crypto');
-const { spawnSync } = require('child_process');
-const { pipeline } = require('stream/promises');
-
-const REPO = 'sv-pro/ai2rules';
-const VERSION = require('./package.json').version;
-const VENDOR = path.join(__dirname, 'vendor');
-const EXE = process.platform === 'win32' ? 'harness.exe' : 'harness';
-
-// npm `${platform}-${arch}` -> what release.yml actually publishes.
-// Linux is **musl** (statically linked, so it runs on any distro). There is no
-// aarch64-linux build in the matrix yet; that platform correctly falls through
-// to the build-from-source hint rather than downloading something wrong.
-const TARGETS = {
-  'linux-x64': { target: 'x86_64-unknown-linux-musl', archive: 'tar.gz' },
-  'darwin-arm64': { target: 'aarch64-apple-darwin', archive: 'tar.gz' },
-  'darwin-x64': { target: 'x86_64-apple-darwin', archive: 'tar.gz' },
-  'win32-x64': { target: 'x86_64-pc-windows-msvc', archive: 'zip' },
-};
-
-function hint(reason) {
-  console.error(`
-ai2rules-harness: ${reason}
-
-No prebuilt binary was installed. You can still build one:
-
-    cargo install --git https://github.com/${REPO} cli-harness
-
-then run \`harness init\` in a project. If you already have a binary:
-
-    export AI2RULES_HARNESS=/absolute/path/to/harness
-`);
-}
-
-async function download(url, dest) {
-  const res = await fetch(url, { redirect: 'follow' });
-  if (!res.ok) throw new Error(`GET ${url} -> HTTP ${res.status}`);
-  await fs.promises.mkdir(path.dirname(dest), { recursive: true });
-  await pipeline(res.body, fs.createWriteStream(dest));
-}
-
-async function fetchText(url) {
-  const res = await fetch(url, { redirect: 'follow' });
-  if (!res.ok) throw new Error(`GET ${url} -> HTTP ${res.status}`);
-  return (await res.text()).trim();
-}
-
-function sha256(file) {
-  return new Promise((resolve, reject) => {
-    const h = crypto.createHash('sha256');
-    fs.createReadStream(file)
-      .on('data', (d) => h.update(d))
-      .on('end', () => resolve(h.digest('hex')))
-      .on('error', reject);
-  });
-}
-
-// `tar` extracts both .tar.gz and .zip: GNU/bsdtar on Unix, and bsdtar has
-// shipped as tar.exe on Windows 10+ since 1803. Avoids a dependency for a
-// package whose whole point is that it installs cleanly.
-function extract(archive, dir) {
-  const res = spawnSync('tar', ['-xf', archive, '-C', dir], { stdio: 'pipe' });
-  if (res.error) throw new Error(`cannot run tar: ${res.error.message}`);
-  if (res.status !== 0) {
-    throw new Error(`tar failed: ${res.stderr?.toString().trim() || `exit ${res.status}`}`);
-  }
-}
-
-async function main() {
-  const override = process.env.AI2RULES_HARNESS;
-  if (override) {
-    if (!fs.existsSync(override)) {
-      hint(`AI2RULES_HARNESS points at ${override}, which does not exist.`);
-      return;
-    }
-    console.log(`ai2rules-harness: using AI2RULES_HARNESS=${override}`);
-    return;
-  }
-
-  const key = `${process.platform}-${process.arch}`;
-  const spec = TARGETS[key];
-  if (!spec) {
-    hint(`no prebuilt binary for ${key} (${os.type()}).`);
-    return;
-  }
-
-  const name = `harness-${spec.target}.${spec.archive}`;
-  const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${name}`;
-  const tmp = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'ai2rules-'));
-  const archive = path.join(tmp, name);
-
-  try {
-    await download(url, archive);
-
-    const expected = (await fetchText(`${url}.sha256`)).split(/\s+/)[0];
-    const actual = await sha256(archive);
-    if (!expected || expected !== actual) {
-      throw new Error(`checksum mismatch\n  expected ${expected || '(none published)'}\n  actual   ${actual}`);
-    }
-
-    extract(archive, tmp);
-    // The archive contains `harness-<target>/harness` — staged that way so it
-    // has no nested target/.../release path.
-    const unpacked = path.join(tmp, `harness-${spec.target}`, EXE);
-    if (!fs.existsSync(unpacked)) throw new Error(`archive did not contain ${EXE}`);
-
-    await fs.promises.mkdir(VENDOR, { recursive: true });
-    await fs.promises.copyFile(unpacked, path.join(VENDOR, EXE));
-    if (process.platform !== 'win32') await fs.promises.chmod(path.join(VENDOR, EXE), 0o755);
-
-    console.log(`ai2rules-harness: installed ${spec.target} (sha256 ${actual.slice(0, 12)}…)`);
-  } catch (err) {
-    await fs.promises.rm(VENDOR, { recursive: true, force: true }).catch(() => {});
-    hint(`could not install a prebuilt binary: ${err.message}`);
-  } finally {
-    await fs.promises.rm(tmp, { recursive: true, force: true }).catch(() => {});
-  }
-}
-
-main().catch((err) => hint(String(err && err.message ? err.message : err)));