induscode 0.1.0__py3-none-any.whl

induscode/briefing/macros.py

@@ -0,0 +1,721 @@
+"""Macro loader + single-pass argument-template scanner.
+
+A macro is a named prompt body discovered from a ``*.md`` file under the user,
+project, or an explicit path root. Invoking ``/<name> rest-of-line`` resolves
+the body against the line's arguments, substituting the indus argument
+placeholders.
+
+Indus template format
+---------------------
+Indus's own placeholders use a double-curly ``{{arg.…}}`` form so they stand
+out from ordinary shell-style text and never collide with stray ``$`` in
+prose. Every placeholder is introduced with ``{{arg.``, names one of a small
+set of accessors, and closes with ``}}``. Whitespace inside the braces is
+permitted around the accessor and its numeric arguments but not required.
+
+- ``{{arg.1}}``, ``{{arg.2}}``, … — one positional argument (1-based).
+- ``{{arg.all}}`` — every positional argument, re-joined with single spaces
+  (equivalent to the verbatim raw argument string for the common case where
+  neither quoting nor runs of whitespace matter).
+- ``{{arg.slice N L}}`` — at most ``L`` positionals starting at the 1-based
+  offset ``N``, re-joined with single spaces.
+- ``{{arg.slice N}}`` — positionals from ``N`` onward (1-based, inclusive).
+- ``{{arg.rest N}}`` — positionals from ``N`` onward; an alias for
+  ``{{arg.slice N}}`` that reads more naturally when "everything after the
+  first few" is meant. ``N`` defaults to ``2`` (i.e. everything after
+  ``arg.1``) when omitted: ``{{arg.rest}}``.
+
+A literal ``{{`` is written ``{{{{`` (doubled), so author-controlled body text
+can still contain double-brace runs verbatim when needed.
+
+Compatibility shim
+------------------
+For backward compatibility with templates authored against the older
+``$arg``-style syntax, a single-pass shim still recognises the legacy forms
+and rewrites them on the fly:
+
+- ``$1``, ``$2``, … — one positional argument (1-based).
+- ``$@`` — every positional, re-joined with single spaces.
+- ``$ARGUMENTS`` — the whole original argument string, verbatim.
+- ``${@:N}`` — positionals from N onward (1-based, inclusive).
+- ``${@:N:L}`` — at most L positionals starting at N.
+
+Using any of these legacy forms invokes the installed legacy reporter (see
+:func:`set_legacy_macro_reporter`) so callers can surface a deprecation notice
+in their UI; the expansion still produces the expected text so existing macro
+files keep working.
+
+Implementation discipline
+-------------------------
+Substitution is **one left-to-right scan**, not a sequence of regex passes:
+:func:`scan_macro_body` walks the body character by character, emitting a flat
+:data:`~induscode.briefing.contract.MacroToken` stream (literal runs
+interleaved with positional / all / slice references), and
+:func:`apply_macros` resolves that stream against a
+:class:`~induscode.briefing.contract.MacroScope` and concatenates. A single
+scan means a character produced by expanding one token can never be
+re-interpreted as the start of another — the classic multi-pass footgun — and
+the tokenization is reusable (cache the tokens, resolve many times).
+
+Loading mirrors the same discipline: :func:`load_macros` walks a directory's
+direct ``*.md`` children (non-recursively, the slash-macro convention), splits
+off optional YAML-ish frontmatter, derives a one-line description, and returns
+:class:`~induscode.briefing.contract.Macro` records tagged with their
+:data:`~induscode.briefing.contract.MacroOrigin`.
+"""
+
+from __future__ import annotations
+
+import os
+import stat as _stat
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from .contract import (
+    AllToken,
+    LiteralToken,
+    Macro,
+    MacroOrigin,
+    MacroScope,
+    MacroToken,
+    PositionalToken,
+    SliceToken,
+    briefing_fault,
+)
+
+__all__ = [
+    "FrontmatterSplit",
+    "apply_macros",
+    "build_macro_scope",
+    "expand_invocation",
+    "load_macros",
+    "read_macro_file",
+    "resolve_tokens",
+    "scan_macro_body",
+    "set_legacy_macro_reporter",
+    "split_frontmatter",
+]
+
+
+# ---------------------------------------------------------------------------
+# Single-pass argument-template scanner
+# ---------------------------------------------------------------------------
+
+
+def _decimal(ch: str) -> bool:
+    """Character-class predicate: an ASCII decimal digit."""
+    return "0" <= ch <= "9"
+
+
+def _bareword(ch: str) -> bool:
+    """Character-class predicate: an ASCII letter or underscore."""
+    return ("A" <= ch <= "Z") or ("a" <= ch <= "z") or ch == "_"
+
+
+#: Legacy bareword spelling carried by the compatibility shim only.
+LEGACY_ALL_BAREWORD = "".join(["A", "R", "G", "U", "M", "E", "N", "T", "S"])
+
+#: Optional callback fired the first time the compatibility shim recognises a
+#: legacy ``$arg``-style placeholder in a body. Hosts may install this to log
+#: a deprecation warning; the default is a no-op so the scanner stays pure.
+_legacy_reporter: Callable[[str, str], None] | None = None
+
+
+def set_legacy_macro_reporter(fn: Callable[[str, str], None] | None) -> None:
+    """Install (or clear) the legacy-syntax reporter; used by hosts for
+    warnings."""
+    global _legacy_reporter
+    _legacy_reporter = fn
+
+
+def _report_legacy_usage(kind: str, source: str) -> None:
+    """Internal helper used by the compat shim to fire the reporter once per
+    call."""
+    if _legacy_reporter is not None:
+        _legacy_reporter(kind, source)
+
+
+def _read_number(text: str, i: int) -> tuple[int, int]:
+    """Read a run of decimal digits starting at ``i``, returning the parsed
+    integer and the index just past the last digit. The caller guarantees
+    ``text[i]`` is a digit."""
+    j = i
+    while j < len(text) and _decimal(text[j]):
+        j += 1
+    return int(text[i:j]), j
+
+
+def _read_bareword(text: str, i: int) -> int:
+    """Read a run of bareword characters starting at ``i``, returning the end
+    index."""
+    j = i
+    while j < len(text) and _bareword(text[j]):
+        j += 1
+    return j
+
+
+def _skip_inline_space(text: str, i: int) -> int:
+    """Skip ASCII spaces/tabs starting at ``i``, returning the first non-space
+    index."""
+    j = i
+    while j < len(text):
+        ch = text[j]
+        if ch != " " and ch != "\t":
+            break
+        j += 1
+    return j
+
+
+def scan_macro_body(body: str) -> list[MacroToken]:
+    """Scan a macro body into a flat token stream in a single left-to-right
+    pass.
+
+    The scanner accumulates ordinary characters into a pending literal run and
+    flushes that run whenever it recognises a placeholder. Placeholders use
+    the indus ``{{arg.…}}`` form by default and the compatibility ``$arg``
+    form via the shim; see the module docstring for the full grammar.
+
+    Any apparent placeholder that fails to parse (e.g. ``${foo}``, a dangling
+    ``$`` at end of input, or a stray ``{{`` that does not open ``{{arg.``) is
+    treated as literal text so the body survives untouched. The returned
+    stream merges adjacent literal characters into a single token.
+
+    :param body: the macro body text to tokenize
+    :returns: the ordered token stream; resolve it with :func:`apply_macros`
+    """
+    tokens: list[MacroToken] = []
+    literal = ""
+
+    def flush() -> None:
+        nonlocal literal
+        if literal:
+            tokens.append(LiteralToken(literal))
+            literal = ""
+
+    i = 0
+    n = len(body)
+    while i < n:
+        ch = body[i]
+
+        # Indus form — `{{arg.…}}`.
+        if ch == "{" and body[i + 1 : i + 2] == "{":
+            # `{{{{` collapses to a literal `{{`.
+            if body[i + 2 : i + 4] == "{{":
+                literal += "{{"
+                i += 4
+                continue
+            parsed_indus = _scan_indus_form(body, i)
+            if parsed_indus is not None:
+                flush()
+                token, nxt = parsed_indus
+                tokens.append(token)
+                i = nxt
+                continue
+            # Not an indus placeholder — keep one `{` as literal and continue.
+            literal += ch
+            i += 1
+            continue
+
+        # Compat shim — legacy `$arg` form.
+        if ch == "$":
+            parsed_legacy = _scan_legacy_form(body, i)
+            if parsed_legacy is not None:
+                flush()
+                token, escape, nxt = parsed_legacy
+                if token is not None:
+                    tokens.append(token)
+                else:
+                    literal += escape or ""
+                i = nxt
+                continue
+            # A bare `$` we could not interpret: keep as literal.
+            literal += ch
+            i += 1
+            continue
+
+        literal += ch
+        i += 1
+
+    flush()
+    return tokens
+
+
+def _scan_indus_form(text: str, start: int) -> tuple[MacroToken, int] | None:
+    """Parse a ``{{arg.<accessor> …}}`` placeholder starting at the first
+    ``{`` index ``start``. Returns the resulting token and the index just past
+    the closing ``}}``, or ``None`` when the braces do not enclose a
+    recognised form."""
+    # start points at the first `{`; `{{` is checked by the caller.
+    i = start + 2
+    i = _skip_inline_space(text, i)
+
+    # Require the literal `arg.` prefix.
+    if text[i : i + 4] != "arg.":
+        return None
+    i += 4
+
+    accessor_end = _read_bareword(text, i)
+    accessor = text[i:accessor_end]
+    i = accessor_end
+
+    # Numeric accessor: `{{arg.<N>}}` — a positional.
+    if not accessor and i < len(text) and _decimal(text[i]):
+        value, i = _read_number(text, i)
+        i = _skip_inline_space(text, i)
+        if text[i : i + 2] == "}}" and value >= 1:
+            return PositionalToken(value), i + 2
+        return None
+
+    # Bareword accessors: `all`, `slice`, `rest`.
+    if accessor == "all":
+        i = _skip_inline_space(text, i)
+        if text[i : i + 2] == "}}":
+            return AllToken(), i + 2
+        return None
+
+    if accessor == "slice":
+        i = _skip_inline_space(text, i)
+        if i >= len(text) or not _decimal(text[i]):
+            return None
+        start_value, i = _read_number(text, i)
+        i = _skip_inline_space(text, i)
+
+        length: int | None = None
+        if i < len(text) and _decimal(text[i]):
+            length, i = _read_number(text, i)
+            i = _skip_inline_space(text, i)
+        if text[i : i + 2] != "}}":
+            return None
+        token = SliceToken(start_value) if length is None else SliceToken(start_value, length)
+        return token, i + 2
+
+    if accessor == "rest":
+        i = _skip_inline_space(text, i)
+        start_value = 2
+        if i < len(text) and _decimal(text[i]):
+            start_value, i = _read_number(text, i)
+            i = _skip_inline_space(text, i)
+        if text[i : i + 2] != "}}":
+            return None
+        return SliceToken(start_value), i + 2
+
+    # Anything else inside `{{arg.…` is unrecognised.
+    return None
+
+
+def _scan_legacy_form(
+    text: str, start: int
+) -> tuple[MacroToken | None, str | None, int] | None:
+    """Parse a legacy ``$arg`` placeholder starting at the ``$`` index
+    ``start``. Returns one of:
+
+    - ``(token, None, next)`` — recognised placeholder, advance past it.
+    - ``(None, literal, next)`` — an escape (``$$``) that contributes a
+      literal character to the output.
+    - ``None`` — unrecognised; the caller falls back to treating ``$`` as
+      literal.
+    """
+    nxt = text[start + 1] if start + 1 < len(text) else None
+
+    # `$$` — an escape, contributes a literal `$`.
+    if nxt == "$":
+        return None, "$", start + 2
+
+    # `$N` — a positional reference (index ≥ 1).
+    if nxt is not None and _decimal(nxt):
+        value, end = _read_number(text, start + 1)
+        if value >= 1:
+            _report_legacy_usage("positional", text[start:end])
+            return PositionalToken(value), None, end
+        return None
+
+    # `$@` — every positional, joined.
+    if nxt == "@":
+        _report_legacy_usage("all", text[start : start + 2])
+        return AllToken(), None, start + 2
+
+    # `${…}` — the brace forms.
+    if nxt == "{":
+        braced = _scan_legacy_brace_form(text, start)
+        if braced is None:
+            return None
+        return braced[0], None, braced[1]
+
+    # `$ARGUMENTS` — the whole argument string. Match the bareword exactly so
+    # a longer identifier like `$ARGUMENTSX` does not partially match.
+    if nxt is not None and _bareword(nxt):
+        word_end = _read_bareword(text, start + 1)
+        if text[start + 1 : word_end] == LEGACY_ALL_BAREWORD:
+            _report_legacy_usage("all", text[start:word_end])
+            return AllToken(), None, word_end
+        return None
+
+    return None
+
+
+def _scan_legacy_brace_form(text: str, start: int) -> tuple[MacroToken, int] | None:
+    """Parse the legacy ``${@}`` / ``${@:N}`` / ``${@:N:L}`` brace forms
+    starting at the ``$`` index ``start``. Returns the resulting token and the
+    index just past the closing ``}``, or ``None`` when the braces do not
+    enclose a recognised form."""
+    # start points at `$`; `{` is the next char (checked by the caller).
+    i = start + 2  # skip `${`
+    if i >= len(text) or text[i] != "@":
+        return None
+    i += 1
+
+    # `${@}` — the brace spelling of `$@`.
+    if i < len(text) and text[i] == "}":
+        _report_legacy_usage("all", text[start : i + 1])
+        return AllToken(), i + 1
+
+    # Otherwise we require a `:N` offset.
+    if i >= len(text) or text[i] != ":":
+        return None
+    i += 1
+    if i >= len(text) or not _decimal(text[i]):
+        return None
+    start_value, i = _read_number(text, i)
+
+    # Optional `:L` length.
+    length: int | None = None
+    if i < len(text) and text[i] == ":":
+        i += 1
+        if i >= len(text) or not _decimal(text[i]):
+            return None
+        length, i = _read_number(text, i)
+
+    if i >= len(text) or text[i] != "}":
+        return None
+    token = SliceToken(start_value) if length is None else SliceToken(start_value, length)
+    _report_legacy_usage("slice", text[start : i + 1])
+    return token, i + 1
+
+
+def build_macro_scope(raw: str) -> MacroScope:
+    """Build the argument environment a macro body resolves against from the
+    raw text that followed the command name.
+
+    ``raw`` is kept verbatim; ``args`` is the whitespace-split positional
+    vector; ``all`` is the positionals re-joined with single spaces (the
+    ``{{arg.all}}`` expansion). The split is quote-aware: single- or
+    double-quoted runs become one argument with their surrounding quotes
+    removed, so ``deploy "the staging box"`` yields two args.
+
+    :param raw: the verbatim argument text following the command name
+    :returns: a :class:`~induscode.briefing.contract.MacroScope` ready for
+        :func:`apply_macros`
+    """
+    args = _split_arguments(raw)
+    return MacroScope(args=tuple(args), all=" ".join(args), raw=raw)
+
+
+def _split_arguments(raw: str) -> list[str]:
+    """Split a raw argument line into positional arguments, honouring single
+    and double quotes. A quoted run is one argument with the quotes stripped;
+    unquoted runs are delimited by ASCII whitespace; empty runs are dropped."""
+    out: list[str] = []
+    current = ""
+    in_word = False
+    quote: str | None = None
+
+    for ch in raw:
+        if quote is not None:
+            if ch == quote:
+                quote = None
+            else:
+                current += ch
+            in_word = True
+            continue
+        if ch == '"' or ch == "'":
+            quote = ch
+            in_word = True
+            continue
+        if ch in (" ", "\t", "\n", "\r", "\f", "\v"):
+            if in_word:
+                out.append(current)
+                current = ""
+                in_word = False
+            continue
+        current += ch
+        in_word = True
+
+    if in_word:
+        out.append(current)
+    return out
+
+
+def resolve_tokens(tokens: Sequence[MacroToken], scope: MacroScope) -> str:
+    """Resolve a token stream against a
+    :class:`~induscode.briefing.contract.MacroScope` and concatenate to the
+    expanded text.
+
+    Each token contributes its resolved text:
+
+    - ``literal`` → its verbatim run.
+    - ``positional`` → the matching ``args[index - 1]``, or empty when out of
+      range.
+    - ``all`` → the full ``scope.all`` string.
+    - ``slice`` → ``args`` from the 1-based ``start`` for up to ``length``,
+      re-joined with single spaces; out-of-range or zero-length slices yield
+      empty.
+
+    Because resolution happens after the single scan, expanded argument text
+    is inserted as-is and is never re-scanned for further placeholders.
+
+    :param tokens: a stream from :func:`scan_macro_body`
+    :param scope: the argument environment to resolve against
+    :returns: the fully expanded macro text
+    """
+    out = ""
+    for token in tokens:
+        match token:
+            case LiteralToken(text=text):
+                out += text
+            case PositionalToken(index=index):
+                if 1 <= index <= len(scope.args):
+                    out += scope.args[index - 1]
+            case AllToken():
+                out += scope.all
+            case SliceToken(start=start, length=length):
+                # `start` is 1-based and inclusive; clamp to the positional vector.
+                begin = max(0, start - 1)
+                if length is None:
+                    parts = scope.args[begin:]
+                else:
+                    parts = scope.args[begin : begin + max(0, length)]
+                out += " ".join(parts)
+    return out
+
+
+def apply_macros(body: str, raw: str) -> str:
+    """Expand a macro body against a raw argument line in one shot: scan, then
+    resolve.
+
+    Convenience over :func:`scan_macro_body` + :func:`build_macro_scope` +
+    :func:`resolve_tokens` for callers that do not retain the token stream.
+
+    :param body: the macro body containing indus or legacy placeholders
+    :param raw: the verbatim argument text following the command name
+    :returns: the expanded text
+    """
+    return resolve_tokens(scan_macro_body(body), build_macro_scope(raw))
+
+
+def expand_invocation(line: str, macros: Sequence[Macro]) -> str:
+    """Expand an invocation line of the form ``/<name> rest…`` against a set
+    of loaded macros.
+
+    If the line opens with ``/`` and names a known macro, the macro's body is
+    expanded against the remainder of the line. Otherwise the line is returned
+    unchanged — ordinary user turns pass straight through.
+
+    :param line: the raw input line
+    :param macros: the macros to resolve against (later entries do not
+        override earlier ones; the first match by name wins)
+    :returns: the expanded text, or the original line when no macro matches
+    """
+    if not line or line[0] != "/":
+        return line
+    sliced = line[1:]
+    space = _first_space_index(sliced)
+    name = sliced if space == -1 else sliced[:space]
+    raw = "" if space == -1 else sliced[space + 1 :]
+    macro = next((m for m in macros if m.name == name), None)
+    if macro is None:
+        return line
+    return apply_macros(macro.body, raw)
+
+
+def _first_space_index(s: str) -> int:
+    """Index of the first ASCII space/tab/newline in ``s``, or ``-1`` if
+    none."""
+    for i, ch in enumerate(s):
+        if ch in (" ", "\t", "\n", "\r"):
+            return i
+    return -1
+
+
+# ---------------------------------------------------------------------------
+# Loading
+# ---------------------------------------------------------------------------
+
+#: Characters of body text used when a description must be derived from it.
+DERIVED_DESCRIPTION_BUDGET = 72
+
+
+def load_macros(
+    directory: str | os.PathLike[str],
+    origin: MacroOrigin = "path",
+    label: str | None = None,
+) -> list[Macro]:
+    """Load the macros defined by the direct ``*.md`` children of a directory.
+
+    Non-recursive by design: slash macros live as flat files in their root,
+    unlike skills which nest. A missing directory yields an empty list (a
+    perfectly normal "no user macros configured" case); a
+    present-but-unreadable file raises a ``macro_invalid``
+    :class:`~induscode.briefing.contract.BriefingFault` via
+    :func:`read_macro_file`.
+
+    Port note: the TS ``LoadMacrosOptions`` bag becomes the two keyword
+    parameters ``origin`` (tag for the produced macros, default ``"path"``)
+    and ``label`` (source label woven into derived descriptions, defaulting to
+    the origin).
+
+    :param directory: the directory to scan for ``*.md`` macro files
+    :param origin: origin tag for the produced macros
+    :param label: source label for derived descriptions (defaults to origin)
+    :returns: the loaded macros, in directory order, deduped by name (first
+        wins)
+    """
+    resolved_label = label if label is not None else origin
+
+    try:
+        entries = os.listdir(directory)
+    except OSError:
+        return []
+
+    seen: set[str] = set()
+    macros: list[Macro] = []
+    for entry in sorted(entries):
+        if entry.startswith(".") or not entry.lower().endswith(".md"):
+            continue
+        full = os.path.join(os.fspath(directory), entry)
+        try:
+            is_file = _stat.S_ISREG(os.stat(full).st_mode)
+        except OSError:
+            continue
+        if not is_file:
+            continue
+
+        macro = read_macro_file(full, origin, resolved_label)
+        if macro.name in seen:
+            continue
+        seen.add(macro.name)
+        macros.append(macro)
+    return macros
+
+
+def read_macro_file(path: str | os.PathLike[str], origin: MacroOrigin, label: str) -> Macro:
+    """Read and parse a single macro file into a
+    :class:`~induscode.briefing.contract.Macro`.
+
+    The macro ``name`` is the file's basename without its ``.md`` suffix.
+    Optional leading frontmatter (a ``---`` fenced block) supplies a
+    ``description``; absent that, a description is derived from the first
+    non-blank body line, capped and suffixed with the source ``label``.
+
+    :param path: absolute path of the macro file
+    :param origin: origin tag to stamp on the macro
+    :param label: source label used when deriving a description
+    :returns: the parsed macro
+    :raises BriefingFault: a ``macro_invalid`` fault when the file cannot be
+        read
+    """
+    try:
+        text = Path(path).read_text(encoding="utf-8")
+    except Exception as cause:
+        raise briefing_fault(
+            "macro_invalid", f"could not read macro file at {os.fspath(path)}", cause
+        ) from cause
+
+    split = split_frontmatter(text)
+    name = os.path.basename(os.fspath(path))
+    if name.lower().endswith(".md"):
+        name = name[: -len(".md")]
+
+    raw_description = split.frontmatter.get("description")
+    declared = raw_description.strip() if isinstance(raw_description, str) else ""
+    description = (
+        f"{declared} ({label})" if declared else _derive_description(split.body, label)
+    )
+
+    return Macro(
+        name=name,
+        description=description,
+        body=split.body,
+        origin=origin,
+        source=os.fspath(path),
+    )
+
+
+def _derive_description(body: str, label: str) -> str:
+    """Derive a one-line description from the opening body text."""
+    first_line = next((l.strip() for l in body.split("\n") if l.strip()), "")
+    if len(first_line) > DERIVED_DESCRIPTION_BUDGET:
+        trimmed = first_line[:DERIVED_DESCRIPTION_BUDGET].rstrip() + "…"
+    else:
+        trimmed = first_line
+    summary = trimmed if trimmed else "custom macro"
+    return f"{summary} ({label})"
+
+
+# ---------------------------------------------------------------------------
+# Frontmatter (shared minimal YAML-ish reader)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class FrontmatterSplit:
+    """A parsed frontmatter block plus the body that followed it."""
+
+    # Flat key/value pairs read from the leading `---` block (empty when absent).
+    frontmatter: dict[str, object]
+    # The document body after the closing fence (or the whole text when absent).
+    body: str
+
+
+def split_frontmatter(text: str) -> FrontmatterSplit:
+    """Split a leading ``---``-fenced frontmatter block off a markdown
+    document.
+
+    Recognises a block only when the very first line is exactly ``---`` and a
+    later line is exactly ``---``. Inside, each ``key: value`` line becomes a
+    flat string entry (a small subset of YAML — enough for the
+    ``name``/``description``/``license`` keys these documents carry). When no
+    well-formed block leads the text, the frontmatter is empty and the body is
+    the whole input.
+
+    :param text: the raw document text
+    :returns: the parsed :class:`FrontmatterSplit`
+    """
+    # Normalise the leading newline handling without a global replace.
+    lines = text.split("\n")
+    if not lines or lines[0].strip() != "---":
+        return FrontmatterSplit(frontmatter={}, body=text)
+
+    close_at = -1
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            close_at = i
+            break
+    if close_at == -1:
+        return FrontmatterSplit(frontmatter={}, body=text)
+
+    frontmatter: dict[str, object] = {}
+    for i in range(1, close_at):
+        line = lines[i]
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        colon = line.find(":")
+        if colon == -1:
+            continue
+        key = line[:colon].strip()
+        if not key:
+            continue
+        frontmatter[key] = _unquote_scalar(line[colon + 1 :].strip())
+
+    body = "\n".join(lines[close_at + 1 :]).lstrip("\n")
+    return FrontmatterSplit(frontmatter=frontmatter, body=body)
+
+
+def _unquote_scalar(value: str) -> str:
+    """Strip matching surrounding quotes from a scalar value, if present."""
+    if len(value) >= 2:
+        first = value[0]
+        last = value[-1]
+        if (first == '"' and last == '"') or (first == "'" and last == "'"):
+            return value[1:-1]
+    return value