agent-wire-cli 0.2.1__py3-none-any.whl

agent_wire/channels/tier3_regional/xiaoyuzhou.py

@@ -0,0 +1,70 @@
+"""Xiaoyuzhou (小宇宙) podcasts: episode show notes, audio URL, optional transcript; podcast feeds."""
+
+import re
+from urllib.parse import urlsplit
+
+from agent_wire.channels.base import (
+    Channel,
+    WireUnsupported,
+    html_to_markdown,
+    listing,
+    script_json,
+    ts,
+)
+from agent_wire.media import audio_transcriber
+
+
+def page_props(html: str) -> dict:
+    data = script_json(html, "script#__NEXT_DATA__") or {}
+    return (data.get("props") or {}).get("pageProps") or {}
+
+
+def parse_episode(props: dict) -> dict:
+    ep = props.get("episode") or {}
+    if not ep:
+        raise WireUnsupported("xiaoyuzhou episode data missing")
+    notes = ep.get("shownotes") or ep.get("description") or ""
+    audio = (ep.get("enclosure") or {}).get("url") or (ep.get("media") or {}).get("source", {}).get(
+        "url"
+    )
+    return {"title": ep.get("title"), "author_handle": (ep.get("podcast") or {}).get("title"),
+            "timestamp": ts(ep.get("pubDate")), "body": html_to_markdown(notes) if "<" in notes else notes,
+            "metadata": {"length": f"{(ep.get('duration') or 0) // 60}m", "plays": ep.get("playCount"),
+                         "comments": ep.get("commentCount"), "audio": audio}}  # fmt: skip
+
+
+class XiaoyuzhouChannel(Channel):
+    name = "xiaoyuzhou"
+
+    async def read(self, url, *, query=None, section=None, include_comments=True):
+        if re.search(r"/podcast/", urlsplit(url).path):
+            return await self.feed(url)
+        f = await self.fetch(url, archive=False)
+        info = parse_episode(page_props(f.text))
+        audio = info["metadata"].get("audio")
+        if audio and audio_transcriber.enabled():
+            try:
+                transcript = await audio_transcriber.transcribe(self.ctx.pool, audio)
+                info["body"] += f"\n\n## Transcript\n{transcript}"
+            except audio_transcriber.TranscriptionUnavailable as e:
+                info["body"] += f"\n\n_Transcript unavailable: {e}_"
+        return self.doc(f, url, **info)
+
+    async def feed(self, target, *, sort="hot", limit=10):
+        url = (
+            target
+            if target.startswith("http")
+            else f"https://www.xiaoyuzhoufm.com/podcast/{target}"
+        )
+        f = await self.fetch(url, archive=False)
+        props = page_props(f.text)
+        pod = props.get("podcast") or {}
+        episodes = pod.get("episodes") or props.get("episodes") or []
+        items = [{"title": e.get("title"), "url": f"https://www.xiaoyuzhoufm.com/episode/{e.get('eid')}",
+                  "meta": [(e.get("pubDate") or "")[:10], f"{(e.get('duration') or 0) // 60}m"],
+                  "snippet": e.get("description") or ""} for e in episodes[:limit]]  # fmt: skip
+        return self.doc(f, url, title=pod.get("title") or "Xiaoyuzhou podcast", author_handle=pod.get("author"),
+                        body=(pod.get("brief") or "") + "\n\n" + listing(items))  # fmt: skip
+
+
+CHANNEL = XiaoyuzhouChannel

agent_wire/channels/tier3_regional/xueqiu.py

