grison 0.1.0__tar.gz

grison-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+
+# uv / venv
+.venv/
+
+# grison private workspace dir (creds + state) — never commit
+.grison/
+
+# grison workspace content — real engagement data lands here after `grison sync`
+findings/
+methodology/

grison-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valiente Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grison-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: grison
+Version: 0.1.0
+Summary: A markdown hub between security scanners and Valiente's Ghostwriter + BookStack.
+Project-URL: Homepage, https://github.com/ValienteTechnologies/grison
+Project-URL: Issues, https://github.com/ValienteTechnologies/grison/issues
+Author: Valiente Technologies
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bookstack,ghostwriter,markdown,pentest,scanner,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# grison
+
+grison is a markdown hub between security scanners and Valiente's infra. It parses
+scanner exports into a single house schema of markdown findings, and reconciles a local
+git-like workspace with Ghostwriter (findings) and BookStack (methodology) via a 3-way
+sync. Markdown is the lingua franca — which also makes an LLM editing the workspace the
+transform layer, so grison itself has no AI subsystem; its job is to validate and sync
+those edits safely.
+
+## Install
+
+```sh
+uv sync           # Python 3.11+, managed with uv
+uv run grison --help
+```
+
+## The three verbs
+
+| Command | Does |
+|---|---|
+| `grison parse <path…>` | scanner export(s) → markdown findings in `findings/inbox/` (offline; auto-detects the scanner) |
+| `grison status <path…>` | per-record validity: schema / enums / CVSS / CWE / the GW HTML whitelist |
+| `grison sync` | reconcile the workspace with Ghostwriter + BookStack; direction derived per record |
+
+There is no `pull`/`push` (sync derives direction), no `init` (the first `sync`
+bootstraps the workspace + a `.grison/env` creds template), and no `validate` (status
+reports it, sync enforces it). Moving a finding between cells is a plain `cp`/`mv`.
+
+## Data model — a 2×2, mirrored faithfully
+
+The workspace tree *is* the model. Segment 1 = domain (backend), segment 2 = tier:
+
+```
+findings/                 # ⇄ Ghostwriter
+  inbox/                  # parse output — local-only, triage then cp into a report
+  library/                # ⇄ GW finding table
+  reports/<id>-<slug>/    # ⇄ GW reportedFinding — one dir per EXISTING report
+    <rfid>-<slug>.md
+    evidence/*.png        # images attached to a finding
+methodology/              # ⇄ BookStack
+  library/<book>/<page>.md
+  checklists/<engagement>/  # per-engagement copies — local-only, cp -r from library/
+.grison/                  # creds + state; always gitignored
+```
+
+**Location is identity.** A file's directory fixes its remote target; sync matches by
+remote id, not filename (filenames are cosmetic). A file whose location disagrees with
+its stored id is a *move* → a new record — which is all the old
+`instantiate`/`promote` verbs did. grison syncs findings + evidence into reports it
+never creates.
+
+## Finding markdown schema (by example)
+
+One tier-agnostic schema; structured facts in frontmatter, prose in fixed `##` sections.
+
+```markdown
+---
+grison:
+  kind: finding
+  tier: instance            # library | instance
+  gw: { table: reportedFinding, id: 183, report_id: 6 }
+  synced: { hash: sha256:…, at: 2026-07-14T12:00:00Z }  # the 3-way merge base
+severity: high              # informational|low|medium|high|critical
+finding_type: web           # network|physical|wireless|web|mobile|cloud|host
+cvss: { vector: "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H", score: 9.8 }
+cwe: ["CWE-79"]             # validated against the embedded CWE index
+affected_entities: |        # instances only
+  https://app.example/
+evidence:                   # instances only; images attached to this finding
+  - { file: evidence/shell.png, caption: Shell, friendly_name: shell, gw: { id: 38, hash: sha256:… } }
+---
+
+# {title}
+## Description
+## Impact
+## Mitigation
+## Replication Steps
+## References
+```
+
+The pydantic models in `grison/model/` **are** the schema; enums carry their Ghostwriter
+ids (derived, never stored). CVSS accepts well-formed 3.0 or 3.1 as-authored.
+
+## Converter whitelist (markdown ⇄ Ghostwriter HTML)
+
+GW's rich-text fields use a tiny closed vocabulary, and the converter (`grison/markdown/`)
+fails loudly on anything outside it rather than corrupt silently:
+
+- Inline: `**bold**` ⇄ `<strong>`, `` `code` `` ⇄ `<code>`, `*em*` ⇄ `<em>`, `[t](u)` ⇄ `<a>`.
+- Block: paragraphs ⇄ `<p>`, `- ` lists ⇄ `<ul><li>` (never `<ol>`).
+- Rejected in a field: tables, ordered lists, images, headings. The `##` section headers
+  are grison structure that map to GW's separate fields, not field content.
+
+(BookStack methodology pages are markdown-native, so they mirror verbatim — no converter.)
+
+## Sync + guardrails
+
+Direction isn't chosen — the 3-way base (`synced.hash`) *determines* it per record:
+only-local-changed → push, only-remote → pull, both → **collision** (the remote side is
+written to an `x.remote.md` sidecar; local is never overwritten — resolve then
+`sync --force-local/--force-remote <file>`), converged-under-a-stale-base → repair.
+
+Guardrails stop **anomalous or destructive outcomes**, never routine ones (no
+confirmation nagging; `--dry-run` is opt-in). Three layers: validation (silent when
+green), trip-wires that fire only on anomaly (mass-change guard, structure drift,
+collision, duplicate identity, broken link), and a pre-write **snapshot** of every remote
+write batch (with a paired `rollback.py`) so every write is reversible.

