mdview-cli 0.1.0__py3-none-any.whl

mdview_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mdview_cli/api.py

@@ -0,0 +1,58 @@
+import httpx
+
+
+class ApiError(RuntimeError):
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class MdviewApi:
+    def __init__(self, base_url: str, token: str | None = None, timeout: float = 75):
+        self.client = httpx.Client(
+            base_url=base_url,
+            headers={"Authorization": f"Bearer {token}"} if token else {},
+            timeout=timeout,
+        )
+
+    def request(self, method: str, path: str, **kwargs):
+        try:
+            response = self.client.request(method, path, **kwargs)
+        except httpx.HTTPError as error:
+            raise ApiError(f"Could not reach mdview.io: {error}") from error
+        if response.is_error:
+            try:
+                body = response.json()
+                message = body.get("message") or body.get("error") or response.reason_phrase
+            except ValueError:
+                message = response.reason_phrase
+            raise ApiError(str(message), response.status_code)
+        return response
+
+    def create(self, title, content):
+        return self.request("POST", "/api/documents", json={"title": title, "content": content}).json()
+
+    def publish(self, title, content):
+        return self.request("POST", "/api/public/publish", json={"title": title, "content": content}).json()
+
+    def update(self, document_id, title, content, updated_at=None):
+        body = {"title": title, "content": content}
+        if updated_at:
+            body["clientUpdatedAt"] = updated_at
+        return self.request("PUT", f"/api/documents/{document_id}", json=body).json()
+
+    def share(self, document_id):
+        return self.request("POST", f"/api/documents/{document_id}/share", json={}).json()
+
+    def verify(self, document_id, status=False):
+        suffix = "/status" if status else ""
+        return self.request("GET", f"/api/documents/{document_id}/verify{suffix}").json()
+
+    def fix(self, document_id):
+        return self.request("POST", f"/api/documents/{document_id}/fix/diagrams", json={}).json()
+
+    def export_pdf(self, document_id):
+        return self.request("GET", f"/api/documents/{document_id}/export/pdf").content
+
+    def documents(self):
+        return self.request("GET", "/api/documents").json()

mdview_cli/cli.py

