harborloop 0.3.0 → 0.4.1

package/bin/checksums.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.4.1",
+  "algorithm": "sha256",
+  "binaries": {
+    "@gethrbr/harborloop-darwin-arm64": "d72a976949c98fb1410dd2f6bec31f9cebebf30ff3f73b056b3a4012bacedd64",
+    "@gethrbr/harborloop-darwin-x64": "e76a70f27d75038ba55c41d5f78d429fd09a82349dc851506fbdc4e0e197f865",
+    "@gethrbr/harborloop-linux-x64": "449c5b3ae98dd2d45f3cf541bc3a4a0a6a8b3968b3a383e09e317d0a94c1dec6",
+    "@gethrbr/harborloop-linux-arm64": "719cce2ae6d78db23a89c1b700c6258090b40267acefe259cf3590b26195f5ba",
+    "@gethrbr/harborloop-linux-x64-musl": "26d7862226f11b897a4604c038859bdbff0e23dde8eeb162ae5ae0635ac32d2d",
+    "@gethrbr/harborloop-win32-x64": "c2e0652c69f8332f947936916215d8b0e780e16b1a3b9cccd826a795a6a61a09"
+  }
+}

package/bin/harbor.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * The published `harbor` command: find this machine's binary, prove it is ours,
+ * and run it.
+ *
+ * The binary is 60-86 MB per platform, so shipping all six in one tarball would
+ * be a 435 MB install to use one of them. Instead each platform is its own
+ * package, declared as an OPTIONAL dependency with `os`/`cpu` fields; npm
+ * installs exactly the one that matches and skips the rest. This shim is the
+ * only JavaScript that ships.
+ *
+ * The hooks do NOT come through here. `harbor init` hardlinks them straight to
+ * the binary, so the per-prompt path pays nothing for this indirection, which
+ * matters because it runs on every prompt and every tool call.
+ */
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { closeSync, openSync, readFileSync, readSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * musl and glibc need different binaries and both report `linux`/`x64`.
+ *
+ * `process.report` names the glibc it is running against; on Alpine there is no
+ * glibc and the field is absent. Getting this wrong is not a graceful
+ * degradation, it is a binary that dies with a linker error most users cannot
+ * read, so the check is explicit rather than inferred from a distro name.
+ */
+export function isMusl(platform = process.platform, report = () => process.report?.getReport()) {
+  if (platform !== 'linux') return false;
+  try {
+    const r = report();
+    const header = typeof r === 'object' && r !== null ? r.header : null;
+    return !(header && typeof header.glibcVersionRuntime === 'string');
+  } catch {
+    return false;
+  }
+}
+
+export function platformPackage(platform = process.platform, arch = process.arch, musl = isMusl(platform)) {
+  if (platform === 'darwin' && arch === 'arm64') return '@gethrbr/harborloop-darwin-arm64';
+  if (platform === 'darwin' && arch === 'x64') return '@gethrbr/harborloop-darwin-x64';
+  if (platform === 'linux' && arch === 'arm64') return '@gethrbr/harborloop-linux-arm64';
+  if (platform === 'linux' && arch === 'x64')
+    return musl ? '@gethrbr/harborloop-linux-x64-musl' : '@gethrbr/harborloop-linux-x64';
+  if (platform === 'win32' && arch === 'x64') return '@gethrbr/harborloop-win32-x64';
+  return null;
+}
+
+/**
+ * Hash a file in 1 MB chunks rather than reading it whole.
+ *
+ * 62-86 MB through `readFileSync` is 86 MB of resident memory a moment before
+ * we spawn a second process that needs its own. Chunked is the same 40 ms and a
+ * bounded footprint.
+ */
+export function sha256File(path) {
+  const hash = createHash('sha256');
+  const buf = Buffer.allocUnsafe(1024 * 1024);
+  const fd = openSync(path, 'r');
+  try {
+    let read;
+    while ((read = readSync(fd, buf, 0, buf.length, null)) > 0) hash.update(buf.subarray(0, read));
+  } finally {
+    closeSync(fd);
+  }
+  return hash.digest('hex');
+}
+
+/**
+ * 🔒 **Does the binary on disk match the one this release published?**
+ *
+ * The threat is not hypothetical enough to skip. This shim `require.resolve`s an
+ * executable out of a SEPARATE npm package and runs it with the user's full
+ * privileges, and the program it runs edits `~/.claude.json` and installs hooks
+ * that fire on every prompt. Six extra package names is six extra ways in: a
+ * leaked token scoped to one of them, an internal registry mirror that rewrites
+ * tarballs, or anything with write access to `node_modules` after install.
+ *
+ * `checksums.json` is generated from the exact bytes packed into each platform
+ * package and ships INSIDE this wrapper, so the two travel together in one
+ * publish. An attacker who controls a platform package but not the wrapper
+ * cannot make this function say yes.
+ *
+ * ⚠️ It fails CLOSED, including when the manifest is missing or has no entry for
+ * this platform. A build of ours always has one — `release.mjs` refuses to
+ * publish otherwise and a test asserts it — so absence is not a version of ours
+ * running, it is the signature the check exists to catch.
+ */
+export function verifyIntegrity(binary, manifestPath, pkg) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return { ok: false, reason: `integrity manifest is missing or unreadable at ${manifestPath}` };
+  }
+  if (manifest.algorithm !== 'sha256') {
+    return { ok: false, reason: `integrity manifest uses unknown algorithm ${String(manifest.algorithm)}` };
+  }
+  const expected = manifest.binaries?.[pkg];
+  if (typeof expected !== 'string' || expected.length !== 64) {
+    return { ok: false, reason: `integrity manifest has no sha256 for ${pkg}` };
+  }
+  let actual;
+  try {
+    actual = sha256File(binary);
+  } catch (err) {
+    return { ok: false, reason: `could not read ${binary}: ${err.message}` };
+  }
+  if (actual !== expected) {
+    return { ok: false, reason: `${binary}\n  expected sha256 ${expected}\n  found    sha256 ${actual}` };
+  }
+  return { ok: true };
+}
+
+function main(argv = process.argv.slice(2)) {
+  const pkg = platformPackage();
+  if (pkg === null) {
+    process.stderr.write(
+      `harbor: no build for ${process.platform}/${process.arch}.\n` +
+        `Supported: macOS (arm64, x64), Linux (x64, arm64, x64-musl), Windows (x64).\n`
+    );
+    return 1;
+  }
+
+  let binary;
+  try {
+    binary = require.resolve(`${pkg}/bin/harbor${process.platform === 'win32' ? '.exe' : ''}`);
+  } catch {
+    // An optional dependency that failed to install is SILENT by design, so this
+    // is the only place a user ever learns it happened. Naming the package is the
+    // difference between an actionable message and a mystery.
+    process.stderr.write(
+      `harbor: the binary for ${process.platform}/${process.arch} is not installed.\n` +
+        `It ships as the optional dependency ${pkg}.\n` +
+        `Reinstall with:  npm install ${pkg}\n` +
+        `If you installed with --no-optional, that flag is why.\n`
+    );
+    return 1;
+  }
+
+  // The escape hatch exists so a mismatch is a support ticket rather than an
+  // unusable install, and it is loud on every run so it cannot become the
+  // permanent state of someone's machine without them knowing.
+  if (process.env.HARBOR_SKIP_INTEGRITY === '1') {
+    process.stderr.write('harbor: HARBOR_SKIP_INTEGRITY=1 — running an UNVERIFIED binary.\n');
+  } else {
+    const manifest = join(dirname(fileURLToPath(import.meta.url)), 'checksums.json');
+    const verdict = verifyIntegrity(binary, manifest, pkg);
+    if (!verdict.ok) {
+      process.stderr.write(
+        `harbor: refusing to run — the binary does not match this release.\n` +
+          `  ${verdict.reason}\n` +
+          `Reinstall with:  npm install --force harborloop\n` +
+          `If you build harbor yourself, run the binary directly instead of through this shim.\n`
+      );
+      return 1;
+    }
+  }
+
+  // `stdio: 'inherit'` so the child owns the real terminal: `harbor login` opens a
+  // browser and prints a URL, and `doctor` renders a table. Neither survives being
+  // piped through a parent that buffers.
+  const result = spawnSync(binary, argv, { stdio: 'inherit' });
+  if (result.error) {
+    process.stderr.write(`harbor: could not run ${binary}: ${result.error.message}\n`);
+    return 1;
+  }
+  // A signalled child has a null status. Report it the way a shell would, so a
+  // Ctrl-C is not reported as a clean exit.
+  return result.status === null ? 1 : result.status;
+}
+
+// npm links this file into `node_modules/.bin` as a SYMLINK, so `argv[1]` is the
+// link and `import.meta.url` is the target. `realpath` is what makes them equal.
+// A shim that cannot tell must still run: refusing would brick the command.
+let isEntry = true;
+try {
+  isEntry =
+    process.argv[1] === undefined || realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+} catch {
+  isEntry = true;
+}
+if (isEntry) process.exit(main());

