iteration-cli 0.9.0 → 0.10.0

package/dist/systemd-user.d.ts

@@ -1,7 +0,0 @@
-import type { CollectorSource } from "iteration-trace-contracts";
-export declare function ensureSystemdUserLinger(): Promise<void>;
-export declare function systemdLogPath(source: CollectorSource): string;
-export declare function systemdUserUnit(cliPath?: string, nodePath?: string, dataDirectory?: string, source?: CollectorSource, outputPath?: string, errorPath?: string): string;
-export declare function installSystemdUserService(dataDirectory: string, source: CollectorSource): Promise<string>;
-export declare function uninstallSystemdUserService(source: CollectorSource): Promise<void>;
-export declare function systemdUserServiceStatus(source: CollectorSource): Promise<boolean>;

package/dist/systemd-user.js

@@ -1,137 +0,0 @@
-import { execFile as execFileCallback } from "node:child_process";
-import { promises as fs } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
-const execFile = promisify(execFileCallback);
-const SYSTEMCTL_TIMEOUT_MS = 10_000;
-const LOGINCTL_TIMEOUT_MS = 10_000;
-function currentUserId() {
-    const userId = process.getuid?.();
-    if (userId === undefined)
-        throw new Error("Could not determine the current Linux user id.");
-    return String(userId);
-}
-async function lingerState(userId) {
-    const { stdout } = await execFile("loginctl", ["show-user", userId, "--property=Linger", "--value"], { timeout: LOGINCTL_TIMEOUT_MS });
-    const state = stdout.trim();
-    if (state === "yes" || state === "no")
-        return state;
-    throw new Error(`Could not read Linux background service setting: ${state || "empty response"}.`);
-}
-export async function ensureSystemdUserLinger() {
-    const userId = currentUserId();
-    let state = "no";
-    let queryFailure;
-    try {
-        state = await lingerState(userId);
-    }
-    catch (error) {
-        queryFailure = error;
-    }
-    if (state === "yes")
-        return;
-    try {
-        await execFile("loginctl", ["--no-ask-password", "enable-linger", userId], {
-            timeout: LOGINCTL_TIMEOUT_MS,
-        });
-    }
-    catch (userError) {
-        try {
-            await execFile("sudo", ["-n", "loginctl", "enable-linger", userId], {
-                timeout: LOGINCTL_TIMEOUT_MS,
-            });
-        }
-        catch (adminError) {
-            throw new Error("This server does not allow Iteration to keep collecting after you log out. Ask an administrator to allow background services for your account, then run iteration connect again.", {
-                cause: new AggregateError(queryFailure
-                    ? [queryFailure, userError, adminError]
-                    : [userError, adminError], "Could not enable Linux background collection."),
-            });
-        }
-    }
-    try {
-        if ((await lingerState(userId)) === "yes")
-            return;
-    }
-    catch (error) {
-        throw new Error("Could not verify Linux background collection after logout.", {
-            cause: error,
-        });
-    }
-    throw new Error("Linux did not enable background collection after logout.");
-}
-function unitName(source) {
-    return `iteration-${source}-collector.service`;
-}
-function unitPath(source) {
-    return path.join(os.homedir(), ".config", "systemd", "user", unitName(source));
-}
-export function systemdLogPath(source) {
-    return path.join(os.homedir(), ".config", "iteration", "logs", `iteration-${source}-collector.error.log`);
-}
-function unitValue(value) {
-    if (/[\r\n\0]/.test(value))
-        throw new Error("Collector paths cannot contain line breaks.");
-    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("%", "%%")}"`;
-}
-export function systemdUserUnit(cliPath = fileURLToPath(new URL("./cli.js", import.meta.url)), nodePath = process.execPath, dataDirectory = path.join(os.homedir(), ".config", "iteration", "codex-collector"), source = "codex", outputPath = path.join(os.homedir(), ".config", "iteration", "logs", `iteration-${source}-collector.log`), errorPath = systemdLogPath(source)) {
-    return [
-        "[Unit]",
-        `Description=Iteration ${source} collector`,
-        "[Service]",
-        "Type=exec",
-        `ExecStart=${[nodePath, cliPath, "run", source, "--data-directory", dataDirectory].map(unitValue).join(" ")}`,
-        "Restart=always",
-        "RestartSec=5",
-        `StandardOutput=append:${unitValue(outputPath)}`,
-        `StandardError=append:${unitValue(errorPath)}`,
-        "[Install]",
-        "WantedBy=default.target",
-        "",
-    ].join("\n");
-}
-async function systemctl(...args) {
-    const { stdout } = await execFile("systemctl", ["--user", ...args], {
-        timeout: SYSTEMCTL_TIMEOUT_MS,
-    });
-    return stdout.trim();
-}
-export async function installSystemdUserService(dataDirectory, source) {
-    await ensureSystemdUserLinger();
-    const file = unitPath(source);
-    const logDirectory = path.dirname(systemdLogPath(source));
-    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
-    await fs.mkdir(logDirectory, { recursive: true, mode: 0o700 });
-    await fs.writeFile(file, systemdUserUnit(undefined, undefined, dataDirectory, source), {
-        encoding: "utf8",
-        mode: 0o644,
-    });
-    await systemctl("daemon-reload");
-    await systemctl("enable", unitName(source));
-    await systemctl("restart", unitName(source));
-    return file;
-}
-export async function uninstallSystemdUserService(source) {
-    const file = unitPath(source);
-    try {
-        await fs.access(file);
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return;
-        throw error;
-    }
-    await systemctl("disable", "--now", unitName(source));
-    await fs.rm(file);
-    await systemctl("daemon-reload");
-}
-export async function systemdUserServiceStatus(source) {
-    const state = await systemctl("show", "--property=ActiveState", "--value", unitName(source));
-    if (state === "active")
-        return true;
-    if (state === "inactive" || state === "failed")
-        return false;
-    throw new Error(`Could not determine ${source} collector service state: ${state || "empty response"}.`);
-}