@@ -0,0 +1,77 @@
+"""Xueqiu (雪球): stock quotes and hot discussions, after priming the anonymous xq_a_token cookie."""
+
+import re
+from urllib.parse import quote, urlsplit
+
+from agent_wire.channels.base import Channel, WireUnsupported, html_to_markdown, ts
+from agent_wire.engine.http_pool import Fetched
+from agent_wire.engine.waterfall import WireFetchError
+from agent_wire.firewall.outbound_privacy import parse_json
+from agent_wire.models import WireComment
+
+
+def parse_quote(data: dict) -> dict:
+    q = (data.get("data") or {}).get("quote") or {}
+    if not q:
+        raise WireUnsupported("xueqiu returned no quote (unknown symbol?)")
+    lines = [f"Price: {q.get('current')} {q.get('currency') or ''} ({q.get('percent'):+}%)" if q.get("percent") is not None
+             else f"Price: {q.get('current')}",
+             f"52W: {q.get('high52w')} / {q.get('low52w')} · P/E (TTM): {q.get('pe_ttm')} · Market cap: {q.get('market_capital')}"]  # fmt: skip
+    return {"title": f"{q.get('name')} ({q.get('symbol')})", "body": "\n".join(lines),
+            "metadata": {"exchange": q.get("exchange")}}  # fmt: skip
+
+
+def parse_statuses(data: dict) -> list[WireComment]:
+    return [WireComment(id=str(s.get("id")), body=html_to_markdown(s.get("text") or s.get("description") or ""),
+                        author_handle=(s.get("user") or {}).get("screen_name"), score=s.get("like_count") or 0,
+                        timestamp=ts(s.get("created_at")))
+            for s in data.get("list", [])]  # fmt: skip
+
+
+class XueqiuChannel(Channel):
+    name = "xueqiu"
+
+    def __init__(self, ctx):
+        super().__init__(ctx)
+        self._primed = False
+
+    async def _get(self, url: str) -> Fetched:
+        if not self._primed:  # anonymous visitor cookie, kept in the shared chrome session
+            await self.ctx.pool.get("https://xueqiu.com/", impersonate="chrome")
+            self._primed = True
+        f = await self.ctx.pool.get(
+            url, impersonate="chrome", headers={"Referer": "https://xueqiu.com/"}
+        )
+        if not f.ok:
+            raise WireFetchError(
+                f"xueqiu: HTTP {f.status}; its WAF needs a JS challenge: install the stealth extra "
+                "or run `wire auth login xueqiu.com`"
+            )
+        return f
+
+    async def _stock(self, url: str, symbol: str, include_comments: bool):
+        f = await self._get(
+            f"https://stock.xueqiu.com/v5/stock/quote.json?symbol={quote(symbol)}&extend=detail"
+        )
+        info = parse_quote(parse_json(f.content))
+        if include_comments:
+            try:
+                s = await self._get("https://xueqiu.com/query/v1/symbol/search/status.json?count=15&comment=0"
+                                    f"&symbol={quote(symbol)}&hl=0&source=all&sort=alpha&page=1")  # fmt: skip
+                info["comments"] = parse_statuses(parse_json(s.content))
+            except (WireFetchError, ValueError):
+                pass
+        return self.doc(f, url, **info)
+
+    async def read(self, url, *, query=None, section=None, include_comments=True):
+        m = re.search(r"/S/([\w.]+)", urlsplit(url).path)
+        if not m:
+            return await self.ctx.channel("web").read(url, query=query, section=section)
+        return await self._stock(url, m[1].upper(), include_comments)
+
+    async def feed(self, target, *, sort="hot", limit=10):
+        sym = target.strip().upper()
+        return await self._stock(f"https://xueqiu.com/S/{sym}", sym, True)
+
+
+CHANNEL = XueqiuChannel

agent_wire/channels/tier3_regional/zhihu.py

