@mattersec/matt 0.1.17

package/README.md

@@ -0,0 +1,59 @@
+# @mattersec/overwatch
+
+AI agent telemetry collector for developer machines. Monitors Claude Code, Cursor, and Codex hooks, captures events, forwards to the Mattersec security intelligence dashboard.
+
+## Install
+
+```
+npm install -g @mattersec/overwatch
+```
+
+### Installation notes
+
+On POSIX platforms the postinstall step replaces the JS shim with a direct symlink to the native binary so `overwatch` invocations skip Node cold-start entirely. If you install with `npm install -g --ignore-scripts` (common in locked-down corporate npm environments), the optimize step is skipped and every invocation pays ~30 ms of Node startup overhead. Functionally correct, just slower. To apply the optimization after an `--ignore-scripts` install:
+
+```
+node "$(npm root -g)/@mattersec/overwatch/install.js"
+```
+
+## Quickstart
+
+**Easiest path:** visit [overwatch.mattersec.com](https://overwatch.mattersec.com), sign up, and follow the install wizard. It hands you a one-time `npx @mattersec/overwatch link --token=…` command that authenticates this machine, installs your AI tool hooks, and starts the daemon — all in one paste.
+
+If you'd rather drive each step manually:
+
+```
+overwatch auth login                 # device-code flow
+overwatch install-hooks claude-code  # install hooks
+overwatch start                      # register background service + start daemon
+overwatch status
+```
+
+## Uninstall
+
+Because npm has no `preuninstall` hook, run the service cleanup explicitly before removing the package:
+
+```
+overwatch uninstall-service
+npm uninstall -g @mattersec/overwatch
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `overwatch start` | Register service + start daemon |
+| `overwatch stop` | Stop daemon (service registration stays) |
+| `overwatch status` | Print daemon / auth / events status |
+| `overwatch auth login/logout/status/whoami` | Auth subcommands |
+| `overwatch install-hooks <tool>` | Install hooks for `claude-code`, `cursor`, or `codex` |
+| `overwatch uninstall-hooks <tool>` | Remove hooks |
+| `overwatch check` | Hook installation status |
+| `overwatch buffer list/flush/clear` | Manage the encrypted event buffer |
+| `overwatch dashboard` | Open Mattersec dashboard in browser |
+| `overwatch update` | Update via npm registry |
+| `overwatch uninstall-service` | Remove service registration |
+
+## License
+
+Proprietary — © Mattersec Labs.

package/bin/matt

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// JS shim for `@mattersec/matt`. On first install (and during `npx`
+// runs that don't get to run install.js before invoking us), this file is
+// what gets symlinked into PATH. We resolve the platform-specific
+// optionalDependency at runtime and exec the native binary.
+//
+// `install.js` (postinstall) replaces this file with a direct symlink to the
+// native binary so subsequent invocations skip the Node startup cost (~30 ms).
+// If install.js fails for any reason, this shim keeps working — slow, but
+// correct.
+'use strict';
+
+const { spawn } = require('child_process');
+
+const { platform, arch } = process;
+
+function detectLibc() {
+  if (platform !== 'linux') return null;
+  try {
+    const report = process.report && process.report.getReport();
+    if (report && report.header && report.header.glibcVersionRuntime) {
+      return 'gnu';
+    }
+    return 'musl';
+  } catch (_) {
+    return 'gnu';
+  }
+}
+
+const libc = detectLibc();
+const triple = libc ? `${platform}-${arch}-${libc}` : `${platform}-${arch}`;
+const pkgName = `@mattersec/matt-${triple}`;
+const binExt = platform === 'win32' ? '.exe' : '';
+
+let binPath;
+try {
+  binPath = require.resolve(`${pkgName}/matt${binExt}`);
+} catch (_) {
+  process.stderr.write(
+    `matt: platform '${triple}' is not supported, or '${pkgName}' was ` +
+      `not installed. If your platform is supported, this usually means npm ` +
+      `skipped the optionalDependency for your OS/arch. Please open an issue at:\n` +
+      `  https://github.com/mattersec-labs/overwatch-cli/issues\n`
+  );
+  process.exit(1);
+}
+
+// Use spawn (not spawnSync) so we forward stdin properly for interactive
+// commands like `matt link` that may prompt for OTP / browser approval.
+const child = spawn(binPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  // On Windows, `windowsHide: true` prevents a phantom console flash when
+  // the launched binary in turn spawns helper processes.
+  windowsHide: true,
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise the signal in our own process so parent shells see the right
+    // termination semantics (Ctrl-C → 130, etc.). spawn returns null code on
+    // signal-termination.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code === null ? 1 : code);
+});
+
+child.on('error', (err) => {
+  process.stderr.write(`matt: failed to spawn native binary: ${err.message}\n`);
+  process.exit(1);
+});

