remoto.el

;;; remoto.el --- Browse GitHub repos without cloning -*- lexical-binding: t; -*-
;;
;; Copyright (C) 2026 Ag Ibragimov
;;
;; Author: Ag Ibragimov <agzam.ibragimov@gmail.com>
;; Assisted-by: ECA:claude-opus-5
;; Maintainer: Ag Ibragimov <agzam.ibragimov@gmail.com>
;; Created: April 24, 2026
;; Version: 2.0.0
;; Keywords: tools vc
;; Homepage: https://github.com/agzam/remoto.el
;; Package-Requires: ((emacs "29.1") (ghub "4.0.0"))
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
;; This file is not part of GNU Emacs.

;;; Commentary:

;; remoto.el lets you browse any GitHub repository in Emacs as if it were
;; cloned locally - without cloning it.  It registers a virtual filesystem
;; via `file-name-handler-alist' that translates Emacs file operations into
;; GitHub API calls via the `ghub' library.
;;
;; Loading this file defines things and changes nothing.  `global-remoto-mode'
;; is the switch: it installs the file-name handler, the `find-file' and
;; `dired' URL rewriting, the completion metadata, and the auto-enabling of
;; `remoto-mode' in remoto buffers, and removes all of them when turned off.
;;
;; Usage:
;;   C-x C-f /github:torvalds/linux RET
;;   M-x remoto-browse RET https://github.com/torvalds/linux RET
;;
;; Both turn the mode on when it is off: `remoto-browse' itself, and the
;; path through `remoto-autoload-file-name-handler', which the package
;; autoloads register for `/github:' and `/gh:' paths the way TRAMP
;; autoloads on a remote path.  `(global-remoto-mode 1)' in the init file
;; turns it on ahead of time.  `remoto-browse' supports pasting any GitHub
;; URL, git remote URL, or owner/repo shorthand.

;;; Code:

(require 'cl-lib)
(require 'files-x)
(require 'format-spec)
(require 'ghub)

;;;; Path parsing

(defconst remoto--path-regexp
  (rx bos "/github:"
      (group (+ (not (in "/@"))))       ; owner
      "/"
      (group (+ (not (in "/@:"))))      ; repo
      (? "@" (group (+ (not (in ":/"))))) ; ref (optional)
      ":"
      (group (* anything))              ; path
      eos)
  "Regexp matching canonical remoto paths.
Groups: 1=owner, 2=repo, 3=ref (maybe nil), 4=path.")

(defconst remoto--handler-regexp "\\`/\\(?:github\\|gh\\):"
  "Regexp matching remoto file paths.
Matches the canonical /github: prefix and its /gh: shorthand alias.
Spelled out rather than built with `rx' because the autoload cookie on
`remoto-autoload-file-name-handler' repeats it as a literal.")

(defconst remoto--repo-delimiters
  '((?/ . files-default)
    (?@ . branches)
    (?# . issues))
  "Alist mapping delimiter characters after OWNER/REPO to completion levels.
`/' means browse files on default branch, `@' means pick a branch/tag,
`#' means browse issues/PRs.")

(cl-defstruct (remoto-path (:constructor remoto-path-create)
                           (:copier nil))
  "Parsed components of a remoto path."
  owner repo ref path)

(defun remoto--parse-path (filename)
  "Parse canonical remoto FILENAME into a `remoto-path' struct.
Returns nil if FILENAME does not match the canonical format."
  (when (string-match remoto--path-regexp filename)
    (remoto-path-create
     :owner (match-string 1 filename)
     :repo  (match-string 2 filename)
     :ref   (match-string 3 filename)
     :path  (let ((p (match-string 4 filename)))
              (if (or (null p) (string-empty-p p)) "/" p)))))

(defun remoto--canonical-path (parsed)
  "Build a canonical remoto path string from PARSED `remoto-path'."
  (format "/github:%s/%s%s:%s"
          (remoto-path-owner parsed)
          (remoto-path-repo parsed)
          (if (remoto-path-ref parsed)
              (concat "@" (remoto-path-ref parsed))
            "")
          (or (remoto-path-path parsed) "/")))

(defun remoto--repo-key (parsed)
  "Return cache key string for PARSED `remoto-path'.
Format: owner/repo@ref."
  (format "%s/%s@%s"
          (remoto-path-owner parsed)
          (remoto-path-repo parsed)
          (or (remoto-path-ref parsed) "HEAD")))

;;;; GitHub API

(declare-function dired-get-filename "dired" (&optional localp no-error-if-not-filep))

(defgroup remoto nil
  "Browse GitHub repos without cloning."
  :group 'tools
  :prefix "remoto-")

(defcustom remoto-github-auth nil
  "Auth token source for GitHub API requests via ghub.
nil means use the default ghub token (USERNAME^ghub in auth-source).
A symbol like `forge' uses that package's token instead.
A string is used as a literal token.
See ghub documentation for auth-source setup."
  :type '(choice (const :tag "Default ghub token" nil)
                 (symbol :tag "Package token name")
                 (string :tag "Literal token"))
  :group 'remoto)

(defcustom remoto-auth-timeout 10
  "Seconds to wait for auth-source token lookup before giving up.
When ghub's token lookup (which may trigger GPG decryption of
authinfo) exceeds this limit, remoto falls back to unauthenticated
access for that request.  Use `remoto-reset-auth' to retry after
adding a token."
  :type 'number
  :group 'remoto)

(defcustom remoto-search-cache-ttl 300
  "Seconds before cached API results expire.
Set to 0 to disable caching.  Applies to the search, branch, and
directory-listing caches.  Defined early so functions above the
\"Repository search\" section can reference it at byte-compile time."
  :type 'integer
  :group 'remoto)

(defvar remoto--auth-failed nil
  "Non-nil when authenticated GitHub access has permanently failed.
Set on actual auth errors (missing token, 401), NOT on timeouts.
Causes `remoto--api' to skip token lookup and use unauthenticated
requests.  Reset with `remoto-reset-auth'.")

(defvar remoto--effective-auth nil
  "Resolved auth value that actually works, or nil if not yet probed.
Set by `remoto--warm-auth' after trying `remoto-github-auth' and
falling back to `forge' if available.  Cleared by `remoto-reset-auth'.")

(defvar remoto--authenticated-user nil
  "Cached GitHub login of the authenticated user, or nil if unknown.
Set by `remoto--get-authenticated-user' on first successful lookup.
Cleared by `remoto-reset-auth'.")

(defun remoto--json-reader (_status)
  "Parse JSON response with list-type arrays for remoto compatibility.
Finds the JSON body by scanning for the first `{' or `[',
handling both header-present and header-stripped response buffers
across different ghub and url.el versions."
  (goto-char (point-min))
  (when (re-search-forward "[{[]" nil t)
    (backward-char 1)
    (let ((body (buffer-substring-no-properties (point) (point-max))))
      (unless (string-empty-p body)
        (condition-case nil
            (json-parse-string
             (decode-coding-string body 'utf-8)
             :object-type 'alist
             :array-type 'list
             :null-object nil
             :false-object nil)
          (json-error nil))))))

;;;; Fetch indicator

(defcustom remoto-show-fetch-indicator t
  "When non-nil, show a \"fetching\" indicator during GitHub requests.
While completing a remoto path (e.g. with \\[find-file]) or at the
`remoto-browse' prompt, it is drawn as minibuffer text, so it works with
any completion UI (vertico, icomplete, default, ...).  A fetch that
blocks with no such prompt up, as when the chosen path opens, shows it
in the echo area instead."
  :type 'boolean
  :group 'remoto)

(defvar remoto--inflight-count 0
  "Number of API requests the minibuffer overlay stands for.
Every async request of the completion counts, and so does a blocking
fetch that runs while a remoto prompt is up.")

(defvar remoto--status-overlay nil
  "Overlay holding the fetch indicator slot in the active minibuffer.")

(defconst remoto--fetch-indicator-text
  (propertize "⟳" 'face 'shadow)
  "Circle arrow shown by the fetch indicator in both contexts.
Reused by the minibuffer slot and the echo-area message so the two read
identically.  One character, because a word in the minibuffer scrolls
the line as it comes and goes; a text character rather than an emoji,
because a color glyph is taller than the line it sits in and ignores
the `shadow' face.")

(defconst remoto--fetch-indicator-blank
  (make-string (string-width remoto--fetch-indicator-text) ?\s)
  "What the indicator's slot holds between requests.")

(defun remoto--clear-status ()
  "Remove the fetch indicator slot, if any."
  (when (overlayp remoto--status-overlay)
    (delete-overlay remoto--status-overlay))
  (setq remoto--status-overlay nil))

(defun remoto--render-status (buffer busy)
  "Draw the fetch indicator slot in BUFFER, filled when BUSY.
The slot sits between the prompt and the input, never after it.  Emacs
draws the cursor after any string that follows point, and a completion
UI that opens its candidate list there claims the `cursor' property for
its own string - Vertico does - so an indicator after the input drags
the cursor sideways on every request.  The blank keeps the slot's width
between requests, so the input does not shift either."
  (with-current-buffer buffer
    (let ((pos (minibuffer-prompt-end)))
      (unless (and (overlayp remoto--status-overlay)
                   (eq (overlay-buffer remoto--status-overlay) buffer))
        (remoto--clear-status)
        (setq remoto--status-overlay (make-overlay pos pos)))
      (move-overlay remoto--status-overlay pos pos)
      (overlay-put remoto--status-overlay 'priority 1000)
      (overlay-put remoto--status-overlay 'before-string
                   (concat (if busy
                               remoto--fetch-indicator-text
                             remoto--fetch-indicator-blank)
                           " ")))))

(defun remoto--hide-status ()
  "Blank the fetch indicator, keeping its slot while the prompt is up.
A slot that came and went would shift the input left and right as
requests come and go, which is what drawing it at all has to avoid."
  (let ((buf (and (overlayp remoto--status-overlay)
                  (overlay-buffer remoto--status-overlay))))
    (if (and (buffer-live-p buf) (minibufferp buf))
        (remoto--render-status buf nil)
      (remoto--clear-status))))

(defun remoto--completion-minibuffer ()
  "Return the active minibuffer when it is completing for remoto, else nil.
That is a file name inside a remoto path, with either prefix and possibly
behind a shadowed directory (\"~/x//gh:o/\") the way `read-file-name'
reads it, or the `remoto-browse' prompt, whose collection is
`remoto--repo-completion-table'.  A prompt opened inside a remoto
directory counts even with nothing typed: `read-file-name' puts its DIR
argument in the minibuffer's `default-directory', and completion keeps
fetching from there after \\[move-beginning-of-line] \\[kill-line]."
  (when-let* ((win (active-minibuffer-window))
              (buf (window-buffer win)))
    (with-current-buffer buf
      (and (or (eq minibuffer-completion-table #'remoto--repo-completion-table)
               (string-match-p remoto--handler-regexp
                               (condition-case nil
                                   (substitute-in-file-name
                                    (minibuffer-contents-no-properties))
                                 (error "")))
               (string-match-p remoto--handler-regexp
                               (or default-directory "")))
           buf))))

(defun remoto--show-status ()
  "Show the in-flight fetch indicator in the active remoto minibuffer.
No-op unless `remoto-show-fetch-indicator' is non-nil and the active
minibuffer is one that `remoto--completion-minibuffer' recognizes.
Drawn as minibuffer text so it works with any completion UI."
  (when remoto-show-fetch-indicator
    (when-let* ((buf (remoto--completion-minibuffer)))
      (remoto--render-status buf t))))

(defun remoto--inflight-inc ()
  "Register a new in-flight async request and show the indicator."
  (setq remoto--inflight-count (1+ remoto--inflight-count))
  (remoto--show-status))

(defun remoto--inflight-dec ()
  "Mark one in-flight async request as finished.
Blank the indicator once no requests remain."
  (setq remoto--inflight-count (max 0 (1- remoto--inflight-count)))
  (when (zerop remoto--inflight-count)
    (remoto--hide-status)))

(defun remoto--minibuffer-exit-cleanup ()
  "Reset in-flight indicator state when a minibuffer exits."
  (remoto--clear-status)
  (setq remoto--inflight-count 0))

(defvar remoto--sync-fetch-depth 0
  "Nesting depth of `remoto--with-fetch-indicator' bodies.
Only the outermost body draws and clears the indicator, so a command
wrapped as a whole and the API calls inside it draw it once.")

(defvar remoto--sync-fetch-overlay nil
  "Non-nil while the outermost blocking fetch is drawn as the minibuffer overlay.
Decides which of the two indicators the end of that fetch clears.")

(defun remoto--sync-fetch-begin ()
  "Draw the indicator for the blocking fetch about to begin.
In a remoto completion minibuffer that is the overlay of the async
fetches, painted at once because nothing redisplays while the fetch
blocks; anywhere else it is an echo-area message, which the echo area
shows at once."
  (setq remoto--sync-fetch-depth (1+ remoto--sync-fetch-depth))
  (when (= remoto--sync-fetch-depth 1)
    (setq remoto--sync-fetch-overlay (and (remoto--completion-minibuffer) t))
    (if remoto--sync-fetch-overlay
        (progn (remoto--inflight-inc)
               (redisplay))
      (let ((message-log-max nil))
        (message "Remoto %s" remoto--fetch-indicator-text)))))

(defun remoto--sync-fetch-end ()
  "Clear the indicator once the outermost blocking fetch is over.
A message that something else put up meanwhile is left alone."
  (setq remoto--sync-fetch-depth (max 0 (1- remoto--sync-fetch-depth)))
  (when (zerop remoto--sync-fetch-depth)
    (if remoto--sync-fetch-overlay
        (remoto--inflight-dec)
      (when (equal (current-message)
                   (format "Remoto %s" remoto--fetch-indicator-text))
        (let ((message-log-max nil))
          (message nil))))
    (setq remoto--sync-fetch-overlay nil)))

(defmacro remoto--with-fetch-indicator (&rest body)
  "Run BODY, a blocking GitHub round-trip, with the fetch indicator up.
Every synchronous API call goes through this, so `remoto-browse' and a
path at `find-file' or `dired' show the same thing: the minibuffer
overlay while completing, the echo area once the prompt is gone.
Honors `remoto-show-fetch-indicator' and does nothing in batch, where
there is no display.  Returns BODY's value."
  (declare (indent 0) (debug t))
  `(if (or noninteractive (not remoto-show-fetch-indicator))
       (progn ,@body)
     (remoto--sync-fetch-begin)
     (unwind-protect
         (progn ,@body)
       (remoto--sync-fetch-end))))

(cl-defstruct (remoto--request (:constructor remoto--request-create))
  "A GitHub request started under `while-no-input'."
  (status 'pending)
  buffer
  value)

(defvar remoto--pending-requests (make-hash-table :test 'equal)
  "Requests started under `while-no-input', keyed by (RESOURCE . AUTH).
Such a request outlives the completion call that started it: the reply
lands in its `remoto--request', and the next call for the same key
waits on that request or reads the landed reply instead of asking
GitHub again.  A failed request leaves the table, so the next call
retries.")

(defun remoto--request-condition (err resource)
  "Turn ERR, as ghub hands it to an errorback, into the condition ghub signals.
RESOURCE names the request in the condition data."
  (pcase err
    (`(error http ,code . ,rest)
     (list 'ghub-http-error code (nth 2 (assq code url-http-codes))
           (concat "https://api.github.com" resource) (car rest)))
    (`(error . ,data) (cons 'ghub-error data))
    (_ err)))

(defun remoto--request-start (key resource auth)
  "Start a callback request for RESOURCE with AUTH and register it under KEY."
  (let ((req (remoto--request-create)))
    (setf (remoto--request-buffer req)
          (ghub-get resource nil
                    :auth auth
                    :reader #'remoto--json-reader
                    :host "api.github.com"
                    :callback (lambda (value &rest _)
                                (setf (remoto--request-value req) value
                                      (remoto--request-status req) 'done))
                    :errorback (lambda (err &rest _)
                                 (remhash key remoto--pending-requests)
                                 (setf (remoto--request-value req)
                                       (remoto--request-condition err resource)
                                       (remoto--request-status req) 'error))))
    (puthash key req remoto--pending-requests)
    req))

(defun remoto--auth-key (auth)
  "Return a stable identity for AUTH that is not the credential itself.
`remoto--pending-requests' only has to tell two callers apart, and its
keys are readable in a backtrace or a variable dump, so a token string
goes in hashed.  A symbol such as `none' is no secret and stays as is."
  (if (stringp auth) (secure-hash 'sha256 auth) auth))

(defun remoto--ghub-get-interruptible (resource auth)
  "GET RESOURCE with AUTH through a callback, waiting in a way input can end.
`url-retrieve-synchronously' leaves its buffer behind when `while-no-input'
throws past it, and the reply nobody reads keeps the buffer alive; ghub
kills the buffer of a callback request itself once the reply is handled.
Return the value or signal the condition the synchronous call would."
  (let* ((key (cons resource (remoto--auth-key auth)))
         (req (or (gethash key remoto--pending-requests)
                  (remoto--request-start key resource auth))))
    (while (and (eq (remoto--request-status req) 'pending)
                (buffer-live-p (remoto--request-buffer req)))
      (accept-process-output nil 0.1))
    (remhash key remoto--pending-requests)
    (pcase (remoto--request-status req)
      ('done (remoto--request-value req))
      ('error (let ((err (remoto--request-value req)))
                (signal (car err) (cdr err))))
      (_ (error "Remoto: no reply for %s" resource)))))

(defun remoto--ghub-get (resource auth endpoint)
  "Call `ghub-get' on RESOURCE with AUTH, translating errors.
ENDPOINT is used in error messages for context.  Always passes
`:host \"api.github.com\"' explicitly - ghub's default host
resolution can resolve to github.com (HTML) instead of the
JSON API endpoint."
  (condition-case err
      (remoto--with-fetch-indicator
        (let ((inhibit-message (not ghub-debug)))
          ;; `while-no-input' binds `throw-on-input'; only then can input
          ;; abandon the call, and only then is the callback path needed.
          (if throw-on-input
              (remoto--ghub-get-interruptible resource auth)
            (ghub-get resource nil
                      :auth auth
                      :reader #'remoto--json-reader
                      :host "api.github.com"))))
    ;; ghub signals every HTTP failure as (ghub-http-error CODE MESSAGE URL
    ;; PAYLOAD); there are no per-status error symbols to match on.
    (ghub-http-error
     (pcase (cadr err)
       (404 (user-error "Remoto: not found: %s" endpoint))
       (403 (user-error "Remoto: access denied (rate limit or permissions): %s"
                        endpoint))
       (401 (user-error "Remoto: authentication failed; \
configure ghub token in auth-source"))
       (_ (user-error "Remoto: API error: %s" (error-message-string err)))))
    (json-error
     (user-error "Remoto: could not parse API response for %s" endpoint))))

(defun remoto--api (endpoint)
  "Call GitHub REST API ENDPOINT via ghub, return parsed JSON.
ENDPOINT should not have a leading slash - one is prepended
automatically.  Auth resolution order: `remoto--effective-auth',
`remoto-github-auth', ghub's built-in auth-source lookup,
`remoto--find-github-token' (last resort).  When every avenue
fails, signals `user-error'.  Public repos work without any
setup via unauthenticated fallback."
  (let* ((resource (concat "/" endpoint))
         (auth (cond (remoto--auth-failed 'none)
                     (remoto--effective-auth remoto--effective-auth)
                     ((stringp remoto-github-auth) remoto-github-auth)
                     ;; Try our own auth-source search before ghub's
                     ;; resolution, which uses different host/user
                     ;; patterns and often fails on fresh sessions.
                     (t (or (when-let* ((token (remoto--find-github-token)))
                              (setq remoto--effective-auth token)
                              token)
                            ;; A lookup that fails inside sets the flag; this
                            ;; call must go unauthenticated too, or ghub's own
                            ;; lookup hits the same broken backend and errors.
                            (and remoto--auth-failed 'none))))))
    (if (eq auth 'none)
        (remoto--ghub-get resource 'none endpoint)
      (condition-case err
          ;; Only apply the auth timeout on the first call (before we
          ;; know whether auth works).  Once the authenticated user is
          ;; cached, auth-source won't block, so skip the timeout to
          ;; avoid aborting slow HTTP responses.
          (if remoto--authenticated-user
              (remoto--ghub-get resource auth endpoint)
            (let ((result (with-timeout (remoto-auth-timeout 'remoto--timed-out)
                            (remoto--ghub-get resource auth endpoint))))
              (when (eq result 'remoto--timed-out)
                (message "Remoto: auth lookup timed out; retrying next call (see `remoto-auth-timeout')")
                (setq result (remoto--ghub-get resource 'none endpoint)))
              result))
        ;; Re-raise API errors (404, 403, etc.) from remoto--ghub-get;
        ;; these are not auth failures.
        (user-error
         (if (string-prefix-p "Remoto:" (cadr err))
             (signal (car err) (cdr err))
           ;; ghub auth config error (e.g. "Cannot determine
           ;; username").  Every avenue exhausted - fail loudly.
           (setq remoto--auth-failed t)
           (user-error "Remoto: authentication failed for %s; \
configure a GitHub token in auth-source, then M-x remoto-reset-auth"
                       endpoint)))
        (error
         ;; ghub could not resolve auth at all.  Fail loudly so the
         ;; user knows auth is the problem, not a missing repo.
         (setq remoto--auth-failed t)
         (user-error "Remoto: authentication failed for %s (%s); \
configure a GitHub token in auth-source, then M-x remoto-reset-auth"
                     endpoint (error-message-string err)))))))

(defun remoto--paginated-api (endpoint per-page &optional max-pages)
  "Fetch all pages of paginated GitHub API ENDPOINT via `remoto--api'.
Request PER-PAGE items per page, following pages until a short page is
returned or MAX-PAGES (default 10) is reached.  The cap bounds latency
and request count on very large repositories."
  (let ((query-endpoint (concat endpoint (if (cl-search "?" endpoint) "&" "?"))))
    (cl-loop for page from 1 to (or max-pages 10)
             for page-data = (remoto--api
                              (format "%sper_page=%d&page=%d"
                                      query-endpoint per-page page))
             append page-data
             until (< (length page-data) per-page))))

(defun remoto-reset-auth ()
  "Clear the auth failure cache, retrying token lookup on next API call.
Use after adding a GitHub token to auth-source."
  (interactive)
  (setq remoto--auth-failed nil
        remoto--effective-auth nil
        remoto--authenticated-user nil)
  (message "Remoto: auth cache cleared; will retry token lookup on next request"))

(defun remoto--default-branch (owner repo)
  "Fetch the default branch for OWNER/REPO."
  (let ((data (remoto--api (format "repos/%s/%s" owner repo))))
    (alist-get 'default_branch data)))

(defconst remoto--dir-entry
  '((type . "tree") (size . 0) (sha . "") (mode . "040000"))
  "Alist for synthesized directory entries (root, intermediates, `.', `..').")

;;;; Tree cache

(defvar remoto--tree-cache (make-hash-table :test 'equal)
  "Cache: \"owner/repo@ref\" -> hash table of path -> entry plist.")

(defvar remoto--default-branch-cache (make-hash-table :test 'equal)
  "Cache: \"owner/repo\" -> default branch name.")

(defvar remoto--branches-cache (make-hash-table :test 'equal)
  "Cache: \"owner/repo\" -> (TIMESTAMP . BRANCH-NAMES).")

(defvar remoto--users-cache (make-hash-table :test 'equal)
  "Cache: query string -> (TIMESTAMP . USER-NAMES).
Entries expire after `remoto-search-cache-ttl' seconds.")


(defun remoto--resolve-ref (parsed)
  "Ensure PARSED `remoto-path' has a concrete ref, resolving if needed.
Returns a new `remoto-path' with ref filled in."
  (if (remoto-path-ref parsed)
      parsed
    (let* ((owner (remoto-path-owner parsed))
           (repo (remoto-path-repo parsed))
           (repo-id (format "%s/%s" owner repo))
           (branch (or (gethash repo-id remoto--default-branch-cache)
                       (let ((b (remoto--default-branch owner repo)))
                         (puthash repo-id b remoto--default-branch-cache)
                         b))))
      (remoto-path-create
       :owner owner :repo repo :ref branch
       :path (remoto-path-path parsed)))))

(defun remoto--fetch-tree (owner repo ref)
  "Fetch full tree for OWNER/REPO at REF from GitHub API.
Returns a hash table of path -> alist with keys type, size, sha, mode."
  (let* ((endpoint (format "repos/%s/%s/git/trees/%s?recursive=1" owner repo ref))
         (data (remoto--api endpoint))
         (entries (alist-get 'tree data))
         (truncated (alist-get 'truncated data))
         (table (make-hash-table :test 'equal :size (length entries))))
    (when (eq truncated t)
      (puthash "\0truncated" t table)
      (message "Remoto: tree truncated for %s/%s@%s, fetching dirs on demand"
               owner repo ref))
    ;; Root entry
    (puthash "" remoto--dir-entry table)
    (puthash "/" remoto--dir-entry table)
    ;; All entries from API
    (dolist (entry entries)
      (let ((path (alist-get 'path entry))
            (plist (list (cons 'type (alist-get 'type entry))
                         (cons 'size (or (alist-get 'size entry) 0))
                         (cons 'sha  (alist-get 'sha entry))
                         (cons 'mode (alist-get 'mode entry)))))
        (puthash path plist table)
        ;; Synthesize intermediate directories
        (let ((parts (split-string path "/" t)))
          (when (< 1 (length parts))
            (cl-loop for i from 1 below (length parts)
                     for dir = (mapconcat #'identity (seq-take parts i) "/")
                     unless (gethash dir table)
                     do (puthash dir remoto--dir-entry table))))))
    table))

(defun remoto--ensure-tree (parsed)
  "Ensure tree is cached for PARSED path, return the tree hash table."
  (let* ((resolved (remoto--resolve-ref parsed))
         (key (remoto--repo-key resolved)))
    (or (gethash key remoto--tree-cache)
        (let* ((tree (remoto--fetch-tree
                      (remoto-path-owner resolved)
                      (remoto-path-repo resolved)
                      (remoto-path-ref resolved))))
          (puthash key tree remoto--tree-cache)
          tree))))

(defun remoto--fetch-directory-contents (parsed dir-key tree)
  "Fetch DIR-KEY via Contents API for PARSED repo, merge into TREE.
On-demand fallback for repos whose recursive tree was truncated."
  (let* ((resolved (remoto--resolve-ref parsed))
         (endpoint (if (string-empty-p dir-key)
                       (format "repos/%s/%s/contents?ref=%s"
                               (remoto-path-owner resolved)
                               (remoto-path-repo resolved)
                               (remoto-path-ref resolved))
                     (format "repos/%s/%s/contents/%s?ref=%s"
                             (remoto-path-owner resolved)
                             (remoto-path-repo resolved)
                             (url-hexify-string dir-key)
                             (remoto-path-ref resolved))))
         (data (condition-case nil
                   (remoto--api endpoint)
                 (user-error nil))))
    (puthash (concat "\0fetched:" dir-key) t tree)
    ;; Contents API returns a list of alists for directories
    (when (and (consp data) (consp (caar data)))
      (dolist (entry data)
        (let* ((path (alist-get 'path entry))
               (api-type (alist-get 'type entry))
               (type (if (equal api-type "dir") "tree" "blob"))
               (plist (list (cons 'type type)
                            (cons 'size (or (alist-get 'size entry) 0))
                            (cons 'sha (or (alist-get 'sha entry) ""))
                            (cons 'mode (if (equal type "tree") "040000" "100644")))))
          ;; Keep existing entries from Trees API (they have richer mode info)
          (unless (gethash path tree)
            (puthash path plist tree)))))))

(defvar remoto--dir-contents-cache (make-hash-table :test 'equal)
  "Cache: \"owner/repo@ref:dir\" -> (TIMESTAMP . CHILDREN-LIST).
Stores lightweight directory listings from Contents API.")

(defun remoto--fetch-dir-children-light (owner repo ref dir-path)
  "Fetch direct children of DIR-PATH in OWNER/REPO@REF via Contents API.
Returns a list of (NAME . PLIST) pairs, capped at 20 entries.
Uses cache when available.  Much faster than recursive tree fetch."
  (let* ((key (format "%s/%s@%s:%s" owner repo ref (or dir-path "")))
         (entry (gethash key remoto--dir-contents-cache))
         (now (float-time)))
    (if (and entry
             (or (zerop remoto-search-cache-ttl)
                 (< (- now (car entry)) remoto-search-cache-ttl)))
        (cdr entry)
      (condition-case nil
          (let* ((endpoint (if (or (null dir-path) (string-empty-p dir-path))
                               (format "repos/%s/%s/contents?ref=%s"
                                       owner repo ref)
                             (format "repos/%s/%s/contents/%s?ref=%s"
                                     owner repo (url-hexify-string dir-path) ref)))
                 (data (remoto--api endpoint))
                 (children
                  (when (and (consp data) (consp (caar data)))
                    (let ((result nil))
                      (dolist (item (seq-take data 20))
                        (let* ((name (alist-get 'name item))
                               (api-type (alist-get 'type item))
                               (type (if (equal api-type "dir") "tree" "blob"))
                               (plist (list (cons 'type type)
                                            (cons 'size (or (alist-get 'size item) 0))
                                            (cons 'sha (or (alist-get 'sha item) ""))
                                            (cons 'mode (if (equal type "tree")
                                                            "040000" "100644")))))
                          (push (cons name plist) result)))
                      (nreverse result)))))
            (puthash key (cons now children) remoto--dir-contents-cache)
            children)
        (error nil)))))

(defun remoto--tree-lookup-key (path)
  "Normalize PATH for tree hash-table lookup.
Strips leading/trailing slashes and collapses runs of slashes."
  (let ((p (replace-regexp-in-string "/+" "/" path)))
    (when (string-prefix-p "/" p)
      (setq p (substring p 1)))
    (when (and (not (string-empty-p p))
               (string-suffix-p "/" p))
      (setq p (substring p 0 (1- (length p)))))
    p))

(defun remoto--tree-entry (parsed)
  "Look up the tree entry for PARSED path.  Return plist or nil.
For truncated trees, fetches the parent directory on demand."
  (let* ((tree (remoto--ensure-tree parsed))
         (key (remoto--tree-lookup-key (remoto-path-path parsed))))
    (or (gethash key tree)
        (when (and (gethash "\0truncated" tree)
                   (not (string-empty-p key)))
          (let ((parent (if (string-search "/" key)
                            (remoto--tree-lookup-key
                             (file-name-directory (directory-file-name key)))
                          "")))
            (unless (gethash (concat "\0fetched:" parent) tree)
              (remoto--fetch-directory-contents parsed parent tree))
            (gethash key tree))))))

(defun remoto--tree-children (parsed)
  "List direct children of directory at PARSED path.
Returns list of (NAME . PLIST) for each child.
For truncated trees, fetches the directory on demand."
  (let* ((tree (remoto--ensure-tree parsed))
         (dir-path (remoto--tree-lookup-key (remoto-path-path parsed)))
         (_ (when (and (gethash "\0truncated" tree)
                       (not (gethash (concat "\0fetched:" dir-path) tree)))
              (remoto--fetch-directory-contents parsed dir-path tree)))
         (prefix (if (string-empty-p dir-path) "" (concat dir-path "/")))
         (prefix-len (length prefix)))
    (thread-last (hash-table-keys tree)
      (seq-filter (lambda (path)
                    (and (not (string-prefix-p "\0" path))
                         (string-prefix-p prefix path)
                         (not (equal path dir-path))
                         ;; Direct child: no more slashes after prefix
                         (not (string-search "/" (substring path prefix-len))))))
      (mapcar (lambda (path)
                (cons (substring path prefix-len)
                      (gethash path tree))))
      (seq-remove (lambda (child) (string-empty-p (car child))))
      (seq-sort (lambda (a b) (string< (car a) (car b)))))))

;;;; Path normalization helpers

(defun remoto--normalize-path (path)
  "Clean up PATH component: collapse double slashes, resolve . and .."
  (let* ((parts (split-string path "/" t))
         (result nil))
    (dolist (p parts)
      (cond
       ((equal p "."))
       ((equal p "..")
        (when result (pop result)))
       (t (push p result))))
    (let ((normalized (concat "/" (mapconcat #'identity (nreverse result) "/"))))
      ;; Preserve trailing slash for directories
      (if (and (string-suffix-p "/" path)
               (not (string-suffix-p "/" normalized)))
          (concat normalized "/")
        normalized))))

(defun remoto--file-name-prefix (filename)
  "Extract the /github:owner/repo@ref: prefix from FILENAME."
  (when (string-match (rx bos "/github:"
                          (+ (not ":"))
                          ":")
                      filename)
    (match-string 0 filename)))

;;;; File-name handler

(defconst remoto--shorthand-prefix "/gh:"
  "Shorthand alias for the canonical /github: prefix.")

(defun remoto--normalize-shorthand (arg)
  "Rewrite a leading /gh: shorthand in ARG to the canonical /github:.
A non-string ARG, or a string lacking the shorthand prefix, is returned
unchanged so downstream handlers only ever see canonical paths."
  (if (and (stringp arg)
           (string-prefix-p remoto--shorthand-prefix arg))
      (concat "/github:" (substring arg (length remoto--shorthand-prefix)))
    arg))

(defun remoto-file-name-handler (operation &rest args)
  "Handle file OPERATION for remoto paths.
Dispatches to `remoto--handle-OPERATION' or falls through to defaults.
The /gh: shorthand in ARGS is normalized to /github: first, so every
resolved handler receives only canonical paths."
  (let ((args (mapcar #'remoto--normalize-shorthand args)))
    (if-let* ((handler (intern-soft (format "remoto--handle-%s" operation)))
              ((fboundp handler)))
        (apply handler args)
      ;; Fall through to default handler
      (let ((inhibit-file-name-handlers
             (cons #'remoto-file-name-handler
                   (and (eq inhibit-file-name-operation operation)
                        inhibit-file-name-handlers)))
            (inhibit-file-name-operation operation))
        (apply operation args)))))

;;;; Read operations

(defun remoto--handle-file-exists-p (filename)
  "Return t if FILENAME exists or is openable.
Returns nil for mid-completion paths (no selection made yet),
triggering variable `confirm-nonexistent-file-or-buffer' on RET."
  (cond
   ;; /github: and /github:owner/ - directory-like, exist for navigation
   ((string-match (rx bos "/github:" (? "/") eos) filename) t)
   ((string-match (rx bos "/github:"
                      (+ (not (in "/:@#")))
                      "/" eos)
                  filename) t)
   ;; /github:owner/repo/ - openable as dired on default branch
   ((string-match (rx bos "/github:"
                      (+ (not (in "/:@#")))
                      "/"
                      (+ (not (in "/:@#")))
                      "/")
                  filename) t)
   ;; /github:owner/repo#NUM - specific issue ref, openable
   ((string-match (rx bos "/github:"
                      (+ (not (in "/:@#")))
                      "/"
                      (+ (not (in "/:@#")))
                      "#"
                      (+ digit) eos)
                  filename) t)
   ;; /github:owner/repo (bare) - NOT openable, still needs delimiter
   ((string-match (rx bos "/github:"
                      (+ (not (in "/:@#")))
                      "/"
                      (+ (not (in "/:@#")))
                      eos)
                  filename)
    nil)
   ;; /github:owner/repo# or /github:owner/repo@ - delimiter without selection
   ((string-match (rx bos "/github:"
                      (+ (not (in "/:@#")))
                      "/"
                      (+ (not (in "/:@#")))
                      (in "@#") eos)
                  filename)
    nil)
   ;; /github:owner# or /github:owner@ - no repo, invalid
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx (in "@#") eos) filename))
    nil)
   ;; Full canonical path - check tree
   (t
    (when-let* ((parsed (remoto--parse-path filename)))
      ;; The repository root at a ref is openable on its shape alone, the
      ;; way /github:owner/repo/ above is.  Answering it from the tree
      ;; would cost one recursive tree per ref, because completion asks
      ;; this of every candidate it offers at the @ level.
      (if (string-empty-p (remoto--tree-lookup-key (remoto-path-path parsed)))
          t
        (and (remoto--tree-entry parsed) t))))))

(defun remoto--handle-access-file (filename string)
  "Return nil when FILENAME can be read, else signal `file-missing'.
STRING names the caller's purpose, as `access-file' documents.  Without
this the operation falls through to the local primitive, which sees no
such file and always signals, and `recentf' then drops every remoto
path."
  (unless (remoto--handle-file-exists-p filename)
    (signal 'file-missing
            (list string "No such file or directory" filename))))

(defun remoto--handle-file-directory-p (filename)
  "Return t if FILENAME is a directory in the remote repo.
Also returns t for partial paths like /github: and /github:OWNER/."
  (cond
   ;; /github: is a virtual directory root
   ((string-match (rx bos "/github:" (? "/") eos) filename) t)
   ;; /github:owner/ is a virtual owner directory
   ((remoto--parse-partial-github-path
     (remoto--handle-file-name-as-directory filename))
    t)
   (t
    (when-let* ((parsed (remoto--parse-path filename))
                (entry (remoto--tree-entry parsed)))
      (equal "tree" (alist-get 'type entry))))))

(defun remoto--handle-file-accessible-directory-p (filename)
  "Return t if FILENAME is an accessible directory.
Delegates to `file-directory-p' - remote dirs are always readable."
  (remoto--handle-file-directory-p filename))

(defun remoto--handle-file-regular-p (filename)
  "Return t if FILENAME is a regular file in the remote repo."
  (when-let* ((parsed (remoto--parse-path filename))
              (entry (remoto--tree-entry parsed)))
    (equal "blob" (alist-get 'type entry))))

(defun remoto--handle-file-readable-p (filename)
  "Return non-nil if remote FILENAME is readable."
  (remoto--handle-file-exists-p filename))

(defun remoto--handle-file-writable-p (_filename)
  "Remote repos are never writable."
  nil)

(defun remoto--handle-file-attributes (filename &optional _id-format)
  "Return file attributes for FILENAME.
Synthesized from tree cache - timestamps are epoch 0."
  (when-let* ((parsed (remoto--parse-path filename))
              (entry (remoto--tree-entry parsed)))
    (let* ((dir? (equal "tree" (alist-get 'type entry)))
           (size (or (alist-get 'size entry) 0))
           (mode-str (or (alist-get 'mode entry) "100644"))
           (mode (string-to-number mode-str 8))
           ;; Use epoch 0 for all timestamps
           (time '(0 0 0 0)))
      ;; Return vector matching `file-attributes' format:
      ;; (type links uid gid atime mtime ctime size mode
      ;;  gid-change inode device)
      (list (if dir? t nil)      ; type: t=dir, nil=file
            1                    ; links
            0                    ; uid
            0                    ; gid
            time                 ; atime
            time                 ; mtime
            time                 ; ctime
            size                 ; size
            (format "%05o" mode) ; mode string
            nil                  ; gid-change
            0                    ; inode
            0))))               ; device

(defun remoto--handle-directory-files (directory &optional full match nosort count)
  "List files in remote DIRECTORY.
FULL, MATCH, NOSORT, COUNT as per `directory-files'."
  (when-let* ((parsed (remoto--parse-path directory)))
    (let ((names (append '("." "..")
                         (mapcar #'car (remoto--tree-children parsed)))))
      (when match
        (setq names (seq-filter (lambda (name)
                                  (string-match-p match name))
                                names)))
      (unless nosort
        (setq names (sort names #'string<)))
      (when count
        (setq names (seq-take names count)))
      (if full
          (let ((prefix (remoto--file-name-prefix directory))
                (dir-path (remoto-path-path parsed)))
            (mapcar (lambda (name)
                      (concat prefix
                              (remoto--normalize-path
                               (concat dir-path "/" name))))
                    names))
        names))))

(defun remoto--handle-directory-files-and-attributes
    (directory &optional full match nosort id-format)
  "Like `directory-files-and-attributes' for remote DIRECTORY.
Pass FULL, MATCH, NOSORT, and ID-FORMAT through unchanged."
  (let* ((parsed (remoto--parse-path directory))
         (prefix (remoto--file-name-prefix directory))
         (base-path (lambda (f)
                      (concat prefix
                              (remoto--normalize-path
                               (concat (remoto-path-path parsed) "/" f))))))
    (thread-last
      (remoto--handle-directory-files directory full match nosort)
      (mapcar (lambda (f)
                (cons f (remoto--handle-file-attributes
                         (if full f (funcall base-path f))
                         id-format)))))))

(defun remoto--parse-partial-github-path (directory)
  "Parse a partial /github: DIRECTORY for pre-repo completion.
Returns a plist with :level plus context keys, or nil.
Levels: `root', `owner', `repo' (branches/tags), `files-default', `issues'."
  (when (stringp directory)
    (cond
     ;; /github:
     ((string-match (rx bos "/github:" eos) directory)
      (list :level 'root :owner nil))
     ;; /github:owner/repo# - issues level (repo must contain no /:@#)
     ((string-match (rx bos "/github:"
                        (group (+ (not (in "/:@#"))))
                        "/"
                        (group (+ (not (in "/:@#"))))
                        "#" eos)
                    directory)
      (list :level 'issues
            :owner (match-string 1 directory)
            :repo (match-string 2 directory)))
     ;; /github:owner/repo@ - branches/tags level
     ((string-match (rx bos "/github:"
                        (group (+ (not (in "/:@#"))))
                        "/"
                        (group (+ (not (in "/:@#"))))
                        "@" (? "/") eos)
                    directory)
      (list :level 'repo
            :owner (match-string 1 directory)
            :repo (match-string 2 directory)))
     ;; /github:owner/repo/ or /github:owner/repo/subdir/ - files-default
     ((string-match (rx bos "/github:"
                        (group (+ (not (in "/:@#"))))
                        "/"
                        (group (+ (not (in ":@#"))))
                        "/" eos)
                    directory)
      ;; Distinguish owner/ (level=owner) from owner/repo/ (level=files-default)
      ;; The second group must be a repo name (no slashes) or repo/subpath
      (let ((owner (match-string 1 directory))
            (rest (match-string 2 directory)))
        (if (string-match-p "/" rest)
            ;; rest contains slash: owner/repo/subdir
            (let* ((slash-pos (string-match "/" rest))
                   (repo (substring rest 0 slash-pos)))
              (list :level 'files-default
                    :owner owner
                    :repo repo))
          ;; rest is just repo name
          (list :level 'files-default
                :owner owner
                :repo rest))))
     ;; /github:owner/ - owner level
     ((string-match (rx bos "/github:"
                        (group (+ (not (in "/:@#"))))
                        "/" eos)
                    directory)
      (list :level 'owner :owner (match-string 1 directory))))))

(defvar remoto-min-search-chars) ; forward-decl for byte-compiler

(defun remoto--owner-candidate (owner)
  "Return a /github: root completion candidate for account OWNER.
Preserves OWNER's text properties (used for affixation) and attaches a
`remoto-target' of the canonical owner path so Embark can act on it."
  (propertize (concat owner "/")
              'remoto-target (concat "/github:" (substring-no-properties owner))))

(defun remoto--minibuffer-input ()
  "Contents of the current buffer when it is an active completion minibuffer."
  (when (and (minibufferp) minibuffer-completion-table)
    (minibuffer-contents-no-properties)))

(defun remoto--input-query (input directory)
  "Return the text of INPUT after DIRECTORY, or nil when INPUT is elsewhere.
Normalize INPUT with `substitute-in-file-name' first, the way
`read-file-name' does, so a shadowed prefix such as \"~/x//github:o/\"
and the /gh: shorthand both resolve to DIRECTORY.  Return nil as well when
the text after DIRECTORY carries a level delimiter: `partial-completion'
probes parent levels with an empty FILE while the input sits deeper,
and that probe must not turn the deeper path into a search query."
  (when-let* ((effective (condition-case nil
                             (substitute-in-file-name input)
                           (error input)))
              ((string-prefix-p directory effective))
              (rest (substring effective (length directory)))
              ((not (string-match-p (rx (in "/@#:")) rest))))
    rest))

(defun remoto--minibuffer-query (directory)
  "What the user typed after DIRECTORY in the active minibuffer, or nil.
Completion styles that express the typed text as `completion-regexp-list'
\(orderless) hand the table only the text up to the completion boundary,
so FILE in `file-name-all-completions' arrives empty; the search levels
need the typed text as their API query."
  (when-let* ((input (remoto--minibuffer-input)))
    (remoto--input-query input directory)))

(defun remoto--completion-query (file directory)
  "Search query for FILE in DIRECTORY: FILE, or the minibuffer text if empty."
  (if (string-empty-p file)
      (or (remoto--minibuffer-query directory) file)
    file))

(defun remoto--candidate-match-text (candidate)
  "Text that `completion-regexp-list' is matched against for CANDIDATE.
The bare number of an issue and the bare name of a repo or account are
rarely what the user types, so the title or description joins the
name.  The trailing / or : delimiter stays out, as the built-in file
name primitives match names without it."
  (let ((name (string-trim-right candidate "[/:]"))
        (extra (or (remoto--get-prop candidate 'remoto-topic-title)
                   (remoto--get-prop candidate 'remoto-repo-desc)
                   (remoto--get-prop candidate 'remoto-acct-desc))))
    (if (and (stringp extra) (not (string-empty-p extra)))
        (concat name " " extra)
      name)))

(defun remoto--filter-by-completion-regexps (candidates)
  "Drop the CANDIDATES that `completion-regexp-list' rejects.
Completion styles rely on the table applying `completion-regexp-list'
itself: the built-in `file-name-all-completions' and TRAMP both do, and
orderless never filters on its own.  Case folding follows
`completion-ignore-case', as in the built-in primitives."
  (if (null completion-regexp-list)
      candidates
    (let ((case-fold-search completion-ignore-case))
      (seq-filter (lambda (c)
                    (let ((text (remoto--candidate-match-text c)))
                      (seq-every-p (lambda (re) (string-match-p re text))
                                   completion-regexp-list)))
                  candidates))))

(defun remoto--handle-file-name-all-completions (file directory)
  "Return completions for FILE in remote DIRECTORY.
Applies `completion-regexp-list' like the built-in primitive does."
  (remoto--filter-by-completion-regexps
   (remoto--file-name-completions file directory)))

(defun remoto--file-name-completions (file directory)
  "Return unfiltered completions for FILE in remote DIRECTORY.
Handles multiple levels: user search at /github:, repo listing at
/github:OWNER/, branch/tag at /github:OWNER/REPO@, files at
/github:OWNER/REPO/, issues at /github:OWNER/REPO#, and file
listing within a repo.  Search-level calls (user, repo) are
non-blocking: cached results are returned immediately while async
fetches populate the cache in the background.
An empty FILE does not mean an empty query: see `remoto--minibuffer-query'."
  (if-let* ((partial (remoto--parse-partial-github-path directory)))
      (pcase (plist-get partial :level)
        ('root
         ;; Empty query + authenticated: show user + orgs
         ;; Non-empty: search users/orgs matching the query (non-blocking)
         (let ((query (remoto--completion-query file directory)))
           (if (string-empty-p query)
               (when-let* ((user remoto--authenticated-user))
                 (let* ((orgs (remoto--fetch-user-orgs user))
                        (all (cons (propertize user 'remoto-acct-type "User") orgs)))
                   (mapcar #'remoto--owner-candidate all)))
             (when-let* ((result (remoto--search-users query)))
               (let ((filtered (seq-filter (lambda (u) (string-prefix-p file u))
                                           result)))
                 ;; Pre-fetch repos for the top match so the cache is
                 ;; warm by the time the user types "/"
                 (when-let* ((top (car filtered)))
                   (remoto--prefetch-owner-repos top))
                 (mapcar #'remoto--owner-candidate filtered))))))
        ('owner
         ;; Repo completion at /github:OWNER/
         ;; Try cached/async results first; on cold-cache nil, fall
         ;; back to a synchronous fetch that yields to user input.
         (let* ((owner (plist-get partial :owner))
                (query (remoto--completion-query file directory))
                (repos (if (string-empty-p query)
                           (remoto--recent-owner-repos owner)
                         (remoto--search-owner-repos owner query))))
           (unless repos
             (let ((sync (while-no-input
                           (if (string-empty-p query)
                               (remoto--recent-owner-repos-sync owner)
                             (when (<= remoto-min-search-chars (length query))
                               (remoto--search-owner-repos-sync owner query))))))
               (when (consp sync)
                 (setq repos sync))))
           (mapcar (lambda (r)
                     (let* ((name (if (string-suffix-p "/" r) (substring r 0 -1) r))
                            (cand (concat name "/")))
                       ;; Carry the full canonical path so Embark actions can
                       ;; resolve a bare candidate (see `remoto--embark-transform').
                       (put-text-property 0 (length cand) 'remoto-target
                                          (format "/github:%s/%s:/" owner name)
                                          cand)
                       cand))
                   repos)))
        ('repo
         ;; Branch + tag completion at /github:OWNER/REPO@
         (if (string-suffix-p ":" file)
             ;; Ref already selected (e.g. "main:") - exact match
             (list file)
           (let* ((owner (plist-get partial :owner))
                  (repo (plist-get partial :repo))
                  (branches (while-no-input
                              (remoto--fetch-branches owner repo)))
                  (tags (while-no-input
                          (remoto--fetch-tags owner repo))))
             (when (or (listp branches) (listp tags))
               (let ((branch-set (when (listp branches)
                                   (mapcar (lambda (b)
                                             (propertize (concat b ":")
                                                        'remoto-ref-type "branch"
                                                        'remoto-target
                                                        (format "/github:%s/%s@%s:/"
                                                                owner repo b)))
                                           branches)))
                     (tag-set (when (listp tags)
                                (mapcar (lambda (tg)
                                          (propertize (concat tg ":")
                                                     'remoto-ref-type "tag"
                                                     'remoto-target
                                                     (format "/github:%s/%s@%s:/"
                                                             owner repo tg)))
                                        tags))))
                 (thread-last (append branch-set tag-set)
                   (seq-filter (lambda (r)
                                 (or (string-empty-p file)
                                     (string-prefix-p file r))))))))))
        ('files-default
         ;; File completion on default branch: /github:OWNER/REPO/[subdir/]
         ;; Uses lightweight Contents API (single call) instead of
         ;; recursive tree fetch for fast initial display.
         (let* ((owner (plist-get partial :owner))
                (repo (plist-get partial :repo))
                (branch (condition-case nil
                            (while-no-input
                              (remoto--default-branch owner repo))
                          (user-error nil))))
           (when (and (stringp branch) (not (equal branch t)))
             ;; Extract subpath from directory after owner/repo/
             (let* ((repo-end (string-match
                               (rx (+ (not (in "/:@#")))
                                   "/"
                                   (+ (not (in "/:@#")))
                                   "/")
                               directory
                               (length "/github:")))
                    (subpath (if repo-end
                                (substring directory (match-end 0))
                              ""))
                    (children (while-no-input
                                (remoto--fetch-dir-children-light
                                 owner repo branch subpath)))
                    (names (when (listp children)
                             (mapcar (lambda (child)
                                       (if (equal "tree" (alist-get 'type (cdr child)))
                                           (concat (car child) "/")
                                         (car child)))
                                     children)))
                    (filtered (when names
                                (if (string-empty-p file)
                                    names
                                  (seq-filter (lambda (name)
                                               (string-search file name))
                                             names)))))
               (when filtered
                 (mapcar (lambda (name)
                           (propertize name 'remoto-target
                                       (format "/github:%s/%s@%s:/%s%s"
                                               owner repo branch subpath name)))
                         filtered))))))
        ('issues
         ;; Issue/PR completion at /github:OWNER/REPO#
         (let* ((owner (plist-get partial :owner))
                (repo (plist-get partial :repo))
                (query (remoto--completion-query file directory))
                (issues
                 (cond
                  ;; Empty query: show top open issues
                  ((string-empty-p query)
                   (while-no-input
                     (remoto--fetch-issues owner repo)))
                  ;; Numeric query: direct fetch + filter cached
                  ((string-match-p (rx bos (+ digit) eos) query)
                   (let* ((cached (while-no-input
                                    (remoto--fetch-issues owner repo)))
                          (direct (while-no-input
                                    (remoto--fetch-issue owner repo query)))
                          (results (if (listp cached) cached nil)))
                     (if direct
                         (cl-remove-duplicates
                          (cons direct results)
                          :key (lambda (i) (alist-get 'number i)))
                       results)))
                  ;; Text query: search
                  (t
                   (while-no-input
                     (remoto--search-issues owner repo query))))))
           (when (listp issues)
             (let* ((candidates
                     (mapcar (lambda (i)
                               (let* ((num (number-to-string (alist-get 'number i)))
                                      (is-pr (and (alist-get 'pull_request i) t))
                                      (title (or (alist-get 'title i) ""))
                                      (state (or (alist-get 'state i) "")))
                                 (propertize num
                                             'remoto-topic-pr is-pr
                                             'remoto-topic-title title
                                             'remoto-topic-state state
                                             'remoto-target
                                             (format "/github:%s/%s#%s"
                                                     owner repo num))))
                             issues))
                    (filtered
                     (if (or (string-empty-p file)
                             (string-match-p (rx bos (+ digit) eos) file))
                         (seq-filter (lambda (n) (string-prefix-p file n)) candidates)
                       candidates)))
               ;; Sort: PRs first, then issues; within each group by number descending
               (sort filtered
                     (lambda (a b)
                       (let ((a-pr (get-text-property 0 'remoto-topic-pr a))
                             (b-pr (get-text-property 0 'remoto-topic-pr b)))
                         (cond
                          ((and a-pr (not b-pr)) t)
                          ((and (not a-pr) b-pr) nil)
                          (t (< (string-to-number b) (string-to-number a))))))))))))
    ;; Full canonical path - existing behavior
    (when-let* ((parsed (remoto--parse-path directory)))
      (let* ((owner (remoto-path-owner parsed))
             (repo (remoto-path-repo parsed))
             (ref (remoto-path-ref parsed))
             (path (remoto-path-path parsed))
             (dir-path (if (equal path "/") ""
                         (string-trim-left path "/")))
             (children (remoto--tree-children parsed))
             (names (thread-last children
                      (mapcar (lambda (child)
                                (if (equal "tree" (alist-get 'type (cdr child)))
                                    (concat (car child) "/")
                                  (car child))))
                      (seq-filter (lambda (name)
                                    (string-prefix-p file name)))))
             (commits (when ref
                        (remoto--fetch-file-commits
                         owner repo ref dir-path names))))
        (mapcar (lambda (name)
                  (let ((cand (copy-sequence name))
                        (msg (alist-get name commits nil nil #'equal)))
                    (when msg
                      (put-text-property 0 (length cand) 'remoto-file-commit msg cand))
                    (put-text-property 0 (length cand) 'remoto-target
                                       (concat directory name) cand)
                    cand))
                names)))))

(defun remoto--handle-file-name-completion (file directory &optional predicate)
  "Complete FILE in remote DIRECTORY using optional PREDICATE.
Handles partial /github: paths for pre-repo completion.
PREDICATE may be a function, nil, or a string directory-prefix
passed through by `completion-file-name-table' - strings are
ignored since remoto paths always qualify."
  (let ((completions (remoto--handle-file-name-all-completions file directory))
        ;; completion-file-name-table passes the read-file-name
        ;; directory as a string predicate - not a callable filter
        (pred (if (stringp predicate) nil predicate)))
    (cond
     ((null completions) nil)
     ((null (cdr completions))
      (if (equal file (car completions)) t (car completions)))
     (t (try-completion file completions pred)))))

(defun remoto--handle-expand-file-name (name &optional dir)
  "Expand NAME relative to DIR for remoto paths."
  (let ((inhibit-file-name-handlers
         (cons #'remoto-file-name-handler
               (and (eq inhibit-file-name-operation 'expand-file-name)
                    inhibit-file-name-handlers)))
        (inhibit-file-name-operation 'expand-file-name))
    (cond
     ;; Already absolute remoto path
     ((string-prefix-p "/github:" name) name)
     ;; Local absolute or home-relative path - never resolve under remoto
     ((or (and (string-prefix-p "/" name)
              (not (string-prefix-p "/github:" name)))
          (string-prefix-p "~" name))
      (expand-file-name name))
     ;; Relative path under a remoto directory
     ((and dir (string-prefix-p "/github:" dir))
      (if-let* ((parsed (remoto--parse-path dir))
                (prefix (remoto--file-name-prefix dir)))
          (let* ((dir-path (remoto-path-path parsed))
                 (combined (concat dir-path "/" name)))
            (concat prefix (remoto--normalize-path combined)))
        ;; Partial path (e.g. /github:owner/ or /github:owner/repo@)
        (concat dir name)))
     ;; Not our path, delegate
     (t (expand-file-name name dir)))))

(defun remoto--handle-file-truename (filename &optional _counter _prev-dirs)
  "Return FILENAME as-is - no symlink resolution for remote repos."
  filename)

(defun remoto--reached-p (filename)
  "Return non-nil when FILENAME's repository was already reached this session.
A cached default branch or tree is as close as remoto comes to an open
connection: it means GitHub answered for that repository without a new
request."
  (when-let* ((parsed (remoto--parse-path filename)))
    (or (gethash (format "%s/%s"
                         (remoto-path-owner parsed)
                         (remoto-path-repo parsed))
                 remoto--default-branch-cache)
        (gethash (remoto--repo-key parsed) remoto--tree-cache))))

(defun remoto--handle-file-remote-p (filename &optional identification connected)
  "Return remote identification for FILENAME.
Use IDENTIFICATION to select which remote field to report.
CONNECTED asks for an answer only while the repository is reachable
without a request, which is what keeps `recentf' and `auto-revert' from
making remoto fetch a tree just to classify a path.  The symbol `never'
means the opposite - answer, but never open a connection - so it reads
like a nil CONNECTED here, where no answer costs one.
Handles partial paths for pre-repo completion."
  (when (and (string-prefix-p "/github:" filename)
             (or (not connected)
                 (eq connected 'never)
                 (remoto--reached-p filename)))
    (if-let* ((parsed (remoto--parse-path filename))
              (prefix (remoto--file-name-prefix filename)))
        (pcase identification
          ('method "github")
          ('host (format "%s/%s" (remoto-path-owner parsed)
                         (remoto-path-repo parsed)))
          (_ prefix))
      ;; Partial path - still remote
      (pcase identification
        ('method "github")
        ('host "github.com")
        (_ "/github:")))))

(defun remoto--handle-file-name-directory (filename)
  "Return directory part of remote FILENAME.
Handles partial paths including # and files-default short forms."
  (cond
   ;; /github:owner/repo#query - # is delimiter, directory is up to and including #
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx bos "/github:"
                           (+ (not (in "/:@#")))
                           "/"
                           (+ (not (in "/:@#")))
                           "#")
                       filename))
    (match-string 0 filename))
   ;; /github:owner/repo@... - treat repo@ as directory
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx bos "/github:"
                           (+ (not (in "/:@#")))
                           "/"
                           (+ (not (in "/:@#")))
                           "@")
                       filename))
    (match-string 0 filename))
   ;; /github:owner/repo/... - files-default short form
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx bos "/github:"
                           (+ (not (in "/:@#")))
                           "/"
                           (+ (not (in "/:@#")))
                           "/")
                       filename))
    (if (string-suffix-p "/" filename)
        filename
      ;; Find the last / and return everything up to and including it
      (let ((last-slash (string-match-p (rx "/" (+ (not "/")) eos) filename)))
        (if last-slash
            (substring filename 0 (1+ last-slash))
          filename))))
   ;; /github:owner/repo (bare, no delimiter) -> directory is /github:owner/
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx bos "/github:"
                           (+ (not (in "/:@#")))
                           "/")
                       filename))
    (match-string 0 filename))
   ;; /github: or /github:owner or /github:owner-with-specials
   ;; Anything after /github: without a / is the owner query
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename)))
    (if (string-match (rx bos "/github:" eos) filename)
        "/github:"
      "/github:"))
   ;; Full canonical path.  The result must be a prefix of FILENAME:
   ;; `completion-file-name-table' derives the completion boundary from
   ;; its length, so a synthesized "/" after the colon would push the
   ;; boundary past the text being completed and make the UI append the
   ;; candidate to it.  Hence the raw path, not the parsed one, which
   ;; normalizes "" to "/".
   (t
    (when-let* ((prefix (remoto--file-name-prefix filename))
                ((remoto--parse-path filename)))
      (let* ((path (substring filename (length prefix)))
             (dir (if (string-suffix-p "/" path)
                      path
                    (file-name-directory path))))
        (concat prefix (or dir "")))))))

(defun remoto--handle-file-name-nondirectory (filename)
  "Return non-directory part of remote FILENAME.
Handles partial paths including # and files-default short forms."
  (cond
   ;; /github: -> ""
   ((string-match (rx bos "/github:" eos) filename) "")
   ;; /github:owner/repo#query - nondirectory is text after #
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx bos "/github:"
                           (+ (not (in "/:@#")))
                           "/"
                           (+ (not (in "/:@#")))
                           "#"
                           (group (* anything)) eos)
                       filename))
    (match-string 1 filename))
   ;; /github:owner/repo@ -> ""
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx bos "/github:"
                           (+ (not (in "/:@#")))
                           "/"
                           (+ (not (in "/:@#")))
                           "@" eos)
                       filename))
    "")
   ;; /github:owner/repo@branch -> "branch"
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx bos "/github:"
                           (+ (not (in "/:@#")))
                           "/"
                           (+ (not (in "/:@#")))
                           "@"
                           (group (+ (not (in "/:@"))))
                           eos)
                       filename))
    (match-string 1 filename))
   ;; /github:owner/repo/path - files-default short form
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx bos "/github:"
                           (+ (not (in "/:@#")))
                           "/"
                           (+ (not (in "/:@#")))
                           "/")
                       filename))
    ;; After repo/, extract the last component without re-entering handler
    (if (string-suffix-p "/" filename)
        ""
      (let ((last-slash (string-match-p (rx "/" (+ (not "/")) eos) filename)))
        (if last-slash
            (substring filename (1+ last-slash))
          ""))))
   ;; /github:owner/ -> ""
   ((and (string-prefix-p "/github:" filename)
         (string-suffix-p "/" filename)
         (not (remoto--parse-path filename)))
    "")
   ;; /github:owner/repo (bare, no delimiter) -> "repo"
   ((and (string-prefix-p "/github:" filename)
         (not (remoto--parse-path filename))
         (string-match (rx bos "/github:" (+ (not (in "/:@#"))) "/"
                           (group (+ (not (in "/:@#")))) eos)
                       filename))
    (match-string 1 filename))
   ;; /github:query - everything after /github: is the query (owner or owner#, etc.)
   ((and (not (remoto--parse-path filename))
         (string-match (rx bos "/github:" (group (+ anything)) eos) filename))
    (match-string 1 filename))
   ;; Full canonical path
   (t
    (if-let* ((parsed (remoto--parse-path filename)))
        (thread-last (remoto-path-path parsed)
          (directory-file-name)
          (file-name-nondirectory))
      (file-name-nondirectory filename)))))

;;;; File content fetching

(defun remoto--relative-path (path)
  "Strip leading slash from PATH for API requests."
  (if (string-prefix-p "/" path) (substring path 1) path))

(defvar remoto--content-cache (make-hash-table :test 'equal)
  "Cache: sha -> raw file bytes as a unibyte string.")

(defun remoto--fetch-file-content (owner repo path ref)
  "Fetch the raw bytes of the file at PATH in OWNER/REPO@REF.
Uses Contents API for files under 1MB, Blobs API otherwise.
Return a unibyte string; the caller decides how to decode it."
  (let* ((endpoint (format "repos/%s/%s/contents/%s?ref=%s"
                           owner repo
                           (url-hexify-string path) ref))
         (data (remoto--api endpoint))
         (sha (alist-get 'sha data))
         (cached (gethash sha remoto--content-cache)))
    (or cached
        (let* ((encoding (alist-get 'encoding data))
               (content
                (if (equal encoding "base64")
                    (let ((raw (alist-get 'content data)))
                      (base64-decode-string (string-replace "\n" "" raw)))
                  ;; Too large - use Blobs API
                  (remoto--fetch-blob owner repo sha))))
          (puthash sha content remoto--content-cache)
          content))))

(defun remoto--fetch-blob (owner repo sha)
  "Fetch a git blob by SHA from OWNER/REPO.  Return its raw bytes."
  (let* ((endpoint (format "repos/%s/%s/git/blobs/%s" owner repo sha))
         (data (remoto--api endpoint))
         (raw (alist-get 'content data)))
    (base64-decode-string (string-replace "\n" "" raw))))

(defun remoto--topic-path (filename)
  "Return (REPO-PATH . NUMBER) when FILENAME names an issue or pull request.
The /github:OWNER/REPO#NUM shape belongs to `remoto-topic-display', not
to any file operation, so both the `find-file' advice and the handler
recognize it here."
  (when (and (stringp filename)
             (string-match (rx "/github:" (+ (not (in "/@#"))) "/"
                               (+ (not (in "/@#")))
                               (group "#") (group (+ digit)) eos)
                           filename))
    (cons (substring filename 0 (match-beginning 1))
          (match-string 2 filename))))

(defun remoto--handle-insert-file-contents
    (filename &optional visit beg end replace)
  "Insert contents of remote FILENAME into current buffer.
VISIT, BEG, END, REPLACE as per `insert-file-contents'."
  ;; Reached when the `find-file-noselect' advice did not run, which is
  ;; the case for the very first remoto call of a session.  Say what the
  ;; path is and take the buffer `find-file-noselect' made with it: that
  ;; function has no unwind of its own, so the error would leave an empty
  ;; buffer named after the number.  The emptiness test is what tells that
  ;; buffer apart from a caller's own.
  (when (remoto--topic-path filename)
    ;; An empty buffer with no file name, under VISIT, is the state
    ;; `find-file-noselect' leaves: that call reached the handler because it
    ;; started before `remoto--install' added the advice that turns a #NUM
    ;; path into a topic buffer, and the advice is in place by now, so
    ;; repeating the call works.  Any other caller asked for file contents
    ;; directly and needs the command that goes through the advice.
    (let ((from-find-file (and visit (zerop (buffer-size)) (not buffer-file-name))))
      (when from-find-file
        (set-buffer-modified-p nil)
        (kill-buffer (current-buffer)))
      (user-error
       "Remoto: %s is an issue or pull request, not a file - %s"
       filename
       (if from-find-file
           "remoto is loaded now, run the command again"
         "open it with `find-file'"))))
  (let ((parsed (remoto--parse-path filename)))
    (unless parsed
      (error "Remoto: cannot parse path: %s" filename))
    ;; `find-file-noselect' treats a `file-error' as a nonexistent file and
    ;; otherwise keeps the buffer it created; the tree is cached, so the
    ;; check costs no request.  Like the primitive and TRAMP, a visiting
    ;; call still records the file name so the new-file path can go on.
    (unless (remoto--tree-entry parsed)
      (when visit
        (setq buffer-file-name filename)
        (set-buffer-modified-p nil))
      (signal 'file-missing
              (list "Opening input file" "No such file or directory" filename)))
    (let* ((resolved (remoto--resolve-ref parsed))
           (path (remoto--relative-path (remoto-path-path resolved)))
           (bytes (remoto--fetch-file-content
                   (remoto-path-owner resolved)
                   (remoto-path-repo resolved)
                   path
                   (remoto-path-ref resolved))))
      (when replace (erase-buffer))
      (let ((pt (point))
            len)
        ;; Insert the bytes and decode them in place, so the file gets the
        ;; coding the primitive would pick from disk: cookies and
        ;; `auto-coding-alist' by name, then detection.  A binary such as
        ;; an image stays raw bytes under `no-conversion', which is how
        ;; `image-mode' recovers the data from a remote buffer.  The
        ;; primitive sets `buffer-file-coding-system' from the result once
        ;; this handler returns the decoded length.
        (save-restriction
          (narrow-to-region pt pt)
          (insert (if (or beg end) (substring bytes (or beg 0) end) bytes))
          (decode-coding-inserted-region (point-min) (point-max) filename
                                         visit beg end replace)
          (setq len (- (point-max) (point-min))))
        (goto-char pt)
        (when visit
          (setq buffer-file-name filename)
          (setq buffer-read-only t)
          (set-buffer-modified-p nil)
          (set-visited-file-modtime 0))
        (list filename len)))))

;;;; Dired integration

(defun remoto--mode-to-string (mode-str dir?)
  "Convert git MODE-STR to an ls-style permission string for DIR?."
  (cond
   (dir?                "drwxr-xr-x")
   ((equal mode-str "100755") "-rwxr-xr-x")
   ((equal mode-str "120000") "lrwxrwxrwx")
   (t                   "-rw-r--r--")))

(defun remoto--format-dired-entry (name plist)
  "Format a single Dired line for NAME with PLIST attributes.
No leading spaces - Dired and dired-subtree add their own."
  (let* ((dir? (equal "tree" (alist-get 'type plist)))
         (size (or (alist-get 'size plist) 0))
         (mode (or (alist-get 'mode plist) "100644"))
         (perms (remoto--mode-to-string mode dir?)))
    (format "%s  1 github github %8d Jan  1  2000 %s\n"
            perms size name)))

(defun remoto--handle-insert-directory
    (filename _switches &optional _wildcard full-directory-p)
  "Insert a Dired-format listing for remote FILENAME.
Use FULL-DIRECTORY-P to force directory-style output.
A short form such as /github:OWNER/REPO/ is resolved here rather than
left unparseable: `dired-noselect' discards the result of the one
operation the autoload bootstrap can rewrite, so the first Dired of a
session reaches this handler with the name the caller typed."
  (when-let* ((parsed (remoto--parse-path (remoto--maybe-rewrite filename)))
              (entry (remoto--tree-entry parsed)))
    (cond
     ((or full-directory-p
          (equal "tree" (alist-get 'type entry)))
      (insert "total 0\n")
      (insert (remoto--format-dired-entry "." remoto--dir-entry))
      (insert (remoto--format-dired-entry ".." remoto--dir-entry))
      (dolist (child (remoto--tree-children parsed))
        (insert (remoto--format-dired-entry (car child) (cdr child)))))
     (t
      (let ((name (file-name-nondirectory
                   (directory-file-name (remoto-path-path parsed)))))
        (insert (remoto--format-dired-entry name entry)))))))

(defun remoto--handle-file-local-copy (filename)
  "Download remote FILENAME to a temp file, return temp path."
  (when-let* ((parsed (remoto--parse-path filename))
              (resolved (remoto--resolve-ref parsed))
              (path (remoto--relative-path (remoto-path-path resolved)))
              (content (remoto--fetch-file-content
                        (remoto-path-owner resolved)
                        (remoto-path-repo resolved)
                        path
                        (remoto-path-ref resolved))))
    (let* ((ext (file-name-extension path t))
           (temp (make-temp-file "remoto-" nil ext))
           (coding-system-for-write 'no-conversion))
      (write-region content nil temp nil 0)
      temp)))

(defun remoto--handle-make-nearby-temp-file (prefix &optional dir-flag suffix)
  "Create a temp file using PREFIX in the system temp dir.
Pass DIR-FLAG and SUFFIX through to `make-temp-file'."
  (make-temp-file prefix dir-flag suffix))

;;;; Additional operations needed by dired and other Emacs internals

(defun remoto--handle-file-name-as-directory (filename)
  "Append / to FILENAME if not already present."
  (if (string-suffix-p "/" filename)
      filename
    (concat filename "/")))

(defun remoto--handle-directory-file-name (directory)
  "Strip trailing / from DIRECTORY."
  (if (and (string-suffix-p "/" directory)
           ;; Don't strip the / after the colon in /github:o/r@ref:/
           (not (string-suffix-p ":/" directory)))
      (substring directory 0 (1- (length directory)))
    directory))

(defun remoto--handle-file-name-case-insensitive-p (_filename)
  "GitHub repos are case-sensitive."
  nil)

(defun remoto--handle-vc-registered (_filename)
  "Remote files are not under local vc."
  nil)

(defun remoto--handle-make-directory (dir &optional _parents)
  "Ignore existing DIR and signal an error otherwise."
  (unless (remoto--handle-file-directory-p dir)
    (user-error "Remoto: repository is read-only")))

(defun remoto--handle-abbreviate-file-name (filename)
  "Return FILENAME as-is - no abbreviation for remote paths."
  filename)

(defun remoto--handle-unhandled-file-name-directory (_filename)
  "Return nil - no local equivalent for remote paths."
  nil)

;;;; Write operations (all read-only)

(defun remoto--read-only (&rest _args)
  "Signal that remote repos are read-only."
  (user-error "Remoto: repository is read-only"))

(defalias 'remoto--handle-write-region #'remoto--read-only)
(defalias 'remoto--handle-delete-file #'remoto--read-only)
(defalias 'remoto--handle-delete-directory #'remoto--read-only)
(defalias 'remoto--handle-rename-file #'remoto--read-only)
(defun remoto--handle-copy-file (file newname
                                      &optional ok-if-already-exists keep-time
                                      preserve-uid-gid preserve-permissions)
  "Copy FILE to NEWNAME.  Works when destination is outside remoto.
OK-IF-ALREADY-EXISTS, KEEP-TIME, PRESERVE-UID-GID, and
PRESERVE-PERMISSIONS are passed through to `copy-file'."
  (if (string-match-p remoto--path-regexp newname)
      (remoto--read-only 'copy-file file newname)
    (let ((local-copy (remoto--handle-file-local-copy file)))
      (unless local-copy
        (error "Remoto: failed to download %s" file))
      (unwind-protect
          (let ((inhibit-file-name-handlers
                 (cons #'remoto-file-name-handler
                       (and (eq inhibit-file-name-operation 'copy-file)
                            inhibit-file-name-handlers)))
                (inhibit-file-name-operation 'copy-file))
            (copy-file local-copy newname ok-if-already-exists keep-time
                       preserve-uid-gid preserve-permissions))
        (when (file-exists-p local-copy)
          (delete-file local-copy))))))
(defalias 'remoto--handle-set-file-modes #'remoto--read-only)
(defalias 'remoto--handle-set-file-times #'remoto--read-only)

;;;; User input parsing

(defun remoto--parse-github-url (input)
  "Parse GitHub web INPUT into a `remoto-path' struct."
  (cond
   ((string-match
     (rx bos "https://github.com/"
         (group (+ (not "/")))
         "/"
         (group (+ (not (in "/#"))))
         (? "/" (or "tree" "blob") "/"
            (group (+ (not "/")))
            (? "/" (group (+ (not "#")))))
         (* nonl)
         eos)
     input)
    (remoto-path-create
     :owner (match-string 1 input)
     :repo (let ((repo (match-string 2 input)))
             (if (string-suffix-p ".git" repo) (substring repo 0 -4) repo))
     :ref (match-string 3 input)
     :path (concat "/" (or (match-string 4 input) ""))))
   ((string-match
     (rx bos "https://github.com/"
         (group (+ (not "/")))
         "/"
         (group (+ (not (in "/#. "))))
         (* (in "/."))
         eos)
     input)
    (remoto-path-create
     :owner (match-string 1 input)
     :repo (match-string 2 input)
     :ref nil
     :path "/"))))

(defun remoto--parse-topic-url (input)
  "Return (OWNER REPO NUMBER) for a pull request or issue web URL INPUT.
Accepts the https and bare github.com forms.  Whatever follows the
number is ignored: /files, /commits, an #issuecomment fragment, a query.
Return nil for any other input."
  (when (string-match (rx bos (? "/") (? "https://") "github.com/"
                          (group (+ (not (in "/#?")))) "/"
                          (group (+ (not (in "/#?")))) "/"
                          (or "pull" "issues") "/"
                          (group (+ digit))
                          (or eos (in "/#?")))
                      input)
    (list (match-string 1 input) (match-string 2 input) (match-string 3 input))))

(defun remoto--parse-git-remote (input)
  "Parse git remote INPUT into a `remoto-path' struct."
  (when (string-match
         (rx bos "git@github.com:"
             (group (+ (not "/")))
             "/"
             (group (+ (not (in "/ "))))
             eos)
         input)
    (let ((repo (match-string 2 input)))
      (remoto-path-create
       :owner (match-string 1 input)
       :repo (if (string-suffix-p ".git" repo)
                 (substring repo 0 -4)
               repo)
       :ref nil
       :path "/"))))

(defun remoto--parse-repo-shorthand (input)
  "Parse owner/repo INPUT into a `remoto-path' struct."
  (when (string-match
         (rx bos
             (group (+ (not (in "/@"))))
             "/"
             (group (+ (not (in "/@"))))
             (? "@" (group (+ nonl)))
             eos)
         input)
    (remoto-path-create
     :owner (match-string 1 input)
     :repo (match-string 2 input)
     :ref (match-string 3 input)
     :path "/")))

(defun remoto--parse-input (input)
  "Normalize user INPUT into a `remoto-path' struct.
Accept GitHub URLs, git remote URLs, or owner/repo shorthand."
  (let ((input (string-trim input)))
    (or (remoto--parse-github-url input)
        (remoto--parse-git-remote input)
        (remoto--parse-repo-shorthand input)
        (user-error "Remoto: cannot parse input: %s" input))))

;;;###autoload
(defun remoto-refresh ()
  "Invalidate cached tree for the current repo, re-fetch on next access."
  (interactive)
  (let* ((dir (or dired-directory default-directory))
         (parsed (remoto--parse-path dir)))
    (if parsed
        (let* ((resolved (remoto--resolve-ref parsed))
               (key (remoto--repo-key resolved)))
          (remhash key remoto--tree-cache)
          (remhash (format "%s/%s" (remoto-path-owner resolved)
                           (remoto-path-repo resolved))
                   remoto--branches-cache)
          (message "Remoto: cache cleared for %s" key)
          (when (derived-mode-p 'dired-mode)
            (revert-buffer)))
      (user-error "Remoto: not in a remoto buffer"))))

;;;; Forge web URLs

(defvar remoto-forge-url-templates
  '((github
     (blob    . "https://github.com/%o/%r/blob/%R/%p%L")
     (tree    . "https://github.com/%o/%r/tree/%R/%p%L")
     (blame   . "https://github.com/%o/%r/blame/%R/%p%L")
     (history . "https://github.com/%o/%r/commits/%R/%p")
     (raw     . "https://raw.githubusercontent.com/%o/%r/%R/%p")
     (repo    . "https://github.com/%o/%r")
     (ssh     . "git@github.com:%o/%r.git")
     (https   . "https://github.com/%o/%r.git")
     (compare . "https://github.com/%o/%r/compare/%R")
     (new-pr  . "https://github.com/%o/%r/pull/new/%R")
     (issue   . "https://github.com/%o/%r/issues/%N")
     (pr-diff . "https://github.com/%o/%r/pull/%N/files")
     (owner       . "https://github.com/%o")
     (owner-repos . "https://github.com/%o?tab=repositories")
     (line    . "#L%s")
     (region  . "#L%s-L%e")))
  "Per-forge web-URL templates, keyed by forge symbol.

Each value is an alist of (KIND . TEMPLATE).  Path-level kinds: `blob',
`tree', `blame', `history', `raw'.  Repository-level kinds: `repo' (web
root), `ssh' and `https' (clone URLs).  Account-level kinds: `owner' for
the profile page and `owner-repos' for the repositories tab.  Plus the
line-fragment builders `line' and `region'.  Templates are expanded with
`format-spec' using:

  %o  repository owner
  %r  repository name
  %R  git ref (branch, tag, or commit SHA)
  %p  path relative to the repository root
  %L  line fragment built from the `line'/`region' templates
  %s  start line (in the `line' and `region' templates)
  %e  end line (in the `region' template)

Supporting another forge (GitLab, Codeberg, ...) is a matter of adding
an entry here and teaching `remoto--parse-path' the new path prefix.")

(defun remoto--forge-type (path)
  "Return the forge symbol for remoto PATH, or nil when undetermined.
Derived from the path prefix, e.g. \"/github:...\" -> `github'."
  (when (and (stringp path)
             (string-match (rx bos "/" (group (+ (not (in "/:")))) ":") path))
    (let ((prefix (match-string 1 path)))
      (if (member prefix '("github" "gh")) 'github (intern prefix)))))

(defun remoto--url-encode-path (path)
  "Percent-encode each segment of PATH for a web URL, keeping the slashes."
  (mapconcat #'url-hexify-string (split-string (or path "") "/") "/"))

(defun remoto--forge-url (forge kind owner repo ref path &optional line-start line-end)
  "Build a FORGE web URL of KIND for OWNER/REPO at REF and PATH.
KIND is one of `blob', `tree', `blame', `history', `raw'.  A nil REF
defaults to \"HEAD\" (the forge resolves it to the default branch), so a
repo-level target with no ref still produces a valid URL.  LINE-START and
LINE-END add a line or line-range fragment when KIND's template includes
one."
  (let* ((templates (or (alist-get forge remoto-forge-url-templates)
                        (user-error "Remoto: no URL templates for forge `%s'"
                                    forge)))
         (template (or (alist-get kind templates)
                       (user-error "Remoto: forge `%s' has no `%s' URL"
                                   forge kind)))
         (line (cond
                ((and line-start line-end)
                 (format-spec (alist-get 'region templates)
                              `((?s . ,line-start) (?e . ,line-end))))
                (line-start
                 (format-spec (alist-get 'line templates)
                              `((?s . ,line-start))))
                (t ""))))
    (format-spec template `((?o . ,owner)
                            (?r . ,repo)
                            (?R . ,(or ref "HEAD"))
                            (?p . ,(remoto--url-encode-path path))
                            (?L . ,line)))))

(defun remoto--forge-issue-url (forge owner repo number &optional kind)
  "Build a web URL for issue/PR NUMBER in OWNER/REPO on FORGE.
KIND selects the %N-based template (default `issue'); the PR files-diff
page uses `pr-diff'."
  (let* ((kind (or kind 'issue))
         (template (or (alist-get kind (alist-get forge remoto-forge-url-templates))
                       (user-error "Remoto: forge `%s' has no `%s' URL" forge kind))))
    (format-spec template `((?o . ,owner) (?r . ,repo) (?N . ,number)))))

(defun remoto--forge-owner-url (forge owner &optional kind)
  "Build a web URL for the account/organization OWNER on FORGE.
KIND selects the %o-based template (default `owner'); the repositories
tab uses `owner-repos'."
  (let* ((kind (or kind 'owner))
         (template (or (alist-get kind (alist-get forge remoto-forge-url-templates))
                       (user-error "Remoto: forge `%s' has no `%s' URL" forge kind))))
    (format-spec template `((?o . ,owner)))))

(defun remoto--resolve-commit-sha (owner repo ref)
  "Resolve REF in OWNER/REPO to a commit SHA via the forge API.
Used for permalinks so the link survives the ref moving on."
  (let* ((data (remoto--api (format "repos/%s/%s/commits/%s" owner repo ref)))
         (sha (alist-get 'sha data)))
    (or sha
        (user-error "Remoto: could not resolve commit SHA for %s/%s@%s"
                    owner repo ref))))

(defun remoto--path-context (path &optional line-start line-end)
  "Build a forge-agnostic context plist for the remoto PATH string.
Return nil when PATH is not a remoto path.

Plist keys: :forge :owner :repo :ref :path :kind :type :line-start
:line-end.  :kind is `tree' or `blob'.  :type is the Embark target type,
one of `remoto-repo', `remoto-dir', `remoto-file'.  A repository root is
classified as `remoto-repo' without resolving the ref or fetching the
tree (so it works offline and on bare `owner/repo' targets).  LINE-START
and LINE-END are retained only for `remoto-file' targets."
  (when-let* ((parsed (remoto--parse-path path)))
    (if (member (remoto-path-path parsed) '("" "/"))
        (list :forge (remoto--forge-type path)
              :owner (remoto-path-owner parsed)
              :repo (remoto-path-repo parsed)
              :ref (remoto-path-ref parsed)
              :path "" :kind 'tree :type 'remoto-repo
              :line-start nil :line-end nil)
      (let* ((resolved (remoto--resolve-ref parsed))
             (entry (remoto--tree-entry resolved))
             (filep (not (and entry (equal "tree" (alist-get 'type entry))))))
        (list :forge (remoto--forge-type path)
              :owner (remoto-path-owner resolved)
              :repo (remoto-path-repo resolved)
              :ref (remoto-path-ref resolved)
              :path (remoto--relative-path (remoto-path-path resolved))
              :kind (if filep 'blob 'tree)
              :type (if filep 'remoto-file 'remoto-dir)
              :line-start (and filep line-start)
              :line-end (and filep line-end))))))

(defun remoto--buffer-file-context ()
  "Return a context plist describing the current buffer's remoto target.

Works in file buffers (line/region at point) and in Dired (entry at
point, falling back to the directory).  Resolves the ref so the context
carries a concrete branch, then delegates classification to
`remoto--path-context'.  Signals a `user-error' when the current buffer
is not a remoto buffer."
  (let* ((dired (derived-mode-p 'dired-mode))
         (file (or buffer-file-name
                   (and dired (dired-get-filename nil t))
                   (and dired (if (listp dired-directory)
                                  (car dired-directory)
                                dired-directory))
                   default-directory))
         (parsed (and file (remoto--parse-path file))))
    (unless parsed
      (user-error "Remoto: not in a remoto buffer"))
    (let* ((canonical (remoto--canonical-path (remoto--resolve-ref parsed)))
           (region (and (not dired) (use-region-p)))
           (line-start (and (not dired)
                            (line-number-at-pos
                             (if region (region-beginning) (point)))))
           (line-end (and region (line-number-at-pos (region-end)))))
      (remoto--path-context canonical line-start line-end))))

(defun remoto--context-url (ctx kind &optional ref)
  "Build a URL of KIND from context plist CTX.
Optional REF overrides the ref in CTX (used for permalinks)."
  (remoto--forge-url (plist-get ctx :forge)
                     kind
                     (plist-get ctx :owner)
                     (plist-get ctx :repo)
                     (or ref (plist-get ctx :ref))
                     (plist-get ctx :path)
                     (plist-get ctx :line-start)
                     (plist-get ctx :line-end)))

(defun remoto--context-web-url (ctx)
  "Return the human-facing web URL for context CTX, chosen by its :type.
A repo target yields the repository page, a directory the tree view, and
a file the blob view (with any line fragment)."
  (remoto--context-url ctx (pcase (plist-get ctx :type)
                             ('remoto-repo 'repo)
                             ('remoto-dir 'tree)
                             (_ 'blob))))

(defun remoto--require-blob (ctx what)
  "Signal a `user-error' unless CTX refers to a file.
WHAT names the operation, for the error message."
  (unless (eq (plist-get ctx :kind) 'blob)
    (user-error "Remoto: %s is only available for files, not directories"
                what)))

(defun remoto--kill-url (url)
  "Put URL on the kill ring and report it in the echo area."
  (kill-new url)
  (message "Copied: %s" url))

;;;; URL commands

;;;###autoload
(defun remoto-copy-url ()
  "Copy the forge web URL for the current file or directory.
In a file buffer the link targets the current line, or the active
region as a line range.  In Dired it targets the entry at point, or
the directory itself."
  (interactive)
  (let ((ctx (remoto--buffer-file-context)))
    (remoto--kill-url (remoto--context-url ctx (plist-get ctx :kind)))))

;;;###autoload
(defun remoto-copy-blame-url ()
  "Copy the forge blame URL for the current file and line/region."
  (interactive)
  (let ((ctx (remoto--buffer-file-context)))
    (remoto--require-blob ctx "Blame")
    (remoto--kill-url (remoto--context-url ctx 'blame))))

;;;###autoload
(defun remoto-copy-permalink ()
  "Copy a permalink: the web URL pinned to the current commit SHA.
Resolves the ref to a commit via the forge API so the link keeps
pointing at the same content even after the branch advances."
  (interactive)
  (let* ((ctx (remoto--buffer-file-context))
         (sha (remoto--resolve-commit-sha (plist-get ctx :owner)
                                          (plist-get ctx :repo)
                                          (plist-get ctx :ref))))
    (remoto--kill-url (remoto--context-url ctx (plist-get ctx :kind) sha))))

;;;###autoload
(defun remoto-copy-raw-url ()
  "Copy the raw-content URL for the current file."
  (interactive)
  (let ((ctx (remoto--buffer-file-context)))
    (remoto--require-blob ctx "Raw URL")
    (remoto--kill-url (remoto--context-url ctx 'raw))))

;;;###autoload
(defun remoto-copy-history-url ()
  "Copy the commit-history URL for the current file or directory."
  (interactive)
  (let ((ctx (remoto--buffer-file-context)))
    (remoto--kill-url (remoto--context-url ctx 'history))))

;;;###autoload
(defun remoto-browse-url ()
  "Open the forge web page for the current file or directory in a browser."
  (interactive)
  (let* ((ctx (remoto--buffer-file-context))
         (url (remoto--context-url ctx (plist-get ctx :kind))))
    (browse-url url)
    (message "Browsing: %s" url)))

;;;###autoload
(define-obsolete-function-alias 'remoto-copy-github-url #'remoto-copy-url "1.8.0")

;;;; Repository search

(defvar remoto--search-cache (make-hash-table :test 'equal)
  "Cache: query string -> (TIMESTAMP . RESULTS).
Entries expire after `remoto-search-cache-ttl' seconds.")

(defcustom remoto-debounce-delay 0.3
  "Seconds of idle time before firing an async search request.
Lower values feel more responsive but generate more API calls."
  :type 'number
  :group 'remoto)

(defcustom remoto-min-search-chars 3
  "Minimum characters before searching users or repos.
Prevents premature API requests while typing short prefixes."
  :type 'integer
  :group 'remoto)

(defcustom remoto-repo-cache-ttl 1800
  "Seconds before repo list cache entries expire.
Repo lists change infrequently, so a longer TTL (default 30 min)
avoids repeated fetches during a session."
  :type 'integer
  :group 'remoto)

(defvar remoto--debounce-timer nil
  "Active idle timer for debounced async searches.")

(defvar remoto--debounce-key nil
  "Key identifying the currently pending debounce.
When a new debounce request arrives with the same key, the
existing timer is kept rather than cancelled and rescheduled.
This prevents completion frameworks (vertico, icomplete) from
starving the async fetch by re-calling the completion function
on every `post-command-hook' cycle.")

(defvar remoto--async-generation 0
  "Monotonic counter for invalidating stale async callbacks.
Incremented on each new debounce schedule; callbacks whose
captured generation doesn't match the current value are stale
and skip UI refresh (but still cache their results).")

(defun remoto--search-cache-get (key &optional ttl)
  "Return cached results for KEY if not expired.
TTL overrides `remoto-search-cache-ttl' when provided.
Returns two values via list: (HIT-P RESULTS).  HIT-P is non-nil
when KEY was found and not expired.  RESULTS may be nil for
queries that returned zero results."
  (let ((cache-ttl (or ttl remoto-search-cache-ttl)))
    (if-let* ((entry (gethash key remoto--search-cache))
              (timestamp (car entry))
              (fresh-p (or (zerop cache-ttl)
                           (< (- (float-time) timestamp) cache-ttl))))
        (list t (cdr entry))
      (when entry (remhash key remoto--search-cache))
      '(nil nil))))

(defun remoto--search-cache-put (key results)
  "Store RESULTS for KEY with current timestamp."
  (puthash key (cons (float-time) results) remoto--search-cache)
  results)

(defun remoto--api-async (endpoint callback)
  "Call GitHub REST API ENDPOINT asynchronously via ghub.
CALLBACK receives the parsed JSON response.  Errors are silently
dropped since async callers cannot meaningfully handle them in the
completion context.  Always passes `:host \"api.github.com\"'
explicitly to avoid ghub resolving to the HTML site.
A shared in-flight counter drives the fetch indicator and is
decremented on success, error, and synchronous failure."
  (let* ((resource (concat "/" endpoint))
         (auth (cond (remoto--auth-failed 'none)
                     (remoto--effective-auth remoto--effective-auth)
                     ((stringp remoto-github-auth) remoto-github-auth)
                     (t (when-let* ((token (remoto--find-github-token)))
                          (setq remoto--effective-auth token)
                          token)))))
    (condition-case nil
        (let ((inhibit-message t))
          (remoto--inflight-inc)
          ;; ghub calls :callback as (value headers status req) and retries
          ;; with (value) on `wrong-number-of-arguments'.  Accept the full
          ;; arglist so the retry never fires and the in-flight counter is
          ;; decremented exactly once.  All callers pass a 1-arg callback.
          (ghub-get resource nil
                    :auth auth
                    :reader #'remoto--json-reader
                    :host "api.github.com"
                    :callback (lambda (value &rest _)
                                (remoto--inflight-dec)
                                (funcall callback value))
                    :errorback (lambda (&rest _)
                                 (remoto--inflight-dec)
                                 nil)))
      (error (remoto--inflight-dec) nil))))

(defun remoto--debounce (key fn)
  "Schedule FN after `remoto-debounce-delay' seconds of idle time.
KEY identifies this request; if a timer is already pending for
the same KEY, it is kept as-is (no cancel/reschedule).  A
different KEY cancels the old timer and schedules a new one."
  (unless (and remoto--debounce-timer
               (equal key remoto--debounce-key))
    (when remoto--debounce-timer
      (cancel-timer remoto--debounce-timer))
    (setq remoto--debounce-key key)
    (cl-incf remoto--async-generation)
    (let ((gen remoto--async-generation))
      (setq remoto--debounce-timer
            (run-with-idle-timer
             remoto-debounce-delay nil
             (lambda ()
               (setq remoto--debounce-timer nil
                     remoto--debounce-key nil)
               (when (= gen remoto--async-generation)
                 (funcall fn))))))))

(defun remoto--invalidate-completion-ui ()
  "Void live front-ends' recompute caches in the selected minibuffer.
Emacs has no single API for refreshing an in-progress completion UI,
so poke the popular front-ends explicitly and fall back to
`post-command-hook' for anything else.  Assumes the active minibuffer
window is selected."
  ;; Default cycling cache.
  (when (boundp 'completion-all-sorted-completions)
    (setq completion-all-sorted-completions nil))
  ;; Vertico skips recompute while the input is `equal', so a
  ;; late-arriving fetch is ignored unless its cache is voided.
  ;; `set' avoids a free-variable warning when vertico is absent.
  (when (boundp 'vertico--input)
    (set 'vertico--input t))
  ;; Icomplete/fido and any UI that recomputes on this hook.
  (run-hooks 'post-command-hook)
  ;; The default *Completions* buffer is not live; rebuild it only
  ;; when it is already on screen.
  (when (get-buffer-window "*Completions*" 0)
    (minibuffer-completion-help)))

(defun remoto--refresh-minibuffer-completions ()
  "Refresh the active minibuffer's completion display.
Called from async callbacks after updating the cache, so freshly
cached candidates appear without the user editing the input."
  (run-at-time
   0 nil
   (lambda ()
     (when-let* ((win (active-minibuffer-window)))
       (with-selected-window win
         (remoto--invalidate-completion-ui))))))

(defun remoto--search-query (input)
  "Build a GitHub search query string from INPUT.
When INPUT contains a slash, searches within that owner's repos.
Otherwise searches by repository name."
  (if-let* ((slash-pos (string-search "/" input))
            (owner (substring input 0 slash-pos))
            (repo-part (substring input (1+ slash-pos))))
      (if (string-empty-p repo-part)
          (format "user:%s" owner)
        (format "%s in:name user:%s" repo-part owner))
    (format "%s in:name" input)))

(defun remoto--fetch-branches (owner repo)
  "Fetch branch names for OWNER/REPO, cached per `remoto-search-cache-ttl'."
  (let* ((key (format "%s/%s" owner repo))
         (entry (gethash key remoto--branches-cache))
         (now (float-time)))
    (if (and entry
             (or (zerop remoto-search-cache-ttl)
                 (< (- now (car entry)) remoto-search-cache-ttl)))
        (cdr entry)
      (condition-case nil
          (let* ((endpoint (format "repos/%s/%s/branches" owner repo))
                 (data (remoto--paginated-api endpoint 100))
                 (branches (mapcar (lambda (item) (alist-get 'name item)) data)))
            (puthash key (cons now branches) remoto--branches-cache)
            branches)
        (user-error nil)))))

(defvar remoto--tags-cache (make-hash-table :test 'equal)
  "Cache for repository tags.  key -> (TIMESTAMP . TAGS-LIST).")

(defun remoto--fetch-tags (owner repo)
  "Fetch tag names for OWNER/REPO, cached per `remoto-search-cache-ttl'."
  (let* ((key (format "%s/%s" owner repo))
         (entry (gethash key remoto--tags-cache))
         (now (float-time)))
    (if (and entry
             (or (zerop remoto-search-cache-ttl)
                 (< (- now (car entry)) remoto-search-cache-ttl)))
        (cdr entry)
      (condition-case nil
          (let* ((endpoint (format "repos/%s/%s/tags" owner repo))
                 (data (remoto--paginated-api endpoint 100))
                 (tags (mapcar (lambda (item) (alist-get 'name item)) data)))
            (puthash key (cons now tags) remoto--tags-cache)
            tags)
        (user-error nil)))))

(defvar remoto--issues-cache (make-hash-table :test 'equal)
  "Cache for issue listings.  key -> (TIMESTAMP . ISSUES-ALIST).")

(defun remoto--fetch-issues (owner repo)
  "Fetch open issues+PRs for OWNER/REPO, cached."
  (let* ((key (format "%s/%s" owner repo))
         (entry (gethash key remoto--issues-cache))
         (now (float-time)))
    (if (and entry
             (or (zerop remoto-search-cache-ttl)
                 (< (- now (car entry)) remoto-search-cache-ttl)))
        (cdr entry)
      (condition-case nil
          (let* ((endpoint (format "repos/%s/%s/issues?state=open&sort=updated&per_page=30"
                                   owner repo))
                 (data (remoto--api endpoint)))
            (puthash key (cons now data) remoto--issues-cache)
            data)
        (user-error nil)))))

(defun remoto--search-issues (owner repo query)
  "Search issues+PRs in OWNER/REPO matching QUERY."
  (condition-case nil
      (let* ((endpoint (format "search/issues?q=%s+repo:%s/%s&per_page=30"
                               (url-hexify-string query) owner repo))
             (data (remoto--api endpoint)))
        (alist-get 'items data))
    (user-error nil)))

(defun remoto--fetch-issue (owner repo number)
  "Fetch single issue NUMBER from OWNER/REPO."
  (condition-case nil
      (remoto--api (format "repos/%s/%s/issues/%s" owner repo number))
    (user-error nil)))

(defun remoto--fetch-issue-comments (owner repo number)
  "Fetch comments for issue NUMBER from OWNER/REPO.
Returns list of comment alists, or nil on error."
  (condition-case nil
      (remoto--api (format "repos/%s/%s/issues/%s/comments" owner repo number))
    (user-error nil)))

(defvar remoto--file-commits-cache (make-hash-table :test 'equal)
  "Cache for per-file last commit messages.
Key: \"owner/repo@ref:dir\", Value: (TIMESTAMP . ALIST).
ALIST maps filename -> first line of commit message.")

(defun remoto--fetch-file-commits (owner repo ref dir-path children)
  "Fetch last commit message for each file in CHILDREN.
DIR-PATH is the directory path within OWNER/REPO at REF.
CHILDREN is a list of filenames.  Returns alist of (name . msg).
Cached per `remoto-search-cache-ttl'.  Capped at 20 API calls."
  (let* ((key (format "%s/%s@%s:%s" owner repo ref dir-path))
         (entry (gethash key remoto--file-commits-cache))
         (now (float-time)))
    (if (and entry
             (or (zerop remoto-search-cache-ttl)
                 (< (- now (car entry)) remoto-search-cache-ttl)))
        (cdr entry)
      (condition-case nil
          (let ((result nil))
            (dolist (child (seq-take children 20))
              (let* ((bare-name (string-trim-right child "/"))
                     (file-path (if (string-empty-p dir-path)
                                    bare-name
                                  (concat dir-path "/" bare-name)))
                     (endpoint (format "repos/%s/%s/commits?sha=%s&path=%s&per_page=1"
                                       owner repo
                                       (url-hexify-string ref)
                                       (url-hexify-string file-path)))
                     (commits (remoto--api endpoint)))
                (when-let* ((first (car commits))
                            (c (alist-get 'commit first))
                            (raw (alist-get 'message c))
                            (msg (car (split-string raw "\n" t))))
                  (push (cons child msg) result))))
            (puthash key (cons now result) remoto--file-commits-cache)
            result)
        (error nil)))))

(defun remoto--fetch-user-orgs (_user)
  "Fetch organization memberships for the authenticated user.
Uses /user/orgs which includes private memberships.
Returns propertized login strings with type and description."
  (condition-case nil
      (let ((data (remoto--paginated-api "user/orgs" 100)))
        (mapcar (lambda (item)
                  (propertize (alist-get 'login item)
                              'remoto-acct-type "Organization"
                              'remoto-acct-desc
                              (or (alist-get 'description item) "")))
                data))
    (user-error nil)))



(defun remoto--search-users (prefix)
  "Search GitHub users/orgs matching PREFIX, never blocking.
Returns cached or locally-narrowed results immediately.  On cache
miss, schedules a debounced async fetch and returns nil; the
completion UI refreshes when results arrive.
Requires at least `remoto-min-search-chars' characters."
  (when-let* (((<= remoto-min-search-chars (length prefix)))
              (prefix-down (downcase prefix)))
    ;; Check exact cache hit
    (pcase-let ((`(,hit ,results) (remoto--search-cache-get
                                    (concat "\0users:" prefix-down))))
      (if hit results
        ;; Try narrowing from a shorter cached query
        (let ((narrowed
               (cl-loop for key being the hash-keys of remoto--users-cache
                        for entry = (gethash key remoto--users-cache)
                        when (and entry
                                  (string-prefix-p key prefix-down)
                                  (< (length key) (length prefix-down))
                                  (or (zerop remoto-search-cache-ttl)
                                      (< (- (float-time) (car entry))
                                         remoto-search-cache-ttl)))
                        return (seq-filter
                                (lambda (u)
                                  (string-prefix-p prefix-down (downcase u)))
                                (cdr entry)))))
          (if narrowed
              (progn
                (puthash (concat "\0users:" prefix-down)
                         (cons (float-time) narrowed)
                         remoto--search-cache)
                narrowed)
            ;; Schedule async fetch instead of blocking
            (remoto--debounce
             (concat "\0users:" prefix-down)
             (lambda ()
               (remoto--api-async
                (format "search/users?q=%s&per_page=30"
                        (url-hexify-string prefix))
                (lambda (data)
                  (let* ((items (alist-get 'items data))
                         (results (mapcar (lambda (item)
                                           (propertize
                                            (alist-get 'login item)
                                            'remoto-acct-type
                                            (or (alist-get 'type item) "")))
                                         items)))
                    (puthash prefix-down (cons (float-time) results)
                             remoto--users-cache)
                    (puthash (concat "\0users:" prefix-down)
                             (cons (float-time) results)
                             remoto--search-cache)
                    (remoto--refresh-minibuffer-completions))))))
            nil))))))

(defvar remoto--prefetch-timer nil
  "Idle timer for speculative repo pre-fetching.")

(defun remoto--prefetch-owner-repos (owner)
  "Pre-fetch recent repos for OWNER asynchronously.
Cancels any previously scheduled pre-fetch.  Uses the async API
so it never blocks typing."
  (when remoto--prefetch-timer
    (cancel-timer remoto--prefetch-timer))
  (let ((cache-key (format "\0repos-recent:%s" (downcase owner))))
    (setq remoto--prefetch-timer
          (run-with-idle-timer
           0.001 nil
           (lambda ()
             (setq remoto--prefetch-timer nil)
             (let ((q (url-hexify-string (format "user:%s" owner))))
               (remoto--api-async
                (format "search/repositories?q=%s&sort=updated&per_page=30" q)
                (lambda (data)
                  (let ((repos (mapcar
                                (lambda (item)
                                  (propertize (alist-get 'name item)
                                              'remoto-repo-desc
                                              (or (alist-get 'description item) "")))
                                (alist-get 'items data))))
                    (remoto--search-cache-put cache-key repos))))))))))

(defun remoto--recent-owner-repos (owner)
  "Return cached recent repos for OWNER, scheduling async refresh.
Uses `remoto-repo-cache-ttl' for longer caching.  Returns cached
results immediately (may be nil on first access); an async fetch
updates the cache and refreshes the completion UI."
  (let* ((cache-key (format "\0repos-recent:%s" (downcase owner))))
    (pcase-let ((`(,hit ,results) (remoto--search-cache-get
                                    cache-key remoto-repo-cache-ttl)))
      (if hit
          ;; Cache hit - return immediately, schedule background refresh
          ;; if cache is older than the short TTL (stale but usable)
          (let ((entry (gethash cache-key remoto--search-cache)))
            (when (and entry
                       (< remoto-search-cache-ttl (- (float-time) (car entry))))
              (remoto--async-refresh-recent-repos owner cache-key))
            results)
        ;; Cache miss - schedule async fetch, return nil
        (remoto--async-refresh-recent-repos owner cache-key)
        nil))))

(defun remoto--extract-search-repos (data &optional name-key)
  "Extract propertized repo names from GitHub search DATA.
NAME-KEY selects the JSON field for the repo name (default `name')."
  (mapcar (lambda (item)
            (propertize (alist-get (or name-key 'name) item)
                        'remoto-repo-desc
                        (or (alist-get 'description item) "")))
          (alist-get 'items data)))

(defun remoto--async-refresh-recent-repos (owner cache-key)
  "Fire async fetch of OWNER's recent repos, updating CACHE-KEY."
  (remoto--debounce
   cache-key
   (lambda ()
     (let ((q (url-hexify-string (format "user:%s" owner))))
       (remoto--api-async
        (format "search/repositories?q=%s&sort=updated&per_page=30" q)
        (lambda (data)
          (let ((repos (remoto--extract-search-repos data)))
            (remoto--search-cache-put cache-key repos)
            (remoto--refresh-minibuffer-completions))))))))

(defun remoto--search-owner-repos (owner query)
  "Search OWNER's repos matching QUERY, never blocking.
Returns cached or locally-narrowed results immediately.  On cache
miss, schedules a debounced async fetch and returns nil.
Requires at least `remoto-min-search-chars' characters in QUERY.
Also narrows from the recent-repos cache when available."
  (if (< (length query) remoto-min-search-chars)
      ;; Below threshold: try narrowing from the recent-repos cache
      (when-let* ((recent-key (format "\0repos-recent:%s" (downcase owner)))
                  (entry (gethash recent-key remoto--search-cache))
                  ((or (zerop remoto-repo-cache-ttl)
                       (< (- (float-time) (car entry)) remoto-repo-cache-ttl))))
        (seq-filter (lambda (r) (string-search (downcase query) (downcase r)))
                    (cdr entry)))
    (let* ((owner-down (downcase owner))
         (query-down (downcase query))
         (cache-key (format "\0repos:%s/%s" owner-down query-down)))
    (pcase-let ((`(,hit ,results) (remoto--search-cache-get cache-key)))
      (if hit results
        ;; Try narrowing from a shorter search query cache (reliable)
        (let ((search-narrowed
               (cl-loop for len from (1- (length query-down)) downto 1
                        for prefix = (substring query-down 0 len)
                        for pk = (format "\0repos:%s/%s" owner-down prefix)
                        for entry = (gethash pk remoto--search-cache)
                        when (and entry
                                  (or (zerop remoto-search-cache-ttl)
                                      (< (- (float-time) (car entry))
                                         remoto-search-cache-ttl)))
                        return (seq-filter
                                (lambda (r)
                                  (string-search query-down (downcase r)))
                                (cdr entry)))))
          (if search-narrowed
              ;; Narrowed from a real search result - reliable, cache it
              (remoto--search-cache-put cache-key search-narrowed)
            ;; No search cache to narrow from. Show preview from
            ;; recent-repos (if any) but always schedule the real
            ;; search since recent-repos is only 30 items.
            (let ((preview
                   (when-let* ((recent-key (format "\0repos-recent:%s" owner-down))
                               (entry (gethash recent-key remoto--search-cache))
                               ((or (zerop remoto-repo-cache-ttl)
                                    (< (- (float-time) (car entry))
                                       remoto-repo-cache-ttl))))
                     (seq-filter (lambda (r)
                                   (string-search query-down (downcase r)))
                                 (cdr entry)))))
              ;; Always schedule async search for full results
              (remoto--debounce
               cache-key
               (lambda ()
                 (let ((q (url-hexify-string
                           (format "%s in:name user:%s" query owner))))
                   (remoto--api-async
                    (format "search/repositories?q=%s&per_page=100" q)
                    (lambda (data)
                      (let ((repos (remoto--extract-search-repos data)))
                        (remoto--search-cache-put cache-key repos)
                        (remoto--refresh-minibuffer-completions)))))))
              ;; Return preview immediately (may be nil)
              preview))))))))

(defun remoto--recent-owner-repos-sync (owner)
  "Synchronously fetch recent repos for OWNER, caching the result.
Intended for use inside `while-no-input' as a fallback when the
async path returned nil on a cold cache."
  (condition-case nil
      (let* ((cache-key (format "\0repos-recent:%s" (downcase owner)))
             (q (url-hexify-string (format "user:%s" owner)))
             (data (remoto--api
                    (format "search/repositories?q=%s&sort=updated&per_page=30"
                            q))))
        (when data
          (let ((repos (remoto--extract-search-repos data)))
            (remoto--search-cache-put cache-key repos)
            repos)))
    (error nil)))

(defun remoto--search-owner-repos-sync (owner query)
  "Synchronously search OWNER's repos matching QUERY, caching the result.
Intended for use inside `while-no-input' as a fallback when the
async path returned nil on a cold cache."
  (condition-case nil
      (let* ((owner-down (downcase owner))
             (query-down (downcase query))
             (cache-key (format "\0repos:%s/%s" owner-down query-down))
             (q (url-hexify-string
                 (format "%s in:name user:%s" query owner)))
             (data (remoto--api
                    (format "search/repositories?q=%s&per_page=100" q))))
        (when data
          (let ((repos (remoto--extract-search-repos data)))
            (remoto--search-cache-put cache-key repos)
            repos)))
    (error nil)))

(defun remoto--get-authenticated-user ()
  "Return the GitHub login of the authenticated user, or nil.
Caches the result for the session.  Returns nil when auth has
failed or the API call errors."
  (or remoto--authenticated-user
      (unless remoto--auth-failed
        (condition-case nil
            (when-let* ((data (remoto--api "user"))
                        (login (alist-get 'login data)))
              (setq remoto--authenticated-user login))
          (user-error nil)))))

(defun remoto--complete-branches (query at-pos)
  "Complete branch names for QUERY with @ at AT-POS.
Returns owner/repo@branch candidates matching the prefix after @."
  (let* ((repo-part (substring query 0 at-pos))
         (branch-prefix (substring query (1+ at-pos))))
    (when (string-match
           (rx bos (group (+ (not "/"))) "/" (group (+ nonl)) eos)
           repo-part)
      (when-let* ((branches (remoto--fetch-branches
                             (match-string 1 repo-part)
                             (match-string 2 repo-part))))
        (thread-last branches
          (seq-filter (lambda (b)
                        (or (string-empty-p branch-prefix)
                            (string-prefix-p branch-prefix b))))
          (mapcar (lambda (b) (format "%s@%s" repo-part b))))))))

(defun remoto--qualify-repos (owner names)
  "Prefix each bare repo NAME in NAMES with OWNER/, preserving properties.
The shared owner-repo search returns bare repo names; `remoto-browse'
presents them as OWNER/REPO while keeping the `remoto-repo-desc' text
property used for annotations."
  (mapcar (lambda (name)
            (apply #'propertize (concat owner "/" name)
                   (text-properties-at 0 name)))
          names))

(defun remoto--search-repos-by-name (query)
  "Search repositories by name for a plain, ownerless QUERY.
Returns owner/repo strings.  On cache miss schedules a debounced
async fetch and returns nil; the UI refreshes when results arrive.
Requires at least `remoto-min-search-chars' characters."
  (when (<= remoto-min-search-chars (length query))
    (pcase-let ((`(,hit ,results) (remoto--search-cache-get query)))
      (if hit
          results
        (remoto--debounce
         (concat "\0browse:" query)
         (lambda ()
           (remoto--api-async
            (format "search/repositories?q=%s&per_page=100"
                    (url-hexify-string (remoto--search-query query)))
            (lambda (data)
              (let ((results (remoto--extract-search-repos data 'full_name)))
                (remoto--search-cache-put query results)
                (remoto--refresh-minibuffer-completions))))))
        nil))))

(defun remoto--search-repos-fetch (query)
  "Return repo candidates for QUERY as owner/repo strings, never blocking.
An OWNER/REPO-prefix query is delegated to the shared
`remoto--search-owner-repos' engine (the same code path the
`/github:' file-name completion uses), so results stay correct and
consistent across both entry points; its bare repo names are
reformatted to OWNER/REPO.  An OWNER/ query (no repo part) lists the
owner's recent repos.  A plain query searches repositories by name."
  (let ((slash-pos (string-search "/" query)))
    (cond
     ((null slash-pos) (remoto--search-repos-by-name query))
     ((zerop slash-pos) nil)
     (t (let ((owner (substring query 0 slash-pos))
              (repo-q (substring query (1+ slash-pos))))
          (remoto--qualify-repos
           owner
           (if (string-empty-p repo-q)
               (remoto--recent-owner-repos owner)
             (remoto--search-owner-repos owner repo-q))))))))

(defun remoto--search-repos (query &optional callback)
  "Search GitHub repositories matching QUERY.
Returns a list of owner/repo strings.  Requires at least 3 characters.
When QUERY contains `@', completes branch names for the specified repo.

When CALLBACK is non-nil, passes results to it instead of returning
them directly.  This supports consult's async dynamic collection
protocol."
  (let* ((at-pos (string-search "@" query))
         (results (if at-pos
                      (remoto--complete-branches query at-pos)
                    (remoto--search-repos-fetch query))))
    (if callback
        (funcall callback results)
      results)))

(defvar remoto--browse-history nil
  "Minibuffer history for `remoto-browse'.")

(defun remoto--browse-parse-input (string)
  "Parse STRING from `remoto-browse' into (MODE OWNER REPO QUERY).
MODE is one of `search', `branches', `issues'.
OWNER+REPO are non-nil for @ and # modes.
QUERY is the text after the delimiter."
  (cond
   ;; owner/repo#query - issues mode
   ((string-match (rx bos (group (+ (not (in "/@#"))))
                      "/" (group (+ (not (in "/@#"))))
                      "#" (group (* anything)) eos)
                  string)
    (list 'issues (match-string 1 string)
          (match-string 2 string) (match-string 3 string)))
   ;; owner/repo@query - branches mode
   ((string-match (rx bos (group (+ (not (in "/@#"))))
                      "/" (group (+ (not (in "/@#"))))
                      "@" (group (* anything)) eos)
                  string)
    (list 'branches (match-string 1 string)
          (match-string 2 string) (match-string 3 string)))
   ;; owner/repo/[subpath] - files mode
   ((string-match (rx bos (group (+ (not (in "/@#"))))
                      "/" (group (+ (not (in "/@#"))))
                      "/" (group (* anything)) eos)
                  string)
    (list 'files (match-string 1 string)
          (match-string 2 string) (match-string 3 string)))
   ;; plain search
   (t (list 'search nil nil string))))

(defun remoto--browse-completions (string)
  "Return completion candidates for STRING in `remoto-browse'.
Handles search, branch, and issue modes."
  (pcase-let ((`(,mode ,owner ,repo ,query) (remoto--browse-parse-input string)))
    (pcase mode
      ('issues
       (let* ((prefix (format "%s/%s#" owner repo))
              (issues
               (cond
                ((string-empty-p query)
                 (while-no-input (remoto--fetch-issues owner repo)))
                ((string-match-p (rx bos (+ digit) eos) query)
                 (let* ((cached (while-no-input
                                  (remoto--fetch-issues owner repo)))
                        (direct (while-no-input
                                  (remoto--fetch-issue owner repo query)))
                        (results (if (listp cached) cached nil)))
                   (if direct
                       (cl-remove-duplicates
                        (cons direct results)
                        :key (lambda (i) (alist-get 'number i)))
                     results)))
                (t (while-no-input
                     (remoto--search-issues owner repo query))))))
         (when (listp issues)
           (let ((candidates
                  (mapcar (lambda (i)
                            (let* ((num (number-to-string (alist-get 'number i)))
                                   (is-pr (and (alist-get 'pull_request i) t))
                                   (title (or (alist-get 'title i) ""))
                                   (state (or (alist-get 'state i) "")))
                              (propertize (concat prefix num)
                                          'remoto-topic-pr is-pr
                                          'remoto-topic-title title
                                          'remoto-topic-state state
                                          'remoto-target
                                          (format "/github:%s/%s#%s"
                                                  owner repo num))))
                          issues)))
             (sort candidates
                   (lambda (a b)
                     (let ((a-pr (get-text-property 0 'remoto-topic-pr a))
                           (b-pr (get-text-property 0 'remoto-topic-pr b)))
                       (cond
                        ((and a-pr (not b-pr)) t)
                        ((and (not a-pr) b-pr) nil)
                        (t (> (string-to-number (replace-regexp-in-string ".*#" "" a))
                              (string-to-number (replace-regexp-in-string ".*#" "" b))))))))))))
      ('branches
       (let* ((prefix (format "%s/%s@" owner repo))
              (branches (while-no-input
                          (remoto--fetch-branches owner repo)))
              (tags (while-no-input
                      (remoto--fetch-tags owner repo))))
         (when (or (listp branches) (listp tags))
           (let ((branch-set (when (listp branches)
                               (mapcar (lambda (b)
                                         (propertize (concat prefix b)
                                                     'remoto-ref-type "branch"
                                                     'remoto-target
                                                     (format "/github:%s/%s@%s:/"
                                                             owner repo b)))
                                       branches)))
                 (tag-set (when (listp tags)
                            (mapcar (lambda (tg)
                                      (propertize (concat prefix tg)
                                                  'remoto-ref-type "tag"
                                                  'remoto-target
                                                  (format "/github:%s/%s@%s:/"
                                                          owner repo tg)))
                                    tags))))
             (seq-filter (lambda (r)
                           (or (string-empty-p query)
                               (string-prefix-p query
                                                (replace-regexp-in-string ".*@" "" r))))
                         (append branch-set tag-set))))))
      ('files
       (let* ((prefix (format "%s/%s/" owner repo))
              (branch (while-no-input
                        (remoto--default-branch owner repo))))
         (when (and (stringp branch) (not (equal branch t)))
           (let* ((subpath (if (string-search "/" query)
                               (file-name-directory query)
                             ""))
                  (file-part (if (string-search "/" query)
                                 (file-name-nondirectory query)
                               query))
                  (children (while-no-input
                              (remoto--fetch-dir-children-light
                               owner repo branch subpath)))
                  (names (when (listp children)
                           (mapcar (lambda (child)
                                     (let* ((name (car child))
                                            (dir? (equal "tree"
                                                         (alist-get 'type (cdr child))))
                                            (display (if dir? (concat name "/") name)))
                                       (propertize (concat prefix subpath display)
                                                   'remoto-target
                                                   (format "/github:%s/%s@%s:/%s%s"
                                                           owner repo branch
                                                           subpath display))))
                                   children))))
             (if (string-empty-p file-part)
                 names
               (seq-filter (lambda (n) (string-search file-part n)) names))))))
      ('search
       (mapcar (lambda (cand)
                 (let ((c (copy-sequence cand)))
                   (put-text-property 0 (length c) 'remoto-target
                                      (format "/github:%s:/"
                                              (substring-no-properties c))
                                      c)
                   c))
               (remoto--search-repos query))))))

(defun remoto--browse-metadata (string)
  "Return completion metadata alist for STRING in `remoto-browse'."
  (pcase (car (remoto--browse-parse-input string))
    ('issues
     (let ((group-fn (lambda (candidate transform)
                       (if transform candidate
                         (if (get-text-property 0 'remoto-topic-pr candidate)
                             "Pull Request"
                           "Issue"))))
           (affix-fn (lambda (candidates)
                       (remoto--affixate
                        (mapcar (lambda (c)
                                  (let ((title (or (get-text-property 0 'remoto-topic-title c) ""))
                                        (state (or (get-text-property 0 'remoto-topic-state c) ""))
                                        (is-pr (get-text-property 0 'remoto-topic-pr c)))
                                    (list c
                                          (if is-pr "PR " "   ")
                                          (format "%s [%s]" title state))))
                                candidates)))))
       `(metadata (category . remoto-browse)
                  (group-function . ,group-fn)
                  (affixation-function . ,affix-fn))))
    ('branches
     (let ((group-fn (lambda (candidate transform)
                       (if transform candidate
                         (if (equal "tag" (get-text-property 0 'remoto-ref-type candidate))
                             "Tag"
                           "Branch")))))
       `(metadata (category . remoto-browse)
                  (group-function . ,group-fn))))
    ('files
     '(metadata (category . remoto-browse)))
    ('search
     (let ((affix-fn (lambda (candidates)
                       (remoto--affixate
                        (mapcar (lambda (c)
                                  (let ((desc (or (get-text-property 0 'remoto-repo-desc c) "")))
                                    (list c "" desc)))
                                candidates)))))
       `(metadata (category . remoto-browse)
                  (affixation-function . ,affix-fn))))))

(defun remoto--repo-completion-table (string pred action)
  "Programmed completion table for GitHub repos, branches, and issues.
STRING is the current minibuffer input, PRED a filter predicate,
ACTION the completion action dispatched by `completing-read'.
Detects @ and # delimiters to switch between modes.
Styles that filter by `completion-regexp-list' pass an empty STRING (the
table has no boundaries); the minibuffer then supplies the query, and
`complete-with-action' applies the regexps to the resulting list."
  (cond
   ((eq action 'metadata) (remoto--browse-metadata string))
   ((eq (car-safe action) 'boundaries) nil)
   (t (let ((input (if (string-empty-p string)
                       (or (remoto--minibuffer-input) string)
                     string)))
        (complete-with-action action (remoto--browse-completions input)
                              string pred)))))

(defun remoto--read-repo ()
  "Read a GitHub repo from the minibuffer with search completion.
Type 3+ characters to trigger GitHub search.  Tab completes.
Append @ to complete branches/tags, # to browse issues/PRs.
URLs and owner/repo shorthand can be typed directly."
  (completing-read "GitHub repo: "
                   #'remoto--repo-completion-table
                   nil nil nil
                   'remoto--browse-history))

;;;###autoload
(defun remoto-browse (input)
  "Browse a GitHub repository without cloning.
INPUT can be any GitHub URL, git remote URL, or owner/repo shorthand.
Supports owner/repo#NUM to view issues/PRs and owner/repo@ref for
specific branches/tags.
With interactive use, provides search completion - type 3+ characters
to search GitHub repositories.
Turns on `global-remoto-mode' when it is off: the buffers this command
opens need the file-name handler for as long as they live."
  (interactive (progn (remoto--ensure-global-mode)
                      (list (remoto--read-repo))))
  (remoto--ensure-global-mode)
  ;; A pull request or issue web URL is the topic, not the repository root
  ;; the URL parser would make of it.
  (when-let* ((topic (remoto--parse-topic-url input)))
    (setq input (apply #'format "%s/%s#%s" topic)))
  (remoto--with-fetch-indicator
    (cond
     ;; Issue/PR mode: owner/repo#NUM
     ((string-match (rx bos (group (+ (not (in "/@#"))))
                        "/" (group (+ (not (in "/@#"))))
                        "#" (group (+ digit)) eos)
                    input)
      (let ((owner (match-string 1 input))
            (repo (match-string 2 input))
            (number (match-string 3 input)))
        (remoto--require-topic)
        (remoto-topic-display number (format "/github:%s/%s" owner repo))))
     ;; Files mode: owner/repo/[subpath]
     ((string-match (rx bos (group (+ (not (in "/@#"))))
                        "/" (group (+ (not (in "/@#"))))
                        "/" (group (* anything)) eos)
                    input)
      (let* ((owner (match-string 1 input))
             (repo (match-string 2 input))
             (subpath (match-string 3 input))
             (canonical (remoto--maybe-rewrite
                         (format "/github:%s/%s/%s" owner repo subpath))))
        (if (and (remoto--parse-path canonical)
                 (equal "tree"
                        (alist-get 'type
                                   (remoto--tree-entry
                                    (remoto--parse-path canonical)))))
            (dired canonical)
          (find-file canonical))))
     ;; Branch mode or plain repo
     (t
      (let* ((clean (if (string-match (rx bos (group (+ (not (in "/@#")))
                                                     "/" (+ (not (in "/@#"))))
                                          "@" (group (+ nonl)) eos)
                                      input)
                        (format "%s@%s" (match-string 1 input)
                                (match-string 2 input))
                      input))
             (parsed (remoto--parse-input clean))
             (resolved (remoto--resolve-ref parsed))
             (canonical (remoto--canonical-path resolved)))
        (if (equal "tree"
                   (alist-get 'type (remoto--tree-entry resolved)))
            (dired canonical)
          (find-file canonical)))))))

;;;; GitHub input detection

(defun remoto--github-input-p (input)
  "Return non-nil if INPUT can look like a GitHub URL or shorthand."
  (and (stringp input)
       (string-match-p
        (rx bos
            (or "https://github.com/"
                "git@github.com:"
                (or "github.com/" "/github.com/")))
        input)))

(defun remoto--parse-partial-canonical (input)
  "Parse partial canonical INPUT like /github:OWNER/REPO[@REF].
Returns a `remoto-path' struct or nil."
  (cond
   ((string-match (rx bos "/github:"
                      (group (+ (not (in "/:@#"))))
                      "/"
                      (group (+ (not (in "/:@#"))))
                      (? "@" (group (+ (not (in "/:")))))
                      eos)
                  input)
    (remoto-path-create
     :owner (match-string 1 input)
     :repo (match-string 2 input)
     :ref (match-string 3 input)
     :path "/"))
   ;; Also handle with trailing /
   ((string-match (rx bos "/github:"
                      (group (+ (not (in "/:@#"))))
                      "/"
                      (group (+ (not (in "/:@#"))))
                      (? "@" (group (+ (not (in "/:")))))
                      "/" eos)
                  input)
    (remoto-path-create
     :owner (match-string 1 input)
     :repo (match-string 2 input)
     :ref (match-string 3 input)
     :path "/"))))

(defun remoto--maybe-rewrite (input)
  "If INPUT is a GitHub URL/shorthand, return canonical remoto path.
Also handles partial canonical paths like /github:OWNER/REPO and the
/gh: shorthand prefix.  Otherwise return INPUT unchanged."
  (setq input (remoto--normalize-shorthand input))
  (cond
   ;; Already a full canonical path
   ((remoto--parse-path input) input)
   ;; Files-default short form: /github:owner/repo/ or /github:owner/repo/path
   ((and (string-prefix-p "/github:" input)
         (not (remoto--parse-path input))
         (string-match (rx bos "/github:"
                           (group (+ (not (in "/:@#"))))
                           "/"
                           (group (+ (not (in "/:@#"))))
                           "/" (group (* anything)) eos)
                       input))
    (let* ((owner (match-string 1 input))
           (repo (match-string 2 input))
           (subpath (match-string 3 input))
           (repo-id (format "%s/%s" owner repo))
           (branch (or (gethash repo-id remoto--default-branch-cache)
                       (let ((b (remoto--default-branch owner repo)))
                         (when b (puthash repo-id b remoto--default-branch-cache))
                         b))))
      (if branch
          (format "/github:%s/%s@%s:/%s" owner repo branch subpath)
        input)))
   ;; Partial canonical path: /github:owner/repo or /github:owner/repo@ref
   ((and (string-prefix-p "/github:" input)
         (remoto--parse-partial-canonical input))
    (let* ((parsed (remoto--parse-partial-canonical input))
           (resolved (remoto--resolve-ref parsed)))
      (remoto--canonical-path resolved)))
   ;; GitHub URL or shorthand
   ((remoto--github-input-p input)
    (let* ((clean (replace-regexp-in-string "\\`/?" "" input))
           (clean (cond
                   ((string-match-p "\\`github\\.com/" clean)
                    (concat "https://" clean))
                   (t clean)))
           (parsed (condition-case nil
                       (remoto--parse-input clean)
                     (error nil))))
      (cond
       (parsed
        (let ((resolved (remoto--resolve-ref parsed)))
          (remoto--canonical-path resolved)))
       (t input))))
   (t input)))

(defun remoto--dired-around-a (orig-fn dir-or-list &rest args)
  "Rewrite GitHub URLs and short remoto paths to canonical paths for Dired.
Call ORIG-FN with DIR-OR-LIST and ARGS after any rewrite.
Advises `dired-noselect' rather than `dired', because `dired',
`dired-other-window' and `dired-other-frame' all go through it, and only
a canonical name gives the buffer its canonical `default-directory'."
  (if-let* ((raw (if (consp dir-or-list) (car dir-or-list) dir-or-list))
            ((stringp raw))
            (dir (remoto--normalize-shorthand raw))
            ((or (remoto--github-input-p dir)
                 (string-prefix-p "/github:" dir))))
      (let ((canonical (remoto--maybe-rewrite dir)))
        (apply orig-fn
               (if (consp dir-or-list)
                   (cons canonical (cdr dir-or-list))
                 canonical)
               args))
    (apply orig-fn dir-or-list args)))

(defun remoto--find-file-around-a (orig-fn filename &rest args)
  "Rewrite GitHub URLs to canonical remoto paths for `find-file'.
Intercepts #NUM patterns to display issues instead of file operations.
Call ORIG-FN with FILENAME and ARGS after any rewrite."
  (setq filename (remoto--normalize-shorthand filename))
  ;; A pull request or issue web URL is the topic, not the repository root
  ;; the URL parser would make of it.
  (when-let* ((topic (remoto--parse-topic-url filename)))
    (setq filename (apply #'format "/github:%s/%s#%s" topic)))
  ;; Check for #NUM BEFORE rewrite (rewrite would mangle the # delimiter)
  (if-let* ((topic (remoto--topic-path filename)))
      (progn
        (remoto--require-topic)
        (remoto-topic-display (cdr topic) (car topic)))
    (apply orig-fn (remoto--maybe-rewrite filename) args)))

;;;; Eager auth warm-up

(defun remoto--find-github-token ()
  "Search auth-source for a GitHub API token.
Different ghub versions and user setups store tokens under different
hosts (api.github.com vs github.com) and package suffixes (^forge,
^ghub).  Try all known combinations to find a working token."
  (when-let* ((username (condition-case nil
                            (ghub--username "github.com" nil)
                          (error nil))))
    (let ((hosts '("api.github.com" "github.com"))
          (packages '("forge" "ghub" nil)))
      (catch 'found
        (dolist (host hosts)
          (dolist (pkg packages)
            (let* ((user (if pkg (format "%s^%s" username pkg) username))
                   (results (condition-case err
                                (auth-source-search :host host :user user :max 1)
                              ;; A broken backend (say, a .authinfo.gpg that
                              ;; does not decrypt) fails the same way for
                              ;; every combination and for every later API
                              ;; call, which would repeat this lookup.  Report
                              ;; it once, go unauthenticated, and leave the
                              ;; retry to `remoto-reset-auth'.
                              (error
                               (setq remoto--auth-failed t)
                               (message "Remoto: auth-source lookup failed (%s); \
using unauthenticated access until M-x remoto-reset-auth"
                                        (error-message-string err))
                               (throw 'found nil))))
                   (secret (plist-get (car results) :secret))
                   (token (if (functionp secret) (funcall secret) secret)))
              (when (and token (not (string-empty-p token)))
                (throw 'found token)))))))))

(defun remoto--warm-auth ()
  "Pre-fetch the authenticated GitHub user in the background.
Runs on an idle timer so GPG decryption happens before the user
types anything.  Bypasses ghub's own token resolution (which may
look up the wrong auth-source host) by searching auth-source
directly and passing the token string to ghub."
  (unless (or remoto--authenticated-user remoto--auth-failed)
    (if-let* ((token (or (and (stringp remoto-github-auth) remoto-github-auth)
                         (remoto--find-github-token))))
        (condition-case err
            (when-let* ((data (let ((inhibit-message t))
                                (ghub-get "/user" nil
                                          :auth token
                                          :host "api.github.com"
                                          :reader #'remoto--json-reader)))
                        (login (alist-get 'login data)))
              (setq remoto--authenticated-user login
                    remoto--effective-auth token)
              (message "Remoto: authenticated as %s" login))
          (error
           (setq remoto--auth-failed t)
           (message "Remoto: token found but API call failed (%s); \
using unauthenticated access"
                    (error-message-string err))))
      ;; No token found yet - don't set auth-failed so remoto--api
      ;; can still try ghub's own auth-source resolution on demand.
      ;; The warm-up is opportunistic; failing here should not lock
      ;; out the session permanently.  A backend failure inside the
      ;; lookup has already set auth-failed and said so.
      (unless remoto--auth-failed
        (message "Remoto: no token found during warm-up; \
will try ghub auth on first API call")))))

(defvar remoto--warm-auth-timer nil
  "Pending idle timer for `remoto--warm-auth', or nil.
Held so turning `global-remoto-mode' off before the timer fires can
cancel it.")

;;;; Minor mode

(defvar remoto-command-map
  (let ((map (make-sparse-keymap)))
    (define-key map "u" #'remoto-copy-url)
    (define-key map "b" #'remoto-copy-blame-url)
    (define-key map "p" #'remoto-copy-permalink)
    (define-key map "r" #'remoto-copy-raw-url)
    (define-key map "h" #'remoto-copy-history-url)
    (define-key map "w" #'remoto-browse-url)
    map)
  "Keymap of remoto URL commands, meant to be bound to a prefix key.

Short mnemonic keys: `u' copy-url, `b' blame, `p' permalink, `r' raw,
`h' history, `w' browse.  It is intentionally bound to no key by
default, so it claims none of the user-reserved \\=`C-c LETTER\\=' space.
Bind it as a unit under a prefix of your choice, e.g.:

  (with-eval-after-load \\='remoto
    (keymap-set remoto-mode-map \"C-c g\" remoto-command-map))")
(defalias 'remoto-command-map remoto-command-map)

(defvar remoto-mode-map (make-sparse-keymap)
  "Keymap for `remoto-mode'.
Empty by default.  Populate it in your configuration, commonly by
binding the variable `remoto-command-map' to a prefix key.")

;;;###autoload
(define-minor-mode remoto-mode
  "Minor mode for buffers backed by a remoto virtual filesystem.

Offers forge-agnostic commands to copy or open the web URL of the file
or directory shown in the current buffer.  The commands work the same in
file buffers and in Dired, and adapt to the forge behind the path (only
GitHub today, but designed for more).

While `global-remoto-mode' is on, `remoto-mode' is enabled automatically
when visiting a remoto path.  Its keymap is empty by default; the
commands are grouped in the variable `remoto-command-map', which you can
bind to a prefix of your choosing."
  :lighter " Remoto"
  :keymap remoto-mode-map)

(defun remoto--maybe-enable-mode ()
  "Enable `remoto-mode' when the current buffer is a remoto buffer.
`global-remoto-mode' runs it from `find-file-hook' and `dired-mode-hook'."
  (let ((file (or buffer-file-name
                  (and (derived-mode-p 'dired-mode)
                       (if (listp dired-directory)
                           (car dired-directory)
                         dired-directory)))))
    (when (and (stringp file)
               (string-match-p remoto--handler-regexp file))
      (remoto-mode 1))))

(defun remoto--get-prop (candidate prop)
  "Get text property PROP from CANDIDATE.
Searches from the end backwards, skipping trailing delimiters.
Handles candidates with prefix prepended by completion framework."
  (let ((len (length candidate)))
    (when (< 0 len)
      ;; Try near end (skip trailing / : characters which lack props)
      (or (and (< 1 len) (get-text-property (- len 2) prop candidate))
          (get-text-property (1- len) prop candidate)
          (get-text-property 0 prop candidate)))))

(defface remoto-annotation
  '((t :inherit completions-annotations))
  "Face for remoto completion annotations.")

(defvar remoto-annotation-width-step 10
  "Round annotation alignment width up to this step size.")

(defun remoto--affixate (items)
  "Format ITEMS as affixation triples with aligned suffixes.
ITEMS is a list of (candidate prefix suffix).
Uses display property for alignment (works in any completion UI)."
  (let* ((max-len (apply #'max 0 (mapcar (lambda (x) (length (car x))) items)))
         (align-to (* (ceiling (/ (float (+ max-len 4))
                                  remoto-annotation-width-step))
                      remoto-annotation-width-step)))
    (mapcar (lambda (x)
              (let* ((c (nth 0 x))
                     (prefix (nth 1 x))
                     (suffix (nth 2 x)))
                (list c prefix
                      (if (string-empty-p suffix) ""
                        (concat (propertize " " 'display
                                            `(space :align-to ,align-to))
                                (propertize suffix 'face 'remoto-annotation))))))
            items)))

(defun remoto--completion-metadata (directory)
  "Return completion metadata alist for DIRECTORY, or nil.
Provides group-function and affixation-function for @ and # modes."
  (cond
   ;; Issues mode: /github:OWNER/REPO#
   ((string-match (rx (+ (not (in "/:@#"))) "/" (+ (not (in "/:@#"))) "#" eos)
                  directory)
    (let ((group-fn (lambda (candidate transform)
                      (if transform candidate
                        (if (remoto--get-prop candidate 'remoto-topic-pr)
                            "Pull Request"
                          "Issue"))))
          (affix-fn (lambda (candidates)
                      (remoto--affixate
                       (mapcar (lambda (c)
                                 (let ((title (or (remoto--get-prop c 'remoto-topic-title) ""))
                                       (state (or (remoto--get-prop c 'remoto-topic-state) ""))
                                       (is-pr (remoto--get-prop c 'remoto-topic-pr)))
                                   (list c
                                         (if is-pr "PR " "   ")
                                         (format "%s [%s]" title state))))
                               candidates)))))
      ;; The candidates come pre-sorted (pull requests first, newest first);
      ;; without these two entries the UI re-sorts them by length or name.
      `((category . remoto-issue)
        (display-sort-function . identity)
        (cycle-sort-function . identity)
        (group-function . ,group-fn)
        (affixation-function . ,affix-fn))))
   ;; Branches/tags mode: /github:OWNER/REPO@
   ((string-match (rx (+ (not (in "/:@#"))) "/" (+ (not (in "/:@#"))) "@" eos)
                  directory)
    (let ((group-fn (lambda (candidate transform)
                      (if transform candidate
                        (if (equal "tag" (remoto--get-prop candidate 'remoto-ref-type))
                            "Tag"
                          "Branch")))))
      `((category . remoto-branch)
        (group-function . ,group-fn))))
   ;; File mode: canonical path or files-default (owner/repo/ with optional subpath)
   ((or (string-match (rx "@" (+ (not (in ":"))) ":" (? "/")) directory)
        (string-match (rx "/github:" (+ (not (in "/:@#"))) "/"
                          (+ (not (in "/:@#"))) "/" (* nonl) eos)
                      directory))
    (let ((affix-fn (lambda (candidates)
                      (remoto--affixate
                       (mapcar (lambda (c)
                                 (let ((msg (or (remoto--get-prop c 'remoto-file-commit) "")))
                                   (list c "" msg)))
                               candidates)))))
      `((category . remoto-file)
        (affixation-function . ,affix-fn))))
   ;; Owner mode: /github:OWNER/ - repo descriptions
   ((string-match (rx "/github:" (+ (not (in "/:@#"))) "/" eos) directory)
    (let ((affix-fn (lambda (candidates)
                      (remoto--affixate
                       (mapcar (lambda (c)
                                 (let ((desc (or (remoto--get-prop c 'remoto-repo-desc) "")))
                                   (list c "" desc)))
                               candidates)))))
      `((category . remoto-repo)
        (affixation-function . ,affix-fn))))
   ;; Root mode: /github: - user/org type
   ((equal directory "/github:")
    (let ((affix-fn (lambda (candidates)
                      (remoto--affixate
                       (mapcar (lambda (c)
                                 (let* ((acct-type (or (remoto--get-prop c 'remoto-acct-type) ""))
                                        (desc (or (remoto--get-prop c 'remoto-acct-desc) ""))
                                        (suffix (cond
                                                 ((not (string-empty-p desc))
                                                  (format "%s  %s" acct-type desc))
                                                 (t acct-type))))
                                   (list c "" suffix)))
                               candidates)))))
      `((category . remoto-owner)
        (affixation-function . ,affix-fn))))))

(defun remoto--read-file-name-internal-a (orig string pred action)
  "Inject remoto completion metadata inside `read-file-name'.
Completion itself is delegated to ORIG so candidates stay relative to the
completion boundary.  Re-basing them to full paths makes frameworks like
Vertico prepend the directory twice (e.g. /github: + /github:owner ->
/github:/github:owner).  Only category/affixation metadata is added, for the
@ (branches/tags), # (issues), and owner/repo levels.  The /gh: shorthand is
already canonicalized by `substitute-in-file-name', so EFFECTIVE is /github:.
Args: ORIG, STRING, PRED, ACTION."
  (let ((effective (substitute-in-file-name string)))
    (if (not (and (eq action 'metadata) (string-prefix-p "/github:" effective)))
        (funcall orig string pred action)
      (let* ((dir (or (file-name-directory effective) ""))
             (extra (remoto--completion-metadata dir))
             (base (funcall orig string pred action))
             (base-alist (and (consp base) (eq (car base) 'metadata) (cdr base))))
        (if extra
            ;; Replace category so Marginalia doesn't override our annotations.
            ;; Use the per-level category from `remoto--completion-metadata' when
            ;; it provides one, else the generic `remoto'.
            (let ((cat (or (alist-get 'category extra) 'remoto)))
              (cons 'metadata (append (assq-delete-all 'category (copy-alist extra))
                                      `((category . ,cat))
                                      (assq-delete-all 'category (copy-alist base-alist)))))
          (or base (cons 'metadata nil)))))))

;;;; Global mode

(defun remoto--drop-autoload-handler ()
  "Remove the bootstrap entry of the autoloads from `file-name-handler-alist'."
  (setq file-name-handler-alist
        (rassq-delete-all #'remoto-autoload-file-name-handler
                          file-name-handler-alist)))

(defun remoto--install ()
  "Install the handler, the advice, the hooks and the auth warm-up timer.
Each step is idempotent, so a second call while on is a no-op."
  ;; The real handler takes over from the bootstrap entry; left behind, that
  ;; entry would catch the operations the real handler passes down.
  (remoto--drop-autoload-handler)
  (unless (equal (cdr (assoc remoto--handler-regexp file-name-handler-alist))
                 #'remoto-file-name-handler)
    (push (cons remoto--handler-regexp #'remoto-file-name-handler)
          file-name-handler-alist))
  (advice-add 'dired-noselect :around #'remoto--dired-around-a)
  (advice-add 'find-file-noselect :around #'remoto--find-file-around-a)
  (advice-add 'read-file-name-internal :around
              #'remoto--read-file-name-internal-a)
  (add-hook 'find-file-hook #'remoto--maybe-enable-mode)
  (add-hook 'dired-mode-hook #'remoto--maybe-enable-mode)
  ;; Clear the fetch indicator and reset in-flight state whenever a
  ;; minibuffer exits.
  (add-hook 'minibuffer-exit-hook #'remoto--minibuffer-exit-cleanup)
  (unless (timerp remoto--warm-auth-timer)
    (setq remoto--warm-auth-timer
          (run-with-idle-timer 2 nil #'remoto--warm-auth))))

(defun remoto--uninstall ()
  "Remove the handler, the advice, the hooks and the auth warm-up timer."
  (setq file-name-handler-alist
        (assoc-delete-all remoto--handler-regexp file-name-handler-alist))
  (advice-remove 'dired-noselect #'remoto--dired-around-a)
  (advice-remove 'find-file-noselect #'remoto--find-file-around-a)
  (advice-remove 'read-file-name-internal #'remoto--read-file-name-internal-a)
  (remove-hook 'find-file-hook #'remoto--maybe-enable-mode)
  (remove-hook 'dired-mode-hook #'remoto--maybe-enable-mode)
  (remove-hook 'minibuffer-exit-hook #'remoto--minibuffer-exit-cleanup)
  (when (timerp remoto--warm-auth-timer)
    (cancel-timer remoto--warm-auth-timer))
  (setq remoto--warm-auth-timer nil))

;;;###autoload
(define-minor-mode global-remoto-mode
  "Toggle remoto's virtual filesystem for GitHub repositories.

When on, `/github:OWNER/REPO...' and `/gh:...' paths work in `find-file',
`dired', and every other file operation, GitHub URLs typed at those
prompts are rewritten to remoto paths, `find-file' completion inside a
remoto path shows remoto's annotations, `remoto-mode' turns on in remoto
buffers, and a GitHub token is looked up once Emacs is idle.  When off,
all of that is removed again.

Loading remoto does not turn this mode on.  Enable it in your init file,
or let the first use do it: `remoto-browse', the Embark open actions,
and a `/github:' or `/gh:' path at any file prompt all turn it on."
  :global t
  :group 'remoto
  (if global-remoto-mode
      (remoto--install)
    (remoto--uninstall)))

(defun remoto--ensure-global-mode ()
  "Turn on `global-remoto-mode' when it is off, and say so.
For remoto's own entry points: the buffers they open need the
file-name handler for as long as they live, so the mode has to stay on."
  (unless global-remoto-mode
    (global-remoto-mode 1)
    (message "Remoto: `global-remoto-mode' enabled")))

;;;###autoload
(defun remoto-autoload-file-name-handler (operation &rest args)
  "Turn on `global-remoto-mode' for the first remoto path, then run OPERATION.
ARGS are the arguments of OPERATION.  The package autoloads register
this handler in `file-name-handler-alist', so a `/github:' or `/gh:'
path typed at a file prompt works before remoto is loaded, the way a
remote path loads TRAMP.  Calling it loads remoto; it then leaves the
alist for good, and `remoto--install' puts the real handler in front.

The call that brings remoto in runs without the advice `remoto--install'
adds, because the advice arrives while that call is already under way.
`expand-file-name' is what `find-file-noselect' asks first, and what it
gets back is the name it visits, so canonicalizing here gives that one
call the rewrite the advice would have given it.  A file prompt asks
`substitute-in-file-name' first instead, and a prompt is still being
typed into, so it is left alone."
  (remoto--drop-autoload-handler)
  (remoto--ensure-global-mode)
  (when (and (eq operation 'expand-file-name) (stringp (car args)))
    (setcar args (remoto--maybe-rewrite (car args))))
  (apply operation args))

;;;###autoload (add-to-list 'file-name-handler-alist '("\\`/\\(?:github\\|gh\\):" . remoto-autoload-file-name-handler))

;;;; Issue display (see remoto-topic.el for full implementation)

(declare-function remoto-topic-display "remoto-topic" (number repo-path))

(defun remoto--require-topic ()
  "Load remoto-topic if not already loaded.
Adds the package directory to `load-path' if needed."
  (unless (featurep 'remoto-topic)
    (when-let* ((dir (file-name-directory
                      (or load-file-name
                          (locate-library "remoto")
                          buffer-file-name))))
      (add-to-list 'load-path dir))
    (require 'remoto-topic)))

;;;; Unload

(defun remoto-unload-function ()
  "Turn `global-remoto-mode' off and drop the caches.
The bootstrap entry of the autoloads goes too: it is still there when
remoto was loaded some other way and the mode never turned on."
  (when global-remoto-mode
    (global-remoto-mode -1))
  (remoto--drop-autoload-handler)
  (clrhash remoto--tree-cache)
  (clrhash remoto--default-branch-cache)
  (clrhash remoto--branches-cache)
  (clrhash remoto--users-cache)
  (clrhash remoto--content-cache)
  (clrhash remoto--search-cache)
  (clrhash remoto--tags-cache)
  (clrhash remoto--issues-cache)
  (clrhash remoto--file-commits-cache)
  (clrhash remoto--dir-contents-cache)
  (clrhash remoto--pending-requests)
  nil)

(provide 'remoto)
;;; remoto.el ends here