jpsync 1.0.0__py3-none-any.whl

jp/commands/__init__.py

@@ -0,0 +1,39 @@
+"""Command registry: each module exposes add_parser(subparsers)."""
+
+from __future__ import annotations
+
+from . import (
+    clone,
+    config_cmd,
+    diff,
+    doctor,
+    ignore_cmd,
+    init,
+    kernel,
+    login,
+    ls,
+    pull,
+    push,
+    rm,
+    status,
+    update,
+    version,
+)
+
+ALL = [
+    clone,
+    init,
+    login,
+    pull,
+    push,
+    status,
+    ls,
+    diff,
+    config_cmd,
+    ignore_cmd,
+    rm,
+    kernel,
+    doctor,
+    update,
+    version,
+]

jp/commands/_context.py

@@ -0,0 +1,99 @@
+"""Shared helpers for commands: locate the repo and build a live API client."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .. import config as config_mod
+from ..api import Api
+from ..config import Config
+from ..errors import ConfigError
+from ..ignore import IgnoreSet
+from ..index import Index
+
+
+@dataclass
+class RepoContext:
+    root: Path
+    cfg: Config
+    index: Index
+    ignore: IgnoreSet
+
+
+def load_repo() -> RepoContext:
+    """Locate the jp repo from the cwd and load its config/index/ignore."""
+    from ..paths import find_root
+
+    root = find_root()
+    if root is None:
+        raise ConfigError(
+            "not inside a jp repository (no .jp directory found). "
+            "Run 'jp init' or 'jp clone' first."
+        )
+    cfg = config_mod.load(root)
+    # Apply the workspace color policy (env/--no-color still override it).
+    from .. import ui
+
+    ui.set_color_mode(cfg.color)
+    index = Index.load(root)
+    ignore = IgnoreSet.from_root(root)
+    return RepoContext(root=root, cfg=cfg, index=index, ignore=ignore)
+
+
+def build_api(cfg: Config) -> Api:
+    """Construct an Api client, loading the token (and registering it for redaction)."""
+    token = config_mod.load_token(cfg)
+    return Api(cfg.base_url, token)
+
+
+def choose_credential(args: object, root: Path | None = None) -> str:
+    """Decide which saved credential ``clone``/``init`` should record.
+
+    Returns the credential NAME to store in the new workspace's config, or ``""``
+    when no credential applies (an explicit ``--token-path`` or a ``JP_TOKEN``/
+    ``JP_TOKEN_FILE`` env token is being used instead).
+
+    Resolution: an explicit ``--credential`` is validated against what exists;
+    otherwise zero credentials is an error (run ``jp login`` first), exactly one
+    is used silently, and several trigger an interactive picker (or, in a
+    non-interactive shell, an error asking for ``--credential``).
+    """
+    import os
+
+    from .. import credentials, tui
+    from ..errors import AuthError, UsageError
+
+    # An explicit token path bypasses the credential system entirely.
+    if getattr(args, "token_path", ""):
+        return ""
+
+    requested = (getattr(args, "credential", "") or "").strip()
+    available = credentials.list_credentials(root=root)
+
+    if requested:
+        if not any(c.name == requested for c in available):
+            names = ", ".join(c.name for c in available) or "(none)"
+            raise UsageError(f"no saved credential named {requested!r}. Available: {names}")
+        return requested
+
+    if not available:
+        if os.environ.get("JP_TOKEN") or os.environ.get("JP_TOKEN_FILE"):
+            return ""
+        raise AuthError("no credentials configured. Run 'jp login' first to save your API token.")
+
+    if len(available) == 1:
+        return available[0].name
+
+    # More than one: let the user choose.
+    if tui.interactive():
+        labels = [f"{c.name}  ({c.scope})" for c in available]
+        idx = tui.select_one(labels, title="Select a credential for this workspace")
+        if idx is None:
+            raise UsageError("no credential selected")
+        return available[idx].name
+
+    names = ", ".join(c.name for c in available)
+    raise UsageError(
+        f"multiple saved credentials; choose one with --credential NAME (one of: {names})"
+    )

jp/commands/_mirror.py

@@ -0,0 +1,100 @@
+"""Mirror-mode deletion handling, shared by ``jp push`` and ``jp pull``.
+
+Mirror mode is OFF by default. When ON, after the additive sync, files that
+exist on one side but not the other become *deletion candidates*. This module
+NEVER deletes without consent:
+
+  * In an interactive terminal it shows a keep/delete selector (every file
+    defaults to KEEP) and only deletes what the user explicitly marks.
+  * With ``--yes`` it deletes every candidate (for scripts that opt in).
+  * In a non-interactive shell WITHOUT ``--yes`` it deletes nothing and says so.
+
+Every remote deletion is re-validated against the workspace prefix immediately
+before the call, so a mirror delete can never escape the user's own subtree.
+"""
+
+from __future__ import annotations
+
+from .. import paths, tui, ui
+from ..sync import Outcome
+from ._context import RepoContext
+
+
+def handle(
+    side: str,  # "remote" (push) or "local" (pull)
+    ctx: RepoContext,
+    api: object,
+    outcome: Outcome,
+    *,
+    yes: bool,
+    dry_run: bool,
+) -> None:
+    candidates = list(outcome.deletable)
+    if not candidates:
+        return
+
+    if dry_run:
+        ui.warn(
+            f"mirror mode: {len(candidates)} file(s) exist on {side} but not on the "
+            f"other side and could be deleted (run without --dry-run to choose):"
+        )
+        for rel in candidates:
+            ui.detail(f"    {rel}")
+        return
+
+    # Decide what to delete.
+    if yes:
+        selected = candidates
+    elif tui.interactive():
+        selected = tui.confirm_deletions(candidates, side)
+    else:
+        ui.warn(
+            f"mirror mode: {len(candidates)} file(s) exist on {side} but not on the "
+            "other side. Refusing to delete without a terminal; re-run interactively "
+            "or pass --yes to delete them all."
+        )
+        for rel in candidates:
+            ui.detail(f"    {rel}")
+        return
+
+    if not selected:
+        ui.info("mirror: kept everything (nothing deleted)")
+        return
+
+    if side == "remote":
+        _delete_remote(ctx, api, selected, outcome)
+    else:
+        _delete_local(ctx, selected, outcome)
+
+
+def _delete_remote(ctx: RepoContext, api: object, selected: list[str], outcome: Outcome) -> None:
+    prefix = paths.validate_prefix(ctx.cfg.prefix)
+    for rel in selected:
+        try:
+            remote_path = paths.remote_path_for(prefix, rel)
+            # SAFETY: re-assert containment immediately before the destructive call.
+            paths.assert_within_prefix(remote_path, prefix)
+            api.delete(remote_path)  # type: ignore[attr-defined]
+            ctx.index.remove(rel)
+            ctx.index.save()
+            outcome.deleted.append(rel)
+            ui.info(f"  deleted remote: {rel}")
+        except Exception as exc:  # keep going; report per-file
+            outcome.failures.append((rel, f"delete failed: {exc}"))
+
+
+def _delete_local(ctx: RepoContext, selected: list[str], outcome: Outcome) -> None:
+    for rel in selected:
+        try:
+            dest = paths.safe_local_dest(ctx.root, rel)
+            if dest.is_symlink():
+                outcome.failures.append((rel, "refusing to delete through a symlink"))
+                continue
+            if dest.is_file():
+                dest.unlink()
+            ctx.index.remove(rel)
+            ctx.index.save()
+            outcome.deleted.append(rel)
+            ui.info(f"  deleted local: {rel}")
+        except Exception as exc:
+            outcome.failures.append((rel, f"delete failed: {exc}"))

jp/commands/_report.py

@@ -0,0 +1,47 @@
+"""Shared summary printing for sync outcomes (push/pull/clone)."""
+
+from __future__ import annotations
+
+from .. import ui
+from ..sync import Outcome
+
+
+def report_outcome(verb: str, outcome: Outcome, *, dry_run: bool) -> None:
+    """Print a human summary of a sync run.
+
+    Conflicts and per-file failures are surfaced clearly. Skipped dotfiles are
+    reported but never treated as an error (see docs/architecture.md).
+    """
+    prefix = "[dry-run] would " if dry_run else ""
+
+    for rel in outcome.transferred:
+        ui.out(f"  {prefix}{verb}: {rel}")
+
+    if outcome.skipped_hidden:
+        ui.warn(
+            f"skipped {len(outcome.skipped_hidden)} hidden/dotfile(s) "
+            "(server rejects hidden uploads):"
+        )
+        ui.bullets(outcome.skipped_hidden, indent="    - ")
+
+    if outcome.conflicts:
+        ui.warn(
+            f"{len(outcome.conflicts)} conflict(s) NOT touched "
+            "(both sides changed; resolve manually):"
+        )
+        ui.bullets(outcome.conflicts, indent="    ! ")
+
+    if outcome.failures:
+        ui.error(f"{len(outcome.failures)} file(s) failed:")
+        for rel, reason in outcome.failures:
+            ui.error(f"    x {rel}: {reason}")
+
+    n = len(outcome.transferred)
+    if dry_run:
+        ui.info(f"{prefix}{verb} {n} file(s); {len(outcome.up_to_date)} already up to date")
+    else:
+        ui.success(
+            f"{verb}: {n} transferred, {len(outcome.up_to_date)} up to date, "
+            f"{len(outcome.skipped_hidden)} skipped, {len(outcome.conflicts)} conflict(s), "
+            f"{len(outcome.failures)} failed"
+        )

jp/commands/clone.py

@@ -0,0 +1,97 @@
+"""``jp clone`` -- create a local workspace from a Jupyter URL and pull it.
+
+Usage mirrors git::
+
+    jp clone https://host/user/<name>/lab/tree/<folder> [dir]
+
+The URL is parsed into a Contents-API base URL and a remote prefix; you can
+also pass ``--base-url``/``--prefix`` explicitly instead of a URL.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .. import config as config_mod
+from .. import sync, ui
+from ..config import Config
+from ..errors import EXIT_OK, EXIT_PARTIAL, UsageError
+from ..ignore import IgnoreSet
+from ..index import Index
+from ..paths import DOT_DIR, validate_prefix
+from ..urls import parse_clone_url
+from . import _context
+from ._report import report_outcome
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser(
+        "clone",
+        help="clone a remote Jupyter folder into a new local directory",
+    )
+    p.add_argument(
+        "url",
+        nargs="?",
+        default="",
+        help="Jupyter folder URL, e.g. https://host/user/<name>/lab/tree/<folder>",
+    )
+    p.add_argument("dir", nargs="?", default="", help="target directory (default: prefix basename)")
+    p.add_argument("--base-url", default="", help="Contents API base URL (instead of a URL)")
+    p.add_argument("--prefix", default="", help="remote prefix (instead of a URL)")
+    p.add_argument("--token-path", default="", help="path to the token file")
+    p.add_argument(
+        "--credential", default="", help="name of a saved credential to use (see 'jp login')"
+    )
+    p.add_argument(
+        "--dry-run", action="store_true", help="show what would be downloaded; write nothing"
+    )
+    p.set_defaults(func=run)
+
+
+def _resolve_source(args: argparse.Namespace) -> tuple[str, str]:
+    """Return (base_url, prefix) from either a URL or explicit flags."""
+    if args.url:
+        base_url, prefix = parse_clone_url(args.url)
+    else:
+        base_url, prefix = str(args.base_url).strip(), str(args.prefix).strip()
+    if not base_url:
+        raise UsageError("provide a Jupyter URL, or both --base-url and --prefix")
+    if not base_url.startswith(("http://", "https://")):
+        raise UsageError(f"base URL must be http(s): {base_url!r}")
+    # validate_prefix refuses an empty/root/shared prefix with a clear message.
+    prefix = validate_prefix(prefix)
+    return base_url.rstrip("/"), prefix
+
+
+def run(args: argparse.Namespace) -> int:
+    base_url, prefix = _resolve_source(args)
+
+    target = args.dir or prefix.rstrip("/").split("/")[-1]
+    root = Path(target).resolve()
+    if (root / DOT_DIR).exists():
+        raise UsageError(f"{root} is already a jp workspace")
+    root.mkdir(parents=True, exist_ok=True)
+
+    # Pick which saved credential this workspace will use (no repo exists yet,
+    # so only global credentials are in play here).
+    credential = _context.choose_credential(args, root=None)
+    cfg = Config(
+        base_url=base_url,
+        prefix=prefix,
+        token_path=str(args.token_path or ""),
+        credential=credential,
+    )
+    cfg._config_dir = root / DOT_DIR
+    if not args.dry_run:
+        config_mod.save(root, cfg)
+        Index(root).save()
+
+    index = Index.load(root) if not args.dry_run else Index(root)
+    ignore = IgnoreSet.from_root(root)
+    api = _context.build_api(cfg)
+
+    ui.heading(f"cloning {cfg.prefix} -> {root}")
+    outcome = sync.pull(root, cfg, api, index, ignore, dry_run=args.dry_run)
+    report_outcome("clone", outcome, dry_run=args.dry_run)
+    return EXIT_PARTIAL if outcome.had_failures else EXIT_OK

