libra mega2 browser

Browse one directory level of a remote Mega2 repository over HTTP — either interactively in the terminal or as a single machine-readable listing for scripts and agents.

mega2 is a Libra-only extension with no Git-equivalent contract: it never clones, fetches or pushes Git objects, and it lists remote metadata rather than local tree objects. For local object inspection use libra ls-tree.

Synopsis

libra mega2 browser --server <BASE-URL> [PATH] [--ref <COMMIT-OR-TAG>] [--json|--machine]

Description

All inputs are validated before the terminal or the network is touched:

• --server must be https://…, or http://… only for a loopback host (127.0.0.1, ::1, localhost). Credentials (userinfo), query strings, fragments and a base path are rejected; the client always appends /api/v1/tree.
• PATH must be rooted (/ by default) and may not contain ./.. components, NUL, control characters or platform separators.
• --ref selects a commit or tag; when omitted the server default revision is used.

Browsing sends exactly one anonymous GET /api/v1/tree per navigation or reload. No Authorization header is attached, no repository is opened (the command works outside a repository), and no local state — index, object store, database, configuration — is read or written.

The client is bounded: redirects and proxies are disabled, the timeout is 10 seconds, the response body is capped at 1 MiB and the listing at 2000 entries, and only directory/file content types are accepted. Names containing .., path separators or terminal control characters are refused fail-closed, and the server-provided item path is never used as navigation authority.

Interactive mode (default)

Interactive mode requires stdin and stdout to be terminals. If either is not a TTY the command refuses immediately with a stable error and a hint to use --json; it never alters the terminal first.

Key	Action
↑/↓ or k/j	Move the selection
Enter	Open the selected directory (one fetch of the child path)
Backspace or h	Go to the parent directory (never above /)
r	Reload the current listing
q (or Ctrl-C, Esc)	Quit

Raw mode and the alternate screen are restored on every exit path, including errors.

Machine mode (--json / --machine)

With --json (or --machine, which implies --json=ndjson --no-pager --color=never --quiet) the command performs exactly one fetch and prints the standard Libra JSON envelope:

{
  "ok": true,
  "command": "mega2 browser",
  "data": {
    "server": "https://mega2.example.com",
    "ref": "v1.2",
    "path": "/src",
    "items": [
      { "name": "pkg", "content_type": "directory" },
      { "name": "main.rs", "content_type": "file" }
    ]
  }
}

items is deterministic: directories first, then names in ascending order. server is the canonical scheme/host/port origin of the validated URL.

Options

Option	Description
--server <BASE-URL>	Mega2 server base URL (required). HTTPS, or loopback HTTP.
[PATH]	Rooted directory path to list; defaults to /.
--ref <COMMIT-OR-TAG>	Optional commit or tag to list.
--json[=<FORMAT>]	Global flag: one fetch, JSON envelope (pretty/compact/ndjson).
--machine	Global flag: strict NDJSON machine mode.

Security and limits

• Read-only and anonymous: browse never sends credentials, and nothing is persisted to disk (no config, no token, no cache across processes).
• Exactly one request per navigation/reload; no recursion, prefetch or background work.
• Errors never echo server response bodies, credentials, tokens or unvalidated paths; refused redirects, schema mismatches and hostile names fail closed.

Examples

# Browse the remote root interactively
libra mega2 browser --server https://mega2.example.com

# Open a rooted path directly
libra mega2 browser --server https://mega2.example.com src/pkg

# List a specific commit or tag
libra mega2 browser --server https://mega2.example.com --ref v1.2

# Exactly one fetch, JSON envelope (works without a TTY, outside any repository)
libra --json mega2 browser --server https://mega2.example.com

# NDJSON for automation
libra --machine mega2 browser --server http://127.0.0.1:8080