@groundtrack/hooks 0.1.26 → 0.1.27

package/dist/session-import/watch-lock.d.ts

@@ -0,0 +1,17 @@
+import type { SetupEnvironment } from "../setup/agents.js";
+import type { AgentSessionSource } from "./types.js";
+export type WatchLock = Readonly<{
+    path: string;
+    release(): void;
+}>;
+/**
+ * A PID lock with stale detection.
+ *
+ * Creation is atomic (`open(..., "wx")`). Stale takeover never unlinks the
+ * observed path directly: it renames the lock to a unique quarantine name,
+ * verifies that the quarantined file is the same stale owner, and only then
+ * removes it. If another process replaced the lock between observation and
+ * takeover, the moved lock is restored and acquisition retries. This prevents
+ * two starters from both removing each other's fresh lock.
+ */
+export declare function acquireWatchLock(context: SetupEnvironment, source: AgentSessionSource): WatchLock;

package/dist/session-import/watch-lock.js

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { watchLockPath } from "./watch-state.js";
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function readOwner(path) {
+    try {
+        if (lstatSync(path).isSymbolicLink())
+            throw new Error(`Refusing to use a symbolic link as the watch lock: ${path}`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        return readFileSync(path, "utf8").trim();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+/**
+ * A PID lock with stale detection.
+ *
+ * Creation is atomic (`open(..., "wx")`). Stale takeover never unlinks the
+ * observed path directly: it renames the lock to a unique quarantine name,
+ * verifies that the quarantined file is the same stale owner, and only then
+ * removes it. If another process replaced the lock between observation and
+ * takeover, the moved lock is restored and acquisition retries. This prevents
+ * two starters from both removing each other's fresh lock.
+ */
+export function acquireWatchLock(context, source) {
+    const path = watchLockPath(context, source);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const owner = `${process.pid}:${randomUUID()}`;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            try {
+                writeFileSync(fd, `${owner}\n`);
+            }
+            finally {
+                closeSync(fd);
+            }
+            if (readOwner(path) !== owner)
+                throw new Error(`The Groundtrack watch lock changed during acquisition: ${path}`);
+            return {
+                path,
+                release() {
+                    try {
+                        if (readOwner(path) === owner)
+                            rmSync(path, { force: true });
+                    }
+                    catch {
+                        // The lock was already removed or replaced; never remove another owner's file.
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const observed = readOwner(path);
+        if (observed === null)
+            continue;
+        const pid = Number(observed.split(":", 1)[0]);
+        if (Number.isSafeInteger(pid) && pid > 0 && processAlive(pid))
+            throw new Error(`Another groundtrack watch is already running (pid ${pid}).`);
+        const quarantine = `${path}.stale-${process.pid}-${randomUUID()}`;
+        try {
+            renameSync(path, quarantine);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        const moved = readOwner(quarantine);
+        if (moved !== observed) {
+            // We raced with a fresh owner and moved its lock. Put it back if possible;
+            // never delete a lock that does not match the stale owner we observed.
+            try {
+                renameSync(quarantine, path);
+            }
+            catch {
+                throw new Error(`The Groundtrack watch lock changed during stale takeover. Retry when no other watch is running: ${path}`);
+            }
+            continue;
+        }
+        rmSync(quarantine, { force: true });
+    }
+    throw new Error(`Could not acquire the Groundtrack watch lock: ${path}`);
+}

package/dist/session-import/watch-state.d.ts

@@ -0,0 +1,47 @@
+import { type SetupEnvironment } from "../setup/agents.js";
+import type { AgentSessionMetadata, AgentSessionSource } from "./types.js";
+export type WatchFileStatus = "active" | "imported";
+export type SerializedMetadata = Readonly<{
+    externalSessionId: string;
+    timestamp: string | null;
+    cwd: string | null;
+    repositoryUrl: string | null;
+    repositoryBranch: string | null;
+    repositoryCommitSha: string | null;
+    originator: string | null;
+    isSubagent: boolean;
+    historyBaseThreadId?: string | null;
+    historyMode?: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+}>;
+export type WatchFileState = {
+    size: number;
+    mtimeMs: number;
+    sessionId: string;
+    metadata: SerializedMetadata;
+    status: WatchFileStatus;
+    contentHash?: string;
+    receiptKey?: string;
+    importedAt?: string;
+};
+export type WatchSessionState = {
+    pages: string[];
+    fingerprint: string;
+    status: WatchFileStatus;
+    contentHash?: string;
+    receiptKey?: string;
+    importedAt?: string;
+};
+export type WatchState = {
+    version: 1;
+    files: Record<string, WatchFileState>;
+    sessions: Record<string, WatchSessionState>;
+};
+export declare function watchStatePath(context: SetupEnvironment, source: AgentSessionSource): string;
+export declare function watchLockPath(context: SetupEnvironment, source: AgentSessionSource): string;
+export declare function emptyWatchState(): WatchState;
+export declare function serializeMetadata(metadata: AgentSessionMetadata): SerializedMetadata;
+export declare function deserializeMetadata(metadata: SerializedMetadata): AgentSessionMetadata;
+export declare function readWatchState(context: SetupEnvironment, source: AgentSessionSource): WatchState;
+export declare function writeWatchState(context: SetupEnvironment, source: AgentSessionSource, state: WatchState): void;

package/dist/session-import/watch-state.js

@@ -0,0 +1,128 @@
+import { join } from "node:path";
+import { stateDir } from "../setup/agents.js";
+import { readFile, writeAtomic } from "../setup/files.js";
+export function watchStatePath(context, source) {
+    return join(stateDir(context), `watch-state-${source}.json`);
+}
+export function watchLockPath(context, source) {
+    return join(stateDir(context), `watch-${source}.lock`);
+}
+export function emptyWatchState() {
+    return { version: 1, files: {}, sessions: {} };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNullableString(value) {
+    return value === null || typeof value === "string";
+}
+function isSerializedMetadata(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.externalSessionId === "string" &&
+        isNullableString(value.timestamp) &&
+        isNullableString(value.cwd) &&
+        isNullableString(value.repositoryUrl) &&
+        isNullableString(value.repositoryBranch) &&
+        isNullableString(value.repositoryCommitSha) &&
+        isNullableString(value.originator) &&
+        typeof value.isSubagent === "boolean" &&
+        (value.historyBaseThreadId === undefined || isNullableString(value.historyBaseThreadId)) &&
+        (value.historyMode === undefined || isNullableString(value.historyMode)) &&
+        isNullableString(value.startedAt) &&
+        isNullableString(value.endedAt));
+}
+function isWatchFileState(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.size === "number" &&
+        Number.isFinite(value.size) &&
+        typeof value.mtimeMs === "number" &&
+        Number.isFinite(value.mtimeMs) &&
+        typeof value.sessionId === "string" &&
+        (value.status === "active" || value.status === "imported") &&
+        isSerializedMetadata(value.metadata) &&
+        (value.contentHash === undefined || typeof value.contentHash === "string") &&
+        (value.receiptKey === undefined || typeof value.receiptKey === "string") &&
+        (value.importedAt === undefined || typeof value.importedAt === "string"));
+}
+function isWatchSessionState(value) {
+    if (!isRecord(value))
+        return false;
+    return (Array.isArray(value.pages) &&
+        value.pages.every((page) => typeof page === "string") &&
+        typeof value.fingerprint === "string" &&
+        (value.status === "active" || value.status === "imported") &&
+        (value.contentHash === undefined || typeof value.contentHash === "string") &&
+        (value.receiptKey === undefined || typeof value.receiptKey === "string") &&
+        (value.importedAt === undefined || typeof value.importedAt === "string"));
+}
+export function serializeMetadata(metadata) {
+    return {
+        externalSessionId: metadata.externalSessionId,
+        timestamp: metadata.timestamp?.toISOString() ?? null,
+        cwd: metadata.cwd,
+        repositoryUrl: metadata.repositoryUrl,
+        repositoryBranch: metadata.repositoryBranch,
+        repositoryCommitSha: metadata.repositoryCommitSha,
+        originator: metadata.originator,
+        isSubagent: metadata.isSubagent,
+        historyBaseThreadId: metadata.historyBaseThreadId ?? null,
+        historyMode: metadata.historyMode ?? null,
+        startedAt: metadata.startedAt?.toISOString() ?? null,
+        endedAt: metadata.endedAt?.toISOString() ?? null,
+    };
+}
+function parseDate(value) {
+    if (value === null)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+export function deserializeMetadata(metadata) {
+    return {
+        externalSessionId: metadata.externalSessionId,
+        timestamp: parseDate(metadata.timestamp),
+        cwd: metadata.cwd,
+        repositoryUrl: metadata.repositoryUrl,
+        repositoryBranch: metadata.repositoryBranch,
+        repositoryCommitSha: metadata.repositoryCommitSha,
+        originator: metadata.originator,
+        isSubagent: metadata.isSubagent,
+        historyBaseThreadId: metadata.historyBaseThreadId ?? null,
+        historyMode: metadata.historyMode ?? null,
+        startedAt: parseDate(metadata.startedAt),
+        endedAt: parseDate(metadata.endedAt),
+    };
+}
+export function readWatchState(context, source) {
+    const path = watchStatePath(context, source);
+    const text = readFile(path);
+    if (text === null)
+        return emptyWatchState();
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Groundtrack's watch state is not valid JSON: ${path}`);
+    }
+    if (!isRecord(value) || value.version !== 1 || !isRecord(value.files))
+        throw new Error(`Groundtrack's watch state is invalid: ${path}`);
+    const files = {};
+    for (const [filePath, file] of Object.entries(value.files)) {
+        if (isWatchFileState(file))
+            files[filePath] = file;
+    }
+    const sessions = {};
+    if (isRecord(value.sessions)) {
+        for (const [sessionId, session] of Object.entries(value.sessions)) {
+            if (isWatchSessionState(session))
+                sessions[sessionId] = session;
+        }
+    }
+    return { version: 1, files, sessions };
+}
+export function writeWatchState(context, source, state) {
+    writeAtomic(watchStatePath(context, source), `${JSON.stringify(state, null, 2)}\n`, 0o600);
+}

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

@@ -0,0 +1,38 @@
+import { type SetupEnvironment } from "../setup/agents.js";
+import { type ImportArguments } from "./cli.js";
+import type { ImportAgent } from "./types.js";
+export declare const WATCH_USAGE = "Usage:\n  groundtrack watch --once [--agent codex|claude] [--repo PATH | --all-repos] [--since DATE]\n                           [--include-subagents] [--include-unscoped]\n                           [--visibility private|organization] [--dry-run] [--yes] [--json]\n\nWatch options:\n  --once                 Run one scan and exit (required for now)\n  --agent VALUE          codex or claude\n  --repo PATH            Watch sessions for this Git repository (default: current repository)\n  --all-repos            Watch sessions associated with any Git repository\n  --include-unscoped     With --all-repos, also watch sessions outside a Git repository\n  --since DATE           Only sessions at or after an ISO timestamp or local YYYY-MM-DD\n  --include-subagents    Include subagent, forked-agent, and guardian sessions\n  --visibility VALUE     private (default) or organization\n  --api-key KEY          API key; prefer GROUNDTRACK_IMPORT_KEY or GROUNDTRACK_API_KEY\n  --receipt-scope VALUE  Stable receipt scope from create_session_import_key\n  --url URL              Groundtrack app or API URL (default: https://app.groundtrack.dev)\n  --dry-run              Scan and plan without uploading or writing cursor state\n  --yes, -y              Upload completed sessions without prompting\n  --json                 Emit exactly one machine-readable result object\n";
+export type WatchArguments = ImportArguments & Readonly<{
+    once: boolean;
+}>;
+export declare function parseWatchArguments(argv: readonly string[]): WatchArguments;
+export type WatchResult = Readonly<{
+    dryRun: boolean;
+    preview: boolean;
+    agent: ImportAgent;
+    scope: string;
+    scanned: number;
+    added: number;
+    changed: number;
+    removed: number;
+    cacheHits: number;
+    cacheMisses: number;
+    active: number;
+    complete: number;
+    alreadyImported: number;
+    uploaded: number;
+    duplicate: number;
+    failed: Array<{
+        path: string;
+        error: string;
+    }>;
+    skipped: Record<string, number>;
+    cursorPath: string;
+    sessionsUrl: string;
+}>;
+export type WatchDependencies = Readonly<{
+    fetch?: typeof globalThis.fetch;
+    now?: () => number;
+}>;
+export declare function runWatchOnce(args: ImportArguments, context: SetupEnvironment, dependencies?: WatchDependencies): Promise<WatchResult>;
+export declare function runWatchCli(argv: readonly string[]): Promise<void>;