@counterfact-labs/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1 @@
+Copyright (c) 2026 Counterfact Labs, Inc. All rights reserved. This software is provided to access the Counterfact service and may be used only for that purpose. No other rights are granted.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# Counterfact command line
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Check an agent's prompt, skills and tool definitions from your terminal or coding agent. Requires Node.js 20 or later.
+
+```sh
+npm install -g @counterfact-labs/cli
+counterfact-labs login
+counterfact-labs check ./support-agent
+```
+
+The command lists the selected files and shows the server's price before asking to continue. Use `--yes` after agreeing to that price. Use `--dry-run` to see the files and quote without starting analysis or charging your balance. A quote requires uploading the selected files, including in a dry run.
+
+```sh
+counterfact-labs check ./support-agent --dry-run
+counterfact-labs check ./support-agent --yes
+counterfact-labs finding <finding-id>
+counterfact-labs balance
+counterfact-labs logout
+```
+
+Checks return exit code 0 on success, 1 on error and 2 when the balance is too low. The server chooses the files, sets the price and writes the result summary. The first eligible check is free. Failed checks are not charged.
+
+The console is at `https://app.counterfactlabs.com`. Sign in again after moving from the old address; saved sign-in belongs to the server address.
+
+Add the local MCP server to Codex:
+
+```sh
+codex mcp add counterfact -- npx -y @counterfact-labs/cli@latest mcp
+```
+
+Checks can take several minutes. Codex has a [60-second tool timeout by default](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). In `~/.codex/config.toml`, add `tool_timeout_sec = 900` to the existing `[mcp_servers.counterfact]` section. It should look like this; keep any other settings already in that section:
+
+```toml
+[mcp_servers.counterfact]
+command = "npx"
+args = ["-y", "@counterfact-labs/cli@latest", "mcp"]
+tool_timeout_sec = 900
+```
+
+Cancellation stops the local wait. A confirmed check keeps running on the server after cancellation or a timeout, and its result appears on the console's Checks page.
+
+Add this to your project's `AGENTS.md`:
+
+```markdown
+When I ask to check an agent, use Counterfact's check_agent tool with its folder path.
+Call it without confirm first. Show me the selected files and price, and get my
+agreement before calling again with confirm: true. If the files or price change,
+show me a fresh preview and ask again. Use get_finding for an explanation, quoted
+lines and suggested fixes. Use get_balance for the balance and top-up link.
+After editing prompts, skills or tool definitions, suggest a check and wait for
+me to ask for it.
+```
+
+The MCP server reads local files and communicates over stdin and stdout. Its tools are `check_agent(path, confirm?)`, `get_finding(id)` and `get_balance()`. Each result's structured content repeats the tool's text, and completed checks add their finding ids. Keep the preview and confirmation in the same MCP session.
+
+Privacy: only files requested by the server are uploaded. The tool skips `.git`, `node_modules`, `.gitignore` matches, symlinks and secret file names such as `.env` and private keys. Uploaded files are kept with the check while the workspace exists, and deleted with the check or workspace. Sign-in is saved in `~/.config/counterfact-labs/credentials` with owner-only permissions. `logout` removes that local sign-in; revoke the token from your account to disable it elsewhere.
+
+Set `COUNTERFACT_URL` to use another server. It defaults to `https://app.counterfactlabs.com`. Sign-in is tied to the server address; sign in again when changing it.
+
+From this repository, `npm run cli:test` copies the API types and secret-file rule from their server owners, compiles the package with TypeScript and runs its offline tests. No additional npm dependencies are needed.

package/dist/api-types.js

@@ -0,0 +1,2 @@
+// This file is copied into the command-line package before its build. Keep it self-contained.
+export const CLI_BODY_LIMIT = 2 * 1024 * 1024;

package/dist/api.js

