iteration-cli 0.4.0 → 0.4.2

package/README.md

@@ -4,11 +4,10 @@ Install one CLI for Iteration's supported coding-agent sources:
 
 ```sh
 npm install --global iteration-cli
-iteration connect codex
-iteration status codex
+iteration
 ```
 
-The Codex collector currently runs on macOS with Node.js 22 or later. `iteration connect codex --include-history` also imports earlier local sessions after you approve access. Run `iteration help` for the available commands.
+The Codex collector currently runs on macOS with Node.js 22 or later. Connecting imports existing local Codex sessions and collects new activity. Run `iteration status` to check uploads, or `iteration help` for other commands.
 
 If you previously installed the Codex-specific package, remove it with the package manager you used:
 
@@ -18,4 +17,4 @@ pnpm remove --global iteration-codex-collector
 npm uninstall --global iteration-codex-collector
 ```
 
-Then install `iteration-cli` and run `iteration start codex`. This points the existing background collector at the new CLI. Its local configuration and pending events remain in place.
+Then install `iteration-cli` and run `iteration start codex`. This points the existing background collector at the new CLI and schedules a one-time backfill of earlier local sessions. Its local configuration and pending events remain in place.

package/dist/clerk-device-auth.js

@@ -164,13 +164,13 @@ async function pollForAccessToken(tokenUrl, clientId, deviceCode, expiresIn, ini
             case "access_denied":
                 throw new Error("You denied Iteration collector access.");
             case "expired_token":
-                throw new Error("The sign-in code expired. Run init again.");
+                throw new Error("The sign-in code expired. Run iteration again.");
             default:
                 throw new Error("Clerk device sign-in failed: " +
                     (providerError.data.error_description ?? providerError.data.error));
         }
     }
-    throw new Error("The sign-in code expired. Run init again.");
+    throw new Error("The sign-in code expired. Run iteration again.");
 }
 async function clerkDeviceSignIn(configuration) {
     const endpoints = await discoverDeviceEndpoints(configuration.issuerUrl);
@@ -218,7 +218,7 @@ async function chooseOrganization(organizations, hasMore) {
         process.stdout.write("More workspaces exist; enter an organization ID to choose one not listed.\n");
     }
     if (process.stdin.isTTY !== true) {
-        throw new Error("Run init interactively or pass --organization-id.");
+        throw new Error("Run iteration interactively or pass --organization-id.");
     }
     const prompt = createInterface({
         input: process.stdin,

package/dist/cli.js

@@ -8,7 +8,7 @@ import { authenticateAndEnrollCollector } from "./clerk-device-auth.js";
 import { importCodexHistory } from "./history-import.js";
 import { runCollector } from "./service.js";
 import { installLaunchAgent, launchAgentStatus, uninstallLaunchAgent, } from "./launch-agent.js";
-import { assertFreshCollectorDirectory, collectorPaths, ensureStartableState, loadConfig, outboxSize, pendingEventIds, prepareInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
+import { assertFreshCollectorDirectory, collectorPaths, ensureStartableState, historyScanProgress, loadConfig, outboxSize, pendingEventIds, prepareInitialState, saveConfig, saveState, validateCollectorEndpoint, } from "./storage.js";
 const DEFAULT_INGEST_ENDPOINT = "https://useiteration.com/api/traces/ingest";
 function argumentsForCli() {
     const parsed = parseArgs({
@@ -30,7 +30,7 @@ function argumentsForCli() {
         throw new Error("Too many command arguments. Run iteration help for usage.");
     }
     return {
-        command: parsed.positionals[0] ?? "help",
+        command: parsed.positionals[0] ?? "",
         source: parsed.positionals[1],
         values: parsed.values,
     };
@@ -45,16 +45,63 @@ function optionalString(values, name) {
     }
     return parsed.data;
 }
-function usage() {
+function usage(command) {
+    if (command === "connect") {
+        process.stdout.write([
+            "Connect Codex to Iteration",
+            "  iteration connect codex",
+            "",
+            "Existing local sessions and new activity are collected automatically.",
+            "",
+            "Options for advanced setups:",
+            "  --device-name NAME      Name this Mac in Iteration",
+            "  --organization-id UUID  Select a workspace without a prompt",
+            "  --codex-home DIR        Use a different Codex data directory",
+            "  --data-directory DIR   Use a different Iteration state directory",
+            "  --endpoint URL         Use a different Iteration server",
+        ].join("\n") + "\n");
+        return;
+    }
     process.stdout.write([
         "Iteration CLI",
-        "  iteration connect codex [--endpoint URL] [--device-name NAME] [--organization-id UUID] [--include-history] [--codex-home DIR] [--data-directory DIR]",
-        "  iteration status codex [--data-directory DIR]",
-        "  iteration import-history codex [--data-directory DIR] [--yes]",
-        "  iteration start codex [--data-directory DIR]",
-        "  iteration disconnect codex",
+        "",
+        "Get started:",
+        "  iteration                 Connect Codex, or show connection status",
+        "",
+        "Commands:",
+        "  iteration connect codex   Connect Codex directly",
+        "  iteration status          Check uploads and connection",
+        "  iteration disconnect codex      Stop collecting",
+        "",
+        "Run iteration connect codex --help for advanced setup options.",
     ].join("\n") + "\n");
 }
+async function configured(paths) {
+    try {
+        await fs.access(paths.config);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return false;
+        }
+        throw new Error(`Could not inspect collector config at ${paths.config}.`, {
+            cause: error,
+        });
+    }
+}
+async function defaultCommand() {
+    const paths = collectorPaths(dataDirectory({}));
+    if (await configured(paths)) {
+        await status({});
+        return;
+    }
+    if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        process.stdout.write("Run iteration in a terminal to connect Codex.\n");
+        return;
+    }
+    await initialize({});
+}
 function dataDirectory(values) {
     return path.resolve(optionalString(values, "data-directory") ??
         path.join(os.homedir(), ".config", "iteration", "codex-collector"));
@@ -69,12 +116,11 @@ async function initialize(values) {
     const organizationId = optionalString(values, "organization-id");
     const directory = dataDirectory(values);
     const paths = collectorPaths(directory);
-    const includeHistory = values["include-history"] === true;
     const codexHome = path.resolve(optionalString(values, "codex-home") ??
         process.env.CODEX_HOME ??
         path.join(os.homedir(), ".codex"));
     await assertFreshCollectorDirectory(paths);
-    const preparedState = await prepareInitialState(codexHome, includeHistory);
+    const preparedState = await prepareInitialState(codexHome, true);
     const enrollment = await authenticateAndEnrollCollector(endpointUrl, deviceName, organizationId);
     const config = {
         endpoint: endpointUrl.toString(),
@@ -89,14 +135,13 @@ async function initialize(values) {
     catch (error) {
         throw new Error("Collector access was approved, but local setup did not finish. Run iteration start codex to repair it.", { cause: error });
     }
-    let agentFile;
     try {
-        agentFile = await installLaunchAgent(directory);
+        await installLaunchAgent(directory);
     }
     catch (error) {
         throw new Error("Collector access was approved, but background startup failed. Run iteration start codex to retry it.", { cause: error });
     }
-    process.stdout.write(`Collector installed for ${enrollment.organizationName} and set to start at login. ${includeHistory ? "Existing sessions will be imported." : "Existing sessions are skipped; new activity will be collected."}\nLaunch agent: ${agentFile}\n`);
+    process.stdout.write(`Codex connected to ${enrollment.organizationName}. Existing local sessions and new activity will upload in the background. Run iteration status to check uploads.\n`);
 }
 async function importHistory(values) {
     if (process.platform !== "darwin") {
@@ -112,7 +157,7 @@ async function importHistory(values) {
         return;
     }
     const result = await importCodexHistory(config, paths, true);
-    process.stdout.write(`History scan scheduled for ${result.size.files} local session files (${result.size.bytes} bytes). Scanning and uploads run in bounded batches and may take time. Older sessions appear under the date Iteration receives them. iteration status codex shows events waiting to upload, not total scan progress.${result.backgroundRunning ? "" : " The collector was not running; run iteration start codex to begin scanning."}\n`);
+    process.stdout.write(`History scan scheduled for ${result.size.files} local session files (${result.size.bytes} bytes). Scanning and uploads run in bounded batches and may take time. Older sessions appear under the date Iteration receives them. Use iteration status to see local scan progress and pending uploads.${result.backgroundRunning ? "" : " The collector was not running; run iteration start codex to begin scanning."}\n`);
 }
 async function start(values) {
     if (process.platform !== "darwin") {
@@ -123,39 +168,49 @@ async function start(values) {
     const config = await loadConfig(paths);
     const repairedState = await ensureStartableState(config, paths);
     await installLaunchAgent(directory);
-    process.stdout.write(`Collector started. Run iteration status codex to check uploads.${repairedState ? " Incomplete setup was repaired with new activity only; use iteration import-history codex if you want to include earlier local sessions." : ""}\n`);
+    process.stdout.write(`Collector started. Existing local sessions and new activity will upload in the background. Run iteration status to check uploads.${repairedState ? " Incomplete setup was repaired." : ""}\n`);
 }
 async function status(values) {
     const paths = collectorPaths(dataDirectory(values));
-    try {
-        await fs.access(paths.config);
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-            process.stdout.write("Installed: false\nRunning: false\nPending events: 0\n");
-            return;
-        }
-        throw new Error(`Could not inspect collector config at ${paths.config}.`, {
-            cause: error,
-        });
+    if (!(await configured(paths))) {
+        process.stdout.write("Installed: false\nRunning: false\nPending events: 0\n");
+        return;
     }
-    await loadConfig(paths);
+    const config = await loadConfig(paths);
     const running = await launchAgentStatus();
-    const [size, ids] = await Promise.all([
+    const [size, ids, scan] = await Promise.all([
         outboxSize(paths),
         pendingEventIds(paths),
+        historyScanProgress(config.codexHome, paths),
     ]);
+    const scanLabel = scan.kind === "waiting"
+        ? "Local history: waiting for collector start"
+        : scan.totalBytes === 0
+            ? "Local scan: no session data found"
+            : `Local scan: ${scan.scannedBytes} of ${scan.totalBytes} bytes processed`;
     process.stdout.write([
         "Installed: true",
         `Running: ${running}`,
+        scanLabel,
         `Pending events: ${ids.size}`,
         `Pending bytes: ${size}`,
     ].join("\n") + "\n");
 }
 async function main() {
     const { command, source, values } = argumentsForCli();
-    if (values.help === true || command === "help")
-        return usage();
+    if (values.help === true || command === "help") {
+        return usage(command === "help" ? source : command);
+    }
+    if (values["include-history"] === true &&
+        !(command === "connect" && source === "codex")) {
+        throw new Error("Existing sessions are included automatically. Run iteration to connect.");
+    }
+    if (command === "" || (command === "connect" && source === undefined)) {
+        if (Object.keys(values).length > 0) {
+            throw new Error("Options require a source. Run iteration connect codex --help for details.");
+        }
+        return defaultCommand();
+    }
     if (command === "connect" && source === "codex")
         return initialize(values);
     if (command === "run") {
@@ -163,7 +218,7 @@ async function main() {
             throw new Error("The run command takes no source.");
         return runCollector(optionalString(values, "data-directory") ?? undefined);
     }
-    if (command === "status" && source === "codex")
+    if (command === "status" && (source === undefined || source === "codex"))
         return status(values);
     if (command === "import-history" && source === "codex")
         return importHistory(values);
@@ -177,6 +232,6 @@ async function main() {
     throw new Error(`Unknown Iteration command: ${[command, source].filter(Boolean).join(" ")}. Run iteration help for usage.`);
 }
 main().catch((error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : "Unknown collector error."}\n`);
