@groundtrack/hooks 0.1.8 → 0.1.10

package/dist/session-import/cursor.js

@@ -0,0 +1,268 @@
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isSessionRecord, sessionString, } from "./canonical.js";
+import { sessionImportFormatIdentity, } from "./format.js";
+import { containsInternalInstructionText, sanitizeSessionValue, sanitizeWorkingDirectory, } from "./redaction.js";
+function timestamp(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+function defaultDatabasePath(context) {
+    if (context.env.CURSOR_STATE_DB)
+        return context.env.CURSOR_STATE_DB;
+    if (context.platform === "darwin")
+        return join(context.userHome, "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb");
+    if (context.platform === "win32" && context.env.APPDATA)
+        return join(context.env.APPDATA, "Cursor", "User", "globalStorage", "state.vscdb");
+    return join(context.env.XDG_CONFIG_HOME || join(context.userHome, ".config"), "Cursor", "User", "globalStorage", "state.vscdb");
+}
+function readHeaders(context) {
+    const path = defaultDatabasePath(context);
+    if (!existsSync(path))
+        throw new Error(`Cursor session database not found: ${path}`);
+    let DatabaseSync;
+    try {
+        const sqlite = createRequire(import.meta.url)("node:sqlite");
+        DatabaseSync = sqlite.DatabaseSync;
+    }
+    catch {
+        throw new Error("Cursor session import requires unflagged node:sqlite support (Node.js 22.13+, 23.4+, or 24+).");
+    }
+    const database = new DatabaseSync(path, { readOnly: true });
+    try {
+        return database
+            .prepare(`
+        SELECT
+          composerId,
+          createdAt,
+          lastUpdatedAt,
+          isSubagent,
+          CASE WHEN json_valid(value)
+            THEN COALESCE(
+              json_extract(value, '$.workspaceIdentifier.uri.fsPath'),
+              json_extract(value, '$.trackedGitRepos[0].repoPath')
+            )
+            ELSE NULL
+          END AS workingDirectory
+        FROM composerHeaders
+      `)
+            .all();
+    }
+    finally {
+        database.close();
+    }
+}
+function cursorProjectName(path) {
+    return path.replace(/^[/\\]+/, "").replaceAll(/[:/\\]+/g, "-");
+}
+function transcriptPaths(projectsRoot) {
+    const result = new Map();
+    if (!existsSync(projectsRoot))
+        return result;
+    for (const project of readdirSync(projectsRoot, { withFileTypes: true })) {
+        if (!project.isDirectory())
+            continue;
+        const transcripts = join(projectsRoot, project.name, "agent-transcripts");
+        if (!existsSync(transcripts))
+            continue;
+        for (const session of readdirSync(transcripts, { withFileTypes: true })) {
+            if (!session.isDirectory())
+                continue;
+            const path = join(transcripts, session.name, `${session.name}.jsonl`);
+            if (!existsSync(path))
+                continue;
+            const paths = result.get(session.name) ?? [];
+            paths.push(path);
+            result.set(session.name, paths);
+        }
+    }
+    return result;
+}
+function selectTranscript(paths, workingDirectory) {
+    if (!workingDirectory)
+        return paths.length === 1 ? paths[0] : null;
+    const expectedProject = cursorProjectName(workingDirectory);
+    const matching = paths.filter((path) => dirname(dirname(dirname(path)))
+        .split(/[/\\]/)
+        .at(-1) === expectedProject);
+    return matching.length === 1 ? matching[0] : null;
+}
+function isEmptyTranscript(path) {
+    if (statSync(path).size > 64 * 1024)
+        return false;
+    let records;
+    try {
+        records = readFileSync(path, "utf8")
+            .split(/\r?\n/)
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return false;
+    }
+    return !records.some((record) => isSessionRecord(record) &&
+        (record.role === "user" || record.role === "assistant") &&
+        isSessionRecord(record.message) &&
+        Array.isArray(record.message.content));
+}
+export function cursorCandidates(context, headers = readHeaders(context)) {
+    const projectsRoot = context.env.CURSOR_PROJECTS_DIR ?? join(context.sessionHome, "projects");
+    const transcripts = transcriptPaths(projectsRoot);
+    const included = [];
+    const skipped = [];
+    const headerSessionIds = new Set();
+    for (const header of headers) {
+        const externalSessionId = sessionString(header.composerId);
+        if (!externalSessionId)
+            continue;
+        headerSessionIds.add(externalSessionId);
+        const paths = transcripts.get(externalSessionId);
+        if (!paths?.length)
+            continue;
+        const workingDirectory = sessionString(header.workingDirectory);
+        const path = selectTranscript(paths, workingDirectory);
+        if (!path) {
+            for (const duplicate of paths)
+                skipped.push({
+                    path: duplicate,
+                    reason: workingDirectory ? "workspace_mismatch" : "conflicting_duplicates",
+                });
+            continue;
+        }
+        for (const other of paths) {
+            if (other !== path)
+                skipped.push({ path: other, reason: "workspace_mismatch" });
+        }
+        const startedAt = timestamp(header.createdAt);
+        const endedAt = timestamp(header.lastUpdatedAt);
+        const discoveredAt = endedAt ?? new Date(statSync(path).mtimeMs);
+        if (!startedAt ||
+            (header.lastUpdatedAt != null && !endedAt) ||
+            (endedAt && endedAt < startedAt)) {
+            skipped.push({ path, reason: "invalid_metadata" });
+            continue;
+        }
+        if (isEmptyTranscript(path)) {
+            skipped.push({ path, reason: "empty_trace" });
+            continue;
+        }
+        included.push({
+            path,
+            metadata: {
+                externalSessionId,
+                timestamp: discoveredAt,
+                cwd: workingDirectory,
+                repositoryUrl: null,
+                repositoryBranch: null,
+                repositoryCommitSha: null,
+                originator: "cursor",
+                isSubagent: header.isSubagent === 1,
+                startedAt,
+                endedAt,
+            },
+        });
+    }
+    for (const [sessionId, paths] of transcripts) {
+        if (headerSessionIds.has(sessionId))
+            continue;
+        for (const path of paths)
+            skipped.push({ path, reason: "missing_metadata" });
+    }
+    return { included, skipped };
+}
+function normalizeMessage(record) {
+    const role = sessionString(record.role);
+    if (role !== "user" && role !== "assistant")
+        return null;
+    const message = isSessionRecord(record.message) ? record.message : null;
+    if (!message || !Array.isArray(message.content))
+        return null;
+    const entries = [];
+    let sensitive = false;
+    let unsupported = false;
+    for (const block of message.content) {
+        if (!isSessionRecord(block)) {
+            unsupported = true;
+            continue;
+        }
+        const type = sessionString(block.type);
+        if (type === "thinking" || type === "redacted_thinking") {
+            sensitive = true;
+            continue;
+        }
+        if (type === "text") {
+            const text = sessionString(block.text);
+            if (!text)
+                continue;
+            if (containsInternalInstructionText(text))
+                sensitive = true;
+            else
+                entries.push({
+                    kind: role === "user" ? "user_message" : "assistant_message",
+                    occurredAt: null,
+                    payload: { text: sanitizeSessionValue(text) },
+                });
+            continue;
+        }
+        if (role === "assistant" && type === "tool_use") {
+            const toolName = sessionString(block.name);
+            if (!toolName)
+                unsupported = true;
+            else
+                entries.push({
+                    kind: "tool_call",
+                    occurredAt: null,
+                    payload: {
+                        callId: sessionString(block.id),
+                        toolName,
+                        input: sanitizeSessionValue(block.input),
+                    },
+                });
+            continue;
+        }
+        unsupported = true;
+    }
+    return { entries, sensitive, unsupported };
+}
+export function createCursorSessionNormalizer(metadata) {
+    return {
+        normalizeRecord: (record, entryBudget = Number.POSITIVE_INFINITY) => {
+            if (record.type === "turn_ended")
+                return { entries: [], sensitive: false, unsupported: false };
+            const normalized = normalizeMessage(record) ?? {
+                entries: [],
+                sensitive: false,
+                unsupported: true,
+            };
+            const overflowed = normalized.entries.length > entryBudget;
+            return overflowed
+                ? { ...normalized, entries: normalized.entries.slice(0, entryBudget), overflowed }
+                : normalized;
+        },
+        canonicalMetadata: () => metadata
+            ? {
+                type: "session",
+                version: 1,
+                externalSessionId: metadata.externalSessionId,
+                repositoryUrl: metadata.repositoryUrl,
+                repositoryBranch: metadata.repositoryBranch,
+                repositoryCommitSha: metadata.repositoryCommitSha,
+                workingDirectory: sanitizeWorkingDirectory(metadata.cwd),
+                originator: "cursor",
+                model: null,
+            }
+            : null,
+    };
+}
+export const cursorSessionFormat = {
+    ...sessionImportFormatIdentity("cursor"),
+    discovery: "custom",
+    homeEnvironmentVariable: "CURSOR_HOME",
+    defaultHomeDirectory: ".cursor",
+    discoverCandidates: cursorCandidates,
+    createNormalizer: createCursorSessionNormalizer,
+    sourceHashSeed: (metadata) => metadata.externalSessionId,
+};

package/dist/session-import/discovery.d.ts

@@ -0,0 +1,31 @@
+import type { SessionImportFormat } from "./format.js";
+import type { AgentSessionCandidate, FailedAgentSession, SkippedAgentSession } from "./types.js";
+export declare function normalizeRepositoryUrl(value: string): string | null;
+export type RepositoryIdentity = Readonly<{
+    root: string;
+    remotes: ReadonlySet<string>;
+}>;
+export declare function repositoryIdentity(path: string): RepositoryIdentity;
+export type DiscoverSessionsOptions = Readonly<{
+    home: string;
+    format: SessionImportFormat;
+    repository?: RepositoryIdentity;
+    allRepositories: boolean;
+    includeUnscoped: boolean;
+    includeSubagents: boolean;
+    since: Date | null;
+    nowMs?: number;
+    liveWindowMs?: number;
+    resolveRepositoryRoot?: (path: string) => string;
+    resolveRepositoryIdentity?: (path: string) => RepositoryIdentity;
+    userHome?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    workingDirectory?: string;
+}>;
+export declare function discoverSessions(options: DiscoverSessionsOptions): {
+    included: AgentSessionCandidate[];
+    skipped: SkippedAgentSession[];
+    failed: FailedAgentSession[];
+    cleanup?: () => void;
+};

package/dist/session-import/discovery.js

@@ -0,0 +1,241 @@
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, lstatSync, openSync, readSync, readdirSync, realpathSync, } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { isSessionRecord } from "./canonical.js";
+function initialRecords(path, maxRecords, maxBytes = 1024 * 1024) {
+    const file = openSync(path, "r");
+    try {
+        const chunks = [];
+        let offset = 0;
+        let newlineCount = 0;
+        while (offset < maxBytes && newlineCount < maxRecords) {
+            const chunk = Buffer.alloc(Math.min(64 * 1024, maxBytes - offset));
+            const read = readSync(file, chunk, 0, chunk.length, offset);
+            if (read === 0)
+                break;
+            const bytes = chunk.subarray(0, read);
+            chunks.push(bytes);
+            offset += read;
+            for (const byte of bytes) {
+                if (byte === 10 && ++newlineCount >= maxRecords)
+                    break;
+            }
+        }
+        return Buffer.concat(chunks)
+            .toString("utf8")
+            .split(/\r?\n/, maxRecords)
+            .flatMap((line) => {
+            if (!line.trim())
+                return [];
+            try {
+                const record = JSON.parse(line);
+                return isSessionRecord(record) ? [record] : [];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    finally {
+        closeSync(file);
+    }
+}
+function walkJsonl(root) {
+    if (!existsSync(root))
+        return [];
+    const result = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = resolve(directory, entry.name);
+            if (entry.isDirectory())
+                visit(path);
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith(".jsonl"))
+                result.push(path);
+        }
+    };
+    visit(root);
+    return result.sort();
+}
+export function normalizeRepositoryUrl(value) {
+    const trimmed = value
+        .trim()
+        .replace(/\.git\/?$/i, "")
+        .replace(/\/$/, "");
+    const scp = trimmed.match(/^[^@\s]+@([^:\s]+):(.+)$/);
+    const path = scp?.[2] ??
+        (() => {
+            try {
+                return new URL(trimmed).pathname;
+            }
+            catch {
+                return trimmed.includes("/") ? trimmed : null;
+            }
+        })();
+    if (!path)
+        return null;
+    const parts = path.split("/").filter(Boolean);
+    if (parts.length < 2)
+        return null;
+    return parts.slice(-2).join("/").toLowerCase();
+}
+function repositoryRoot(path) {
+    return realpathSync(execFileSync("git", ["-C", path, "rev-parse", "--show-toplevel"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5_000,
+    }).trim());
+}
+export function repositoryIdentity(path) {
+    const root = repositoryRoot(path);
+    const names = execFileSync("git", ["-C", root, "remote"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5_000,
+    })
+        .split(/\r?\n/)
+        .filter(Boolean);
+    const remotes = new Set();
+    for (const name of names) {
+        const urls = execFileSync("git", ["-C", root, "remote", "get-url", "--all", name], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5_000,
+        }).split(/\r?\n/);
+        for (const url of urls) {
+            const normalized = normalizeRepositoryUrl(url);
+            if (normalized)
+                remotes.add(normalized);
+        }
+    }
+    return { root, remotes };
+}
+function isInside(candidate, root) {
+    if (!isAbsolute(candidate))
+        return false;
+    const child = relative(root, resolve(candidate));
+    return child === "" || (!child.startsWith(`..${sep}`) && child !== "..");
+}
+export function discoverSessions(options) {
+    const nowMs = options.nowMs ?? Date.now();
+    const liveWindowMs = options.liveWindowMs ?? 5 * 60_000;
+    const included = [];
+    const discoveryContext = {
+        sessionHome: options.home,
+        userHome: options.userHome ?? homedir(),
+        workingDirectory: options.workingDirectory ?? options.repository?.root ?? process.cwd(),
+        env: options.env ?? process.env,
+        platform: options.platform ?? process.platform,
+    };
+    const discovered = options.format.discovery === "custom"
+        ? options.format.discoverCandidates(discoveryContext)
+        : (() => {
+            const candidates = [];
+            const rejected = [];
+            for (const path of options.format.sessionRoots(options.home).flatMap(walkJsonl)) {
+                const metadata = options.format.parseDiscoveryMetadata(initialRecords(path, options.format.discoveryRecordLimit));
+                if (metadata)
+                    candidates.push({ path, metadata });
+                else
+                    rejected.push({ path, reason: "invalid_metadata" });
+            }
+            return { included: candidates, skipped: rejected };
+        })();
+    const skipped = [...discovered.skipped];
+    const repositoryRootsByCwd = new Map();
+    const repositoryIdentitiesByRoot = new Map();
+    const repositoryRootForCwd = (cwd) => {
+        if (!cwd)
+            return null;
+        const cached = repositoryRootsByCwd.get(cwd);
+        if (cached !== undefined)
+            return cached;
+        let root = null;
+        try {
+            root = (options.resolveRepositoryRoot ?? repositoryRoot)(cwd);
+        }
+        catch { }
+        repositoryRootsByCwd.set(cwd, root);
+        return root;
+    };
+    const repositoryIdentityForCwd = (cwd) => {
+        const root = repositoryRootForCwd(cwd);
+        if (!root)
+            return null;
+        const cached = repositoryIdentitiesByRoot.get(root);
+        if (cached !== undefined)
+            return cached;
+        let identity = null;
+        try {
+            identity = (options.resolveRepositoryIdentity ?? repositoryIdentity)(root);
+        }
+        catch { }
+        repositoryIdentitiesByRoot.set(root, identity);
+        return identity;
+    };
+    const soleRemote = (identity) => {
+        if (!identity || identity.remotes.size !== 1)
+            return null;
+        return identity.remotes.values().next().value ?? null;
+    };
+    for (const candidate of discovered.included) {
+        const { path, metadata } = candidate;
+        const modifiedAtMs = candidate.modifiedAt?.getTime() ??
+            (() => {
+                const file = lstatSync(path);
+                return file.isFile() ? file.mtimeMs : Number.NaN;
+            })();
+        if (!Number.isFinite(modifiedAtMs))
+            continue;
+        if (nowMs - modifiedAtMs < liveWindowMs) {
+            skipped.push({ path, reason: "live" });
+            continue;
+        }
+        if (!options.includeSubagents && metadata.isSubagent) {
+            skipped.push({ path, reason: "subagent" });
+            continue;
+        }
+        if (options.since && (!metadata.timestamp || metadata.timestamp < options.since)) {
+            skipped.push({ path, reason: "before_since" });
+            continue;
+        }
+        const normalizedRemote = metadata.repositoryUrl
+            ? normalizeRepositoryUrl(metadata.repositoryUrl)
+            : null;
+        const matchesCurrentRepository = options.repository
+            ? normalizedRemote
+                ? options.repository.remotes.has(normalizedRemote)
+                : Boolean(metadata.cwd && isInside(metadata.cwd, options.repository.root))
+            : false;
+        if (!options.allRepositories && !matchesCurrentRepository) {
+            skipped.push({ path, reason: "other_repository" });
+            continue;
+        }
+        if (options.allRepositories &&
+            !options.includeUnscoped &&
+            !normalizedRemote &&
+            !repositoryRootForCwd(metadata.cwd)) {
+            skipped.push({ path, reason: "unscoped" });
+            continue;
+        }
+        const inferredRemote = normalizedRemote
+            ? null
+            : options.repository && matchesCurrentRepository
+                ? soleRemote(options.repository)
+                : options.allRepositories
+                    ? soleRemote(repositoryIdentityForCwd(metadata.cwd))
+                    : null;
+        included.push(inferredRemote
+            ? { ...candidate, metadata: { ...metadata, repositoryUrl: inferredRemote } }
+            : candidate);
+    }
+    if (!options.format.materializeCandidates)
+        return { included, skipped, failed: [] };
+    const materialized = options.format.materializeCandidates(included, discoveryContext);
+    return {
+        included: [...materialized.included],
+        skipped,
+        failed: [...materialized.failed],
+        cleanup: materialized.cleanup,
+    };
+}