package/install.js

@@ -0,0 +1,170 @@
+// Post-install optimize: replace the JS shim at bin/matt with a direct
+// symlink (POSIX) or the Rust launcher .exe (Windows) to the platform binary.
+// Skipping Node from the CLI invocation hot path.
+//
+// Modeled on esbuild's `maybeOptimizePackage` — see
+// https://github.com/evanw/esbuild/blob/main/CHANGELOG-2021.md
+//
+// If anything fails, the JS shim remains in place and the CLI still works
+// (just slower by ~30 ms due to Node startup).
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { platform, arch } = process;
+
+function detectLibc() {
+  if (platform !== 'linux') return null;
+  try {
+    const report = process.report && process.report.getReport();
+    if (report && report.header && report.header.glibcVersionRuntime) {
+      return 'gnu';
+    }
+    return 'musl';
+  } catch (_) {
+    return 'gnu';
+  }
+}
+
+function resolvePlatformBinary() {
+  const libc = detectLibc();
+  const triple = libc ? `${platform}-${arch}-${libc}` : `${platform}-${arch}`;
+  const pkgName = `@mattersec/matt-${triple}`;
+  const binExt = platform === 'win32' ? '.exe' : '';
+  try {
+    return {
+      pkgName,
+      path: require.resolve(`${pkgName}/matt${binExt}`),
+    };
+  } catch (e) {
+    return { pkgName, path: null, error: e.message };
+  }
+}
+
+// Persist node + npm absolute paths so the daemon (which inherits a minimal
+// launchd/systemd PATH and won't see nvm/fnm/asdf installs) can spawn the
+// right `npm install -g` at auto-update time. Best-effort: never throw.
+// See `src/update/install_meta.rs` for the consumer side.
+function writeInstallMeta() {
+  try {
+    const home = os.homedir();
+    if (!home) return;
+    const dataDir = path.join(home, '.matt');
+    if (!fs.existsSync(dataDir)) {
+      fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+    }
+
+    let globalPrefix = process.env.npm_config_prefix || null;
+    if (!globalPrefix) {
+      try {
+        globalPrefix = execFileSync('npm', ['prefix', '-g'], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+          timeout: 5000,
+        }).trim() || null;
+      } catch (_) {
+        globalPrefix = null;
+      }
+    }
+
+    let pkgVersion = null;
+    try {
+      pkgVersion = require('./package.json').version || null;
+    } catch (_) { /* ignore */ }
+
+    const meta = {
+      node: process.execPath || null,
+      npm: process.env.npm_execpath || null,
+      global_prefix: globalPrefix,
+      package_version: pkgVersion,
+      captured_at: new Date().toISOString(),
+    };
+
+    const metaPath = path.join(dataDir, 'install_meta.json');
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+    if (platform !== 'win32') {
+      try { fs.chmodSync(metaPath, 0o600); } catch (_) { /* ignore */ }
+    }
+  } catch (e) {
+    // Never block install on this — daemon falls back to bare `npm` on PATH.
+    console.error(`matt: install_meta capture skipped (${e.message})`);
+  }
+}
+
+function optimizePosix(shimPath, platformBin) {
+  // Replace the JS shim with a symlink (fast) or a copy (fallback).
+  try {
+    fs.unlinkSync(shimPath);
+  } catch (_) {
+    /* ignore; file may not exist */
+  }
+  try {
+    fs.symlinkSync(platformBin, shimPath);
+    fs.chmodSync(shimPath, 0o755);
+    return;
+  } catch (e) {
+    // Symlinks failed (uncommon on POSIX) — fall back to copy.
+    try {
+      fs.copyFileSync(platformBin, shimPath);
+      fs.chmodSync(shimPath, 0o755);
+      return;
+    } catch (copyErr) {
+      console.error(
+        `matt: postinstall optimize failed (${copyErr.message}); ` +
+          `falling back to Node-shim invocation (~30 ms slower per call).`
+      );
+    }
+  }
+}
+
+function optimizeWindows(platformBin) {
+  // Copy the Rust launcher from the platform package's bin/ into the meta
+  // package's bin/ — this way npm's .cmd wrapper invokes the .exe directly
+  // (no Node). The launcher in turn CreateProcess's the platform binary.
+  const metaExePath = path.join(__dirname, 'bin', 'matt.exe');
+  // Look for a launcher sibling of the platform binary.
+  const platformDir = path.dirname(platformBin);
+  const launcherCandidate = path.join(platformDir, 'matt-launcher.exe');
+  try {
+    if (fs.existsSync(launcherCandidate)) {
+      fs.copyFileSync(launcherCandidate, metaExePath);
+      return;
+    }
+    // Fallback: copy the platform binary itself.
+    fs.copyFileSync(platformBin, metaExePath);
+  } catch (e) {
+    console.error(
+      `matt: postinstall optimize failed on Windows (${e.message}); ` +
+        `falling back to Node shim.`
+    );
+  }
+}
+
+(function main() {
+  writeInstallMeta();
+
+  const resolved = resolvePlatformBinary();
+  if (!resolved.path) {
+    // Platform not supported or package not installed — leave the JS shim in
+    // place. The shim itself will report the missing platform at invocation time.
+    return;
+  }
+
+  // Defensive: refuse to symlink outside node_modules (symlink-escape guard).
+  if (!path.resolve(resolved.path).includes(`${path.sep}node_modules${path.sep}`)) {
+    console.error(
+      `matt: refused to optimize bin — resolved path is outside node_modules: ${resolved.path}`
+    );
+    return;
+  }
+
+  if (platform === 'win32') {
+    optimizeWindows(resolved.path);
+  } else {
+    const shimPath = path.join(__dirname, 'bin', 'matt');
+    optimizePosix(shimPath, resolved.path);
+  }
+})();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mattersec/matt",
+  "version": "0.1.17",
+  "description": "matt — AI agent telemetry for developer machines",
+  "bin": {
+    "matt": "bin/matt"
+  },
+  "scripts": {
+    "postinstall": "node install.js",
+    "preuninstall": "node preuninstall.js"
+  },
+  "optionalDependencies": {
+    "@mattersec/matt-darwin-arm64": "=0.1.17",
+    "@mattersec/matt-darwin-x64": "=0.1.17",
+    "@mattersec/matt-linux-x64-gnu": "=0.1.17",
+    "@mattersec/matt-linux-arm64-gnu": "=0.1.17",
+    "@mattersec/matt-linux-x64-musl": "=0.1.17",
+    "@mattersec/matt-linux-arm64-musl": "=0.1.17",
+    "@mattersec/matt-win32-x64": "=0.1.17",
+    "@mattersec/matt-win32-arm64": "=0.1.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://mattersec.com",
+  "license": "SEE LICENSE IN LICENSE",
+  "files": [
+    "bin/",
+    "install.js",
+    "preuninstall.js",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mattersec-labs/overwatch-cli.git",
+    "directory": "npm/matt"
+  },
+  "bugs": {
+    "url": "https://github.com/mattersec-labs/overwatch-cli/issues"
+  }
+}

