surf-cli 0.7.0__py3-none-any.whl

surf/orchestrator.py

@@ -0,0 +1,300 @@
+# orchestrator.py
+"""Laminate models, logic, and adapters. No heading regex."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from surf import __version__
+from surf.adapters import (
+    PdfIngestError,
+    document_byte_count,
+    read_document,
+    read_pdf_catalog,
+    read_pdf_pages,
+    resolve_file,
+    resolve_tex_include,
+    write_output,
+)
+from surf.logic import (
+    exclusive_page_end,
+    extract_section,
+    format_empty_index,
+    format_empty_pdf_index,
+    format_file_index,
+    format_heading_list,
+    format_outline_list,
+    match_outline_span,
+    parse_heading_path,
+    parse_headings,
+    parse_link,
+    parse_tex_headings,
+    split_frontmatter,
+    tex_include_path,
+)
+from surf.models import (
+    CliFailure,
+    CliOptions,
+    CliSuccess,
+    CliTarget,
+    DocumentLines,
+    ErrorMessage,
+    ExitCode,
+    FileRef,
+    HeadingLevel,
+    HeadingPath,
+    HeadingPathRemainder,
+    HeadingText,
+    LineCount,
+    OutlineLevel,
+    RenderedBody,
+)
+
+type CliResult = CliSuccess | CliFailure
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="surf",
+        description="Extract markdown, TeX, or PDF outline sections with Obsidian link support.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "target",
+        nargs="?",
+        help="Link or file path: [[path#Heading]], [Text](path#Heading), or file path",
+    )
+    parser.add_argument(
+        "heading",
+        nargs="?",
+        help="Heading or outline title (when target is a plain file path)",
+    )
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--full", action="store_true", help="Output frontmatter + section content")
+    mode.add_argument(
+        "--content-only",
+        "--body-only",
+        action="store_true",
+        dest="content_only",
+        help="Section content without frontmatter (default)",
+    )
+    mode.add_argument(
+        "--frontmatter-only",
+        "-f",
+        action="store_true",
+        dest="frontmatter_only",
+        help="Output only the YAML frontmatter",
+    )
+    mode.add_argument(
+        "--list",
+        "-l",
+        action="store_true",
+        dest="list_headings",
+        help="List headings or PDF outline titles",
+    )
+    parser.add_argument(
+        "--level",
+        type=int,
+        default=None,
+        help="Max heading level when listing (1..N); exact level when extracting",
+    )
+    parser.add_argument(
+        "--no-heading", action="store_true", help="Exclude the heading line from output"
+    )
+    parser.add_argument(
+        "--output", "-o", type=str, default=None, help="Write output to file instead of stdout"
+    )
+    return parser
+
+
+def options_from_namespace(args: argparse.Namespace) -> CliOptions | CliFailure:
+    if args.target is None:
+        return CliFailure(
+            message=ErrorMessage("no target specified. Use surf --help for usage."),
+            exit_code=ExitCode(2),
+        )
+    parsed = parse_link(CliTarget(args.target))
+    heading_path = parsed.heading_path
+    if heading_path is None and args.heading is not None:
+        heading_path = parse_heading_path(HeadingPathRemainder(args.heading))
+        if heading_path is None:
+            heading_path = HeadingPath(segments=(HeadingText(args.heading),))
+    output_ref = FileRef(args.output) if args.output else None
+    return CliOptions(
+        file_ref=parsed.file_ref,
+        heading_path=heading_path,
+        list_headings=bool(args.list_headings),
+        frontmatter_only=bool(args.frontmatter_only),
+        full=bool(args.full),
+        no_heading=bool(args.no_heading),
+        level_filter=args.level,
+        output_ref=output_ref,
+    )
+
+
+def _run_pdf(path: Path, options: CliOptions) -> CliResult:
+    try:
+        catalog = read_pdf_catalog(path)
+    except PdfIngestError as exc:
+        return CliFailure(message=ErrorMessage(str(exc)), exit_code=ExitCode(1))
+    outline_level = OutlineLevel(options.level_filter) if options.level_filter is not None else None
+    if options.frontmatter_only:
+        return CliSuccess(body=RenderedBody(""))
+    if options.list_headings or options.heading_path is None:
+        if not catalog.outline:
+            return CliSuccess(
+                body=format_empty_pdf_index(
+                    page_count=catalog.page_count, byte_count=catalog.byte_count
+                )
+            )
+        return CliSuccess(body=format_outline_list(catalog.outline, level_filter=outline_level))
+    span = match_outline_span(catalog.outline, options.heading_path, level_filter=outline_level)
+    if span is None:
+        remainder = "#".join(str(seg) for seg in options.heading_path.segments)
+        return CliFailure(
+            message=ErrorMessage(f'heading "{remainder}" not found in {path}.'),
+            exit_code=ExitCode(1),
+        )
+    if span.start_page is None:
+        return CliSuccess(body=RenderedBody(""))
+    try:
+        pages = read_pdf_pages(path, span.start_page, exclusive_page_end(span))
+    except PdfIngestError as exc:
+        return CliFailure(message=ErrorMessage(str(exc)), exit_code=ExitCode(1))
+    return CliSuccess(body=RenderedBody("\n".join(pages).rstrip()))
+
+
+def run(options: CliOptions) -> CliResult:
+    if options.file_ref is None:
+        return CliFailure(
+            message=ErrorMessage("could not parse file path from target."),
+            exit_code=ExitCode(2),
+        )
+    try:
+        path = resolve_file(options.file_ref)
+    except FileNotFoundError as exc:
+        return CliFailure(message=ErrorMessage(str(exc)), exit_code=ExitCode(2))
+    if path.suffix.lower() == ".pdf":
+        return _run_pdf(path, options)
+    try:
+        lines = read_document(path)
+    except UnicodeDecodeError:
+        return CliFailure(
+            message=ErrorMessage(f"could not decode {path} as UTF-8."),
+            exit_code=ExitCode(1),
+        )
+    line_count = LineCount(len(lines))
+    byte_count = document_byte_count(path)
+    if path.suffix.lower() == ".tex":
+        lines = _expand_tex_inputs(
+            lines,
+            root_dir=path.parent,
+            current=path,
+            seen=frozenset(),
+        )
+    split = split_frontmatter(lines)
+    headings = (
+        parse_tex_headings(split.body)
+        if path.suffix.lower() == ".tex"
+        else parse_headings(split.body)
+    )
+    empty_index = format_empty_index(line_count=line_count, byte_count=byte_count)
+    heading_level = HeadingLevel(options.level_filter) if options.level_filter is not None else None
+
+    if options.list_headings:
+        if not headings:
+            return CliSuccess(body=empty_index)
+        return CliSuccess(
+            body=format_heading_list(split.body, headings=headings, level_filter=heading_level)
+        )
+    if options.frontmatter_only:
+        if split.frontmatter is None:
+            return CliSuccess(body=RenderedBody(""))
+        return CliSuccess(body=RenderedBody("\n".join(split.frontmatter)))
+
+    if options.heading_path is None:
+        if not headings and split.frontmatter is None:
+            return CliSuccess(body=empty_index)
+        return CliSuccess(
+            body=format_file_index(split, headings=headings, level_filter=heading_level)
+        )
+
+    extracted = extract_section(
+        split.body,
+        options.heading_path,
+        level_filter=heading_level,
+        headings=headings,
+    )
+    if extracted is None:
+        remainder = "#".join(str(seg) for seg in options.heading_path.segments)
+        return CliFailure(
+            message=ErrorMessage(f'heading "{remainder}" not found in {path}.'),
+            exit_code=ExitCode(1),
+        )
+
+    section_lines = extracted.lines
+    if options.no_heading and section_lines:
+        section_lines = section_lines[int(extracted.heading_line_count) :]
+    parts: list[str] = []
+    if options.full and split.frontmatter is not None:
+        parts.append("\n".join(split.frontmatter))
+    parts.append("\n".join(section_lines))
+    return CliSuccess(body=RenderedBody("\n".join(parts).rstrip()))
+
+
+def _expand_tex_inputs(
+    lines: DocumentLines,
+    *,
+    root_dir: Path,
+    current: Path,
+    seen: frozenset[Path],
+) -> DocumentLines:
+    resolved = current.resolve()
+    if resolved in seen:
+        return ()
+    loaded = seen | {resolved}
+    out: list[str] = []
+    for line in lines:
+        rel = tex_include_path(line)
+        if rel is None:
+            out.append(line)
+            continue
+        child = resolve_tex_include(root_dir, rel)
+        if child is None:
+            out.append(line)
+            continue
+        out.extend(
+            _expand_tex_inputs(
+                read_document(child),
+                root_dir=root_dir,
+                current=child,
+                seen=loaded,
+            )
+        )
+    return tuple(out)
+
+
+def run_argv(argv: Sequence[str] | None = None) -> CliResult:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    converted = options_from_namespace(args)
+    if isinstance(converted, CliFailure):
+        return converted
+    return run(converted)
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    converted = options_from_namespace(args)
+    if isinstance(converted, CliFailure):
+        print(f"Error: {converted.message}", file=sys.stderr)
+        raise SystemExit(converted.exit_code)
+    result = run(converted)
+    if isinstance(result, CliFailure):
+        print(f"Error: {result.message}", file=sys.stderr)
+        raise SystemExit(result.exit_code)
+    write_output(result.body, converted.output_ref)

surf_cli-0.7.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: surf-cli
+Version: 0.7.0
+Summary: Extract markdown, TeX, or PDF outline sections by heading with Obsidian link support
+Project-URL: Homepage, https://github.com/saintx/surf-cli
+Project-URL: Repository, https://github.com/saintx/surf-cli
+Project-URL: Issues, https://github.com/saintx/surf-cli/issues
+Project-URL: Author, https://github.com/saintx
+Author-email: "Alexander R. Saint Croix" <alex@saintx.us>
+License: MIT License
+        
+        Copyright (c) 2026 Alexander R. Saint Croix
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pypdf>=6.17.0
+Description-Content-Type: text/markdown
+
+# surf
+
+Extract one section of a markdown, TeX, or PDF file by its heading. The rest of the file never loads.
+
+```bash
+uv tool install surf-cli
+cd plugins/surf/skills/surf/references
+```
+
+A file with no heading named returns the map, frontmatter and then headings, and none of the body:
+
+```
+$ surf about.md
+---
+metadata:
+  author:
+    name: Alexander R. Saint Croix
+    github_username: saintx
+    email: alex@saintx.us
+    twitter: alexsaintx
+  surf-version: "0.7.0"
+---
+
+- Surf — About
+  - Overview
+  - When to use
+```
+
+A heading returns that section and stops at the next heading of the same or higher level:
+
+```
+$ surf about.md "When to use"
+## When to use
+
+Invoke when skimming markdown, TeX, or PDF files, checking what a file contains,
+listing structure, extracting a named address, or batch-scanning metadata across
+a directory. See `surf --help` for CLI flags. Skip when the full body is already
+needed. ...
+```
+
+The same two commands work on TeX, addressed by sectioning commands and the `abstract` environment, and on PDF, addressed by outline bookmarks. The whitepaper in this directory ships in both forms and lists the same tree from either:
+
+```
+$ surf surf.tex --list
+- abstract
+- Background
+- A Thin Index Shaped by Intent
+- Agentic Context Composition
+- Skills You Can Check
+- Indexes over Indexes
+- Markdown, TeX, and PDF
+- This Paper
+
+$ surf surf.pdf "Skills You Can Check"
+```
+
+surf exists so that agent skills can be thin. The `SKILL.md` beside these files is a table of intents, each resolving to `surf path "Heading"`, over reference material the agent never reads whole. `surf.pdf` explains why the tool was built and what that pattern makes possible.
+
+## Addressing
+
+`surf --list file.md` is the heading tree without YAML. `surf -f file.md` is YAML only. Nested paths (`Overview#Usage`) select a child when the same name appears under different parents.
+
+A heading is an address: ATX display text on markdown, brace title on TeX, the TeX `abstract` environment (addressed as `abstract`), or an outline bookmark title on PDF. On markdown and TeX the return value is that section through the next heading of the same or higher level. On PDF it is dest-to-next-dest page text; when the next dest is on the same page, that dest page is included.
+
+`--level` is 1 at the top of the heading tree. On markdown that is `#`. On TeX it is the shallowest command in the file, so `--level 1` is `\section` in an article. On PDF it is the outline's native rank. Listing with `--level N` includes ranks 1 through N. Named extract uses N as an exact match.
+
+TeX `\input` and `\include` of `.tex` files are expanded relative to the file you name. Graphics, comments, shell pipes, and macro-constructed paths are not.
+
+If the file has no headings, or a PDF has no outline, surf prints that it has no structural index, with line and byte counts on markdown and TeX, or page and byte counts on PDF. It does not dump the body.
+
+Python 3.12+. pypdf is the runtime dependency for PDF outline addressing.
+
+## Agent skill
+
+`plugins/surf` packages the skill for agents. It carries a Claude Code manifest, an Agent Plugins 1.0.0 manifest, and the skill itself at `plugins/surf/skills/surf`, in the Agent Skills format that Claude Code, Codex, Gemini CLI, Cursor, and Grok Build read.
+
+Claude Code installs it from the marketplace in this repo:
+
+```bash
+claude plugin marketplace add saintx/surf-cli
+claude plugin install surf@surf-cli
+```
+
+Any harness that reads a skills directory takes a copy of the skill:
+
+```bash
+cp -R plugins/surf/skills/surf ~/.agents/skills/surf
+```
+
+The repo also carries `.agents/skills/surf`, `.claude/skills/surf`, and `.grok/skills/surf` as symlinks into the plugin, so an agent working in this checkout has the skill available.
+
+## Install
+
+The distribution name is `surf-cli`. The command is `surf`. Python 3.12+.
+
+```bash
+uv tool install surf-cli
+surf --version
+```
+
+```bash
+pipx install surf-cli
+surf --version
+```
+
+```bash
+pip install surf-cli
+```
+
+### Nix
+
+From a local clone, install the flake into the nix profile:
+
+```bash
+nix profile install "git+file://${PWD}"
+surf --version
+```
+
+Pin a tagged release with `?ref=X.Y.Z`. If `surf` is already in the profile under a different flake URL, remove it first:
+
+```bash
+nix profile remove surf
+nix profile install "git+file://${PWD}?ref=X.Y.Z"
+```
+
+`scripts/deploy.sh` syncs, tests, and retargets the profile at the latest local semver tag.
+
+## Releasing
+
+Version locations, the bump checklist, tagging, and nix profile deployment are in [RELEASING.md](RELEASING.md).
+
+## Development
+
+```bash
+nix develop
+```
+
+## Tests
+
+```bash
+scripts/test.sh    # uv run pytest src/surf
+```

surf_cli-0.7.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+surf/__init__.py,sha256=1pXaPX_VAHeJdvB-x89tLLKyRjvp77XDIa7BjgvOdYE,144
+surf/__main__.py,sha256=ANlz65xgS_gLYkFY7rNicUva_NffRRumsnLQZJjPp1M,117
+surf/adapters.py,sha256=I0A_B85ABh-IaXCni3rfXMfPzRIdIOSe-6bZnrNQZnY,5007
+surf/logic.py,sha256=bZyRCT7SyEnzeFKik0nMb1OVQJRGcw6HHqPyXVilj2o,18540
+surf/models.py,sha256=_Cr4vJBaq_At4yCYKj2QggYvpLo-g4g4NvkXZhsqCvE,3421
+surf/orchestrator.py,sha256=zFkXukKHmk_rg5jqOAWMSyUPL3XOGu5jAgc6SaKQsOI,9726
+surf_cli-0.7.0.dist-info/METADATA,sha256=oO6IMBWRNBdNGF5H9tYRfSyLJE5JxkDFWvuJFMyftss,6460
+surf_cli-0.7.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+surf_cli-0.7.0.dist-info/entry_points.txt,sha256=vU3KRWN9HFa83zwz9ozp2pb6eaPIfnyAdjPhf64Xtdo,48
+surf_cli-0.7.0.dist-info/licenses/LICENSE,sha256=zMyNx4S0Dmu2So_ND8lf2NICO0jVbRNZeEjaGP_qgAk,1081
+surf_cli-0.7.0.dist-info/RECORD,,

surf_cli-0.7.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

surf_cli-0.7.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+surf = surf.orchestrator:main

surf_cli-0.7.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander R. Saint Croix
+
+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.