@@ -0,0 +1,57 @@
+"""Zhihu: questions with top answers, single answers and zhuanlan articles from js-initialData."""
+
+import re
+from urllib.parse import urlsplit
+
+from agent_wire.channels.base import Channel, WireUnsupported, html_to_markdown, script_json, ts
+from agent_wire.models import WireComment
+
+
+def parse_initial(state: dict, kind: str, ident: str, answer_id: str | None = None) -> dict:
+    entities = (state.get("initialState") or {}).get("entities") or {}
+    if kind == "article":
+        a = (entities.get("articles") or {}).get(ident)
+        if not a:
+            raise WireUnsupported("zhihu article not in page state (login wall?)")
+        return {"title": a.get("title"), "author_handle": (a.get("author") or {}).get("name"),
+                "timestamp": ts(a.get("created")), "score": a.get("voteupCount"),
+                "body": html_to_markdown(a.get("content") or "")}  # fmt: skip
+    q = (entities.get("questions") or {}).get(ident) or {}
+    answers = list((entities.get("answers") or {}).values())
+    if answer_id:
+        answers = [a for a in answers if str(a.get("id")) == answer_id] or answers
+    if not q and not answers:
+        raise WireUnsupported("zhihu question not in page state (login wall?)")
+    comments = [
+        WireComment(id=str(a.get("id")), body=html_to_markdown(a.get("content") or a.get("excerpt") or ""),
+                    author_handle=(a.get("author") or {}).get("name"), score=a.get("voteupCount") or 0,
+                    timestamp=ts(a.get("createdTime")))
+        for a in answers
+    ]  # fmt: skip
+    return {"title": q.get("title"), "body": html_to_markdown(q.get("detail") or ""), "comments": comments,
+            "metadata": {"answers": q.get("answerCount"), "followers": q.get("followerCount"),
+                         "views": q.get("visitCount")}}  # fmt: skip
+
+
+class ZhihuChannel(Channel):
+    name = "zhihu"
+
+    async def read(self, url, *, query=None, section=None, include_comments=True):
+        p = urlsplit(url)
+        if (p.hostname or "").startswith("zhuanlan") and (m := re.search(r"/p/(\d+)", p.path)):
+            kind, ident, answer = "article", m[1], None
+        elif m := re.search(r"/question/(\d+)(?:/answer/(\d+))?", p.path):
+            kind, ident, answer = "question", m[1], m[2]
+        else:
+            return await self.ctx.channel("web").read(url, query=query, section=section)
+        f = await self.fetch(url, archive=False)
+        state = script_json(f.text, "script#js-initialData") or {}
+        return self.doc(f, url, **parse_initial(state, kind, ident, answer))
+
+    async def search(self, query, *, limit=5, sort="relevance"):
+        raise WireUnsupported(
+            "zhihu search needs its signed API; use platforms=['web'] with 'site:zhihu.com'"
+        )
+
+
+CHANNEL = ZhihuChannel

agent_wire/cli.py