package/dist/session-import/format.d.ts

@@ -0,0 +1,51 @@
+import type { CanonicalSessionEntry, CanonicalSessionMetadata, SessionRecord } from "./canonical.js";
+import type { AgentSessionCandidate, AgentSessionMetadata, AgentSessionSource, FailedAgentSession, ImportAgent, SkippedAgentSession } from "./types.js";
+export type SessionRecordNormalization = Readonly<{
+    entries: readonly CanonicalSessionEntry[];
+    sensitive: boolean;
+    unsupported: boolean;
+    overflowed?: boolean;
+}>;
+export type SessionNormalizer = Readonly<{
+    normalizeRecord(record: SessionRecord, entryBudget?: number): SessionRecordNormalization;
+    canonicalMetadata(): Omit<CanonicalSessionMetadata, "startedAt" | "endedAt" | "statistics"> | null;
+}>;
+export type SessionDiscoveryContext = Readonly<{
+    sessionHome: string;
+    userHome: string;
+    workingDirectory: string;
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+}>;
+export type SessionDiscoveryCandidates = Readonly<{
+    included: readonly AgentSessionCandidate[];
+    skipped: readonly SkippedAgentSession[];
+}>;
+export type MaterializedSessionCandidates = Readonly<{
+    included: readonly AgentSessionCandidate[];
+    failed: readonly FailedAgentSession[];
+    cleanup(): void;
+}>;
+type SessionImportFormatBase = Readonly<{
+    agent: ImportAgent;
+    source: AgentSessionSource;
+    displayName: string;
+    homeEnvironmentVariable: string;
+    defaultHomeDirectory: string;
+    materializeCandidates?(candidates: readonly AgentSessionCandidate[], context: SessionDiscoveryContext): MaterializedSessionCandidates;
+    createNormalizer(metadata?: AgentSessionMetadata): SessionNormalizer;
+    sourceHashSeed?(metadata: AgentSessionMetadata): string;
+}>;
+type FileSessionDiscovery = Readonly<{
+    discovery: "files";
+    discoveryRecordLimit: number;
+    sessionRoots(home: string): readonly string[];
+    parseDiscoveryMetadata(records: readonly SessionRecord[]): AgentSessionMetadata | null;
+}>;
+type CustomSessionDiscovery = Readonly<{
+    discovery: "custom";
+    discoverCandidates(context: SessionDiscoveryContext): SessionDiscoveryCandidates;
+}>;
+export type SessionImportFormat = SessionImportFormatBase & (FileSessionDiscovery | CustomSessionDiscovery);
+export declare function sessionImportFormatIdentity(agent: ImportAgent): Pick<SessionImportFormat, "agent" | "source" | "displayName">;
+export {};

