@nothumanwork/nn 0.1.0

package/src/index.ts

@@ -0,0 +1,247 @@
+#!/usr/bin/env bun
+
+import "./db/libsql-native.ts";
+import { resolve } from "node:path";
+
+import { doctorDb } from "./db/migrate.ts";
+import { listSessions, searchEvents } from "./db/client.ts";
+import { exportSession, resolveSessionId } from "./export/registry.ts";
+import { ingestIncremental, ingestProvider } from "./ingest/pipeline.ts";
+import { installHooks } from "./install/index.ts";
+import { listProviders } from "./providers/registry.ts";
+import type { ProviderId } from "./ir/types.ts";
+import type { ExportTarget } from "./export/types.ts";
+import { syncPull, syncPush, syncStatus } from "./sync/turso.ts";
+import { runCoordinatorOnce } from "./sync/coordinator.ts";
+import { handleHookInvocation } from "./hooks/ingest.ts";
+import type { HookEventKind, HookPayload } from "./hooks/types.ts";
+import { HOOK_EVENTS } from "./hooks/types.ts";
+import { cursorSessionIdFromPath } from "./providers/cursor/index.ts";
+import { stdin } from "bun";
+
+const USAGE = `nn (Neural Net) — multi-provider transcript fabric
+
+Usage:
+  nn install hooks [--global] [--provider <id>]
+  nn hook --provider <id> --event <kind>
+  nn ingest --provider <provider> [--session <id>] [--all]
+  nn export --session <id> [--to <target>] [--output <file.jsonl>]
+  nn search <query> [--limit <n>]
+  nn sessions list [--provider <provider>]
+  nn sync status|push|pull
+  nn doctor
+
+Providers: ${listProviders().join(", ")}
+Export targets: generic, cursor, claude, codex, grok, pi, antigravity, copilot
+`;
+
+function printHelp(): void {
+  console.log(USAGE.trimEnd());
+}
+
+function parseFlag(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  if (index === -1) {
+    return undefined;
+  }
+  return args[index + 1];
+}
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+function parsePositiveInt(value: string, flag: string): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${flag} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function commandArgs(subcommand: string | undefined, rest: string[]): string[] {
+  return subcommand ? [subcommand, ...rest] : rest;
+}
+
+function searchArgs(args: string[]): { query: string; limit?: number } {
+  const limitRaw = parseFlag(args, "--limit");
+  const limit = limitRaw ? parsePositiveInt(limitRaw, "--limit") : undefined;
+  const query = args
+    .filter((arg, index, all) => {
+      if (arg === "--limit") {
+        return false;
+      }
+      if (index > 0 && all[index - 1] === "--limit") {
+        return false;
+      }
+      return true;
+    })
+    .join(" ")
+    .trim();
+  return { query, limit };
+}
+
+async function runHook(args: string[]): Promise<number> {
+  try {
+    const provider = parseFlag(args, "--provider") as ProviderId | undefined;
+    const hookEvent = parseFlag(args, "--event") as HookEventKind | undefined;
+    if (!provider || !hookEvent || !HOOK_EVENTS.includes(hookEvent)) {
+      console.error("usage: nn hook --provider <id> --event <kind>");
+      return 0;
+    }
+    const raw = await stdin.text();
+    const payload = raw.trim() ? (JSON.parse(raw) as HookPayload) : {};
+    await handleHookInvocation(provider, hookEvent, payload);
+    console.log(JSON.stringify({}));
+    return 0;
+  } catch (error) {
+    console.error("[nn] hook failed", error);
+    console.log(JSON.stringify({}));
+    return 0;
+  }
+}
+
+async function main(): Promise<number> {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || hasFlag(argv, "--help") || hasFlag(argv, "-h")) {
+    printHelp();
+    return 0;
+  }
+
+  const [command, subcommand, ...rest] = argv;
+
+  if (command === "__coordinator") {
+    await runCoordinatorOnce();
+    return 0;
+  }
+
+  if (command === "hook") {
+    return runHook(argv.slice(1));
+  }
+
+  if (command === "install" && subcommand === "hooks") {
+    const provider = parseFlag(rest, "--provider") as ProviderId | undefined;
+    const result = installHooks({
+      global: hasFlag(rest, "--global"),
+      providers: provider ? [provider] : undefined,
+    });
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (command === "ingest") {
+    const args = commandArgs(subcommand, rest);
+    const provider = parseFlag(args, "--provider") as ProviderId | undefined;
+    if (!provider) {
+      console.error("--provider is required");
+      return 1;
+    }
+    const sessionId = parseFlag(args, "--session");
+    const report = await ingestProvider({
+      provider,
+      sessionId,
+      all: hasFlag(args, "--all"),
+    });
+    console.log(JSON.stringify(report, null, 2));
+    return 0;
+  }
+
+  if (command === "export") {
+    const args = commandArgs(subcommand, rest);
+    const target = parseFlag(args, "--to") as ExportTarget | undefined;
+    const sessionRef = parseFlag(args, "--session");
+    const outputPath = parseFlag(args, "--output");
+    if (!sessionRef) {
+      console.error("--session is required");
+      return 1;
+    }
+    let sessionId = sessionRef;
+    if (!sessionRef.startsWith("sess:")) {
+      sessionId = await resolveSessionId("cursor", sessionRef).catch(
+        async () => {
+          for (const provider of listProviders()) {
+            const found = await resolveSessionId(provider, sessionRef).catch(
+              () => null,
+            );
+            if (found) {
+              return found;
+            }
+          }
+          throw new Error(`Session not found: ${sessionRef}`);
+        },
+      );
+    }
+    const result = await exportSession(
+      sessionId,
+      target,
+      outputPath ? resolve(outputPath) : undefined,
+    );
+    if (outputPath) {
+      console.error(`Wrote ${result.outputPath}`);
+      if (result.manifestPath) {
+        console.error(`Wrote ${result.manifestPath}`);
+      }
+      return 0;
+    }
+    process.stdout.write(result.content);
+    return 0;
+  }
+
+  if (command === "search") {
+    const args = commandArgs(subcommand, rest);
+    let parsed: ReturnType<typeof searchArgs>;
+    try {
+      parsed = searchArgs(args);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      return 1;
+    }
+    if (!parsed.query) {
+      console.error("search query required");
+      return 1;
+    }
+    const results = await searchEvents(parsed.query, parsed.limit);
+    console.log(JSON.stringify(results, null, 2));
+    return 0;
+  }
+
+  if (command === "sessions" && subcommand === "list") {
+    const provider = parseFlag(rest, "--provider") as ProviderId | undefined;
+    const sessions = await listSessions(provider);
+    console.log(JSON.stringify(sessions, null, 2));
+    return 0;
+  }
+
+  if (command === "sync") {
+    if (subcommand === "status") {
+      console.log(JSON.stringify(await syncStatus(), null, 2));
+      return 0;
+    }
+    if (subcommand === "push") {
+      console.log(await syncPush());
+      return 0;
+    }
+    if (subcommand === "pull") {
+      console.log(await syncPull());
+      return 0;
+    }
+    console.error("Unknown sync subcommand");
+    return 1;
+  }
+
+  if (command === "doctor") {
+    const db = await doctorDb();
+    const sync = await syncStatus();
+    console.log(JSON.stringify({ db, sync }, null, 2));
+    return db.ok ? 0 : 1;
+  }
+
+  console.error(`Unknown command: ${argv.join(" ")}`);
+  printHelp();
+  return 1;
+}
+
+export { ingestIncremental, cursorSessionIdFromPath };
+
+const exitCode = await main();
+process.exit(exitCode);

