feat: v0.3.0 — broadcast-safety fix, reverse tool, validator & MCP hardening (#7)

Security:
- converter: h2-h6 headings (and any heading routed to the section.mrkdwn
  fallback) now entity-escape < > & in the heading text. The fallback
  previously escaped only emphasis markers, so `## <!channel>` in
  rich_text mode emitted a live broadcast. handleFallback and the
  blockquote unknown-child path were hardened the same way.

Added:
- server: block_kit_to_markdown tool (inverse conversion; lossy, warns)
- server: MCP tool annotations on all six tools
- server: block-kit-cheatsheet MCP resource + format_for_slack prompt
- validator: button/context/table/image-title/section-accessory rules
- validator: surface-aware validation (modal/home 100-block ceiling)
- converter: MaxNestingDepth guard (ErrInputTooDeeplyNested)
- internal/reverse package; block_kit re-exports the new surface

Changed:
- server: return_preview_url is a real opt-out (*bool)
- server: convert rejects unknown split values; non-loopback bind warning
- deps: slack-go/slack v0.23.0 -> v0.23.1

Fixed:
- splitter: SplitText no longer cuts inside a multi-byte UTF-8 rune
- converter: long-heading fallback truncation is rune-safe, no dangling \

ci: coverage gate now enforces >=80% per package, not just overall.

Author: hishamkaram

.github/workflows/ci.yml

@@ -31,31 +31,48 @@ jobs:
       - name: Coverage report
         run: go tool cover -func=cover.out
 
-      - name: Coverage gate (≥80% on listed packages)
-        # Per research.md §8 mandate: block_kit + the four conversion-engine
-        # packages must hit at least 80% statement coverage. Other packages
-        # are advisory.
+      - name: Coverage gate (≥80% per package + overall)
+        # block_kit + the conversion-engine packages must each hit at least
+        # 80% statement coverage, and so must the overall figure. Per-package
+        # coverage is computed directly from the merged cover profile
+        # (count covered vs total statements, grouped by package dir) — the
+        # `go tool cover -func` output has no per-package total line.
         run: |
           set -euo pipefail
+          awk 'NR==1{next} {
+            split($1,a,":"); file=a[1];
+            n=split(file,p,"/"); dir=p[1];
+            for (i=2;i<n;i++) dir=dir"/"p[i];
+            tot[dir]+=$2; if ($3+0>0) cov[dir]+=$2
+          } END { for (d in tot) printf "%s %.1f\n", d, 100*cov[d]/tot[d] }' cover.out \
+            | sort > pkgcov.txt
+          cat pkgcov.txt
+          fail=0
           for pkg in \
             github.com/hishamkaram/mcp-slack-block-kit/block_kit \
             github.com/hishamkaram/mcp-slack-block-kit/internal/converter \
+            github.com/hishamkaram/mcp-slack-block-kit/internal/reverse \
             github.com/hishamkaram/mcp-slack-block-kit/internal/validator \
             github.com/hishamkaram/mcp-slack-block-kit/internal/splitter \
             github.com/hishamkaram/mcp-slack-block-kit/internal/preview \
           ; do
-            line=$(go tool cover -func=cover.out | awk -v p="$pkg/" '$1 ~ p && $1 ~ /total:|\.go/' | grep -E "^${pkg}/[a-z_]+\.go" | awk '{ sum += $NF; n++ } END { if (n) printf "%.1f", sum/n; else print "0" }') || line=0
-            # Fallback: use the per-file coverage average. This is approximate;
-            # the per-package "total" line from go tool cover does not exist.
-            echo "$pkg average per-file coverage: ${line}%"
+            pct=$(awk -v p="$pkg" '$1==p {print $2}' pkgcov.txt)
+            pct=${pct:-0}
+            if awk -v t="$pct" 'BEGIN { exit (t+0 >= 80 ? 0 : 1) }'; then
+              echo "OK:   $pkg ${pct}%"
+            else
+              echo "FAIL: $pkg coverage ${pct}% is below the 80% gate"
+              fail=1
+            fi
           done
-          # Hard total gate from the overall percentage.
           total=$(go tool cover -func=cover.out | tail -1 | awk '{print $NF}' | tr -d '%')
