iteration-cli 0.4.0 → 0.4.1

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

@@ -22,7 +22,6 @@ function argumentsForCli() {
             "organization-id": { type: "string" },
             "codex-home": { type: "string" },
             "data-directory": { type: "string" },
-            "include-history": { type: "boolean" },
             yes: { type: "boolean" },
         },
     });
@@ -30,7 +29,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 +44,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 +115,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 +134,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") {
@@ -123,21 +167,13 @@ 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 running = await launchAgentStatus();
@@ -154,8 +190,15 @@ async function status(values) {
 }
 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 (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 +206,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 +220,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/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,7 @@ 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 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) {
@@ -321,12 +322,11 @@ export async function initializeState(codexHome, paths, includeHistory) {
 export async function prepareInitialState(codexHome, includeHistory) {
     const sourceDirectory = path.resolve(codexHome);
     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 await rolloutFiles(sessionsRoot)) {
+            cursors[filename] = await lastCompleteRecordOffset(filename, (await fs.stat(filename)).size);
+        }
     }
     return {
         cursors,
@@ -346,7 +346,31 @@ 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;
+}
+export async function ensureHistoryBackfill(codexHome, 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 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 saveState({ ...state, cursors: {}, skipping: [] }, paths);
+    await writeJsonAtomic(paths.historyBackfill, { version: 1 });
     return true;
 }
 export async function resetHistoryCursors(codexHome, paths) {

package/package.json

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