@@ -0,0 +1,97 @@
+import { CLI_BODY_LIMIT } from "./api-types.js";
+export const DEFAULT_URL = "https://app.counterfactlabs.com";
+export class ApiError extends Error {
+    status;
+    code;
+    retryAfterMs;
+    constructor(status, code, message, retryAfterMs = 0) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+function retryAfterMs(value) {
+    if (!value)
+        return 0;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+}
+export class ApiClient {
+    token;
+    fetcher;
+    signal;
+    baseUrl;
+    constructor(baseUrl, token, fetcher = fetch, signal) {
+        this.token = token;
+        this.fetcher = fetcher;
+        this.signal = signal;
+        const url = new URL(baseUrl);
+        if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+            throw new Error("COUNTERFACT_URL must be an HTTP or HTTPS address without credentials or query fields.");
+        this.baseUrl = url.href.replace(/\/+$/, "");
+    }
+    async request(path, body, authenticated = true) {
+        this.signal?.throwIfAborted();
+        const headers = { accept: "application/json" };
+        if (authenticated) {
+            const token = await this.token();
+            if (!token)
+                throw new Error("Not signed in. Run counterfact-labs login.");
+            headers.authorization = `Bearer ${token}`;
+        }
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const serialized = body === undefined ? undefined : JSON.stringify(body);
+        if (serialized !== undefined && Buffer.byteLength(serialized, "utf8") > CLI_BODY_LIMIT) {
+            throw new ApiError(413, "body_too_large", "The upload is too large. Send at most 2 MB.");
+        }
+        const controller = new AbortController();
+        const cancel = () => controller.abort(this.signal?.reason);
+        const timeout = setTimeout(() => controller.abort(), 120_000);
+        timeout.unref();
+        this.signal?.addEventListener("abort", cancel, { once: true });
+        try {
+            this.signal?.throwIfAborted();
+            let response;
+            try {
+                response = await this.fetcher(`${this.baseUrl}/api/cli/${path}`, {
+                    method: body === undefined ? "GET" : "POST", headers,
+                    body: serialized,
+                    redirect: "error", signal: controller.signal,
+                });
+            }
+            catch {
+                this.signal?.throwIfAborted();
+                throw new ApiError(0, "unreachable", "Can't reach Counterfact. Try again shortly.");
+            }
+            let value;
+            try {
+                value = await response.json();
+            }
+            catch (error) {
+                this.signal?.throwIfAborted();
+                if (response.ok) {
+                    if (error instanceof SyntaxError)
+                        throw new Error("Counterfact returned an invalid response. Try again shortly.");
+                    throw new ApiError(0, "unreachable", "Can't reach Counterfact. Try again shortly.");
+                }
+            }
+            this.signal?.throwIfAborted();
+            if (!response.ok) {
+                const error = value;
+                throw new ApiError(response.status, error?.code ?? "request_failed", typeof error?.error === "string" ? error.error : "The request could not be completed. Try again shortly.", retryAfterMs(response.headers.get("retry-after")));
+            }
+            return value;
+        }
+        finally {
+            clearTimeout(timeout);
+            this.signal?.removeEventListener("abort", cancel);
+        }
+    }
+}
+export function errorCode(error) { return error instanceof ApiError && error.code === "low_balance" ? 2 : 1; }
+export function errorText(error) { return error instanceof Error ? error.message : "The request could not be completed. Try again shortly."; }

package/dist/commands/balance.js

@@ -0,0 +1,6 @@
+import { money } from "../output.js";
+export async function balance(ctx) {
+    const value = await ctx.api.request("balance");
+    ctx.write(`Balance: ${money(value.balanceMicro)}\nTop up: ${value.topUpUrl}\n`);
+    return 0;
+}

package/dist/commands/check.js

@@ -0,0 +1,102 @@
+import { resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+import { listFiles, readUpload } from "../files.js";
+import { repositoryFacts } from "../git.js";
+import { fileText, quoteText, tasteText } from "../output.js";
+import { ApiError } from "../api.js";
+async function awaitQuote(response, ctx) {
+    let progressShown = false;
+    try {
+        while (response.status === "running") {
+            ctx.write(`\r\u001b[2K${response.progress}`);
+            progressShown = true;
+            await ctx.sleep(2000);
+            response = await ctx.api.request(`checks/${encodeURIComponent(response.id)}`);
+        }
+        if (response.status === "failed" || (response.status === "awaiting_confirm" && "error" in response))
+            throw new Error(response.error);
+        if (response.status !== "awaiting_confirm")
+            throw new Error("The check has already finished. Run the check again for a new quote.");
+        return response;
+    }
+    finally {
+        if (progressShown)
+            ctx.write("\r\u001b[2K");
+    }
+}
+export async function prepareCheck(path, ctx) {
+    const root = await realpath(resolve(path));
+    const { repoRoot, ...facts } = await repositoryFacts(root);
+    const files = await listFiles(root, repoRoot);
+    const plan = await ctx.api.request("checks/plan", { files });
+    const selected = new Set(plan.wanted);
+    const wanted = files.filter(file => selected.has(file.path));
+    if (!wanted.length)
+        throw new Error("No agent files were found in this folder.");
+    ctx.write(fileText(path, wanted));
+    const upload = await readUpload(root, files, plan.wanted);
+    const response = await awaitQuote(await ctx.api.request("checks", { ...facts, files: upload }), ctx);
+    ctx.write(quoteText(response.quote));
+    return { root, response, files: upload };
+}
+/** A confirmed check can keep running and charge while the connection is down. */
+async function pollConfirmed(id, ctx) {
+    const started = ctx.now();
+    let waited = 0, backoff = 2000;
+    for (;;) {
+        try {
+            return await ctx.api.request(`checks/${id}`);
+        }
+        catch (error) {
+            if (!(error instanceof ApiError) || !(error.status === 0 || error.status === 429 || error.status >= 500 && error.status < 600))
+                throw error;
+            const wait = Math.max(backoff, error.retryAfterMs);
+            // Count both elapsed requests and scheduled waits, including injected clocks.
+            if (Math.max(ctx.now() - started, waited) + wait >= 300_000) {
+                throw new Error(`The check is still running. Its result will appear on the console's Checks page: ${ctx.api.baseUrl}/checks`);
+            }
+            await ctx.sleep(wait);
+            waited += wait;
+            backoff = Math.min(backoff * 2, 30_000);
+        }
+    }
+}
+export async function confirmPrepared(prepared, ctx) {
+    // A preview's price belongs to those uploaded files. Edits need a fresh preview and agreement.
+    const files = Object.entries(prepared.files).map(([path, text]) => ({ path, size: Buffer.byteLength(text, "utf8") }));
+    const current = await readUpload(prepared.root, files, files.map(file => file.path));
+    if (files.some(file => current[file.path] !== prepared.files[file.path]))
+        throw new Error("The agent files changed. Get a new preview and agree to its price before confirming.");
+    const id = encodeURIComponent(prepared.response.id);
+    await ctx.api.request(`checks/${id}/confirm`, { quoteId: prepared.response.quote.quoteId });
+    ctx.write("\r\u001b[2KChecking the agent…");
+    try {
+        for (;;) {
+            await ctx.sleep(2000);
+            const response = await pollConfirmed(id, ctx);
+            if (response.status === "done") {
+                ctx.write("\r\u001b[2K");
+                ctx.write(tasteText(response.taste, response.findingIds));
+                return response;
+            }
+            if (response.status === "failed" || (response.status === "awaiting_confirm" && "error" in response))
+                throw new Error(response.error);
+            if (response.status === "awaiting_confirm")
+                throw new Error("The check needs approval again. Run the check again to see its price.");
+            ctx.write(`\r\u001b[2K${response.progress}`);
+        }
+    }
+    catch (error) {
+        ctx.write("\r\u001b[2K");
+        throw error;
+    }
+}
+export async function check(path, options, ctx) {
+    const prepared = await prepareCheck(path, ctx);
+    if (options.dryRun)
+        return 0;
+    if (!options.yes && !await ctx.ask("Continue? [Y/n] "))
+        return 0;
+    await confirmPrepared(prepared, ctx);
+    return 0;
+}

package/dist/commands/finding.js

@@ -0,0 +1,15 @@
+export async function finding(id, ctx) {
+    const value = await ctx.api.request(`findings/${encodeURIComponent(id)}`);
+    ctx.write(`${value.title}\n${value.explanation}\n`);
+    for (const quote of value.quotes) {
+        ctx.write(`\n${quote.path}${quote.line === null ? "" : `:${quote.line}`}\n`);
+        if (quote.text !== null)
+            ctx.write(quote.text.split("\n").map(line => `> ${line}`).join("\n") + "\n");
+    }
+    for (const fix of value.fixes) {
+        ctx.write(`\n${fix.title}\n${fix.approach}\n`);
+        if (fix.targetFiles.length)
+            ctx.write(`Files: ${fix.targetFiles.map(file => `${file.path}${file.create ? " (new file)" : ""}`).join(", ")}\n`);
+    }
+    return 0;
+}

package/dist/commands/login.js

@@ -0,0 +1,20 @@
+import { saveCredentials } from "../credentials.js";
+export async function login(ctx) {
+    const device = await ctx.api.request("device", {}, false);
+    ctx.write(`To sign in, open ${device.verificationUri} and enter ${device.userCode}\n`);
+    const until = ctx.now() + device.expiresIn * 1000;
+    while (ctx.now() < until) {
+        await ctx.sleep(device.interval * 1000);
+        const poll = await ctx.api.request("device/token", { deviceCode: device.deviceCode }, false);
+        if (poll.status === "ok") {
+            await saveCredentials(ctx.homeDir, ctx.api.baseUrl, poll.token);
+            ctx.write("Signed in.\n");
+            return 0;
+        }
+        if (poll.status === "expired")
+            break;
+        if (poll.status === "denied")
+            throw new Error("Sign-in was cancelled. Run counterfact-labs login to try again.");
+    }
+    throw new Error("The sign-in code expired. Run counterfact-labs login to try again.");
+}

package/dist/commands/logout.js

@@ -0,0 +1,6 @@
+import { deleteCredentials } from "../credentials.js";
+export async function logout(ctx) {
+    await deleteCredentials(ctx.homeDir);
+    ctx.write("Signed out on this computer.\n");
+    return 0;
+}

package/dist/context.js

@@ -0,0 +1,27 @@
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { ApiClient, DEFAULT_URL } from "./api.js";
+import { readCredentials } from "./credentials.js";
+export function commandContext(options = {}) {
+    const homeDir = options.homeDir ?? homedir();
+    const baseUrl = (options.baseUrl ?? process.env.COUNTERFACT_URL ?? DEFAULT_URL).replace(/\/+$/, "");
+    const api = new ApiClient(baseUrl, () => readCredentials(homeDir, api.baseUrl), undefined, options.signal);
+    const write = options.write ?? (text => { process.stdout.write(text); });
+    return {
+        api, homeDir, write,
+        sleep: options.sleep ?? (async (ms) => { await delay(ms, undefined, { signal: options.signal }); }), now: options.now ?? Date.now,
+        ask: options.ask ?? (async (question) => {
+            if (!process.stdin.isTTY)
+                throw new Error("Use --yes to confirm a check, or --dry-run to see the files and price.");
+            write(question);
+            const input = createInterface({ input: process.stdin });
+            try {
+                return /^(?:y|yes)?$/i.test((await input.question("")).trim());
+            }
+            finally {
+                input.close();
+            }
+        }),
+    };
+}

package/dist/credentials.js

@@ -0,0 +1,46 @@
+import { constants } from "node:fs";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+function credentialsPath(homeDir) { return join(homeDir, ".config/counterfact-labs/credentials"); }
+function missing(error) { return error.code === "ENOENT"; }
+export async function readCredentials(homeDir, baseUrl) {
+    try {
+        const file = await open(credentialsPath(homeDir), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const value = JSON.parse(await file.readFile("utf8"));
+            if (typeof value?.token !== "string" || !value.token || typeof value.baseUrl !== "string")
+                throw new Error("Invalid credentials");
+            return value.baseUrl === baseUrl ? value.token : null;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (missing(error))
+            return null;
+        throw new Error("Saved sign-in is unreadable. Run counterfact-labs login.");
+    }
+}
+export async function saveCredentials(homeDir, baseUrl, token) {
+    const directory = join(homeDir, ".config/counterfact-labs");
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = join(directory, `.credentials-${randomUUID()}`);
+    try {
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(JSON.stringify({ baseUrl, token }) + "\n", "utf8");
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, credentialsPath(homeDir));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function deleteCredentials(homeDir) {
+    await rm(credentialsPath(homeDir), { force: true });
+}

package/dist/files.js

@@ -0,0 +1,99 @@
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { ignored, parseIgnore } from "./gitignore.js";
+import { SECRET_FILE_RE } from "./secret-files.js";
+const slash = (path) => path.split(sep).join("/");
+function safe(path) {
+    return !!path && !path.includes("\\") && !path.includes("\0") && !path.startsWith("/") && !SECRET_FILE_RE.test(path)
+        && path.split("/").every(part => !["", ".", "..", ".git", "node_modules"].includes(part));
+}
+async function ignoreFile(directory, base) {
+    try {
+        const file = await open(join(directory, ".gitignore"), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            return parseIgnore(await file.readFile("utf8"), base);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (["ENOENT", "ELOOP"].includes(error.code ?? ""))
+            return [];
+        throw error;
+    }
+}
+export async function listFiles(root, repoRoot) {
+    root = await realpath(root);
+    const base = repoRoot ? await realpath(repoRoot) : root;
+    const prefix = slash(relative(base, root));
+    if (prefix.startsWith("../") || prefix === "..")
+        throw new Error("The agent folder must be inside its repository.");
+    let parentRules = [];
+    if (prefix) {
+        let directory = base;
+        parentRules = await ignoreFile(directory, "");
+        for (const part of prefix.split("/")) {
+            directory = join(directory, part);
+            if (ignored(slash(relative(base, directory)), true, parentRules))
+                return [];
+            if (directory !== root)
+                parentRules.push(...await ignoreFile(directory, slash(relative(base, directory))));
+        }
+    }
+    const files = [];
+    async function walk(directory, inherited) {
+        const scope = slash(relative(base, directory));
+        const rules = [...inherited, ...await ignoreFile(directory, scope)];
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            const absolute = join(directory, entry.name);
+            const path = slash(relative(root, absolute));
+            if (!safe(path) || entry.isSymbolicLink() || ignored(slash(relative(base, absolute)), entry.isDirectory(), rules))
+                continue;
+            if (entry.isDirectory())
+                await walk(absolute, rules);
+            else if (entry.isFile()) {
+                const stat = await lstat(absolute);
+                if (stat.isFile())
+                    files.push({ path, size: stat.size });
+            }
+        }
+    }
+    await walk(root, parentRules);
+    return files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+export async function readUpload(root, files, wanted) {
+    root = await realpath(root);
+    const sizes = new Map(files.map(file => [file.path, file.size]));
+    const uploaded = Object.create(null);
+    for (const path of wanted) {
+        if (!safe(path) || !sizes.has(path))
+            throw new Error("Counterfact requested a file outside the local file list.");
+        const absolute = resolve(root, path);
+        // A directory replaced by a symlink after listing must not expose files outside the folder.
+        if (await realpath(dirname(absolute)) !== dirname(absolute))
+            throw new Error("A file changed since listing. Run the check again.");
+        const file = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            if (!(await file.stat()).isFile())
+                throw new Error("Only regular files can be uploaded.");
+            const bytes = await file.readFile();
+            let text;
+            try {
+                text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+            }
+            catch {
+                throw new Error(`${path} is not UTF-8 text and cannot be uploaded.`);
+            }
+            if (Buffer.byteLength(text, "utf8") !== sizes.get(path))
+                throw new Error("A file changed since listing. Run the check again.");
+            uploaded[path] = text;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    return { ...uploaded };
+}

package/dist/git.js

@@ -0,0 +1,21 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { basename, relative, resolve, sep } from "node:path";
+export async function repositoryFacts(root, git = async (args) => (await promisify(execFile)("git", ["-C", root, ...args], { timeout: 3000, maxBuffer: 16_384 })).stdout) {
+    const folderName = basename(resolve(root));
+    let repoRoot;
+    try {
+        repoRoot = (await git(["rev-parse", "--show-toplevel"])).trim();
+    }
+    catch {
+        return { remoteUrl: null, relPath: "", folderName };
+    }
+    let remoteUrl;
+    try {
+        remoteUrl = (await git(["config", "--get", "remote.origin.url"])).trim().replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/]*@/i, "$1") || null;
+    }
+    catch {
+        remoteUrl = null;
+    }
+    return { repoRoot, remoteUrl, relPath: relative(repoRoot, root).split(sep).join("/"), folderName };
+}

package/dist/gitignore.js

@@ -0,0 +1,70 @@
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function glob(pattern) {
+    let result = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "\\" && i + 1 < pattern.length)
+            result += escape(pattern[++i]);
+        else if (ch === "*" && pattern[i + 1] === "*") {
+            i++;
+            if (pattern[i + 1] === "/") {
+                result += "(?:.*/)?";
+                i++;
+            }
+            else
+                result += ".*";
+        }
+        else if (ch === "*")
+            result += "[^/]*";
+        else if (ch === "?")
+            result += "[^/]";
+        else if (ch === "[") {
+            const end = pattern.indexOf("]", i + 1);
+            if (end < 0)
+                result += "\\[";
+            else {
+                const chars = pattern.slice(i + 1, end).replace(/^!/, "^");
+                result += `[${chars}]`;
+                i = end;
+            }
+        }
+        else
+            result += escape(ch);
+    }
+    return result;
+}
+export function parseIgnore(text, base) {
+    const rules = [];
+    for (let line of text.split(/\r?\n/)) {
+        line = line.replace(/(?<!\\) +$/, "");
+        if (!line || line.startsWith("#"))
+            continue;
+        const negate = line.startsWith("!");
+        if (negate)
+            line = line.slice(1);
+        const directory = line.endsWith("/");
+        if (directory)
+            line = line.slice(0, -1);
+        const anchored = line.startsWith("/") || line.includes("/");
+        if (line.startsWith("/"))
+            line = line.slice(1);
+        if (!line)
+            continue;
+        try {
+            rules.push({ base, directory, negate, regex: new RegExp(`${anchored ? "^" : "(?:^|/)"}${glob(line)}$`) });
+        }
+        catch {
+            throw new Error("A .gitignore pattern could not be read.");
+        }
+    }
+    return rules;
+}
+export function ignored(path, directory, rules) {
+    let excluded = false;
+    for (const rule of rules) {
+        const local = rule.base ? path.startsWith(`${rule.base}/`) ? path.slice(rule.base.length + 1) : null : path;
+        if (local !== null && (!rule.directory || directory) && rule.regex.test(local))
+            excluded = !rule.negate;
+    }
+    return excluded;
+}

package/dist/main.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { realpath } from "node:fs/promises";
+import { errorCode, errorText } from "./api.js";
+import { commandContext } from "./context.js";
+import { check } from "./commands/check.js";
+import { finding } from "./commands/finding.js";
+import { balance } from "./commands/balance.js";
+import { login } from "./commands/login.js";
+import { logout } from "./commands/logout.js";
+import { serveMcp } from "./mcp.js";
+const usage = "Usage: counterfact-labs check [path] [--yes] [--dry-run]\n       counterfact-labs finding <id>\n       counterfact-labs balance | login | logout | mcp\n";
+export async function run(args, options = {}) {
+    const write = options.write ?? (text => { process.stdout.write(text); });
+    try {
+        const [command, ...rest] = args;
+        if (["--help", "-h", "help"].includes(command) || !command) {
+            write(usage);
+            return 0;
+        }
+        if (command === "check") {
+            const flags = rest.filter(arg => arg.startsWith("--"));
+            const paths = rest.filter(arg => !arg.startsWith("--"));
+            if (paths.length > 1 || flags.some(flag => !["--yes", "--dry-run"].includes(flag)))
+                throw new Error(usage.trimEnd());
+            return await check(paths[0] ?? ".", { yes: flags.includes("--yes"), dryRun: flags.includes("--dry-run") }, commandContext(options));
+        }
+        if (command === "finding" && rest.length === 1 && !rest[0].startsWith("-"))
+            return await finding(rest[0], commandContext(options));
+        if (rest.length)
+            throw new Error(usage.trimEnd());
+        if (command === "balance")
+            return await balance(commandContext(options));
+        if (command === "login")
+            return await login(commandContext(options));
+        if (command === "logout")
+            return await logout(commandContext(options));
+        if (command === "mcp") {
+            await serveMcp(process.stdin, process.stdout, options);
+            return 0;
+        }
+        throw new Error(usage.trimEnd());
+    }
+    catch (error) {
+        write(errorText(error) + "\n");
+        return errorCode(error);
+    }
+}
+const invokedPath = process.argv[1] ? await realpath(process.argv[1]).catch(() => "") : "";
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
+    process.exitCode = await run(process.argv.slice(2));
+}

package/dist/mcp.js

@@ -0,0 +1,157 @@
+import { createInterface } from "node:readline";
+import { once } from "node:events";
+import { resolve } from "node:path";
+import { errorCode, errorText } from "./api.js";
+import { commandContext } from "./context.js";
+import { confirmPrepared, prepareCheck } from "./commands/check.js";
+import { finding } from "./commands/finding.js";
+import { balance } from "./commands/balance.js";
+const tools = [
+    {
+        name: "check_agent",
+        description: "Preview the files and price of an agent check. Show the user the price and get their agreement "
+            + "before calling with confirm: true. A confirmation uses the most recent preview for that path in this session. "
+            + "Suggest a check after edits; wait for the user to ask for it. If the tool call is cancelled or times out, "
+            + "a confirmed check keeps running on the server and its result will be in the console's Checks page.",
+        inputSchema: { type: "object", properties: { path: { type: "string", description: "The agent folder on this computer." }, confirm: { type: "boolean", default: false } }, required: ["path"], additionalProperties: false },
+    },
+    { name: "get_finding", description: "Get a finding's explanation, quoted lines and suggested fixes.", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false } },
+    { name: "get_balance", description: "Get the balance and top-up link.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+];
+class ProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function object(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+export async function serveMcp(input, output, options = {}) {
+    const previews = new Map();
+    const requests = new Map();
+    let queue = Promise.resolve();
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    async function toolCall(params, signal) {
+        if (!object(params) || typeof params.name !== "string")
+            throw new ProtocolError(-32602, "Choose a tool and its arguments.");
+        const args = params.arguments ?? {};
+        if (!object(args))
+            throw new ProtocolError(-32602, "Tool arguments must be an object.");
+        const name = params.name;
+        const allowed = name === "check_agent" ? ["path", "confirm"] : name === "get_finding" ? ["id"] : [];
+        if (!tools.some(tool => tool.name === name) || Object.keys(args).some(key => !allowed.includes(key)))
+            throw new ProtocolError(-32602, "Unknown tool or argument.");
+        if (name === "check_agent" && (typeof args.path !== "string" || !args.path.trim() || (args.confirm !== undefined && typeof args.confirm !== "boolean")))
+            throw new ProtocolError(-32602, "Provide a path and an optional boolean confirmation.");
+        if (name === "get_finding" && (typeof args.id !== "string" || !args.id.trim()))
+            throw new ProtocolError(-32602, "Provide a finding id.");
+        let text = "", exitCode = 0;
+        let findingIds;
+        try {
+            const ctx = commandContext({ ...options, signal, write: chunk => {
+                    // Progress is transient terminal text; only the final lines belong in a tool response.
+                    if (!chunk.startsWith("\r"))
+                        text += chunk;
+                } });
+            if (name === "get_finding")
+                await finding(args.id, ctx);
+            else if (name === "get_balance")
+                await balance(ctx);
+            else {
+                const path = resolve(args.path);
+                if (args.confirm === true) {
+                    const prepared = previews.get(path);
+                    previews.delete(path);
+                    if (!prepared)
+                        throw new Error("Get a preview first. Show the user the price and get their agreement before confirming.");
+                    findingIds = (await confirmPrepared(prepared, ctx)).findingIds;
+                }
+                else {
+                    previews.delete(path);
+                    previews.set(path, await prepareCheck(args.path, ctx));
+                }
+            }
+        }
+        catch (error) {
+            text += errorText(error) + "\n";
+            exitCode = errorCode(error);
+        }
+        // Some clients (Claude Code among them) give the model only the structured result when one is present, so it
+        // repeats the text: without it the model sees no files, price or results.
+        return { content: [{ type: "text", text }], isError: exitCode !== 0,
+            structuredContent: { text, exitCode, ...(findingIds ? { findingIds } : {}) } };
+    }
+    async function respond(message, id, signal) {
+        if (signal.aborted)
+            return;
+        let reply;
+        try {
+            let result;
+            if (message.method === "initialize") {
+                const requested = object(message.params) ? message.params.protocolVersion : undefined;
+                result = { protocolVersion: ["2024-11-05", "2025-03-26", "2025-06-18"].includes(requested) ? requested : "2025-06-18",
+                    capabilities: { tools: {} }, serverInfo: { name: "counterfact-labs", version: "0.1.1" } };
+            }
+            else if (message.method === "ping")
+                result = {};
+            else if (message.method === "tools/list")
+                result = { tools };
+            else if (message.method === "tools/call")
+                result = await toolCall(message.params, signal);
+            else
+                throw new ProtocolError(-32601, "Method not found.");
+            reply = { jsonrpc: "2.0", id, result };
+        }
+        catch (error) {
+            reply = errorReply(id, error);
+        }
+        // The caller stopped waiting; a late result must not look like a completed call.
+        if (!signal.aborted && !output.write(JSON.stringify(reply) + "\n"))
+            await once(output, "drain");
+    }
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        let id = null;
+        let reply;
+        try {
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                throw new ProtocolError(-32700, "Invalid JSON.");
+            }
+            if (!object(message) || message.jsonrpc !== "2.0" || typeof message.method !== "string"
+                || (message.id !== undefined && typeof message.id !== "string" && typeof message.id !== "number" && message.id !== null))
+                throw new ProtocolError(-32600, "Invalid request.");
+            if (message.id === undefined) {
+                if (message.method === "notifications/cancelled" && object(message.params)) {
+                    const requestId = message.params.requestId;
+                    if (typeof requestId === "string" || typeof requestId === "number")
+                        requests.get(requestId)?.abort();
+                }
+                continue;
+            }
+            id = message.id;
+            const controller = new AbortController();
+            requests.set(id, controller);
+            // Keep preview and confirm in order while still reading cancellation notifications.
+            const request = message;
+            queue = queue.then(() => respond(request, id, controller.signal)).finally(() => { requests.delete(id); });
+            continue;
+        }
+        catch (error) {
+            reply = errorReply(id, error);
+        }
+        if (!output.write(JSON.stringify(reply) + "\n"))
+            await once(output, "drain");
+    }
+    await queue;
+}
+function errorReply(id, error) {
+    return { jsonrpc: "2.0", id, error: {
+            code: error instanceof ProtocolError ? error.code : -32603,
+            message: error instanceof ProtocolError ? error.message : "The request could not be completed.",
+        } };
+}

package/dist/output.js

@@ -0,0 +1,23 @@
+export function money(micro) {
+    const cents = Math.round(micro / 10_000);
+    const whole = Math.trunc(cents / 100);
+    const fraction = Math.abs(cents % 100);
+    return `${cents < 0 ? "-" : ""}$${Math.abs(whole)}${fraction ? `.${String(fraction).padStart(2, "0")}` : ""}`;
+}
+export function fileText(path, files) {
+    const bytes = files.reduce((sum, file) => sum + file.size, 0);
+    const names = files.slice(0, 3).map(file => file.path).join(", ");
+    const more = files.length > 3 ? `, ... ${files.length - 3} more` : "";
+    return `Checking the agent in ${path} (${files.length} files, ${Math.ceil(bytes / 1000)} KB):\n  ${names}${more}\n`;
+}
+export function quoteText(quote) {
+    if (quote.band === null)
+        return quote.message + "\n";
+    if (quote.free)
+        return "This check is free (your first one).\n";
+    return `${quote.message ? quote.message + "\n" : ""}This check costs ${money(quote.priceMicro)} (${quote.band} agent).${quote.balanceMicro === null ? "" : ` Balance: ${money(quote.balanceMicro)}.`}\n`;
+}
+export function tasteText(taste, findingIds) {
+    return [taste.headline, ...taste.lines.map(line => `  ${line}`),
+        ...(findingIds.length ? [`Finding ids: ${findingIds.join(", ")}`] : []), `Full results: ${taste.url}`, ""].join("\n");
+}

package/dist/secret-files.js

@@ -0,0 +1,2 @@
+// Copied from src/lib/conventions/file-patterns.ts by the build.
+export const SECRET_FILE_RE = /(^|\/)(\.env(?:\.[^/]*)?|\.(?:npmrc|pypirc|netrc)|(?:credentials|secrets)\.(?:json|ya?ml)|secrets\.toml|[^/]+-credentials\.json|service-account[^/]*\.json|id_(?:rsa|dsa|ecdsa|ed25519)|[^/]+\.(?:pem|key|p12|pfx))$/i;

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@counterfact-labs/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "UNLICENSED",
+  "description": "Check an agent from your terminal or coding agent",
+  "type": "module",
+  "bin": { "counterfact-labs": "dist/main.js" },
+  "engines": { "node": ">=20" },
+  "files": ["dist", "!dist/**/*.test.js", "!dist/test-helpers.js"],
+  "scripts": {
+    "prebuild": "node scripts/copy-api-types.mjs",
+    "build": "node scripts/build.mjs",
+    "test": "npm run build && node --test dist/*.test.js dist/commands/*.test.js",
+    "prepack": "npm run build"
+  }
+}