qhost 0.1.0__py3-none-any.whl

qhost/__init__.py

@@ -0,0 +1,3 @@
+from qhost_core.version import __version__
+
+__all__ = ["__version__"]

qhost/_io.py

@@ -0,0 +1,66 @@
+"""Shared filesystem helpers for the three local-state modules.
+
+Atomic writes (tmp + chmod + replace) and mode-checks are identical for
+`config.toml`, `credentials.toml`, and `.qhost`, so they live here. Each
+state module imports from this — nothing else does.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+_MODE_WARNED: set[str] = set()
+
+
+def atomic_write(path: Path, payload: str, *, mode: int) -> None:
+    """Write `payload` to `path` via tmp + chmod + replace.
+
+    Mode is set on the tmp file *before* the rename so the visible file is
+    never briefly readable in a wider mode. Skips chmod on Windows.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=path.name + ".",
+        suffix=".tmp",
+        dir=str(path.parent),
+    )
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(payload)
+        if not sys.platform.startswith("win"):
+            os.chmod(tmp, mode)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+        raise
+
+
+def warn_if_world_readable(path: Path) -> None:
+    """Print a one-time stderr warning if `path` is readable by group/other.
+
+    Used for secrets files (`config.toml`, `credentials.toml`). No-op on
+    Windows. Each path is warned about at most once per process to avoid
+    spamming CLI output across multiple commands in the same invocation.
+    """
+    if sys.platform.startswith("win"):
+        return
+    key = str(path)
+    if key in _MODE_WARNED:
+        return
+    try:
+        mode = path.stat().st_mode & 0o777
+    except OSError:
+        return
+    if mode & 0o077:
+        _MODE_WARNED.add(key)
+        print(
+            f"warning: {path} mode is {oct(mode)} (should be 0o600); "
+            "anyone on this machine can read it.",
+            file=sys.stderr,
+        )

qhost/_toml.py

