ct-view.json

{
  "name": "ct-view",
  "description": "Show one file's lines by range, or the regions around a pattern with context, instead of dumping the whole file. --range A:B (1-based inclusive; also A:, :B, A) prints a span; --match PATTERN prints the windows around matching lines with --context lines on each side (overlapping windows merge, like grep -C). Read-only, no allow-gate. With --json, emits {tool, path, total_lines, shown, lines:[{n,text}], matched?}. Exit status: 0 shown, 1 if --match matched nothing, 2 on a read or usage error. --match uses substring->glob->regex promotion, searched unanchored per line; --mode literal|glob|regex|auto states the interpretation (auto is the promotion rule, requested out loud). --match accepts payload schemes: file:PATH reads the pattern verbatim from a file (literal by default), text:VALUE escapes the prefix; a multi-line pattern matches as a line-anchored literal BLOCK (context expands around the whole matched region; a block with no match reports its nearest miss to stderr). --match is repeatable: several patterns are merged into one de-duplicated set of context windows in a single call, and --json reports each pattern's hit count in a `matches` array. Invoke as `ct view ...` or `ct-view ...`.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "The file to view (positional, required)."
      },
      "range": {
        "type": "string",
        "description": "Line range A:B (1-based, inclusive); also A: (to end), :B (from start), or A (one line)."
      },
      "match": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Show only lines matching this pattern (substring->glob->regex promoted, searched unanchored), with --context lines around each hit. Repeatable: several --match patterns produce ONE merged, de-duplicated set of windows, so \"show me around A and B\" is a single bounded read instead of two calls. In text output a pattern that matched nothing is named on stderr; under --json a `matches` array reports each pattern's hit count. Exit 1 means the union was empty (no pattern matched anything). Accepts file:PATH / stdin: / text:VALUE payloads; a multi-line payload matches as a line-anchored literal block."
      },
      "mode": {
        "type": "string",
        "enum": [
          "literal",
          "glob",
          "regex",
          "auto"
        ],
        "description": "How patterns are interpreted. literal|glob|regex pin one reading for every pattern in the invocation; auto states the substring->glob->regex promotion rule out loud. Use literal for verbatim code anchors."
      },
      "context": {
        "type": "integer",
        "description": "Lines of context shown around each --match hit. Default: 2.",
        "default": 2
      },
      "limit": {
        "type": "integer",
        "description": "Cap the number of lines emitted."
      },
      "plain": {
        "type": "boolean",
        "description": "Suppress the line-number gutter in text output."
      },
      "frontmatter": {
        "type": "boolean",
        "description": "OKF: show only the concept's leading frontmatter block."
      },
      "no-frontmatter": {
        "type": "boolean",
        "description": "OKF: omit the concept's frontmatter block from the shown lines. With --json, a 'frontmatter' field is added whenever the file is an OKF concept, regardless of this flag."
      },
      "json": {
        "type": "boolean",
        "description": "Emit a structured JSON result instead of text."
      },
      "timeout": {
        "type": "number",
        "description": "Abort with exit 2 (and a one-line message) if the view exceeds SECS seconds (fractional allowed)."
      },
      "heartbeat": {
        "type": "number",
        "description": "Print a liveness pulse every SECS seconds (fractional allowed) while the run is in progress."
      },
      "heartbeat-emit": {
        "type": "string",
        "description": "Heartbeat line template. Tokens: {ELAPSED} (whole seconds so far) {TOOL}. Default: \"[{ELAPSED}s]\"."
      },
      "heartbeat-to": {
        "type": "string",
        "enum": [
          "stderr",
          "stdout"
        ],
        "description": "Stream heartbeat pulses are written to. Default: stderr."
      },
      "json-pretty": {
        "type": "boolean",
        "description": "Like --json, but pretty-printed (indented)."
      }
    },
    "required": [
      "path"
    ]
  },
  "examples": [
    {
      "cmd": "ct view src/steer.rs --range 900:965",
      "why": "Read only lines 900-965 of a large file, instead of sed -n '900,965p' src/steer.rs."
    },
    {
      "cmd": "ct view src/lib.rs --match 'pub mod' --context 0",
      "why": "Show every 'pub mod' line with no surrounding context, instead of grep -n 'pub mod' src/lib.rs."
    },
    {
      "cmd": "ct view Cargo.toml --range :20",
      "why": "Read the first 20 lines, instead of head -n 20 Cargo.toml."
    },
    {
      "cmd": "ct view src/lib.rs --match 'fn parse' --match 'fn render' -C 3",
      "why": "Show the regions around two different anchors in one bounded call, merged and de-duplicated, instead of two separate views."
    }
  ]
}