@@ -0,0 +1,324 @@
+import base64
+import functools
+import io
+import json
+import os
+import re
+import shutil
+import tempfile
+import webbrowser
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+
+from .api import ApiError, MdviewApi
+from .config import base_url, data_dir, get_token, keys_path, remove_token, save_token
+from .state import DocumentState
+
+
+class ServiceError(click.ClickException):
+    exit_code = 3
+
+
+def service_errors(command):
+    @functools.wraps(command)
+    def wrapper(*args, **kwargs):
+        try:
+            return command(*args, **kwargs)
+        except ApiError as error:
+            raise ServiceError(str(error)) from error
+
+    return wrapper
+
+
+def atomic_write(path: Path, data):
+    binary = isinstance(data, bytes)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb" if binary else "w", encoding=None if binary else "utf-8") as stream:
+            stream.write(data)
+        os.replace(temporary, path)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def api_for_token(token=None):
+    credential = token or get_token()
+    if not credential:
+        raise click.UsageError("No CLI token. Run 'mdv keys set' or set MDVIEW_TOKEN.")
+    return MdviewApi(base_url(), credential)
+
+
+def title_for(path: Path, markdown: str, explicit=None) -> str:
+    if explicit:
+        return explicit
+    match = re.search(r"^#\s+(.+?)\s*$", markdown, re.MULTILINE)
+    return match.group(1) if match else path.stem
+
+
+def share_id(body):
+    return body.get("customSlug") or body.get("custom_slug") or body.get("shortId") or body.get("short_id")
+
+
+def share_url(share):
+    return f"{base_url()}/s/{share}"
+
+
+def verdict(report) -> bool:
+    if "renderable" in report:
+        return bool(report["renderable"])
+    return bool(report.get("known")) and int(report.get("diagrams", {}).get("failing", 0)) == 0
+
+
+def result_payload(document_id, share, report, created=False):
+    return {
+        "document_id": document_id,
+        "created": created,
+        "share_url": share_url(share) if share else None,
+        "renderable": verdict(report),
+        "diagrams": report.get("diagrams", {}),
+        "tables": report.get("tables", {}),
+        "failures": report.get("failures", []),
+    }
+
+
+def print_result(payload, as_json=False, *, check=True):
+    if as_json:
+        click.echo(json.dumps(payload, separators=(",", ":")))
+    else:
+        click.echo(f"Document: {payload['document_id']}")
+        if payload.get("share_url"):
+            click.echo(f"Share: {payload['share_url']}")
+        diagrams = payload.get("diagrams") or {}
+        failures = payload.get("failures") or []
+        failing = int(diagrams.get("failing", len(failures)) or 0)
+        total = int(diagrams.get("total", 0) or 0)
+        if payload["renderable"]:
+            click.secho(f"Renderable: yes ({total} diagrams, {payload.get('tables', {}).get('total', 0)} tables)", fg="green")
+        else:
+            click.secho(f"Renderable: no ({failing} of {total} diagrams failed)", fg="red", err=True)
+            for failure in failures:
+                index = failure.get("index", "?")
+                error = failure.get("error") or failure.get("message") or "render failed"
+                click.echo(f"  Diagram {index}: {error}", err=True)
+            click.echo("Run 'mdv fix FILE' to repair the diagrams.", err=True)
+    if check and not payload["renderable"]:
+        raise click.exceptions.Exit(1)
+
+
+def sync_file(path: Path, *, api=None, state=None, title=None, document_id=None, share=True, verify=True):
+    if not path.is_file():
+        raise click.UsageError(f"File not found: {path}")
+    markdown = path.read_text(encoding="utf-8")
+    api = api or api_for_token()
+    state = state or DocumentState()
+    association = state.get(base_url(), path)
+    document_id = document_id or (association and association["document_id"])
+    existing_share = association and association["share_id"]
+    updated_at = association and association["updated_at"]
+    created = document_id is None
+    doc_title = title_for(path, markdown, title)
+    if created:
+        created_body = api.create(doc_title, markdown)
+        document_id = created_body["id"]
+        updated_at = created_body.get("updated_at")
+    else:
+        try:
+            updated = api.update(document_id, doc_title, markdown, updated_at)
+            updated_at = updated.get("updated_at")
+        except ApiError as error:
+            if error.status_code != 404 or document_id != (association and association["document_id"]):
+                raise
+            created_body = api.create(doc_title, markdown)
+            document_id = created_body["id"]
+            updated_at = created_body.get("updated_at")
+            existing_share = None
+            created = True
+    if share and not existing_share:
+        existing_share = share_id(api.share(document_id))
+    state.put(base_url(), path, document_id, existing_share, updated_at)
+    report = api.verify(document_id) if verify else {"renderable": True, "diagrams": {}, "tables": {}}
+    return result_payload(document_id, existing_share, report, created)
+
+
+class MdvGroup(click.Group):
+    """Treat `mdv FILE` as shorthand for `mdv preview FILE`."""
+
+    def resolve_command(self, ctx, args):
+        argument = args[0]
+        if self.get_command(ctx, argument) is None and (
+            Path(argument).is_file() or argument.endswith((".md", ".markdown"))
+        ):
+            return "preview", self.commands["preview"], args
+        return super().resolve_command(ctx, args)
+
+
+@click.group(cls=MdvGroup)
+@click.version_option()
+def cli():
+    """Iterate on Markdown and verify every revision with mdview.io.
+
+    Running `mdv FILE.md` previews the file (same as `mdv preview FILE.md`).
+    """
+
+
+@cli.group()
+def keys():
+    """Manage the mdview.io CLI token."""
+
+
+@keys.command("set")
+def keys_set():
+    token = click.prompt("CLI token", hide_input=True).strip()
+    if not token.startswith("mdv1_"):
+        raise click.UsageError("CLI tokens start with mdv1_.")
+    try:
+        api_for_token(token).documents()
+    except ApiError as error:
+        raise ServiceError(f"Token validation failed: {error}") from error
+    save_token(token)
+    click.echo(f"Token saved to {keys_path()}")
+
+
+@keys.command("path")
+def keys_path_command():
+    click.echo(keys_path())
+
+
+@keys.command("unset")
+def keys_unset():
+    click.echo("Token removed." if remove_token() else "No stored token.")
+
+
+@keys.command("list")
+def keys_list():
+    click.echo("default" if get_token() else "No token configured.")
+
+
+@cli.command("sync")
+@click.argument("file", type=click.Path(path_type=Path))
+@click.option("--title")
+@click.option("--id", "document_id")
+@click.option("--no-share", is_flag=True)
+@click.option("--json", "as_json", is_flag=True)
+@service_errors
+def sync_command(file, title, document_id, no_share, as_json):
+    """Update FILE, preserve its URL, and verify PDF rendering."""
+    payload = sync_file(file, title=title, document_id=document_id, share=not no_share)
+    print_result(payload, as_json)
+
+
+@cli.command("verify")
+@click.argument("file", required=False, type=click.Path(path_type=Path))
+@click.option("--id", "document_id")
+@click.option("--status", is_flag=True)
+@click.option("--json", "as_json", is_flag=True)
+@service_errors
+def verify_command(file, document_id, status, as_json):
+    association = DocumentState().get(base_url(), file) if file else None
+    document_id = document_id or (association and association["document_id"])
+    if not document_id:
+        raise click.UsageError("Provide an associated FILE or --id.")
+    report = api_for_token().verify(document_id, status=status)
+    payload = result_payload(document_id, association and association["share_id"], report)
+    print_result(payload, as_json)
+
+
+@cli.command("fix")
+@click.argument("file", type=click.Path(path_type=Path))
+@click.option("--json", "as_json", is_flag=True)
+@service_errors
+def fix_command(file, as_json):
+    api = api_for_token()
+    state = DocumentState()
+    initial = sync_file(file, api=api, state=state, verify=False)
+    repaired = api.fix(initial["document_id"])
+    markdown = repaired.get("markdown")
+    if markdown is None:
+        raise ServiceError("The repair response did not include Markdown.")
+    backup_dir = data_dir() / "backups" / initial["document_id"]
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    backup = backup_dir / f"{stamp}-{file.name}"
+    shutil.copy2(file, backup)
+    atomic_write(file, markdown)
+    payload = sync_file(file, api=api, state=state)
+    payload["backup"] = str(backup)
+    payload["fixed"] = repaired.get("diagrams", {}).get("fixed", 0)
+    print_result(payload, as_json)
+
+
+@cli.command("export")
+@click.argument("file", type=click.Path(path_type=Path))
+@click.option("-o", "--output", type=click.Path(path_type=Path))
+@click.option("--force", is_flag=True)
+@service_errors
+def export_command(file, output, force):
+    api = api_for_token()
+    payload = sync_file(file, api=api)
+    print_result(payload, check=False)
+    if not payload["renderable"] and not force:
+        raise click.ClickException("Document is not Renderable; use --force to export anyway.")
+    output = output or file.with_suffix(".pdf")
+    pdf = api.export_pdf(payload["document_id"])
+    output.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write(output, pdf)
+    click.echo(f"PDF: {output}")
+
+
+@cli.command("list")
+@click.option("--json", "as_json", is_flag=True)
+@service_errors
+def list_command(as_json):
+    documents = api_for_token().documents()
+    if as_json:
+        click.echo(json.dumps(documents, separators=(",", ":")))
+    else:
+        for document in documents:
+            sid = share_id(document)
+            suffix = f"  {share_url(sid)}" if sid else ""
+            click.echo(f"{document.get('id')}  {document.get('title', 'Untitled')}{suffix}")
+
+
+@cli.command("unlink")
+@click.argument("file", type=click.Path(path_type=Path))
+def unlink_command(file):
+    removed = DocumentState().unlink(base_url(), file)
+    click.echo("Association removed; remote document was not deleted." if removed else "No association found.")
+
+
+@cli.command("preview")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--title")
+@click.option("--json", "as_json", is_flag=True)
+@service_errors
+def preview_command(file, title, as_json):
+    """Publish FILE anonymously and open its temporary mdview page."""
+    markdown = file.read_text(encoding="utf-8")
+    body = MdviewApi(base_url()).publish(title_for(file, markdown, title), markdown)
+    url = body.get("shareUrl") or body.get("viewerUrl")
+    if not url:
+        sid = share_id(body)
+        url = share_url(sid) if sid else None
+    if not url:
+        raise ServiceError("The publish response did not include a share URL.")
+    if as_json:
+        click.echo(json.dumps(body, separators=(",", ":")))
+    else:
+        click.echo(f"Preview: {url}")
+        webbrowser.open(url)
+
+
+@cli.command("open")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+def open_command(file):
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w", zipfile.ZIP_DEFLATED) as archive:
+        archive.write(file, arcname=file.name)
+    payload = base64.b64encode(buffer.getvalue()).decode("ascii")
+    url = f"{base_url()}/#mvd=zip:{payload}"
+    webbrowser.open(url)
+    click.echo(f"Opened {file}")

