@groundtrack/hooks 0.1.7 → 0.1.9

package/dist/session-import/discovery.js

@@ -0,0 +1,188 @@
+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";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function firstLine(path, maxBytes = 1024 * 1024) {
+    const file = openSync(path, "r");
+    try {
+        const chunks = [];
+        let offset = 0;
+        while (offset < maxBytes) {
+            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);
+            const newline = bytes.indexOf(10);
+            chunks.push(newline >= 0 ? bytes.subarray(0, newline) : bytes);
+            offset += newline >= 0 ? newline : read;
+            if (newline >= 0)
+                break;
+        }
+        return Buffer.concat(chunks).toString("utf8").replace(/\r$/, "");
+    }
+    finally {
+        closeSync(file);
+    }
+}
+function isSubagentMetadata(payload) {
+    if (stringValue(payload.parent_thread_id) || stringValue(payload.agent_path))
+        return true;
+    if (isRecord(payload.source) && "subagent" in payload.source)
+        return true;
+    return ["subagent", "agent_forked_thread", "guardian_review"].includes(stringValue(payload.thread_source) ?? "");
+}
+export function parseCodexMetadata(line) {
+    try {
+        const record = JSON.parse(line);
+        if (!isRecord(record) || record.type !== "session_meta" || !isRecord(record.payload))
+            return null;
+        const payload = record.payload;
+        const git = isRecord(payload.git) ? payload.git : {};
+        const externalSessionId = stringValue(payload.session_id) ?? stringValue(payload.id);
+        if (!externalSessionId)
+            return null;
+        const timestampValue = stringValue(payload.timestamp) ?? stringValue(record.timestamp);
+        const timestamp = timestampValue ? new Date(timestampValue) : null;
+        return {
+            externalSessionId,
+            timestamp: timestamp && !Number.isNaN(timestamp.getTime()) ? timestamp : null,
+            cwd: stringValue(payload.cwd),
+            repositoryUrl: stringValue(git.repository_url),
+            repositoryBranch: stringValue(git.branch),
+            repositoryCommitSha: stringValue(git.commit_hash),
+            originator: stringValue(payload.originator),
+            isSubagent: isSubagentMetadata(payload),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+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();
+}
+export function repositoryIdentity(path) {
+    const root = realpathSync(execFileSync("git", ["-C", path, "rev-parse", "--show-toplevel"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5_000,
+    }).trim());
+    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 discoverCodexSessions(options) {
+    const nowMs = options.nowMs ?? Date.now();
+    const liveWindowMs = options.liveWindowMs ?? 5 * 60_000;
+    const roots = [
+        resolve(options.codexHome, "sessions"),
+        resolve(options.codexHome, "archived_sessions"),
+    ];
+    const included = [];
+    const skipped = [];
+    for (const path of roots.flatMap(walkJsonl)) {
+        const metadata = parseCodexMetadata(firstLine(path));
+        if (!metadata) {
+            skipped.push({ path, reason: "invalid_metadata" });
+            continue;
+        }
+        const stat = lstatSync(path);
+        if (!stat.isFile())
+            continue;
+        if (nowMs - stat.mtimeMs < 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 && !normalizedRemote && !options.includeUnscoped) {
+            skipped.push({ path, reason: "unscoped" });
+            continue;
+        }
+        included.push({ path, metadata });
+    }
+    return { included, skipped };
+}

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

@@ -0,0 +1,5 @@
+import type { CodexSessionAnalysis, PrunedCodexSession } from "./types.js";
+export declare function pruneCodexSession(path: string): Promise<PrunedCodexSession>;
+export declare function pruneCodexSession(path: string, options: Readonly<{
+    emitBytes: false;
+}>): Promise<CodexSessionAnalysis>;

package/dist/session-import/prune.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { Transform } from "node:stream";
+import { CODEX_CANONICAL_IMPORT_MAX_RECORD_BYTES, codexSessionMetadata, isSessionRecord, isKnownSkippedCodexRecord, isSensitiveCodexRecord, normalizeCodexResponseItem, sessionString, } from "./codex.js";
+function recordTimestamp(record) {
+    const value = sessionString(record.timestamp);
+    if (!value)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+export async function pruneCodexSession(path, options = {}) {
+    const before = await stat(path);
+    const hash = createHash("sha256");
+    const encoder = new TextEncoder();
+    const entryChunks = [];
+    let entryBytes = 0;
+    let entryCount = 0;
+    const timestamps = [];
+    let metadata = null;
+    let model = null;
+    let originalRecords = 0;
+    let malformedRecordCount = 0;
+    let sensitiveRecordCount = 0;
+    let unsupportedRecordCount = 0;
+    const hashingStream = new Transform({
+        transform(chunk, _encoding, callback) {
+            hash.update(chunk);
+            callback(null, chunk);
+        },
+    });
+    const input = createReadStream(path);
+    input.pipe(hashingStream);
+    const lines = createInterface({ input: hashingStream, crlfDelay: Infinity });
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        originalRecords += 1;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            malformedRecordCount += 1;
+            continue;
+        }
+        if (!isSessionRecord(record)) {
+            malformedRecordCount += 1;
+            continue;
+        }
+        metadata ??= codexSessionMetadata(record);
+        const timestamp = recordTimestamp(record);
+        if (timestamp)
+            timestamps.push(timestamp);
+        if (record.type === "turn_context" && isSessionRecord(record.payload))
+            model ??= sessionString(record.payload.model);
+        const sensitive = isSensitiveCodexRecord(record);
+        if (sensitive)
+            sensitiveRecordCount += 1;
+        const entry = normalizeCodexResponseItem(record);
+        if (entry) {
+            const chunk = encoder.encode(`${JSON.stringify(entry)}\n`);
+            if (chunk.byteLength > CODEX_CANONICAL_IMPORT_MAX_RECORD_BYTES)
+                throw new Error(`Canonical session record is too large: ${path}`);
+            if (options.emitBytes !== false)
+                entryChunks.push(chunk);
+            entryBytes += chunk.byteLength;
+            entryCount += 1;
+        }
+        else if (!isKnownSkippedCodexRecord(record) && !sensitive)
+            unsupportedRecordCount += 1;
+    }
+    const after = await stat(path);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+        throw new Error(`Session changed while it was being read: ${path}`);
+    if (!metadata)
+        throw new Error(`Session metadata is missing: ${path}`);
+    if (entryCount === 0)
+        throw new Error(`Session has no supported trace entries: ${path}`);
+    const startedAt = timestamps.length
+        ? new Date(Math.min(...timestamps.map((timestamp) => timestamp.getTime()))).toISOString()
+        : null;
+    const endedAt = timestamps.length
+        ? new Date(Math.max(...timestamps.map((timestamp) => timestamp.getTime()))).toISOString()
+        : null;
+    const header = {
+        ...metadata,
+        model,
+        startedAt,
+        endedAt,
+        statistics: {
+            totalRecordCount: originalRecords,
+            importedEntryCount: entryCount,
+            skippedRecordCount: originalRecords - entryCount,
+            unsupportedRecordCount,
+            malformedRecordCount,
+            sensitiveRecordCount,
+        },
+    };
+    const headerBytes = encoder.encode(`${JSON.stringify(header)}\n`);
+    if (headerBytes.byteLength > CODEX_CANONICAL_IMPORT_MAX_RECORD_BYTES)
+        throw new Error(`Canonical session metadata is too large: ${path}`);
+    const analysis = {
+        sourceContentHash: hash.digest("hex"),
+        originalBytes: before.size,
+        prunedBytes: headerBytes.byteLength + entryBytes,
+    };
+    if (options.emitBytes === false)
+        return analysis;
+    const bytes = new Uint8Array(analysis.prunedBytes);
+    bytes.set(headerBytes);
+    let offset = headerBytes.byteLength;
+    for (const chunk of entryChunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { ...analysis, bytes };
+}

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

@@ -0,0 +1,20 @@
+import type { SetupEnvironment } from "../setup/agents.js";
+import type { ImportVisibility } from "./types.js";
+type Receipt = Readonly<{
+    sessionId: string;
+    importedAt: string;
+}>;
+type ReceiptFile = {
+    version: 1;
+    receipts: Record<string, Receipt>;
+};
+export declare function receiptPath(context: SetupEnvironment): string;
+export declare function readReceipts(context: SetupEnvironment): ReceiptFile;
+export declare function receiptKey(input: {
+    apiBaseUrl: string;
+    apiKey: string;
+    sourceContentHash: string;
+    visibility: ImportVisibility;
+}): string;
+export declare function saveReceipt(context: SetupEnvironment, file: ReceiptFile, key: string, sessionId: string): void;
+export {};

package/dist/session-import/receipts.js

@@ -0,0 +1,44 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { readJson } from "../setup/config.js";
+import { readFile, writeAtomic } from "../setup/files.js";
+import { stateDir } from "../setup/agents.js";
+import { CODEX_CANONICALIZATION_VERSION } from "./codex.js";
+export function receiptPath(context) {
+    return join(stateDir(context), "session-import-receipts.json");
+}
+export function readReceipts(context) {
+    const text = readFile(receiptPath(context));
+    if (text === null)
+        return { version: 1, receipts: {} };
+    const value = readJson(text);
+    if (value.version !== 1 || !value.receipts || typeof value.receipts !== "object")
+        throw new Error("Groundtrack's session import receipt file is invalid.");
+    const receipts = {};
+    for (const [key, receipt] of Object.entries(value.receipts)) {
+        if (receipt &&
+            typeof receipt === "object" &&
+            "sessionId" in receipt &&
+            typeof receipt.sessionId === "string" &&
+            "importedAt" in receipt &&
+            typeof receipt.importedAt === "string")
+            receipts[key] = { sessionId: receipt.sessionId, importedAt: receipt.importedAt };
+    }
+    return { version: 1, receipts };
+}
+export function receiptKey(input) {
+    return createHash("sha256")
+        .update([
+        input.apiBaseUrl,
+        createHash("sha256").update(input.apiKey).digest("hex"),
+        "codex_cli",
+        CODEX_CANONICALIZATION_VERSION,
+        input.visibility,
+        input.sourceContentHash,
+    ].join("\0"))
+        .digest("hex");
+}
+export function saveReceipt(context, file, key, sessionId) {
+    file.receipts[key] = { sessionId, importedAt: new Date().toISOString() };
+    writeAtomic(receiptPath(context), `${JSON.stringify(file, null, 2)}\n`, 0o600);
+}

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

@@ -0,0 +1,6 @@
+export declare function redactCredentialText(value: string): string;
+export declare function sanitizeRepositoryUrl(value: unknown): string | null;
+export declare function sanitizeWorkingDirectory(value: unknown): string | null;
+export declare function sanitizeSessionValue(value: string): string;
+export declare function sanitizeSessionValue(value: unknown): unknown;
+export declare function containsInternalInstructionText(value: string): boolean;

package/dist/session-import/redaction.js

@@ -0,0 +1,61 @@
+const sensitiveKeyPattern = /(?:^|[_-])(?:api[_-]?key|token|authorization|auth|password|passwd|secret|private[_-]?key|cookie|credentials?)(?:$|[_-])/i;
+const internalInstructionMarkers = [
+    "<local-command-caveat>",
+    "<system-reminder>",
+    "<environment_context>",
+    "<recommended_plugins>",
+    "# AGENTS.md instructions",
+    "<permissions instructions>",
+    "<skills_instructions>",
+    "<app-context>",
+];
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isSensitiveKey(value) {
+    return sensitiveKeyPattern.test(value.replace(/([a-z0-9])([A-Z])/g, "$1_$2"));
+}
+export function redactCredentialText(value) {
+    return value
+        .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "[REDACTED PRIVATE KEY]")
+        .replace(/\b(authorization\s*:\s*(?:bearer|basic)\s+)[^\s,;]+/gi, "$1[REDACTED]")
+        .replace(/\b((?:[a-z0-9_-]*(?:api[_-]?key|token|password|passwd|secret|private[_-]?key|credentials?))\s*[=:]\s*)[^\s,;]+/gi, "$1[REDACTED]")
+        .replace(/(?:^|\s)((?:--)?(?:api-key|token|password|secret)\s+)[^\s,;]+/gi, "$1$2[REDACTED]")
+        .replace(/\b(?:sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{12,})\b/g, "[REDACTED]");
+}
+export function sanitizeRepositoryUrl(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    try {
+        const url = new URL(value);
+        url.username = "";
+        url.password = "";
+        return url.toString();
+    }
+    catch {
+        return redactCredentialText(value);
+    }
+}
+export function sanitizeWorkingDirectory(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    return redactCredentialText(value)
+        .replace(/^\/Users\/[^/]+(?=\/|$)/, "~")
+        .replace(/^\/home\/[^/]+(?=\/|$)/, "~")
+        .replace(/^[A-Za-z]:\\Users\\[^\\]+(?=\\|$)/i, "~");
+}
+export function sanitizeSessionValue(value) {
+    if (typeof value === "string")
+        return redactCredentialText(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeSessionValue);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [
+        key,
+        isSensitiveKey(key) ? "[REDACTED]" : sanitizeSessionValue(nested),
+    ]));
+}
+export function containsInternalInstructionText(value) {
+    return internalInstructionMarkers.some((marker) => value.includes(marker));
+}

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

