@popoverai/dotrequirements 0.22.0 → 0.24.0

package/README.md

@@ -155,23 +155,66 @@ dotreq push .requirements/auth.requirements.md
 dotreq push --yes  # Skip confirmation
 ```
 
-### `dotreq test`
+### `dotreq validate`
 
 Validate requirements files against the schema.
 
 ```bash
-dotreq test
-dotreq test --file .requirements/auth.requirements.md
+dotreq validate
+dotreq validate --file .requirements/auth.requirements.md
 ```
 
-### `dotreq browsertest`
+### `dotreq search`
+
+Search requirements by text or regex across every `.requirements.md` file. Searches IDs, content, and labels.
+
+```bash
+dotreq search "login"
+dotreq search "AUTH-.*" --regex
+```
+
+### `dotreq get`
+
+Print a requirement (or subtree) by ID, with test references and source locations. Accepts both numeric paths (`AUTH-LOGIN-1.0.1`) and label paths (`AUTH-LOGIN-1.given.and`).
+
+```bash
+dotreq get AUTH-LOGIN-1
+dotreq get AUTH-LOGIN-1.0
+```
+
+### `dotreq list`
+
+Summarize requirements in the project. Without flags, lists every root with its child count. With `--untested`, filters to roots with no `requirement()` references in any test.
+
+```bash
+dotreq list
+dotreq list --untested
+```
+
+### `dotreq requirements-for`
+
+Show which requirements a test file references, with the line where each `requirement()` call lives.
+
+```bash
+dotreq requirements-for src/auth.test.ts
+```
+
+### `dotreq tests-for`
+
+Show which tests reference each requirement in a `.requirements.md` file. The inverse of `requirements-for`.
+
+```bash
+dotreq tests-for .requirements/auth.requirements.md
+```
+
+### `dotreq acceptance-test`
 
 Run browser-based acceptance tests against requirements. Uses AI-powered browser automation to verify that your application behaves as specified.
 
 ```bash
-dotreq browsertest LOGIN-1
-dotreq browsertest LOGIN-1 https://example.com
-dotreq browsertest LOGIN-1 --json
+dotreq acceptance-test LOGIN-1
+dotreq acceptance-test LOGIN-1 https://example.com
+dotreq acceptance-test LOGIN-1 --json
 ```
 
 **Options:**
@@ -182,35 +225,140 @@ dotreq browsertest LOGIN-1 --json
 
 **Configuration required:**
 
-Browser testing requires credentials in `project-settings.json`:
+Browser testing needs a Stagehand model and the API key for that model's provider in `project-settings.json`:
 
 ```json
 {
   "defaultURL": "https://your-app.com",
   "browserTest": {
-    "geminiApiKey": "your-gemini-api-key"
+    "modelName": "gateway/anthropic/claude-haiku-4-5",
+    "modelApiKey": "your-api-key"
   }
 }
 ```
 
-Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjectId`.
+Pick any Stagehand-supported model. Example values: `gateway/anthropic/claude-haiku-4-5` (Vercel AI Gateway key), `google/gemini-3-flash-preview` (Gemini key).
 
-### `dotreq mcp-setup`
+Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjectId`. Setting both Browserbase fields switches runs from LOCAL (spawns Playwright on your machine) to BROWSERBASE (managed cloud browsers).
+
+### `dotreq cts` *(Alpha)*
+
+Generate behavioral requirements from an existing codebase. Packs the codebase, plans a behavioral outline, fans out per-area specifier agents to draft per-area requirements, runs a dual review loop, and writes the result to `.requirements/`.
+
+```bash
+dotreq cts run --scope src                 # full pipeline end-to-end
+dotreq cts run --scope src --fresh         # discard cache and start over
+dotreq cts skill-install                   # install the conversational skill wrapper
+```
+
+`cts` shells out to `claude -p` and uses whatever auth mode you've configured for Claude Code. Each pipeline stage is also runnable on its own (`dotreq cts pack`, `plan-loop`, `fan-out`, `compose`, `edit-loop`, `present`) for partial re-runs and debugging.
+
+> **Alpha:** output quality is prompt-sensitive and varies by codebase. See the [Codebase to Spec docs](https://dotrequirements.io/tools/cli/codebase-to-spec) for prerequisites, options, exit codes, and known rough edges. Feedback to support@popover.ca welcome.
+
+> **Heads up:** as of June 15, 2026, `claude -p` bills against your Claude subscription's API credit instead of the subscription seat (per Anthropic's May 13, 2026 announcement). `cts` runs will draw from that credit.
+
+### `dotreq ai-setup`
 
 Configure the MCP server for AI assistants (Claude Code, Cursor, etc.).
 
 ```bash
