faberwright 0.3.0

package/dist/tools/fs.js

@@ -0,0 +1,177 @@
+/**
+ * Filesystem tools. Hardening beyond v0.1:
+ *  - Path jail on every operation (symlink-resolved).
+ *  - ATOMIC writes: write to temp file then rename — a crash mid-write can
+ *    never leave a half-written source file.
+ *  - Every mutation produces a unified diff, enabling approval mode.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createTwoFilesPatch } from "diff";
+import { ToolError } from "../errors.js";
+const SKIP_DIRS = new Set([".git", ".faber", ".codewright", "node_modules", ".venv", "venv", "__pycache__", "dist", "build"]);
+export function resolveInWorkspace(workspace, p) {
+    const abs = path.isAbsolute(p) ? path.resolve(p) : path.resolve(workspace, p);
+    // resolve symlinks on the deepest existing ancestor to prevent escapes
+    let probe = abs;
+    while (!fs.existsSync(probe)) {
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break;
+        probe = parent;
+    }
+    const real = fs.realpathSync(probe) + abs.slice(probe.length);
+    const rel = path.relative(fs.realpathSync(workspace), real);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) {
+        throw new ToolError(`Path escapes the workspace: ${p}`);
+    }
+    return abs;
+}
+function atomicWrite(abs, content) {
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const tmp = `${abs}.faber-tmp-${process.pid}`;
+    fs.writeFileSync(tmp, content);
+    fs.renameSync(tmp, content.length >= 0 ? abs : abs); // rename is atomic on POSIX
+}
+export class FsTools {
+    config;
+    checkpoints;
+    constructor(config, checkpoints) {
+        this.config = config;
+        this.checkpoints = checkpoints;
+    }
+    readFile(p, startLine = 1, endLine) {
+        const abs = resolveInWorkspace(this.config.workspace, p);
+        if (!fs.existsSync(abs))
+            throw new ToolError(`File not found: ${p}`);
+        const size = fs.statSync(abs).size;
+        if (size > this.config.maxFileReadBytes) {
+            throw new ToolError(`File too large (${size} bytes). Read a line range instead (start_line/end_line).`);
+        }
+        const lines = fs.readFileSync(abs, "utf8").split("\n");
+        const chunk = lines.slice(Math.max(0, startLine - 1), endLine ?? lines.length);
+        return chunk.map((l, i) => `${i + startLine}\t${l}`).join("\n") || "(empty file)";
+    }
+    listDir(p = ".", depth = 2) {
+        const root = resolveInWorkspace(this.config.workspace, p);
+        if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+            throw new ToolError(`Not a directory: ${p}`);
+        }
+        const out = [];
+        const walk = (d, level) => {
+            if (level > depth || out.length > 500)
+                return;
+            let entries;
+            try {
+                entries = fs.readdirSync(d, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            entries.sort((a, b) => Number(a.isFile()) - Number(b.isFile()) || a.name.localeCompare(b.name));
+            for (const e of entries) {
+                if (SKIP_DIRS.has(e.name) || e.name.startsWith("."))
+                    continue;
+                out.push(`${"  ".repeat(level)}${e.name}${e.isDirectory() ? "/" : ""}`);
+                if (e.isDirectory())
+                    walk(path.join(d, e.name), level + 1);
+            }
+        };
+        walk(root, 0);
+        return out.join("\n") || "(empty)";
+    }
+    grep(pattern, p = ".", maxResults = 50) {
+        let rx;
+        try {
+            rx = new RegExp(pattern);
+        }
+        catch (e) {
+            throw new ToolError(`Invalid regex: ${e}`);
+        }
+        const root = resolveInWorkspace(this.config.workspace, p);
+        const hits = [];
+        const files = fs.statSync(root).isFile() ? [root] : [...walkFiles(root)];
+        for (const f of files) {
+            let text;
+            try {
+                if (fs.statSync(f).size > 1_000_000)
+                    continue;
+                text = fs.readFileSync(f, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const lines = text.split("\n");
+            for (let i = 0; i < lines.length; i++) {
+                if (rx.test(lines[i])) {
+                    hits.push(`${path.relative(this.config.workspace, f)}:${i + 1}: ${lines[i].trim().slice(0, 200)}`);
+                    if (hits.length >= maxResults)
+                        return hits.join("\n") + "\n(truncated)";
+                }
+            }
+        }
+        return hits.join("\n") || "No matches.";
+    }
+    /** Returns a PendingWrite: diff for preview + apply() that commits it. */
+    stageWrite(p, content) {
+        const abs = resolveInWorkspace(this.config.workspace, p);
+        const before = fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : "";
+        const diff = createTwoFilesPatch(p, p, before, content, "before", "after");
+        return {
+            path: p,
+            diff,
+            apply: () => {
+                this.checkpoints.snapshot(abs);
+                atomicWrite(abs, content);
+                return `Wrote ${Buffer.byteLength(content)} bytes to ${p}`;
+            },
+        };
+    }
+    /** Exact, unique string replacement — staged for approval like stageWrite. */
+    stageEdit(p, oldStr, newStr) {
+        const abs = resolveInWorkspace(this.config.workspace, p);
+        if (!fs.existsSync(abs))
+            throw new ToolError(`File not found: ${p}`);
+        const text = fs.readFileSync(abs, "utf8");
+        const count = text.split(oldStr).length - 1;
+        if (count === 0) {
+            throw new ToolError("old_str not found in file. Re-read the file — it may have changed, or your string may not match exactly (check whitespace).");
+        }
+        if (count > 1) {
+            throw new ToolError(`old_str appears ${count} times; it must be unique. Include more surrounding context.`);
+        }
+        const after = text.replace(oldStr, newStr);
+        const diff = createTwoFilesPatch(p, p, text, after, "before", "after");
+        return {
+            path: p,
+            diff,
+            apply: () => {
+                // guard against the file changing between stage and apply
+                const current = fs.readFileSync(abs, "utf8");
+                if (current !== text)
+                    throw new ToolError(`${p} changed since the edit was staged; re-read and retry.`);
+                this.checkpoints.snapshot(abs);
+                atomicWrite(abs, after);
+                return `Edited ${p} (1 replacement).`;
+            },
+        };
+    }
+}
+function* walkFiles(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (SKIP_DIRS.has(e.name) || e.name.startsWith("."))
+            continue;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            yield* walkFiles(full);
+        else if (e.isFile())
+            yield full;
+    }
+}

