sheafmd 1.0.0__py3-none-any.whl

sheafmd/__init__.py

@@ -0,0 +1,48 @@
+"""sheaf: a working page for a markdown document, shared between a person and their agent.
+
+The library API (SPEC 16). These names stay stable through 1.x; everything else in
+the package is internal.
+
+    html = sheafmd.render(path, share=True, theme=None, title=None, toc="auto",
+                          max_image_width=1400, by=None, for_=None, credit=None, log=None)
+    sheafmd.write_pdf(html, out)                      # raises sheafmd.PdfError
+    src = sheafmd.Source(path); text, digest = src.read(); src.update(change)
+    sheafmd.strip_comments(text)                      # the share copy's comment removal
+    sheafmd.comments.parse(text)                      # comments and malformed
+    sheafmd.load_root_config(root); sheafmd.load_theme(spec, root)
+"""
+from pathlib import Path
+
+__version__ = "1.0.0"
+
+# `render` below is the public function, and it hides the module sheafmd/render.py as
+# an attribute of the package: inside the package import from it (`from .render import
+# build`), never `from . import render` or `import sheafmd.render as r`.
+
+from . import comments
+from .config import ConfigError, RootConfig, load_root_config
+from .pdf import PdfError, write_pdf
+from .render import RenderError, UnclosedComment, render_file, strip_comments
+from .source import Source, StaleError
+from .theme import Theme, load_theme
+
+__all__ = ["render", "write_pdf", "Source", "strip_comments", "comments", "load_root_config",
+           "load_theme", "RootConfig", "Theme", "PdfError", "StaleError", "ConfigError",
+           "RenderError", "UnclosedComment", "__version__"]
+
+
+def render(path, *, share: bool = True, theme=None, title: str | None = None,
+           toc: str = "auto", max_image_width: int = 1400, by: str | None = None,
+           for_: str | None = None, credit: bool | None = None,
+           log: list[str] | None = None) -> str:
+    """The HTML of the markdown file at `path`: a share copy by default, with every
+    comment removed and no script; `share=False` gives the page as the hub would serve
+    it, without the hub's meta values.
+
+    Reads the root's `.sheaf.toml` itself (`for`, `links`, `credit`, the theme). `for_`
+    replaces its `for` for this render; an empty string leaves the "for" out.
+    Every render-log line (`+` added, `!` warning, `-` removed), font failures
+    included, is appended to `log`; without one, the warnings go to stderr."""
+    return render_file(Path(path), share=share, theme=theme, title=title, toc=toc,
+                       max_image_width=max_image_width, by=by, for_=for_, credit=credit,
+                       log=log)

sheafmd/__main__.py

@@ -0,0 +1,6 @@
+"""python -m sheafmd is the same as the sheaf command."""
+import sys
+
+from .cli import main
+
+sys.exit(main())

sheafmd/_pandoc.py

@@ -0,0 +1,20 @@
+"""The one place the bundled pandoc is started (SPEC 3.2).
+
+A document can make pandoc run without end and grow without bound (pandoc 3.9: a footnote
+that cites itself, `[^1]: a [^1]`), so every call has a heap cap and a time limit. A run that
+hits either one comes back as a failed run, like a document pandoc cannot read."""
+import subprocess
+
+import pypandoc
+
+HEAP = "-M1g"      # a 470 KB document needs about 180 MB
+TIMEOUT = 120      # seconds
+
+
+def run(args: list[str], text: str) -> subprocess.CompletedProcess:
+    cmd = [pypandoc.get_pandoc_path(), *args, "+RTS", HEAP, "-RTS"]
+    try:
+        return subprocess.run(cmd, input=text, capture_output=True, text=True,
+                              encoding="utf-8", timeout=TIMEOUT)
+    except subprocess.TimeoutExpired:
+        return subprocess.CompletedProcess(cmd, 124, "", f"pandoc did not finish in {TIMEOUT} seconds")

sheafmd/agent_files/agents-snippet.md