package/src/ingest/jsonl.ts

@@ -0,0 +1,38 @@
+export interface ParsedJsonlLine {
+  lineIndex: number;
+  lineStart: number;
+  lineEnd: number;
+  raw: string;
+}
+
+export function parseCompleteJsonlLines(
+  buffer: Buffer,
+  startOffset = 0,
+): { lines: ParsedJsonlLine[]; consumedBytes: number; partialTail: boolean } {
+  const lines: ParsedJsonlLine[] = [];
+  let lineStart = Math.max(0, startOffset);
+  let consumedBytes = startOffset;
+  let lineIndex = 0;
+
+  while (lineStart < buffer.length) {
+    const newlineIndex = buffer.indexOf(0x0a, lineStart);
+    if (newlineIndex === -1) {
+      return { lines, consumedBytes, partialTail: lineStart < buffer.length };
+    }
+
+    const lineEnd = newlineIndex + 1;
+    const raw = buffer.subarray(lineStart, newlineIndex).toString("utf-8");
+    if (raw.trim().length > 0) {
+      lines.push({ lineIndex: lineIndex + 1, lineStart, lineEnd, raw });
+      lineIndex += 1;
+    }
+    consumedBytes = lineEnd;
+    lineStart = lineEnd;
+  }
+
+  return { lines, consumedBytes, partialTail: false };
+}
+
+export function lineKeyFor(sourcePath: string, lineStart: number): string {
+  return `${sourcePath}:${lineStart}`;
+}