+    process.stderr.write(`${error instanceof Error ? error.message : "Unknown Iteration CLI error."}\n`);
     process.exitCode = 1;
 });

package/dist/launch-agent.d.ts

@@ -2,3 +2,4 @@ export declare function launchAgentPlist(cliPath?: string, nodePath?: string, lo
 export declare function installLaunchAgent(dataDirectory?: string): Promise<string>;
 export declare function uninstallLaunchAgent(): Promise<void>;
 export declare function launchAgentStatus(): Promise<boolean>;
+export declare function launchAgentRunning(output: string): boolean;

package/dist/launch-agent.js

@@ -79,6 +79,7 @@ export async function installLaunchAgent(dataDirectory) {
     const target = launchctlTarget();
     await bootoutIfLoaded(target);
     await execFile("launchctl", ["bootstrap", target, file]);
+    await execFile("launchctl", ["kickstart", "-p", `${target}/${LABEL}`]);
     return file;
 }
 export async function uninstallLaunchAgent() {
@@ -93,10 +94,17 @@ export async function launchAgentStatus() {
     if (process.platform !== "darwin")
         return false;
     try {
-        await execFile("launchctl", ["print", `${launchctlTarget()}/${LABEL}`]);
-        return true;
+        const { stdout } = await execFile("launchctl", [
+            "print",
+            `${launchctlTarget()}/${LABEL}`,
+        ]);
+        return launchAgentRunning(stdout);
     }
     catch {
         return false;
     }
 }
+export function launchAgentRunning(output) {
+    const state = output.match(/^\s*state = ([^\r\n]+)$/m);
+    return state?.[1]?.trim() === "running";
+}

package/dist/service.js

@@ -2,7 +2,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { collectorTick } from "./collector.js";
-import { collectorPaths, ensurePrivateDirectory, loadConfig, } from "./storage.js";
+import { collectorPaths, ensureHistoryBackfill, ensurePrivateDirectory, loadConfig, } from "./storage.js";
 function errorCode(error) {
     if (error instanceof Error && "code" in error)
         return String(error.code);
@@ -75,6 +75,7 @@ export async function runCollector(directory) {
     let retryDelayMs = 5000;
     try {
         const config = await loadConfig(paths);
+        await ensureHistoryBackfill(config.codexHome, paths);
         while (!controller.signal.aborted) {
             try {
                 const result = await collectorTick(config, paths, fetch, controller.signal);

package/dist/storage.d.ts

@@ -16,6 +16,7 @@ export type CollectorPaths = Readonly<{
     state: string;
     outbox: string;
     lock: string;
+    historyBackfill: string;
 }>;
 export declare function validateCollectorEndpoint(endpoint: string): URL;
 export declare function collectorPaths(directory?: string): CollectorPaths;
@@ -33,6 +34,14 @@ export declare function acknowledgeEvents(acknowledgedIds: ReadonlySet<string>,
 export declare function initializeState(codexHome: string, paths: CollectorPaths, includeHistory: boolean): Promise<void>;
 export declare function prepareInitialState(codexHome: string, includeHistory: boolean): Promise<CollectorState>;
 export declare function ensureStartableState(config: CollectorConfig, paths: CollectorPaths): Promise<boolean>;
+export declare function ensureHistoryBackfill(codexHome: string, paths: CollectorPaths): Promise<boolean>;
+export declare function historyScanProgress(codexHome: string, paths: CollectorPaths): Promise<Readonly<{
+    kind: "waiting";
+} | {
+    kind: "scanning";
+    scannedBytes: number;
+    totalBytes: number;
+}>>;
 export declare function resetHistoryCursors(codexHome: string, paths: CollectorPaths): Promise<Readonly<{
     files: number;
     bytes: number;

package/dist/storage.js

@@ -73,6 +73,7 @@ export function collectorPaths(directory = defaultDirectory()) {
         state: path.join(directory, "state.json"),
         outbox: path.join(directory, "outbox.jsonl"),
         lock: path.join(directory, "collector.lock"),
+        historyBackfill: path.join(directory, "history-backfill.json"),
     };
 }
 export async function assertFreshCollectorDirectory(paths) {
@@ -323,10 +324,10 @@ export async function prepareInitialState(codexHome, includeHistory) {
     const sessionsRoot = path.join(sourceDirectory, "sessions");
     const files = await rolloutFiles(sessionsRoot);
     const cursors = {};
-    for (const filename of files) {
-        cursors[filename] = includeHistory
-            ? 0
-            : await lastCompleteRecordOffset(filename, (await fs.stat(filename)).size);
+    if (!includeHistory) {
+        for (const filename of files) {
+            cursors[filename] = await lastCompleteRecordOffset(filename, (await fs.stat(filename)).size);
+        }
     }
     return {
         cursors,
@@ -346,9 +347,80 @@ export async function ensureStartableState(config, paths) {
     if ((await outboxSize(paths)) > 0) {
         throw new Error("Pending events exist without an initialized checkpoint; repair the collector state before starting uploads.");
     }
-    await initializeState(config.codexHome, paths, false);
+    await initializeState(config.codexHome, paths, true);
     return true;
 }
+async function hasHistoryBackfillMarker(paths) {
+    let marker;
+    try {
+        marker = await fs.readFile(paths.historyBackfill, "utf8");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+        marker = null;
+    }
+    if (marker !== null) {
+        if (marker !== '{"version":1}\n') {
+            throw new Error("Collector history backfill marker has an invalid shape.");
+        }
+        return true;
+    }
+    return false;
+}
+export async function ensureHistoryBackfill(codexHome, paths) {
+    if (await hasHistoryBackfillMarker(paths))
+        return false;
+    const state = await loadState(paths);
+    if (!state.initialized || state.sourceDirectory !== path.resolve(codexHome)) {
+        throw new Error("Collector state does not match CODEX_HOME; reconnect Codex before uploading.");
+    }
+    await rolloutFiles(path.join(codexHome, "sessions"));
+    await saveState({ ...state, cursors: {}, skipping: [] }, paths);
+    await writeJsonAtomic(paths.historyBackfill, { version: 1 });
+    return true;
+}
+export async function historyScanProgress(codexHome, paths) {
+    if (!(await hasHistoryBackfillMarker(paths)))
+        return { kind: "waiting" };
+    const state = await loadState(paths);
+    if (!state.initialized || state.sourceDirectory !== path.resolve(codexHome)) {
+        throw new Error("Collector state does not match CODEX_HOME.");
+    }
+    const files = await rolloutFiles(path.join(codexHome, "sessions"));
+    let scannedBytes = 0;
+    let totalBytes = 0;
+    for (let start = 0; start < files.length; start += 64) {
+        const batch = files.slice(start, start + 64);
+        const sizes = await Promise.all(batch.map(async (filename) => {
+            try {
+                return (await fs.stat(filename)).size;
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT")
+                    return null;
+                throw error;
+            }
+        }));
+        for (const [index, size] of sizes.entries()) {
+            if (size === null)
+                continue;
+            const filename = batch[index];
+            if (filename === undefined)
+                continue;
+            totalBytes += size;
+            const cursor = state.cursors[filename] ?? 0;
+            scannedBytes += cursor <= size ? cursor : 0;
+            if (!Number.isSafeInteger(totalBytes) ||
+                !Number.isSafeInteger(scannedBytes)) {
+                throw new Error("Codex history size exceeds the supported limit.");
+            }
+        }
+    }
+    return { kind: "scanning", scannedBytes, totalBytes };
+}
 export async function resetHistoryCursors(codexHome, paths) {
     const state = await loadState(paths);
     const sourceDirectory = path.resolve(codexHome);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iteration-cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "repository": {
     "type": "git",