package/dist/session-import/format.js

@@ -0,0 +1,11 @@
+import { SESSION_IMPORT_AGENTS } from "../agents.js";
+export function sessionImportFormatIdentity(agent) {
+    const definition = SESSION_IMPORT_AGENTS.find((candidate) => candidate.id === agent);
+    if (!definition)
+        throw new Error(`Unsupported session import agent: ${agent}`);
+    return {
+        agent: definition.id,
+        source: definition.source,
+        displayName: definition.name,
+    };
+}

package/dist/session-import/formats.d.ts

@@ -0,0 +1,4 @@
+import type { SessionImportFormat } from "./format.js";
+import type { ImportAgent } from "./types.js";
+export declare const sessionImportFormats: Readonly<Record<ImportAgent, SessionImportFormat>>;
+export declare function sessionImportFormat(agent: ImportAgent): SessionImportFormat;

package/dist/session-import/formats.js

@@ -0,0 +1,13 @@
+import { claudeSessionFormat } from "./claude.js";
+import { codexSessionFormat } from "./codex.js";
+import { cursorSessionFormat } from "./cursor.js";
+import { opencodeSessionFormat } from "./opencode-cli.js";
+export const sessionImportFormats = {
+    claude: claudeSessionFormat,
+    codex: codexSessionFormat,
+    cursor: cursorSessionFormat,
+    opencode: opencodeSessionFormat,
+};
+export function sessionImportFormat(agent) {
+    return sessionImportFormats[agent];
+}

