freeharness 0.4.1 → 0.4.3

package/dist/cli/cleanup.js

@@ -2,30 +2,48 @@
 // discovered by heuristics. User scope: parked upstream claude-mem + data backups, upstream
 // claude-mem hooks in settings.json (once the plugin is registered), legacy /openspec commands,
 // the global @fission-ai/openspec package, a global npm `freeharness` link, retired names
-// (RETIRED) still on disk after a rename or a fold when the manifest records them. Project
+// (RETIRED in install-facts.ts) still on disk after a rename or a fold when the manifest records them,
+// retired hook scripts and the settings entries that run them. Project
 // scope: legacy /openspec commands, project copies of canonical agents/skills, duplicate
 // FreeHarness hook entries. Never listed: the schema override, non-canonical skills/agents,
 // `openspec-*` skills, `.claude/commands/opsx/` (the user's or ours).
 //
 // Two-pass: `planCleanup` computes the list untouched; `applyCleanup` removes the confirmed items.
+// Items under the Claude Code plugin cache are never deleted: they move into the dated archive
+// through the hard-cleanup mover.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { PLUGIN_KEY, PLUGIN_NAME, UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_KEY, UPSTREAM_PLUGIN_NAME } from "../adapters/memory/vendored.js";
+import { PLUGIN_KEY, UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_KEY, UPSTREAM_PLUGIN_NAME } from "../adapters/memory/vendored.js";
 import { manifestPath, readManifest } from "../infra/manifest.js";
-import { configDir, dataDir, diagnoseMemory } from "../adapters/memory/doctor.js";
-import { canonicalNames, memoryPluginInstalled } from "./doctor.js";
+import { configDir, diagnoseMemory, foreignWorkerStep } from "../adapters/memory/doctor.js";
+import { FREE_DIR_NAME, resolveMemoryPaths } from "../adapters/memory/paths.js";
+import { canonicalNames, memoryPluginInstalled, RETIRED, retiredFindings, runsRetiredHook } from "./install-facts.js";
 import { isClaudeMemHook, isOurHook, pruneHooksMatching } from "./uninstall.js";
+import { archiveMove, archiveRootFor, isOrHolds, moveWarning, pluginCacheArchive, pluginCacheOverlap, pluginCacheRefusal } from "./hard-cleanup.js";
+import { removeJsonKey } from "./json-key-edit.js";
+import { configCopyArchive, launcherStillMatches, launcherText, marketplaceRefusal, planUpstreamLaunchers } from "./upstream-launchers.js";
 /** The vendored `openspec` bin replaces it. */
 export const LEGACY_OPENSPEC_PACKAGE = "@fission-ai/openspec";
 /** A global link of it shadows the ~/.local/bin symlink. */
 export const CLI_PACKAGE = "freeharness";
-/** Retired by a rename or a fold, bare names under `~/.claude`. */
-export const RETIRED = {
-    skills: ["local-code-intel"],
-    agents: ["mle-reviewer", "mle-evaluator"],
-};
+/** An entry mixing a retired script with another command is not one we emitted, so it stays. */
+function isRetiredHook(e) {
+    const commands = (e.hooks ?? []).map((h) => h.command ?? "");
+    return commands.length > 0 && commands.every(runsRetiredHook);
+}
+function hookPredicate(owner) {
+    if (owner === UPSTREAM_PLUGIN_NAME)
+        return isClaudeMemHook;
+    return owner === "retired" ? isRetiredHook : isOurHook;
+}
+/** Upstream IDE rule files under the home dir, relative; fixed list. */
+const IDE_RULE_FILES = [
+    path.join(".agent", "rules", `${UPSTREAM_PLUGIN_NAME}-context.md`),
+    path.join(".agents", "rules", `${UPSTREAM_PLUGIN_NAME}-context.md`),
+    path.join(".agent", "rules", "free-mem-context.md"),
+];
 /** Sums the size (bytes) of every file under a directory. */
 export function dirBytes(dir) {
     let total = 0;
@@ -93,18 +111,26 @@ export function globalNpmFreeharnessBin() {
     }
     return bin;
 }
