eledoctl 1.0.0__py3-none-any.whl

eledoctl/__init__.py

@@ -0,0 +1 @@
+"""Command-line toolkit for Eledo."""

eledoctl/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI command definitions."""

eledoctl/cli/common.py

@@ -0,0 +1,25 @@
+"""Shared CLI utilities."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Coroutine
+from typing import Any
+
+import click
+
+from eledoctl.config.settings import ConnectionSettings, load_connection_settings
+
+
+def run[T](coro: Coroutine[Any, Any, T]) -> T:
+    """Run an asynchronous command implementation."""
+    return asyncio.run(coro)
+
+
+def require_connection_settings() -> ConnectionSettings:
+    """Load persisted connection settings or raise a user-facing CLI error."""
+    try:
+        return load_connection_settings()
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        raise click.ClickException(str(exc)) from exc

eledoctl/cli/documents.py

@@ -0,0 +1,195 @@
+"""PDF generation CLI commands."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from eledoctl.cli.common import require_connection_settings, run
+from eledoctl.config.settings import ConnectionSettings
+from pyeledo import EledoClient
+from pyeledo.types import JsonObject
+from pyeledo.utils import parse_json_object
+
+
+@click.group("documents")
+def documents_group() -> None:
+    """Document generation commands."""
+
+
+@documents_group.command("generate")
+@click.argument("template_id")
+@click.option("--template-version", type=int, default=None, help="Optional template version.")
+@click.option(
+    "--payload",
+    type=str,
+    default=None,
+    help='Inline JSON containing the Eledo "file" object.',
+)
+@click.option(
+    "--payload-file",
+    type=click.Path(path_type=Path, exists=True, dir_okay=False),
+    default=None,
+    help='Read the Eledo "file" object from a JSON file.',
+)
+@click.option(
+    "--payload-stdin",
+    is_flag=True,
+    help='Read the Eledo "file" object from standard input.',
+)
+@click.option(
+    "--add-field",
+    "fields",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help=("Add a top-level primitive field. May be repeated. Ignored when a JSON payload source is provided."),
+)
+@click.option(
+    "--output",
+    "output_path",
+    type=click.Path(path_type=Path, dir_okay=False),
+    default=None,
+    help="Document output path. Defaults to filename returned by Eledo.",
+)
+@click.option(
+    "--output-dir",
+    type=click.Path(path_type=Path, file_okay=False),
+    default=None,
+    help="Directory for the generated document when --output is not provided.",
+)
+@click.option("--base64-json", is_flag=True, help="Print JSON metadata with base64 PDF content.")
+def generate_pdf(
+    template_id: str,
+    template_version: int | None,
+    payload: str | None,
+    payload_file: Path | None,
+    payload_stdin: bool,
+    fields: tuple[str, ...],
+    output_path: Path | None,
+    output_dir: Path | None,
+    base64_json: bool,
+) -> None:
+    """Generate a PDF document from an Eledo template."""
+    settings = require_connection_settings()
+    run(
+        _generate_pdf(
+            template_id=template_id,
+            settings=settings,
+            template_version=template_version,
+            file_data=_resolve_payload(
+                payload=payload, payload_file=payload_file, payload_stdin=payload_stdin, fields=fields
+            ),
+            output_path=output_path,
+            output_dir=output_dir,
+            base64_json=base64_json,
+        )
+    )
+
+
+async def _generate_pdf(
+    *,
+    template_id: str,
+    settings: ConnectionSettings,
+    template_version: int | None,
+    file_data: JsonObject | None,
+    output_path: Path | None,
+    output_dir: Path | None,
+    base64_json: bool,
+) -> None:
+    async with EledoClient(base_url=settings.base_url, token=settings.token) as client:
+        result = await client.generate_pdf(
+            template_id=template_id,
+            template_version=template_version,
+            file_data=file_data,
+        )
+
+    if base64_json:
+        click.echo(json.dumps(result.as_json(), indent=2))
+        return
+
+    destination = _resolve_output_path(
+        filename=result.filename,
+        output_path=output_path,
+        output_dir=output_dir,
+    )
+    destination.write_bytes(result.content)
+    click.echo(str(destination))
+
+
+def _resolve_payload(
+    *,
+    payload: str | None,
+    payload_file: Path | None,
+    payload_stdin: bool,
+    fields: tuple[str, ...],
+) -> JsonObject | None:
+    """Read and parse document data from one configured input source."""
+    source_count = sum(
+        (
+            payload is not None,
+            payload_file is not None,
+            payload_stdin,
+        )
+    )
+
+    if source_count > 1:
+        raise click.ClickException("Use only one of --payload, --payload-file, or --payload-stdin.")
+
+    if source_count == 1 and fields:
+        click.echo(
+            "Warning: --add-field values are ignored because a JSON payload was provided.",
+            err=True,
+        )
+
+    if payload is not None:
+        return parse_json_object(payload) or None
+
+    if payload_file is not None:
+        return parse_json_object(payload_file.read_text(encoding="utf-8")) or None
+
+    if payload_stdin:
+        return parse_json_object(click.get_text_stream("stdin").read()) or None
+
+    return _build_field_payload(fields)
+
+
+def _build_field_payload(fields: tuple[str, ...]) -> JsonObject | None:
+    """Build a JSON object from repeated KEY=VALUE field arguments."""
+    if not fields:
+        return None
+
+    payload: JsonObject = {}
+
+    for field in fields:
+        key, separator, value = field.partition("=")
+
+        if separator == "":
+            raise click.ClickException(f"Invalid field {field!r}. Expected KEY=VALUE.")
+
+        key = key.strip()
+
+        if not key:
+            raise click.ClickException(f"Invalid field {field!r}. Field name cannot be empty.")
+
+        payload[key] = value
+
+    return payload
+
+
+def _resolve_output_path(
+    *,
+    filename: str,
+    output_path: Path | None,
+    output_dir: Path | None,
+) -> Path:
+    """Resolve the destination path for a generated document."""
+    if output_path is not None:
+        return output_path
+
+    if output_dir is not None:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        return output_dir / filename
+
+    return Path(filename)

eledoctl/cli/internal/docs.py

@@ -0,0 +1,37 @@
+"""Internal documentation synchronization CLI commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+
+@click.group("internal")
+def internal_group() -> None:
+    """Internal Eledo operational tooling."""
+
+
+@internal_group.group("docs")
+def internal_docs_group() -> None:
+    """Internal documentation synchronization tooling."""
+
+
+@internal_docs_group.command("sync")
+@click.argument("path", type=click.Path(path_type=Path))
+@click.option(
+    "--review-report",
+    type=click.Path(path_type=Path, dir_okay=False),
+    default=None,
+    help="Optional path where manual review report will be written.",
+)
+@click.option("--dry-run", is_flag=True, help="Analyze without uploading changes.")
+def sync_docs(path: Path, review_report: Path | None, dry_run: bool) -> None:
+    """Synchronize Git documentation into Eledo CMS.
+
+    Implementation will be added after the Eledo CMS CRUD API is available.
+    """
+    click.echo("Documentation sync scaffold is ready, but implementation is pending.")
+    click.echo(f"path={path}")
+    click.echo(f"review_report={review_report}")
+    click.echo(f"dry_run={dry_run}")