package/src/ingest/pipeline.ts

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs";
+
+import type { ProviderId } from "../ir/types.ts";
+import { getSourceCursor } from "../db/client.ts";
+import { withDb } from "../db/migrate.ts";
+import { ingestBatch } from "../db/client.ts";
+import { getProvider } from "../providers/registry.ts";
+
+export interface IngestOptions {
+  provider: ProviderId;
+  sessionId?: string;
+  all?: boolean;
+  sourcePath?: string;
+}
+
+export interface IngestReport {
+  provider: ProviderId;
+  sessionsProcessed: number;
+  eventsInserted: number;
+  warnings: string[];
+}
+
+export async function ingestIncremental(
+  provider: ProviderId,
+  sourcePath: string,
+  sessionId: string,
+): Promise<IngestReport> {
+  return withDb(async (client) => {
+    const adapter = getProvider(provider);
+    const offset = await getSourceCursor(client, provider, sourcePath);
+    const batch = adapter.parseIncremental(sourcePath, sessionId, offset);
+    const { inserted } = await ingestBatch(batch);
+    return {
+      provider,
+      sessionsProcessed: 1,
+      eventsInserted: inserted,
+      warnings: batch.warnings,
+    };
+  });
+}
+
+export async function ingestProvider(
+  options: IngestOptions,
+): Promise<IngestReport> {
+  const adapter = getProvider(options.provider);
+
+  if (options.sourcePath && options.sessionId) {
+    return ingestIncremental(
+      options.provider,
+      options.sourcePath,
+      options.sessionId,
+    );
+  }
+
+  const sessions = adapter.discover();
+  const filtered =
+    options.sessionId ?
+      sessions.filter((session) => session.sessionId === options.sessionId)
+    : sessions;
+
+  if (filtered.length === 0) {
+    return {
+      provider: options.provider,
+      sessionsProcessed: 0,
+      eventsInserted: 0,
+      warnings: [],
+    };
+  }
+
+  return withDb(async (client) => {
+    let eventsInserted = 0;
+    const warnings: string[] = [];
+
+    for (const session of filtered) {
+      const offset =
+        options.all ? 0 : (
+          await getSourceCursor(client, options.provider, session.path)
+        );
+      const batch = adapter.parseIncremental(
+        session.path,
+        session.sessionId,
+        offset,
+      );
+      const result = await ingestBatch(batch);
+      eventsInserted += result.inserted;
+      warnings.push(...batch.warnings);
+    }
+
+    return {
+      provider: options.provider,
+      sessionsProcessed: filtered.length,
+      eventsInserted,
+      warnings,
+    };
+  });
+}
+
+export function readFileFromOffset(path: string, offset: number): Buffer {
+  const buffer = readFileSync(path);
+  return buffer.subarray(offset);
+}

package/src/install/index.ts