grison-0.1.0/README.md

@@ -0,0 +1,107 @@
+# grison
+
+grison is a markdown hub between security scanners and Valiente's infra. It parses
+scanner exports into a single house schema of markdown findings, and reconciles a local
+git-like workspace with Ghostwriter (findings) and BookStack (methodology) via a 3-way
+sync. Markdown is the lingua franca — which also makes an LLM editing the workspace the
+transform layer, so grison itself has no AI subsystem; its job is to validate and sync
+those edits safely.
+
+## Install
+
+```sh
+uv sync           # Python 3.11+, managed with uv
+uv run grison --help
+```
+
+## The three verbs
+
+| Command | Does |
+|---|---|
+| `grison parse <path…>` | scanner export(s) → markdown findings in `findings/inbox/` (offline; auto-detects the scanner) |
+| `grison status <path…>` | per-record validity: schema / enums / CVSS / CWE / the GW HTML whitelist |
+| `grison sync` | reconcile the workspace with Ghostwriter + BookStack; direction derived per record |
+
+There is no `pull`/`push` (sync derives direction), no `init` (the first `sync`
+bootstraps the workspace + a `.grison/env` creds template), and no `validate` (status
+reports it, sync enforces it). Moving a finding between cells is a plain `cp`/`mv`.
+
+## Data model — a 2×2, mirrored faithfully
+
+The workspace tree *is* the model. Segment 1 = domain (backend), segment 2 = tier:
+
+```
+findings/                 # ⇄ Ghostwriter
+  inbox/                  # parse output — local-only, triage then cp into a report
+  library/                # ⇄ GW finding table
+  reports/<id>-<slug>/    # ⇄ GW reportedFinding — one dir per EXISTING report
+    <rfid>-<slug>.md
+    evidence/*.png        # images attached to a finding
+methodology/              # ⇄ BookStack
+  library/<book>/<page>.md
+  checklists/<engagement>/  # per-engagement copies — local-only, cp -r from library/
+.grison/                  # creds + state; always gitignored
+```
+
+**Location is identity.** A file's directory fixes its remote target; sync matches by
+remote id, not filename (filenames are cosmetic). A file whose location disagrees with
+its stored id is a *move* → a new record — which is all the old
+`instantiate`/`promote` verbs did. grison syncs findings + evidence into reports it
+never creates.
+
+## Finding markdown schema (by example)
+
+One tier-agnostic schema; structured facts in frontmatter, prose in fixed `##` sections.
+
+```markdown
+---
+grison:
+  kind: finding
+  tier: instance            # library | instance
+  gw: { table: reportedFinding, id: 183, report_id: 6 }
+  synced: { hash: sha256:…, at: 2026-07-14T12:00:00Z }  # the 3-way merge base
+severity: high              # informational|low|medium|high|critical
+finding_type: web           # network|physical|wireless|web|mobile|cloud|host
+cvss: { vector: "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H", score: 9.8 }
+cwe: ["CWE-79"]             # validated against the embedded CWE index
+affected_entities: |        # instances only
+  https://app.example/
+evidence:                   # instances only; images attached to this finding
+  - { file: evidence/shell.png, caption: Shell, friendly_name: shell, gw: { id: 38, hash: sha256:… } }
+---
+
+# {title}
+## Description
+## Impact
+## Mitigation
+## Replication Steps
+## References
+```
+
+The pydantic models in `grison/model/` **are** the schema; enums carry their Ghostwriter
+ids (derived, never stored). CVSS accepts well-formed 3.0 or 3.1 as-authored.
+
+## Converter whitelist (markdown ⇄ Ghostwriter HTML)
+
+GW's rich-text fields use a tiny closed vocabulary, and the converter (`grison/markdown/`)
+fails loudly on anything outside it rather than corrupt silently:
+
+- Inline: `**bold**` ⇄ `<strong>`, `` `code` `` ⇄ `<code>`, `*em*` ⇄ `<em>`, `[t](u)` ⇄ `<a>`.
+- Block: paragraphs ⇄ `<p>`, `- ` lists ⇄ `<ul><li>` (never `<ol>`).
+- Rejected in a field: tables, ordered lists, images, headings. The `##` section headers
+  are grison structure that map to GW's separate fields, not field content.
+
+(BookStack methodology pages are markdown-native, so they mirror verbatim — no converter.)
+
+## Sync + guardrails
+
+Direction isn't chosen — the 3-way base (`synced.hash`) *determines* it per record:
+only-local-changed → push, only-remote → pull, both → **collision** (the remote side is
+written to an `x.remote.md` sidecar; local is never overwritten — resolve then
+`sync --force-local/--force-remote <file>`), converged-under-a-stale-base → repair.
+
+Guardrails stop **anomalous or destructive outcomes**, never routine ones (no
+confirmation nagging; `--dry-run` is opt-in). Three layers: validation (silent when
+green), trip-wires that fire only on anomaly (mass-change guard, structure drift,
+collision, duplicate identity, broken link), and a pre-write **snapshot** of every remote
+write batch (with a paired `rollback.py`) so every write is reversible.