eledoctl/cli/login.py

@@ -0,0 +1,72 @@
+"""Login CLI command."""
+
+from __future__ import annotations
+
+import json
+import webbrowser
+
+import click
+
+from eledoctl.cli.common import run
+from eledoctl.config.settings import DEFAULT_BASE_URL, ConnectionSettings, save_connection_settings
+from pyeledo import EledoApiError, EledoAuthenticationError, EledoClient
+from pyeledo.profile import Profile
+
+LOGIN_PATH = "/app/login/start"
+
+
+@click.command("login")
+@click.option(
+    "--base-url",
+    default=DEFAULT_BASE_URL,
+    show_default=True,
+    help="Eledo base URL.",
+)
+def login(base_url: str) -> None:
+    """Authenticate eledoctl with an Eledo API token."""
+    normalized_base_url = base_url.rstrip("/")
+    login_url = f"{normalized_base_url}{LOGIN_PATH}"
+
+    click.echo("Opening Eledo in your browser.")
+    click.echo()
+    click.echo("To obtain your API token:")
+    click.echo("  1. Log in to your Eledo account.")
+    click.echo("  2. Open Profile in the bottom-left corner.")
+    click.echo("  3. Open the API tab under Your Profile.")
+    click.echo("  4. Generate an API key if needed, then copy it.")
+    click.echo()
+    click.echo(f"Login URL: {login_url}")
+
+    if not webbrowser.open(login_url, new=2):
+        click.echo("The browser could not be opened automatically. Open the URL above manually.", err=True)
+
+    click.echo()
+    token = click.prompt("Paste your Eledo API token", hide_input=True).strip()
+
+    if not token:
+        raise click.ClickException("The API token cannot be empty.")
+
+    settings = ConnectionSettings(
+        base_url=normalized_base_url,
+        token=token,
+    )
+
+    try:
+        profile = run(_validate_token(settings))
+    except (EledoApiError, EledoAuthenticationError) as exc:
+        raise click.ClickException(f"Authentication failed: {exc}") from exc
+
+    try:
+        save_connection_settings(ConnectionSettings(base_url=normalized_base_url, token=token))
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        raise click.ClickException(f"Could not save the local configuration: {exc}") from exc
+
+    click.echo()
+    click.echo(f"Authenticated as {profile.account}.")
+    click.echo("The API token has been saved to the local eledoctl configuration.")
+
+
+async def _validate_token(settings: ConnectionSettings) -> Profile:
+    """Validate an Eledo API token and return its profile."""
+    async with EledoClient(base_url=settings.base_url, token=settings.token) as client:
+        return await client.get_profile()