-/** Claude-mem data backups written by `freeharness memory backup` (`<dataDir>-backup-<stamp>`), oldest first. */
-export function memoryBackupDirs() {
-    const data = dataDir();
-    const parent = path.dirname(data);
-    const prefix = `${path.basename(data)}-backup-`;
-    if (!fs.existsSync(parent))
-        return [];
-    return fs
-        .readdirSync(parent, { withFileTypes: true })
-        .filter((e) => e.isDirectory() && e.name.startsWith(prefix))
-        .map((e) => path.join(parent, e.name))
-        .sort();
+/**
+ * Memory data backups written by `freeharness memory backup` (`<dataDir>-backup-<stamp>`), sorted.
+ * Backups of the default directory count even while a redirected directory is in use.
+ */
+export function memoryBackupDirs(env = process.env, home = os.homedir()) {
+    const live = resolveMemoryPaths(env, home).dataDir;
+    const dirs = [live, path.join(home, FREE_DIR_NAME)];
+    const found = new Set();
+    for (const data of dirs) {
+        const parent = path.dirname(data);
+        const prefix = `${path.basename(data)}-backup-`;
+        if (!fs.existsSync(parent))
+            continue;
+        for (const e of fs.readdirSync(parent, { withFileTypes: true })) {
+            const candidate = path.join(parent, e.name);
+            if (e.isDirectory() && e.name.startsWith(prefix) && !isOrHolds(candidate, live))
+                found.add(candidate);
+        }
+    }
+    return [...found].sort();
 }
 /** Plugin keys registered in Claude Code's installed_plugins.json (e.g. "name@marketplace"); empty when absent or unreadable. */
 function installedPluginKeys(cfg) {
@@ -128,29 +154,28 @@ export function pruneManifest(scope, projectRoot) {
         fs.writeFileSync(file, JSON.stringify({ ...m, files: kept, updatedAt: new Date().toISOString() }, null, 2) + "\n");
     return dropped;
 }
-/** Retired skill/agent names still present under a `.claude` dir: `update`'s additive merge never deletes them; an absent path is skipped. */
-export function retiredFindings(claudeDir, manifest) {
-    const groups = [
-        { kind: "skill", dir: "skills", names: RETIRED.skills },
-        { kind: "agent", dir: "agents", names: RETIRED.agents },
-    ];
-    const found = [];
-    for (const { kind, dir, names } of groups) {
-        for (const name of names) {
-            const fileName = kind === "agent" ? `${name}.md` : name;
-            const p = path.join(claudeDir, dir, fileName);
-            if (!fs.existsSync(p))
-                continue;
-            const under = `${p}${path.sep}`;
-            const recorded = manifest?.files.some((f) => f.path === p || f.path.startsWith(under)) ?? false;
-            found.push({ kind, name, path: p, recorded });
-        }
-    }
-    return found;
+/** Routes a plugin-cache item into the dated archive; an earlier refusal wins over the containment one. */
+function toArchive(item, cfg, archiveRoot) {
+    const archive = pluginCacheArchive(item.target, cfg, archiveRoot);
+    return { ...item, archiveDest: archive.destination, refused: item.refused ?? archive.refused };
+}
+const UPSTREAM_ENABLED_REFUSAL = `the ${UPSTREAM_PLUGIN_KEY} key is still enabled — disable it first: \`claude plugin disable ${UPSTREAM_PLUGIN_KEY}\``;
+/**
+ * Refusal while the build is not the sole active plugin. `memory activate` cannot clear a foreign
+ * worker beside our build, so that case names the doctor FAIL line's steps, as the mixed VERDICT does.
+ */
+function notOursRefusal(d) {
+    const verdictLine = d.lines.find((l) => l.includes("VERDICT")) ?? `verdict ${d.verdict}`;
+    const head = `the FreeHarness build is not the only active memory plugin yet (${verdictLine.replace(/^(OK|WARN)\s+/, "")})`;
+    const step = d.verdict === "mixed" ? foreignWorkerStep(d.worker) : null;
+    if (step === null)
+        return `${head}; run \`freeharness memory activate\` first`;
+    return `${head}; stop the foreign worker first (${step})`;
 }
 /** Computes the user-scope cleanup list; nothing is touched. */
 async function planUser(deps) {
-    const plan = { scope: "user", items: [], notes: [] };
+    const archiveRoot = deps.archiveRoot ?? archiveRootFor(os.homedir(), new Date());
+    const plan = { scope: "user", items: [], notes: [], archiveRoot };
     const cfg = configDir();
     // `memory activate` parks foreign versions under the upstream root (doctor.ts's
     // disabledRoot): an upstream install or a pre-rename FreeHarness build, never ours.
@@ -158,11 +183,9 @@ async function planUser(deps) {
     if (fs.existsSync(disabled)) {
         const d = deps.memory ?? (await diagnoseMemory());
         const item = { kind: "dir", target: disabled, reason: "upstream claude-mem parked by `memory activate`", group: "memory", bytes: dirBytes(disabled) };
-        if (d.verdict !== "ours") {
-            const verdictLine = d.lines.find((l) => l.includes("VERDICT")) ?? `verdict ${d.verdict}`;
-            item.refused = `the FreeHarness build is not the only active memory plugin yet (${verdictLine.replace(/^(OK|WARN)\s+/, "")}); run \`freeharness memory activate\` first`;
-        }
-        plan.items.push(item);
+        if (d.verdict !== "ours")
+            item.refused = notOursRefusal(d);
+        plan.items.push(toArchive(item, cfg, archiveRoot));
     }
     // Superseded FreeHarness builds: our own cache versions (.install-version present) that are
     // not the registered installPath, left behind by a version bump. A legacy-root build that
@@ -171,7 +194,7 @@ async function planUser(deps) {
         const d = deps.memory ?? (await diagnoseMemory());
         if (d.activeInstallPath) {
             for (const c of d.cache.filter((c) => c.ours && !c.legacy && path.resolve(c.dir) !== path.resolve(d.activeInstallPath))) {
-                plan.items.push({ kind: "dir", target: c.dir, reason: `superseded FreeHarness memory build ${c.version} (registered: ${d.activeVersion ?? "?"})`, group: "memory", bytes: dirBytes(c.dir) });
+                plan.items.push(toArchive({ kind: "dir", target: c.dir, reason: `superseded FreeHarness memory build ${c.version} (registered: ${d.activeVersion ?? "?"})`, group: "memory", bytes: dirBytes(c.dir) }, cfg, archiveRoot));
             }
         }
     }
@@ -184,7 +207,21 @@ async function planUser(deps) {
     if (fs.existsSync(userSettings) && memoryPluginInstalled(cfg) && pruneHooksMatching(userSettings, isClaudeMemHook, true) > 0) {
         plan.items.push({ kind: "hooks", target: userSettings, reason: `upstream claude-mem hook entries (the ${PLUGIN_KEY} plugin ships its own hooks.json; these run every hook twice)`, group: "memory", hookOwner: UPSTREAM_PLUGIN_NAME });
     }
-    // Leftovers of a `registerHooks` migration: the pre-rename cache dir (gated on its own
+    // Rule stubs the upstream Gemini/Antigravity installer wrote into IDE rule dirs; no engine
+    // updates them. Fixed list, no glob; a directory at the path is not ours to move.
+    for (const rel of IDE_RULE_FILES) {
+        const file = path.join(os.homedir(), rel);
+        try {
+            const st = fs.lstatSync(file);
+            if (!st.isFile() && !st.isSymbolicLink())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        plan.items.push({ kind: "file", target: file, reason: "upstream IDE rule file (no engine updates it)", group: "memory", ideRule: true, archiveDest: path.join(archiveRoot, "ide-rules", rel) });
+    }
+    // Leftovers of the old key: the pre-rename cache dir (gated on its own
     // existence, not the key's) and the disabled key (listed only while present). Both stay
     // refused while the old key is enabled, or (same VERDICT check as above) while the build is
     // not verified as sole active plugin — installed_plugins.json alone can register the
@@ -202,18 +239,22 @@ async function planUser(deps) {
         }
         let refused;
         if (oldKeyValue === true) {
-            refused = `the ${UPSTREAM_PLUGIN_KEY} key is still enabled — migrate first: \`freeharness init --scope user --only memory\``;
+            refused = UPSTREAM_ENABLED_REFUSAL;
         }
         else if (d.verdict !== "ours") {
-            const verdictLine = d.lines.find((l) => l.includes("VERDICT")) ?? `verdict ${d.verdict}`;
-            refused = `the FreeHarness build is not the only active memory plugin yet (${verdictLine.replace(/^(OK|WARN)\s+/, "")}); run \`freeharness memory activate\` first`;
+            refused = notOursRefusal(d);
         }
         if (fs.existsSync(oldCacheDir)) {
-            plan.items.push({ kind: "dir", target: oldCacheDir, reason: `previous registration, migrated to ${PLUGIN_NAME}`, group: "memory", bytes: dirBytes(oldCacheDir), refused });
+            plan.items.push(toArchive({ kind: "dir", target: oldCacheDir, reason: "previous registration, left in the plugin cache", group: "memory", bytes: dirBytes(oldCacheDir), refused }, cfg, archiveRoot));
         }
         if (oldKeyValue !== undefined) {
-            plan.items.push({ kind: "settings-key", target: userSettings, reason: `disabled ${UPSTREAM_PLUGIN_KEY} key left in enabledPlugins after migrating to ${PLUGIN_KEY}`, group: "memory", settingsKey: UPSTREAM_PLUGIN_KEY, refused });
+            const copy = configCopyArchive(userSettings, os.homedir(), archiveRoot);
+            plan.items.push({ kind: "json-key", target: userSettings, reason: `disabled ${UPSTREAM_PLUGIN_KEY} key left in enabledPlugins`, group: "memory", keyPath: ["enabledPlugins", UPSTREAM_PLUGIN_KEY], archiveDest: copy.destination, refused: refused ?? copy.refused });
         }
+        // An enabled upstream plugin still installs from its marketplace; other clients' launchers are not that plugin.
+        const launchers = planUpstreamLaunchers({ home: os.homedir(), cfg, archiveRoot, marketplaceRefusal: oldKeyValue === true ? UPSTREAM_ENABLED_REFUSAL : undefined });
+        plan.items.push(...launchers.items);
+        plan.notes.push(...launchers.notes);
     }
     const legacy = path.join(cfg, "commands", "openspec");
     if (fs.existsSync(legacy)) {
@@ -250,20 +291,30 @@ async function planUser(deps) {
             plan.items.push({ kind: "npm-global", target: CLI_PACKAGE, reason: `npm -g ${CLI_PACKAGE} (old npm link; shadows ~/.local/bin)${linkedBin ? ` at ${linkedBin}` : ""}`, group: "npm", unlink: true });
         }
     }
-    // Retired names: listed only when the manifest records the path, so a same-named
-    // user-owned skill/agent stays untouched (doctor reports that case as INFO, never here).
+    // Retired names: a skill, agent or file is listed only when the manifest records the path,
+    // so a same-named user-owned one stays untouched (doctor reports that case as INFO, never here).
+    // A hook script lives in FreeHarness's own hooks dir, so its presence is enough.
     const manifest = readManifest(manifestPath("user", ""));
+    const retiredReason = {
+        hook: (name) => `retired hook ${name} (removed from FreeHarness; update never deletes the installed copy)`,
+        file: () => "retired rules file (FreeHarness no longer emits it; update never deletes the installed copy)",
+        skill: () => "retired skill (renamed or folded elsewhere; kept on disk by update's additive manifest merge)",
+        agent: () => "retired agent (renamed or folded elsewhere; kept on disk by update's additive manifest merge)",
+    };
     for (const f of retiredFindings(path.join(os.homedir(), ".claude"), manifest)) {
-        if (!f.recorded)
+        if (!f.recorded && f.kind !== "hook")
             continue;
         plan.items.push({
             kind: f.kind === "skill" ? "dir" : "file",
             target: f.path,
-            reason: `retired ${f.kind} (renamed or folded elsewhere; kept on disk by update's additive manifest merge)`,
+            reason: retiredReason[f.kind](f.name),
             group: "retired",
             bytes: f.kind === "skill" ? dirBytes(f.path) : undefined,
         });
     }
+    if (fs.existsSync(userSettings) && pruneHooksMatching(userSettings, isRetiredHook, true) > 0) {
+        plan.items.push({ kind: "hooks", target: userSettings, reason: `settings hook entries running a retired hook script (${RETIRED.hooks.join(", ")})`, group: "retired", hookOwner: "retired" });
+    }
     plan.notes.push(`kept: ${path.join(os.homedir(), ".local", "share", "openspec", "schemas", "spec-driven")} (the FreeHarness schema override)`);
     return plan;
 }
@@ -311,7 +362,7 @@ function planProject(projectRoot, deps) {
     }
     const oldSafety = path.join(fhDir, "safety.md");
     if (fs.existsSync(oldSafety))
-        plan.items.push({ kind: "file", target: oldSafety, reason: "old project-scope safety.md (global since v0.3.0)", group: "duplicates" });
+        plan.items.push({ kind: "file", target: oldSafety, reason: "old project-scope safety.md (FreeHarness emits no safety.md)", group: "duplicates" });
     plan.notes.push(`kept: ${path.join(claude, "commands", "opsx")} and ${path.join(claude, "skills", "openspec-*")} (ours)`);
     return plan;
 }
@@ -319,9 +370,61 @@ function planProject(projectRoot, deps) {
 export async function planCleanup(scope, projectRoot, deps = {}) {
     return scope === "user" ? planUser(deps) : planProject(projectRoot, deps);
 }
+function inInbox(dest, inbox) {
+    const rel = path.relative(inbox, dest);
+    return !(rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel));
+}
+/**
+ * The destination stays in the `ide-rules` inbox so no plan item lands over other archive content;
+ * a source that became a directory since pass 1 is no longer the stub it listed, and moving it would take what the user put there.
+ */
+function ideRuleRefusal(source, dest, archiveRoot) {
+    if (archiveRoot === undefined)
+        return "no archive root in the plan";
+    const inbox = path.join(archiveRoot, "ide-rules");
+    if (!inInbox(dest, inbox))
+        return `destination ${dest} is outside ${inbox}`;
+    try {
+        if (fs.lstatSync(source).isDirectory())
+            return "is a directory now";
+    }
+    catch {
+        // gone: the move reports it
+    }
+    return undefined;
+}
+/** A pre-edit copy outside the `configs` inbox could land over other archive content, so pass 2 refuses it. */
+function jsonKeyRefusal(item, archiveRoot) {
+    if (archiveRoot === undefined)
+        return "no archive root in the plan";
+    if (!item.keyPath?.length || item.archiveDest === undefined)
+        return "no key path or copy destination in the plan";
+    const inbox = path.join(archiveRoot, "configs");
+    return inInbox(item.archiveDest, inbox) ? undefined : `destination ${item.archiveDest} is outside ${inbox}`;
+}
+/** Moving rather than deleting keeps a wrong match recoverable; each kind has its own pass-2 check, as what makes its move unsafe differs. */
+function archiveItem(item, dest, cfg, archiveRoot, out) {
+    const refused = item.ideRule
+        ? ideRuleRefusal(item.target, dest, archiveRoot)
+        : item.launcher === "marketplace"
+            ? marketplaceRefusal(item.target, dest, archiveRoot)
+            : pluginCacheRefusal(item.target, dest, cfg, archiveRoot);
+    if (refused) {
+        out.skipped.push(item.target);
+        out.warnings.push(`${item.target}: refused (${refused})`);
+        return;
+    }
+    try {
+        out.moved.push(`${item.target} -> ${archiveMove(item.target, dest)}`);
+    }
+    catch (e) {
+        out.warnings.push(moveWarning(item.target, e));
+    }
+}
 /** Removes the confirmed items of a plan (`confirmed` defaults to all); refused items are always skipped. */
 export function applyCleanup(plan, confirmed = () => true) {
-    const out = { removed: [], skipped: [], warnings: [] };
+    const out = { removed: [], moved: [], skipped: [], warnings: [] };
+    const cfg = configDir();
     for (const item of plan.items) {
         if (item.refused || !confirmed(item)) {
             out.skipped.push(item.target);
@@ -329,14 +432,26 @@ export function applyCleanup(plan, confirmed = () => true) {
         }
         switch (item.kind) {
             case "dir":
-            case "file":
+            case "file": {
+                if (item.archiveDest !== undefined) {
+                    archiveItem(item, item.archiveDest, cfg, plan.archiveRoot, out);
+                    break;
+                }
+                // Nothing in, at or above the plugin cache is ever deleted; a link to it is unlinked only.
+                const cached = pluginCacheOverlap(item.target, cfg);
+                if (cached) {
+                    out.skipped.push(item.target);
+                    out.warnings.push(`${item.target}: refused (${cached})`);
+                    break;
+                }
                 fs.rmSync(item.target, { recursive: true, force: true });
                 out.removed.push(item.target);
                 break;
+            }
             case "hooks": {
-                const claudeMem = item.hookOwner === UPSTREAM_PLUGIN_NAME;
-                pruneHooksMatching(item.target, claudeMem ? isClaudeMemHook : isOurHook, false);
-                out.removed.push(`${item.target} (${claudeMem ? UPSTREAM_PLUGIN_NAME : "FreeHarness"} hook entries)`);
+                pruneHooksMatching(item.target, hookPredicate(item.hookOwner), false);
+                const whose = item.hookOwner === UPSTREAM_PLUGIN_NAME ? `upstream ${UPSTREAM_PLUGIN_NAME}` : item.hookOwner === "retired" ? "retired FreeHarness" : "FreeHarness";
+                out.removed.push(`${item.target} (${whose} hook entries)`);
                 break;
             }
             case "npm-global": {
@@ -358,12 +473,16 @@ export function applyCleanup(plan, confirmed = () => true) {
                     out.warnings.push(`npm ${verb} -g ${item.target} failed (exit ${r.status ?? "?"}): ${(r.stderr || r.stdout || "").trim().split("\n")[0]}`);
                 break;
             }
-            case "settings-key": {
-                const settings = JSON.parse(fs.readFileSync(item.target, "utf8"));
-                if (item.settingsKey && settings.enabledPlugins)
-                    delete settings.enabledPlugins[item.settingsKey];
-                fs.writeFileSync(item.target, JSON.stringify(settings, null, 2) + "\n", "utf8");
-                out.removed.push(`${item.target} (removed ${item.settingsKey} from enabledPlugins)`);
+            case "json-key": {
+                const refused = jsonKeyRefusal(item, plan.archiveRoot);
+                const r = refused ? { ok: false, reason: refused } : removeJsonKey(item.target, item.keyPath ?? [], item.archiveDest ?? "", { stillMatches: launcherStillMatches(item) });
+                if (r.ok) {
+                    out.removed.push(`${item.target} (removed ${keyLabel(item)}; copy at ${r.copy})`);
+                }
+                else {
+                    out.skipped.push(item.target);
+                    out.warnings.push(`${item.target}: refused (${r.reason})`);
+                }
                 break;
             }
         }
@@ -373,10 +492,20 @@ export function applyCleanup(plan, confirmed = () => true) {
 /** Renders a plan item for the preview / doctor output, one line, without the OK/WARN prefix. */
 export function describeItem(item) {
     const size = item.bytes !== undefined ? ` (${humanBytes(item.bytes)})` : "";
-    const what = item.kind === "npm-global"
-        ? `npm ${item.unlink ? "unlink" : "uninstall"} -g ${item.target}`
-        : item.kind === "hooks" || item.kind === "settings-key"
-            ? `edit: ${item.target}`
-            : `rm: ${item.target}`;
-    return `${what}${size} — ${item.reason}${item.refused ? ` — REFUSED: ${item.refused}` : ""}`;
+    return `${itemAction(item)}${size} — ${item.reason}${item.refused ? ` — REFUSED: ${item.refused}` : ""}`;
+}
+/** Doctor prints these lines unescaped, and a launcher's key is a server name another program wrote. */
+function keyLabel(item) {
+    return item.keyPath?.map(launcherText).join(".") ?? "?";
+}
+function itemAction(item) {
+    if (item.kind === "npm-global")
+        return `npm ${item.unlink ? "unlink" : "uninstall"} -g ${item.target}`;
+    if (item.kind === "json-key")
+        return `edit: ${item.target} (remove ${keyLabel(item)}; original to ${item.archiveDest ?? "?"})`;
+    if (item.kind === "hooks")
+        return `edit: ${item.target}`;
+    if (item.archiveDest !== undefined)
+        return `mv: ${item.target} -> ${item.archiveDest}`;
+    return `rm: ${item.target}`;
 }

package/dist/cli/cost-quota.d.ts

@@ -0,0 +1,158 @@
+import type { ModelFamily, TokenGroup } from "./cost.js";
+export declare const QUOTA_WINDOWS: readonly ["five_hour", "seven_day"];
+export type QuotaWindow = (typeof QUOTA_WINDOWS)[number];
+export declare const DEFAULT_QUOTA_DAYS = 14;
+export interface WindowReading {
+    used_percentage: number;
+    resets_at: number;
+}
+/** One validated readings line; `ts` re-rendered from its parsed time so untrusted text never prints. */
+export interface QuotaReading {
+    ts: string;
+    time: number;
+    model: string | null;
+    five_hour: WindowReading | null;
+    seven_day: WindowReading | null;
+}
+/** The fit's input row: a percentage rise and the tokens per family recorded while it rose. */
+export interface QuotaInterval {
+    delta: number;
+    tokens: Partial<Record<ModelFamily, TokenGroup>>;
+}
+/** A rising interval as reported, traceable to its two readings. */
+export interface ReportedInterval extends QuotaInterval {
+    window: QuotaWindow;
+    resets_at: number;
+    start: {
+        ts: string;
+        model: string | null;
+        used_percentage: number;
+    };
+    end: {
+        ts: string;
+        model: string | null;
+        used_percentage: number;
+    };
+    tokens_per_pct: Partial<Record<ModelFamily, TokenGroup>>;
+}
+export type FamilyWeights = Partial<Record<ModelFamily, TokenGroup>>;
+export type FitResult = {
+    weights: FamilyWeights;
+    residual: number;
+    intervals: number;
+} | {
+    needed: number;
+    features: number;
+};
+export interface WindowReport {
+    calibrated: boolean;
+    interval_count: number;
+    features: number;
+    needed: number;
+    weights?: FamilyWeights;
+    residual?: number;
+    intervals: ReportedInterval[];
+}
+export interface QuotaReport {
+    days: number;
+    readings: {
+        files: string[];
+        lines: number;
+        malformed: number;
+        out_of_range: number;
+        skipped: string[];
+    };
+    transcripts: {
+        files: number;
+        oversize: number;
+        skipped: number;
+        messages: number;
+    };
+    windows: Record<QuotaWindow, WindowReport>;
+    note: string;
+    written: string | null;
+}
+/** quota-calibration.json: calibrated windows only. */
+export interface QuotaCalibration {
+    written: string;
+    days: number;
+    windows: Partial<Record<QuotaWindow, {
+        weights: FamilyWeights;
+        intervals: number;
+        residual: number;
+    }>>;
+}
+export declare function quotaDir(home?: string): string;
+export declare function quotaCalibrationPath(home?: string): string;
+/** A readings line in the sink schema, else null (malformed). */
+export declare function parseReading(raw: string): QuotaReading | null;
+/** Readings from the rotation then the live file, within the last `days`, in time order. */
+export declare function readReadings(home: string, days: number, now: Date): {
+    readings: QuotaReading[];
+    report: QuotaReport["readings"];
+};
+/**
+ * Rising intervals per window. A reading repeating the window's previous percentage and reset is
+ * no new reading for that window (the other window changed), so the interval starts at the first
+ * reading of the value and keeps the tokens spent while the meter had not yet moved.
+ */
+export declare function formIntervals(readings: QuotaReading[]): Record<QuotaWindow, Omit<ReportedInterval, "tokens" | "tokens_per_pct">[]>;
+interface Message {
+    time: number;
+    family: ModelFamily;
+    cache_read: number;
+    fresh: number;
+}
+/**
+ * Assistant messages with usage, one per `message.id` (else per file and line); the last line of
+ * an id wins, as in the cost tracker, since a streamed message repeats its usage on every line.
+ * A file last written before `since` cannot hold a message inside any interval and is not read.
+ */
+export declare function readMessages(home: string, since: number): {
+    messages: Message[];
+    report: QuotaReport["transcripts"];
+};
+/** Non-negative least squares, Lawson-Hanson (1974): min ||Ax - b|| subject to x >= 0. */
+export declare function nnls(A: number[][], b: number[]): number[];
+/**
+ * Fits percent per million tokens per family and group to the intervals' percentage rises.
+ * @param intervals Rows of (delta percent, tokens per family); tokens are raw counts.
+ * @returns The weights of every family with tokens, the interval count and the median absolute
+ *   residual in percentage points; or, below three intervals per feature, the count needed (a
+ *   window without tokens needs at least one family's two features).
+ */
+export declare function fitWeights(intervals: QuotaInterval[]): FitResult;
+/** Reads, forms intervals, sums tokens and fits each window; writes nothing. */
+export declare function quotaReport(home: string, days: number, now?: Date): QuotaReport;
+export declare function formatQuota(report: QuotaReport): string[];
+/** The calibration file's content: calibrated windows only, so a window without a fit never overwrites one. */
+export declare function calibrationOf(report: QuotaReport, now: Date): QuotaCalibration;
+/**
+ * Replaces the calibration file whole: a temporary file in the same directory, fsync, rename, so
+ * the routing report never reads a half-written file; an existing symlink or non-regular target
+ * is refused rather than replaced.
+ */
+export declare function writeCalibration(file: string, calibration: QuotaCalibration): void;
+/**
+ * Reads the calibration for the routing report's window estimate.
+ * @returns The shape-checked calibration; null without a warning when the file is absent; null
+ *   with one `quota calibration ignored: <reason>` line when it is unreadable or off-contract.
+ */
+export declare function readCalibration(file?: string): {
+    calibration: QuotaCalibration | null;
+    warning: string | null;
+};
+export interface CostQuotaOptions {
+    days?: number;
+    json?: boolean;
+    write?: boolean;
+    /** Tests and callers pin these; the CLI uses the user's HOME and the wall clock. */
+    home?: string;
+    now?: Date;
+}
+/**
+ * Runs the calibration and, with `write`, stores the calibrated windows.
+ * @returns The lines to print: the text report, or one JSON document with `--json`.
+ */
+export declare function costQuota(opts?: CostQuotaOptions): string[];
+export {};