docverse 1.0.0b2__py3-none-any.whl

docverse/__init__.py

@@ -0,0 +1,22 @@
+"""Docverse client library."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._client import DEFAULT_UPDATED_SINCE_OVERLAP, DocverseClient, ProjectList
+from ._exceptions import BuildProcessingError, DocverseClientError
+from ._tar import create_tarball
+
+__all__ = [
+    "DEFAULT_UPDATED_SINCE_OVERLAP",
+    "BuildProcessingError",
+    "DocverseClient",
+    "DocverseClientError",
+    "ProjectList",
+    "__version__",
+    "create_tarball",
+]
+
+try:
+    __version__ = version("docverse")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

docverse/_annotations.py

@@ -0,0 +1,63 @@
+"""Auto-detection of build provenance annotations from CI environments."""
+
+from __future__ import annotations
+
+import os
+
+from .models.builds import BuildAnnotations
+
+__all__ = [
+    "detect_github_actions_annotations",
+    "merge_annotations",
+]
+
+
+def detect_github_actions_annotations() -> BuildAnnotations | None:
+    """Detect build provenance from GitHub Actions environment variables.
+
+    Returns a populated ``BuildAnnotations`` if running inside GitHub
+    Actions (``GITHUB_ACTIONS == "true"``), otherwise ``None``.
+    """
+    if os.environ.get("GITHUB_ACTIONS") != "true":
+        return None
+
+    server_url = os.environ.get("GITHUB_SERVER_URL", "https://github.com")
+    repository = os.environ.get("GITHUB_REPOSITORY")
+    run_id = os.environ.get("GITHUB_RUN_ID")
+
+    run_url: str | None = None
+    if repository and run_id:
+        run_url = f"{server_url}/{repository}/actions/runs/{run_id}"
+
+    return BuildAnnotations(
+        commit_sha=os.environ.get("GITHUB_SHA"),
+        github_repository=repository,
+        github_run_id=run_id,
+        github_run_url=run_url,
+        github_run_attempt=os.environ.get("GITHUB_RUN_ATTEMPT"),
+        github_workflow=os.environ.get("GITHUB_WORKFLOW"),
+        github_actor=os.environ.get("GITHUB_ACTOR"),
+        github_event_name=os.environ.get("GITHUB_EVENT_NAME"),
+        ci_platform="github-actions",
+    )
+
+
+def merge_annotations(
+    auto: BuildAnnotations | None,
+    manual: dict[str, str] | None,
+) -> BuildAnnotations | None:
+    """Merge auto-detected and manual annotations.
+
+    Manual entries take precedence over auto-detected values.  Returns
+    ``None`` if both inputs are empty/None.
+    """
+    result: dict[str, str] = {}
+    if auto is not None:
+        result.update(
+            {k: v for k, v in auto.model_dump().items() if v is not None}
+        )
+    if manual:
+        result.update(manual)
+    if not result:
+        return None
+    return BuildAnnotations.model_validate(result)

docverse/_cli.py

@@ -0,0 +1,413 @@
+"""Command-line interface for the Docverse client."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+from ._annotations import detect_github_actions_annotations, merge_annotations
+from ._client import DocverseClient
+from ._exceptions import BuildProcessingError, DocverseClientError
+from ._tar import create_tarball
+from .models.queue_enums import JobStatus
+
+__all__ = ["main"]
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(message="%(version)s")
+def main() -> None:
+    """Docverse documentation hosting client."""
+
+
+@main.command()
+@click.option(
+    "--org",
+    envvar="DOCVERSE_ORG",
+    show_envvar=True,
+    required=True,
+    help="Organization slug.",
+)
+@click.option(
+    "--project",
+    envvar="DOCVERSE_PROJECT",
+    show_envvar=True,
+    required=True,
+    help="Project slug.",
+)
+@click.option(
+    "--git-ref",
+    envvar="DOCVERSE_GIT_REF",
+    show_envvar=True,
+    default=None,
+    help="Git ref for the build. Defaults to HEAD.",
+)
+@click.option(
+    "--dir",
+    "source_dir",
+    envvar="DOCVERSE_DIR",
+    show_envvar=True,
+    required=True,
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    help="Directory containing the built documentation.",
+)
+@click.option(
+    "--token",
+    envvar="DOCVERSE_TOKEN",
+    show_envvar=True,
+    required=True,
+    help="API bearer token.",
+)
+@click.option(
+    "--base-url",
+    envvar="DOCVERSE_API",
+    show_envvar=True,
+    default="https://roundtable.lsst.cloud/docverse/api",
+    show_default=True,
+    help="Docverse API base URL.",
+)
+@click.option(
+    "--alternate-name",
+    envvar="DOCVERSE_ALTERNATE",
+    show_envvar=True,
+    default=None,
+    help="Alternate deployment name.",
+)
+@click.option(
+    "--annotation",
+    "-a",
+    "annotations",
+    multiple=True,
+    help="Manual annotation in KEY=VALUE format. Can be repeated.",
+)
+@click.option(
+    "--auto-annotations/--no-auto-annotations",
+    default=True,
+    show_default=True,
+    help="Auto-detect annotations from CI environment variables.",
+)
+@click.option(
+    "--no-wait",
+    is_flag=True,
+    default=False,
+    help="Exit after upload without waiting for processing.",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    default=False,
+    help="Show detailed HTTP request/response information.",
+)
+def upload(
+    org: str,
+    project: str,
+    git_ref: str | None,
+    source_dir: Path,
+    token: str,
+    base_url: str,
+    alternate_name: str | None,
+    annotations: tuple[str, ...],
+    auto_annotations: bool,  # noqa: FBT001
+    no_wait: bool,  # noqa: FBT001
+    verbose: bool,  # noqa: FBT001
+) -> None:
+    """Upload a documentation build."""
+    if git_ref is None:
+        git_ref = _detect_git_ref()
+
+    # Parse manual annotations
+    manual: dict[str, str] | None = None
+    if annotations:
+        manual = {}
+        for item in annotations:
+            if "=" not in item:
+                msg = f"Invalid annotation format (expected KEY=VALUE): {item}"
+                raise click.BadParameter(msg, param_hint="'--annotation'")
+            key, value = item.split("=", 1)
+            manual[key] = value
+
+    asyncio.run(
+        _upload_async(
+            org=org,
+            project=project,
+            git_ref=git_ref,
+            source_dir=source_dir,
+            token=token,
+            base_url=base_url,
+            alternate_name=alternate_name,
+            auto_annotations=auto_annotations,
+            manual_annotations=manual,
+            no_wait=no_wait,
+            verbose=verbose,
+        )
+    )
+
+
+def _stage_worker_source(*, worker_dir: Path, dest_dir: Path) -> None:
+    """Pack the worker source and install it into the deployments repo.
+
+    Parameters
+    ----------
+    worker_dir
+        The monorepo's ``cloudflare-worker/`` directory.
+    dest_dir
+        The ``worker/`` directory inside the deployments repo.
+
+    Raises
+    ------
+    click.ClickException
+        If packing, unpacking, or dependency installation fails.
+    """
+    # Phase 1: npm pack
+    click.echo(f"Packing cloudflare worker from {worker_dir}")
+    try:
+        pack_result = subprocess.run(
+            ["npm", "pack", "--json"],
+            check=True,
+            capture_output=True,
+            text=True,
+            cwd=str(worker_dir),
+        )
+    except subprocess.CalledProcessError as exc:
+        msg = f"npm pack failed: {exc.stderr}"
+        raise click.ClickException(msg) from exc
+    try:
+        tarball_name = json.loads(pack_result.stdout)[0]["filename"]
+    except (json.JSONDecodeError, KeyError, IndexError) as exc:
+        msg = f"Failed to parse npm pack output: {pack_result.stdout!r}"
+        raise click.ClickException(msg) from exc
+
+    # Phase 2: copy and unpack into deployments repo
+    click.echo(f"Unpacking worker into {dest_dir}")
+    shutil.copy2(worker_dir / tarball_name, dest_dir / tarball_name)
+    try:
+        subprocess.run(
+            ["tar", "xzf", tarball_name, "--strip-components=1"],
+            check=True,
+            cwd=str(dest_dir),
+        )
+    except subprocess.CalledProcessError as exc:
+        msg = f"Failed to unpack worker tarball: {exc}"
+        raise click.ClickException(msg) from exc
+    finally:
+        for tgz in dest_dir.glob("*.tgz"):
+            tgz.unlink()
+    (worker_dir / tarball_name).unlink(missing_ok=True)
+
+    # Phase 2a: copy the lockfile alongside the unpacked source. ``npm
+    # pack`` always excludes package-lock.json, so without this the
+    # destination keeps whatever lockfile an earlier deploy left behind.
+    # Once that stale lockfile disagrees with the freshly packed
+    # package.json, npm re-resolves the whole tree and deploys stop being
+    # reproducible.
+    lockfile = worker_dir / "package-lock.json"
+    if not lockfile.is_file():
+        msg = f"package-lock.json not found in {worker_dir}"
+        raise click.ClickException(msg)
+    click.echo("Copying worker lockfile")
+    shutil.copy2(lockfile, dest_dir / "package-lock.json")
+
+    # Phase 2b: install worker runtime dependencies. ``npm ci`` installs
+    # exactly what the lockfile pins and wipes node_modules first, so no
+    # stale packages survive from an earlier deploy.
+    click.echo("Installing worker dependencies")
+    try:
+        subprocess.run(
+            ["npm", "ci", "--omit=dev"],
+            check=True,
+            capture_output=True,
+            text=True,
+            cwd=str(dest_dir),
+        )
+    except subprocess.CalledProcessError as exc:
+        msg = f"npm ci failed: {exc.stderr}"
+        raise click.ClickException(msg) from exc
+
+
+@main.command()
+@click.option(
+    "--docverse-repo",
+    required=True,
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    help="Path to the docverse monorepo root.",
+)
+@click.option(
+    "--deployments-repo",
+    required=True,
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    help="Path to local docverse-cloudflare-deployments checkout.",
+)
+@click.option(
+    "--env",
+    "wrangler_env",
+    required=True,
+    help="Wrangler environment name (e.g., dev, production).",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Build the worker bundle without deploying.",
+)
+def deploy_worker(
+    *,
+    docverse_repo: Path,
+    deployments_repo: Path,
+    wrangler_env: str,
+    dry_run: bool,
+) -> None:
+    """Pack and deploy the Cloudflare Worker."""
+    if not re.match(r"^[a-zA-Z0-9_-]+$", wrangler_env):
+        msg = (
+            f"Invalid environment name {wrangler_env!r}: "
+            "must contain only alphanumeric characters, hyphens, "
+            "and underscores"
+        )
+        raise click.ClickException(msg)
+
+    worker_dir = docverse_repo.resolve() / "cloudflare-worker"
+    if not worker_dir.is_dir():
+        msg = f"cloudflare-worker/ not found in {docverse_repo.resolve()}"
+        raise click.ClickException(msg)
+
+    deployments_repo = deployments_repo.resolve()
+    dest_dir = deployments_repo / "worker"
+    dest_dir.mkdir(exist_ok=True)
+
+    # Phases 1 and 2: pack the worker and stage it in the deployments repo
+    _stage_worker_source(worker_dir=worker_dir, dest_dir=dest_dir)
+
+    # Phase 3: wrangler deploy
+    wrangler_cmd = [
+        "npx",
+        "wrangler",
+        "deploy",
+        "--env",
+        wrangler_env,
+    ]
+    if dry_run:
+        outdir = deployments_repo / "dist"
+        wrangler_cmd.extend(["--dry-run", f"--outdir={outdir}"])
+    click.echo(f"Deploying worker (env={wrangler_env}, dry_run={dry_run})")
+    try:
+        subprocess.run(
+            wrangler_cmd,
+            check=True,
+            cwd=str(deployments_repo),
+        )
+    except subprocess.CalledProcessError as exc:
+        msg = f"wrangler deploy failed: {exc}"
+        raise click.ClickException(msg) from exc
+
+    click.echo(f"Worker deployed successfully (env={wrangler_env})")
+
+
+def _detect_git_ref() -> str:
+    """Detect the current git ref from HEAD."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+        msg = (
+            "Could not detect git ref from HEAD. "
+            "Provide --git-ref or set DOCVERSE_GIT_REF."
+        )
+        raise click.UsageError(msg) from exc
+    return result.stdout.strip()
+
+
+async def _upload_async(
+    *,
+    org: str,
+    project: str,
+    git_ref: str,
+    source_dir: Path,
+    token: str,
+    base_url: str,
+    alternate_name: str | None,
+    auto_annotations: bool,
+    manual_annotations: dict[str, str] | None,
+    no_wait: bool,
+    verbose: bool,
+) -> None:
+    """Run the upload workflow."""
+    tarball_path: Path | None = None
+    try:
+        click.echo(f"Creating tarball from {source_dir}")
+        tarball_path, content_hash = create_tarball(source_dir)
+        click.echo(f"Content hash: {content_hash}")
+
+        # Build annotations from auto-detection and manual entries
+        auto = (
+            detect_github_actions_annotations() if auto_annotations else None
+        )
+        merged_annotations = merge_annotations(auto, manual_annotations)
+
+        async with DocverseClient(base_url, token, verbose=verbose) as client:
+            click.echo(f"Creating build for {org}/{project} @ {git_ref}")
+            build = await client.create_build(
+                org,
+                project,
+                git_ref=git_ref,
+                content_hash=content_hash,
+                alternate_name=alternate_name,
+                annotations=merged_annotations,
+            )
+            click.echo(f"Build created: {build.id}")
+
+            if build.upload_url is None:
+                msg = (
+                    "Server did not return an upload URL. "
+                    "The organization may not have an object "
+                    "store configured."
+                )
+                raise DocverseClientError(msg)
+
+            click.echo("Uploading tarball")
+            await client.upload_tarball(build.upload_url, tarball_path)
+
+            click.echo("Signalling upload complete")
+            build = await client.complete_upload(build.self_url)
+
+            if no_wait:
+                click.echo("Upload complete (--no-wait specified)")
+                return
+
+            if build.job_url is None:
+                msg = "Server did not return a job URL after upload"
+                raise DocverseClientError(msg)
+
+            click.echo("Waiting for build processing")
+            job = await client.wait_for_job(build.job_url)
+
+            if job.status == JobStatus.completed_with_errors:
+                click.echo(
+                    f"Build completed with errors (phase={job.phase})",
+                    err=True,
+                )
+                sys.exit(2)
+            elif job.status == JobStatus.cancelled:
+                click.echo("Build processing was cancelled", err=True)
+                sys.exit(2)
+            else:
+                click.echo("Build processing complete")
+
+    except BuildProcessingError as exc:
+        raise click.ClickException(str(exc)) from exc
+    except DocverseClientError as exc:
+        raise click.ClickException(str(exc)) from exc
+    finally:
+        if tarball_path is not None:
+            tarball_path.unlink(missing_ok=True)