eledoctl/cli/main.py

@@ -0,0 +1,30 @@
+"""Top-level eledoctl command tree."""
+
+from __future__ import annotations
+
+import click
+
+from eledoctl.cli.documents import documents_group
+from eledoctl.cli.internal.docs import internal_group
+from eledoctl.cli.login import login
+from eledoctl.cli.profile import profile
+from eledoctl.cli.templates import templates
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+def main() -> None:
+    """Command-line toolkit for Eledo."""
+
+
+main.add_command(login)
+main.add_command(profile)
+main.add_command(templates)
+main.add_command(documents_group)
+main.add_command(internal_group)
+
+# Compatibility alias for direct imports.
+app = main
+
+
+if __name__ == "__main__":
+    main()

eledoctl/cli/profile.py

@@ -0,0 +1,26 @@
+"""Profile CLI command."""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from eledoctl.cli.common import require_connection_settings, run
+from eledoctl.config.settings import ConnectionSettings
+from pyeledo import EledoClient
+
+
+@click.command("profile")
+def profile() -> None:
+    """Fetch current Eledo profile."""
+    settings = require_connection_settings()
+    run(_profile(settings=settings))
+
+
+async def _profile(*, settings: ConnectionSettings) -> None:
+    """Fetch and print the current Eledo profile."""
+    async with EledoClient(base_url=settings.base_url, token=settings.token) as client:
+        result = await client.get_profile()
+
+    click.echo(json.dumps({"account": result.account}, indent=2))

eledoctl/cli/templates.py

@@ -0,0 +1,48 @@
+"""Template CLI commands."""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from eledoctl.cli.common import require_connection_settings, run
+from eledoctl.config.settings import ConnectionSettings
+from pyeledo import EledoClient, TemplateScope
+from pyeledo.types import JsonValue
+
+
+@click.command("templates")
+@click.option(
+    "--scope",
+    type=click.Choice(["private", "public"], case_sensitive=False),
+    default="private",
+    show_default=True,
+    help="Template scope.",
+)
+def templates(scope: str) -> None:
+    """List Eledo templates."""
+    settings = require_connection_settings()
+    template_scope = TemplateScope.PUBLIC if scope.lower() == "public" else TemplateScope.PRIVATE
+    run(_templates(settings=settings, scope=template_scope))
+
+
+async def _templates(*, settings: ConnectionSettings, scope: TemplateScope) -> None:
+    """Fetch and print Eledo templates for the selected scope."""
+    async with EledoClient(base_url=settings.base_url, token=settings.token) as client:
+        result = await client.get_templates(scope=scope)
+
+    payload: JsonValue = {
+        "total": result.total,
+        "templates": [
+            {
+                "id": template.id,
+                "name": template.name,
+                "version": template.version,
+                "bulk": template.bulk,
+            }
+            for template in result.templates
+        ],
+    }
+
+    click.echo(json.dumps(payload, indent=2))

eledoctl/config/__init__.py

@@ -0,0 +1 @@
+"""Local eledoctl configuration."""

eledoctl/config/settings.py