@@ -0,0 +1,99 @@
+"""Minimal TOML writer for qhost's three state files.
+
+Reads use stdlib `tomllib` (Python 3.11+). Writing TOML is implemented in-tree
+to avoid pulling in a runtime dep (`tomli_w`) just to emit a few dozen lines.
+
+The subset supported is deliberately narrow:
+- Top-level scalar `key = value` lines.
+- Section headers `[a]`, `[a.b]`, `[a."quoted"."key"]`.
+- String, int, and bool scalars.
+
+Anything else (arrays, dates, multi-line strings, inline tables, floats)
+raises `TypeError`. If a future state file needs more, extend here — not at
+the call site.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any
+
+_BARE_KEY = re.compile(r"[A-Za-z0-9_-]+")
+
+
+def dumps(data: Mapping[str, Any]) -> str:
+    """Render a nested mapping to TOML text."""
+    lines: list[str] = []
+    scalars, subs = _split(data)
+    for k, v in scalars:
+        lines.append(_format_kv(k, v))
+    for k, v in subs:
+        if lines:
+            lines.append("")
+        _emit_section(lines, [k], v)
+    text = "\n".join(lines)
+    return text + "\n" if text else ""
+
+
+def _emit_section(lines: list[str], path: list[str], data: Mapping[str, Any]) -> None:
+    scalars, subs = _split(data)
+    # Emit a header for this path when it has scalars of its own or is a leaf;
+    # otherwise the path is purely a parent and its header is implicit.
+    if scalars or not subs:
+        lines.append(f"[{_format_path(path)}]")
+        for k, v in scalars:
+            lines.append(_format_kv(k, v))
+    for k, v in subs:
+        lines.append("")
+        _emit_section(lines, [*path, k], v)
+
+
+def _split(
+    data: Mapping[str, Any],
+) -> tuple[list[tuple[str, Any]], list[tuple[str, Mapping[str, Any]]]]:
+    scalars: list[tuple[str, Any]] = []
+    subs: list[tuple[str, Mapping[str, Any]]] = []
+    for k, v in data.items():
+        if isinstance(v, Mapping):
+            subs.append((k, v))
+        else:
+            scalars.append((k, v))
+    return scalars, subs
+
+
+def _format_path(path: list[str]) -> str:
+    return ".".join(_format_key(p) for p in path)
+
+
+def _format_key(k: str) -> str:
+    if _BARE_KEY.fullmatch(k):
+        return k
+    return _quote_string(k)
+
+
+def _format_kv(k: str, v: Any) -> str:
+    return f"{_format_key(k)} = {_format_value(v)}"
+
+
+def _format_value(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, int):
+        return str(v)
+    if isinstance(v, str):
+        return _quote_string(v)
+    raise TypeError(f"unsupported TOML value type: {type(v).__name__}")
+
+
+def _quote_string(s: str) -> str:
+    escaped = (
+        s.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\b", "\\b")
+        .replace("\t", "\\t")
+        .replace("\n", "\\n")
+        .replace("\f", "\\f")
+        .replace("\r", "\\r")
+    )
+    return f'"{escaped}"'

qhost/builders/__init__.py

@@ -0,0 +1,124 @@
+"""Builder protocol and the v1.0 registry.
+
+A builder turns a working directory into an output directory that's ready to
+be packed and uploaded. v1.0 ships two: `directory` (selected by `--dir`,
+publishes a prebuilt tree as-is) and `quarto` (auto-detected via
+`_quarto.yml`, runs `quarto render` with the serving prefix wired in).
+
+The registry is an explicit dict — `BUILDERS[name]` only. Entry-point
+discovery is v2.0 territory per `notes/builders.md`; until then, adding a
+new builder is a code change in this package and nowhere else.
+
+Selection precedence (from `resolve_builder`):
+1. `--dir <path>`  → `DirectoryBuilder.for_dir(path)`. Always wins.
+2. `--build <name>` → `BUILDERS[name]`. Errors if name isn't known.
+3. `detects()` chain → first matching builder.
+4. None → `NoBuilderDetected`.
+
+Refusing-to-guess at step 4 is deliberate: publishing the current working
+directory blindly (no index.html, no marker file, no flag) is too dangerous.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from qhost.errors import BuilderUnknown, NoBuilderDetected
+
+
+@dataclass(frozen=True, slots=True)
+class BuilderOpts:
+    """Inputs the CLI hands to every builder.
+
+    `entrypoint_hint` is whatever the user passed on `--entrypoint`, or None
+    for the builder to pick its own default.
+
+    `sandbox` is informational; builders may want to emit different markup
+    (e.g., a `<base>` tag) when sandboxed, but most won't care.
+
+    `extra` is builder-specific. v1.0 leaves it empty.
+    """
+
+    entrypoint_hint: str | None = None
+    sandbox: bool = False
+    extra: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class BuildResult:
+    """What a builder hands back. `output_dir` is what gets packed."""
+
+    output_dir: Path
+    suggested_entrypoint: str
+    warnings: list[str] = field(default_factory=list)
+
+
+@runtime_checkable
+class Builder(Protocol):
+    name: str
+
+    def detects(self, cwd: Path) -> bool: ...
+
+    def build(
+        self,
+        cwd: Path,
+        *,
+        slug: str,
+        base_url: str,
+        opts: BuilderOpts,
+    ) -> BuildResult: ...
+
+
+def resolve_builder(
+    cwd: Path,
+    *,
+    name: str | None = None,
+    dir_: Path | None = None,
+) -> Builder:
+    """Pick a builder per the precedence rules in this module's docstring."""
+    if dir_ is not None:
+        # Avoid a circular import — DirectoryBuilder imports nothing from here.
+        from qhost.builders.directory import DirectoryBuilder
+
+        return DirectoryBuilder.for_dir(dir_)
+    if name is not None:
+        if name not in BUILDERS:
+            available = ", ".join(sorted(BUILDERS))
+            raise BuilderUnknown(f"unknown builder: {name!r}. Available: {available}")
+        return BUILDERS[name]
+    for builder in BUILDERS.values():
+        if builder.detects(cwd):
+            return builder
+    available = ", ".join(sorted(BUILDERS))
+    raise NoBuilderDetected(
+        "no builder detected: this directory has no `index.html` and no "
+        "`_quarto.yml`. Point at a built output with `qhost publish --dir "
+        f"<path>`, or pass --build <name> (available: {available})."
+    )
+
+
+def _build_registry() -> dict[str, Builder]:
+    from qhost.builders.directory import DirectoryBuilder
+    from qhost.builders.quarto import QuartoBuilder
+
+    # Iteration order matters for auto-detect: builders that detect from a
+    # specific marker file (quarto's _quarto.yml) come before fallbacks.
+    return {"quarto": QuartoBuilder(), "directory": DirectoryBuilder()}
+
+
+# Populated at import time; mutable so additional builders can be registered
+# without restructuring callers. Tests must not mutate this — they should
+# patch instead — but it's not enforced.
+BUILDERS: dict[str, Builder] = _build_registry()
+
+
+__all__ = [
+    "BUILDERS",
+    "Builder",
+    "BuilderOpts",
+    "BuildResult",
+    "resolve_builder",
+]

qhost/builders/directory.py

