@nothumanwork/nn 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Human Works
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# nn
+
+Neural Net — multi-provider transcript fabric for AI coding agents.
+
+Ingest, search, export, and sync conversation transcripts across Cursor, Claude Code, Codex, Pi, Grok, Antigravity, and more.
+
+## Install
+
+```bash
+npx @nothumanwork/nn --help
+```
+
+Or install globally:
+
+```bash
+npm install -g @nothumanwork/nn
+nn --help
+```
+
+## Quick start
+
+```bash
+# Install hooks for all supported providers (project-local)
+nn install hooks
+
+# Install hooks globally
+nn install hooks --global
+
+# Ingest transcripts from a provider
+nn ingest --provider cursor --all
+
+# Search normalized events
+nn search "turso sync"
+
+# List sessions
+nn sessions list
+
+# Export a session (stdout by default)
+nn export --session <id>
+
+# Check local DB and sync health
+nn doctor
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `nn install hooks [--global] [--provider <id>]` | Install agent hooks |
+| `nn hook --provider <id> --event <kind>` | Hook entrypoint (used by agents) |
+| `nn ingest --provider <id> [--session <id>] [--all]` | Ingest provider transcripts |
+| `nn export --session <id> [--to <target>] [--output <file>]` | Export a session |
+| `nn search <query> [--limit <n>]` | Search transcript events |
+| `nn sessions list [--provider <id>]` | List ingested sessions |
+| `nn sync status\|push\|pull` | Turso embedded-replica sync |
+| `nn doctor` | Validate DB, hooks, and sync setup |
+
+## Configuration
+
+Local state lives in `.nn/state/` (override with `NN_STATE_DIR` or `NN_DB_PATH`).
+
+Turso sync is optional — set `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN` to enable cloud sync.
+
+## Development
+
+This package ships prebuilt Bun-compiled binaries per platform. To build from source:
+
+```bash
+bun install
+bun run build          # host platform only
+bun run build:all      # all publish targets
+bun test
+```
+
+## License
+
+MIT

package/bin/nn.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const sourceEntry = join(packageRoot, "src/index.ts");
+
+function isGlibcLinux() {
+  if (process.platform !== "linux") {
+    return false;
+  }
+  try {
+    return Boolean(process.report?.getReport().header.glibcVersionRuntime);
+  } catch {
+    return true;
+  }
+}
+
+function activeTargetName() {
+  const { platform, arch } = process;
+  if (platform === "darwin") {
+    return `${platform}-${arch}`;
+  }
+  if (platform === "linux" && arch === "arm64") {
+    return isGlibcLinux() ? "linux-arm64-gnu" : "linux-arm64-musl";
+  }
+  if (platform === "linux" && arch === "x64") {
+    return isGlibcLinux() ? "linux-x64-gnu" : "linux-x64-musl";
+  }
+  if (platform === "win32" && arch === "x64") {
+    return "win32-x64";
+  }
+  return undefined;
+}
+
+function resolvePlatformBinary() {
+  const targetName = activeTargetName();
+  if (!targetName) {
+    return undefined;
+  }
+
+  const pkg = `@nothumanwork/nn-${targetName}`;
+  const isWindows = targetName === "win32-x64";
+  try {
+    const pkgRoot = dirname(require.resolve(`${pkg}/package.json`));
+    const binaryPath = join(pkgRoot, "bin", isWindows ? "nn.exe" : "nn");
+    return existsSync(binaryPath) ? binaryPath : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function findBun() {
+  const bunFromPath = spawnSync("bun", ["--version"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (bunFromPath.status === 0) {
+    return "bun";
+  }
+  return undefined;
+}
+
+function run(cmd, args) {
+  const result = spawnSync(cmd, args, {
+    stdio: "inherit",
+    env: process.env,
+  });
+  if (result.error) {
+    console.error(`nn: failed to run ${cmd}: ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 1);
+}
+
+const args = process.argv.slice(2);
+const binaryPath = resolvePlatformBinary();
+
+if (binaryPath) {
+  run(binaryPath, args);
+}
+
+if (!existsSync(sourceEntry)) {
+  console.error(
+    `nn: no prebuilt binary for ${process.platform}-${process.arch} and source entry is unavailable.`,
+  );
+  process.exit(1);
+}
+
+const bun = findBun();
+if (!bun) {
+  console.error(
+    `nn: no prebuilt binary for ${process.platform}-${process.arch}. Install Bun (https://bun.sh) or use a supported platform.`,
+  );
+  process.exit(1);
+}
+
+console.warn(
+  `nn: using Bun fallback for ${process.platform}-${process.arch} (platform package not installed)`,
+);
+run(bun, ["run", sourceEntry, ...args]);

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@nothumanwork/nn",
+  "version": "0.1.0",
+  "description": "Neural Net — multi-provider transcript fabric for AI coding agents",
+  "type": "module",
+  "license": "MIT",
+  "author": "The Human Works",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thehumanworks/nn.git"
+  },
+  "homepage": "https://github.com/thehumanworks/nn#readme",
+  "bugs": {
+    "url": "https://github.com/thehumanworks/nn/issues"
+  },
+  "keywords": [
+    "cursor",
+    "claude",
+    "codex",
+    "transcripts",
+    "ai-agents",
+    "hooks",
+    "sqlite",
+    "turso"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "nn": "./bin/nn.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "nn": "doppler run --config prd --project vault -- bun run src/index.ts",
+    "build": "bun run scripts/build.ts",
+    "build:all": "bun run scripts/build-all.ts",
+    "prepare:platform-packages": "bun run scripts/prepare-platform-packages.ts",
+    "install:bin": "bun run scripts/build.ts --install",
+    "prepublishOnly": "bun run build:all && bun run prepare:platform-packages",
+    "publish:all": "bun run scripts/publish-npm.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@libsql/client": "^0.17.3"
+  },
+  "optionalDependencies": {
+    "@nothumanwork/nn-darwin-arm64": "0.1.0",
+    "@nothumanwork/nn-darwin-x64": "0.1.0",
+    "@nothumanwork/nn-linux-arm64-gnu": "0.1.0",
+    "@nothumanwork/nn-linux-arm64-musl": "0.1.0",
+    "@nothumanwork/nn-linux-x64-gnu": "0.1.0",
+    "@nothumanwork/nn-linux-x64-musl": "0.1.0",
+    "@nothumanwork/nn-win32-x64": "0.1.0"
+  },
+  "devDependencies": {
+    "@libsql/darwin-arm64": "0.5.29",
+    "@libsql/darwin-x64": "0.5.29",
+    "@libsql/linux-arm64-gnu": "0.5.29",
+    "@libsql/linux-arm64-musl": "0.5.29",
+    "@libsql/linux-x64-gnu": "0.5.29",
+    "@libsql/linux-x64-musl": "0.5.29",
+    "@libsql/win32-x64-msvc": "0.5.29",
+    "@types/bun": "latest"
+  }
+}