-dotreq mcp-setup
+dotreq ai-setup
 ```
 
 ### `dotreq mcp`
 
-Start the MCP server manually (typically not needed—AI assistants start it automatically after `mcp-setup`).
+Start the MCP server manually (typically not needed—AI assistants start it automatically after `ai-setup`).
 
 ```bash
 dotreq mcp
 ```
 
+### `dotreq harness prepare`
+
+Parse requirements and build a lookup cache for multi-language test tracking. Run before tests in non-JavaScript projects. JavaScript projects don't need this — the test harness calls `prepare()` automatically.
+
+```bash
+dotreq harness prepare
+dotreq harness prepare --quiet
+```
+
+### `dotreq harness finalize`
+
+Aggregate test tracking data and print a coverage report. Run after tests in non-JavaScript projects.
+
+```bash
+dotreq harness finalize
+dotreq harness finalize --push
+dotreq harness finalize --push --context pytest
+```
+
+| Option | Description |
+|--------|-------------|
+| `--push` | Push coverage to dot•requirements cloud |
+| `--quiet` | Output only coverage percentage (for scripting) |
+| `--context <label>` | Attribution label identifying the reporter (e.g. `pytest`, `Jest`) |
+
+### `dotreq report`
+
+View coverage from the most recent local test run, or from the cloud-persisted record.
+
+```bash
+dotreq report                                       # local cache (default)
+dotreq report --source cloud                        # cloud-persisted record
+dotreq report --source cloud --branch main          # filter to a branch
+dotreq report --source cloud --since 1700000000000  # filter to records after a timestamp
+dotreq report --requirement AUTH-LOGIN              # scope to one requirement
+dotreq report --format json
+```
+
+| Option | Description |
+|--------|-------------|
+| `--source <source>` | Where to read coverage from: `local` (default) or `cloud` |
+| `--format <format>` | Output format: `console` (default), `json`, `markdown` |
+| `--requirement <id>` | Filter to a specific requirement (and its children for local source) |
+| `--branch <name>` | Cloud-only: filter coverage to a specific git branch |
+| `--since <timestamp>` | Cloud-only: only show coverage recorded after this Unix-ms timestamp |
+
+`--branch` and `--since` only apply with `--source cloud`; using them with the local source errors out. Cloud queries require running `dotreq link` first.
+
+### `dotreq style-check`
+
+Get AI feedback on a requirements file or a test file. Works on both `*.requirements.md` files (catches vagueness, missing preconditions, untestable assertions) and test files (checks semantic alignment with referenced requirements).
+
+```bash
+dotreq style-check .requirements/auth.requirements.md
+dotreq style-check src/auth.test.ts
+dotreq style-check .requirements/auth.requirements.md --keys AUTH-LOGIN-1,AUTH-LOGIN-2
+```
+
+| Option | Description |
+|--------|-------------|
+| `--keys <list>` | Comma-separated requirement keys to limit the review (requirements files only) |
+| `--model <name>` | Override the AI model used for the review |
+
+When `.requirements/STYLE.md` exists in your project, its contents are included in the AI's prompt so project-specific style preferences influence the feedback. Requires cloud authentication.
+
+### `dotreq review-test`
+
+AI-powered semantic review of a test file against its referenced requirements. Validates that test setup matches GIVEN conditions, actions match WHEN triggers, and assertions match THEN outcomes.
+
+```bash
+dotreq review-test src/auth.test.ts
+```
+
+Catches tests that reference a requirement but don't actually validate what the requirement specifies — especially valuable when AI assistants write tests. Requires cloud authentication.
+
+### `dotreq create-requirement-document`
+
+Print a Markdown template demonstrating the requirements file format, with format guidance and style examples. Use it to seed a new `.requirements.md` file or to prime an AI assistant's context before authoring.
+
+```bash
+dotreq create-requirement-document
+dotreq create-requirement-document .requirements/auth.requirements.md
+```
+
+When a file path is provided, the template references that filename. If `.requirements/STYLE.md` exists, its contents replace the bundled default style body in the output. The template is printed to stdout.
+
 ---
 
 ## What Works Locally
@@ -218,16 +366,18 @@ dotreq mcp
 The following features work fully offline—no account required:
 
 - Write requirements (`.requirements.md` files)
-- Validate requirements (`dotreq test`)
+- Validate requirements (`dotreq validate`)
+- Search and explore (`dotreq search`, `get`, `list`, `requirements-for`, `tests-for`)
 - Reference requirements in tests (`requirement()`)
-- Coverage reporting (console output)
-- MCP tools (search, validate, explore)
+- Local coverage reporting (`dotreq report`, default `--source local`)
+- Generate a requirements template (`dotreq create-requirement-document`)
+- MCP tools that mirror the offline CLI verbs
 
 The following features require a dot•requirements cloud account:
 
 - Sync requirements (`pull` / `push`)
-- Historical coverage tracking
-- AI-powered style checking
+- Cloud coverage queries (`dotreq report --source cloud`)
+- AI-powered style checking and test review (`dotreq style-check`, `dotreq review-test`)
 - Team collaboration
 
 To enable cloud features, run `dotreq link` to connect your project to the cloud.
@@ -471,7 +621,7 @@ AI assistants can read your requirements in context, draft new ones, and verify
 ### Setup
 
 ```bash