package/dist/tools/registry.js

@@ -0,0 +1,206 @@
+import { ToolError } from "../errors.js";
+import { FsTools } from "./fs.js";
+import { SessionStore } from "../memory/sessions.js";
+import { ShellTool } from "./shell.js";
+export class ToolRegistry {
+    config;
+    ltm;
+    indexer;
+    approve;
+    askUser;
+    fs;
+    shell;
+    defs;
+    currentSessionId;
+    constructor(config, checkpoints, ltm, indexer, approve, askUser = async () => 0) {
+        this.config = config;
+        this.ltm = ltm;
+        this.indexer = indexer;
+        this.approve = approve;
+        this.askUser = askUser;
+        this.fs = new FsTools(config, checkpoints);
+        this.shell = new ShellTool(config);
+        this.defs = {
+            read_file: {
+                description: "Read a file with line numbers. Use start_line/end_line for large files.",
+                fields: { path: { type: "string", required: true }, start_line: { type: "integer" }, end_line: { type: "integer" } },
+                handler: (i) => this.fs.readFile(i.path, i.start_line ?? 1, i.end_line),
+            },
+            write_file: {
+                description: "Create or overwrite a file. A checkpoint is taken automatically; in ask-mode the user previews a diff first.",
+                fields: { path: { type: "string", required: true }, content: { type: "string", required: true } },
+                handler: (i) => this.applyPending(this.fs.stageWrite(i.path, i.content)),
+            },
+            edit_file: {
+                description: "Surgically edit a file by replacing old_str (must match exactly once, including whitespace) with new_str. Prefer over write_file for existing files.",
+                fields: { path: { type: "string", required: true }, old_str: { type: "string", required: true }, new_str: { type: "string", required: true } },
+                handler: (i) => this.applyPending(this.fs.stageEdit(i.path, i.old_str, i.new_str)),
+            },
+            list_dir: {
+                description: "List directory contents as a tree (default depth 2).",
+                fields: { path: { type: "string" }, depth: { type: "integer" } },
+                handler: (i) => this.fs.listDir(i.path ?? ".", i.depth ?? 2),
+            },
+            grep: {
+                description: "Regex search across files. Returns path:line: match.",
+                fields: { pattern: { type: "string", required: true }, path: { type: "string" }, max_results: { type: "integer" } },
+                handler: (i) => this.fs.grep(i.pattern, i.path ?? ".", i.max_results ?? 50),
+            },
+            run_shell: {
+                description: "Run a shell command in the workspace (tests, builds, git, installs). Output includes exit code. Destructive commands are blocked; in ask-mode the user approves each command first.",
+                fields: { command: { type: "string", required: true }, timeout: { type: "integer" } },
+                handler: async (i, signal) => {
+                    const command = i.command;
+                    const ok = await this.approve({
+                        kind: "shell",
+                        path: `$ ${command}`,
+                        diff: command,
+                        apply: () => "",
+                    });
+                    if (!ok) {
+                        throw new ToolError(`User REJECTED running: ${command}. Do not retry the same command; ask the user or take a different approach.`);
+                    }
+                    return this.shell.run(command, i.timeout != null ? i.timeout * 1000 : undefined, signal);
+                },
+            },
+            search_code: {
+                description: "Search the symbol index for function/class definitions by name.",
+                fields: { query: { type: "string", required: true } },
+                handler: (i) => {
+                    this.freshIndex();
+                    const results = this.indexer.search(i.query);
+                    return results.length
+                        ? results.map((r) => `${r.path}:${r.line} [${r.kind}] ${r.signature}`).join("\n")
+                        : "No symbols matched. Try `grep` for full-text search.";
+                },
+            },
+            who_calls: {
+                description: "Code graph: list every place a function/symbol is called FROM (its blast radius). Edges are static-analysis hints — verify by reading where precision matters.",
+                fields: { name: { type: "string", required: true } },
+                handler: (i) => {
+                    this.freshIndex();
+                    const edges = this.indexer.whoCalls(i.name);
+                    return edges.length
+                        ? edges.map((e) => `${e.caller} -> ${i.name}  (${e.path}:${e.line})`).join("\n")
+                        : `No recorded callers of ${i.name}. It may be an entry point, called dynamically, or unindexed.`;
+                },
+            },
+            calls_from: {
+                description: "Code graph: list everything a function calls (its dependencies). Static hints — verify by reading where precision matters.",
+                fields: { name: { type: "string", required: true } },
+                handler: (i) => {
+                    this.freshIndex();
+                    const edges = this.indexer.callsFrom(i.name);
+                    return edges.length
+                        ? edges.map((e) => `${i.name} -> ${e.callee}  (${e.path}:${e.line})`).join("\n")
+                        : `${i.name} calls no indexed symbols (leaf function, or calls only external/dynamic code).`;
+                },
+            },
+            trace_path: {
+                description: "Code graph: shortest call chain connecting two symbols, e.g. trace_path(main, saveUser) -> main -> startServer -> handleSignup -> saveUser. Use to understand workflow before editing.",
+                fields: { from: { type: "string", required: true }, to: { type: "string", required: true } },
+                handler: (i) => {
+                    this.freshIndex();
+                    const chain = this.indexer.tracePath(i.from, i.to);
+                    return chain
+                        ? chain.join(" -> ")
+                        : `No static call path found from ${i.from} to ${i.to} (may be connected dynamically, via events, or not at all).`;
+                },
+            },
+            remember: {
+                description: "Store a durable memory for future sessions: project facts, architecture decisions, user preferences, gotchas. kind is one of fact|decision|preference|gotcha.",
+                fields: { kind: { type: "string", required: true }, content: { type: "string", required: true }, tags: { type: "string" } },
+                handler: (i) => `Stored memory #${this.ltm.remember(i.kind, i.content, i.tags ?? "")} (${i.kind}).`,
+            },
+            ask_user: {
+                description: "Present 2-4 mutually exclusive options to the user and get their pick (arrow-key menu). Use BEFORE implementing when there are meaningfully different approaches, designs, or interpretations of the request. Keep each option short (one line). A 'discuss instead' choice is added automatically — never add your own.",
+                fields: { question: { type: "string", required: true }, options: { type: "string_array", required: true } },
+                handler: async (i) => {
+                    const opts = i.options.slice(0, 4);
+                    const withEscape = [...opts, "Chat more about this instead"];
+                    const pick = await this.askUser(i.question, withEscape);
+                    if (pick < 0 || pick >= opts.length) {
+                        return "User did not pick an option — they want to discuss further. Ask a clarifying question instead of implementing.";
+                    }
+                    return `User chose option ${pick + 1}: "${opts[pick]}". Proceed with this approach.`;
+                },
+            },
+            recall_sessions: {
+                description: "Search PAST conversation sessions in this project. Use when the user references a previous conversation ('last time', 'what did I ask before', 'the thing we discussed') or when past context would clearly help. Returns matching snippets with dates.",
+                fields: { query: { type: "string", required: true } },
+                handler: (i) => {
+                    const hits = SessionStore.search(this.config.sessionsDir, i.query, 5, this.currentSessionId);
+                    return hits.length
+                        ? hits.map((h) => `[${h.when}] (${h.role}) ...${h.snippet}...`).join("\n---\n")
+                        : "No matching past conversations found for that query.";
+                },
+            },
+            note_file: {
+                description: "Save/update a one-line summary of what a file does (persisted across sessions).",
+                fields: { path: { type: "string", required: true }, summary: { type: "string", required: true } },
+                handler: (i) => { this.ltm.noteFile(i.path, i.summary); return `Noted ${i.path}.`; },
+            },
+        };
+    }
+    async applyPending(pending) {
+        const ok = await this.approve(pending);
+        if (!ok) {
+            throw new ToolError(`User REJECTED the change to ${pending.path}. Do not retry the same change; ask the user what they want instead or take a different approach.`);
+        }
+        return pending.apply();
+    }
+    freshIndex() {
+        if (!this.indexer.isBuilt())
+            this.indexer.build();
+        else
+            this.indexer.refresh(); // incremental: only changed files re-parsed
+    }
+    /** Canonical signature used by the agent's doom-loop detector. */
+    static signature(name, input) {
+        return `${name}:${JSON.stringify(input, Object.keys(input).sort())}`;
+    }
+    async execute(name, input, signal) {
+        const def = this.defs[name];
+        if (!def)
+            return { output: `Unknown tool: ${name}. Available: ${Object.keys(this.defs).join(", ")}`, isError: true };
+        // validate before executing
+        for (const [field, spec] of Object.entries(def.fields)) {
+            const v = input[field];
+            if (v == null) {
+                if (spec.required)
+                    return { output: `Missing required argument '${field}' for ${name}.`, isError: true };
+                continue;
+            }
+            if (spec.type === "string" && typeof v !== "string") {
+                return { output: `Argument '${field}' of ${name} must be a string.`, isError: true };
+            }
+            if (spec.type === "integer" && (!Number.isFinite(v) || !Number.isInteger(v))) {
+                return { output: `Argument '${field}' of ${name} must be an integer.`, isError: true };
+            }
+            if (spec.type === "string_array" && (!Array.isArray(v) || !v.every((x) => typeof x === "string") || v.length === 0)) {
+                return { output: `Argument '${field}' of ${name} must be a non-empty array of strings.`, isError: true };
+            }
+        }
+        try {
+            return { output: String(await def.handler(input, signal)), isError: false };
+        }
+        catch (err) {
+            if (err instanceof ToolError)
+                return { output: `Tool error: ${err.message}`, isError: true };
+            throw err; // CancelledError and unexpected errors propagate to the agent
+        }
+    }
+    schemas() {
+        return Object.entries(this.defs).map(([name, def]) => ({
+            name,
+            description: def.description,
+            input_schema: {
+                type: "object",
+                properties: Object.fromEntries(Object.entries(def.fields).map(([f, s]) => [f,
+                    s.type === "string_array" ? { type: "array", items: { type: "string" } } : { type: s.type },
+                ])),
+                required: Object.entries(def.fields).filter(([, s]) => s.required).map(([f]) => f),
+            },
+        }));
+    }
+}