package/dist/session-import/normalize.d.ts

@@ -0,0 +1,21 @@
+import { type CanonicalSessionEntry, type CanonicalSessionMetadata } from "./canonical.js";
+import type { SessionNormalizer } from "./format.js";
+import type { AgentSessionMetadata } from "./types.js";
+export type SessionNormalizationErrorCode = "too_many_entries" | "missing_session_metadata" | "empty_trace";
+export declare class SessionNormalizationError extends Error {
+    readonly code: SessionNormalizationErrorCode;
+    constructor(code: SessionNormalizationErrorCode, message: string);
+}
+export type NormalizedSession = Readonly<{
+    metadata: CanonicalSessionMetadata;
+    entries: readonly CanonicalSessionEntry[];
+}>;
+export declare function createSessionNormalizationAccumulator(normalizer: SessionNormalizer, options?: Readonly<{
+    discoveryMetadata?: AgentSessionMetadata;
+    collectEntries?: boolean;
+    onEntry?: (entry: CanonicalSessionEntry) => void;
+}>): {
+    add(record: unknown): void;
+    finish(): NormalizedSession;
+};
+export declare function normalizeSessionRecords(records: readonly unknown[], normalizer: SessionNormalizer, discoveryMetadata?: AgentSessionMetadata): NormalizedSession;