-dotreq mcp-setup
+dotreq ai-setup
 ```
 
 Follow the prompts to configure for your AI assistant (Claude Code, Cursor, etc.).
@@ -481,8 +631,7 @@ Follow the prompts to configure for your AI assistant (Claude Code, Cursor, etc.
 **Exploration:**
 - `search_requirements` — Search by text or regex
 - `get_requirement` — Get a requirement with its children and coverage
-- `list_all_requirements` — List all requirements in the project
-- `list_untested_requirements` — Find requirements without test coverage
+- `list_requirements` — List all requirements in the project (set `untested: true` to filter to coverage gaps)
 - `get_requirements_by_test` — Get requirements referenced by a test file
 - `get_tests_by_requirement` — Get tests that reference a requirement
 
@@ -492,10 +641,11 @@ Follow the prompts to configure for your AI assistant (Claude Code, Cursor, etc.
 - `style_check` — AI-powered style feedback on requirements (supports optional `requirementKeys` filter)
 - `review_test` — Comprehensive test review (style + semantic correctness)
 
+**Coverage:**
+- `report_coverage` — Coverage from local cache or cloud, with optional requirement / branch / since filters
+
 **Cloud:**
 - `push_requirements` — Push to dot•requirements cloud
-- `get_requirement_coverage` — Query coverage data
-- `get_project_coverage_summary` — Project-wide coverage stats
 
 **Diagnostic:**
 - `debug_mcp_environment` — Debug MCP server configuration

package/dist/cli.js

@@ -1,24 +1,33 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
-import { initCommand } from './commands/init.js';
-import { linkCommand } from './commands/link.js';
-import { pullCommand } from './commands/pull.js';
-import { pushCommand } from './commands/push.js';
-import { testCommand } from './commands/test.js';
-import { browserTestCommand } from './commands/browsertest.js';
-import { prepareCommand } from './commands/prepare.js';
-import { finalizeCommand } from './commands/finalize.js';
-import { reportCommand } from './commands/report.js';
-import { mcpCommand } from './commands/mcp.js';
-import { mcpSetupCommand } from './commands/mcp-setup.js';
-import { loadEnvFile } from './utils/env.js';
-import { readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { acceptanceTestCommand } from "./commands/acceptance-test.js";
+import { aiSetupCommand } from "./commands/ai-setup.js";
+import { registerCodebaseToSpec } from "./commands/codebase-to-spec/index.js";
+import { createRequirementDocumentCommand } from "./commands/create-requirement-document.js";
+import { finalizeCommand } from "./commands/finalize.js";
+import { getCommand } from "./commands/get.js";
+import { initCommand } from "./commands/init.js";
+import { linkCommand } from "./commands/link.js";
+import { listCommand } from "./commands/list.js";
+import { mcpCommand } from "./commands/mcp.js";
+import { prepareCommand } from "./commands/prepare.js";
+import { pullCommand } from "./commands/pull.js";
+import { pushCommand } from "./commands/push.js";
+import { reportCommand } from "./commands/report.js";
+import { requirementsForCommand } from "./commands/requirements-for.js";
+import { reviewTestCommand } from "./commands/review-test.js";
+import { searchCommand } from "./commands/search.js";
+import { styleCheckCommand } from "./commands/style-check.js";
+import { testsForCommand } from "./commands/tests-for.js";
+import { validateCommand } from "./commands/validate.js";
+import { loadEnvFile } from "./utils/env.js";
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
 const VERSION = packageJson.version;
 // Load environment variables from .env.local if it exists
 loadEnvFile();
@@ -44,67 +53,118 @@ function wrapCommand(fn) {
 }
 const program = new Command();
 program
-    .name('dotrequirements')
-    .description('Requirements tracking CLI with test harness and MCP server')
+    .name("dotrequirements")
+    .description("Requirements tracking CLI with test harness and MCP server")
     .version(VERSION);
 program
-    .command('init')
-    .description('Initialize a new dotrequirements project')
-    .option('-n, --name <name>', 'Project name (defaults to package.json name or directory name)')
-    .option('-i, --invite <token>', 'Join a team using an invite token')
+    .command("init")
+    .description("Initialize a new dotrequirements project")
+    .option("-n, --name <name>", "Project name (defaults to package.json name or directory name)")
+    .option("-i, --invite <token>", "Join a team using an invite token")
     .action(wrapCommand(initCommand));
 program
-    .command('link')
-    .description('Link local environment to an existing project')
+    .command("link")
+    .description("Link local environment to an existing project")
     .action(wrapCommand(linkCommand));
 program
-    .command('pull')
-    .description('Sync requirements from cloud to local .requirements/ files')
-    .option('-p, --project <id>', 'Project ID to sync')
-    .option('-d, --document <id>', 'Specific document ID to sync')
-    .option('-s, --share <token>', 'Read-only share token for quick onboarding (no setup required)')
+    .command("pull")
+    .description("Sync requirements from cloud to local .requirements/ files")
+    .option("-p, --project <id>", "Project ID to sync")
+    .option("-d, --document <id>", "Specific document ID to sync")
+    .option("-s, --share <token>", "Read-only share token for quick onboarding (no setup required)")
     .action(wrapCommand(pullCommand));
 program
-    .command('push [file]')
-    .description('Push local requirements from .requirements/ to cloud')
-    .option('-y, --yes', 'Skip confirmation prompt')
+    .command("push [file]")
+    .description("Push local requirements from .requirements/ to cloud")
+    .option("-y, --yes", "Skip confirmation prompt")
     .action(wrapCommand(pushCommand));
 program
-    .command('test')
-    .description('Validate requirements files in .requirements/')
-    .option('-f, --file <path>', 'Specific file to validate')
-    .action(wrapCommand(testCommand));
+    .command("validate")
+    .description("Validate requirements files in .requirements/")
+    .option("-f, --file <path>", "Specific file to validate")
+    .action(wrapCommand(validateCommand));
 program
-    .command('browsertest <requirement-key> [url]')
-    .description('Run browser-based acceptance test for a requirement')
-    .option('--json', 'Output results as JSON')
-    .option('--useAgent', 'Encourage Claude to use the Agent tool for multi-step tasks')
-    .action(wrapCommand(browserTestCommand));
-program
-    .command('prepare')
-    .description('Parse requirements and build lookup cache for multi-language test tracking')
-    .option('-q, --quiet', 'Suppress output (for scripting)')
+    .command("acceptance-test <requirement-key> [url]")
+    .description("Run browser-based acceptance test for a requirement")
+    .option("--json", "Output results as JSON")
+    .action(wrapCommand(acceptanceTestCommand));
+const harness = program
+    .command("harness")
+    .description("Test-harness lifecycle commands (prepare, finalize)");
+harness
+    .command("prepare")
+    .description("Parse requirements and build lookup cache for multi-language test tracking")
+    .option("-q, --quiet", "Suppress output (for scripting)")
     .action(wrapCommand(prepareCommand));
-program
-    .command('finalize')
-    .description('Aggregate test tracking data and generate coverage report')
-    .option('--push', 'Push coverage to DotRequirements Cloud')
-    .option('-q, --quiet', 'Output only coverage percentage (for scripting)')
-    .option('--context <label>', 'Attribution label identifying the reporter (e.g. "Vitest", "pytest")')
+harness
+    .command("finalize")
+    .description("Aggregate test tracking data and generate coverage report")
+    .option("--push", "Push coverage to DotRequirements Cloud")
+    .option("-q, --quiet", "Output only coverage percentage (for scripting)")
+    .option("--context <label>", 'Attribution label identifying the reporter (e.g. "Vitest", "pytest")')
     .action(wrapCommand(finalizeCommand));
 program
-    .command('report')
-    .description('Display coverage report from most recent test run')
-    .option('-f, --format <format>', 'Output format: console, json, markdown', 'console')
-    .option('-r, --requirement <id>', 'Filter to specific requirement and its children')
+    .command("report")
+    .description("Display coverage. Defaults to local (most recent test run on this machine); use --source cloud for the persisted record.")
+    .option("--source <source>", "Where to read coverage from: local | cloud", "local")
+    .option("-f, --format <format>", "Output format: console, json, markdown", "console")
+    .option("-r, --requirement <id>", "Filter to a specific requirement (and its children for local source)")
+    .option("--branch <name>", "Cloud-only: filter coverage to a specific git branch")
+    .option("--since <timestamp>", "Cloud-only: only show coverage recorded after this Unix-ms timestamp", (v) => {
+    const n = Number(v);
+    if (!Number.isFinite(n)) {
+        throw new Error(`--since must be a numeric Unix-ms timestamp (got "${v}")`);
+    }
+    return n;
+})
     .action(wrapCommand(reportCommand));
 program
-    .command('mcp')
-    .description('Start the MCP (Model Context Protocol) server for AI assistant integration')
+    .command("mcp")
+    .description("Start the MCP (Model Context Protocol) server for AI assistant integration")
     .action(wrapCommand(mcpCommand));
 program
-    .command('mcp-setup')
-    .description('Configure MCP server for your AI assistant (Claude Code, Claude Desktop, etc.)')
-    .action(wrapCommand(mcpSetupCommand));
+    .command("ai-setup")
+    .description("Configure MCP server for your AI assistant (Claude Code, Claude Desktop, etc.)")
+    .action(wrapCommand(aiSetupCommand));
+program
+    .command("search <query>")
+    .description("Search requirements by text or regex query")
+    .option("--regex", "Interpret query as a case-insensitive regular expression")
+    .action(wrapCommand(searchCommand));
+program
+    .command("get <id>")
+    .description("Print a requirement (or subtree) by ID, with test references and code")
+    .action(wrapCommand(getCommand));
+program
+    .command("list")
+    .description("Summarize every root requirement in the workspace")
+    .option("--untested", "Only show requirements with no requirement() references")
+    .action(wrapCommand(listCommand));
+program
+    .command("requirements-for <test-file>")
+    .description("Show every requirement() reference in a test file")
+    .action(wrapCommand(requirementsForCommand));
+program
+    .command("tests-for <requirements-file>")
+    .description("Show which requirements in a *.requirements.md file have test coverage")
+    .action(wrapCommand(testsForCommand));
+program
+    .command("style-check <file>")
+    .description("AI style review of a requirements or test file (requires cloud auth)")
+    .option("--keys <keys>", "Comma-separated requirement keys to limit the review (requirements files only)", (value) => value
+    .split(",")
+    .map((k) => k.trim())
+    .filter(Boolean))
+    .option("--model <name>", "Override the AI model used for the review")
+    .action(wrapCommand(styleCheckCommand));
+program
+    .command("review-test <test-file>")
+    .description("AI semantic review of a test file against its referenced requirements (requires cloud auth)")
+    .action(wrapCommand(reviewTestCommand));
+program
+    .command("create-requirement-document [file-path]")
+    .description("Print the project style guide; optional [file-path] annotates the output for that target")
+    .action(wrapCommand(createRequirementDocumentCommand));
+registerCodebaseToSpec(program);
 program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/codebase-to-spec/budget.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Working-context budget check for codebase-to-spec.
+ *
+ * After packing, we measure the compressed pack's token count. If it exceeds
+ * the working-context budget (the practical context-window ceiling for the
+ * planner and reviewer agents), the pipeline exits before any LLM-using stage
+ * runs.
+ *
+ * Requirements covered:
+ * - CTS-CLI-3: Pipeline refuses to spec a codebase that exceeds the working context budget
+ */
+/**
+ * Default budget in tokens for the compressed pack.
+ *
+ * Sized to leave generous headroom in a 1M-token context window for the
+ * planner's outline output, the reviewer's critique, and conversation overhead
+ * across review turns.
+ */
+export declare const DEFAULT_BUDGET_TOKENS = 600000;
+/**
+ * Estimate token count from a file size in bytes.
+ *
+ * We use a conservative estimate of 3.5 chars/token (typical for source code
+ * with some markdown overhead). This is deliberately approximate — the goal
+ * is to refuse the codebase BEFORE we pay the cost of an LLM-tokenizing pass.
+ * For exact counts, use `countTokens` on the file content.
+ */
+export declare function estimateTokensFromBytes(bytes: number): number;
+/**
+ * Count tokens in a file using the same conservative estimate.
+ * If the file does not exist, returns 0.
+ */
+export declare function countTokensInFile(path: string): number;
+/**
+ * Read the file (UTF-8) and count tokens from its actual character length.
+ * More accurate than the size-based estimate for non-ASCII content.
+ */
+export declare function countTokensInFileExact(path: string): number;
+export interface BudgetCheckResult {
+    withinBudget: boolean;
+    measuredTokens: number;
+    budgetTokens: number;
+}
+export declare function checkBudget(measuredTokens: number, budgetTokens?: number): BudgetCheckResult;
+/**
+ * Format the budget-exceeded message for the user.
+ *
+ * Per CTS-CLI-3.2 (and its sub-criteria): the message states the codebase is
+ * too large for a single agent's context window, includes the measured token
+ * count and the configured budget, and suggests narrowing the scope path.
+ */
+export declare function formatBudgetExceededMessage(result: BudgetCheckResult): string;
+//# sourceMappingURL=budget.d.ts.map

package/dist/codebase-to-spec/budget.js

@@ -0,0 +1,80 @@
+/**
+ * Working-context budget check for codebase-to-spec.
+ *
+ * After packing, we measure the compressed pack's token count. If it exceeds
+ * the working-context budget (the practical context-window ceiling for the
+ * planner and reviewer agents), the pipeline exits before any LLM-using stage
+ * runs.
+ *
+ * Requirements covered:
+ * - CTS-CLI-3: Pipeline refuses to spec a codebase that exceeds the working context budget
+ */
+import { readFileSync, statSync } from "node:fs";
+/**
+ * Default budget in tokens for the compressed pack.
+ *
+ * Sized to leave generous headroom in a 1M-token context window for the
+ * planner's outline output, the reviewer's critique, and conversation overhead
+ * across review turns.
+ */
+export const DEFAULT_BUDGET_TOKENS = 600_000;
+/**
+ * Estimate token count from a file size in bytes.
+ *
+ * We use a conservative estimate of 3.5 chars/token (typical for source code
+ * with some markdown overhead). This is deliberately approximate — the goal
+ * is to refuse the codebase BEFORE we pay the cost of an LLM-tokenizing pass.
+ * For exact counts, use `countTokens` on the file content.
+ */
+export function estimateTokensFromBytes(bytes) {
+    // 3.5 chars per token, 1 byte per char for ASCII-leaning code
+    return Math.ceil(bytes / 3.5);
+}
+/**
+ * Count tokens in a file using the same conservative estimate.
+ * If the file does not exist, returns 0.
+ */
+export function countTokensInFile(path) {
+    try {
+        const size = statSync(path).size;
+        return estimateTokensFromBytes(size);
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Read the file (UTF-8) and count tokens from its actual character length.
+ * More accurate than the size-based estimate for non-ASCII content.
+ */
+export function countTokensInFileExact(path) {
+    const content = readFileSync(path, "utf-8");
+    return Math.ceil(content.length / 3.5);
+}
+export function checkBudget(measuredTokens, budgetTokens = DEFAULT_BUDGET_TOKENS) {
+    return {
+        withinBudget: measuredTokens <= budgetTokens,
+        measuredTokens,
+        budgetTokens,
+    };
+}
+/**
+ * Format the budget-exceeded message for the user.
+ *
+ * Per CTS-CLI-3.2 (and its sub-criteria): the message states the codebase is
+ * too large for a single agent's context window, includes the measured token
+ * count and the configured budget, and suggests narrowing the scope path.
+ */
+export function formatBudgetExceededMessage(result) {
+    const measured = result.measuredTokens.toLocaleString();
+    const budget = result.budgetTokens.toLocaleString();
+    return [
+        `Your codebase is too large for a single agent's context window.`,
+        ``,
+        `  Compressed pack: ${measured} tokens`,
+        `  Working budget:  ${budget} tokens`,
+        ``,
+        `Try narrowing the scope with --scope <path> to focus on a specific package, module, or directory.`,
+    ].join("\n");
+}
+//# sourceMappingURL=budget.js.map