@@ -0,0 +1,227 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { nnCommand, packageRoot } from "../config/runtime.ts";
+import type { HookEventKind } from "../hooks/types.ts";
+import { HOOK_EVENTS } from "../hooks/types.ts";
+import type {
+  InstallHooksOptions,
+  InstallHooksResult,
+  InstallScope,
+  InstallableProvider,
+  ProviderInstallResult,
+} from "./types.ts";
+import {
+  HOOK_EVENT_BINDINGS,
+  INSTALLABLE_PROVIDERS,
+} from "./types.ts";
+
+const NN_HOOK_MARKER = "hook --provider";
+
+function hookCommand(
+  nn: string,
+  provider: InstallableProvider,
+  hookEvent: HookEventKind,
+): string {
+  return `${nn} hook --provider ${provider} --event ${hookEvent}`;
+}
+
+function nnHookEvent(command: string): string | null {
+  const match = command.match(/--event (\w+)/);
+  return match?.[1] ?? null;
+}
+
+function isNnHook(command: string): boolean {
+  return (
+    command.includes(" hook --provider ") ||
+    command.includes("hooks/ingest.ts") ||
+    command.includes("hooks/memory/ingest.ts")
+  );
+}
+
+function loadJson(path: string): Record<string, unknown> {
+  if (!existsSync(path)) {
+    return {};
+  }
+  return JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+}
+
+function saveJson(path: string, value: Record<string, unknown>): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+}
+
+function mergeCursorHooks(
+  config: Record<string, unknown>,
+  registrations: ProviderInstallResult["registrations"],
+): Record<string, unknown> {
+  const hooks =
+    typeof config.hooks === "object" && config.hooks !== null ?
+      { ...(config.hooks as Record<string, unknown>) }
+    : {};
+
+  for (const registration of registrations) {
+    const existing = Array.isArray(hooks[registration.nativeEvent]) ?
+      [...(hooks[registration.nativeEvent] as unknown[])]
+    : [];
+    const filtered = existing.filter((entry) => {
+      if (typeof entry !== "object" || entry === null) {
+        return true;
+      }
+      const command = String((entry as { command?: string }).command ?? "");
+      if (!isNnHook(command)) {
+        return true;
+      }
+      return nnHookEvent(command) !== registration.hookEvent;
+    });
+    hooks[registration.nativeEvent] = [
+      ...filtered,
+      { command: registration.command },
+    ];
+  }
+
+  return { version: 1, ...config, hooks };
+}
+
+function mergeNestedHooks(
+  config: Record<string, unknown>,
+  registrations: ProviderInstallResult["registrations"],
+): Record<string, unknown> {
+  const hooks =
+    typeof config.hooks === "object" && config.hooks !== null ?
+      { ...(config.hooks as Record<string, unknown>) }
+    : {};
+
+  for (const registration of registrations) {
+    const existingGroups = Array.isArray(hooks[registration.nativeEvent]) ?
+      [...(hooks[registration.nativeEvent] as unknown[])]
+    : [];
+
+    let group =
+      registration.matcher ?
+        (existingGroups.find(
+          (entry) =>
+            typeof entry === "object" &&
+            entry !== null &&
+            (entry as { matcher?: string }).matcher === registration.matcher,
+        ) as { matcher?: string; hooks?: unknown[] } | undefined)
+      : (existingGroups[0] as { matcher?: string; hooks?: unknown[] } | undefined);
+
+    if (!group) {
+      group = registration.matcher ? { matcher: registration.matcher, hooks: [] } : { hooks: [] };
+      existingGroups.push(group);
+    }
+
+    const commandHooks = Array.isArray(group.hooks) ? [...group.hooks] : [];
+    group.hooks = [
+      ...commandHooks.filter((entry) => {
+        if (typeof entry !== "object" || entry === null) {
+          return true;
+        }
+        const command = String((entry as { command?: string }).command ?? "");
+        if (!isNnHook(command)) {
+          return true;
+        }
+        return nnHookEvent(command) !== registration.hookEvent;
+      }),
+      { type: "command", command: registration.command },
+    ];
+    hooks[registration.nativeEvent] = existingGroups;
+  }
+
+  return { ...config, hooks };
+}
+
+function providerConfigPath(
+  provider: InstallableProvider,
+  scope: InstallScope,
+  projectDir: string,
+): string {
+  if (provider === "cursor") {
+    return scope === "global" ?
+        join(homedir(), ".cursor/hooks.json")
+      : join(projectDir, ".cursor/hooks.json");
+  }
+  if (provider === "claude") {
+    return scope === "global" ?
+        join(homedir(), ".claude/settings.json")
+      : join(projectDir, ".claude/settings.json");
+  }
+  if (provider === "codex") {
+    return scope === "global" ?
+        join(homedir(), ".codex/hooks.json")
+      : join(projectDir, ".codex/hooks.json");
+  }
+  if (provider === "pi") {
+    return scope === "global" ?
+        join(homedir(), ".pi/agent/settings.json")
+      : join(projectDir, ".pi/settings.json");
+  }
+  if (provider === "grok") {
+    return scope === "global" ?
+        join(homedir(), ".grok/user-settings.json")
+      : join(projectDir, ".grok/settings.json");
+  }
+  return scope === "global" ?
+      join(homedir(), ".gemini/settings.json")
+    : join(projectDir, ".gemini/settings.json");
+}
+
+function installProvider(
+  provider: InstallableProvider,
+  scope: InstallScope,
+  projectDir: string,
+  nn: string,
+): ProviderInstallResult {
+  const configPath = providerConfigPath(provider, scope, projectDir);
+  const registrations = HOOK_EVENTS.map((hookEvent) => {
+    const binding = HOOK_EVENT_BINDINGS[provider][hookEvent];
+    return {
+      provider,
+      hookEvent,
+      nativeEvent: binding.nativeEvent,
+      matcher: binding.matcher,
+      command: hookCommand(nn, provider, hookEvent),
+    };
+  });
+
+  const existing = loadJson(configPath);
+  const merged =
+    provider === "cursor" ?
+      mergeCursorHooks(existing, registrations)
+    : mergeNestedHooks(existing, registrations);
+  saveJson(configPath, merged);
+
+  return { provider, configPath, registrations };
+}
+
+export function installHooks(
+  options: InstallHooksOptions = {},
+): InstallHooksResult {
+  const sourceRoot = options.sourceRoot ?? packageRoot();
+  const scope: InstallScope = options.global ? "global" : "project";
+  const projectDir = options.projectDir ?? process.cwd();
+  const nn = nnCommand(sourceRoot);
+
+  const providers = (options.providers ?? INSTALLABLE_PROVIDERS).filter(
+    (provider): provider is InstallableProvider =>
+      INSTALLABLE_PROVIDERS.includes(provider as InstallableProvider),
+  );
+
+  const results = providers.map((provider) =>
+    installProvider(provider, scope, projectDir, nn),
+  );
+
+  return {
+    scope,
+    sourceRoot,
+    ingestScriptPath: nn,
+    providers: results,
+  };
+}

