maskflow-cli 0.2.0__tar.gz

maskflow_cli-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+node_modules/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.pytest_cache/
+.idea/
+.coverage
+.mypy_cache/
+.ruff_cache/

maskflow_cli-0.2.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.5
+Name: maskflow-cli
+Version: 0.2.0
+Summary: Command-line interface for MaskFlow: .maskflowrc config validation and inspection
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: maskflow-core[yaml]<0.5,>=0.4.0
+Requires-Dist: maskflow-pack-india<0.2,>=0.1.0
+Requires-Dist: maskflow-pack-intl<0.3,>=0.2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# maskflow-cli
+
+Command-line interface for [MaskFlow](https://github.com/):
+
+```
+maskflow config validate
+maskflow config show --resolved
+maskflow doctor
+maskflow explain "<text>"
+```
+
+`maskflow doctor` checks installed versions, spaCy model presence (and
+which entities that consequently disables), and `.maskflowrc` validity,
+then reports enabled/disabled status for every registered entity. It
+exits 0 only when every check passes.
+
+`maskflow explain "<text>"` shows, span by span, why each piece of text
+was (or wasn't) detected as PII -- the pattern/NER hit, checksum result,
+context boost, and the threshold decision behind it. Spans that scored
+below their entity's threshold are listed separately as NEAREST MISSES,
+with the `.maskflowrc` change that would catch them. Matched text is
+truncated to 8 characters unless `--full` is passed. Accepts the same
+`--config`/`--set` overrides as `maskflow config`, so explanations reflect
+the same resolved config a real `mask()` call would use.
+
+See `docs/configuration.md` in the repo root for the full config reference.

maskflow_cli-0.2.0/README.md

@@ -0,0 +1,26 @@
+# maskflow-cli
+
+Command-line interface for [MaskFlow](https://github.com/):
+
+```
+maskflow config validate
+maskflow config show --resolved
+maskflow doctor
+maskflow explain "<text>"
+```
+
+`maskflow doctor` checks installed versions, spaCy model presence (and
+which entities that consequently disables), and `.maskflowrc` validity,
+then reports enabled/disabled status for every registered entity. It
+exits 0 only when every check passes.
+
+`maskflow explain "<text>"` shows, span by span, why each piece of text
+was (or wasn't) detected as PII -- the pattern/NER hit, checksum result,
+context boost, and the threshold decision behind it. Spans that scored
+below their entity's threshold are listed separately as NEAREST MISSES,
+with the `.maskflowrc` change that would catch them. Matched text is
+truncated to 8 characters unless `--full` is passed. Accepts the same
+`--config`/`--set` overrides as `maskflow config`, so explanations reflect
+the same resolved config a real `mask()` call would use.
+
+See `docs/configuration.md` in the repo root for the full config reference.

maskflow_cli-0.2.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "maskflow-cli"
+version = "0.2.0"
+description = "Command-line interface for MaskFlow: .maskflowrc config validation and inspection"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    # The config engine (schema/discovery/merge/validate) lives in
+    # maskflow_core.config, which only exists from core 0.3.0 -- [yaml]
+    # since the CLI, unlike the SDK, should accept a YAML .maskflowrc out
+    # of the box (it's already a heavier, more optional install than the SDK).
+    "maskflow-core[yaml]>=0.4.0,<0.5",
+    # maskflow_pack_intl is imported (side-effect only, to populate the
+    # PIIType registry) for `maskflow config validate`'s soft entity-name
+    # cross-check -- see app.py. pack-intl 0.1.0 itself requires core<0.3,
+    # unsatisfiable alongside core>=0.3.0 above -- 0.2.0 is the first
+    # version that requires (and works with) the new core.
+    "maskflow-pack-intl>=0.2.0,<0.3",
+    # Same reasoning as pack-intl above, for AADHAAR/PAN/GSTIN/IFSC/UPI_VPA
+    # -- also makes `maskflow doctor`/`maskflow explain` aware of them.
+    "maskflow-pack-india>=0.1.0,<0.2",
+    "typer>=0.12",
+    # CLI-only: pretty-prints `maskflow config show`'s plain TOML dump.
+    "tomli-w>=1.0",
+    # CLI-only: `maskflow doctor`'s health/entity tables.
+    "rich>=13.0",
+]
+
+[project.scripts]
+maskflow = "maskflow_cli.app:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.uv.sources]
+maskflow-core = { workspace = true }
+maskflow-pack-intl = { workspace = true }
+maskflow-pack-india = { workspace = true }
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maskflow_cli"]

maskflow_cli-0.2.0/src/maskflow_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

maskflow_cli-0.2.0/src/maskflow_cli/app.py

@@ -0,0 +1,24 @@
+"""Root CLI: `maskflow ...` (console script entry point, see pyproject.toml)."""
+
+from __future__ import annotations
+
+import maskflow_pack_india  # noqa: F401 -- import side effect registers pack-india's entity types
+import maskflow_pack_intl  # noqa: F401 -- import side effect registers pack-intl's entity types
+import typer
+
+from .commands.config_cmd import app as config_app
+from .commands.doctor_cmd import doctor
+from .commands.explain_cmd import explain
+
+app = typer.Typer(help="MaskFlow: reversible PII masking for LLM calls.", no_args_is_help=True)
+app.add_typer(config_app, name="config")
+app.command("doctor")(doctor)
+app.command("explain")(explain)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

maskflow_cli-0.2.0/src/maskflow_cli/commands/config_cmd.py

@@ -0,0 +1,66 @@
+"""`maskflow config validate` / `maskflow config show [--resolved]`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from maskflow_core.config.resolve import ConfigResolutionError, ResolvedConfig, resolve_config
+
+from ..render import format_resolved, format_show
+
+app = typer.Typer(help="Inspect and validate .maskflowrc configuration.")
+
+_CONFIG_OPTION = typer.Option(
+    None, "--config", help="Explicit config file path, bypassing project/user file discovery."
+)
+_SET_OPTION = typer.Option(
+    [], "--set", help="Override a resolved value, e.g. --set entities.AADHAAR.threshold=0.7"
+)
+
+
+def _resolve_or_exit(config: Path | None, overrides: list[str]) -> ResolvedConfig:
+    try:
+        return resolve_config(config_path_override=config, cli_sets=list(overrides))
+    except ConfigResolutionError as exc:
+        for line in str(exc).splitlines():
+            typer.echo(line, err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command("validate")
+def validate(
+    config: Path | None = _CONFIG_OPTION,
+    set_: list[str] = _SET_OPTION,
+) -> None:
+    """Validate the resolved .maskflowrc, reporting every problem found."""
+    resolved = _resolve_or_exit(config, set_)
+
+    for warning in resolved.warnings:
+        typer.echo(f"WARNING: {warning.message}", err=True)
+
+    sources = []
+    if resolved.user_file is not None:
+        sources.append(f"user file: {resolved.user_file}")
+    if resolved.project_file is not None:
+        sources.append(f"project file: {resolved.project_file}")
+    suffix = f" ({', '.join(sources)})" if sources else " (no config file found -- using defaults)"
+    typer.echo(f"Config is valid.{suffix}")
+
+
+@app.command("show")
+def show(
+    resolved: bool = typer.Option(
+        False, "--resolved", help="Annotate every value with where it came from."
+    ),
+    config: Path | None = _CONFIG_OPTION,
+    set_: list[str] = _SET_OPTION,
+) -> None:
+    """Print the merged, validated config -- plain TOML by default, or one
+    annotated `path = value (origin)` line per field with --resolved."""
+    resolved_config = _resolve_or_exit(config, set_)
+
+    if resolved:
+        typer.echo(format_resolved(resolved_config))
+    else:
+        typer.echo(format_show(resolved_config), nl=False)

maskflow_cli-0.2.0/src/maskflow_cli/commands/doctor_cmd.py

@@ -0,0 +1,20 @@
+"""`maskflow doctor`."""
+
+from __future__ import annotations
+
+import typer
+
+from ..doctor import run_checks
+from ..doctor_render import make_console, render_report
+
+
+def doctor() -> None:
+    """Check installed versions, spaCy model presence, and .maskflowrc
+    validity, and report which entities are consequently enabled/disabled.
+    Exits 0 only when every check passes."""
+    console = make_console()
+    report = run_checks()
+    render_report(console, report)
+
+    if not report.healthy:
+        raise typer.Exit(code=1)

maskflow_cli-0.2.0/src/maskflow_cli/commands/explain_cmd.py

@@ -0,0 +1,43 @@
+"""`maskflow explain "<text>"`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from maskflow_core.config.resolve import ConfigResolutionError, resolve_config
+
+from ..explain import run_explain
+from ..explain_render import make_console, render_explain
+
+_CONFIG_OPTION = typer.Option(
+    None, "--config", help="Explicit config file path, bypassing project/user file discovery."
+)
+_SET_OPTION = typer.Option(
+    [], "--set", help="Override a resolved value, e.g. --set entities.SSN.threshold=0.3"
+)
+_FULL_OPTION = typer.Option(
+    False, "--full", help="Show the entire matched value instead of truncating to 8 chars."
+)
+
+
+def explain(
+    text: str = typer.Argument(..., help="Text to analyze -- never written to any log."),
+    full: bool = _FULL_OPTION,
+    config: Path | None = _CONFIG_OPTION,
+    set_: list[str] = _SET_OPTION,
+) -> None:
+    """Show, span by span, why each piece of text was (or wasn't) detected
+    as PII: the pattern/NER hit, checksum result, context boost, and the
+    threshold decision behind it. Spans that scored below their entity's
+    threshold are listed separately as NEAREST MISSES, with the
+    .maskflowrc change that would catch them."""
+    try:
+        resolved = resolve_config(config_path_override=config, cli_sets=list(set_))
+    except ConfigResolutionError as exc:
+        for line in str(exc).splitlines():
+            typer.echo(line, err=True)
+        raise typer.Exit(code=1) from exc
+
+    result = run_explain(text, resolved.config, full=full)
+    render_explain(make_console(), result)

maskflow_cli-0.2.0/src/maskflow_cli/doctor.py

@@ -0,0 +1,184 @@
+"""Data gathering for `maskflow doctor` -- pure checks, no Rich/Typer here,
+so the logic is testable without rendering. See doctor_render.py for the
+table output and commands/doctor_cmd.py for the Typer command + exit code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib import metadata
+from typing import Literal
+
+from maskflow_core.config.resolve import ConfigResolutionError, ResolvedConfig, resolve_config
+from maskflow_core.entities import PIIType
+from maskflow_core.ner import MODEL_NAME
+from maskflow_core.registry import NER_RECOGNIZERS, PATTERNS
+
+Status = Literal["ok", "warn", "error"]
+
+
+@dataclass(frozen=True)
+class ComponentCheck:
+    name: str
+    version: str | None
+    status: Status
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class EntityCheck:
+    name: str
+    detector: str
+    enabled: bool
+    reason: str = ""
+
+
+@dataclass(frozen=True)
+class DoctorReport:
+    components: list[ComponentCheck] = field(default_factory=list)
+    entities: list[EntityCheck] = field(default_factory=list)
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for c in self.components if c.status == "error")
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for c in self.components if c.status == "warn")
+
+    @property
+    def healthy(self) -> bool:
+        return self.error_count == 0
+
+
+def _version(dist_name: str) -> str | None:
+    try:
+        return metadata.version(dist_name)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def _check_packages() -> list[ComponentCheck]:
+    checks: list[ComponentCheck] = []
+
+    for dist_name in ("maskflow-core", "maskflow-cli"):
+        version = _version(dist_name)
+        if version is None:
+            checks.append(ComponentCheck(dist_name, None, "error", "not installed"))
+        else:
+            checks.append(ComponentCheck(dist_name, version, "ok"))
+
+    installed_packs = sorted(
+        {
+            name
+            for dist in metadata.distributions()
+            if (name := dist.metadata.get("Name")) and name.startswith("maskflow-pack-")
+        }
+    )
+    for pack in installed_packs:
+        checks.append(ComponentCheck(pack, _version(pack), "ok"))
+
+    return checks
+
+
+def _check_spacy() -> tuple[ComponentCheck, ComponentCheck]:
+    model_name = f"spaCy model ({MODEL_NAME})"
+    try:
+        import spacy
+    except ImportError:
+        return (
+            ComponentCheck(
+                "spaCy", None, "error", "not installed (pip install maskflow-core[nlp])"
+            ),
+            ComponentCheck(model_name, None, "error", "unavailable -- spaCy not installed"),
+        )
+
+    spacy_check = ComponentCheck("spaCy", spacy.__version__, "ok")
+    try:
+        spacy.load(MODEL_NAME)
+    except OSError:
+        model_check = ComponentCheck(
+            model_name, None, "error", f"MISSING (python -m spacy download {MODEL_NAME})"
+        )
+    else:
+        model_check = ComponentCheck(model_name, _version(MODEL_NAME), "ok")
+    return spacy_check, model_check
+
+
+def _check_config() -> tuple[ComponentCheck, ResolvedConfig | None]:
+    try:
+        resolved = resolve_config()
+    except ConfigResolutionError as exc:
+        detail = f"{len(exc.errors)} error(s) -- run `maskflow config validate`"
+        return ComponentCheck(".maskflowrc", None, "error", detail), None
+
+    if resolved.project_file is not None:
+        detail = f"valid (project file: {resolved.project_file})"
+    elif resolved.user_file is not None:
+        detail = f"valid (user file: {resolved.user_file})"
+    else:
+        detail = "valid (no config file found -- using defaults)"
+
+    status: Status = "ok"
+    if resolved.warnings:
+        status = "warn"
+        detail += f" -- {len(resolved.warnings)} warning(s), see `maskflow config validate`"
+
+    return ComponentCheck(".maskflowrc", None, status, detail), resolved
+
+
+def _check_redis() -> ComponentCheck:
+    # RedisMappingStore (maskflow_core.mapping_store) is an interface-only
+    # stub -- every method raises NotImplementedError regardless of whether
+    # a `redis` client or server is reachable, so there is nothing to probe
+    # yet. Always the same informational warning until that ships for real.
+    return ComponentCheck(
+        "Redis", None, "warn", "RedisMappingStore not implemented yet -- using in-memory store"
+    )
+
+
+def _entity_checks(resolved: ResolvedConfig | None, spacy_ready: bool) -> list[EntityCheck]:
+    ner_label_by_type: dict[PIIType, str] = {
+        mapping.pii_type: label for label, mapping in NER_RECOGNIZERS.items()
+    }
+    all_types = set(PATTERNS) | set(ner_label_by_type)
+
+    checks: list[EntityCheck] = []
+    for pii_type in sorted(all_types):
+        detector = (
+            f"ner:{ner_label_by_type[pii_type]}" if pii_type in ner_label_by_type else "pattern"
+        )
+
+        entity_config = (
+            resolved.config.entities.get(str(pii_type)) if resolved is not None else None
+        )
+        if entity_config is not None and not entity_config.enabled:
+            reason = ".maskflowrc: entities.<X>.enabled = false"
+            checks.append(EntityCheck(str(pii_type), detector, False, reason))
+            continue
+
+        if pii_type in ner_label_by_type and not spacy_ready:
+            checks.append(EntityCheck(str(pii_type), detector, False, "spaCy model unavailable"))
+            continue
+
+        checks.append(EntityCheck(str(pii_type), detector, True))
+
+    return checks
+
+
+def run_checks() -> DoctorReport:
+    components: list[ComponentCheck] = []
+    components.extend(_check_packages())
+
+    spacy_check, model_check = _check_spacy()
+    components.append(spacy_check)
+    components.append(model_check)
+
+    config_check, resolved = _check_config()
+    components.append(config_check)
+
+    components.append(_check_redis())
+
+    entities = _entity_checks(resolved, spacy_ready=model_check.status == "ok")
+
+    return DoctorReport(components=components, entities=entities)

maskflow_cli-0.2.0/src/maskflow_cli/doctor_render.py

@@ -0,0 +1,83 @@
+"""Rich rendering for `maskflow doctor`. Kept separate from doctor.py's pure
+data gathering so the checks themselves are testable without a console."""
+
+from __future__ import annotations
+
+from rich import box
+from rich.console import Console
+from rich.table import Table
+
+from .doctor import ComponentCheck, DoctorReport, EntityCheck
+
+# A fixed width rather than terminal auto-detection: `maskflow doctor`'s
+# longer detail strings (e.g. "MISSING (python -m spacy download ...)")
+# would otherwise wrap unpredictably under a non-tty (CI logs, CliRunner in
+# tests) where Rich falls back to an 80-column default.
+CONSOLE_WIDTH = 100
+
+_STATUS_SYMBOL: dict[str, str] = {"ok": "✓", "warn": "⚠", "error": "✗"}
+_STATUS_COLOR: dict[str, str] = {"ok": "green", "warn": "yellow", "error": "red"}
+
+
+def _component_status(check: ComponentCheck) -> str:
+    symbol = _STATUS_SYMBOL[check.status]
+    color = _STATUS_COLOR[check.status]
+    text = f"{symbol} {check.detail}".strip() if check.detail else symbol
+    return f"[{color}]{text}[/{color}]"
+
+
+def _component_table(components: list[ComponentCheck]) -> Table:
+    table = Table(box=box.SIMPLE_HEAD, show_edge=False, pad_edge=False)
+    table.add_column("Component")
+    table.add_column("Version")
+    table.add_column("Status", no_wrap=False, overflow="fold")
+    for check in components:
+        table.add_row(check.name, check.version or "—", _component_status(check))
+    return table
+
+
+def _entity_status(check: EntityCheck) -> str:
+    if check.enabled:
+        return "[green]✓ enabled[/green]"
+    return f"[red]✗ disabled — {check.reason}[/red]"
+
+
+def _entity_table(entities: list[EntityCheck]) -> Table:
+    table = Table(box=box.SIMPLE_HEAD, show_edge=False, pad_edge=False)
+    table.add_column("Entity")
+    table.add_column("Detector")
+    table.add_column("Status", overflow="fold")
+    for check in entities:
+        table.add_row(check.name, check.detector, _entity_status(check))
+    return table
+
+
+def _summary_line(report: DoctorReport) -> str:
+    active = sum(1 for e in report.entities if e.enabled)
+    total = len(report.entities)
+    disabled_note = "" if active == total else f" {total - active} disabled."
+    return f"{active} of {total} entities active.{disabled_note}"
+
+
+def render_report(console: Console, report: DoctorReport) -> None:
+    console.print("[bold]MaskFlow Doctor[/bold]")
+    console.print(_component_table(report.components))
+    console.print()
+    console.print(_entity_table(report.entities))
+    console.print()
+    console.print(_summary_line(report))
+
+    errors = report.error_count
+    warnings = report.warning_count
+    if errors == 0 and warnings == 0:
+        console.print("[bold green]✓ All checks passed.[/bold green]")
+    elif errors == 0:
+        console.print(f"[bold yellow]⚠ Healthy with {warnings} warning(s).[/bold yellow]")
+    else:
+        console.print(
+            f"[bold red]✗ Not fully healthy — {errors} error(s), {warnings} warning(s).[/bold red]"
+        )
+
+
+def make_console() -> Console:
+    return Console(width=CONSOLE_WIDTH)

maskflow_cli-0.2.0/src/maskflow_cli/explain.py

@@ -0,0 +1,92 @@
+"""Data assembly for `maskflow explain` -- compiles the resolved
+.maskflowrc config, runs detect(return_rejected=True), and turns the
+resulting Spans into renderable views. No Rich/Typer here, so this is
+testable without a console; see explain_render.py for the console output
+and commands/explain_cmd.py for the Typer command.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from maskflow_core.config.engine import compile_config
+from maskflow_core.config.schema import RootConfig
+from maskflow_core.detection import DEFAULT_MIN_CONFIDENCE, detect
+from maskflow_core.entities import ExplanationStep, Span
+
+# How much of a matched value maskflow explain shows by default -- never the
+# whole thing unless --full is passed (CLAUDE.md rule 1: never print raw PII
+# by default, even in a diagnostic tool).
+TRUNCATE_LEN = 8
+
+
+@dataclass(frozen=True)
+class SpanView:
+    entity_type: str
+    score: float
+    validated: bool
+    start: int
+    end: int
+    display_text: str
+    truncated: bool
+    steps: tuple[ExplanationStep, ...]
+    # None for a masked span; the entity's active threshold for a near miss.
+    threshold: float | None = None
+
+
+@dataclass(frozen=True)
+class ExplainResult:
+    text_length: int
+    masked: list[SpanView]
+    near_misses: list[SpanView]
+
+
+def _display_text(text: str, full: bool) -> tuple[str, bool]:
+    if full or len(text) <= TRUNCATE_LEN:
+        return text, False
+    return text[:TRUNCATE_LEN] + "…", True
+
+
+def _view(span: Span, *, full: bool, threshold: float | None) -> SpanView:
+    display_text, truncated = _display_text(span.text, full)
+    return SpanView(
+        entity_type=str(span.entity_type),
+        score=span.score,
+        validated=span.validated,
+        start=span.start,
+        end=span.end,
+        display_text=display_text,
+        truncated=truncated,
+        steps=tuple(span.explanation),
+        threshold=threshold,
+    )
+
+
+def suggested_threshold(score: float) -> float:
+    """The largest multiple of 0.05 at or below `score` -- low enough that
+    setting entities.<TYPE>.threshold to this value would have caught this
+    exact span, with a small margin against float rounding."""
+    return math.floor(score * 20) / 20
+
+
+def run_explain(text: str, root_config: RootConfig, *, full: bool = False) -> ExplainResult:
+    compiled = compile_config(root_config)
+
+    accepted, rejected = detect(
+        text,
+        min_confidence=DEFAULT_MIN_CONFIDENCE,
+        return_rejected=True,
+        **compiled.detect_kwargs(),
+    )
+
+    masked = [_view(s, full=full, threshold=None) for s in accepted]
+    near_misses = [
+        _view(
+            s,
+            full=full,
+            threshold=compiled.per_entity_threshold.get(s.entity_type, DEFAULT_MIN_CONFIDENCE),
+        )
+        for s in rejected
+    ]
+    return ExplainResult(text_length=len(text), masked=masked, near_misses=near_misses)

maskflow_cli-0.2.0/src/maskflow_cli/explain_render.py

@@ -0,0 +1,113 @@
+"""Rich rendering for `maskflow explain`. Kept separate from explain.py's
+pure data assembly so the view-building logic is testable without a
+console."""
+
+from __future__ import annotations
+
+from maskflow_core.entities import ExplanationStep
+from rich.console import Console
+
+from .explain import ExplainResult, SpanView, suggested_threshold
+
+# Fixed width for the same reason as doctor_render.py: predictable wrapping
+# under a non-tty (CI logs, CliRunner in tests).
+CONSOLE_WIDTH = 100
+
+
+def _format_delta(delta: float) -> str:
+    return f"+{delta}" if delta >= 0 else str(delta)
+
+
+def _step_line(step: ExplanationStep) -> str:
+    if step.rule.startswith(("pattern:", "ner:")):
+        return f"{step.rule} {step.outcome}"
+    if step.rule == "checksum":
+        return f"checksum {step.outcome} ({_format_delta(step.delta)})"
+    if step.rule == "context":
+        if step.outcome == "not_configured":
+            return "context: no context keywords configured for this entity"
+        if step.outcome == "boosted":
+            return f"context: {step.detail} ({_format_delta(step.delta)})"
+        return f"context: {step.detail}"
+    if step.rule == "threshold":
+        return f"threshold: {step.detail}"
+    if step.rule == "overlap:contained":
+        return f"overlap: preferred {step.detail}"
+    if step.rule == "merge":
+        return f"merge: {step.detail}"
+    return f"{step.rule}: {step.outcome} {step.detail}".strip()
+
+
+def _render_span(console: Console, label: str, view: SpanView) -> None:
+    header = f"[{label}] {view.entity_type:<16} score {view.score:.2f}   "
+    if view.threshold is not None:
+        header += f"threshold {view.threshold:.2f}   "
+    else:
+        header += f"validated {'✓' if view.validated else '—'}   "
+    header += f"span {view.start}:{view.end}"
+    # markup=False: `header`/`match_line`/step text are literal (may contain
+    # bracket labels like "[a]" or an actual matched value) -- Rich's markup
+    # parser would otherwise try to interpret "[a]" as a style tag and drop it.
+    console.print(header, markup=False)
+
+    match_line = f'    match  "{view.display_text}"'
+    if view.truncated:
+        match_line += "   (--full to show entire match)"
+    console.print(match_line, markup=False)
+
+    for step in view.steps:
+        if step.rule == "threshold":
+            continue  # rendered as the closing "dropped --" line instead
+        console.print(f"    │ {_step_line(step)}", markup=False)
+
+    if view.threshold is not None:
+        console.print(
+            f"    └ [red]dropped — score {view.score:.2f} < threshold {view.threshold:.2f}[/red]"
+        )
+    else:
+        console.print("    └ [green]masked[/green]")
+    console.print()
+
+
+def _render_fixit(console: Console, view: SpanView) -> None:
+    assert view.threshold is not None
+    suggestion = suggested_threshold(view.score)
+    console.print(
+        f"    Not detected: {view.entity_type} scored {view.score:.2f}, "
+        f"below threshold {view.threshold:.2f}."
+    )
+    console.print("    To catch it, add to .maskflowrc (project root):\n")
+    console.print(f"        [entities.{view.entity_type}]", markup=False)
+    console.print(f"        threshold = {suggestion:g}")
+    console.print()
+
+
+def render_explain(console: Console, result: ExplainResult) -> None:
+    if not result.masked and not result.near_misses:
+        console.print(f"Analyzed {result.text_length} chars. No PII detected.")
+        return
+
+    near_miss_word = "near miss" if len(result.near_misses) == 1 else "near misses"
+    console.print(
+        f"Analyzed {result.text_length} chars. "
+        f"{len(result.masked)} span(s) masked, {len(result.near_misses)} {near_miss_word}.\n"
+    )
+
+    for i, view in enumerate(result.masked, start=1):
+        _render_span(console, str(i), view)
+
+    if result.near_misses:
+        console.print("[bold]NEAREST MISSES[/bold] — below threshold, not masked\n")
+        for i, view in enumerate(result.near_misses):
+            label = chr(ord("a") + i)
+            _render_span(console, label, view)
+            _render_fixit(console, view)
+
+    console.print(
+        f"{len(result.masked)} span(s) masked · {len(result.near_misses)} near miss(es) shown "
+        "· no raw PII written to any log"
+    )
+
+
+def make_console() -> Console:
+    return Console(width=CONSOLE_WIDTH)

maskflow_cli-0.2.0/src/maskflow_cli/render.py

@@ -0,0 +1,77 @@
+"""Rendering for `maskflow config show`/`show --resolved`. Both redact
+exclusions.values in every code path -- those are free-form user text that
+could itself be PII-shaped, so the raw literal is never printed (see
+CLAUDE.md rule 1: never log/print PII).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from typing import Any
+
+import tomli_w
+from maskflow_core.config.merge import flatten_leaves
+from maskflow_core.config.resolve import ResolvedConfig
+
+_SECTION_ORDER = {"maskflow": 0, "entities": 1, "custom": 2, "exclusions": 3}
+
+
+def _redact_value(value: str) -> str:
+    if len(value) <= 2:
+        return "*" * len(value)
+    return value[0] + "*" * (len(value) - 2) + value[-1]
+
+
+def _redact_values_list(values: list[str]) -> list[str]:
+    return [_redact_value(v) for v in values]
+
+
+def _sort_key(path: tuple[str, ...]) -> tuple[Any, ...]:
+    return (_SECTION_ORDER.get(path[0], 99), *path[1:])
+
+
+def format_resolved(resolved: ResolvedConfig) -> str:
+    """One aligned line per leaf field: `path = value   (origin)`."""
+    leaves = flatten_leaves(asdict(resolved.config))
+    leaves.sort(key=lambda item: _sort_key(item[0]))
+
+    rows: list[tuple[str, str, str]] = []
+    for path, value in leaves:
+        if path[0] == "exclusions" and path[-1] == "values":
+            value = _redact_values_list(value)
+        prov = resolved.provenance.get(path)
+        origin = prov.describe() if prov is not None else "default"
+        rows.append((".".join(path), json.dumps(value), origin))
+
+    if not rows:
+        return ""
+
+    key_width = max(len(key) for key, _, _ in rows)
+    value_width = max(len(value) for _, value, _ in rows)
+    return "\n".join(
+        f"{key.ljust(key_width)} = {value.ljust(value_width)}   ({origin})"
+        for key, value, origin in rows
+    )
+
+
+def _strip_none(value: Any) -> Any:
+    """TOML has no null type -- drop None-valued keys (e.g. an unset
+    EntityConfig.threshold/strategy, meaning "inherit the default") rather
+    than fail to serialize them."""
+    if isinstance(value, dict):
+        return {k: _strip_none(v) for k, v in value.items() if v is not None}
+    if isinstance(value, list):
+        return [_strip_none(v) for v in value]
+    return value
+
+
+def format_show(resolved: ResolvedConfig) -> str:
+    """Plain TOML dump of the merged, validated config -- for inspection,
+    not guaranteed round-trippable: exclusions.values is redacted, so it
+    won't read back as the original values, and unset fields (None) are
+    omitted rather than serialized."""
+    data = asdict(resolved.config)
+    if data.get("exclusions", {}).get("values"):
+        data["exclusions"]["values"] = _redact_values_list(data["exclusions"]["values"])
+    return tomli_w.dumps(_strip_none(data))

maskflow_cli-0.2.0/tests/conftest.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def fixtures_dir() -> Path:
+    return Path(__file__).parent / "fixtures"

maskflow_cli-0.2.0/tests/fixtures/partial.toml

@@ -0,0 +1,2 @@
+[entities.PAN]
+enabled = true

maskflow_cli-0.2.0/tests/fixtures/typo.toml

@@ -0,0 +1,8 @@
+[maskflow]
+packs = ["india"]
+
+[entities.PAN]
+threshod = 0.5
+
+[exclusions]
+values = ["test@example.com"]

maskflow_cli-0.2.0/tests/fixtures/valid.toml

@@ -0,0 +1,17 @@
+[maskflow]
+packs = ["india"]
+default_strategy = "replace"
+
+[entities.AADHAAR]
+enabled = true
+threshold = 0.6
+strategy = "mask"
+
+[custom.EMPLOYEE_ID]
+pattern = '\bEMP-\d{6}\b'
+score = 0.9
+context = ["employee"]
+
+[exclusions]
+values = ["test@example.com"]
+patterns = ['\bDEMO-\d+\b']

maskflow_cli-0.2.0/tests/test_cli_doctor.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import maskflow_cli.commands.doctor_cmd as doctor_cmd_module
+import maskflow_cli.doctor as doctor_module
+import maskflow_pack_intl  # noqa: F401 -- side effect: populates PATTERNS/NER_RECOGNIZERS
+import pytest
+from maskflow_cli.app import app
+from maskflow_cli.doctor import ComponentCheck, DoctorReport, EntityCheck
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+@dataclass(frozen=True)
+class _FakeEntityConfig:
+    enabled: bool
+
+
+def test_doctor_exits_nonzero_when_a_component_errors(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(
+        doctor_module,
+        "_check_spacy",
+        lambda: (
+            ComponentCheck("spaCy", None, "error", "not installed"),
+            ComponentCheck("spaCy model (en_core_web_sm)", None, "error", "unavailable"),
+        ),
+    )
+    result = runner.invoke(app, ["doctor"], env={"HOME": "/nonexistent-home"})
+    assert result.exit_code == 1
+    assert "MaskFlow Doctor" in result.stdout
+    assert "Not fully healthy" in result.stdout
+    assert "PERSON_NAME" in result.stdout
+    assert "disabled" in result.stdout
+
+
+def test_doctor_exits_zero_when_fully_healthy(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake_report = DoctorReport(
+        components=[ComponentCheck("maskflow-core", "0.3.0", "ok")],
+        entities=[EntityCheck("EMAIL", "pattern", True)],
+    )
+    monkeypatch.setattr(doctor_cmd_module, "run_checks", lambda: fake_report)
+    result = runner.invoke(app, ["doctor"])
+    assert result.exit_code == 0
+    assert "All checks passed" in result.stdout
+
+
+def test_entity_disabled_via_maskflowrc_reports_that_reason() -> None:
+    resolved = doctor_module.ResolvedConfig(
+        config=type("Cfg", (), {"entities": {"EMAIL": _FakeEntityConfig(enabled=False)}})(),
+        provenance={},
+        project_file=None,
+        user_file=None,
+    )
+    checks = doctor_module._entity_checks(resolved, spacy_ready=True)
+    email = next(c for c in checks if c.name == "EMAIL")
+    assert not email.enabled
+    assert "maskflowrc" in email.reason
+
+
+def test_entity_disabled_via_missing_spacy_model() -> None:
+    checks = doctor_module._entity_checks(None, spacy_ready=False)
+    person = next(c for c in checks if c.name == "PERSON_NAME")
+    assert not person.enabled
+    assert "spaCy" in person.reason
+
+    email = next(c for c in checks if c.name == "EMAIL")
+    assert email.enabled
+    assert email.detector == "pattern"

maskflow_cli-0.2.0/tests/test_cli_explain.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from maskflow_cli.app import app
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+def test_explain_masks_a_detected_email_and_truncates_the_match() -> None:
+    result = runner.invoke(app, ["explain", "Email me at john.doe@example.com please"])
+    assert result.exit_code == 0
+    assert "EMAIL" in result.stdout
+    assert "masked" in result.stdout
+    # Truncated to 8 chars + an ellipsis by default -- the full address
+    # (>8 chars) must never appear verbatim.
+    assert "john.doe@example.com" not in result.stdout
+    assert "john.doe" in result.stdout
+
+
+def test_explain_full_flag_shows_the_entire_match() -> None:
+    result = runner.invoke(app, ["explain", "--full", "Email me at john.doe@example.com please"])
+    assert result.exit_code == 0
+    assert "john.doe@example.com" in result.stdout
+
+
+def test_explain_reports_a_near_miss_with_a_maskflowrc_snippet() -> None:
+    result = runner.invoke(
+        app, ["explain", "Random unrelated text with a number 123456789 in it, nothing special."]
+    )
+    assert result.exit_code == 0
+    assert "NEAREST MISSES" in result.stdout
+    assert "[entities.SSN]" in result.stdout
+    assert "threshold = 0.35" in result.stdout
+    # The bare 9-digit run itself (>8 chars) must still be truncated here too.
+    assert "123456789" not in result.stdout
+
+
+def test_explain_no_pii_detected() -> None:
+    result = runner.invoke(app, ["explain", "nothing interesting here at all"])
+    assert result.exit_code == 0
+    assert "No PII detected" in result.stdout
+
+
+def test_explain_set_override_disables_an_entity() -> None:
+    result = runner.invoke(
+        app, ["explain", "--set", "entities.EMAIL.enabled=false", "Email me at a@b.com"]
+    )
+    assert result.exit_code == 0
+    assert "EMAIL" not in result.stdout
+
+
+def test_explain_lowering_threshold_via_set_promotes_a_near_miss_to_masked() -> None:
+    text = "Random unrelated text with a number 123456789 in it, nothing special."
+    result = runner.invoke(app, ["explain", "--set", "entities.SSN.threshold=0.3", text])
+    assert result.exit_code == 0
+    assert "NEAREST MISSES" not in result.stdout
+    assert "SSN" in result.stdout
+    assert "masked" in result.stdout
+
+
+def test_explain_bad_config_exits_nonzero(fixtures_dir: Path) -> None:
+    result = runner.invoke(
+        app, ["explain", "--config", str(fixtures_dir / "typo.toml"), "hello"]
+    )
+    assert result.exit_code == 1
+    assert "did you mean 'threshold'?" in result.stderr

maskflow_cli-0.2.0/tests/test_cli_show.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from maskflow_cli.app import app
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+def test_show_plain_toml(fixtures_dir: Path) -> None:
+    result = runner.invoke(app, ["config", "show", "--config", str(fixtures_dir / "valid.toml")])
+    assert result.exit_code == 0
+    assert 'default_strategy = "replace"' in result.stdout
+    # exclusions.values must never appear verbatim in output.
+    assert "test@example.com" not in result.stdout
+
+
+def test_show_resolved_annotates_provenance(fixtures_dir: Path) -> None:
+    result = runner.invoke(
+        app, ["config", "show", "--resolved", "--config", str(fixtures_dir / "valid.toml")]
+    )
+    assert result.exit_code == 0
+    assert "entities.AADHAAR.threshold = 0.6" in result.stdout
+    assert "project file:" in result.stdout
+    assert str(fixtures_dir / "valid.toml") in result.stdout
+    assert "test@example.com" not in result.stdout
+
+
+def test_show_resolved_defaults_marked_default(fixtures_dir: Path) -> None:
+    # partial.toml only sets entities.PAN.enabled -- threshold/strategy
+    # (and the whole maskflow/exclusions sections) fall back to defaults.
+    result = runner.invoke(
+        app, ["config", "show", "--resolved", "--config", str(fixtures_dir / "partial.toml")]
+    )
+    assert result.exit_code == 0
+    line = next(
+        line for line in result.stdout.splitlines() if line.startswith("entities.PAN.threshold")
+    )
+    assert "null" in line
+    assert "(default)" in line

maskflow_cli-0.2.0/tests/test_cli_validate.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from maskflow_cli.app import app
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+def test_validate_no_config_is_valid() -> None:
+    result = runner.invoke(app, ["config", "validate"], env={"HOME": "/nonexistent-home"})
+    assert result.exit_code == 0
+    assert "Config is valid" in result.stdout
+
+
+def test_validate_valid_fixture(fixtures_dir: Path) -> None:
+    result = runner.invoke(
+        app, ["config", "validate", "--config", str(fixtures_dir / "valid.toml")]
+    )
+    assert result.exit_code == 0
+    assert "Config is valid" in result.stdout
+    # entity-name soft cross-check warning for custom.EMPLOYEE_ID -- a
+    # genuinely custom type, not something any pack registers. AADHAAR (also
+    # in this fixture) no longer triggers this warning now that pack-india
+    # is wired in, so this assertion only holds because of EMPLOYEE_ID.
+    assert "WARNING" in result.stderr
+    assert "EMPLOYEE_ID" in result.stderr
+    assert "AADHAAR" not in result.stderr
+
+
+def test_validate_typo_exits_nonzero(fixtures_dir: Path) -> None:
+    result = runner.invoke(app, ["config", "validate", "--config", str(fixtures_dir / "typo.toml")])
+    assert result.exit_code == 1
+    assert "did you mean 'threshold'?" in result.stderr
+
+
+def test_validate_set_override(fixtures_dir: Path) -> None:
+    result = runner.invoke(
+        app,
+        [
+            "config",
+            "validate",
+            "--config",
+            str(fixtures_dir / "valid.toml"),
+            "--set",
+            "entities.AADHAAR.threshold=0.99",
+        ],
+    )
+    assert result.exit_code == 0
+
+
+def test_validate_set_bad_pattern_rejected(fixtures_dir: Path) -> None:
+    result = runner.invoke(
+        app,
+        [
+            "config",
+            "validate",
+            "--set",
+            "custom.BAD.pattern=(a+)+",
+            "--set",
+            "custom.BAD.score=0.9",
+        ],
+    )
+    assert result.exit_code == 1
+    assert "unsafe pattern" in result.stderr