-          echo "overall coverage: ${total}%"
-          awk -v t="$total" 'BEGIN { exit (t+0 >= 80 ? 0 : 1) }' || {
+          if awk -v t="$total" 'BEGIN { exit (t+0 >= 80 ? 0 : 1) }'; then
+            echo "OK:   overall ${total}%"
+          else
             echo "FAIL: overall coverage ${total}% is below the 80% gate"
-            exit 1
-          }
+            fail=1
+          fi
+          exit $fail
 
   lint:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -15,6 +15,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.3.0] - 2026-05-15
+
+### Security
+- **converter**: h2–h6 headings — and any heading routed to the
+  `section.mrkdwn` fallback (a long h1, or an h1 containing a
+  link/image/inline code) — now entity-escape `<`, `>`, `&` in the
+  heading text. The fallback previously escaped only the emphasis
+  markers `* _ ~ \``, so a heading such as `## <!channel>` in
+  `rich_text` mode (or `auto` when the input routes to rich_text
+  decomposition) emitted a live `<!channel>` broadcast. The
+  `handleFallback` and blockquote unknown-child paths, which also build
+  text elements directly, were hardened the same way.
+  `allow_broadcasts` and `preserve_mention_tokens` are still honored.
+
+### Added
+- **server**: new `block_kit_to_markdown` MCP tool — the inverse of
+  `convert_markdown_to_block_kit`. Best-effort and lossy; constructs
+  with no Markdown equivalent (buttons, accessories, colors) are
+  approximated and reported in `warnings`.
+- **server**: all six tools now advertise MCP tool annotations
+  (`readOnlyHint`, `openWorldHint`, and a human-readable title).
+- **server**: a `block-kit-cheatsheet` MCP resource documenting the
+  conversion modes, supported/unsupported Markdown, Slack's documented
+  limits, and the mention-safety model.
+- **server**: a `format_for_slack` MCP prompt.
+- **validator**: per-element rules for buttons (text/value/url/action_id
+  lengths), context blocks (≤10 elements), table blocks (≤100 rows, ≤20
+  columns, ≤20 column_settings), image-block titles (≤2000 chars), and
+  section accessories.
+- **validator**: surface-aware validation — `ValidateForSurface` plus a
+  `surface` input on `validate_block_kit` / `lint_block_kit` raise the
+  block ceiling from 50 (messages) to 100 (modals, App Home tabs).
+- **converter**: `Options.MaxNestingDepth` (default 100) rejects
+  pathologically deep input with the new `ErrInputTooDeeplyNested`
+  sentinel — `MaxInputBytes` bounds bytes but not structural depth.
+- **block_kit**: re-exports `BlockKitToMarkdown`, the `Surface` type and
+  `SurfaceMessage`/`SurfaceModal`/`SurfaceHomeTab` constants,
+  `ErrInputTooDeeplyNested`, and `DefaultMaxNestingDepth`.
+
+### Changed
+- **server**: `convert_markdown_to_block_kit`'s `return_preview_url` is
+  now a genuine opt-out — pass `false` to skip preview-URL generation
+  (the field is a nullable bool, so omitting it still defaults to true).
+- **server**: `convert_markdown_to_block_kit` rejects an unknown `split`
+  value with a clear error instead of silently ignoring it.
+- **server**: the HTTP and SSE transports log a warning when bound to a
+  non-loopback address with no bearer token configured.
+- **deps**: `slack-go/slack` v0.23.0 → v0.23.1.
+
+### Fixed
+- **splitter**: `SplitText` no longer cuts inside a multi-byte UTF-8
+  rune when a single un-breakable token (a long CJK run, a non-ASCII
+  URL) exceeds the limit — the hard-cut now steps back to the nearest
+  rune boundary. The fuzz target gained multibyte seeds and a
+  `utf8.ValidString` invariant.
+- **converter**: the long-heading `section.mrkdwn` fallback truncation
+  is now rune-safe and strips a dangling backslash that could otherwise
+  escape the closing `*` and leave the bold run unterminated.
+
+---
+
 ## [0.2.1] - 2026-05-13
 
 ### Fixed
@@ -230,7 +291,8 @@ cosign verify-blob \
 - Slack Block Kit Builder URLs above ~8 KiB get unreliable in
   browsers/Slack — the preview tool flags those as `Truncated: true`.
 
-[Unreleased]: https://github.com/hishamkaram/mcp-slack-block-kit/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/hishamkaram/mcp-slack-block-kit/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/hishamkaram/mcp-slack-block-kit/releases/tag/v0.3.0
 [0.2.1]: https://github.com/hishamkaram/mcp-slack-block-kit/releases/tag/v0.2.1
 [0.2.0]: https://github.com/hishamkaram/mcp-slack-block-kit/releases/tag/v0.2.0
 [0.1.0]: https://github.com/hishamkaram/mcp-slack-block-kit/releases/tag/v0.1.0