package/preuninstall.js

@@ -0,0 +1,36 @@
+'use strict';
+// Stop the daemon before npm deletes its binary.
+// On Windows, a running process holds an exclusive lock on its .exe file —
+// npm cannot delete it and leaves behind a broken partial uninstall.
+// Reading the PID file and terminating directly is the reliable fallback when
+// IPC is unavailable (e.g. npm uninstall run without matt stop first).
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const pidFile = path.join(os.homedir(), '.matt', 'matt.pid');
+
+try {
+    const pid = parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
+    if (!isNaN(pid) && pid > 0) {
+        try {
+            process.kill(pid, 0); // throws ESRCH if not running — nothing to do
+            process.kill(pid);    // SIGTERM on POSIX, TerminateProcess on Windows
+            // Poll up to 2 s for the process to exit and release file handles.
+            // Atomics.wait is synchronous sleep available in Node.js (not browsers).
+            const deadline = Date.now() + 2000;
+            while (Date.now() < deadline) {
+                try {
+                    process.kill(pid, 0);
+                } catch (_) {
+                    break; // process gone — safe for npm to delete files
+                }
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+            }
+        } catch (_) {
+            // ESRCH: process already gone — nothing to do
+        }
+    }
+} catch (_) {
+    // No PID file or unreadable — daemon not running
+}