package/dist/tools/shell.js

@@ -0,0 +1,68 @@
+/**
+ * Shell tool: timeout (SIGKILL fallback), denylist, output truncation,
+ * cancellation via AbortSignal. Guardrails — not a security boundary; run
+ * Faber in a container for untrusted code (see README).
+ */
+import { spawn } from "node:child_process";
+import { ToolError, CancelledError } from "../errors.js";
+const DENY = [
+    /\brm\s+(-[a-zA-Z]*\s+)*[/~]\s*$/,
+    /\brm\s+-[a-zA-Z]*r[a-zA-Z]*\s+\/(?:\s|$)/,
+    /\bmkfs\b/,
+    /\bdd\s+.*of=\/dev\//,
+    /:\(\)\s*\{.*\};\s*:/,
+    /\bsudo\b/,
+    /\bshutdown\b|\breboot\b/,
+    />\s*\/dev\/sd[a-z]/,
+    /\bchmod\s+-R\s+777\s+\//,
+];
+const MAX_OUTPUT = 20_000;
+export class ShellTool {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    run(command, timeoutMs, signal) {
+        for (const rx of DENY) {
+            if (rx.test(command)) {
+                throw new ToolError("Command blocked by safety policy (destructive or privileged pattern). Use a narrower, non-destructive command.");
+            }
+        }
+        const timeout = Math.min(timeoutMs ?? this.config.shellTimeoutMs, 600_000);
+        return new Promise((resolve, reject) => {
+            const child = spawn(command, { shell: true, cwd: this.config.workspace });
+            let out = "";
+            let killed = false;
+            const kill = (why) => {
+                killed = true;
+                child.kill("SIGTERM");
+                setTimeout(() => child.kill("SIGKILL"), 3000).unref();
+                if (why === "timeout") {
+                    reject(new ToolError(`Command timed out after ${timeout / 1000}s. Consider a faster variant or run it in the background.`));
+                }
+                else {
+                    reject(new CancelledError());
+                }
+            };
+            const timer = setTimeout(() => kill("timeout"), timeout);
+            signal?.addEventListener("abort", () => { clearTimeout(timer); kill("cancel"); }, { once: true });
+            const collect = (chunk, label = "") => {
+                if (out.length < MAX_OUTPUT * 2)
+                    out += (label && !out.endsWith(label) ? label : "") + chunk.toString();
+            };
+            child.stdout.on("data", (c) => collect(c));
+            child.stderr.on("data", (c) => collect(c, "\n[stderr]\n"));
+            child.on("error", (err) => { clearTimeout(timer); reject(new ToolError(`Failed to start command: ${err.message}`)); });
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                if (killed)
+                    return;
+                let text = out;
+                if (text.length > MAX_OUTPUT) {
+                    text = text.slice(0, MAX_OUTPUT / 2) + "\n...[output truncated]...\n" + text.slice(-MAX_OUTPUT / 2);
+                }
+                resolve(`[exit code: ${code ?? "?"}]\n${text.trim() || "(no output)"}`);
+            });
+        });
+    }
+}