@@ -0,0 +1,5 @@
+This project keeps documents in markdown and uses sheaf: `sheaf FILE.md` opens a page for the person and prints its URL, which you give them. Do not render text meant for pasting somewhere else (an email, a post, a commit message, a prompt, a config file): put it in the conversation.
+Before you revise a document, read its comments with `sheaf comments FILE.md`.
+After you handle a comment, reply with `sheaf reply FILE.md ID "what you did" --resolve`; never delete a comment. A message that starts "Tell from sheaf" is a comment to act on: do it, then reply with `--role action`.
+Record what goes wrong with `sheaf diag note "what went wrong"`. Never run `sheaf signin-url` yourself: it prints the hub's key; ask the person to run it.
+Every page, article, tool or document you name is a markdown link to its URL, checked with curl that it answers.

sheafmd/agent_files/claude-skill.md

@@ -0,0 +1,65 @@
+---
+name: sheaf
+description: Show a markdown document to the person as a page in their browser and work through the comments they leave on it. Use when the person wants to read, review or edit a .md document on a page, when a document has open comments to answer, or when a message that starts "Tell from sheaf" arrives.
+---
+<!-- written by sheaf init; sheaf may replace it -->
+
+# sheaf
+
+sheaf turns a markdown file into a working page for the person: they read it, edit it and leave
+comments on passages. The `.md` stays the source; whatever they do on the page lands back in it.
+You work on the same file, and you see their comments in it.
+
+## Show a document
+
+`sheaf <file>` (for example `sheaf plan.md`) starts the hub if none runs, opens the page in the
+person's browser and prints its URL. Give them that URL in your reply. Do it for what they will
+read or review: plans, reports, comparisons, specifications, handoff notes. If they would have to
+read it twice in the terminal, render it once.
+
+Do not render text meant for pasting somewhere else (an email, a post, a commit message, a
+prompt, a config file). A page gets in the way of the paste: put it in the conversation.
+
+`sheaf <file> --share` writes a copy with no comments and no script, one HTML file to send on.
+
+## Before you revise a document, read its comments
+
+    sheaf comments plan.md            # the open comments: id, author, line, the passage, the thread
+    sheaf comments plan.md --all      # the resolved ones too
+
+If the sheaf tools are connected to you (`documents`, `threads`, `reply`, `resolve`), they do the
+same. A comment sits in the `.md` right after the passage it is about. Edit the text around it
+freely; never write, change or delete a comment by hand, because the commands keep the format the
+page reads.
+
+## After you handle a comment, reply and resolve it
+
+    sheaf reply plan.md c3 "Moved the date to March and said why." --resolve
+
+Reply in the thread, and resolve it when it is done. Never delete a comment: the person reads the
+answers comment by comment. Add a comment of your own on a passage with
+`sheaf comment plan.md "the exact passage" "your note"`.
+
+## A message that starts "Tell from sheaf"
+
+The person pressed Tell on a comment: act on it in this conversation, then answer in the thread
+with the role `action`, so the page shows that you did it:
+
+    sheaf reply plan.md c3 "What you did." --role action
+
+With the tools: `reply(doc=..., id=..., text=..., role="action")`. A reply with no role is an
+answer (use it when you only answer a question and change nothing). If you cannot do what the
+comment asks, say so in the thread.
+
+## Links
+
+Every page, article, tool or document you name, in text you write into the document or in a reply, is a markdown link [words](https://full-url) to its URL, checked with curl that it answers. Link only what the text names, and never a generic page (a home page, a search page) where a specific one is meant.
+
+## When something goes wrong
+
+Record what only you can see, for the person who looks after sheaf: `sheaf diag note "what went
+wrong, and what you were doing"`. It goes to the diagnostics log on their machine, nowhere else.
+
+`sheaf signin-url` prints a URL that signs a browser in and holds the hub's key. Never run it
+yourself: the key would be in your transcript. If the person needs one, ask the person to run it
+in their own terminal. Never paste such a URL into a conversation or a file.