@@ -0,0 +1,108 @@
+"""Local configuration persistence for eledoctl."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from platformdirs import user_config_path
+
+from pyeledo.types import JsonObject, JsonValue
+
+APP_NAME = "eledoctl"
+CONFIG_FILE = "config.json"
+DEFAULT_BASE_URL = "https://eledo.online"
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionSettings:
+    base_url: str
+    token: str
+
+
+def load_connection_settings() -> ConnectionSettings:
+    """Load the default persisted Eledo connection settings."""
+    config = load_config()
+    default = config.get("default")
+
+    if not isinstance(default, dict):
+        raise ValueError("No Eledo credentials found. Run `eledoctl login` first.")
+
+    base_url = default.get("base_url")
+    token = default.get("token")
+
+    if not isinstance(base_url, str) or not base_url:
+        raise ValueError("Stored Eledo base URL is missing or invalid.")
+
+    if not isinstance(token, str) or not token:
+        raise ValueError("Stored Eledo API token is missing or invalid.")
+
+    return ConnectionSettings(
+        base_url=base_url,
+        token=token,
+    )
+
+
+def config_dir() -> Path:
+    """Return the user configuration directory."""
+    path = user_config_path(APP_NAME, ensure_exists=True)
+
+    if os.name == "posix":
+        path.chmod(0o700)
+
+    return path
+
+
+def config_path() -> Path:
+    """Return the local configuration file path."""
+    return config_dir() / CONFIG_FILE
+
+
+def load_config() -> JsonObject:
+    """Load the local eledoctl configuration."""
+    path = config_path()
+
+    if not path.exists():
+        return {}
+
+    data: JsonValue = json.loads(path.read_text(encoding="utf-8"))
+
+    if not isinstance(data, dict):
+        raise ValueError("Configuration root must be a JSON object.")
+
+    return data
+
+
+def save_config(config: JsonObject) -> None:
+    """Persist the local configuration atomically."""
+    destination = config_path()
+
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        dir=destination.parent,
+        prefix=f".{destination.name}.",
+        suffix=".tmp",
+        delete=False,
+    ) as temporary_file:
+        json.dump(config, temporary_file, indent=2, sort_keys=True)
+        temporary_file.write("\n")
+        temporary_path = Path(temporary_file.name)
+
+    if os.name == "posix":
+        temporary_path.chmod(0o600)
+
+    temporary_path.replace(destination)
+
+
+def save_connection_settings(settings: ConnectionSettings) -> None:
+    """Persist the default Eledo connection and API token."""
+    config = load_config()
+    config["default"] = {
+        "base_url": settings.base_url.rstrip("/"),
+        "token": settings.token,
+    }
+    save_config(config)

eledoctl/internal/docsync/slug.py

@@ -0,0 +1,21 @@
+"""Slug generation helpers for documentation synchronization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def build_slug(path: Path, *, docs_root: Path) -> str:
+    """Build CMS slug from a documentation file path.
+
+    Example:
+        docs/product/template-editor.md -> /product/template-editor
+    """
+    relative = path.relative_to(docs_root)
+    without_suffix = relative.with_suffix("")
+
+    parts = list(without_suffix.parts)
+    if parts[-1] == "index":
+        parts = parts[:-1]
+
+    return "/" + "/".join(parts)

eledoctl/internal/transform/markdown.py

@@ -0,0 +1,39 @@
+"""Markdown transformation helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class GitDocument:
+    """Parsed Git document with frontmatter separated from body."""
+
+    frontmatter: dict[str, Any]
+    content: str
+
+
+def parse_git_document(text: str) -> GitDocument:
+    """Parse a Markdown document and strip simple YAML frontmatter.
+
+    This intentionally avoids depending on a full YAML parser in the scaffold.
+    Complex frontmatter support can be added later if needed.
+    """
+    if not text.startswith("---\n"):
+        return GitDocument(frontmatter={}, content=text.strip())
+
+    marker = "\n---\n"
+    end = text.find(marker, 4)
+    if end == -1:
+        return GitDocument(frontmatter={}, content=text.strip())
+
+    raw_frontmatter = text[4:end]
+    body = text[end + len(marker) :]
+    frontmatter: dict[str, Any] = {}
+    for line in raw_frontmatter.splitlines():
+        if not line.strip() or ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        frontmatter[key.strip()] = value.strip().strip("\"'")
+    return GitDocument(frontmatter=frontmatter, content=body.strip())