Skip to content

feat: contexting status --json for machine-readable project state #1

Description

@ktappdev

Problem

External tools (LLM agents, editor extensions, CI scripts) need to discover contexting's file paths and health state for a project. Currently they either:

  • Hardcode paths like .ctx/ctx_index.json — breaks when config customizes them
  • Shell out to contexting doctor --json — overloaded with health checks, noisy
  • Parse .ctx/ctx_config.toml directly — fragile, format may change

The other approach (hardcoding wrong paths like .contexting_runtime.json and context.json) already caused bugs in downstream tools.

Proposed Solution

Add contexting status --json that returns a focused machine-readable object:

{
  "project_root": "/path/to/project",
  "config_path": ".ctx/ctx_config.toml",
  "index_path": ".ctx/ctx_index.json",
  "cache_path": ".ctx/ctx_cache.json",
  "runtime_path": ".ctx/ctx_runtime.json",
  "index_exists": true,
  "index_generated_at": "2026-06-16T10:00:00Z",
  "cache_entries": 42,
  "watch_running": true,
  "watch_pid": 12345,
  "watch_address": "127.0.0.1:54321"
}

Implementation Notes

  • Reuse resolveConfigPath for path resolution (same as search-hints/eval)
  • Check runtime file existence + PID liveness for watch_running
  • ContextIndex.GeneratedAt already exists in .ctx/ctx_index.json
  • Cache entry count from len(LoadSynonymCache(...))
  • Skip config prompt in PersistentPreRunE (add "status" to skip list)

Acceptance Criteria

  • contexting status --json returns valid JSON with all fields above
  • Paths respect --config flag and config file values
  • watch_running is true only if runtime file exists AND PID is alive
  • Works from any subdirectory (resolves config path to absolute)
  • No config prompt when config doesn't exist

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions