iteration-cli 0.9.1 → 0.10.0

package/dist/cursor-hooks.js

@@ -1,163 +0,0 @@
-import { promises as fs } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import * as z from "zod";
-import { ensurePrivateDirectory } from "./storage.js";
-export const CURSOR_HOOKS = [
-    "sessionStart",
-    "beforeSubmitPrompt",
-    "preToolUse",
-    "postToolUse",
-    "postToolUseFailure",
-    "afterAgentThought",
-    "afterAgentResponse",
-    "preCompact",
-    "stop",
-    "subagentStart",
-    "subagentStop",
-    "sessionEnd",
-];
-export function cursorHookDirectory(dataDirectory) {
-    return path.join(dataDirectory, "cursor-hooks");
-}
-export function cursorHookFailurePath(dataDirectory) {
-    return path.join(dataDirectory, "cursor-hook-failure.json");
-}
-export async function cursorHookFailureAtMs(dataDirectory) {
-    let contents;
-    try {
-        contents = await fs.readFile(cursorHookFailurePath(dataDirectory), "utf8");
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return null;
-        throw error;
-    }
-    let decoded;
-    try {
-        decoded = JSON.parse(contents);
-    }
-    catch (error) {
-        throw new Error("Cursor hook failure status is invalid.", { cause: error });
-    }
-    const parsed = z
-        .object({ atMs: z.number().int().min(0) })
-        .strict()
-        .safeParse(decoded);
-    if (!parsed.success)
-        throw new Error("Cursor hook failure status is invalid.");
-    return parsed.data.atMs;
-}
-function shellQuote(value) {
-    return `'${value.replaceAll("'", `'\\''`)}'`;
-}
-function hookCommand(hook, dataDirectory) {
-    const entry = fileURLToPath(new URL("./cursor-hook-entry.js", import.meta.url));
-    return `${shellQuote(process.execPath)} ${shellQuote(entry)} ${shellQuote(hook)} ${shellQuote(dataDirectory)}`;
-}
-const hookEntrySchema = z.object({ command: z.string().optional() }).loose();
-const hookFileSchema = z
-    .object({
-    version: z.literal(1).optional(),
-    hooks: z.record(z.string(), z.array(hookEntrySchema)).optional(),
-})
-    .loose();
-async function readHooks(filename) {
-    let contents;
-    let mode = 0o600;
-    try {
-        contents = await fs.readFile(filename, "utf8");
-        mode = (await fs.stat(filename)).mode & 0o777;
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return { file: {}, mode };
-        throw new Error(`Could not read Cursor hooks at ${filename}.`, {
-            cause: error,
-        });
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(contents);
-    }
-    catch (error) {
-        throw new Error(`Cursor hooks at ${filename} are not valid JSON.`, {
-            cause: error,
-        });
-    }
-    const checked = hookFileSchema.safeParse(parsed);
-    if (!checked.success)
-        throw new Error(`Cursor hooks at ${filename} have an unexpected shape.`);
-    return { file: checked.data, mode };
-}
-async function writeHooks(filename, file, mode) {
-    await ensurePrivateDirectory(path.dirname(filename));
-    const target = await fs.realpath(filename).catch((error) => {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return filename;
-        throw error;
-    });
-    const temporary = `${target}.iteration-${process.pid}.tmp`;
-    const handle = await fs.open(temporary, "w", mode);
-    try {
-        await handle.writeFile(`${JSON.stringify(file, null, 2)}\n`, "utf8");
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-    await fs.rename(temporary, target);
-}
-function entries(value) {
-    return value ?? [];
-}
-export async function installCursorHooks(cursorHome, dataDirectory) {
-    await ensurePrivateDirectory(cursorHookDirectory(dataDirectory));
-    const filename = path.join(cursorHome, "hooks.json");
-    const { file, mode } = await readHooks(filename);
-    const hooks = { ...file.hooks };
-    for (const hook of CURSOR_HOOKS) {
-        const command = hookCommand(hook, dataDirectory);
-        const existing = entries(hooks[hook]);
-        if (!existing.some((entry) => entry.command === command))
-            hooks[hook] = [...existing, { command }];
-    }
-    await writeHooks(filename, { ...file, version: 1, hooks }, mode);
-}
-export async function uninstallCursorHooks(cursorHome, dataDirectory) {
-    const filename = path.join(cursorHome, "hooks.json");
-    const { file, mode } = await readHooks(filename);
-    const hooks = { ...file.hooks };
-    let changed = false;
-    for (const hook of CURSOR_HOOKS) {
-        const existing = entries(hooks[hook]);
-        const remaining = existing.filter((entry) => entry.command !== hookCommand(hook, dataDirectory));
-        if (remaining.length !== existing.length) {
-            changed = true;
-            if (remaining.length === 0)
-                delete hooks[hook];
-            else
-                hooks[hook] = remaining;
-        }
-    }
-    if (changed)
-        await writeHooks(filename, { ...file, hooks }, mode);
-}
-export async function cursorHookFiles(dataDirectory) {
-    const directory = cursorHookDirectory(dataDirectory);
-    let names;
-    try {
-        names = await fs.readdir(directory);
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return [];
-        throw error;
-    }
-    if (names.length > 10_000)
-        throw new Error("Cursor hook queue exceeds the scan limit.");
-    return names
-        .filter((name) => /^[0-9a-f-]+\.jsonl$/i.test(name))
-        .sort()
-        .map((name) => path.join(directory, name));
-}

package/dist/cursor-transcript.d.ts

@@ -1,8 +0,0 @@
-import { type TraceEvent } from "iteration-trace-contracts";
-type ParseResult = Readonly<{
-    events: readonly TraceEvent[];
-    gaps: readonly string[];
-}>;
-export declare function parseCursorTranscriptLine(line: string, filename: string, byteOffset: number): ParseResult;
-export declare function parseCursorHookLine(line: string, filename: string): ParseResult;
-export {};

package/dist/cursor-transcript.js

@@ -1,294 +0,0 @@
-import { createHash } from "node:crypto";
-import path from "node:path";
-import * as z from "zod";
-import { parseTraceEventBatch, } from "iteration-trace-contracts";
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-function record(value) {
-    const parsed = z.record(z.string(), z.json()).safeParse(value);
-    return parsed.success ? parsed.data : null;
-}
-function string(value) {
-    const parsed = z.string().safeParse(value);
-    return parsed.success ? parsed.data : null;
-}
-function nonnegativeInteger(value) {
-    const parsed = z
-        .number()
-        .int()
-        .min(0)
-        .max(Number.MAX_SAFE_INTEGER)
-        .safeParse(value);
-    return parsed.success ? parsed.data : null;
-}
-function event(conversationId, filename, byteOffset, index, eventType, payload, callId = null, occurredAt = null) {
-    const hash = createHash("sha256")
-        .update(`${filename}:${byteOffset}:${index}:${eventType}`)
-        .digest("hex");
-    return {
-        eventId: `${String(index).padStart(4, "0")}:${hash}`,
-        sessionId: `cursor:${conversationId}`,
-        sequence: byteOffset * 1000 + index,
-        callId,
-        projectId: null,
-        occurredAt,
-        eventType,
-        payload,
-    };
-}
-export function parseCursorTranscriptLine(line, filename, byteOffset) {
-    const conversationId = path.basename(filename, ".jsonl");
-    if (!UUID.test(conversationId) ||
-        path.basename(path.dirname(filename)) !== conversationId)
-        return { events: [], gaps: ["invalid_cursor_transcript_path"] };
-    let decoded;
-    try {
-        decoded = JSON.parse(line);
-    }
-    catch {
-        return { events: [], gaps: ["malformed_jsonl_record"] };
-    }
-    const source = record(decoded);
-    if (source === null)
-        return { events: [], gaps: ["record_is_not_an_object"] };
-    const events = [];
-    const gaps = [];
-    if (byteOffset === 0) {
-        events.push({
-            ...event(conversationId, filename, 0, 0, "session_meta", {
-                id: conversationId,
-                transcript_path: filename,
-            }),
-            run: {
-                kind: "identity",
-                id: conversationId,
-                parentId: null,
-                ownStart: true,
-                startOrdinal: null,
-            },
-        });
-    }
-    const role = string(source.role);
-    if (role === "user" || role === "assistant") {
-        const message = record(source.message);
-        if (message === null || !Array.isArray(message.content))
-            gaps.push("cursor_message_without_content");
-        else {
-            for (const [index, value] of message.content.entries()) {
-                const block = record(value);
-                if (block === null) {
-                    gaps.push("invalid_cursor_content_block");
-                    continue;
-                }
-                const type = string(block.type);
-                const eventType = type === "tool_use"
-                    ? "tool_call"
-                    : type === "thinking"
-                        ? "reasoning"
-                        : type === "text"
-                            ? role === "user"
-                                ? "user_message"
-                                : "assistant_message"
-                            : "source_record";
-                events.push(event(conversationId, filename, byteOffset, index + 1, eventType, {
-                    text: string(block.text) ?? string(block.thinking),
-                    name: string(block.name),
-                    input: block.input ?? null,
-                    sourceType: type,
-                    record: source,
-                }, string(block.id)));
-                if (type !== "text" && type !== "tool_use" && type !== "thinking")
-                    gaps.push(`unsupported_cursor_content_block:${type ?? "unknown"}`);
-            }
-        }
-    }
-    else if (source.type === "turn_ended") {
-        events.push(event(conversationId, filename, byteOffset, 1, source.status === "success" ? "turn_complete" : "turn_aborted", { record: source }));
-    }
-    else {
-        gaps.push(`unsupported_cursor_record:${string(source.type) ?? "unknown"}`);
-        events.push(event(conversationId, filename, byteOffset, 1, "source_record", {
-            sourceType: string(source.type),
-            record: source,
-        }));
-    }
-    return validated(events, gaps);
-}
-export function parseCursorHookLine(line, filename) {
-    let decoded;
-    try {
-        decoded = JSON.parse(line);
-    }
-    catch {
-        return { events: [], gaps: ["malformed_cursor_hook_record"] };
-    }
-    const wrapper = record(decoded);
-    const input = wrapper === null ? null : record(wrapper.input);
-    const conversationId = input === null ? null : string(input.conversation_id);
-    const hook = wrapper === null ? null : string(wrapper.hook);
-    const capturedAt = wrapper === null ? null : string(wrapper.capturedAt);
-    if (wrapper?.kind === "subagent_transcript_chunk") {
-        const subagent = record(wrapper.subagent);
-        const part = nonnegativeInteger(subagent?.part);
-        const totalParts = nonnegativeInteger(subagent?.totalParts);
-        if (conversationId === null ||
-            !UUID.test(conversationId) ||
-            capturedAt === null ||
-            Number.isNaN(Date.parse(capturedAt)) ||
-            subagent === null ||
-            part === null ||
-            totalParts === null ||
-            part < 1 ||
-            part > totalParts ||
-            string(subagent.base64) === null)
-            return { events: [], gaps: ["invalid_cursor_subagent_transcript_chunk"] };
-        const transcriptBytes = nonnegativeInteger(wrapper.transcriptBytes) ?? 0;
-        const candidate = event(conversationId, filename, transcriptBytes, part, "source_record", {
-            sourceType: "cursor_subagent_transcript",
-            text: string(subagent.text),
-            base64: string(subagent.base64),
-            path: string(subagent.path),
-            part,
-            totalParts,
-            parent_conversation_id: string(input?.parent_conversation_id),
-            subagent_id: string(input?.subagent_id),
-        }, null, capturedAt);
-        const hash = candidate.eventId.split(":").at(-1);
-        return validated([
-            {
-                ...candidate,
-                sequence: transcriptBytes * 1000 + 500,
-                eventId: `${String(Date.parse(capturedAt)).padStart(13, "0")}:${String(2000 + part).padStart(4, "0")}:${hash}`,
-            },
-        ], []);
-    }
-    if (input === null ||
-        conversationId === null ||
-        !UUID.test(conversationId) ||
-        hook === null ||
-        capturedAt === null ||
-        Number.isNaN(Date.parse(capturedAt)))
-        return { events: [], gaps: ["invalid_cursor_hook_record"] };
-    const transcriptBytes = wrapper?.transcriptBytes;
-    const sequence = nonnegativeInteger(transcriptBytes) ?? 0;
-    const events = [];
-    if (hook === "beforeSubmitPrompt" || hook === "sessionStart") {
-        const roots = Array.isArray(input.workspace_roots)
-            ? input.workspace_roots
-            : [];
-        events.push({
-            ...event(conversationId, filename, sequence, 0, "session_meta", {
-                id: conversationId,
-                cwd: string(roots[0]),
-                version: string(input.cursor_version),
-                model: string(input.model),
-                transcript_path: string(input.transcript_path),
-            }, null, capturedAt),
-            run: {
-                kind: "identity",
-                id: conversationId,
-                parentId: null,
-                ownStart: true,
-                startOrdinal: null,
-            },
-        });
-    }
-    const rawText = JSON.stringify(input);
-    if (Buffer.byteLength(rawText, "utf8") <= 500_000) {
-        events.push(event(conversationId, filename, sequence, 1, "source_record", {
-            sourceType: `cursor_hook:${hook}`,
-            record: input,
-        }, null, capturedAt));
-    }
-    else {
-        const chunks = splitText(rawText);
-        for (const [index, text] of chunks.entries())
-            events.push(event(conversationId, filename, sequence, index + 1, "source_record", {
-                sourceType: `cursor_hook:${hook}`,
-                text,
-                part: index + 1,
-                totalParts: chunks.length,
-            }, null, capturedAt));
-    }
-    const next = events.length + 1;
-    if (hook === "preToolUse") {
-        events.push(event(conversationId, filename, sequence, next, "tool_call", {
-            name: string(input.tool_name),
-            input: input.tool_input ?? null,
-        }, string(input.tool_use_id), capturedAt));
-    }
-    if (hook === "postToolUse" || hook === "postToolUseFailure") {
-        const output = string(input.tool_output) ??
-            string(input.error_message) ??
-            string(input.error) ??
-            (input.tool_output === undefined && input.error === undefined
-                ? null
-                : JSON.stringify(input.tool_output ?? input.error));
-        const chunks = output === null ? [null] : splitText(output);
-        for (const [index, text] of chunks.entries())
-            events.push(event(conversationId, filename, sequence, next + index, "tool_result", {
-                text,
-                name: string(input.tool_name),
-                part: index + 1,
-                totalParts: chunks.length,
-            }, string(input.tool_use_id), capturedAt));
-    }
-    else if (hook === "afterAgentThought") {
-        events.push(event(conversationId, filename, sequence, next, "reasoning", {
-            text: string(input.text) ?? string(input.thought),
-        }, null, capturedAt));
-    }
-    else if (hook === "afterAgentResponse" &&
-        (input.usage !== undefined ||
-            input.input_tokens !== undefined ||
-            input.output_tokens !== undefined)) {
-        events.push(event(conversationId, filename, sequence, next, "token_usage_record", {
-            model: string(input.model),
-            usage: input.usage ?? {
-                input_tokens: input.input_tokens ?? null,
-                output_tokens: input.output_tokens ?? null,
-                cache_read_tokens: input.cache_read_tokens ?? null,
-                cache_write_tokens: input.cache_write_tokens ?? null,
-            },
-        }, null, capturedAt));
-    }
-    const capturedAtMs = Date.parse(capturedAt);
-    const ordered = events.map((candidate, index) => {
-        const digest = candidate.eventId.split(":").at(-1);
-        const thought = candidate.eventType === "reasoning"
-            ? createHash("sha256")
-                .update(`${conversationId}:${string(input.generation_id)?.slice(0, 36) ?? ""}:${candidate.payload.text}`)
-                .digest("hex")
-            : null;
-        return {
-            ...candidate,
-            sequence: sequence * 1000 + 500,
-            eventId: thought === null
-                ? `${String(capturedAtMs).padStart(13, "0")}:${String(index).padStart(4, "0")}:${digest}`
-                : `thought:${thought}`,
-        };
-    });
-    return validated(ordered, []);
-}
-function splitText(value) {
-    if (value.length === 0)
-        return [""];
-    const chunks = [];
-    for (let start = 0; start < value.length;) {
-        let end = Math.min(start + 250_000, value.length);
-        if (end < value.length && /[\uD800-\uDBFF]/u.test(value[end - 1]))
-            end -= 1;
-        chunks.push(value.slice(start, end));
-        start = end;
-    }
-    return chunks;
-}
-function validated(events, gaps) {
-    const valid = [];
-    for (const candidate of events) {
-        if (parseTraceEventBatch({ events: [candidate] }).success)
-            valid.push(candidate);
-        else
-            gaps.push(`invalid_normalized_event:${candidate.eventType}`);
-    }
-    return { events: valid, gaps };
-}

package/dist/history-import.d.ts

@@ -1,17 +0,0 @@
-import { type CollectorConfig, type CollectorPaths } from "./storage.js";
-type HistoryImportSize = Readonly<{
-    files: number;
-    bytes: number;
-}>;
-export type HistoryImportControl = Readonly<{
-    isRunning: () => Promise<boolean>;
-    stop: () => Promise<void>;
-    start: (directory: string) => Promise<unknown>;
-    acquireLock: (paths: CollectorPaths) => Promise<() => Promise<void>>;
-}>;
-export declare function importSourceHistory(config: CollectorConfig, paths: CollectorPaths, confirmed: boolean, control?: HistoryImportControl): Promise<Readonly<{
-    imported: boolean;
-    size: HistoryImportSize;
-    backgroundRunning: boolean | null;
-}>>;
-export {};

package/dist/history-import.js

@@ -1,63 +0,0 @@
-import path from "node:path";
-import { backgroundServiceStatus, installBackgroundService, uninstallBackgroundService, } from "./background-service.js";
-import { waitForCollectorLock } from "./service.js";
-import { collectorSource, collectorSourceDirectory, historyImportSize, loadState, resetHistoryCursors, } from "./storage.js";
-function backgroundControl(source) {
-    return {
-        isRunning: () => backgroundServiceStatus(source),
-        stop: () => uninstallBackgroundService(source),
-        start: (directory) => installBackgroundService(directory, source),
-        acquireLock: waitForCollectorLock,
-    };
-}
-export async function importSourceHistory(config, paths, confirmed, control = backgroundControl(collectorSource(config))) {
-    const source = collectorSource(config);
-    const directory = collectorSourceDirectory(config);
-    const state = await loadState(paths);
-    if (!state.initialized || state.sourceDirectory !== path.resolve(directory)) {
-        throw new Error(`Connect the ${source} source before importing its history.`);
-    }
-    const estimate = await historyImportSize(directory, source);
-    if (!confirmed)
-        return { imported: false, size: estimate, backgroundRunning: null };
-    const wasRunning = await control.isRunning();
-    let size = null;
-    let stopAttempted = false;
-    let rewound = false;
-    let failure = null;
-    try {
-        if (wasRunning) {
-            stopAttempted = true;
-            await control.stop();
-        }
-        const releaseLock = await control.acquireLock(paths);
-        try {
-            size = await resetHistoryCursors(directory, paths, source);
-            rewound = true;
-        }
-        finally {
-            await releaseLock();
-        }
-    }
-    catch (error) {
-        failure = { error };
-    }
-    if (stopAttempted) {
-        try {
-            await control.start(config.dataDirectory);
-        }
-        catch (error) {
-            throw new Error(rewound
-                ? `History checkpoints were rewound, but the collector could not restart. Run iteration start ${source} to resume uploads.`
-                : `The collector could not be restored after a failed history import. Run iteration start ${source} to resume uploads.`, {
-                cause: failure ? new AggregateError([failure.error, error]) : error,
-            });
-        }
-    }
-    if (failure)
-        throw failure.error;
-    if (size === null) {
-        throw new Error("History import did not update checkpoints.");
-    }
-    return { imported: true, size, backgroundRunning: wasRunning };
-}

package/dist/launch-agent.d.ts

@@ -1,13 +0,0 @@
-import type { CollectorSource } from "iteration-trace-contracts";
-export type LaunchAgentRestart = {
-    isLoaded(timeoutMs: number): Promise<boolean>;
-    bootstrap(timeoutMs: number): Promise<void>;
-    wait(delayMs: number): Promise<void>;
-    now(): number;
-};
-export declare function launchAgentPlist(cliPath?: string, nodePath?: string, logDirectory?: string, dataDirectory?: string, source?: CollectorSource): string;
-export declare function bootstrapAfterBootout(wasLoaded: boolean, control: LaunchAgentRestart): Promise<void>;
-export declare function installLaunchAgent(dataDirectory?: string, source?: CollectorSource): Promise<string>;
-export declare function uninstallLaunchAgent(source?: CollectorSource): Promise<void>;
-export declare function launchAgentStatus(source?: CollectorSource): Promise<boolean>;
-export declare function launchAgentRunning(output: string): boolean;