package/dist/turn-summary.d.ts

@@ -1,23 +0,0 @@
-import { type CollectorFrictionSummary } from "iteration-trace-contracts";
-import { type CollectorFetcher } from "./collector-fetch.js";
-import { type CollectorConfig } from "./storage.js";
-export type TurnSummaryPaths = Readonly<{
-    directory: string;
-    script: string;
-    requests: string;
-    lines: string;
-    shown: string;
-}>;
-export declare function turnSummaryPaths(dataDirectory: string): TurnSummaryPaths;
-export declare function installTurnSummary(config: CollectorConfig): Promise<void>;
-export declare function uninstallTurnSummary(config: CollectorConfig): Promise<void>;
-export declare function turnSummaryMessage(summary: CollectorFrictionSummary): string | null;
-export declare class TurnSummaryRefreshError extends Error {
-    constructor(message: string, options?: ErrorOptions);
-}
-export declare function refreshTurnSummaries(config: CollectorConfig, refreshedAt: Map<string, Readonly<{
-    directory: string;
-    atMs: number;
-}>>, nowMs: number, fetcher?: CollectorFetcher, signal?: AbortSignal): Promise<number>;
-export type TurnSummaryApproval = "approved" | "needs_approval" | "not_installed";
-export declare function codexTurnSummaryApproval(config: CollectorConfig): Promise<TurnSummaryApproval>;

package/dist/turn-summary.js