package/src/config/env.ts

@@ -0,0 +1,31 @@
+function readRaw(name: string): string | undefined {
+  const value = process.env[name]?.trim();
+  return value || undefined;
+}
+
+export function envString(name: string): string | undefined {
+  return readRaw(name);
+}
+
+export function envInt(name: string, defaultValue: number): number {
+  const raw = readRaw(name);
+  if (!raw) {
+    return defaultValue;
+  }
+  const value = Number(raw);
+  return Number.isFinite(value) && value >= 0 ? value : defaultValue;
+}
+
+export function envBool(name: string, defaultValue: boolean): boolean {
+  const raw = readRaw(name)?.toLowerCase();
+  if (!raw) {
+    return defaultValue;
+  }
+  if (["1", "true", "yes", "on"].includes(raw)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(raw)) {
+    return false;
+  }
+  return defaultValue;
+}

package/src/config/paths.ts

@@ -0,0 +1,50 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+import { envString } from "./env.ts";
+
+export const DB_BASENAME = "nn.db";
+export const LOCK_BASENAME = "nn-ingest.lock";
+
+export function projectDir(): string {
+  return envString("NN_PROJECT_DIR") || envString("CURSOR_PROJECT_DIR") || process.cwd();
+}
+
+/** Provider-agnostic project-local state (DB, sync coordinator, locks). */
+export function stateDir(): string {
+  const override = envString("NN_STATE_DIR");
+  if (override) {
+    return resolve(override);
+  }
+  return resolve(projectDir(), ".nn/state");
+}
+
+export function dbPath(): string {
+  const override = envString("NN_DB_PATH");
+  if (override) {
+    return resolve(override);
+  }
+  return resolve(stateDir(), DB_BASENAME);
+}
+
+export function lockPath(): string {
+  return resolve(stateDir(), LOCK_BASENAME);
+}
+
+export function homeDir(): string {
+  return homedir();
+}
+
+export function encodeProjectSlug(projectPath: string): string {
+  const normalized = projectPath.replace(/\\/g, "/");
+  if (normalized === "/") {
+    return "";
+  }
+  return normalized.replace(/^\//, "").replace(/\//g, "-").replace(/\./g, "-");
+}
+
+export function ensureProjectDir(cwd?: string): void {
+  if (cwd && !envString("NN_PROJECT_DIR") && !envString("CURSOR_PROJECT_DIR")) {
+    process.env.NN_PROJECT_DIR = cwd;
+  }
+}

package/src/config/runtime.ts

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+export function isCompiledExecutable(): boolean {
+  return import.meta.path.includes("/$bunfs/");
+}
+
+export function packageRoot(): string {
+  if (isCompiledExecutable()) {
+    return dirname(process.execPath);
+  }
+  return resolve(import.meta.dir, "../..");
+}
+
+export function cliEntrypoint(): string {
+  if (isCompiledExecutable()) {
+    return process.execPath;
+  }
+  return resolve(packageRoot(), "src/index.ts");
+}
+
+export function nnCommand(sourceRoot = packageRoot()): string {
+  if (isCompiledExecutable()) {
+    return process.execPath;
+  }
+  if (existsSync(resolve(sourceRoot, "src/index.ts"))) {
+    return `bun run ${resolve(sourceRoot, "src/index.ts")}`;
+  }
+  return `bun run ${cliEntrypoint()}`;
+}
+
+export function coordinatorSpawn(): { cmd: string[] } {
+  if (isCompiledExecutable()) {
+    return { cmd: [process.execPath, "__coordinator"] };
+  }
+  return { cmd: [process.execPath, cliEntrypoint(), "__coordinator"] };
+}

package/src/config/sync.ts

@@ -0,0 +1,48 @@
+import { join } from "node:path";
+
+import { envBool, envInt } from "./env.ts";
+import { stateDir } from "./paths.ts";
+
+export interface SyncConfig {
+  enabled: boolean;
+  debounceMs: number;
+  flushTimeoutMs: number;
+  syncIntervalMs: number;
+  pullOnSession: boolean;
+}
+
+function isValidTursoUrl(url: string): boolean {
+  if (url.includes("{{") || url.includes("}}")) {
+    return false;
+  }
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "libsql:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+export function tursoConfigured(): boolean {
+  const url = process.env.TURSO_DATABASE_URL?.trim();
+  const token = process.env.TURSO_AUTH_TOKEN?.trim();
+  if (!url || !token) {
+    return false;
+  }
+  return isValidTursoUrl(url);
+}
+
+export function syncConfig(): SyncConfig {
+  const configured = tursoConfigured();
+  return {
+    enabled: configured && envBool("NN_SYNC_ENABLED", true),
+    debounceMs: envInt("NN_SYNC_DEBOUNCE_MS", 3000),
+    flushTimeoutMs: envInt("NN_SYNC_FLUSH_TIMEOUT_MS", 5000),
+    syncIntervalMs: envInt("NN_SYNC_INTERVAL_MS", 0),
+    pullOnSession: envBool("NN_SYNC_PULL_ON_SESSION", configured),
+  };
+}
+
+export function coordinatorStatePath(): string {
+  return join(stateDir(), "sync-coordinator.json");
+}