package/src/install/types.ts

@@ -0,0 +1,85 @@
+import type { HookEventKind } from "../hooks/types.ts";
+import type { ProviderId } from "../ir/types.ts";
+
+export type InstallScope = "project" | "global";
+
+export interface HookRegistration {
+  provider: ProviderId;
+  hookEvent: HookEventKind;
+  nativeEvent: string;
+  matcher?: string;
+  command: string;
+}
+
+export interface ProviderInstallResult {
+  provider: ProviderId;
+  configPath: string;
+  registrations: HookRegistration[];
+}
+
+export interface InstallHooksOptions {
+  global?: boolean;
+  projectDir?: string;
+  sourceRoot?: string;
+  providers?: ProviderId[];
+}
+
+export interface InstallHooksResult {
+  scope: InstallScope;
+  sourceRoot: string;
+  ingestScriptPath: string;
+  providers: ProviderInstallResult[];
+}
+
+export const INSTALLABLE_PROVIDERS = [
+  "cursor",
+  "claude",
+  "codex",
+  "pi",
+  "grok",
+  "antigravity",
+] as const satisfies readonly ProviderId[];
+
+export type InstallableProvider = (typeof INSTALLABLE_PROVIDERS)[number];
+
+export const HOOK_EVENT_BINDINGS: Record<
+  InstallableProvider,
+  Record<HookEventKind, { nativeEvent: string; matcher?: string }>
+> = {
+  cursor: {
+    sessionStart: { nativeEvent: "sessionStart" },
+    postToolUse: { nativeEvent: "postToolUse" },
+    turnEnd: { nativeEvent: "afterAgentResponse" },
+    stop: { nativeEvent: "stop" },
+  },
+  claude: {
+    sessionStart: { nativeEvent: "SessionStart", matcher: "startup" },
+    postToolUse: { nativeEvent: "PostToolUse" },
+    turnEnd: { nativeEvent: "Stop" },
+    stop: { nativeEvent: "Stop" },
+  },
+  codex: {
+    sessionStart: { nativeEvent: "SessionStart", matcher: "startup" },
+    postToolUse: { nativeEvent: "PostToolUse" },
+    turnEnd: { nativeEvent: "Stop" },
+    stop: { nativeEvent: "Stop" },
+  },
+  pi: {
+    sessionStart: { nativeEvent: "SessionStart", matcher: "startup" },
+    postToolUse: { nativeEvent: "PostToolUse" },
+    turnEnd: { nativeEvent: "Stop" },
+    stop: { nativeEvent: "Stop" },
+  },
+  grok: {
+    sessionStart: { nativeEvent: "SessionStart", matcher: "startup" },
+    postToolUse: { nativeEvent: "PostToolUse" },
+    turnEnd: { nativeEvent: "Stop" },
+    stop: { nativeEvent: "Stop" },
+  },
+  antigravity: {
+    sessionStart: { nativeEvent: "SessionStart", matcher: "startup" },
+    postToolUse: { nativeEvent: "AfterTool", matcher: "*" },
+    turnEnd: { nativeEvent: "AfterAgent", matcher: "*" },
+    stop: { nativeEvent: "SessionEnd", matcher: "exit" },
+  },
+};