core

Overview ¶

Package core — atomic.go: shared file-mutation primitives for Edit and Write. These helpers guarantee no partial-write artifacts on crash and give us a single place to add safety polish (line-ending preservation, BOM handling) consistently across both tools.

Per ADR-007 we do not use a third-party "atomic write" library — Go's stdlib (`os.WriteFile` + `os.Rename`) is enough when used correctly. The platform invariant we rely on: rename(2) on the same filesystem is atomic, so writers never see a half-written file at the target path.

Package core implements clawtool's canonical core tools per ADR-005.

Quality bar reminder: each core tool must measurably beat the corresponding native built-in across the major agents. For Bash:

• timeout-safe: output is captured even when the process is killed
• predictable cwd: defaults to $HOME, never the daemon's cwd
• structured result: stdout/stderr/exit_code/duration_ms/timed_out returned as JSON even on timeout

v0.1 implements timeout-safe + structured result + cwd. Secret redaction and per-session command history land in v0.2.

Package core — Edit performs a precise search-and-replace on an existing file with safety polish:

• uniqueness check by default (refuses ambiguous edits)
• atomic temp+rename so a crash never leaves a half-written file
• line-ending preserve (LF / CRLF / CR detected from current content)
• BOM preserve
• binary refusal (symmetric with Read)

Per ADR-007 we wrap stdlib `os` for I/O and add our own polish layer. The search-and-replace shape mirrors what Claude Code's native Edit uses today (old_string / new_string / replace_all) — agents that learnt that interface get the same affordances against clawtool's stronger invariants.

Package core — Glob is the canonical wrapper around bmatcuk/doublestar.

Per ADR-007 we don't write a glob engine. doublestar is the de-facto double-star (`**`) glob library in Go, used by GoReleaser, k6, etc. This file's value is the polish layer: cwd-aware path resolution, uniform structured output, hard cap to protect agent context, and platform-stable separators (the wrapper always returns forward-slash paths regardless of OS — agents expect that).

Package core — Grep wraps ripgrep when present, falls back to system grep.

Per ADR-007 we curate ripgrep as the default engine: it has the correct .gitignore semantics, --type aliases, fast Aho-Corasick matching, and a stable JSON output that is straightforward to parse. The fallback is system grep (-rn) so clawtool's Grep is never unavailable.

Output is uniform across engines so the agent never has to know which one ran. The `engine` field in the result lets users / tests verify.

Package core — Read returns file content with stable line cursors, deterministic line counts, and per-format dispatch.

Per ADR-007 we wrap mature engines instead of writing parsers:

• text → stdlib bufio (line-walked, single-pass)
• pdf → pdftotext (poppler-utils) shell-out
• ipynb → native JSON cell parse
• docx → pandoc shell-out (universal office converter)
• xlsx → github.com/xuri/excelize/v2 (Microsoft/Alibaba/Oracle in prod)
• csv / tsv → stdlib encoding/csv (header + bounded preview)
• html → github.com/go-shiori/go-readability (Mozilla Readability port)
• json / yaml / toml / xml → text passthrough with format tag
• binary → refused with structured error

Adding a new format means: extend detectFormat, add a reader function, update CoreToolDocs's description, ship tests for the format. The readResult shape stays uniform so the agent never has to branch on which engine ran.

Package core — ToolSearch is the discovery primitive that makes a 50+ tool catalog usable per ADR-005. The agent calls ToolSearch with a natural-language query, gets ranked candidates, then binds to the right tool with its full schema via the regular tools/list output.

Package core — WebFetch retrieves a URL and renders the body in the best shape for an AI agent: clean article text for HTML, raw text for plain-text MIME types, structured rejection for binaries.

Per ADR-007 we wrap two mature engines:

• net/http stdlib client for transport (proxy, TLS, redirect handling are all stock — battle-tested across Go's user base);
• github.com/go-shiori/go-readability for HTML extraction (Mozilla Readability port, the same algorithm Firefox Reader View ships).

What clawtool adds: agent-friendly polish — a hard body cap so a runaway page can't blow context, structured result with content-type-aware `format`, citation metadata (final URL after redirects, fetched_at).

Package core — WebSearch is a pluggable web-search primitive. clawtool itself does no crawling or ranking; it adapts whichever search backend the user has configured (Brave today; Tavily / SearXNG planned) into a uniform `{results, backend, …}` shape.

Per ADR-007 we wrap, never reinvent. The backend interface is small on purpose so adding a new provider is one file (see websearch_brave.go for the canonical example).

Package core — Write creates or overwrites a whole file with given content. Sister tool to Edit; the boundary is intentional:

• Edit modifies a substring of an existing file. Refuses if the file is missing.
• Write replaces or creates the whole file. If the file already exists and has detectable line endings, those endings are preserved by default so existing tooling (CR LF on Windows, etc.) keeps working.

Per ADR-007 we wrap stdlib `os` for I/O. The polish layer is the same atomic-write primitive Edit uses, plus a parent-directory auto-create so agents don't need a separate `mkdir` step before writing.