Fix zero value handling in CLI output and explicit file protocol configuration

[Copilot]

Two issues were preventing correct behavior in edge cases:

1. CLI zero value handling: Truthy checks treated 0 as absent, displaying "unknown size" and omitting repo count when cache was empty but successfully cleared
2. Git file protocol: Missing explicit protocol.file.allow=always caused Git 2.38.1+ to default to "user" mode, blocking non-interactive file:// clones from local cache

Changes

src/cli/index.ts: Replace truthy checks with explicit !== undefined

// Before: 0 treated as falsy
const sizeInMB = result.bytesFreed ? ... : "unknown size";
const repoLabel = result.repoCount ? ... : "";

// After: 0 displays correctly
const sizeInMB = result.bytesFreed !== undefined ? ... : "unknown size";
const repoLabel = result.repoCount !== undefined ? ... : "";

src/git/fetch-source.ts: Add explicit protocol configuration for both true and false cases

// Before: only set when false
if (!options?.allowFileProtocol) {
  configs.push("-c", "protocol.file.allow=never");
}

// After: explicit configuration in both cases
if (options?.allowFileProtocol) {
  configs.push("-c", "protocol.file.allow=always");
} else {
  configs.push("-c", "protocol.file.allow=never");
}

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Summary by CodeRabbit

Release Notes

• New Features

  • Added clean-cache CLI command to manage and clear global git cache with metrics reporting
  • Introduced configurable table-of-contents formats ("tree" and "compressed")
  • Added timeoutMs configuration option (default: 120 seconds)
  • Exposed cleanGitCache public API for cache management

• Documentation

  • Updated configuration documentation for new options and parameters

• Tests

  • Added comprehensive test coverage for clean-cache command and TOC format variations

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

📝 Walkthrough

Walkthrough

This PR adds a new CLI command to clear the global Git cache with metrics reporting, extends the TOC configuration to support "tree" and "compressed" formats with normalization logic, updates schemas and documentation, and includes comprehensive tests for all new features.

Changes

Cohort / File(s)	Summary
Cache cleanup feature src/clean-git-cache.ts, src/api.ts, src/cli/index.ts, src/cli/parse-args.ts, tests/clean-git-cache.test.js	Introduces cleanGitCache module with platform-aware cache directory resolution, recursive size calculation, and repository counting. Exports the new API and integrates a clean-cache CLI command that reports metrics or JSON output. Adds tests validating cache removal and missing cache scenarios.
TOC format enhancement src/config-schema.ts, src/config.ts, src/toc.ts, tests/sync-toc-formats.test.js, tests/sync-toc.test.js	Introduces TocFormat type ("tree" | "compressed") and extends configuration schemas to support both boolean and format-based TOC toggles. Adds tocFormat field across defaults and sources. Implements normalizeTocConfig to reconcile toc/tocFormat combinations for backward compatibility. Updates generateSourceToc to route rendering based on format, adding renderCompressedToc for compact Vercel-style output.
Schema and documentation updates docs.config.schema.json, README.md	Updates JSON schema to reflect new toc and tocFormat properties in defaults and sources. Adds documentation for timeoutMs default and explicit "(200 MB)" note for maxBytes.
Git fetch internals src/git/fetch-source.ts	Adds internal cache directory resolution, URL hashing, persistent cache usage, and enhanced git invocation logic to support caching of cloned repositories. No public API changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related PRs

• Remove TOC.md files when toc setting is disabled #11 — Modifies TOC generation and sync flow in src/toc.ts and related touch points, directly intersecting with this PR's TOC format enhancements.

Poem

🐰 A cache swept clean, formats dance in two—
Compressed or tree, the choice belongs to you!
With metrics in paw and docs arranged just right,
This rabbit-coded change makes syncing bright! 🌳✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and specifically describes the main change: updating the TOC (table of contents) format to match Vercel's AGENTS.md style, which is the central objective of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/fbosch/docs-cache@13

commit: db81975

[Copilot]

Pull request overview

This pull request adds a new tocFormat configuration option to control how TOC.md files are formatted, supporting two formats: "tree" (hierarchical directory structure) and "compressed" (flat file list). The default format is "compressed".

Changes:

• Added tocFormat configuration field accepting "tree" or "compressed" as values
• Implemented compressed TOC rendering that displays files in a flat list with full paths
• Updated configuration schema and types to support both the new tocFormat field and backward-compatible toc field (which can now be boolean or format string)
• Added comprehensive test coverage for both TOC formats and backward compatibility scenarios

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/sync-toc-formats.test.js	New comprehensive test suite covering default compressed format, explicit tree format, defaults inheritance, and backward compatibility with boolean and string toc values
src/toc.ts	Added renderCompressedToc function for flat file list rendering and updated generateSourceToc and writeToc to support format selection
src/config.ts	Added TocFormat type, updated interfaces to include both toc and tocFormat fields, implemented normalizeTocConfig for handling configuration normalization, and updated DEFAULT_CONFIG to use tocFormat: "compressed"
src/config-schema.ts	Added TocFormatSchema and updated Zod schemas to accept toc as union of boolean or format string, plus separate tocFormat field
docs.config.schema.json	Updated JSON schema to reflect new toc and tocFormat field definitions with appropriate types and enums

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fbosch]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/cli/index.ts`:
- Around line 247-252: The code currently treats zero values as absent because
it checks truthiness; update the checks for result.bytesFreed and
result.repoCount in the sizeInMB and repoLabel computations to explicitly handle
zero (use !== undefined or the nullish coalescing operator ??) so that
bytesFreed === 0 yields "0.00 MB" and repoCount === 0 produces " (0 cached
repositories)"; modify the expressions that set sizeInMB and repoLabel
(referencing sizeInMB, repoLabel, result.bytesFreed, result.repoCount)
accordingly.

In `@src/git/fetch-source.ts`:
- Around line 47-59: The configs array in fetch-source.ts currently only adds
"protocol.file.allow=never" when options?.allowFileProtocol is false, but when
options.allowFileProtocol is true you must explicitly set
"protocol.file.allow=always" to avoid Git 2.38.1+ defaulting to "user" (which
can block non-interactive file:// clones); update the logic around configs (the
configs variable and the conditional using options?.allowFileProtocol) to push
"-c", "protocol.file.allow=always" when allowFileProtocol is true and keep
pushing "-c", "protocol.file.allow=never" when it is false or undefined so local
cache clones succeed in non-interactive scenarios.

🧹 Nitpick comments (1)

src/git/fetch-source.ts (1)

15-41: Consider extracting shared cache-path helpers.

getCacheBaseDir, resolveGitCacheDir, and exists are duplicated in src/clean-git-cache.ts. A shared utility would reduce divergence risk as behavior evolves.