scc-cli 0.2.11

System Context Compiler CLI, daemon, MCP server, and Claude Code plugin
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

"""SCC tool handlers — thin wrappers over the local `scc` CLI.

Every handler: receives args (dict), does the work, returns a JSON string,
never raises (Hermes plugin contract).
"""

import json
import os
import shutil
import subprocess

# trace:exempt reason=vendored-copy (byte-identical copy of plugins/ for crates.io packaging; canonical marker lives at the plugins/ original)


def _scc_bin():
    return os.environ.get("SCC_BIN") or shutil.which("scc") or "scc"


def _run(args):
    """Run scc with --json and return parsed output."""
    try:
        proc = subprocess.run(
            [_scc_bin(), *args, "--json"],
            capture_output=True,
            text=True,
            timeout=120,
        )
    except FileNotFoundError:
        return {
            "error": "scc binary not found — install System Context Compiler or set SCC_BIN"
        }
    except subprocess.TimeoutExpired:
        return {"error": "scc timed out"}
    if proc.returncode != 0:
        return {"error": proc.stderr.strip() or "scc failed"}
    try:
        return json.loads(proc.stdout)
    except json.JSONDecodeError:
        return {"error": "scc returned non-JSON output"}


# trace:exempt reason=internal-detail  # CLI wrapper helper; behavior traced at impl.scc.cli
def _run_text(args):
    """Run scc WITHOUT --json and return the raw stdout text.

    Used by the text-artifact tools (startup/surface/structural have no
    --json mode); failures return the same error dict shape as `_run`.
    """
    try:
        proc = subprocess.run(
            [_scc_bin(), *args],
            capture_output=True,
            text=True,
            timeout=120,
        )
    except FileNotFoundError:
        return {
            "error": "scc binary not found — install System Context Compiler or set SCC_BIN"
        }
    except subprocess.TimeoutExpired:
        return {"error": "scc timed out"}
    if proc.returncode != 0:
        return {"error": proc.stderr.strip() or "scc failed"}
    return {"content": proc.stdout}


def system_overview(args: dict, **kwargs) -> str:
    return json.dumps(_run(["overview"]))


def system_atlas(args: dict, **kwargs) -> str:
    cmd = ["atlas"]
    if args.get("token_budget"):
        cmd += ["--budget", str(args["token_budget"])]
    return json.dumps(_run(cmd))


def task_context(args: dict, **kwargs) -> str:
    cmd = ["context", "task", args.get("goal", "")]
    if args.get("files"):
        cmd += ["--files", " ".join(args["files"])]
    if args.get("symbols"):
        cmd += ["--symbols", " ".join(args["symbols"])]
    if args.get("token_budget"):
        cmd += ["--budget", str(args["token_budget"])]
    return json.dumps(_run(cmd))


def component_context(args: dict, **kwargs) -> str:
    return json.dumps(_run(["context", "component", args.get("component", "")]))


def flow_context(args: dict, **kwargs) -> str:
    return json.dumps(_run(["context", "flow", args.get("flow", "")]))


def impact_context(args: dict, **kwargs) -> str:
    cmd = ["impact"]
    if args.get("files"):
        cmd += list(args["files"])
    if args.get("symbols"):
        cmd += ["--symbols", " ".join(args["symbols"])]
    if args.get("diff"):
        cmd += ["--diff", args["diff"]]
    return json.dumps(_run(cmd))


def verify_context(args: dict, **kwargs) -> str:
    return json.dumps(_run(["verify"]))


# trace:exempt reason=internal-detail  # CLI mirror wrapper; behavior traced at impl.scc.cli
def system_context(args: dict, **kwargs) -> str:
    """The fused session-startup artifact (Atlas + Surface + coverage + omissions)."""
    cmd = ["context", "startup"]
    if args.get("token_budget"):
        cmd += ["--budget", str(args["token_budget"])]
    return json.dumps(_run_text(cmd))


# trace:exempt reason=internal-detail  # CLI mirror wrapper; behavior traced at impl.scc.cli
def surface_map(args: dict, **kwargs) -> str:
    """The System Surface Map, global or task-personalized."""
    cmd = ["surface"]
    if args.get("goal"):
        cmd += ["--task", args["goal"]]
    if args.get("token_budget"):
        cmd += ["--budget", str(args["token_budget"])]
    return json.dumps(_run_text(cmd))


# trace:exempt reason=internal-detail  # CLI mirror wrapper; behavior traced at impl.scc.cli
def structural_source(args: dict, **kwargs) -> str:
    """Structural Source for explicit files or a goal-resolved file set."""
    cmd = ["context", "structural"]
    if args.get("files"):
        cmd += ["--files", " ".join(args["files"])]
    if args.get("goal"):
        cmd += ["--task", args["goal"]]
    if args.get("token_budget"):
        cmd += ["--budget", str(args["token_budget"])]
    return json.dumps(_run_text(cmd))