@@ -0,0 +1,28 @@
+export type ImportVisibility = "private" | "organization";
+export type CodexSessionMetadata = Readonly<{
+    externalSessionId: string;
+    timestamp: Date | null;
+    cwd: string | null;
+    repositoryUrl: string | null;
+    repositoryBranch: string | null;
+    repositoryCommitSha: string | null;
+    originator: string | null;
+    isSubagent: boolean;
+}>;
+export type CodexSessionCandidate = Readonly<{
+    path: string;
+    metadata: CodexSessionMetadata;
+}>;
+export type DiscoverySkipReason = "invalid_metadata" | "live" | "subagent" | "before_since" | "other_repository" | "unscoped";
+export type SkippedCodexSession = Readonly<{
+    path: string;
+    reason: DiscoverySkipReason;
+}>;
+export type CodexSessionAnalysis = Readonly<{
+    sourceContentHash: string;
+    originalBytes: number;
+    prunedBytes: number;
+}>;
+export type PrunedCodexSession = CodexSessionAnalysis & Readonly<{
+    bytes: Uint8Array<ArrayBuffer>;
+}>;

package/dist/session-import/types.js

@@ -0,0 +1 @@
+export {};

package/dist/setup/agents.d.ts

@@ -0,0 +1,59 @@
+import { type Agent } from "../agents.js";
+export declare const MCP_URL = "https://app.groundtrack.dev/api/mcp";
+export type SetupEnvironment = {
+    repoDir: string;
+    homeDir: string;
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+};
+export declare function environment(options?: Partial<SetupEnvironment>): SetupEnvironment;
+export declare function agentId(value: string): Agent;
+export declare function executable(name: string, context: SetupEnvironment): string | null;
+export declare function stateDir(context: SetupEnvironment): string;
+export declare function configPaths(agent: Agent, context: SetupEnvironment): {
+    project: string;
+    user: string;
+    presence: string[];
+};
+export declare function serverPath(agent: Agent, config: Record<string, unknown>): string[];
+export declare function readConfig(agent: Agent, text: string): Record<string, unknown>;
+export declare function serverMap(agent: Agent, config: Record<string, unknown>): Record<string, unknown>;
+export declare function isGroundtrack(alias: string, value: unknown, url: string): boolean;
+export declare function discoverAgents(context: SetupEnvironment, url?: string): ({
+    id: "claude";
+    name: "Claude Code";
+    aliases: readonly ["claude-code"];
+    source: "claude_code";
+    enrichment: "command";
+    detected: boolean;
+    configured: boolean;
+    issue: string | null;
+} | {
+    id: "codex";
+    name: "Codex";
+    aliases: readonly [];
+    source: "codex";
+    enrichment: "command";
+    detected: boolean;
+    configured: boolean;
+    issue: string | null;
+} | {
+    id: "cursor";
+    name: "Cursor";
+    aliases: readonly [];
+    source: "cursor";
+    enrichment: "command";
+    detected: boolean;
+    configured: boolean;
+    issue: string | null;
+} | {
+    id: "opencode";
+    name: "OpenCode";
+    aliases: readonly [];
+    source: "opencode";
+    enrichment: "plugin";
+    detected: boolean;
+    configured: boolean;
+    issue: string | null;
+})[];
+export declare function savedAgents(context: SetupEnvironment): Agent[] | null;