git-ftp 2.0.0.dev0__py3-none-any.whl

gitftp/cli/cmd_snapshot.py

@@ -0,0 +1,20 @@
+"""The ``snapshot`` action: turn a remote directory into a new repository."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from gitftp import mirror
+from gitftp.cli.options import common_options, prepare, url_argument
+
+
+@click.command("snapshot", short_help="Download a remote directory into a new repository.")
+@common_options
+@url_argument
+@click.argument("directory", required=False, metavar="[DIRECTORY]")
+@click.pass_context
+def command(ctx: click.Context, /, url: str | None, directory: str | None, **kw: Any) -> None:
+    opts, out = prepare(ctx, kw)
+    mirror.run_snapshot(opts, url, directory, out)

gitftp/cli/cmd_unlock.py

@@ -0,0 +1,19 @@
+"""The ``unlock`` action (new): remove a stale remote lock."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from gitftp import mirror
+from gitftp.cli.options import common_options, session_for, url_argument
+
+
+@click.command("unlock", short_help="Remove a stale remote lock left by an interrupted deploy.")
+@common_options
+@url_argument
+@click.pass_context
+def command(ctx: click.Context, /, url: str | None, **kw: Any) -> None:
+    _opts, session = session_for(ctx, url, kw, need_repo=False)
+    mirror.run_unlock(session)

gitftp/cli/cmd_version.py

