fscars 0.1.0__py3-none-any.whl

fscars/__init__.py

@@ -0,0 +1,23 @@
+"""Functional Scars — bolt-on correction primitive for AI coding agents.
+
+Reference implementation of the framework described in
+*Lucy Syndrome in LLM Agents: A Practitioner Framework for Cross-Session
+Correction Persistence* (Del Puerto, 2026), DOI 10.5281/zenodo.19555971.
+"""
+
+from fscars.core.fire import Fire, FireRecord, Severity
+from fscars.core.payload import HookEventType, HookPayload
+from fscars.core.scar import FunctionalScar, Scope
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Fire",
+    "FireRecord",
+    "FunctionalScar",
+    "HookEventType",
+    "HookPayload",
+    "Scope",
+    "Severity",
+    "__version__",
+]

fscars/adapters/__init__.py

@@ -0,0 +1 @@
+"""Platform-specific adapters that translate hook payloads to fscars HookPayload."""

fscars/adapters/base.py

@@ -0,0 +1,51 @@
+"""Adapter base class.
+
+Each adapter wraps one AI coding agent platform (Claude Code, Codex CLI,
+Cursor, etc.). The adapter knows:
+
+- How to parse that platform's hook stdin payload.
+- How to write the platform's settings/config so a single fscars entrypoint
+  receives every hook event.
+- How to format the output the platform expects.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from fscars.core.payload import HookPayload
+from fscars.core.scar import ScarOutput
+
+
+class Adapter(ABC):
+    """Common interface for platform adapters."""
+
+    name: str = "abstract"
+
+    @abstractmethod
+    def parse_stdin(self, raw: dict) -> HookPayload | None:
+        """Translate a platform-specific JSON payload into a HookPayload.
+
+        Returns None if the payload is malformed. The engine treats None
+        as "do nothing".
+        """
+        ...
+
+    @abstractmethod
+    def emit_output(self, output: ScarOutput) -> str:
+        """Serialize ScarOutput in the format the platform expects on stdout."""
+        ...
+
+    @abstractmethod
+    def install(self, project_root: Path) -> None:
+        """Wire the entrypoint into the platform's hook config under project_root."""
+        ...
+
+    @abstractmethod
+    def uninstall(self, project_root: Path) -> None:
+        """Reverse install — remove the entrypoint registration."""
+        ...
+
+
+__all__ = ["Adapter"]

fscars/adapters/claude_code/__init__.py

@@ -0,0 +1,5 @@
+"""Claude Code adapter."""
+
+from fscars.adapters.claude_code.adapter import ClaudeCodeAdapter
+
+__all__ = ["ClaudeCodeAdapter"]

fscars/adapters/claude_code/adapter.py