mdview_cli/config.py

@@ -0,0 +1,49 @@
+import json
+import os
+from pathlib import Path
+
+from platformdirs import user_config_path, user_data_path
+
+
+def config_dir() -> Path:
+    override = os.environ.get("MDVIEW_CONFIG_DIR")
+    return Path(override) if override else user_config_path("mdview-cli")
+
+
+def data_dir() -> Path:
+    override = os.environ.get("MDVIEW_DATA_DIR")
+    return Path(override) if override else user_data_path("mdview-cli")
+
+
+def keys_path() -> Path:
+    return config_dir() / "keys.json"
+
+
+def base_url() -> str:
+    return os.environ.get("MDVIEW_BASE_URL", "https://mdview.io").rstrip("/")
+
+
+def get_token() -> str | None:
+    value = os.environ.get("MDVIEW_TOKEN")
+    if value:
+        return value.strip()
+    try:
+        return json.loads(keys_path().read_text(encoding="utf-8")).get("default")
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def save_token(token: str) -> None:
+    path = keys_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({"default": token}) + "\n", encoding="utf-8")
+    if os.name == "posix":
+        path.chmod(0o600)
+
+
+def remove_token() -> bool:
+    try:
+        keys_path().unlink()
+        return True
+    except FileNotFoundError:
+        return False