package/dist/usage.js

@@ -0,0 +1,147 @@
+/**
+ * Persistent usage ledger — every task's token/cost record, per project.
+ * Stored in <project>/.faber/usage.db (per-project, like all state). Powers the
+ * /usage panel (session / today / all-time) and cross-project totals via a
+ * small registry of project paths in ~/.faber/projects.json — the first
+ * resident of the global home directory from the roadmap.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+export class UsageLedger {
+    projectPath;
+    db;
+    session = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0, calls: 0, tasks: 0 };
+    constructor(dbPath, projectPath) {
+        this.projectPath = projectPath;
+        this.db = new DatabaseSync(dbPath);
+        this.db.exec("PRAGMA journal_mode = WAL");
+        this.db.exec(`CREATE TABLE IF NOT EXISTS tasks (
+      ts INTEGER, input INTEGER, cache_read INTEGER, cache_write INTEGER,
+      output INTEGER, calls INTEGER, model TEXT)`);
+        this.registerProject();
+    }
+    record(u, model) {
+        this.db.prepare("INSERT INTO tasks VALUES (?, ?, ?, ?, ?, ?, ?)")
+            .run(Date.now(), u.input, u.cacheRead, u.cacheWrite, u.output, u.calls, model);
+        this.session.input += u.input;
+        this.session.cacheRead += u.cacheRead;
+        this.session.cacheWrite += u.cacheWrite;
+        this.session.output += u.output;
+        this.session.calls += u.calls;
+        this.session.tasks += 1;
+    }
+    totals(sinceMs) {
+        return this.db.prepare(`SELECT COUNT(*) tasks, COALESCE(SUM(input),0) input, COALESCE(SUM(cache_read),0) cacheRead,
+              COALESCE(SUM(cache_write),0) cacheWrite, COALESCE(SUM(output),0) output,
+              COALESCE(SUM(calls),0) calls
+       FROM tasks WHERE ts >= ?`).get(sinceMs ?? 0);
+    }
+    /** Cost in USD; undefined when CW_PRICE_IN/OUT aren't configured. */
+    static cost(u, priceIn, priceOut) {
+        if (!priceIn || !priceOut)
+            return undefined;
+        return (u.input * priceIn + u.cacheRead * priceIn * 0.1 +
+            u.cacheWrite * priceIn * 1.25 + u.output * priceOut) / 1e6;
+    }
+    /** Net savings from caching vs paying full input price (reads at 0.1x minus write premium). */
+    static saved(u, priceIn) {
+        if (!priceIn)
+            return undefined;
+        return (u.cacheRead * priceIn * 0.9 - u.cacheWrite * priceIn * 0.25) / 1e6;
+    }
+    // ---- global registry so usage can be summed across every project ----
+    registerProject() {
+        try {
+            const dir = path.join(os.homedir(), ".faber");
+            fs.mkdirSync(dir, { recursive: true });
+            const reg = path.join(dir, "projects.json");
+            let list = [];
+            try {
+                list = JSON.parse(fs.readFileSync(reg, "utf8"));
+            }
+            catch { /* fresh */ }
+            if (!list.includes(this.projectPath)) {
+                list.push(this.projectPath);
+                fs.writeFileSync(reg, JSON.stringify(list, null, 2));
+            }
+        }
+        catch { /* registry is best-effort */ }
+    }
+    static allProjects() {
+        const home = os.homedir();
+        let list = [];
+        for (const reg of [path.join(home, ".faber", "projects.json"),
+            path.join(home, ".codewright", "projects.json")]) {
+            try {
+                for (const p of JSON.parse(fs.readFileSync(reg, "utf8"))) {
+                    if (!list.includes(p))
+                        list.push(p);
+                }
+            }
+            catch { /* absent registry is fine */ }
+        }
+        if (!list.length)
+            return [];
+        const out = [];
+        for (const p of list) {
+            const dbPath = [path.join(p, ".faber", "usage.db"), path.join(p, ".codewright", "usage.db")]
+                .find((d) => fs.existsSync(d));
+            if (!dbPath)
+                continue;
+            try {
+                const led = new UsageLedger(dbPath, p);
+                out.push({ project: p, totals: led.totals() });
+                led.close();
+            }
+            catch { /* skip unreadable */ }
+        }
+        return out;
+    }
+    close() { this.db.close(); }
+}
+const k = (n) => n >= 1_000_000 ? (n / 1_000_000).toFixed(1) + "M"
+    : n >= 1000 ? (n / 1000).toFixed(1) + "k" : String(n);
+const money = (v) => v === undefined ? "—" : `$${v.toFixed(2)}`;
+/** Render the /usage stats panel. */
+export function renderUsagePanel(ledger, priceIn, priceOut) {
+    const midnight = new Date();
+    midnight.setHours(0, 0, 0, 0);
+    const rows = [
+        ["this session", ledger.session],
+        ["today", ledger.totals(midnight.getTime())],
+        ["all time", ledger.totals()],
+    ];
+    const lines = [];
+    const W = [13, 7, 12, 9, 7, 9, 9];
+    const cells = (c) => c.map((s, i) => s.padEnd(W[i])).join(" ");
+    lines.push(cells(["", "tasks", "in", "cached", "out", "cost", "saved"]));
+    for (const [label, t] of rows) {
+        const totalIn = t.input + t.cacheRead + t.cacheWrite;
+        const pct = totalIn > 0 ? Math.round((t.cacheRead / totalIn) * 100) + "%" : "0%";
+        lines.push(cells([
+            label, String(t.tasks), k(totalIn), pct, k(t.output),
+            money(UsageLedger.cost(t, priceIn, priceOut)),
+            money(UsageLedger.saved(t, priceIn)),
+        ]));
+    }
+    if (!priceIn || !priceOut) {
+        lines.push("");
+        lines.push("set CW_PRICE_IN and CW_PRICE_OUT ($/Mtok) to see cost and savings");
+    }
+    const others = UsageLedger.allProjects().filter((p) => p.totals.tasks > 0);
+    if (others.length > 1) {
+        lines.push("");
+        lines.push("across all projects:");
+        for (const { project, totals: t } of others) {
+            const totalIn = t.input + t.cacheRead + t.cacheWrite;
+            lines.push(cells([
+                "  " + path.basename(project).slice(0, 11), String(t.tasks), k(totalIn),
+                totalIn > 0 ? Math.round((t.cacheRead / totalIn) * 100) + "%" : "0%",
+                k(t.output), money(UsageLedger.cost(t, priceIn, priceOut)), "",
+            ]));
+        }
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "faberwright",
+  "version": "0.3.0",
+  "description": "Faber: an agentic AI coding assistant for your terminal — streams, edits with diff approval, runs your tests, and remembers your project across sessions.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "bin": {
+    "faber": "dist/index.js",
+    "fb": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsc && node --test dist-test/test/*.test.js",
+    "prepublishOnly": "npm test && npm run build",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "postbuild": "chmod +x dist/index.js"
+  },
+  "dependencies": {
+    "diff": "^7.0.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/diff": "^6.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "coding-assistant",
+    "agent",
+    "anthropic",
+    "claude",
+    "openai",
+    "ollama",
+    "code-graph",
+    "developer-tools",
+    "terminal",
+    "llm"
+  ]
+}