package/package.json

@@ -1,43 +1,21 @@
 {
   "name": "harborloop",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Install and health-check the harbor knowledge loop in your terminal. Recall in Claude Code, Codex and Cursor; a doctor that can say no.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://gethrbr.com",
   "bin": {
-    "harbor": "dist/index.js"
+    "harbor": "bin/harbor.mjs"
   },
-  "main": "dist/api.js",
-  "types": "dist/api.d.ts",
   "files": [
-    "dist",
-    "hooks",
+    "bin",
     "LICENSE",
     "README.md"
   ],
   "engines": {
     "node": ">=18"
   },
-  "publishConfig": {
-    "//": "A scoped package defaults to RESTRICTED, and `npm publish` on a scope with no paid plan fails outright rather than publishing privately. This is the whole difference between a wedge anybody can `npx` and a 402.",
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.hooks.json",
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "//pretest": "Three suites EXECUTE hooks/*.mjs by path (recall-redelivery.test.ts:29 and friends). Those used to be tracked source, so a checkout was enough; they are build output now, and CI runs tests BEFORE build. Without this, npm test passes locally off a stale hooks/ and fails on a clean clone.",
-    "pretest": "tsc -p tsconfig.hooks.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "e2e": "npm run e2e:offline && node e2e/loop.e2e.mjs",
-    "e2e:offline": "node e2e/offline.mjs",
-    "e2e:hooks": "node e2e/hooks.e2e.mjs",
-    "e2e:loop": "node e2e/loop.e2e.mjs",
-    "//prepublishOnly": "`files` ships `dist`, and NOTHING re-derived it from the tree being published \u2014 a stale `dist` was one `npm publish` away, and the tarball is exactly what nobody looks inside. Not `prepack`, which would also fire on the `npm pack` the e2e harness runs.",
-    "prepublishOnly": "npm run typecheck && npm run test && npm run build && npm run e2e:offline"
-  },
   "keywords": [
     "claude-code",
     "codex",
@@ -47,10 +25,16 @@
     "knowledge-graph",
     "agents.md"
   ],
-  "devDependencies": {
-    "@types/node": "^22.10.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+  "optionalDependencies": {
+    "@gethrbr/harborloop-darwin-arm64": "0.4.1",
+    "@gethrbr/harborloop-darwin-x64": "0.4.1",
+    "@gethrbr/harborloop-linux-x64": "0.4.1",
+    "@gethrbr/harborloop-linux-arm64": "0.4.1",
+    "@gethrbr/harborloop-linux-x64-musl": "0.4.1",
+    "@gethrbr/harborloop-win32-x64": "0.4.1"
+  },
+  "publishConfig": {
+    "//": "A scoped package defaults to RESTRICTED, and `npm publish` on a scope with no paid plan fails outright rather than publishing privately. This is the whole difference between a wedge anybody can `npx` and a 402.",
+    "access": "public"
   }
 }