mdview_cli/state.py

@@ -0,0 +1,54 @@
+import sqlite3
+from pathlib import Path
+
+from .config import data_dir
+
+
+class DocumentState:
+    def __init__(self, path: Path | None = None):
+        db_path = path or (data_dir() / "state.db")
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.connection = sqlite3.connect(db_path)
+        self.connection.execute(
+            """CREATE TABLE IF NOT EXISTS associations (
+                server TEXT NOT NULL,
+                path TEXT NOT NULL,
+                document_id TEXT NOT NULL,
+                share_id TEXT,
+                updated_at TEXT,
+                PRIMARY KEY (server, path)
+            )"""
+        )
+
+    @staticmethod
+    def canonical(path: Path) -> str:
+        return str(path.expanduser().resolve())
+
+    def get(self, server: str, path: Path):
+        row = self.connection.execute(
+            "SELECT document_id, share_id, updated_at FROM associations WHERE server = ? AND path = ?",
+            (server, self.canonical(path)),
+        ).fetchone()
+        if not row:
+            return None
+        return {"document_id": row[0], "share_id": row[1], "updated_at": row[2]}
+
+    def put(self, server: str, path: Path, document_id: str, share_id=None, updated_at=None):
+        self.connection.execute(
+            """INSERT INTO associations (server, path, document_id, share_id, updated_at)
+               VALUES (?, ?, ?, ?, ?)
+               ON CONFLICT(server, path) DO UPDATE SET
+                 document_id=excluded.document_id,
+                 share_id=COALESCE(excluded.share_id, associations.share_id),
+                 updated_at=COALESCE(excluded.updated_at, associations.updated_at)""",
+            (server, self.canonical(path), document_id, share_id, updated_at),
+        )
+        self.connection.commit()
+
+    def unlink(self, server: str, path: Path) -> bool:
+        cursor = self.connection.execute(
+            "DELETE FROM associations WHERE server = ? AND path = ?",
+            (server, self.canonical(path)),
+        )
+        self.connection.commit()
+        return cursor.rowcount > 0