jp/commands/config_cmd.py

@@ -0,0 +1,132 @@
+"""``jp config`` -- view and edit workspace configuration.
+
+With no action, opens an interactive settings screen (arrows to move, Space to
+change, ``i`` for info, ``/`` to search, Enter to save, Esc to cancel) -- much
+like Claude Code's settings. In a non-interactive shell it falls back to
+printing the current settings.
+
+The scriptable forms still work for automation:
+
+    jp config list
+    jp config get <key>
+    jp config set <key> <value>
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from .. import config as config_mod
+from .. import credentials, tui, ui
+from ..errors import EXIT_OK, UsageError
+from ..settings_schema import BY_KEY, SPECS
+from ._context import load_repo
+
+# Connection fields shown as read-only context above the editable settings.
+_CONNECTION_KEYS = ("base_url", "prefix", "credential", "token_path")
+
+
+def _token_source(cfg: config_mod.Config, root: object) -> str:
+    """Human-readable description of where this workspace's token comes from.
+
+    Prefers the named credential (the modern path); falls back to a direct
+    ``token_path`` in the config; otherwise reports that none is configured.
+    Never prints the token value itself -- only its name/location.
+    """
+    if cfg.credential:
+        from pathlib import Path
+
+        cred = credentials.resolve(cfg.credential, Path(str(root)))
+        if cred is not None:
+            return f"{cfg.credential} ({cred.scope}: {cred.token_path})"
+        return f"{cfg.credential} (not found -- run 'jp login --name {cfg.credential}')"
+    if cfg.token_path:
+        return cfg.token_path
+    return "(unset -- run 'jp login')"
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("config", help="view/edit settings (interactive by default)")
+    p.add_argument("action", nargs="?", choices=["get", "set", "list"], help="scriptable action")
+    p.add_argument("key", nargs="?", help="config key")
+    p.add_argument("value", nargs="?", help="value to set")
+    p.set_defaults(func=run)
+
+
+def _print_list(cfg: config_mod.Config) -> None:
+    for key in (*_CONNECTION_KEYS, *(s.key for s in SPECS)):
+        ui.info(f"{key} = {getattr(cfg, key, '')}")
+
+
+def run(args: argparse.Namespace) -> int:
+    ctx = load_repo()
+    cfg = ctx.cfg
+
+    # --- scriptable paths ---------------------------------------------------
+    if args.action == "list":
+        _print_list(cfg)
+        return EXIT_OK
+    if args.action == "get":
+        if not args.key:
+            raise UsageError("config get requires a key")
+        ui.info(f"{getattr(cfg, args.key, '')}")
+        return EXIT_OK
+    if args.action == "set":
+        if not args.key or args.value is None:
+            raise UsageError("config set requires a key and a value")
+        if not hasattr(cfg, args.key):
+            raise UsageError(f"unknown config key: {args.key}")
+        spec = BY_KEY.get(args.key)
+        value: object = args.value
+        if spec is not None:
+            try:
+                value = spec.coerce(args.value)
+            except (TypeError, ValueError) as exc:
+                raise UsageError(f"invalid value for {args.key}: {args.value!r} ({exc})") from exc
+            if spec.options and value not in spec.options:
+                allowed = ", ".join(spec.fmt(o) for o in spec.options)
+                raise UsageError(f"{args.key} must be one of: {allowed}")
+        setattr(cfg, args.key, value)
+        config_mod.save(ctx.root, cfg)
+        ui.success(f"set {args.key} = {spec.fmt(value) if spec else value}")
+        return EXIT_OK
+
+    # --- interactive (no action) -------------------------------------------
+    if not tui.interactive():
+        # Non-interactive shell: just show the settings (never block on a prompt).
+        _print_list(cfg)
+        ui.info("\n(run in a terminal for the interactive editor, or use 'jp config set')")
+        return EXIT_OK
+
+    # Connection context (read-only here; change via 'jp config set').
+    ui.heading(f"jp workspace: {ctx.root}")
+    ui.detail(f"  base_url = {cfg.base_url or '(unset)'}")
+    ui.detail(f"  prefix   = {cfg.prefix or '(unset)'}")
+    ui.detail(f"  token    = {_token_source(cfg, ctx.root)}")
+    ui.info("")
+
+    rows = [
+        tui.Setting(
+            key=s.key,
+            label=s.label,
+            value=getattr(cfg, s.key),
+            options=s.options,
+            help_text=s.help_text,
+            fmt=s.fmt,
+        )
+        for s in SPECS
+    ]
+    result = tui.settings_menu(rows, title="Settings")
+    if result is None:
+        ui.info("no changes saved")
+        return EXIT_OK
+
+    changed = [r for r in result if r.changed]
+    if not changed:
+        ui.info("no changes")
+        return EXIT_OK
+    for r in changed:
+        setattr(cfg, r.key, r.value)
+    config_mod.save(ctx.root, cfg)
+    ui.success(f"saved {len(changed)} change(s): " + ", ".join(r.key for r in changed))
+    return EXIT_OK

jp/commands/diff.py

@@ -0,0 +1,93 @@
+"""``jp diff`` -- show a unified text diff of changed files (read-only).
+
+For text files, prints a unified diff between the remote (or base) and local
+content. Binary files are reported as "binary differs". Read-only: never writes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+
+from .. import ui
+from ..errors import EXIT_OK
+from ..sync import Change
+from . import _context
+from ._context import load_repo
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("diff", help="show unified diffs of changed files (read-only)")
+    p.add_argument("path", nargs="?", default="", help="limit to a single relative path")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    ctx = load_repo()
+    api = _context.build_api(ctx.cfg)
+    from .. import sync
+
+    states = sync.diff(ctx.root, ctx.cfg, api, ctx.index, ctx.ignore)
+    only = args.path.replace("\\", "/").strip("/") if args.path else ""
+
+    shown = 0
+    for st in states:
+        if only and st.rel != only:
+            continue
+        if st.change in (Change.UNCHANGED,):
+            continue
+        if st.change in (Change.REMOTE_NEW,):
+            ui.heading(f"remote-only: {st.rel}")
+            continue
+        if st.change == Change.LOCAL_NEW:
+            ui.heading(f"local-only: {st.rel}")
+            continue
+
+        local_text = _read_local_text(ctx.root, st.rel)
+        remote_text = _read_remote_text(api, st)
+        if local_text is None or remote_text is None:
+            ui.heading(f"{st.rel}: binary differs")
+            shown += 1
+            continue
+
+        ui.heading(f"diff {st.rel}")
+        diff_lines = difflib.unified_diff(
+            remote_text.splitlines(keepends=True),
+            local_text.splitlines(keepends=True),
+            fromfile=f"remote/{st.rel}",
+            tofile=f"local/{st.rel}",
+        )
+        for line in diff_lines:
+            ui.out(line.rstrip("\n"))
+        shown += 1
+
+    if shown == 0:
+        ui.info("no textual differences")
+    return EXIT_OK
+
+
+def _read_local_text(root, rel: str) -> str | None:
+    try:
+        data = (root / rel).read_bytes()
+    except OSError:
+        return None
+    return _decode(data)
+
+
+def _read_remote_text(api, st) -> str | None:
+    if st.remote_entry is None:
+        return ""
+    try:
+        data = api.get_file_bytes(st.remote_entry.path)
+    except Exception:
+        return None
+    return _decode(data)
+
+
+def _decode(data: bytes) -> str | None:
+    if b"\x00" in data:
+        return None
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None