package/dist/api.d.ts

@@ -1,109 +0,0 @@
-export type ApiFailureKind = 'unauthorized' | 'forbidden' | 'payment_required' | 'not_found' | 'rate_limited' | 'server' | 'network' | 'shape';
-export declare class ApiError extends Error {
-    readonly kind: ApiFailureKind;
-    readonly status: number | null;
-    readonly body: unknown;
-    constructor(kind: ApiFailureKind, message: string, status?: number | null, body?: unknown);
-}
-export interface RequestOptions {
-    readonly method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    readonly body?: unknown;
-    readonly bearer?: string | null;
-    readonly timeoutMs?: number;
-    readonly fetchImpl?: typeof fetch;
-}
-export declare function apiRequest<T>(url: string, opts?: RequestOptions): Promise<T>;
-export declare function describeRetryAfter(headers: Headers, now?: number): string;
-export interface ExchangeResult {
-    readonly token: string;
-}
-export declare function exchangeAuthCode(apiUrl: string, code: string, codeVerifier: string, fetchImpl?: typeof fetch): Promise<string>;
-export declare function refreshRunnerToken(apiUrl: string, runnerToken: string, fetchImpl?: typeof fetch): Promise<string>;
-export interface Workspace {
-    readonly id: string;
-    readonly name: string;
-}
-export interface CurrentUser {
-    readonly id: string;
-    readonly email: string;
-    readonly name: string;
-    readonly lastWorkspaceId: string | null;
-}
-export declare function fetchCurrentUser(apiUrl: string, runnerToken: string, fetchImpl?: typeof fetch): Promise<CurrentUser>;
-export declare function listWorkspaces(apiUrl: string, runnerToken: string, fetchImpl?: typeof fetch): Promise<Workspace[]>;
-export interface MintedToken {
-    readonly token: string;
-    readonly expiresIn: string;
-    readonly connectionId: string;
-}
-export declare function mintMcpToken(apiUrl: string, runnerToken: string, workspaceId: string, provider: string, fetchImpl?: typeof fetch): Promise<MintedToken>;
-export interface RepoBinding {
-    readonly id: string;
-    readonly originUrl: string;
-    readonly displayName: string | null;
-    readonly projectId: string | null;
-    readonly projectName: string | null;
-}
-export declare function listRepoBindings(apiUrl: string, runnerToken: string, workspaceId: string, fetchImpl?: typeof fetch): Promise<RepoBinding[]>;
-export declare function createRepoBinding(apiUrl: string, runnerToken: string, workspaceId: string, input: {
-    originUrl: string;
-    displayName?: string;
-    projectId?: string | null;
-}, fetchImpl?: typeof fetch): Promise<RepoBinding>;
-export interface Project {
-    readonly id: string;
-    readonly name: string;
-}
-export declare function listProjects(apiUrl: string, runnerToken: string, workspaceId: string, fetchImpl?: typeof fetch): Promise<Project[]>;
-export interface LoopMetrics {
-    readonly windowDays: number;
-    readonly projectId: string | null;
-    readonly recall: {
-        sessions: number;
-        served: number;
-    };
-    readonly fit: {
-        servedAtoms: number;
-        citedAtoms: number;
-        avgBundle: number | null;
-    };
-    readonly attribution: {
-        recalls: number;
-        keyed: number;
-    };
-    readonly contributed: {
-        total: number;
-        approved: number;
-        pending: number;
-    };
-    readonly corpus?: {
-        admitted: number;
-        retired: number;
-        liveAtoms: number;
-        retiredByCause?: {
-            cause: string;
-            count: number;
-        }[];
-        ledgerEmpty: boolean;
-    };
-    readonly byTransport?: {
-        transport: string;
-        label: string;
-        recalls: number;
-        keyed: number;
-        clients: string[];
-    }[];
-    readonly spend?: {
-        writeSpendCents: number;
-        writeSpendUsd: number;
-        spendRows: number;
-        unpricedRows: number;
-        citedAtoms: number;
-        costPerCitedAtomUsd: number | null;
-    };
-}
-export declare function parseLoopMetrics(data: unknown): LoopMetrics;
-export declare function fetchLoopMetrics(apiUrl: string, mcpToken: string, params?: {
-    originUrl?: string;
-    windowDays?: number;
-}, fetchImpl?: typeof fetch): Promise<LoopMetrics>;