mdview_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: mdview-cli
+Version: 0.1.0
+Summary: Iterate on Markdown and verify every revision with mdview.io
+License-Expression: MIT
+Project-URL: Homepage, https://mdview.io
+Project-URL: Repository, https://github.com/gogainda/mdview-cli
+Project-URL: Issues, https://github.com/gogainda/mdview-cli/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# mdv
+
+`mdv` opens Markdown in mdview.io and can keep an evolving file attached to one
+stable document while checking every revision in the PDF renderer.
+
+## Quick start — no token required
+
+```bash
+uv tool install mdview-cli
+mdv architecture.md
+```
+
+`mdv FILE.md` is shorthand for `mdv preview FILE.md`: it publishes the file
+anonymously and opens a temporary mdview page you can share (30-day expiry,
+2 MB limit). No account, token, or configuration required.
+
+`open` renders a local file in the browser without uploading anything at all:
+
+```bash
+mdv open architecture.md
+```
+
+## Verify every revision
+
+Saved-document commands require a mdview.io CLI token because they update your
+documents between runs. Configure it once, then sync the same file after every
+edit:
+
+```bash
+mdv keys set
+mdv sync architecture.md
+```
+
+Edit the file and run `mdv sync architecture.md` again. The share URL stays the
+same. Exit status `0` means every Mermaid diagram rendered; status `1` means the
+document needs attention.
+
+```bash
+mdv fix architecture.md
+mdv export architecture.md
+```
+
+`open` and `preview` are token-free. `sync`, `verify`, `fix`, `export`, and `list` use a token
+to access Saved documents. In CI, set `MDVIEW_TOKEN` instead of storing it.
+`MDVIEW_BASE_URL` overrides the service URL for development.

mdview_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mdview_cli/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+mdview_cli/api.py,sha256=ecupcg7cNJvFtM3iMCvrRyjSrMPWJFrH_WFHPv4HrQY,2302
+mdview_cli/cli.py,sha256=L3qnQ_3B-MwTpnwWX9EiQoKpAJ44S7Jsx7U6RWmeIcQ,11609
+mdview_cli/config.py,sha256=dJu3k5q_LrrZe0_Rn5cpC-26BbvBpQb8skbu1-_FGW8,1248
+mdview_cli/state.py,sha256=EHL5iy1Izbm41fOg-NFxmVScy3jjaLnHfF8ZNPoNvFI,2067
+mdview_cli-0.1.0.dist-info/licenses/LICENSE,sha256=ZKMOPBiHvTgIhnX2ej1pankBmQOyFjx_bNzharc9DQQ,1066
+mdview_cli-0.1.0.dist-info/METADATA,sha256=lJsa3YH25-hNDybd0mcRI-51JyV5FSgkBiWLmRQy46A,1888
+mdview_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+mdview_cli-0.1.0.dist-info/entry_points.txt,sha256=smr7TlDjPfpnl3Cgihhg2OfFsSQrQJxnBoqk8NE1G44,43
+mdview_cli-0.1.0.dist-info/top_level.txt,sha256=Uli2yMYFokqicsUBvA0FO3YhMFhPBIYuiGjEjq35aIY,11
+mdview_cli-0.1.0.dist-info/RECORD,,

mdview_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mdview_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mdv = mdview_cli.cli:cli

mdview_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdview.io
+
+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.

mdview_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mdview_cli