@cairn-tool/cairn 2.0.0

package/dist/update-notifier.js

@@ -0,0 +1,301 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+/** How long a cached result stays fresh. */
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** argv token that runs the detached cache refresh. Hidden from help. */
+export const REFRESH_COMMAND = "__refresh-update-cache";
+/** User-facing command that checks explicitly; suppresses the passive notice. */
+export const CHECK_COMMAND = "check-update";
+/**
+ * Contract-discovery commands. Their stdout is unconditionally a machine
+ * document, so a notice is never useful alongside them.
+ */
+export const DESCRIBE_COMMAND = "describe";
+export const SCHEMA_COMMAND = "schema";
+export const COMPLETION_COMMAND = "completion";
+/**
+ * `scripts run` hands its stderr to a child process, so a notice appended at exit
+ * would land inside whatever the calling hook captured.
+ */
+export const SCRIPTS_COMMAND = "scripts";
+export const SCRIPTS_RUN_SUBCOMMAND = "run";
+/**
+ * The machine-stream guarantees, published through `describe` so consumers can
+ * read them rather than infer them. Exported from here, next to the gate that
+ * enforces them, so the two cannot drift.
+ */
+export const NOTIFIER_CONTRACT = {
+    description: "The update notice is advisory only and never appears on a machine-readable stream.",
+    stream: "stderr",
+    suppressedWhen: [
+        "CAIRN_NO_UPDATE_NOTIFIER=1",
+        "CI is set",
+        "stderr is not a TTY",
+        "--format is json, jsonl, or sarif, including a project-configured format",
+        "the command is check-update, describe, schema, completion, scripts run, or the internal cache refresh",
+    ],
+    optOutEnv: "CAIRN_NO_UPDATE_NOTIFIER",
+};
+/**
+ * How long a held refresh lock is trusted. Must exceed the child's own fetch
+ * timeout so a working refresh is never treated as abandoned.
+ */
+export const LOCK_STALE_MS = 60_000;
+export function getCachePath(env = process.env, homedir) {
+    const home = homedir ?? os.homedir();
+    const xdg = env.XDG_CACHE_HOME?.trim();
+    const base = xdg && xdg.length > 0 ? xdg : path.join(home, ".cache");
+    return path.join(base, "cairn", "update-check.json");
+}
+export function readCache(cachePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const { lastCheckedAt, latestVersion } = parsed;
+        if (typeof lastCheckedAt !== "number" || !Number.isFinite(lastCheckedAt))
+            return null;
+        return {
+            lastCheckedAt,
+            latestVersion: typeof latestVersion === "string" ? latestVersion : null,
+        };
+    }
+    catch {
+        // A missing or corrupt cache is not an error — treat it as "never checked".
+        return null;
+    }
+}
+export function writeCache(cachePath, cache) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, JSON.stringify(cache), "utf-8");
+        return true;
+    }
+    catch {
+        // The cache is an optimisation; never let it break a command.
+        return false;
+    }
+}
+export function getLockPath(cachePath) {
+    return path.join(path.dirname(cachePath), "update-check.lock");
+}
+function isLockStale(lockPath, now, staleMs) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+        const at = parsed.at;
+        // An unreadable lock cannot be reasoned about; assume it was abandoned.
+        if (typeof at !== "number" || !Number.isFinite(at))
+            return true;
+        const age = now - at;
+        return age < 0 || age >= staleMs;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Exclusively claims the right to spawn a refresh, so concurrent invocations
+ * cannot each start their own child process. Uses an atomic `wx` create rather
+ * than an exists-then-write check, which would race.
+ *
+ * Returns false when another refresh is already in flight.
+ */
+export function acquireRefreshLock(lockPath, now, staleMs = LOCK_STALE_MS) {
+    const payload = JSON.stringify({ pid: process.pid, at: now });
+    try {
+        fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+        fs.writeFileSync(lockPath, payload, { flag: "wx" });
+        return true;
+    }
+    catch {
+        // Either the lock is held or the directory is unwritable. Only take it over
+        // when it is demonstrably stale — a crashed child must not block forever.
+        if (!isLockStale(lockPath, now, staleMs))
+            return false;
+        try {
+            fs.rmSync(lockPath, { force: true });
+            fs.writeFileSync(lockPath, payload, { flag: "wx" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export function releaseRefreshLock(lockPath) {
+    try {
+        fs.rmSync(lockPath, { force: true });
+    }
+    catch {
+        // Best-effort; the stale timeout is the backstop.
+    }
+}
+export function isCacheStale(cache, now, intervalMs = CHECK_INTERVAL_MS) {
+    if (!cache)
+        return true;
+    const age = now - cache.lastCheckedAt;
+    // A negative age means the clock moved backwards; re-check rather than
+    // trusting a timestamp from the future and going quiet indefinitely.
+    return age < 0 || age >= intervalMs;
+}
+function parseVersion(value) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value.trim());
+    if (!m)
+        return null;
+    return {
+        core: [Number(m[1]), Number(m[2]), Number(m[3])],
+        prerelease: m[4] ?? null,
+    };
+}
+/**
+ * True when `candidate` is a strictly newer release than `current`.
+ *
+ * Deliberately conservative: unparseable input and prerelease-to-prerelease
+ * comparisons return false. A wrong `true` nags the user on every command, so
+ * staying quiet is the safer failure mode.
+ */
+export function isNewerVersion(candidate, current) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(current);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a.core[i] > b.core[i])
+            return true;
+        if (a.core[i] < b.core[i])
+            return false;
+    }
+    // Same core version: a final release supersedes a prerelease of it.
+    return a.prerelease === null && b.prerelease !== null;
+}
+/** Detects JSON output from already-normalised argv (cli.ts expands `-fj` first). */
+export function hasJsonOutput(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (/^--format=(?:json|jsonl|sarif)$/.test(arg))
+            return true;
+        if (arg === "--format" && ["json", "jsonl", "sarif"].includes(argv[i + 1] ?? ""))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether the notice may be shown at all. Also gates the background refresh, so
+ * non-interactive callers never spawn a child process either.
+ */
+export function isNotifierAllowed(ctx) {
+    // The pre-rename spelling stays honored: an opt-out already exported in a CI
+    // job or a shell profile must not start printing notices because the tool was
+    // renamed. Only the current name is published through `describe`.
+    if (ctx.env.CAIRN_NO_UPDATE_NOTIFIER === "1")
+        return false;
+    if (ctx.env.CLAUDE_CLI_NO_UPDATE_NOTIFIER === "1")
+        return false;
+    if (ctx.env.CI)
+        return false;
+    // Not a terminal means the output is being parsed by something. Both stdout
+    // and stderr carry machine-readable payloads depending on the command, so
+    // there is no safe stream to write to.
+    if (!ctx.isTty)
+        return false;
+    if (hasJsonOutput(ctx.argv))
+        return false;
+    // The refresh child must not recurse, and `check-update` reports the same
+    // thing itself — a passive notice alongside it would just be duplication.
+    if (ctx.argv.includes(REFRESH_COMMAND))
+        return false;
+    if (ctx.argv.includes(CHECK_COMMAND))
+        return false;
+    // Contract-discovery commands always emit a machine document, and agents that
+    // poll them should not keep spawning the background refresh.
+    if (ctx.argv.includes(DESCRIBE_COMMAND))
+        return false;
+    if (ctx.argv.includes(SCHEMA_COMMAND))
+        return false;
+    // `eval "$(cairn completion zsh)"` belongs in an interactive rc file,
+    // where stderr *is* a TTY. Without this the notice would print on every shell
+    // start and the background refresh would spawn on every shell start.
+    if (ctx.argv.includes(COMPLETION_COMMAND))
+        return false;
+    // `scripts run` gives its stderr to a child process, so anything written at
+    // exit lands inside the output a calling hook captured. Matched by adjacency
+    // rather than by `includes`, because `run` is also a legal script name.
+    const scriptsIndex = ctx.argv.indexOf(SCRIPTS_COMMAND);
+    if (scriptsIndex !== -1 && ctx.argv[scriptsIndex + 1] === SCRIPTS_RUN_SUBCOMMAND)
+        return false;
+    return true;
+}
+export function shouldNotify(ctx) {
+    if (!isNotifierAllowed(ctx))
+        return false;
+    const latest = ctx.cache?.latestVersion;
+    if (!latest)
+        return false;
+    return isNewerVersion(latest, ctx.currentVersion);
+}
+export function formatNotice(current, latest, packageName) {
+    const dim = "\x1b[2m";
+    const bold = "\x1b[1m";
+    const yellow = "\x1b[33m";
+    const reset = "\x1b[0m";
+    return [
+        "",
+        `${yellow}Update available${reset} ${dim}${current}${reset} → ${bold}${latest}${reset}`,
+        `${dim}Run${reset} npm install -g ${packageName} ${dim}to update.${reset}`,
+        "",
+    ].join("\n");
+}
+/**
+ * Prints an update notice from cache at process exit and kicks off a detached refresh when
+ * the cache is stale. Never delays or fails a command.
+ */
+export function installUpdateNotifier(opts) {
+    const env = opts.env ?? process.env;
+    const isTty = opts.isTty ?? process.stderr.isTTY === true;
+    const argv = opts.argv;
+    if (!isNotifierAllowed({ argv, isTty, env }))
+        return;
+    const cachePath = opts.cachePath ?? getCachePath(env);
+    const cache = readCache(cachePath);
+    const now = opts.now ?? Date.now();
+    if (shouldNotify({ currentVersion: opts.currentVersion, cache, argv, isTty, env })) {
+        const latest = cache?.latestVersion;
+        if (latest) {
+            // Deferred to exit so the notice lands after the command's own output.
+            process.on("exit", () => {
+                process.stderr.write(formatNotice(opts.currentVersion, latest, opts.packageName));
+            });
+        }
+    }
+    if (!isCacheStale(cache, now))
+        return;
+    // Claim the lock here, in the parent, rather than in the child. Letting every
+    // invocation spawn a child that then discovers it lost the race would defeat
+    // the point — the cost being avoided is the process spawn itself.
+    const lockPath = getLockPath(cachePath);
+    if (!acquireRefreshLock(lockPath, now))
+        return;
+    if (!spawnRefresh(opts.entryPoint, env)) {
+        // Nothing will ever release it otherwise.
+        releaseRefreshLock(lockPath);
+    }
+}
+function spawnRefresh(entryPoint, env) {
+    try {
+        const child = spawn(process.execPath, [entryPoint, REFRESH_COMMAND], {
+            detached: true,
+            stdio: "ignore",
+            env,
+        });
+        // Let the parent exit immediately regardless of the child.
+        child.unref();
+        return true;
+    }
+    catch {
+        // A failed spawn must never surface to the user.
+        return false;
+    }
+}
+//# sourceMappingURL=update-notifier.js.map

package/dist/update-notifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-notifier.js","sourceRoot":"","sources":["../src/update-notifier.ts"],"names":[],"mappings":"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"}

package/dist/url-cache.d.ts

@@ -0,0 +1,14 @@
+export interface RawUrlResult {
+    status: number | null;
+    error?: string;
+    redirected: boolean;
+    finalUrl: string;
+}
+export declare function getUrlCachePath(env?: NodeJS.ProcessEnv, homedir?: string): string;
+export declare function urlCacheKey(url: string, options: {
+    timeout: number;
+    retries: number;
+    headFallbackStatuses: readonly number[];
+}): string;
+export declare function readUrlCache(cachePath: string, key: string, ttl: number, now?: number): RawUrlResult | undefined;
+export declare function writeUrlCache(cachePath: string, key: string, result: RawUrlResult, now?: number): boolean;

package/dist/url-cache.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+export function getUrlCachePath(env = process.env, homedir = os.homedir()) {
+    const configured = env.XDG_CACHE_HOME?.trim();
+    const base = configured ? configured : path.join(homedir, ".cache");
+    return path.join(base, "cairn", "url-checks.json");
+}
+export function urlCacheKey(url, options) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        url,
+        timeout: options.timeout,
+        retries: options.retries,
+        headFallbackStatuses: [...options.headFallbackStatuses].sort((a, b) => a - b),
+    }))
+        .digest("hex");
+}
+function read(cachePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+        if (parsed.version !== 1 || !parsed.entries || typeof parsed.entries !== "object")
+            throw new Error();
+        return parsed;
+    }
+    catch {
+        return { version: 1, entries: {} };
+    }
+}
+export function readUrlCache(cachePath, key, ttl, now = Date.now()) {
+    const entry = read(cachePath).entries[key];
+    if (!entry ||
+        !Number.isFinite(entry.checkedAt) ||
+        !(entry.status === null ||
+            (Number.isInteger(entry.status) && entry.status >= 100 && entry.status <= 599)) ||
+        typeof entry.redirected !== "boolean" ||
+        typeof entry.finalUrl !== "string" ||
+        (entry.error !== undefined && typeof entry.error !== "string"))
+        return undefined;
+    const age = now - entry.checkedAt;
+    if (age < 0 || age >= ttl)
+        return undefined;
+    const { checkedAt: _checkedAt, ...result } = entry;
+    return result;
+}
+export function writeUrlCache(cachePath, key, result, now = Date.now()) {
+    let temporary;
+    try {
+        const cache = read(cachePath);
+        cache.entries[key] = { ...result, checkedAt: now };
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        temporary = `${cachePath}.${process.pid}.tmp`;
+        fs.writeFileSync(temporary, JSON.stringify(cache), "utf-8");
+        fs.renameSync(temporary, cachePath);
+        return true;
+    }
+    catch {
+        if (temporary) {
+            try {
+                fs.rmSync(temporary, { force: true });
+            }
+            catch {
+                // Cache cleanup is best-effort.
+            }
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=url-cache.js.map

package/dist/url-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-cache.js","sourceRoot":"","sources":["../src/url-cache.ts"],"names":[],"mappings":"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"}

package/dist/usage/aggregate.d.ts

@@ -0,0 +1,107 @@
+import type { DayBucket, FileAggregate, TokenTotals, ToolKind } from "./events.js";
+/**
+ * Rollups over scanned aggregates.
+ *
+ * Pure: every function here takes `FileAggregate[]` and returns rows. Nothing
+ * reads the filesystem, nothing knows which provider produced the input, and
+ * nothing formats anything — that is `src/commands/usage.ts`.
+ */
+export declare const TOKEN_DIMENSIONS: readonly ["model", "day", "week", "month", "project", "session", "provider"];
+export type TokenDimension = (typeof TOKEN_DIMENSIONS)[number];
+export declare const TOOL_DIMENSIONS: readonly ["name", "kind", "server", "day", "session", "provider"];
+export type ToolDimension = (typeof TOOL_DIMENSIONS)[number];
+export declare const SESSION_SORTS: readonly ["recent", "tokens", "tools", "duration"];
+/**
+ * How `usage agents` groups.
+ *
+ * `role` is the reusable agent type, which is what `agentType` means for every
+ * provider. `path` is the task-specific identifier, which only some record.
+ */
+export declare const AGENT_DIMENSIONS: readonly ["role", "path"];
+export type AgentDimension = (typeof AGENT_DIMENSIONS)[number];
+export type SessionSort = (typeof SESSION_SORTS)[number];
+/**
+ * One row of any rollup.
+ *
+ * A single row type across every subcommand is what lets them share the
+ * `usage-rollup` schema. Only `key` and `count` are always present; each
+ * dimension fills in the fields that mean something for it and leaves the rest
+ * off, so a consumer reads a row by the `dimension` the payload declares.
+ */
+export interface RollupRow {
+    key: string;
+    /** Which provider a row came from, where a row belongs to exactly one. */
+    provider?: string;
+    count: number;
+    tokens?: TokenTotals;
+    sessions?: number;
+    toolCalls?: number;
+    prompts?: number;
+    /** Tools. */
+    kind?: ToolKind;
+    server?: string;
+    /** Hooks. */
+    failures?: number;
+    cancelled?: number;
+    meanMs?: number;
+    maxMs?: number;
+    /** Subagents. */
+    maxDepth?: number;
+    /** Sessions. */
+    project?: string;
+    title?: string;
+    gitBranch?: string;
+    firstTs?: string;
+    lastTs?: string;
+    durationMs?: number;
+    subagents?: number;
+    models?: string[];
+}
+/** The Monday that starts the ISO week a UTC day falls in. */
+export declare function weekOf(day: string): string;
+export declare function totalsOf(files: readonly FileAggregate[]): TokenTotals;
+/** Every day bucket in the selection, merged. */
+export declare function mergedBucket(files: readonly FileAggregate[]): DayBucket;
+export interface UsageSummary {
+    sessions: number;
+    transcripts: number;
+    subagentTranscripts: number;
+    projects: number;
+    prompts: number;
+    errors: number;
+    compactions: number;
+    firstDay: string | null;
+    lastDay: string | null;
+    days: number;
+    tokens: TokenTotals;
+    tokensByKind: {
+        main: TokenTotals;
+        subagent: TokenTotals;
+    };
+    models: RollupRow[];
+    tools: RollupRow[];
+    features: {
+        skills: number;
+        subagents: number;
+        hooks: number;
+        hookFailures: number;
+        slashCommands: number;
+        mcpCalls: number;
+    };
+}
+export declare function summarize(files: readonly FileAggregate[]): UsageSummary;
+export declare function rollupTokens(files: readonly FileAggregate[], dimension: TokenDimension): RollupRow[];
+export declare function rollupTools(files: readonly FileAggregate[], dimension: ToolDimension, kind?: ToolKind): RollupRow[];
+export declare function rollupSessions(files: readonly FileAggregate[], sort?: SessionSort): RollupRow[];
+export declare function rollupProjects(files: readonly FileAggregate[]): RollupRow[];
+export declare function rollupSkills(files: readonly FileAggregate[]): RollupRow[];
+/**
+ * Subagent activity.
+ *
+ * Spawn counts come from the parent's `Agent` tool calls; tokens come from the
+ * subagent transcripts themselves, because the parent's `toolUseResult` records
+ * only the subagent's final message and understates real spend several-fold.
+ */
+export declare function rollupAgents(files: readonly FileAggregate[], dimension?: AgentDimension): RollupRow[];
+export declare function rollupHooks(files: readonly FileAggregate[]): RollupRow[];
+export declare function rollupCommands(files: readonly FileAggregate[]): RollupRow[];