@@ -1,365 +0,0 @@
-import { createHash } from "node:crypto";
-import { promises as fs } from "node:fs";
-import path from "node:path";
-import { isLaunchDirectory, parseCollectorFrictionSummary, } from "iteration-trace-contracts";
-import * as z from "zod";
-import { collectorFetch } from "./collector-fetch.js";
-import { ensurePrivateDirectory } from "./storage.js";
-const REFRESH_INTERVAL_MS = 5 * 60 * 1000;
-const REQUEST_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
-const MAX_REFRESHES_PER_PASS = 20;
-const REQUEST_TIMEOUT_MS = 10_000;
-const HOOK_TIMEOUT_SECONDS = 1;
-const REQUEST_KEY_PATTERN = /^\d{1,10}$/;
-export function turnSummaryPaths(dataDirectory) {
-    const directory = path.join(dataDirectory, "turn-summary");
-    return {
-        directory,
-        script: path.join(directory, "stop-hook.sh"),
-        requests: path.join(directory, "requests"),
-        lines: path.join(directory, "lines"),
-        shown: path.join(directory, "shown"),
-    };
-}
-function shellQuote(value) {
-    return `'${value.replaceAll("'", `'\\''`)}'`;
-}
-// The hook runs at the end of every agent turn, so it only reads files the
-// collector keeps current and never waits on the network. Every failure prints
-// the empty object both agents accept, so a broken summary never blocks a turn.
-function hookScript(paths) {
-    return `#!/bin/sh
-exec 2>/dev/null
-cat >/dev/null
-summary=${shellQuote(paths.directory)}
-quiet() { printf '{}\\n'; exit 0; }
-unset GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_PREFIX
-cd "\${CLAUDE_PROJECT_DIR:-.}" || quiet
-directory=$(git rev-parse --show-toplevel) || quiet
-case $directory in /*) ;; *) quiet ;; esac
-set -- $(printf '%s' "$directory" | cksum)
-key=$1
-[ -n "$key" ] || quiet
-printf '%s\\n' "$directory" > "$summary/requests/$key"
-[ -f "$summary/lines/$key" ] || quiet
-{ IFS= read -r owner && IFS= read -r message; } < "$summary/lines/$key" || quiet
-[ "$owner" = "$directory" ] || quiet
-last=
-[ -f "$summary/shown/$key" ] && IFS= read -r last < "$summary/shown/$key"
-[ "$last" = "$message" ] && quiet
-printf '%s\\n' "$message" > "$summary/shown/$key" || quiet
-printf '%s\\n' "$message"
-`;
-}
-function hookCommand(paths) {
-    return `/bin/sh ${shellQuote(paths.script)}`;
-}
-function agentHookFile(config) {
-    if ("cursorHome" in config)
-        throw new Error("Cursor uses its own trace hooks.");
-    return "claudeHome" in config
-        ? path.join(config.claudeHome, "settings.json")
-        : path.join(config.codexHome, "hooks.json");
-}
-const hookEntrySchema = z.object({ command: z.string().optional() }).loose();
-const hookGroupSchema = z
-    .object({ hooks: z.array(hookEntrySchema).optional() })
-    .loose();
-const hookFileSchema = z
-    .object({
-    hooks: z
-        .object({ Stop: z.array(hookGroupSchema).optional() })
-        .loose()
-        .optional(),
-})
-    .loose();
-async function readHookFile(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 agent hooks at ${filename}.`, {
-            cause: error,
-        });
-    }
-    let decoded;
-    try {
-        decoded = JSON.parse(contents);
-    }
-    catch (error) {
-        throw new Error(`Agent hooks at ${filename} are not valid JSON.`, {
-            cause: error,
-        });
-    }
-    const parsed = hookFileSchema.safeParse(decoded);
-    if (!parsed.success) {
-        throw new Error(`Agent hooks at ${filename} have an unexpected shape.`, {
-            cause: parsed.error,
-        });
-    }
-    return { file: parsed.data, mode };
-}
-async function writeHookFile(filename, file, mode) {
-    await fs.mkdir(path.dirname(filename), { recursive: true });
-    // Settings kept in a dotfiles repository are often symlinks; replacing the
-    // link with a file would silently detach them from that repository.
-    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`;
-    await fs.writeFile(temporary, `${JSON.stringify(file, null, 2)}\n`, {
-        encoding: "utf8",
-        mode,
-    });
-    await fs.rename(temporary, target);
-}
-function withoutCommand(groups, command) {
-    return groups.flatMap((group) => {
-        const hooks = group.hooks?.filter((hook) => hook.command !== command);
-        if (hooks === undefined || hooks.length === group.hooks?.length)
-            return [group];
-        return hooks.length === 0 ? [] : [{ ...group, hooks }];
-    });
-}
-function hasCommand(groups, command) {
-    return groups.some((group) => group.hooks?.some((hook) => hook.command === command));
-}
-export async function installTurnSummary(config) {
-    const paths = turnSummaryPaths(config.dataDirectory);
-    await ensurePrivateDirectory(paths.directory);
-    await Promise.all([paths.requests, paths.lines, paths.shown].map(ensurePrivateDirectory));
-    await fs.writeFile(paths.script, hookScript(paths), {
-        encoding: "utf8",
-        mode: 0o700,
-    });
-    await fs.chmod(paths.script, 0o700);
-    const filename = agentHookFile(config);
-    const { file, mode } = await readHookFile(filename);
-    const command = hookCommand(paths);
-    const stop = file.hooks?.Stop ?? [];
-    if (hasCommand(stop, command))
-        return;
-    await writeHookFile(filename, {
-        ...file,
-        hooks: {
-            ...file.hooks,
-            Stop: [
-                ...stop,
-                {
-                    hooks: [
-                        { type: "command", command, timeout: HOOK_TIMEOUT_SECONDS },
-                    ],
-                },
-            ],
-        },
-    }, mode);
-}
-export async function uninstallTurnSummary(config) {
-    const filename = agentHookFile(config);
-    const { file, mode } = await readHookFile(filename);
-    const stop = file.hooks?.Stop ?? [];
-    const command = hookCommand(turnSummaryPaths(config.dataDirectory));
-    if (!hasCommand(stop, command))
-        return;
-    const remaining = withoutCommand(stop, command);
-    const { Stop: _removed, ...otherEvents } = file.hooks ?? {};
-    await writeHookFile(filename, {
-        ...file,
-        hooks: remaining.length === 0
-            ? otherEvents
-            : { ...otherEvents, Stop: remaining },
-    }, mode);
-}
-export function turnSummaryMessage(summary) {
-    if (summary.weekEpisodes === 0)
-        return null;
-    const episodes = `${summary.weekEpisodes} friction episode${summary.weekEpisodes === 1 ? "" : "s"}`;
-    const recent = summary.dayEpisodes === 0
-        ? ""
-        : ` · ${summary.dayEpisodes} new since yesterday`;
-    return `◆ Iteration · ${episodes} in this repo this week${recent}`;
-}
-export class TurnSummaryRefreshError extends Error {
-    constructor(message, options) {
-        super(message, options);
-        this.name = "TurnSummaryRefreshError";
-    }
-}
-async function fetchSummary(config, directory, fetcher, signal) {
-    const url = new URL("/api/traces/friction-summary", config.endpoint);
-    url.searchParams.set("directory", directory);
-    let response;
-    try {
-        response = await fetcher(url, {
-            headers: { authorization: `Bearer ${config.token}` },
-            signal: signal
-                ? AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)])
-                : AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        });
-    }
-    catch (error) {
-        if (signal?.aborted)
-            throw error;
-        throw new TurnSummaryRefreshError("Friction summary could not reach Iteration.", { cause: error });
-    }
-    if (response.status !== 200) {
-        throw new TurnSummaryRefreshError(`Friction summary failed with HTTP ${response.status}.`);
-    }
-    let body;
-    try {
-        body = await response.json();
-    }
-    catch (error) {
-        throw new TurnSummaryRefreshError("Friction summary returned an unreadable response.", { cause: error });
-    }
-    const parsed = parseCollectorFrictionSummary(body);
-    if (!parsed.success)
-        throw new TurnSummaryRefreshError(parsed.error);
-    return parsed.value;
-}
-async function readRequest(filename) {
-    try {
-        const [directory] = (await fs.readFile(filename, "utf8")).split("\n");
-        return directory ?? null;
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return null;
-        throw error;
-    }
-}
-async function writeLine(paths, key, directory, message) {
-    const filename = path.join(paths.lines, key);
-    if (message === null) {
-        await fs.rm(filename, { force: true });
-        return;
-    }
-    const temporary = `${filename}.${process.pid}.tmp`;
-    await fs.writeFile(temporary, `${directory}\n${JSON.stringify({ systemMessage: message })}\n`, { encoding: "utf8", mode: 0o600 });
-    await fs.rename(temporary, filename);
-}
-async function forget(paths, key) {
-    await Promise.all([paths.requests, paths.lines, paths.shown].map((directory) => fs.rm(path.join(directory, key), { force: true })));
-}
-// Refreshes the summary line for each repository the hook asked about. The
-// hook reads the result on a later turn, so a slow or failed request never
-// delays the agent.
-export async function refreshTurnSummaries(config, refreshedAt, nowMs, fetcher = collectorFetch, signal) {
-    const paths = turnSummaryPaths(config.dataDirectory);
-    let keys;
-    try {
-        keys = await fs.readdir(paths.requests);
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return 0;
-        throw error;
-    }
-    let refreshed = 0;
-    for (const key of keys.sort()) {
-        signal?.throwIfAborted();
-        if (!REQUEST_KEY_PATTERN.test(key))
-            continue;
-        const filename = path.join(paths.requests, key);
-        const stats = await fs.stat(filename).catch((error) => {
-            if (error instanceof Error && "code" in error && error.code === "ENOENT")
-                return null;
-            throw error;
-        });
-        if (stats === null)
-            continue;
-        const directory = await readRequest(filename);
-        if (nowMs - stats.mtimeMs > REQUEST_RETENTION_MS ||
-            directory === null ||
-            !isLaunchDirectory(directory)) {
-            await forget(paths, key);
-            refreshedAt.delete(key);
-            continue;
-        }
-        const previous = refreshedAt.get(key);
-        if (previous !== undefined &&
-            previous.directory === directory &&
-            nowMs - previous.atMs < REFRESH_INTERVAL_MS) {
-            continue;
-        }
-        if (refreshed === MAX_REFRESHES_PER_PASS)
-            break;
-        refreshedAt.set(key, { directory, atMs: nowMs });
-        refreshed += 1;
-        const summary = await fetchSummary(config, directory, fetcher, signal);
-        await writeLine(paths, key, directory, turnSummaryMessage(summary));
-    }
-    return refreshed;
-}
-function tomlBasicString(value) {
-    return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
-}
-// Codex runs a hook only after the developer trusts it in /hooks, and records
-// that trust as a hash of the normalized hook. Recomputing the same hash tells
-// whether Codex will run this exact entry; any other result keeps the reminder.
-function codexHookHash(command) {
-    const identity = {
-        event_name: "stop",
-        hooks: [
-            {
-                async: false,
-                command,
-                timeout: HOOK_TIMEOUT_SECONDS,
-                type: "command",
-            },
-        ],
-    };
-    return `sha256:${createHash("sha256").update(JSON.stringify(identity)).digest("hex")}`;
-}
-function codexTrustedHash(configToml, key) {
-    const lines = configToml.split(/\r?\n/);
-    const header = `[hooks.state.${tomlBasicString(key)}]`;
-    const start = lines.findIndex((line) => line.trim() === header);
-    if (start < 0)
-        return null;
-    let trustedHash = null;
-    for (const line of lines.slice(start + 1)) {
-        const trimmed = line.trim();
-        if (trimmed.startsWith("["))
-            break;
-        if (/^enabled\s*=\s*false\b/.test(trimmed))
-            return null;
-        const match = /^trusted_hash\s*=\s*"(sha256:[0-9a-f]{64})"/.exec(trimmed);
-        if (match?.[1] !== undefined)
-            trustedHash = match[1];
-    }
-    return trustedHash;
-}
-export async function codexTurnSummaryApproval(config) {
-    if ("claudeHome" in config || "cursorHome" in config)
-        return "approved";
-    const filename = agentHookFile(config);
-    const { file } = await readHookFile(filename);
-    const command = hookCommand(turnSummaryPaths(config.dataDirectory));
-    const stop = file.hooks?.Stop ?? [];
-    for (const [groupIndex, group] of stop.entries()) {
-        const handlerIndex = group.hooks?.findIndex((hook) => hook.command === command) ?? -1;
-        if (handlerIndex < 0)
-            continue;
-        let configToml;
-        try {
-            configToml = await fs.readFile(path.join(config.codexHome, "config.toml"), "utf8");
-        }
-        catch (error) {
-            if (error instanceof Error && "code" in error && error.code === "ENOENT")
-                return "needs_approval";
-            throw new Error("Could not read the Codex config.", { cause: error });
-        }
-        const trusted = codexTrustedHash(configToml, `${filename}:stop:${groupIndex}:${handlerIndex}`);
-        return trusted === codexHookHash(command) ? "approved" : "needs_approval";
-    }
-    return "not_installed";
-}