CLAUDE.md

@@ -71,10 +71,11 @@ CI mirrors all of the above. Coverage gate: **≥80% overall, enforced in
 ```
 cmd/mcp-slack-block-kit/   cobra entry point (server default + convert subcommand)
 internal/converter/       goldmark renderer + emoji/mentions/markdown_block
+internal/reverse/         Block Kit → markdown (inverse of converter; lossy)
 internal/validator/       slack constraint suite + structured Violations
 internal/splitter/        SplitText + ChunkBlocks (50-block + table-isolation)
 internal/preview/         Block Kit Builder URL encoder
-internal/server/          MCP wiring (5 tools on top of go-sdk v1.6.0)
+internal/server/          MCP wiring (6 tools + cheatsheet resource + prompt)
 block_kit/                 Public Go library re-exports (semver-stable surface)
 docs/                     Public docs (CLAUDE-architecture.md, etc.)
 docs/internal/            Gitignored design notes (research.md lives here)

README.md

@@ -22,16 +22,22 @@
 
 ## What it does
 
-Five MCP tools your AI assistant can call:
+Six MCP tools your AI assistant can call:
 
 | Tool | What it does |
 |---|---|
-| **`convert_markdown_to_block_kit`** | Markdown → Block Kit JSON. Auto mode picks between Slack's new (Feb 2025) `markdown` block and full deterministic decomposition into `rich_text` / `section` / `header` / `image` / `divider`. |
-| **`validate_block_kit`** | Validates a payload against the documented Slack constraints (per-block char limits, count limits, XOR rules, `only_one_table_allowed`, the 12k-char `markdown_block` cap, etc.) with structured violations + fix hints. |
+| **`convert_markdown_to_block_kit`** | Markdown → Block Kit JSON. Auto mode picks between Slack's new (Feb 2025) `markdown` block and full deterministic decomposition into `rich_text` / `section` / `header` / `image` / `divider` / `table`. |
+| **`block_kit_to_markdown`** | The inverse — Block Kit JSON → Markdown. Best-effort and lossy; constructs with no Markdown equivalent (buttons, accessories, colors) are approximated and reported in `warnings`. |
+| **`validate_block_kit`** | Validates a payload against the documented Slack constraints (per-block char limits, count limits, button/context/table element limits, XOR rules, `only_one_table_allowed`, the 12k-char `markdown_block` cap, etc.) with structured violations + fix hints. Pass `surface` (`message` / `modal` / `home`) to set the block ceiling. |
 | **`preview_block_kit`** | Returns a Block Kit Builder URL — one click to a live visual preview in Slack's own builder. No workspace credentials needed. |
 | **`lint_block_kit`** | Warns on near-limit content, deprecated patterns, and accessibility gaps (e.g. missing image `alt_text`). Always advisory. |
 | **`split_blocks`** | Splits an oversized payload into multiple Slack-API-compliant chunks on the >50-block axis, with `only_one_table_allowed` enforcement. |
 
+The server also exposes an MCP **resource** (`block-kit-cheatsheet` — the
+conversion modes, supported Markdown, Slack limits, and mention-safety
+model) and a **prompt** (`format_for_slack`) so MCP clients can discover
+how to use the tools.
+
 Plus a **`convert` CLI** for offline testing without an MCP client.
 
 ### Conversion modes
@@ -43,6 +49,18 @@ Plus a **`convert` CLI** for offline testing without an MCP client.
 | **`auto`** (default) | One Slack `markdown` block when the input is short, image-free, and contains no nested-block patterns. Otherwise full `rich_text` decomposition. | Most LLM workflows — let the converter pick. |
 | **`rich_text`** | Always full decomposition into typed `rich_text` / `section` / `header` / `image` / `divider` / `table` blocks. | When you want explicit, deterministic block shapes (e.g. for downstream styling, validation, or because you don't want to delegate rendering to Slack's `markdown` parser). |
 | **`markdown_block`** | Single Slack `markdown` block — Slack's server-side parser owns the rendering. | When the input is known-good markdown and you want the smallest possible payload. Errors if input >12,000 chars. |
+| **`section_mrkdwn`** | `section` blocks with `mrkdwn` text. | Downstream consumers that need the older `section`-based shape. |
+
+### Supported Markdown
+
+Headings, bold, italic, strikethrough, inline code, fenced code blocks,
+ordered/unordered lists (including nesting), block quotes, thematic
+breaks, links, images, GFM tables, task lists, and `:emoji:` shortcodes;
+bare URLs are auto-linked. **Not** supported: footnotes and definition
+lists (emitted as plain text); raw HTML is entity-escaped to literal
+text. In `rich_text` mode, Markdown link *titles* are dropped — Slack's
+rich-text link element has no title field (they survive in
+`markdown_block` mode).
 
 ### Nested elements
 

block_kit/block_kit.go

@@ -55,6 +55,7 @@ import (
 
 	"github.com/hishamkaram/mcp-slack-block-kit/internal/converter"
 	"github.com/hishamkaram/mcp-slack-block-kit/internal/preview"
+	"github.com/hishamkaram/mcp-slack-block-kit/internal/reverse"
 	"github.com/hishamkaram/mcp-slack-block-kit/internal/splitter"
 	"github.com/hishamkaram/mcp-slack-block-kit/internal/validator"
 )
@@ -85,17 +86,22 @@ const (
 // Slack-defined ceilings, exposed for callers that want to reference the
 // same constants as the converter.
 const (
-	MaxBlocksPerMessage  = converter.MaxBlocksPerMessage
-	MaxSectionTextChars  = converter.MaxSectionTextChars
-	MaxHeaderTextChars   = converter.MaxHeaderTextChars
-	MaxMarkdownBlockSum  = converter.MaxMarkdownBlockSum
-	MaxBlockIDChars      = converter.MaxBlockIDChars
-	DefaultMaxInputBytes = converter.DefaultMaxInputBytes
+	MaxBlocksPerMessage    = converter.MaxBlocksPerMessage
+	MaxSectionTextChars    = converter.MaxSectionTextChars
+	MaxHeaderTextChars     = converter.MaxHeaderTextChars
+	MaxMarkdownBlockSum    = converter.MaxMarkdownBlockSum
+	MaxBlockIDChars        = converter.MaxBlockIDChars
+	DefaultMaxInputBytes   = converter.DefaultMaxInputBytes
+	DefaultMaxNestingDepth = converter.DefaultMaxNestingDepth
 )
 
 // ErrInputTooLarge is returned when input exceeds Options.MaxInputBytes.
 var ErrInputTooLarge = converter.ErrInputTooLarge
 
+// ErrInputTooDeeplyNested is returned when the parsed markdown AST nests
+// deeper than Options.MaxNestingDepth.
+var ErrInputTooDeeplyNested = converter.ErrInputTooDeeplyNested
+
 // ErrMarkdownBlockTooLarge is returned when input is requested to be
 // emitted as a single Slack markdown block but exceeds the 12,000-char cap.
 var ErrMarkdownBlockTooLarge = converter.ErrMarkdownBlockTooLarge
@@ -133,6 +139,17 @@ const (
 	SeverityWarning = validator.SeverityWarning
 )
 
+// Surface identifies the Slack surface a payload targets. It sets the
+// block-count ceiling: messages allow 50 blocks, modals and App Home tabs
+// allow 100. Pass one to Validator.ValidateForSurface.
+type Surface = validator.Surface
+
+const (
+	SurfaceMessage = validator.SurfaceMessage
+	SurfaceModal   = validator.SurfaceModal
+	SurfaceHomeTab = validator.SurfaceHomeTab
+)
+
 // NewValidator returns a Validator that reports only Slack-published
 // constraint violations as errors.
 func NewValidator() *Validator { return validator.New() }
@@ -177,3 +194,14 @@ func PreviewURLString(blocks []slack.Block) (string, error) {
 
 // BuilderHost is the canonical Block Kit Builder URL prefix.
 const BuilderHost = preview.BuilderHost
+
+// --- Reverse (Block Kit → Markdown) -----------------------------------------
+
+// BlockKitToMarkdown converts a Slack Block Kit block list back into
+// Markdown — the inverse of Converter.Convert. The conversion is
+// best-effort and lossy: Block Kit can express styling and interactive
+// elements with no Markdown equivalent. The returned warnings slice names
+// every construct that could not be represented faithfully.
+func BlockKitToMarkdown(blocks []slack.Block) (markdown string, warnings []string, err error) {
+	return reverse.ToMarkdown(blocks)
+}