@@ -0,0 +1,171 @@
+"""Claude Code adapter — Anthropic's claude-code CLI.
+
+Reads JSON from stdin in the shape Claude Code uses and writes
+hookSpecificOutput in the shape it expects.
+
+Reference: Claude Code hooks documentation
+https://docs.anthropic.com/claude/docs/claude-code/hooks
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fscars.adapters.base import Adapter
+from fscars.core.payload import HookEventType, HookPayload
+from fscars.core.scar import ScarOutput
+
+# Map Claude Code event names → canonical fscars event types
+_CC_TO_CANONICAL = {
+    "SessionStart": HookEventType.SESSION_START,
+    "SessionEnd": HookEventType.SESSION_END,
+    "UserPromptSubmit": HookEventType.USER_PROMPT_SUBMIT,
+    "PreToolUse": HookEventType.PRE_TOOL_USE,
+    "PostToolUse": HookEventType.POST_TOOL_USE,
+    "Stop": HookEventType.STOP,
+    "Notification": HookEventType.NOTIFICATION,
+}
+
+
+class ClaudeCodeAdapter(Adapter):
+    """Adapter for Anthropic Claude Code."""
+
+    name = "claude_code"
+
+    def parse_stdin(self, raw: dict) -> HookPayload | None:
+        """Convert Claude Code's stdin payload to a normalized HookPayload."""
+        if not isinstance(raw, dict):
+            return None
+
+        # Claude Code sometimes uses "hook_event_name", sometimes "event"
+        event_name = (
+            raw.get("hook_event_name")
+            or raw.get("event")
+            or raw.get("hookEventName")
+            or ""
+        )
+        canonical = _CC_TO_CANONICAL.get(event_name)
+        if canonical is None:
+            return None
+
+        try:
+            return HookPayload(
+                event_type=canonical,
+                tool_name=raw.get("tool_name"),
+                tool_input=raw.get("tool_input") or {},
+                prompt=raw.get("prompt"),
+                cwd=raw.get("cwd") or raw.get("workspace") or "",
+                session_id=raw.get("session_id") or "",
+                raw=raw,
+            )
+        except Exception:
+            return None
+
+    def emit_output(self, output: ScarOutput) -> str:
+        """Build the JSON string Claude Code expects on stdout.
+
+        On block, the run_hook script also exits with code 2 — the
+        decision="block" field is for surface visibility.
+        """
+        if output.is_empty:
+            return "{}"
+
+        payload: dict = {}
+        hook_specific: dict = {}
+        if output.additional_context:
+            hook_specific["additionalContext"] = output.additional_context
+        if output.block:
+            hook_specific["decision"] = "block"
+        if hook_specific:
+            payload["hookSpecificOutput"] = hook_specific
+        if output.system_message:
+            payload["systemMessage"] = output.system_message
+        return json.dumps(payload, ensure_ascii=False)
+
+    # -----------------------------------------------------------------
+    # install / uninstall — wire up `.claude/settings.json`
+    # -----------------------------------------------------------------
+
+    SETTINGS_FILE = ".claude/settings.json"
+    HOOK_COMMAND = "python -m fscars.run_hook --adapter claude_code"
+
+    def install(self, project_root: Path) -> None:
+        """Add fscars entries to .claude/settings.json under project_root.
+
+        Idempotent: re-running install does not duplicate entries.
+        """
+        settings_path = project_root / self.SETTINGS_FILE
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if settings_path.exists():
+            try:
+                settings = json.loads(settings_path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                settings = {}
+        else:
+            settings = {}
+
+        hooks = settings.setdefault("hooks", {})
+
+        wanted_events = (
+            "SessionStart",
+            "UserPromptSubmit",
+            "PreToolUse",
+            "PostToolUse",
+            "Stop",
+        )
+        entry = {"command": self.HOOK_COMMAND}
+
+        for event in wanted_events:
+            current = hooks.get(event) or []
+            if not isinstance(current, list):
+                current = [current]
+            already = any(
+                isinstance(c, dict) and c.get("command") == self.HOOK_COMMAND
+                for c in current
+            )
+            if not already:
+                current.append(entry)
+            hooks[event] = current
+
+        settings_path.write_text(
+            json.dumps(settings, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+
+    def uninstall(self, project_root: Path) -> None:
+        """Remove fscars entries from .claude/settings.json. Leaves other hooks alone."""
+        settings_path = project_root / self.SETTINGS_FILE
+        if not settings_path.exists():
+            return
+        try:
+            settings = json.loads(settings_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            return
+
+        hooks = settings.get("hooks") or {}
+        for event, entries in list(hooks.items()):
+            if not isinstance(entries, list):
+                continue
+            kept = [
+                e
+                for e in entries
+                if not (isinstance(e, dict) and e.get("command") == self.HOOK_COMMAND)
+            ]
+            if kept:
+                hooks[event] = kept
+            else:
+                hooks.pop(event)
+        if hooks:
+            settings["hooks"] = hooks
+        elif "hooks" in settings:
+            settings.pop("hooks")
+
+        settings_path.write_text(
+            json.dumps(settings, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+
+
+__all__ = ["ClaudeCodeAdapter"]

fscars/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package — exposes the `fscar` command via Typer."""

fscars/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Subcommand modules for the fscar CLI."""

fscars/cli/commands/disable.py

@@ -0,0 +1,53 @@
+"""`fscar disable` — disable a scar without deleting it."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from fscars.core.store import default_store
+
+
+def run(
+    scar_id: str = typer.Argument(..., help="The scar_id to disable."),
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        "-p",
+        help="Project root.",
+        file_okay=False,
+        resolve_path=True,
+    ),
+    enable: bool = typer.Option(
+        False, "--enable", help="Re-enable a previously disabled scar."
+    ),
+) -> None:
+    """Add or remove a scar_id from .fscars/disabled.txt."""
+    store = default_store(project)
+    if not store.exists():
+        typer.secho(
+            f"No fscars store at {store.root}. Run `fscar init` first.",
+            fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=1)
+
+    disabled = store.disabled_scars()
+    if enable:
+        if scar_id not in disabled:
+            typer.echo(f"{scar_id} is not currently disabled.")
+            return
+        disabled.discard(scar_id)
+        typer.secho(f"[OK] Re-enabled {scar_id}", fg=typer.colors.GREEN)
+    else:
+        if scar_id in disabled:
+            typer.echo(f"{scar_id} is already disabled.")
+            return
+        disabled.add(scar_id)
+        typer.secho(f"[OK] Disabled {scar_id}", fg=typer.colors.YELLOW)
+
+    lines = sorted(disabled)
+    store.disabled_file.write_text(
+        "\n".join(lines) + ("\n" if lines else ""),
+        encoding="utf-8",
+    )

fscars/cli/commands/doctor.py

@@ -0,0 +1,92 @@
+"""`fscar doctor` — diagnose installation and hook wiring."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from fscars import __version__
+from fscars.core.store import default_store
+
+
+def run(
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        "-p",
+        help="Project root.",
+        file_okay=False,
+        resolve_path=True,
+    ),
+) -> None:
+    """Run a self-check on a project and report PASS / WARN / FAIL items."""
+    typer.echo(f"fscars version: {__version__}")
+    typer.echo(f"project root  : {project}")
+    typer.echo("")
+
+    store = default_store(project)
+
+    items: list[tuple[str, str, str]] = []
+
+    items.append(
+        ("PASS" if store.root.exists() else "FAIL", ".fscars/ exists", str(store.root))
+    )
+    items.append(
+        (
+            "PASS" if store.config_file.exists() else "WARN",
+            "config.toml present",
+            str(store.config_file),
+        )
+    )
+    items.append(
+        (
+            "PASS" if store.logs_dir.exists() else "WARN",
+            "logs/ directory ready",
+            str(store.logs_dir),
+        )
+    )
+
+    settings_path = project / ".claude" / "settings.json"
+    settings_ok = False
+    if settings_path.exists():
+        try:
+            settings = json.loads(settings_path.read_text(encoding="utf-8"))
+            hooks = settings.get("hooks") or {}
+            settings_ok = any(
+                isinstance(v, list)
+                and any(
+                    isinstance(item, dict)
+                    and "fscars.run_hook" in str(item.get("command", ""))
+                    for item in v
+                )
+                for v in hooks.values()
+            )
+        except json.JSONDecodeError:
+            settings_ok = False
+    items.append(
+        (
+            "PASS" if settings_ok else "WARN",
+            "Claude Code hook wired",
+            str(settings_path),
+        )
+    )
+
+    fail = False
+    for status, label, detail in items:
+        color = {
+            "PASS": typer.colors.GREEN,
+            "WARN": typer.colors.YELLOW,
+            "FAIL": typer.colors.RED,
+        }.get(status, typer.colors.WHITE)
+        typer.secho(f"[{status}] ", fg=color, nl=False)
+        typer.echo(f"{label} — {detail}")
+        if status == "FAIL":
+            fail = True
+
+    typer.echo("")
+    if fail:
+        typer.secho("doctor: one or more checks failed.", fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+    typer.secho("doctor: all checks passed.", fg=typer.colors.GREEN)

fscars/cli/commands/init.py

@@ -0,0 +1,51 @@
+"""`fscar init` — wire fscars into the current project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from fscars.adapters.claude_code import ClaudeCodeAdapter
+from fscars.core.store import default_store
+
+
+def run(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Project root (defaults to the current directory).",
+        file_okay=False,
+        resolve_path=True,
+    ),
+    adapter: str = typer.Option(
+        "claude_code",
+        "--adapter",
+        "-a",
+        help="Which AI coding agent to wire up.",
+    ),
+) -> None:
+    """Create .fscars/ and register the hook entrypoint with the chosen adapter."""
+    project_root = path
+    project_root.mkdir(parents=True, exist_ok=True)
+
+    store = default_store(project_root)
+    fresh = not store.exists()
+    store.initialize()
+
+    if adapter == "claude_code":
+        ClaudeCodeAdapter().install(project_root)
+        wired = ".claude/settings.json"
+    else:
+        raise typer.BadParameter(f"Unknown adapter: {adapter}")
+
+    if fresh:
+        typer.secho(
+            f"[OK] Initialized fscars at {store.root}",
+            fg=typer.colors.GREEN,
+        )
+    else:
+        typer.echo(f"[OK] fscars already initialized at {store.root}")
+    typer.echo(f"[OK] Wired hook entry into {project_root / wired}")
+    typer.echo("")
+    typer.echo("Next: copy a starter scar from `cookbook/scars/`, or run")
+    typer.echo("      `fscar fire <name> \"<rule>\"` to register one inline.")

fscars/cli/commands/list_cmd.py

@@ -0,0 +1,63 @@
+"""`fscar list` — show registered scars and their fire counts."""
+
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from fscars.core.engine import ScarRegistry
+from fscars.core.log import read_fires
+from fscars.core.store import default_store
+
+
+def run(
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        "-p",
+        help="Project root (defaults to the current directory).",
+        file_okay=False,
+        resolve_path=True,
+    ),
+) -> None:
+    """List active scars with last-fire timestamps."""
+    registry = ScarRegistry.load_builtins()
+    store = default_store(project)
+
+    fires = read_fires(root=store.root)
+    counts: Counter[str] = Counter(f.scar_id for f in fires)
+    last_fire: dict[str, str] = {}
+    for f in fires:
+        last_fire.setdefault(f.scar_id, f.timestamp)
+        if f.timestamp > last_fire[f.scar_id]:
+            last_fire[f.scar_id] = f.timestamp
+
+    table = Table(title="Functional Scars", show_lines=False)
+    table.add_column("scar_id")
+    table.add_column("name")
+    table.add_column("event")
+    table.add_column("severity")
+    table.add_column("fires", justify="right")
+    table.add_column("last fire")
+    table.add_column("enabled")
+
+    scars = registry.all()
+    if not scars:
+        typer.echo("No scars registered. Add one in cookbook/scars/.")
+        return
+
+    for scar in scars:
+        table.add_row(
+            scar.scar_id,
+            scar.name or "-",
+            scar.event_type.value,
+            scar.severity.value,
+            str(counts.get(scar.scar_id, 0)),
+            last_fire.get(scar.scar_id, "-"),
+            "yes" if scar.enabled else "no",
+        )
+    Console().print(table)

fscars/cli/commands/log_cmd.py

@@ -0,0 +1,66 @@
+"""`fscar log` — show recent fires."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from fscars.core.log import read_fires
+from fscars.core.store import default_store
+
+
+def run(
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        "-p",
+        help="Project root.",
+        file_okay=False,
+        resolve_path=True,
+    ),
+    scar: str | None = typer.Option(
+        None, "--scar", "-s", help="Filter to a single scar_id."
+    ),
+    session: str | None = typer.Option(
+        None, "--session", help="Filter to a single session_id."
+    ),
+    n: int = typer.Option(20, "-n", help="Number of recent fires to show."),
+) -> None:
+    """Show the most recent fires from .fscars/logs/fires.jsonl."""
+    store = default_store(project)
+    fires = read_fires(root=store.root)
+
+    if scar:
+        fires = [f for f in fires if f.scar_id == scar]
+    if session:
+        fires = [f for f in fires if f.session_id == session]
+
+    fires = fires[-n:]
+    if not fires:
+        typer.echo("No fires recorded yet.")
+        return
+
+    table = Table(title=f"Recent fires (showing {len(fires)})", show_lines=False)
+    table.add_column("timestamp")
+    table.add_column("scar_id")
+    table.add_column("event")
+    table.add_column("action")
+    table.add_column("tool")
+    table.add_column("trigger")
+    table.add_column("ms", justify="right")
+
+    for f in fires:
+        table.add_row(
+            f.timestamp,
+            f.scar_id,
+            f.event_type if isinstance(f.event_type, str) else f.event_type.value,
+            f.action if isinstance(f.action, str) else f.action.value,
+            f.tool_name or "-",
+            (f.trigger_match or "")[:40],
+            f"{f.latency_ms:.1f}" if f.latency_ms is not None else "-",
+        )
+
+    Console().print(table)

fscars/cli/commands/stats.py

@@ -0,0 +1,76 @@
+"""`fscar stats` — compute persistence metrics from fires.jsonl."""
+
+from __future__ import annotations
+
+import statistics
+from collections import Counter
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from fscars.core.log import read_fires
+from fscars.core.store import default_store
+
+
+def run(
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        "-p",
+        help="Project root.",
+        file_okay=False,
+        resolve_path=True,
+    ),
+) -> None:
+    """Show fire counts, average latency, and tokens added by scar."""
+    store = default_store(project)
+    fires = read_fires(root=store.root)
+
+    if not fires:
+        typer.echo("No fires recorded yet — nothing to compute.")
+        return
+
+    counts: Counter[str] = Counter(f.scar_id for f in fires)
+    by_scar: dict[str, list[float]] = {}
+    tokens_total: Counter[str] = Counter()
+    blocked_total: Counter[str] = Counter()
+
+    for f in fires:
+        if f.latency_ms is not None and f.latency_ms >= 0:
+            by_scar.setdefault(f.scar_id, []).append(f.latency_ms)
+        tokens_total[f.scar_id] += f.tokens_added
+        action_value = f.action if isinstance(f.action, str) else f.action.value
+        if action_value == "blocked":
+            blocked_total[f.scar_id] += 1
+
+    table = Table(title=f"fscar stats ({len(fires)} fires)", show_lines=False)
+    table.add_column("scar_id")
+    table.add_column("fires", justify="right")
+    table.add_column("blocked", justify="right")
+    table.add_column("p50 ms", justify="right")
+    table.add_column("p99 ms", justify="right")
+    table.add_column("tokens added", justify="right")
+
+    for scar_id, n_fires in counts.most_common():
+        latencies = by_scar.get(scar_id, [])
+        if latencies:
+            p50 = f"{statistics.median(latencies):.1f}"
+            p99 = (
+                f"{statistics.quantiles(latencies, n=100)[98]:.1f}"
+                if len(latencies) >= 100
+                else f"{max(latencies):.1f}"
+            )
+        else:
+            p50 = p99 = "-"
+        table.add_row(
+            scar_id,
+            str(n_fires),
+            str(blocked_total.get(scar_id, 0)),
+            p50,
+            p99,
+            str(tokens_total[scar_id]),
+        )
+
+    Console().print(table)