@@ -0,0 +1,19 @@
+"""The ``version`` action."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from gitftp.cli.options import common_options
+from gitftp.version import runtime_info, version_line
+
+
+@click.command("version", short_help="Print the version.")
+@common_options
+def command(verbose: int = 0, **_kw: Any) -> None:
+    click.echo(version_line())
+    if verbose:
+        for line in runtime_info():
+            click.echo(line)

gitftp/cli/group.py

@@ -0,0 +1,68 @@
+"""The click group and the action registry."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+import click
+
+from gitftp.version import version_line
+
+ACTIONS: tuple[str, ...] = (
+    "init",
+    "push",
+    "catchup",
+    "show",
+    "log",
+    "download",
+    "pull",
+    "snapshot",
+    "add-scope",
+    "remove-scope",
+    "unlock",
+    "help",
+    "version",
+)
+
+_MODULES = {name: f"gitftp.cli.cmd_{name.replace('-', '_')}" for name in ACTIONS}
+
+
+class GitFtpGroup(click.Group):
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return list(ACTIONS)
+
+
+def _print_version(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
+    if not value or ctx.resilient_parsing:
+        return
+    click.echo(version_line())
+    ctx.exit(0)
+
+
+def build_group() -> click.Group:
+    @click.group(
+        cls=GitFtpGroup,
+        name="git-ftp",
+        context_settings={"help_option_names": ["-h", "--help"], "max_content_width": 100},
+        invoke_without_command=True,
+        help="Git powered FTP, FTPS, FTPES and SFTP client.",
+    )
+    @click.option(
+        "--version",
+        is_flag=True,
+        expose_value=False,
+        is_eager=True,
+        callback=_print_version,
+        help="Print the version and exit.",
+    )
+    @click.pass_context
+    def group(ctx: click.Context, /, **_kw: Any) -> None:
+        if ctx.invoked_subcommand is None:
+            click.echo("git-ftp <action> [<options>] [<url>]")
+            ctx.exit(2)
+
+    for name, module_name in _MODULES.items():
+        module = importlib.import_module(module_name)
+        group.add_command(module.command, name=name)
+    return group

gitftp/cli/options.py

@@ -0,0 +1,208 @@
+"""Options shared by every action, plus helpers for command modules."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, TypeVar
+
+import click
+
+from gitftp.options import CliOptions
+from gitftp.output import Output
+from gitftp.session import Session, open_session
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Options that take a value; the CLI normaliser must not mistake the value for the action.
+VALUE_OPTIONS = frozenset(
+    {
+        "-u",
+        "--user",
+        "-p",
+        "--passwd",
+        "--password",
+        "--password-command",
+        "-k",
+        "--keychain",
+        "--key",
+        "--pubkey",
+        "--key-passphrase",
+        "-b",
+        "--branch",
+        "-c",
+        "--commit",
+        "-s",
+        "--scope",
+        "--syncroot",
+        "--remote-root",
+        "--cacert",
+        "-x",
+        "--proxy",
+        "-j",
+        "--jobs",
+    }
+)
+OPTIONAL_VALUE_OPTIONS = frozenset({"-u", "--user", "-k", "--keychain", "-s", "--scope"})
+_LONG = {"-u": "--user", "-k": "--keychain", "-s": "--scope"}
+
+
+def long_name(opt: str) -> str:
+    return _LONG.get(opt, opt)
+
+
+def common_options(f: F) -> F:
+    decorators = [
+        click.option(
+            "-u",
+            "--user",
+            "user",
+            is_flag=False,
+            flag_value="",
+            default=None,
+            metavar="[USER]",
+            help="FTP login name (bare -u: the local user).",
+        ),
+        click.option(
+            "-p",
+            "--passwd",
+            "--password",
+            "password",
+            default=None,
+            metavar="PASSWORD",
+            help="FTP password.",
+        ),
+        click.option(
+            "-P",
+            "--ask-passwd",
+            "ask_password",
+            is_flag=True,
+            help="Ask for the password interactively.",
+        ),
+        click.option(
+            "--password-command",
+            default=None,
+            metavar="CMD",
+            help="Shell command whose first output line is the password.",
+        ),
+        click.option(
+            "-k",
+            "--keychain",
+            "keychain",
+            is_flag=False,
+            flag_value="",
+            default=None,
+            metavar="[[ACCOUNT]@[HOST]]",
+            help="macOS keychain entry (bare -k: guess).",
+        ),
+        click.option("--key", default=None, metavar="FILE", help="SFTP private key."),
+        click.option("--pubkey", default=None, metavar="FILE", help="SFTP public key."),
+        click.option(
+            "--key-passphrase",
+            default=None,
+            metavar="TEXT",
+            help="Passphrase of the SFTP private key.",
+        ),
+        click.option(
+            "-b",
+            "--branch",
+            default=None,
+            metavar="BRANCH",
+            help="Deploy this branch instead of the current one.",
+        ),
+        click.option(
+            "-c",
+            "--commit",
+            default=None,
+            metavar="SHA",
+            help="Treat SHA as the deployed commit instead of reading the remote log.",
+        ),
+        click.option(
+            "-s",
+            "--scope",
+            "scope",
+            is_flag=False,
+            flag_value="",
+            default=None,
+            metavar="[SCOPE]",
+            help="Configuration scope (bare -s: current branch).",
+        ),
+        click.option(
+            "--syncroot",
+            default=None,
+            metavar="DIR",
+            help="Deploy only this directory, as the remote root.",
+        ),
+        click.option(
+            "--remote-root",
+            default=None,
+            metavar="DIR",
+            help="Remote directory, replacing the path in the URL.",
+        ),
+        click.option(
+            "--cacert", default=None, metavar="FILE", help="CA certificate bundle for FTPS/FTPES."
+        ),
+        click.option("-x", "--proxy", default=None, metavar="URL", help="Proxy URL."),
+        click.option(
+            "-j",
+            "--jobs",
+            type=int,
+            default=None,
+            metavar="N",
+            help="Parallel connections (default 4, 1 = sequential).",
+        ),
+        click.option(
+            "-a", "--all", "all", is_flag=True, help="Upload all files, not only changes."
+        ),
+        click.option("-A", "--active", is_flag=True, help="Use FTP active mode."),
+        click.option("-l", "--lock", is_flag=True, help="Lock the remote during the deploy."),
+        click.option("-D", "--dry-run", is_flag=True, help="Show what would happen."),
+        click.option("-f", "--force", is_flag=True, help="Skip the lock check and questions."),
+        click.option("-n", "--silent", is_flag=True, help="Print nothing but fatal errors."),
+        click.option("-v", "--verbose", count=True, help="Verbose (-vv: protocol trace)."),
+        click.option(
+            "--insecure", is_flag=True, help="Do not verify TLS certificates / host keys."
+        ),
+        click.option("--disable-epsv", is_flag=True, help="Use PASV instead of EPSV."),
+        click.option("--no-commit", is_flag=True, help="pull: merge without committing."),
+        click.option(
+            "--changed-only",
+            is_flag=True,
+            help="download/pull: only files that changed locally as well.",
+        ),
+        click.option("--no-verify", is_flag=True, help="Skip the pre-ftp-push hook."),
+        click.option("--no-post-hooks", is_flag=True, help="Skip the post-ftp-push hook."),
+        click.option(
+            "--enable-post-errors", is_flag=True, help="Fail when the post-ftp-push hook fails."
+        ),
+        click.option("--auto-init", is_flag=True, help="push: init when the remote has no log."),
+        click.option(
+            "--worktree",
+            is_flag=True,
+            help="Upload files from a temporary git worktree so edits to the working "
+            "tree during the upload are ignored.",
+        ),
+    ]
+    for d in reversed(decorators):
+        f = d(f)
+    return f
+
+
+url_argument = click.argument("url", required=False, metavar="[URL]")
+
+
+def prepare(ctx: click.Context, kw: dict[str, Any]) -> tuple[CliOptions, Output]:
+    opts = CliOptions.from_kwargs(kw)
+    out: Output = ctx.obj if isinstance(ctx.obj, Output) else Output()
+    out.level = opts.level
+    ctx.obj = out
+    return opts, out
+
+
+def session_for(
+    ctx: click.Context, url: str | None, kw: dict[str, Any], *, need_repo: bool = True
+) -> tuple[CliOptions, Session]:
+    opts, out = prepare(ctx, kw)
+    session = open_session(opts, url, out, cwd=Path.cwd(), need_repo=need_repo)
+    ctx.call_on_close(session.close)
+    return opts, session

gitftp/config.py

@@ -0,0 +1,170 @@
+"""Configuration lookup with upstream's precedence.
+
+Order for a key ``k`` with scope ``s`` (first *found* wins, even if the value
+is empty, because ``git-ftp.<scope>.url ""`` is the documented way to mask a
+default):
+
+1. ``.git-ftp-config`` in the repository: ``git-ftp.<s>.k``
+2. ``.git-ftp-config``: ``git-ftp.k``
+3. git config (system, global, local merged): ``git-ftp.<s>.k``
+4. git config: ``git-ftp.k``
+
+A valueless key (a bare ``insecure`` line) is read as true, as git reads it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from gitftp import url as urlmod
+from gitftp.errors import GitError, MissingArgumentError, UsageError
+from gitftp.gitrepo import GitRunner
+
+SECTION = "git-ftp"
+CONFIG_FILE = ".git-ftp-config"
+DEFAULT_DEPLOYED_SHA1_FILE = ".git-ftp.log"
+DEFAULT_JOBS = 4
+SCOPE_RE = re.compile(r"^[-0-9a-zA-Z_/]+$")
+
+KEYS = (
+    "url",
+    "user",
+    "password",
+    "password-command",
+    "keychain",
+    "cacert",
+    "insecure",
+    "disable-epsv",
+    "proxy",
+    "no-commit",
+    "branch",
+    "syncroot",
+    "key",
+    "pubkey",
+    "key-passphrase",
+    "remote-root",
+    "deployedsha1file",
+    "jobs",
+    "worktree",
+)
+
+_TRUE = frozenset({"true", "yes", "on", "1"})
+_FALSE = frozenset({"false", "no", "off", "0", ""})
+
+
+def parse_bool(value: str | None) -> bool | None:
+    """Git's boolean spellings. ``None`` (valueless) is true; unknown text is ``None``."""
+    if value is None:
+        return True
+    v = value.strip().lower()
+    if v in _TRUE:
+        return True
+    if v in _FALSE:
+        return False
+    return None
+
+
+class Config:
+    def __init__(
+        self,
+        scope: str | None,
+        file_cfg: Mapping[str, str | None],
+        git_cfg: Mapping[str, str | None],
+    ) -> None:
+        self.scope = scope
+        self._sources: tuple[Mapping[str, str | None], ...] = (file_cfg, git_cfg)
+
+    @classmethod
+    def load(cls, git: GitRunner, root: Path | None, scope: str | None) -> Config:
+        file_cfg: Mapping[str, str | None] = {}
+        base = root if root is not None else git.cwd
+        cfg_file = base / CONFIG_FILE
+        if cfg_file.is_file():
+            file_cfg = git.config_list(cfg_file)
+        git_cfg = git.config_list()
+        return cls(scope, file_cfg, git_cfg)
+
+    # -- lookups -----------------------------------------------------------
+    def lookup_raw(self, key: str) -> tuple[bool, str | None]:
+        """(found, value); value is None for a valueless key."""
+        for src in self._sources:
+            if self.scope:
+                scoped = f"{SECTION}.{self.scope}.{key}"
+                if scoped in src:
+                    return True, src[scoped]
+            plain = f"{SECTION}.{key}"
+            if plain in src:
+                return True, src[plain]
+        return False, None
+
+    def lookup(self, key: str) -> str | None:
+        """The value, or ``None`` when the key is absent. A valueless key reads as ''."""
+        found, value = self.lookup_raw(key)
+        if not found:
+            return None
+        return "" if value is None else value
+
+    def get(self, key: str, default: str = "") -> str:
+        value = self.lookup(key)
+        return default if value is None else value
+
+    def get_bool(self, key: str, default: bool = False) -> bool:
+        found, value = self.lookup_raw(key)
+        if not found:
+            return default
+        parsed = parse_bool(value)
+        if parsed is None:
+            raise UsageError(f"Invalid boolean value '{value}' for git-ftp.{key}.")
+        return parsed
+
+    def get_int(self, key: str, default: int) -> int:
+        value = self.lookup(key)
+        if value is None or value == "":
+            return default
+        try:
+            return int(value)
+        except ValueError:
+            raise UsageError(f"Invalid number '{value}' for git-ftp.{key}.") from None
+
+    def git_option(self, dotted: str) -> str | None:
+        """An ordinary (never scoped) git option such as ``http.proxy``."""
+        value = self._sources[1].get(dotted.lower())
+        return value
+
+
+# -- scopes -----------------------------------------------------------------
+def validate_scope(name: str, *, from_option: bool) -> str:
+    if not name:
+        raise MissingArgumentError("Missing scope argument.")
+    if not SCOPE_RE.match(name):
+        if from_option:
+            raise UsageError(f"Invalid scope name '{name}'.")
+        raise UsageError("Invalid scope name. Only these characters are allowed: 0-9 a-z A-Z - _ /")
+    return name
+
+
+def add_scope(git: GitRunner, scope: str, raw_url: str) -> None:
+    """``git ftp add-scope``: store url/user/password in the local git config."""
+    validate_scope(scope, from_option=False)
+    if not raw_url:
+        raise MissingArgumentError("Missing URL argument.")
+    u = urlmod.parse(raw_url)
+    lead = "/" if u.absolute else ""
+    bare = (
+        f"{u.scheme.value}://{u.host}/{lead}{u.path}".rstrip("/")
+        if u.path
+        else (f"{u.scheme.value}://{u.host}/{lead}".rstrip("/"))
+    )
+    git.config_set(f"{SECTION}.{scope}.url", bare)
+    if u.user is not None:
+        git.config_set(f"{SECTION}.{scope}.user", u.user)
+    if u.password is not None:
+        git.config_set(f"{SECTION}.{scope}.password", u.password)
+
+
+def remove_scope(git: GitRunner, scope: str) -> None:
+    validate_scope(scope, from_option=False)
+    if not git.config_remove_section(f"{SECTION}.{scope}"):
+        raise GitError(f"Cannot find scope {scope}.")