grison-0.1.0/grison/__init__.py

@@ -0,0 +1,9 @@
+"""grison — a markdown hub between security scanners and Valiente's infra.
+
+Everything is a *source*, *transform*, or *sink* of markdown. See the module
+layout (ports & adapters): ``model`` (schema), ``scanners`` (source adapters),
+``markdown`` (serialization + HTML⇄md converter), ``sinks`` (file sink),
+``remote`` (Ghostwriter + BookStack), and ``cli``.
+"""
+
+__version__ = "0.1.0"

grison-0.1.0/grison/cli.py

@@ -0,0 +1,304 @@
+"""grison CLI — three verbs: ``parse``, ``status``, ``sync``.
+
+The path names the backend (``findings/`` ⇄ Ghostwriter, ``methodology/`` ⇄
+BookStack); location decides identity; the first ``sync`` bootstraps the workspace.
+``parse`` and ``status`` are offline; ``sync`` reconciles findings with Ghostwriter
+and methodology with BookStack (push/pull/collision derived per record).
+"""
+
+from __future__ import annotations
+
+import fcntl
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from grison.model import FindingType
+from grison.remote.bookstack import BookStackClient
+from grison.remote.bootstrap import bootstrap_workspace
+from grison.remote.creds import MissingCreds
+from grison.remote.creds import load as load_creds
+from grison.remote.ghostwriter import GhostwriterClient
+from grison.remote.methodology import MethResult, sync_methodology
+from grison.remote.sync import SyncResult
+from grison.remote.sync import sync as run_sync
+from grison.sinks import ParseSummary, run_parse
+from grison.validate import validate_file
+from grison.workspace import bootstrap_tree, inbox_dir
+
+app = typer.Typer(
+    name="grison",
+    help="A markdown hub between security scanners and Valiente's Ghostwriter + BookStack.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.callback()
+def _root() -> None:
+    """grison — parse scanner artifacts to markdown, then status/sync with the remotes."""
+
+
+@app.command()
+def parse(
+    paths: Annotated[list[Path], typer.Argument(help="Scanner export file(s) or dir(s).")],
+    scanner: Annotated[
+        str | None,
+        typer.Option("--scanner", help="Force a scanner type instead of auto-detecting."),
+    ] = None,
+    out: Annotated[
+        Path | None,
+        typer.Option("-o", "--out", help="Output dir (default: findings/inbox/)."),
+    ] = None,
+    finding_type: Annotated[
+        FindingType | None,
+        typer.Option("--finding-type", help="Override the per-scanner finding-type default."),
+    ] = None,
+    min_severity: Annotated[
+        str | None,
+        typer.Option("--min-severity", help="Keep only e.g. 'high,critical' or 'medium-critical'."),
+    ] = None,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Preview without writing.")] = False,
+) -> None:
+    """Turn scanner export(s) into markdown findings in findings/inbox/ (offline)."""
+    if out is None:
+        bootstrap_tree(Path.cwd())  # the binary scaffolds; no init
+        out_dir = inbox_dir(Path.cwd())
+    else:
+        out_dir = out
+    summary = run_parse(
+        paths,
+        out_dir,
+        scanner=scanner,
+        finding_type=finding_type,
+        min_severity=min_severity,
+        dry_run=dry_run,
+    )
+    _print_parse_summary(summary, out_dir, dry_run=dry_run)
+    if summary.errors:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def status(
+    paths: Annotated[list[Path], typer.Argument(help="Finding markdown file(s) or dir(s).")],
+) -> None:
+    """Report per-record validity (schema / enum / CVSS / CWE / GW whitelist)."""
+    files = _resolve_md(paths)
+    if not files:
+        typer.secho("no markdown files found", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=0)
+
+    invalid = 0
+    for f in files:
+        errors = validate_file(f)
+        if errors:
+            invalid += 1
+            typer.secho(f"INVALID  {f}", fg=typer.colors.RED)
+            for e in errors:
+                typer.echo(f"           - {e}")
+        else:
+            typer.secho(f"valid    {f}", fg=typer.colors.GREEN)
+
+    valid = len(files) - invalid
+    typer.echo("")
+    fg = typer.colors.RED if invalid else typer.colors.GREEN
+    typer.secho(f"{valid} valid, {invalid} invalid", fg=fg)
+    if invalid:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def sync(
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Preview the plan, write nothing (== status).")
+    ] = False,
+    force_local: Annotated[
+        Path | None,
+        typer.Option("--force-local", help="Resolve a file's collision by taking local (push)."),
+    ] = None,
+    force_remote: Annotated[
+        Path | None,
+        typer.Option("--force-remote", help="Resolve a file's collision by taking remote (pull)."),
+    ] = None,
+) -> None:
+    """Reconcile the workspace with Ghostwriter — push/pull/collision derived per record.
+
+    Bootstraps on first run. Direction isn't chosen: a locally-edited record pushes, a
+    remote-changed one pulls, and a record changed on both sides is surfaced (never
+    overwritten). Every remote write is snapshot-backed.
+    """
+    root = Path.cwd()
+    boot = bootstrap_workspace(root)
+    creds = load_creds(root)
+    try:
+        creds.require_ghostwriter()
+    except MissingCreds as e:
+        if boot.env_created:
+            typer.secho(f"Scaffolded workspace + wrote {boot.env_path}", fg=typer.colors.GREEN)
+        typer.secho(str(e), fg=typer.colors.YELLOW)
+        raise typer.Exit(code=1) from None
+
+    fl = {force_local.resolve()} if force_local else set()
+    fr = {force_remote.resolve()} if force_remote else set()
+    with _workspace_lock(root):  # one sync at a time per workspace (GW has no compare-and-swap)
+        with GhostwriterClient(creds) as client:
+            result = run_sync(root, client, dry_run=dry_run, force_local=fl, force_remote=fr)
+        _print_sync_summary(result, dry_run=dry_run)
+        bad = bool(
+            result.collisions or result.invalid or result.mass_change_blocked or result.errors
+        )
+
+        if creds.bs_url and creds.bs_token_id and creds.bs_token_secret:
+            with BookStackClient(creds) as bs:
+                m = sync_methodology(root, bs, dry_run=dry_run, force_local=fl, force_remote=fr)
+            _print_meth_summary(m, dry_run=dry_run)
+            bad = bad or bool(
+                m.collisions or m.invalid or m.drift or m.artifacts
+                or m.mass_change_blocked or m.errors
+            )
+
+    if bad:
+        raise typer.Exit(code=1)
+
+
+@contextmanager
+def _workspace_lock(root: Path) -> Iterator[None]:
+    """Serialize sync runs per workspace via an exclusive flock on .grison/lock."""
+    lock_path = root / ".grison" / "lock"
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    fh = lock_path.open("w", encoding="utf-8")
+    try:
+        try:
+            fcntl.flock(fh, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            typer.secho(
+                "another grison sync is already running in this workspace (.grison/lock held)",
+                fg=typer.colors.RED,
+            )
+            raise typer.Exit(code=1) from None
+        yield
+    finally:
+        fcntl.flock(fh, fcntl.LOCK_UN)
+        fh.close()
+
+
+def _print_meth_summary(m: MethResult, *, dry_run: bool) -> None:
+    tense = "would " if dry_run else ""
+    typer.secho(
+        f"methodology: {tense}pull {len(m.pulled)}, {tense}push {len(m.pushed)}, "
+        f"{tense}create {len(m.created)}  ({len(m.unchanged)} clean, {len(m.repaired)} repaired)",
+        fg=typer.colors.GREEN,
+    )
+    if m.snapshot_dir:
+        typer.echo(f"snapshot: {m.snapshot_dir}")
+    if m.mass_change_blocked:
+        typer.secho(
+            "MASS-CHANGE GUARD tripped on methodology — writes withheld.", fg=typer.colors.RED
+        )
+    for p, why in m.drift:
+        typer.secho(f"structure-drift  {p}: {why}", fg=typer.colors.RED)
+    for p, what in m.artifacts:
+        typer.secho(f"artifact  {p}: {what}", fg=typer.colors.RED)
+    if m.collisions:
+        typer.secho(
+            f"{len(m.collisions)} collision(s) — hand-merge then --force-*:", fg=typer.colors.RED
+        )
+        for p in m.collisions:
+            typer.echo(f"  ! {p}")
+    for p in m.invalid:
+        typer.secho(f"broken link  {p}", fg=typer.colors.RED)
+    for p, reason in m.skipped:
+        typer.secho(f"skipped  {p}: {reason}", fg=typer.colors.YELLOW)
+    for e in m.errors:
+        typer.secho(f"  error: {e}", fg=typer.colors.RED)
+
+
+def _print_sync_summary(result: SyncResult, *, dry_run: bool) -> None:
+    tense = "would " if dry_run else ""
+    ev = ""
+    if result.evidence_up or result.evidence_down or result.evidence_deleted:
+        ev = f"  [evidence ↑{result.evidence_up} ↓{result.evidence_down}"
+        if result.evidence_deleted:
+            ev += f" ✕{result.evidence_deleted}"
+        ev += "]"
+    typer.secho(
+        f"{tense}pull {len(result.pulled)}, {tense}push {len(result.pushed)}, "
+        f"{tense}insert {len(result.inserted)}  ({len(result.unchanged)} clean, "
+        f"{len(result.repaired)} repaired){ev}",
+        fg=typer.colors.GREEN,
+    )
+    if result.snapshot_dir:
+        typer.echo(f"snapshot: {result.snapshot_dir}")
+    if result.mass_change_blocked:
+        typer.secho(
+            "MASS-CHANGE GUARD tripped — remote writes withheld. Re-run a narrower path "
+            "or confirm with a targeted sync.",
+            fg=typer.colors.RED,
+        )
+    if result.collisions:
+        typer.secho(
+            f"{len(result.collisions)} collision(s) — hand-merge then --force-local/-remote:",
+            fg=typer.colors.RED,
+        )
+        for p in result.collisions:
+            typer.echo(f"  ! {p}  (remote at {p.with_suffix('.remote.md').name})")
+    if result.invalid:
+        typer.secho(f"{len(result.invalid)} broken link(s) (id set, no sync base) — re-link with "
+                    "--force-remote/--force-local:", fg=typer.colors.RED)
+        for p in result.invalid:
+            typer.echo(f"  ? {p}")
+    for p, reason in result.skipped:
+        typer.secho(f"skipped  {p}: {reason}", fg=typer.colors.YELLOW)
+    for e in result.errors:
+        typer.secho(f"  error: {e}", fg=typer.colors.RED)
+
+
+def _resolve_md(paths: list[Path]) -> list[Path]:
+    files: list[Path] = []
+    for p in paths:
+        if p.is_dir():
+            files.extend(sorted(p.glob("*.md")))
+        elif p.is_file():
+            files.append(p)
+    return files
+
+
+def _print_parse_summary(summary: ParseSummary, out_dir: Path, *, dry_run: bool) -> None:
+    n_files = sum(summary.files_parsed.values())
+    by_scanner = ", ".join(f"{k}: {v}" for k, v in sorted(summary.files_parsed.items()))
+    typer.secho(
+        f"Parsed {len(summary.findings)} finding(s) from {n_files} file(s)"
+        + (f" ({by_scanner})" if by_scanner else ""),
+        fg=typer.colors.GREEN,
+    )
+
+    sink = summary.sink
+    if sink is not None:
+        verb = "Would write" if dry_run else "Wrote"
+        typer.echo(f"{verb} {len(sink.written)} → {out_dir}  ({len(sink.unchanged)} unchanged)")
+
+    for path, reason in summary.skipped_files:
+        typer.secho(f"skipped  {path.name}: {reason}", fg=typer.colors.YELLOW)
+
+    if summary.warnings:
+        typer.secho(f"{len(summary.warnings)} warning(s):", fg=typer.colors.YELLOW)
+        for w in summary.warnings:
+            typer.echo(f"  - {w}")
+
+    if summary.errors:
+        typer.secho(f"{len(summary.errors)} finding(s) failed validation:", fg=typer.colors.RED)
+        for e in summary.errors:
+            typer.echo(f"  - {e}")
+
+
+def main() -> None:
+    """Console-script entry point (``grison``)."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

grison-0.1.0/grison/markdown/__init__.py

@@ -0,0 +1,33 @@
+"""Markdown layer: the HTML⇄markdown converter, Finding⇄document serialization,
+and scanner-IR → house-schema mapping.
+
+The GW field vocabulary is tiny and closed; the converter fails loudly on anything
+outside it. A Finding's prose fields are markdown; ``##`` section headers are grison
+structure that map to Ghostwriter's separate fields.
+"""
+
+from __future__ import annotations
+
+from grison.markdown.converter import ConverterError, html_to_md, md_to_html
+from grison.markdown.document import (
+    DocumentError,
+    finding_to_markdown,
+    markdown_to_finding,
+)
+from grison.markdown.mapping import (
+    MappingResult,
+    default_finding_type,
+    ir_to_finding,
+)
+
+__all__ = [
+    "ConverterError",
+    "DocumentError",
+    "MappingResult",
+    "default_finding_type",
+    "finding_to_markdown",
+    "html_to_md",
+    "ir_to_finding",
+    "markdown_to_finding",
+    "md_to_html",
+]