plonecli 7.0.0b1__py3-none-any.whl

plonecli/__init__.py

@@ -0,0 +1 @@
+"""Plone CLI - A command line tool for creating Plone packages."""

plonecli/cli.py

@@ -0,0 +1,354 @@
+"""Console script for plonecli."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import subprocess
+import sys
+
+import click
+from click_aliases import ClickAliasedGroup
+
+from plonecli.config import load_config, save_config
+from plonecli.exceptions import NoSuchValue, NotInPackageError
+from plonecli.project import find_project_root
+from plonecli.registry import TemplateRegistry
+from plonecli.templates import (
+    ensure_templates_cloned,
+    get_templates_info,
+    run_add,
+    run_create,
+    update_templates_clone,
+)
+
+
+def echo(msg, fg="green", reverse=False):
+    click.echo(click.style(msg, fg=fg, reverse=reverse))
+
+
+def _get_registry():
+    """Create a TemplateRegistry with current context."""
+    config = load_config()
+    project = find_project_root()
+    return TemplateRegistry(config, project)
+
+
+def get_templates(ctx, args, incomplete):
+    """Shell completion for template names."""
+    reg = _get_registry()
+    templates = reg.get_available_templates()
+    return [k for k in templates if incomplete in k]
+
+
+class ClickFilteredAliasedGroup(ClickAliasedGroup):
+    def list_commands(self, ctx):
+        existing_cmds = super().list_commands(ctx)
+        project = find_project_root()
+        global_cmds = ["completion", "create", "config", "update"]
+        global_only_cmds = ["create"]
+        if not project:
+            cmds = [cmd for cmd in existing_cmds if cmd in global_cmds]
+        else:
+            cmds = [cmd for cmd in existing_cmds if cmd not in global_only_cmds]
+        return cmds
+
+
+@click.group(
+    cls=ClickFilteredAliasedGroup,
+    chain=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    invoke_without_command=True,
+)
+@click.option("-l", "--list-templates", "list_templates", is_flag=True)
+@click.option("-V", "--versions", "versions", is_flag=True)
+@click.pass_context
+def cli(context, list_templates, versions):
+    """Plone Command Line Interface (CLI)"""
+    config = load_config()
+    project = find_project_root()
+    context.obj = {
+        "config": config,
+        "project": project,
+        "target_dir": str(project.root_folder) if project else None,
+    }
+
+    if list_templates:
+        reg = TemplateRegistry(config, project)
+        click.echo(reg.list_templates())
+
+    if versions:
+        plonecli_version = importlib.metadata.version("plonecli")
+        templates_info = get_templates_info(config)
+        click.echo(f"plonecli: {plonecli_version}")
+        click.echo(f"copier-templates: {templates_info}")
+
+    # Check for updates (non-blocking, cached)
+    if not list_templates and not versions:
+        try:
+            from plonecli.updater import check_for_updates
+
+            new_version = check_for_updates()
+            if new_version:
+                echo(
+                    f"\nA new version of plonecli is available: {new_version}",
+                    fg="yellow",
+                )
+                echo(
+                    "Update with: uv tool upgrade plonecli\n",
+                    fg="yellow",
+                )
+        except Exception:  # noqa: BLE001
+            pass
+
+
+@cli.command()
+@click.argument("template", type=click.STRING, shell_complete=get_templates)
+@click.argument("name")
+@click.pass_context
+def create(context, template, name):
+    """Create a new Plone package"""
+    config = context.obj["config"]
+    reg = TemplateRegistry(config)
+
+    resolved = reg.resolve_template_name(template)
+    if resolved is None or not reg.is_main_template(resolved):
+        raise NoSuchValue(
+            context.command.name,
+            template,
+            possibilities=reg.get_main_templates(),
+        )
+
+    echo(f"\nCreating {resolved} project: {name}", fg="green", reverse=True)
+    run_create(resolved, name, config)
+    context.obj["target_dir"] = name
+
+
+@cli.command()
+@click.argument("template", type=click.STRING, shell_complete=get_templates)
+@click.pass_context
+def add(context, template):
+    """Add features to your existing Plone package"""
+    project = context.obj.get("project")
+    if project is None:
+        raise NotInPackageError(context.command.name)
+
+    config = context.obj["config"]
+    reg = TemplateRegistry(config, project)
+
+    resolved = reg.resolve_template_name(template)
+    if resolved is None or not reg.is_subtemplate(resolved):
+        raise NoSuchValue(
+            context.command.name,
+            template,
+            possibilities=reg.get_subtemplates(),
+        )
+
+    echo(f"\nAdding {resolved} to {project.root_folder.name}", fg="green", reverse=True)
+    run_add(resolved, project, config)
+
+
+@cli.command()
+@click.pass_context
+def setup(context):
+    """Run zope-setup inside an existing backend_addon"""
+    project = context.obj.get("project")
+    if project is None:
+        raise NotInPackageError(context.command.name)
+    if project.project_type != "backend_addon":
+        raise click.UsageError(
+            "The 'setup' command can only be run inside a backend_addon project."
+        )
+
+    config = context.obj["config"]
+    echo("\nRunning zope-setup...", fg="green", reverse=True)
+    run_create("zope-setup", str(project.root_folder), config)
+
+
+@cli.command("serve")
+@click.pass_context
+def run_serve(context):
+    """Start the Plone instance (delegates to invoke start)"""
+    project = context.obj.get("project")
+    if project is None:
+        raise NotInPackageError(context.command.name)
+    params = ["uv", "run", "invoke", "start"]
+    echo(f"\nRUN: {' '.join(params)}", fg="green", reverse=True)
+    echo("\nINFO: Open this in a Web Browser: http://localhost:8080")
+    echo("INFO: You can stop it by pressing CTRL + c\n")
+    subprocess.call(params, cwd=str(project.root_folder))
+
+
+@cli.command("test")
+@click.option("-v", "--verbose", is_flag=True, help="Verbose test output")
+@click.pass_context
+def run_test(context, verbose):
+    """Run the tests in your package (delegates to invoke test)"""
+    project = context.obj.get("project")
+    if project is None:
+        raise NotInPackageError(context.command.name)
+    params = ["uv", "run", "invoke", "test"]
+    if verbose:
+        params.append("--verbose")
+    echo(f"\nRUN: {' '.join(params)}", fg="green", reverse=True)
+    subprocess.call(params, cwd=str(project.root_folder))
+
+
+@cli.command("debug")
+@click.pass_context
+def run_debug(context):
+    """Start the Plone instance in debug mode (delegates to invoke debug)"""
+    project = context.obj.get("project")
+    if project is None:
+        raise NotInPackageError(context.command.name)
+    params = ["uv", "run", "invoke", "debug"]
+    echo(f"\nRUN: {' '.join(params)}", fg="green", reverse=True)
+    echo("INFO: You can stop it by pressing CTRL + c\n")
+    subprocess.call(params, cwd=str(project.root_folder))
+
+
+@cli.command()
+@click.pass_context
+def config(context):
+    """Configure plonecli global settings"""
+    cfg = context.obj["config"]
+
+    # Check for migration from .mrbob on first run
+    from plonecli.config import CONFIG_FILE, migrate_from_mrbob
+
+    if not CONFIG_FILE.exists():
+        migrated = migrate_from_mrbob()
+        if migrated:
+            echo("Found existing ~/.mrbob configuration.", fg="yellow")
+            if click.confirm("Import settings from ~/.mrbob?", default=True):
+                cfg = migrated
+
+    # Interactive prompts with current values as defaults
+    cfg.author_name = click.prompt("Author name", default=cfg.author_name)
+    cfg.author_email = click.prompt("Author email", default=cfg.author_email)
+    cfg.github_user = click.prompt("GitHub username", default=cfg.github_user)
+
+    # Suggest latest Plone version
+    from plonecli.plone_versions import get_latest_stable_version
+
+    default_version = cfg.plone_version or get_latest_stable_version()
+    cfg.plone_version = click.prompt(
+        "Default Plone version", default=default_version
+    )
+
+    cfg.repo_url = click.prompt("Templates repo URL", default=cfg.repo_url)
+    cfg.repo_branch = click.prompt("Templates branch", default=cfg.repo_branch)
+
+    save_config(cfg)
+    echo(f"\nConfiguration saved to {CONFIG_FILE}", fg="green")
+
+
+@cli.command()
+@click.pass_context
+def update(context):
+    """Update copier-templates and check for plonecli updates"""
+    config = context.obj["config"]
+
+    # Update templates clone
+    echo("\nUpdating copier-templates...", fg="green")
+    try:
+        ensure_templates_cloned(config)
+        msg = update_templates_clone(config)
+        echo(f"  {msg}", fg="green")
+    except Exception as e:  # noqa: BLE001
+        echo(f"  Failed to update templates: {e}", fg="red")
+
+    # Check PyPI for plonecli updates
+    echo("\nChecking for plonecli updates...", fg="green")
+    try:
+        from plonecli.updater import check_for_updates
+
+        new_version = check_for_updates(force=True)
+        if new_version:
+            current = importlib.metadata.version("plonecli")
+            echo(
+                f"  New version available: {new_version} (current: {current})",
+                fg="yellow",
+            )
+            echo("  Update with: uv tool upgrade plonecli", fg="yellow")
+        else:
+            echo("  plonecli is up to date.", fg="green")
+    except Exception as e:  # noqa: BLE001
+        echo(f"  Could not check for updates: {e}", fg="red")
+
+    # Show templates info
+    echo(f"\nTemplates: {get_templates_info(config)}", fg="green")
+
+
+@cli.command()
+@click.argument(
+    "shell",
+    required=False,
+    type=click.Choice(["bash", "zsh", "fish"]),
+)
+@click.option("--install", is_flag=True, help="Install completion into your shell config")
+def completion(shell, install):
+    """Show or install shell completion.
+
+    Without arguments, auto-detects your shell and prints the completion script.
+    Use --install to append the activation line to your shell config file.
+    """
+    import os
+
+    if shell is None:
+        login_shell = os.path.basename(os.environ.get("SHELL", ""))
+        if login_shell in ("bash", "zsh", "fish"):
+            shell = login_shell
+        else:
+            raise click.UsageError(
+                f"Could not detect shell (SHELL={os.environ.get('SHELL', '')!r}).\n"
+                "Please specify one: plonecli completion bash|zsh|fish"
+            )
+
+    env_var = "_PLONECLI_COMPLETE"
+    source_cmd = f"{env_var}={shell}_source plonecli"
+
+    if not install:
+        # Print the completion script to stdout
+        import subprocess as _sp
+
+        env = {**os.environ, env_var: f"{shell}_source"}
+        result = _sp.run(["plonecli"], capture_output=True, text=True, env=env)
+        if result.stdout:
+            click.echo(result.stdout)
+        else:
+            # Fallback: print eval instruction
+            click.echo(f'eval "$({source_cmd})"')
+        return
+
+    # --install: append eval line to the appropriate rc file
+    rc_files = {
+        "bash": os.path.expanduser("~/.bashrc"),
+        "zsh": os.path.expanduser("~/.zshrc"),
+        "fish": os.path.expanduser("~/.config/fish/completions/plonecli.fish"),
+    }
+    rc_file = rc_files[shell]
+
+    if shell == "fish":
+        # Fish uses a completions directory with the script itself
+        os.makedirs(os.path.dirname(rc_file), exist_ok=True)
+        eval_line = f"env {source_cmd} | source"
+    else:
+        eval_line = f'eval "$({source_cmd})"'
+
+    # Check if already installed
+    if os.path.exists(rc_file):
+        with open(rc_file) as f:
+            content = f.read()
+        if "_PLONECLI_COMPLETE" in content:
+            echo(f"Shell completion already configured in {rc_file}", fg="yellow")
+            return
+
+    with open(rc_file, "a") as f:
+        f.write(f"\n# plonecli shell completion\n{eval_line}\n")
+
+    echo(f"Shell completion installed in {rc_file}", fg="green")
+    echo(f"Restart your shell or run: source {rc_file}", fg="green")
+
+
+if __name__ == "__main__":
+    cli()

plonecli/config.py

@@ -0,0 +1,127 @@
+"""Global plonecli configuration management."""
+
+from __future__ import annotations
+
+import configparser
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+CONFIG_DIR = Path.home() / ".plonecli"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+TEMPLATES_DIR = Path.home() / ".copier-templates" / "plone-copier-templates"
+DEFAULT_REPO_URL = "https://github.com/plone/copier-templates"
+DEFAULT_BRANCH = "main"
+
+# Environment variable overrides
+ENV_REPO_URL = "PLONECLI_TEMPLATES_REPO_URL"
+ENV_REPO_BRANCH = "PLONECLI_TEMPLATES_BRANCH"
+ENV_TEMPLATES_DIR = "PLONECLI_TEMPLATES_DIR"
+
+
+@dataclass
+class PlonecliConfig:
+    author_name: str = "Plone Developer"
+    author_email: str = "dev@plone.org"
+    github_user: str = ""
+    plone_version: str = ""
+    repo_url: str = DEFAULT_REPO_URL
+    repo_branch: str = DEFAULT_BRANCH
+    templates_dir: str = str(TEMPLATES_DIR)
+
+
+def load_config() -> PlonecliConfig:
+    """Load config from ~/.plonecli/config.toml.
+
+    Environment variables take precedence over config file values:
+    - PLONECLI_TEMPLATES_REPO_URL: Override the templates repo URL
+    - PLONECLI_TEMPLATES_BRANCH: Override the templates branch
+    - PLONECLI_TEMPLATES_DIR: Override the local templates directory
+
+    Returns a PlonecliConfig with defaults for any missing values.
+    """
+    config = PlonecliConfig()
+    if CONFIG_FILE.exists():
+        with open(CONFIG_FILE, "rb") as f:
+            data = tomllib.load(f)
+
+        author = data.get("author", {})
+        defaults = data.get("defaults", {})
+        templates = data.get("templates", {})
+
+        config.author_name = author.get("name", config.author_name)
+        config.author_email = author.get("email", config.author_email)
+        config.github_user = author.get("github_user", config.github_user)
+        config.plone_version = defaults.get("plone_version", config.plone_version)
+        config.repo_url = templates.get("repo_url", config.repo_url)
+        config.repo_branch = templates.get("branch", config.repo_branch)
+        config.templates_dir = templates.get("local_path", config.templates_dir)
+
+    # Environment variables override config file
+    if os.environ.get(ENV_REPO_URL):
+        config.repo_url = os.environ[ENV_REPO_URL]
+    if os.environ.get(ENV_REPO_BRANCH):
+        config.repo_branch = os.environ[ENV_REPO_BRANCH]
+    if os.environ.get(ENV_TEMPLATES_DIR):
+        config.templates_dir = os.environ[ENV_TEMPLATES_DIR]
+
+    # Expand ~ in templates_dir
+    config.templates_dir = str(Path(config.templates_dir).expanduser())
+
+    return config
+
+
+def save_config(config: PlonecliConfig) -> None:
+    """Save config to ~/.plonecli/config.toml."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    content = f"""\
+[author]
+name = "{config.author_name}"
+email = "{config.author_email}"
+github_user = "{config.github_user}"
+
+[defaults]
+plone_version = "{config.plone_version}"
+
+[templates]
+repo_url = "{config.repo_url}"
+branch = "{config.repo_branch}"
+local_path = "{config.templates_dir}"
+"""
+    CONFIG_FILE.write_text(content)
+
+
+def migrate_from_mrbob() -> PlonecliConfig | None:
+    """Attempt to read settings from ~/.mrbob and return a config.
+
+    Returns None if ~/.mrbob doesn't exist or can't be parsed.
+    """
+    mrbob_file = Path.home() / ".mrbob"
+    if not mrbob_file.exists():
+        return None
+
+    parser = configparser.ConfigParser()
+    try:
+        parser.read(str(mrbob_file))
+    except configparser.Error:
+        return None
+
+    config = PlonecliConfig()
+    if parser.has_section("variables"):
+        variables = dict(parser.items("variables"))
+        config.author_name = variables.get("author.name", config.author_name)
+        config.author_email = variables.get("author.email", config.author_email)
+        config.github_user = variables.get(
+            "author.github.user", config.github_user
+        )
+
+    if parser.has_section("defaults"):
+        defaults = dict(parser.items("defaults"))
+        config.plone_version = defaults.get(
+            "plone.version", config.plone_version
+        )
+
+    return config

plonecli/exceptions.py

@@ -0,0 +1,28 @@
+"""Custom exceptions."""
+
+from __future__ import annotations
+
+from click.exceptions import BadOptionUsage, NoSuchOption
+
+
+class NotInPackageError(BadOptionUsage):
+    """Raised if a command is used outside a Plone project."""
+
+    message = 'The "{0}" command is only allowed within an existing package.'
+
+    def __init__(self, option_name, ctx=None):
+        message = self.message.format(option_name)
+        super().__init__(option_name, message, ctx)
+        self.option_name = option_name
+
+
+class NoSuchValue(NoSuchOption):
+    """Raised if an unknown template name is provided."""
+
+    message = 'No such value: "{0}".'
+
+    def __init__(self, option_name, value, possibilities=None, ctx=None):
+        message = self.message.format(value)
+        super().__init__(option_name, message, possibilities, ctx)
+        self.option_name = option_name
+        self.possibilities = possibilities

plonecli/plone_versions.py

@@ -0,0 +1,122 @@
+"""Fetch and cache available Plone versions from dist.plone.org."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from urllib.error import URLError
+from urllib.request import urlopen
+
+from plonecli.config import CONFIG_DIR
+
+
+PLONE_VERSIONS_URL = "https://dist.plone.org/release/"
+VERSIONS_CACHE_FILE = CONFIG_DIR / ".plone_versions_cache.json"
+CACHE_MAX_AGE = timedelta(hours=24)
+FALLBACK_VERSION = "6.1.1"
+
+
+def fetch_stable_versions() -> list[str]:
+    """Fetch directory listing from dist.plone.org/release/ and return
+    stable versions sorted descending (newest first).
+
+    Filters out alpha, beta, rc, and dev releases.
+    """
+    response = urlopen(PLONE_VERSIONS_URL, timeout=10)  # noqa: S310
+    html = response.read().decode("utf-8")
+
+    # Parse directory listing: links like href="6.1.1/"
+    version_pattern = re.compile(r'href="(\d+\.\d+[\.\d]*)/?"')
+    versions = []
+    for match in version_pattern.finditer(html):
+        v = match.group(1)
+        # Filter: no alpha/beta/rc/dev in the version string
+        if not re.search(r"(a|b|rc|dev|alpha|beta)", v, re.IGNORECASE):
+            versions.append(v)
+
+    # Sort by version tuple, descending
+    versions.sort(
+        key=lambda v: tuple(int(x) for x in v.split(".")),
+        reverse=True,
+    )
+    return versions
+
+
+def _read_cache() -> dict | None:
+    """Read the versions cache file. Returns None if missing or expired."""
+    if not VERSIONS_CACHE_FILE.exists():
+        return None
+
+    try:
+        data = json.loads(VERSIONS_CACHE_FILE.read_text())
+        last_check = datetime.fromisoformat(data["last_check"])
+        if datetime.now(timezone.utc) - last_check > CACHE_MAX_AGE:
+            return None
+        return data
+    except (json.JSONDecodeError, KeyError, ValueError):
+        return None
+
+
+def _write_cache(versions: list[str], latest: str) -> None:
+    """Write the versions cache file."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    data = {
+        "last_check": datetime.now(timezone.utc).isoformat(),
+        "versions": versions,
+        "latest": latest,
+    }
+    VERSIONS_CACHE_FILE.write_text(json.dumps(data))
+
+
+def get_latest_stable_version(force: bool = False) -> str:
+    """Return the latest stable Plone version, cached for 24h.
+
+    Falls back to FALLBACK_VERSION if offline or fetch fails.
+    """
+    if not force:
+        cache = _read_cache()
+        if cache:
+            return cache.get("latest", FALLBACK_VERSION)
+
+    try:
+        versions = fetch_stable_versions()
+        if versions:
+            latest = versions[0]
+            _write_cache(versions, latest)
+            return latest
+    except (URLError, OSError, TimeoutError):
+        pass
+
+    # Try stale cache before falling back
+    if VERSIONS_CACHE_FILE.exists():
+        try:
+            data = json.loads(VERSIONS_CACHE_FILE.read_text())
+            return data.get("latest", FALLBACK_VERSION)
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    return FALLBACK_VERSION
+
+
+def get_version_choices(force: bool = False) -> list[str]:
+    """Return recent stable versions suitable for template choices.
+
+    Returns up to 5 most recent stable versions, e.g. ['6.1.1', '6.1.0', '6.0.13'].
+    """
+    if not force:
+        cache = _read_cache()
+        if cache:
+            return cache.get("versions", [FALLBACK_VERSION])[:5]
+
+    try:
+        versions = fetch_stable_versions()
+        if versions:
+            latest = versions[0]
+            _write_cache(versions, latest)
+            return versions[:5]
+    except (URLError, OSError, TimeoutError):
+        pass
+
+    return [FALLBACK_VERSION]