pkg/

directory
v0.17.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2026 License: MIT

README

pkg/

Internal packages for the Confab CLI. Each package has its own README with extension guides, invariants, and design decisions.

Package Index

Package Purpose Change this when...
backendtest Test helper for mock backends: reads zstd-compressed request bodies Changing how mock backends decode requests
codextest Reusable Codex SQLite + sessions-tree fixture for tests Adding new fixture builders for cross-package Codex tests
opencodetest Reusable OpenCode SQLite fixture for tests (real schema, programmatic seeding, no vendored DB) Adding new fixture shapes for cross-package OpenCode tests
confabpath ~/.confab path-builder helpers (Dir, Subpath) Adding new top-level confab state files
pathcanon CanonicalDir — directory-path canonicalization (the per-(provider, dir) binding match contract) Changing how config dirs are compared/canonicalized
config Confab config (API key, redaction, settings.json read/write) + per-(provider, dir) backend bindings Adding config fields, changing settings.json plumbing, binding storage
daemon Background sync daemon lifecycle Changing sync behavior, shutdown logic
git Git repo info extraction Adding new git fields to sync
hookconfig Per-provider hook install/uninstall (Claude settings.json, Codex config.toml, Cursor hooks.json) Adding new hook event types, changing hook command shape
http HTTP client with compression + retries Adding error types, changing retry logic
logger Singleton file logger with rotation Changing log format, adding levels
loginit Startup-time wiring of config → logger level (avoids config↔logger import cycle) Adding new config-driven logger options
provider Provider interface + Claude Code / Codex / OpenCode / Cursor implementations: paths, hooks, parent-PID, root walk, hook payloads, session discovery (scan/find), metadata extraction, agent-ID parsing, OpenCode SQLite collector Adding a new provider or changing tool-specific behavior
redactor JSON-aware sensitive data redaction Adding pattern types (patterns themselves live in config)
sync Sync engine, API client, file tracking Adding API endpoints, changing chunking
types Shared type definitions Adding cross-package types
utils Small shared utilities and constants Rarely — prefer package-local helpers

Dependency Map

cmd/  (uses all packages)
 │
 ├── daemon ──── sync ──┬── http ──── config, logger
 │                      ├── redactor ── config
 │                      ├── provider ──┬── hookconfig ── config, logger
 │                      │              └── config, pathcanon, types, logger
 │                      ├── git ── types
 │                      └── config ── pathcanon, logger
 │
 ├── config
 ├── provider
 ├── hookconfig
 ├── sync
 ├── http
 ├── redactor
 ├── git
 └── logger

Test-only:
  backendtest  (used by sync, daemon, cmd test files)
  codextest    (used by provider, sync, daemon, cmd test files)
  opencodetest (used by provider, sync, daemon, cmd test files)

Leaf packages (no confab dependencies):
  types, utils, confabpath, pathcanon
  git (uses types only)
  logger (uses confabpath only)
  loginit (uses config + logger to break a cycle at startup)

Data Flow

Claude Code / Codex / Cursor writes transcript; OpenCode writes to its SQLite DB
        │
        ▼
  ~/.claude/projects/<path>/<session-id>.jsonl   (Claude Code)
  ~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonl   (Codex)
  ~/.cursor/projects/<workspace>/agent-transcripts/<id>/<id>.jsonl   (Cursor)
  ~/.local/share/opencode/opencode.db → daemon's collector materializes
      ~/.confab/opencode/<id>/messages.jsonl   (OpenCode)
        │
        ▼
  daemon (pkg/daemon) watches file
        │
        ▼
  tracker (pkg/sync) reads new lines, seeks by byte offset
        │
        ▼
  provider (pkg/provider) extracts agent IDs + metadata
  (Claude agent-IDs from transcript content; Codex uses SQLite tree)
        │
        ▼
  redactor (pkg/redactor) redacts sensitive data
        │
        ▼
  client (pkg/sync) uploads chunk via HTTP
        │
        ▼
  http (pkg/http) compresses with zstd, sends to backend

Layering Rules

  • types, utils, confabpath, pathcanon are leaf packages — no confab imports; git imports only types. Any package can depend on them.
  • logger depends only on confabpath (for the default log dir) and is otherwise leaf-like. pkg/config already depends on pkg/logger, so pkg/logger must NOT import pkg/config — startup wiring that needs both lives in pkg/loginit instead.
  • logger is accessed as a singleton — no need to pass it around.
  • Mid-level packages (config, http, redactor, provider) depend on leaves and each other but not on daemon or sync.
  • sync depends on mid-level packages. daemon depends on sync.
  • cmd/ depends on everything. It's the only package that imports daemon.
  • Dependencies flow downward only. If you need to add an upward dependency, you have a design problem — use an interface or move the shared type to types.

Directories

Path Synopsis
Package backendtest provides shared helpers for tests that stand up a mock Confab backend with net/http/httptest.
 Package backendtest provides shared helpers for tests that stand up a mock Confab backend with net/http/httptest.
Package codextest provides a reusable Codex SQLite + rollout-files fixture builder for tests across the codebase (pkg/provider, pkg/sync, pkg/daemon, cmd).
 Package codextest provides a reusable Codex SQLite + rollout-files fixture builder for tests across the codebase (pkg/provider, pkg/sync, pkg/daemon, cmd).
Package confabpath builds paths under the user's ~/.confab directory, where all confab local state (config, sync state, inboxes, logs, update timestamps) lives.
 Package confabpath builds paths under the user's ~/.confab directory, where all confab local state (config, sync state, inboxes, logs, update timestamps) lives.
ABOUTME: Manages the /retro bundled skill — install and uninstall.
 ABOUTME: Manages the /retro bundled skill — install and uninstall.
Package hookconfig owns the install/uninstall/check logic for Confab hooks in Claude Code's settings.json, Codex's config.toml, and Cursor's hooks.json.
 Package hookconfig owns the install/uninstall/check logic for Confab hooks in Claude Code's settings.json, Codex's config.toml, and Cursor's hooks.json.
Package loginit wires the logger up to user configuration at process startup.
 Package loginit wires the logger up to user configuration at process startup.
Package opencodetest builds OpenCode-shaped SQLite fixture databases for tests that exercise the OpenCode SQLite reader and downstream collector.
 Package opencodetest builds OpenCode-shaped SQLite fixture databases for tests that exercise the OpenCode SQLite reader and downstream collector.
Package pathcanon canonicalizes filesystem directory paths so that two different spellings of the same directory compare equal.
 Package pathcanon canonicalizes filesystem directory paths so that two different spellings of the same directory compare equal.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.