@groundtrack/hooks 0.1.25 → 0.1.27

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>;

package/dist/session-import/watch.js

@@ -0,0 +1,402 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { environment } from "../setup/agents.js";
+import { parseImportArguments } from "./cli.js";
+import { groupCodexPages } from "./codex-pages.js";
+import { discoverSessions, repositoryIdentity, statSessionFiles, } from "./discovery.js";
+import { sessionImportFormat } from "./formats.js";
+import { readReceipts } from "./receipts.js";
+import { prepareSession, uploadPreparedSession } from "./sync.js";
+import { acquireWatchLock } from "./watch-lock.js";
+import { deserializeMetadata, readWatchState, serializeMetadata, watchStatePath, writeWatchState, } from "./watch-state.js";
+export const WATCH_USAGE = `Usage:
+  groundtrack watch --once [--agent codex|claude] [--repo PATH | --all-repos] [--since DATE]
+                           [--include-subagents] [--include-unscoped]
+                           [--visibility private|organization] [--dry-run] [--yes] [--json]
+
+Watch options:
+  --once                 Run one scan and exit (required for now)
+  --agent VALUE          codex or claude
+  --repo PATH            Watch sessions for this Git repository (default: current repository)
+  --all-repos            Watch sessions associated with any Git repository
+  --include-unscoped     With --all-repos, also watch sessions outside a Git repository
+  --since DATE           Only sessions at or after an ISO timestamp or local YYYY-MM-DD
+  --include-subagents    Include subagent, forked-agent, and guardian sessions
+  --visibility VALUE     private (default) or organization
+  --api-key KEY          API key; prefer GROUNDTRACK_IMPORT_KEY or GROUNDTRACK_API_KEY
+  --receipt-scope VALUE  Stable receipt scope from create_session_import_key
+  --url URL              Groundtrack app or API URL (default: https://app.groundtrack.dev)
+  --dry-run              Scan and plan without uploading or writing cursor state
+  --yes, -y              Upload completed sessions without prompting
+  --json                 Emit exactly one machine-readable result object
+`;
+export function parseWatchArguments(argv) {
+    const once = argv.includes("--once");
+    const args = parseImportArguments(argv.filter((arg) => arg !== "--once"));
+    if (args.help)
+        return { ...args, once: true };
+    if (!once)
+        throw new Error("The watch loop is not implemented yet. Use groundtrack watch --once.");
+    return { ...args, once: true };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function skippedCounts(skipped) {
+    const result = {};
+    for (const item of skipped)
+        result[item.reason] = (result[item.reason] ?? 0) + 1;
+    return result;
+}
+function fingerprintPages(pages, stats) {
+    const hash = createHash("sha256");
+    for (const path of [...pages].sort()) {
+        const stat = stats.get(path);
+        hash.update(`${path}\0${stat?.size ?? -1}\0${stat?.mtimeMs ?? -1}\n`);
+    }
+    return hash.digest("hex");
+}
+function diffWatchFiles(state, stats) {
+    let added = 0;
+    let changed = 0;
+    let removed = 0;
+    for (const [path, stat] of stats) {
+        const previous = state.files[path];
+        if (!previous)
+            added += 1;
+        else if (previous.size !== stat.size || previous.mtimeMs !== stat.mtimeMs)
+            changed += 1;
+    }
+    for (const path of Object.keys(state.files))
+        if (!stats.has(path))
+            removed += 1;
+    return { added, changed, removed };
+}
+function buildMetadataCache(state, stats) {
+    const cache = new Map();
+    for (const [path, stat] of stats) {
+        const previous = state.files[path];
+        if (!previous || previous.size !== stat.size || previous.mtimeMs !== stat.mtimeMs)
+            continue;
+        cache.set(path, deserializeMetadata(previous.metadata));
+    }
+    return cache;
+}
+function updateWatchStateFromScan(input) {
+    const next = {};
+    for (const [path, stat] of input.stats) {
+        const metadata = input.metadataByPath.get(path) ?? input.cache.get(path);
+        if (!metadata)
+            continue;
+        const previous = input.state.files[path];
+        const unchanged = previous && previous.size === stat.size && previous.mtimeMs === stat.mtimeMs;
+        next[path] = {
+            size: stat.size,
+            mtimeMs: stat.mtimeMs,
+            sessionId: `${input.format.source}:${metadata.externalSessionId}`,
+            metadata: serializeMetadata(metadata),
+            status: unchanged ? previous.status : "active",
+            ...(unchanged
+                ? {
+                    ...(previous.contentHash ? { contentHash: previous.contentHash } : {}),
+                    ...(previous.receiptKey ? { receiptKey: previous.receiptKey } : {}),
+                    ...(previous.importedAt ? { importedAt: previous.importedAt } : {}),
+                }
+                : {}),
+        };
+    }
+    input.state.files = next;
+}
+function markImported(state, prepared, receipts) {
+    const file = state.files[prepared.candidate.path];
+    if (!file || !prepared.receiptKey)
+        return;
+    file.status = "imported";
+    file.contentHash = prepared.sourceContentHash;
+    file.receiptKey = prepared.receiptKey;
+    file.importedAt = receipts.receipts[prepared.receiptKey]?.importedAt ?? new Date().toISOString();
+}
+function markSessionImported(state, pending, receipts) {
+    const session = state.sessions[pending.sessionKey];
+    if (!session || !pending.prepared.receiptKey)
+        return;
+    session.status = "imported";
+    session.contentHash = pending.prepared.sourceContentHash;
+    session.receiptKey = pending.prepared.receiptKey;
+    session.importedAt =
+        receipts.receipts[pending.prepared.receiptKey]?.importedAt ?? new Date().toISOString();
+}
+export async function runWatchOnce(args, context, dependencies = {}) {
+    const agent = args.agent;
+    if (!agent)
+        throw new Error("Choose an agent with --agent. Watch is non-interactive.");
+    const format = sessionImportFormat(agent);
+    if (format.discovery !== "files")
+        throw new Error("watch --once currently supports file-backed sessions (Codex and Claude Code).");
+    const home = resolve(context.env[format.homeEnvironmentVariable] ||
+        resolve(context.homeDir, format.defaultHomeDirectory));
+    const repository = args.allRepositories ? undefined : repositoryIdentity(context.repoDir);
+    const apiKey = args.apiKey ?? context.env.GROUNDTRACK_IMPORT_KEY ?? context.env.GROUNDTRACK_API_KEY ?? null;
+    if (args.yes && !args.dryRun && !apiKey)
+        throw new Error("Set GROUNDTRACK_IMPORT_KEY or GROUNDTRACK_API_KEY before uploading.");
+    const providedReceiptScope = args.receiptScope ?? context.env.GROUNDTRACK_IMPORT_RECEIPT_SCOPE;
+    if (providedReceiptScope && !/^[a-f0-9]{64}$/.test(providedReceiptScope))
+        throw new Error("The import receipt scope must be a 64-character lowercase hex value.");
+    const stableReceiptScope = apiKey?.startsWith("gti_") ? providedReceiptScope : undefined;
+    const receipts = apiKey ? readReceipts(context) : { version: 1, receipts: {} };
+    const state = readWatchState(context, format.source);
+    const stats = statSessionFiles(format, home);
+    const diff = diffWatchFiles(state, stats);
+    const cache = buildMetadataCache(state, stats);
+    const nowMs = dependencies.now?.() ?? Date.now();
+    const discovery = await discoverSessions({
+        home,
+        format,
+        repository,
+        allRepositories: args.allRepositories,
+        includeUnscoped: args.includeUnscoped,
+        includeSubagents: args.includeSubagents,
+        since: args.since,
+        nowMs,
+        metadataCache: cache,
+        userHome: context.homeDir,
+        env: context.env,
+        platform: context.platform,
+        workingDirectory: context.repoDir,
+    });
+    const liveSessionIds = new Set();
+    if (format.agent === "codex") {
+        for (const item of discovery.skipped) {
+            if (item.reason !== "live")
+                continue;
+            const metadata = discovery.metadataByPath.get(item.path);
+            if (metadata && !metadata.isSubagent)
+                liveSessionIds.add(metadata.externalSessionId);
+        }
+    }
+    const grouped = format.agent === "codex"
+        ? await groupCodexPages({
+            candidates: discovery.included.filter((candidate) => !liveSessionIds.has(candidate.metadata.externalSessionId)),
+            metadataByPath: discovery.metadataByPath,
+        })
+        : {
+            candidates: discovery.included.map((candidate) => ({
+                candidate,
+                pages: [candidate.path],
+                merged: false,
+            })),
+            failed: [],
+            cleanup: () => { },
+        };
+    try {
+        const useSessionState = format.agent === "codex";
+        const failures = [
+            ...discovery.failed,
+            ...grouped.failed,
+        ];
+        const prepared = [];
+        const alreadyPrepared = [];
+        const skipped = skippedCounts(discovery.skipped);
+        let alreadyImported = 0;
+        for (const group of grouped.candidates) {
+            const candidate = group.candidate;
+            const sessionKey = `${format.source}:${candidate.metadata.externalSessionId}`;
+            const fingerprint = fingerprintPages(group.pages, stats);
+            if (useSessionState) {
+                const session = state.sessions[sessionKey];
+                if (session?.fingerprint === fingerprint &&
+                    session.receiptKey &&
+                    receipts.receipts[session.receiptKey]) {
+                    session.status = "imported";
+                    session.importedAt = receipts.receipts[session.receiptKey].importedAt;
+                    alreadyImported += 1;
+                    continue;
+                }
+            }
+            else {
+                const previous = state.files[candidate.path];
+                const current = stats.get(candidate.path);
+                const unchanged = Boolean(previous &&
+                    current &&
+                    previous.size === current.size &&
+                    previous.mtimeMs === current.mtimeMs);
+                if (unchanged && previous.receiptKey && receipts.receipts[previous.receiptKey]) {
+                    previous.status = "imported";
+                    previous.importedAt = receipts.receipts[previous.receiptKey].importedAt;
+                    alreadyImported += 1;
+                    continue;
+                }
+            }
+            try {
+                const item = await prepareSession({
+                    candidate,
+                    format,
+                    apiBaseUrl: args.apiBaseUrl,
+                    apiKey,
+                    receiptScope: stableReceiptScope,
+                    visibility: args.visibility,
+                    receipts,
+                });
+                const pending = {
+                    prepared: item,
+                    sessionKey,
+                    fingerprint,
+                    pages: group.pages,
+                };
+                if (item.alreadyImported) {
+                    alreadyImported += 1;
+                    alreadyPrepared.push(pending);
+                }
+                else
+                    prepared.push(pending);
+            }
+            catch (error) {
+                failures.push({ path: candidate.path, error: errorMessage(error) });
+            }
+        }
+        updateWatchStateFromScan({
+            state,
+            format,
+            stats,
+            metadataByPath: discovery.metadataByPath,
+            cache,
+        });
+        if (useSessionState) {
+            for (const group of grouped.candidates) {
+                const sessionKey = `${format.source}:${group.candidate.metadata.externalSessionId}`;
+                const fingerprint = fingerprintPages(group.pages, stats);
+                const previous = state.sessions[sessionKey];
+                const unchanged = previous?.fingerprint === fingerprint;
+                state.sessions[sessionKey] = {
+                    pages: [...group.pages],
+                    fingerprint,
+                    status: unchanged ? previous.status : "active",
+                    ...(unchanged
+                        ? {
+                            ...(previous.contentHash ? { contentHash: previous.contentHash } : {}),
+                            ...(previous.receiptKey ? { receiptKey: previous.receiptKey } : {}),
+                            ...(previous.importedAt ? { importedAt: previous.importedAt } : {}),
+                        }
+                        : {}),
+                };
+            }
+        }
+        for (const pending of alreadyPrepared) {
+            if (useSessionState)
+                markSessionImported(state, pending, receipts);
+            else
+                markImported(state, pending.prepared, receipts);
+        }
+        const scope = args.allRepositories ? "all repositories" : repository.root;
+        const result = (uploaded, duplicate) => ({
+            dryRun: args.dryRun,
+            preview: !args.yes,
+            agent,
+            scope,
+            scanned: stats.size,
+            added: diff.added,
+            changed: diff.changed,
+            removed: diff.removed,
+            cacheHits: discovery.cacheHits,
+            cacheMisses: discovery.cacheMisses,
+            active: discovery.skipped.filter((item) => item.reason === "live").length,
+            complete: prepared.length,
+            alreadyImported,
+            uploaded,
+            duplicate,
+            failed: failures,
+            skipped,
+            cursorPath: watchStatePath(context, format.source),
+            sessionsUrl: args.apiBaseUrl.replace(/\/api$/, "/sessions"),
+        });
+        if (args.dryRun || !args.yes)
+            return result(0, 0);
+        if (!apiKey)
+            throw new Error("Set GROUNDTRACK_IMPORT_KEY or GROUNDTRACK_API_KEY before uploading.");
+        const uploadKey = apiKey;
+        let uploaded = 0;
+        let duplicate = 0;
+        for (let offset = 0; offset < prepared.length; offset += 2) {
+            await Promise.all(prepared.slice(offset, offset + 2).map(async (pending) => {
+                try {
+                    const upload = await uploadPreparedSession({
+                        prepared: pending.prepared,
+                        format,
+                        apiBaseUrl: args.apiBaseUrl,
+                        apiKey: uploadKey,
+                        visibility: args.visibility,
+                        context,
+                        receipts,
+                        fetch: dependencies.fetch,
+                    });
+                    if (upload.duplicate)
+                        duplicate += 1;
+                    else
+                        uploaded += 1;
+                    if (useSessionState)
+                        markSessionImported(state, pending, receipts);
+                    else
+                        markImported(state, pending.prepared, receipts);
+                    writeWatchState(context, format.source, state);
+                }
+                catch (error) {
+                    failures.push({
+                        path: pending.prepared.candidate.path,
+                        error: errorMessage(error),
+                    });
+                }
+            }));
+        }
+        writeWatchState(context, format.source, state);
+        return result(uploaded, duplicate);
+    }
+    finally {
+        grouped.cleanup();
+        discovery.cleanup?.();
+    }
+}
+function printWatchResult(result, input) {
+    const skipped = Object.entries(result.skipped)
+        .map(([reason, count]) => `${reason} ${count}`)
+        .join(" · ");
+    const lines = [
+        `\nGroundtrack · watch ${result.agent} (once)`,
+        `Scope: ${result.scope}`,
+        `Scanned: ${result.scanned} files (${result.added} new, ${result.changed} changed, ${result.removed} removed)`,
+        `Active: ${result.active} · complete: ${result.complete} · already imported: ${result.alreadyImported}`,
+        `Uploaded: ${result.uploaded} (duplicates ${result.duplicate}) · failed: ${result.failed.length}`,
+        ...(skipped ? [`Skipped: ${skipped}`] : []),
+        `Cursor: ${result.cursorPath}`,
+        ...result.failed.slice(0, 5).map((item) => `  ! ${item.path}: ${item.error}`),
+    ];
+    if (result.dryRun)
+        lines.push("Dry run: no uploads, no cursor writes.");
+    else if (!input.yes)
+        lines.push("Preview only. Run with --yes to upload.");
+    lines.push("");
+    process.stdout.write(lines.join("\n"));
+}
+export async function runWatchCli(argv) {
+    const args = parseWatchArguments(argv);
+    if (args.help) {
+        process.stdout.write(WATCH_USAGE);
+        return;
+    }
+    if (!args.agent)
+        throw new Error("Choose an agent with --agent. Watch is non-interactive.");
+    const context = environment({ repoDir: args.repoDir, homeDir: args.homeDir });
+    const format = sessionImportFormat(args.agent);
+    const lock = args.yes && !args.dryRun ? acquireWatchLock(context, format.source) : null;
+    try {
+        const result = await runWatchOnce(args, context);
+        if (args.json)
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        else
+            printWatchResult(result, { yes: args.yes });
+        if (result.failed.length)
+            process.exitCode = 1;
+    }
+    finally {
+        lock?.release();
+    }
+}

package/dist/setup/cli.js

@@ -18,6 +18,7 @@ Usage:
   groundtrack status                       Check selected agents
   groundtrack doctor [--fix]                Check or repair using the same flow
   groundtrack import [options]              Import local coding-agent sessions
+  groundtrack watch --once [options]        Sync completed sessions once
   groundtrack version
 
 Options:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundtrack/hooks",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Lifecycle hook utilities for Groundtrack MCP clients.",
   "keywords": [
     "claude-code",
@@ -116,6 +116,6 @@
     "typescript": "~7.0.2"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.19"
   }
 }