@@ -0,0 +1,56 @@
+"""`directory` builder — publishes a prebuilt directory tree as-is.
+
+Selected by `--dir <path>` (which goes through `for_dir`), by explicit
+`--build directory`, or by auto-detection when the cwd contains an
+`index.html`. The auto-detect signal mirrors what the server already
+requires: a share's content must include the entrypoint file (default
+`index.html`) or the upload is rejected. A cwd without `index.html` is
+unlikely to be a published-ready directory, so detection stays off
+there and the CLI falls through to `NoBuilderDetected`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from qhost.builders import BuilderOpts, BuildResult
+from qhost.errors import BuilderFailed
+
+
+class DirectoryBuilder:
+    name = "directory"
+
+    def __init__(self, dir_: Path | None = None) -> None:
+        self._dir = dir_
+
+    @classmethod
+    def for_dir(cls, path: Path) -> DirectoryBuilder:
+        return cls(path)
+
+    def detects(self, cwd: Path) -> bool:
+        # `--dir <path>` instances are resolved before auto-detect runs, so
+        # only the registry instance (no pinned dir) ever reaches here. Use
+        # the same signal the server validates against post-upload.
+        return self._dir is None and (cwd / "index.html").is_file()
+
+    def build(
+        self,
+        cwd: Path,
+        *,
+        slug: str,
+        base_url: str,
+        opts: BuilderOpts,
+    ) -> BuildResult:
+        out_dir = (self._dir or cwd).resolve()
+        if not out_dir.exists():
+            raise BuilderFailed(f"directory does not exist: {out_dir}")
+        if not out_dir.is_dir():
+            raise BuilderFailed(f"not a directory: {out_dir}")
+        entry = opts.entrypoint_hint or "index.html"
+        warnings: list[str] = []
+        if not (out_dir / entry).is_file():
+            warnings.append(
+                f"entrypoint {entry!r} not found in {out_dir} — "
+                "the server will reject the upload"
+            )
+        return BuildResult(output_dir=out_dir, suggested_entrypoint=entry, warnings=warnings)

qhost/builders/quarto.py

@@ -0,0 +1,88 @@
+"""`quarto` builder — runs `quarto render` with the serving prefix wired in.
+
+Selected automatically when `_quarto.yml` (or `_quarto.yaml`) is present, or
+explicitly via `--build quarto`. The path-prefix flag is `--site-url`, which
+sets `site-url` in the rendered project's config so links resolve correctly
+under qhostd's `/s/<slug>/` prefix.
+
+Output-dir handling (per Quarto 1.4+):
+- Website projects render into `_site/`.
+- Book projects render into `_book/`.
+- Single-document renders (no project type) write the `.html` next to the
+  source. We don't handle this case here — `_quarto.yml` implies a project,
+  so we expect `_site/` or `_book/` to exist after render.
+
+If Quarto exits non-zero, raise `BuilderFailed` with the tail of stderr; if
+`quarto` isn't on PATH, raise `BuilderToolMissing`.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from qhost.builders import BuilderOpts, BuildResult
+from qhost.errors import BuilderFailed, BuilderToolMissing
+
+
+class QuartoBuilder:
+    name = "quarto"
+
+    def detects(self, cwd: Path) -> bool:
+        return (cwd / "_quarto.yml").is_file() or (cwd / "_quarto.yaml").is_file()
+
+    def build(
+        self,
+        cwd: Path,
+        *,
+        slug: str,
+        base_url: str,
+        opts: BuilderOpts,
+    ) -> BuildResult:
+        if shutil.which("quarto") is None:
+            raise BuilderToolMissing(
+                "quarto is not on PATH. Install from https://quarto.org/docs/get-started/."
+            )
+        cmd = ["quarto", "render", str(cwd), "--site-url", base_url, "--quiet"]
+        try:
+            completed = subprocess.run(
+                cmd,
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except OSError as exc:
+            raise BuilderFailed(f"failed to run quarto: {exc}") from exc
+        if completed.returncode != 0:
+            tail = (completed.stderr or completed.stdout or "").strip().splitlines()[-10:]
+            raise BuilderFailed(
+                "quarto render failed (exit "
+                f"{completed.returncode}):\n" + "\n".join(tail)
+            )
+
+        output_dir = _find_output_dir(cwd)
+        entrypoint = opts.entrypoint_hint or "index.html"
+        warnings: list[str] = []
+        if not (output_dir / entrypoint).is_file():
+            warnings.append(
+                f"entrypoint {entrypoint!r} not found in {output_dir} after render"
+            )
+        return BuildResult(
+            output_dir=output_dir,
+            suggested_entrypoint=entrypoint,
+            warnings=warnings,
+        )
+
+
+def _find_output_dir(cwd: Path) -> Path:
+    """Pick the rendered output directory per Quarto's project conventions."""
+    for candidate in ("_site", "_book"):
+        path = cwd / candidate
+        if path.is_dir():
+            return path.resolve()
+    raise BuilderFailed(
+        f"quarto rendered successfully but neither _site/ nor _book/ exists in {cwd}. "
+        "If you use a custom `project.output-dir`, pass `--dir <that-dir>` instead."
+    )