# vera-ccc-tools

## Purpose
Expose CocoIndex Code (`ccc`) as native Pi/Vera tools so semantic code search and index management are available without going through raw bash.

## Registered tools
- `ccc_search` — semantic code search via `ccc search`
- `ccc_index` — build or refresh the project index via `ccc index`
- `ccc_init` — initialize the current project for CocoIndex Code via `ccc init`
- `ccc_doctor` — run CocoIndex diagnostics via `ccc doctor`

Project index status (`ccc status`) is not a tool. It is surfaced as an always-on `ccc-status` segment at the end of the system prompt, refreshed once per user turn.

## Design notes
- Uses the installed `ccc` executable from `PATH`
- Executes commands in the current project `cwd`
- Returns truncated text output suitable for the model context
- Keeps semantic search as a first-class tool while leaving exact file lookup to `fd` / `rg` / `read`
- Forces UTF-8 on spawned `ccc` processes (`PYTHONIOENCODING`/`PYTHONUTF8`) so non-ASCII index content is not mangled when captured on Windows

## Gitignore sync
Index exclusion is kept aligned with the project's effective `.gitignore`, because `ccc`'s own gitignore matcher is unreliable on Windows. `git` is the source of truth: `git ls-files -o -i --exclude-standard --directory -z` yields the ignored set (platform-uniform forward-slash paths), which is converted to `**/<path>/**` globs and merged into `.cocoindex_code/settings.yml` `exclude_patterns`.

- Sync runs before `ccc_search` (when `refresh_index` is on — the default), at the start of `ccc_index`, and after a foreground `ccc_init`. `ccc_search` is the hot path, so newly-ignored files drop out of results on the next search rather than waiting for an explicit re-index.
- Idempotent: a sidecar (`.cocoindex_code/.vera-gitignore-sync.json`) tracks the patterns this tool injected. Each sync reconciles only that set, preserving `ccc` defaults and any user-added patterns. No disk write when the ignored set is unchanged.
- Fallback: a non-git directory, missing `git`, or an empty ignored set leaves `exclude_patterns` at `ccc`'s defaults.
- Cost: one `git ls-files` call (~tens of ms) per refreshing search.

Implemented in `src/gitignore-sync.ts`.

## Non-goals
- replacing `rg` / `fd` for exact text or path lookup
- destructive reset / daemon stop controls
- direct MCP transport management

## External dependencies
- `ccc` installed and available on `PATH`
- CocoIndex daemon health for index/search operations
- initialized project for `ccc_search` unless `ccc_index` or `ccc_init` has been run
- `git` (optional) — enables gitignore sync; when absent, exclusion falls back to `ccc` defaults

## Smoke
- `npm run smoke`
- from project root: `node packages/vera-ccc-tools/scripts/smoke.mjs`

Loaded through `agent/settings.json` as `./packages/vera-ccc-tools`.