@@ -0,0 +1,403 @@
+"""`wire` CLI: serve the MCP server, run the tools from a shell, install into clients, manage logins."""
+
+import asyncio
+import re
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from agent_wire import __version__
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="agent-wire: agents wired to the live internet.",
+)
+auth_app = typer.Typer(no_args_is_help=True, help="Local logins for wire_me and login-only sites.")
+app.add_typer(auth_app, name="auth")
+watch_app = typer.Typer(no_args_is_help=True, help="Watched topics: re-run and report what's new.")
+app.add_typer(watch_app, name="watch")
+library_app = typer.Typer(no_args_is_help=True, help="Saved research briefs: search, list, site.")
+app.add_typer(library_app, name="library")
+
+Profile = Annotated[str, typer.Option("--profile", help="standard, or local for small-VRAM models")]
+
+
+def _utf8() -> None:
+    # Windows consoles default to a legacy code page; output contains ★ ♥ · and CJK text.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+def _run(profile: str, fn) -> None:
+    from agent_wire.server import Wire
+
+    _utf8()
+
+    async def go():
+        wire = Wire(profile)
+        try:
+            return await fn(wire)
+        finally:
+            await wire.close()
+
+    typer.echo(asyncio.run(go()))
+
+
+@app.command()
+def serve(
+    profile: Profile = "standard",
+    transport: Annotated[str, typer.Option(help="stdio, http or sse")] = "stdio",
+    port: int = 8765,
+) -> None:
+    """Run the MCP server (stdio by default)."""
+    from agent_wire.server import create_server
+
+    server = create_server(profile)
+    if transport == "stdio":
+        server.run(show_banner=False)
+    else:
+        server.run(transport=transport, port=port, show_banner=False)
+
+
+@app.command()
+def read(
+    urls: list[str],
+    query: Annotated[str | None, typer.Option("--query", "-q")] = None,
+    section: str | None = None,
+    no_comments: bool = False,
+    max_tokens: int | None = None,
+    force: bool = False,
+    profile: Profile = "standard",
+) -> None:
+    """Read one or more URLs."""
+    _run(profile, lambda w: w.read(urls, query, section, not no_comments, max_tokens, force))
+
+
+@app.command()
+def search(
+    query: str,
+    platform: Annotated[list[str] | None, typer.Option("--platform", "-p")] = None,
+    limit: int = 5,
+    sort: str = "relevance",
+    expand: Annotated[int | None, typer.Option(help="top hits to auto-read")] = None,
+    max_tokens: int | None = None,
+    profile: Profile = "standard",
+) -> None:
+    """Search the web or platforms (reads the top hits too)."""
+    _run(profile, lambda w: w.search(query, platform or ["web"], limit, sort, expand, max_tokens))
+
+
+@app.command()
+def feed(
+    platform: str, target: str, sort: str = "hot", limit: int = 10, profile: Profile = "standard"
+) -> None:
+    """A subreddit, @user timeline, trending repos, market watchlist or RSS feed."""
+    _run(profile, lambda w: w.feed(platform, target, sort, limit))
+
+
+@app.command()
+def me(
+    platform: str, target: str = "latest_posts", limit: int = 5, profile: Profile = "standard"
+) -> None:
+    """Your own activity: latest_posts, likes, bookmarks, notifications, stats."""
+    _run(profile, lambda w: w.me(platform, target, limit))
+
+
+@app.command()
+def status(refresh: bool = False, profile: Profile = "standard") -> None:
+    """Channel health, sessions and route cache."""
+    _run(profile, lambda w: w.status(refresh))
+
+
+@app.command()
+def install(
+    client: Annotated[str, typer.Option("--client", "-c")] = "auto",
+    profile: Profile = "standard",
+    global_: Annotated[
+        bool, typer.Option("--global", help="user-wide config instead of this project")
+    ] = False,
+    project: Annotated[Path, typer.Option(help="project root for project-scoped clients")] = Path(
+        "."
+    ),
+    dry_run: bool = False,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="don't ask before writing")] = False,
+) -> None:
+    """Install into agent clients (auto, all, claude-code, codex, cursor, ...)."""
+    from agent_wire.installers.client_installer import detect
+    from agent_wire.installers.client_installer import install as do_install
+
+    _utf8()
+    if client == "auto" and not dry_run and not yes:
+        found = detect(project.resolve(), Path.home())
+        typer.echo(f"detected clients: {', '.join(found)}")
+        if not typer.confirm("write agent-wire into all of them?", default=True):
+            typer.echo("nothing written; pick one with --client <name>")
+            raise typer.Exit(1)
+    try:
+        results = do_install(client, project=project.resolve(), home=Path.home(), profile=profile,
+                             global_=global_, dry_run=dry_run)  # fmt: skip
+    except ValueError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+    for r in results:
+        typer.echo(f"{r.client}:")
+        for f in r.files:
+            typer.echo(f"  {'would write' if dry_run else 'wrote'} {f}")
+        for note in r.notes:
+            typer.echo(f"  note: {note}")
+
+
+@app.command()
+def research(
+    topic: Annotated[
+        str, typer.Argument(help="topic, 'A vs B', or empty for what's trending")
+    ] = "",
+    days: int = 30,
+    platform: Annotated[list[str] | None, typer.Option("--platform", "-p")] = None,
+    mode: Annotated[str, typer.Option(help="auto, topic, compare, discover, person")] = "auto",
+    depth: Annotated[str, typer.Option(help="quick, default, deep")] = "default",
+    github_user: Annotated[str | None, typer.Option(help="add this GitHub user's activity")] = None,
+    as_of: Annotated[str | None, typer.Option(help="end of the window, YYYY-MM-DD")] = None,
+    emit: Annotated[str, typer.Option(help="md, json or html")] = "md",
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="write to this file")
+    ] = None,
+    save_dir: Annotated[
+        Path | None, typer.Option(help="write <slug>.<ext> into this folder")
+    ] = None,
+    store: Annotated[bool, typer.Option(help="save the run to the local library")] = False,
+    preflight: Annotated[bool, typer.Option(help="show the plan; no network")] = False,
+    max_tokens: int | None = None,
+    profile: Profile = "standard",
+) -> None:
+    """What people said about a topic in the last N days, across sites, as one cited brief."""
+    from agent_wire.server import Wire
+
+    _utf8()
+
+    async def go():
+        wire = Wire(profile)
+        try:
+            return await wire.research(topic, days, platform, mode, depth, as_of, github_user, emit,
+                                       store, preflight, max_tokens or 100_000)  # fmt: skip
+        finally:
+            await wire.close()
+
+    text = asyncio.run(go())
+    target = output
+    if save_dir and not target:
+        slug = re.sub(r"[^a-z0-9]+", "-", (topic or "trending").lower()).strip("-")[:60] or "brief"
+        target = save_dir / f"{slug}-{days}d.{emit}"
+    if target:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text, encoding="utf-8")
+        typer.echo(f"wrote {target}")
+    else:
+        typer.echo(text)
+
+
+def _wire_call(profile: str, fn):
+    """Run fn(wire) with a Wire that is always closed; print the returned text."""
+    from agent_wire.server import Wire
+
+    _utf8()
+
+    async def go():
+        wire = Wire(profile)
+        try:
+            return await fn(wire)
+        finally:
+            await wire.close()
+
+    typer.echo(asyncio.run(go()))
+
+
+@watch_app.command("add")
+def watch_add(
+    topic: str,
+    days: int = 7,
+    platform: Annotated[list[str] | None, typer.Option("--platform", "-p")] = None,
+    webhook: Annotated[
+        str | None, typer.Option(help="POST new findings (JSON) to this URL")
+    ] = None,
+) -> None:
+    """Watch a topic; `wire watch run` reports what appeared since the last run."""
+    from agent_wire.research.planner import normalize_sources
+    from agent_wire.research.watch import check_webhook
+
+    try:
+        sources = normalize_sources(platform)
+        check_webhook(webhook)
+    except ValueError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+
+    async def add(w):
+        w.store.add_watch(topic, days, ",".join(sources) if sources else None, webhook)
+        return (
+            f"watching {topic!r} (last {days} days"
+            + (f", webhook {webhook}" if webhook else "")
+            + ")"
+        )
+
+    _wire_call("standard", add)
+
+
+@watch_app.command("list")
+def watch_list() -> None:
+    """Watched topics."""
+
+    async def ls(w):
+        rows = w.store.watches()
+        return (
+            "\n".join(
+                f"{r['topic']} · {r['days']}d · {r['sources'] or 'default sources'}"
+                + (f" · webhook {r['webhook']}" if r["webhook"] else "")
+                + (f" · last run #{r['last_run_id']}" if r["last_run_id"] else "")
+                for r in rows
+            )
+            or "no watched topics"
+        )
+
+    _wire_call("standard", ls)
+
+
+@watch_app.command("remove")
+def watch_remove(topic: str) -> None:
+    """Stop watching a topic."""
+
+    async def rm(w):
+        return f"removed {topic!r}" if w.store.remove_watch(topic) else f"not watching {topic!r}"
+
+    _wire_call("standard", rm)
+
+
+@watch_app.command("run")
+def watch_run(
+    topic: Annotated[str | None, typer.Argument(help="one topic, or all")] = None,
+) -> None:
+    """Re-run watched topics and show only new findings (schedule this with cron / Task Scheduler)."""
+    from agent_wire.research.watch import run_watches
+
+    _wire_call("standard", lambda w: run_watches(w, topic))
+
+
+@app.command()
+def brief(
+    period: Annotated[str, typer.Argument(help="daily or weekly")] = "daily",
+    no_trending: bool = False,
+) -> None:
+    """Digest across every watched topic, plus what's trending; saved under the library."""
+    from agent_wire.research.briefing import digest
+
+    _wire_call("standard", lambda w: digest(w, period, trending=not no_trending))
+
+
+@library_app.command("search")
+def library_search(query: str, limit: int = 10) -> None:
+    """Offline search over saved briefs."""
+
+    async def s(w):
+        return w.library.search_markdown(query, limit)
+
+    _wire_call("standard", s)
+
+
+@library_app.command("list")
+def library_list(limit: int = 20) -> None:
+    """Saved runs, newest first."""
+
+    async def ls(w):
+        rows = w.store.runs(limit)
+        return "\n".join(f"#{r['id']} · {r['created_at'][:16]} · {r['topic']} ({r['mode']}, {r['days']}d)"
+                         f" · {r['headline']}" for r in rows) or "library is empty (research --store)"  # fmt: skip
+
+    _wire_call("standard", ls)
+
+
+@library_app.command("show")
+def library_show(run_id: int) -> None:
+    """Print a saved brief."""
+
+    async def show(w):
+        run = w.store.run(run_id)
+        return run["markdown"] if run else f"no run #{run_id}"
+
+    _wire_call("standard", show)
+
+
+@library_app.command("feed")
+def library_feed() -> None:
+    """Build WIRE_HOME/library/index.html, feed.xml (Atom) and one page per run."""
+
+    async def build(w):
+        out = w.library.build()
+        return f"wrote {out / 'index.html'} and {out / 'feed.xml'}"
+
+    _wire_call("standard", build)
+
+
+@app.command()
+def version() -> None:
+    """Print the version."""
+    typer.echo(__version__)
+
+
+@auth_app.command("login")
+def auth_login(
+    site: str,
+    from_browser: Annotated[
+        bool, typer.Option("--from-browser", help="copy this site's cookies from a local browser")
+    ] = False,
+) -> None:
+    """Save a session for one site in the encrypted vault (the only cookies agent-wire uses).
+
+    Opens a login window (stealth extra), or with --from-browser copies the site's cookies from
+    a browser you're already logged in to.
+    """
+    from agent_wire.auth.cookie_vault import CookieVault
+    from agent_wire.config import init_wire_home
+
+    _utf8()
+    vault = CookieVault(init_wire_home())
+    if from_browser:
+        n = asyncio.run(vault.import_from_browser(site))
+        typer.echo(
+            f"saved {n} cookies for {site}" if n else f"no {site} cookies found in local browsers"
+        )
+        return
+    try:
+        n = asyncio.run(vault.interactive_login(site))
+    except ImportError as e:
+        typer.echo("wire auth login needs the stealth extra: uv tool install 'agent-wire-cli[stealth]' "
+                   "&& playwright install chromium", err=True)  # fmt: skip
+        raise typer.Exit(1) from e
+    typer.echo(f"saved {n} cookies for {site}" if n else f"no cookies captured for {site}")
+
+
+@auth_app.command("list")
+def auth_list() -> None:
+    """Sites with a saved session (names only, never values)."""
+    from agent_wire.auth.cookie_vault import CookieVault
+    from agent_wire.config import init_wire_home
+
+    domains = CookieVault(init_wire_home()).domains()
+    typer.echo("\n".join(domains) if domains else "no saved sessions")
+
+
+@auth_app.command("logout")
+def auth_logout(site: str) -> None:
+    """Forget a saved session."""
+    from agent_wire.auth.cookie_vault import CookieVault
+    from agent_wire.config import init_wire_home
+
+    removed = CookieVault(init_wire_home()).remove(site)
+    typer.echo(f"removed {site}" if removed else f"no saved session for {site}")
+
+
+if __name__ == "__main__":
+    app()

agent_wire/compression/anchor_slicer.py

@@ -0,0 +1,45 @@
+"""#L45-L120 line slicing for code and #heading section extraction for Markdown."""
+
+import re
+
+CONTEXT_LINES = 5
+
+_LINE_ANCHOR = re.compile(r"#L(\d+)(?:-L?(\d+))?$")
+_HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$")
+
+
+def parse_line_anchor(url: str) -> tuple[int, int] | None:
+    if not (m := _LINE_ANCHOR.search(url)):
+        return None
+    a, b = int(m[1]), int(m[2] or m[1])
+    return min(a, b), max(a, b)
+
+
+def slice_lines(text: str, start: int, end: int, context: int = CONTEXT_LINES) -> str:
+    lines = text.splitlines()
+    lo, hi = max(1, start - context), min(len(lines), end + context)
+    width = len(str(hi))
+    return "\n".join(f"{n:>{width}}| {lines[n - 1]}" for n in range(lo, hi + 1))
+
+
+def slugify(title: str) -> str:
+    """GitHub-style heading anchor."""
+    s = re.sub(r"[^\w\s-]", "", title.strip().lower())
+    return s.replace(" ", "-")
+
+
+def slice_section(markdown: str, section: str) -> str | None:
+    """Heading named/slugged `section` through the next heading of equal or higher level."""
+    target = slugify(section.lstrip("#"))
+    out, level, in_fence = None, 0, False
+    for line in markdown.splitlines():
+        if line.lstrip().startswith(("```", "~~~")):
+            in_fence = not in_fence
+        m = None if in_fence else _HEADING.match(line)
+        if out is not None:
+            if m and len(m[1]) <= level:
+                break
+            out.append(line)
+        elif m and slugify(m[2]) == target:
+            out, level = [line], len(m[1])
+    return "\n".join(out) if out else None