flyfile 0.1.0__py3-none-any.whl

flyfile/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

flyfile/cli/main.py

@@ -0,0 +1,407 @@
+"""flyfile CLI — agent-friendly：JSON 输出、稳定退出码、绝不交互挂起。"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from flyfile import __version__
+from flyfile.client.client import FlyfileClient
+from flyfile.client.errors import EXIT_USAGE, FlyfileError
+from flyfile.cli import output as out
+
+app = typer.Typer(
+    name="flyfile",
+    help="Agent-native data transfer: push/pull/send anything.",
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_enable=False,
+)
+config_app = typer.Typer(help="Manage ~/.flyfile/config.yaml")
+app.add_typer(config_app, name="config")
+
+CONFIG_PATH = Path("~/.flyfile/config.yaml").expanduser()
+
+_DUR = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+
+def parse_duration(text: Optional[str]) -> Optional[int]:
+    if not text:
+        return None
+    m = re.fullmatch(r"(\d+)([smhd])", text)
+    if not m:
+        raise FlyfileError(EXIT_USAGE, "usage",
+                           f"invalid duration '{text}', expected e.g. 30s / 10m / 2h / 7d")
+    return int(m.group(1)) * _DUR[m.group(2)]
+
+
+def load_config() -> dict:
+    if not CONFIG_PATH.exists():
+        return {}
+    import yaml
+    return yaml.safe_load(CONFIG_PATH.read_text()) or {}
+
+
+def get_client(server: Optional[str], token: Optional[str]) -> FlyfileClient:
+    cfg = load_config()
+    server = server or os.environ.get("FLYFILE_SERVER") or cfg.get("server")
+    token = token or os.environ.get("FLYFILE_TOKEN") or cfg.get("token", "")
+    if not server:
+        raise FlyfileError(EXIT_USAGE, "usage", "no server configured",
+                           suggestion="set FLYFILE_SERVER, or run: flyfile config set server http://host:18632")
+    return FlyfileClient(server, token)
+
+
+def run(fn, json_flag: bool):
+    """统一执行入口：错误 → JSON 错误体 + 契约退出码。"""
+    json_mode = out.is_json_mode(json_flag)
+    try:
+        result = fn()
+        if result is not None:
+            out.emit(result, json_mode)
+    except FlyfileError as e:
+        print(json.dumps(e.to_json(), ensure_ascii=False), file=sys.stderr)
+        raise typer.Exit(e.exit_code)
+    except (BrokenPipeError, KeyboardInterrupt):
+        raise typer.Exit(1)
+
+
+ServerOpt = typer.Option(None, "--server", help="Server URL (env: FLYFILE_SERVER)")
+TokenOpt = typer.Option(None, "--token", help="Auth token (env: FLYFILE_TOKEN)")
+JsonOpt = typer.Option(False, "--json", help="Force JSON output (auto when not a TTY)")
+
+
+@app.command()
+def push(
+    source: str = typer.Argument(..., help="File, directory, or '-' for stdin"),
+    name: Optional[str] = typer.Option(None, help="Object name (default: filename)"),
+    tag: list[str] = typer.Option([], "--tag", help="Tag, repeatable"),
+    description: Optional[str] = typer.Option(None),
+    ttl: Optional[str] = typer.Option(None, help="Expiry: 30s / 10m / 2h / 7d (default: keep forever)"),
+    reads: Optional[int] = typer.Option(None, help="Burn after N reads"),
+    no_compress: bool = typer.Option(False, "--no-compress"),
+    content_type: Optional[str] = typer.Option(None),
+    server: Optional[str] = ServerOpt,
+    token: Optional[str] = TokenOpt,
+    json_flag: bool = JsonOpt,
+):
+    """Upload a file/dir/stdin to the server. Idempotent (content-addressed dedup)."""
+    def go():
+        client = get_client(server, token)
+        try:
+            prog = out.progress_printer("push")
+            obj = client.push(source, name, tag, description, parse_duration(ttl),
+                              reads, no_compress, content_type, progress=prog)
+            if prog:
+                sys.stderr.write("\r\x1b[K")  # 清掉流式路径（总量未知）残留的进度行
+            if out.is_json_mode(json_flag):
+                return obj
+            dedup = " (deduped)" if obj.get("deduped") else ""
+            print(f"pushed {obj['name']}  id={obj['id']}  {out.fmt_size(obj['size'])}{dedup}")
+            return None
+        finally:
+            client.close()
+    run(go, json_flag)
+
+
+@app.command()
+def pull(
+    ref: str = typer.Argument(..., metavar="ID_OR_NAME",
+                              help="Object id, or name (glob ok) resolved via query"),
+    output: Optional[str] = typer.Option(None, "-o", "--output",
+                                         help="Destination path, '-' for stdout (text defaults to stdout)"),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing destination"),
+    latest: bool = typer.Option(False, "--latest",
+                                help="If a name matches multiple objects, take the newest"),
+    server: Optional[str] = ServerOpt,
+    token: Optional[str] = TokenOpt,
+    json_flag: bool = JsonOpt,
+):
+    """Download an object by id or name. Dirs are extracted, text goes to stdout."""
+    def go():
+        client = get_client(server, token)
+        try:
+            result = client.pull(ref, output, force,
+                                 progress=out.progress_printer("pull"), latest=latest)
+            if result.get("output") == "-":
+                return None
+            if out.is_json_mode(json_flag):
+                return result
+            print(f"{result['name']} -> {result['output']}  {out.fmt_size(result['size'])}")
+            return None
+        finally:
+            client.close()
+    run(go, json_flag)
+
+
+@app.command()
+def ls(
+    name: Optional[str] = typer.Option(None, help="Glob on name, e.g. 'log*'"),
+    tag: list[str] = typer.Option([], "--tag", help="Filter by tag (AND), repeatable"),
+    kind: Optional[str] = typer.Option(None, help="text | file | dir"),
+    since: Optional[str] = typer.Option(None, help="Created within: 2h / 7d"),
+    until: Optional[str] = typer.Option(None, help="Created before: 2h / 7d ago"),
+    limit: int = typer.Option(50),
+    offset: int = typer.Option(0),
+    server: Optional[str] = ServerOpt,
+    token: Optional[str] = TokenOpt,
+    json_flag: bool = JsonOpt,
+):
+    """Query objects by metadata."""
+    def go():
+        client = get_client(server, token)
+        try:
+            now = int(time.time())
+            return client.ls(
+                name=name, tags=tag, kind=kind, limit=limit, offset=offset,
+                created_after=now - parse_duration(since) if since else None,
+                created_before=now - parse_duration(until) if until else None,
+            )
+        finally:
+            client.close()
+    run(go, json_flag)
+
+
+@app.command()
+def info(
+    ref: str = typer.Argument(..., metavar="ID_OR_NAME"),
+    latest: bool = typer.Option(False, "--latest",
+                                help="If a name matches multiple objects, take the newest"),
+    server: Optional[str] = ServerOpt,
+    token: Optional[str] = TokenOpt,
+    json_flag: bool = JsonOpt,
+):
+    """Show object metadata by id or name (does not consume reads)."""
+    def go():
+        client = get_client(server, token)
+        try:
+            return client.resolve(ref, latest)
+        finally:
+            client.close()
+    run(go, json_flag)
+
+
+@app.command()
+def preview(
+    ref: str = typer.Argument(..., metavar="ID_OR_NAME"),
+    nbytes: int = typer.Option(2048, "--bytes", help="Bytes of head to preview"),
+    latest: bool = typer.Option(False, "--latest",
+                                help="If a name matches multiple objects, take the newest"),
+    server: Optional[str] = ServerOpt,
+    token: Optional[str] = TokenOpt,
+    json_flag: bool = JsonOpt,
+):
+    """Peek content without downloading or consuming reads (dir → file list)."""
+    def go():
+        client = get_client(server, token)
+        try:
+            return client.preview(ref, nbytes, latest)
+        finally:
+            client.close()
+    run(go, json_flag)
+
+
+@app.command()
+def rm(
+    ref: str = typer.Argument(..., metavar="ID_OR_NAME"),
+    if_exists: bool = typer.Option(False, "--if-exists", help="Exit 0 even if missing"),
+    latest: bool = typer.Option(False, "--latest",
+                                help="If a name matches multiple objects, take the newest"),
+    server: Optional[str] = ServerOpt,
+    token: Optional[str] = TokenOpt,
+    json_flag: bool = JsonOpt,
+):
+    """Delete an object."""
+    def go():
+        client = get_client(server, token)
+        try:
+            try:
+                return client.rm(ref, latest)
+            except FlyfileError as e:
+                if if_exists and e.error == "not_found":
+                    return {"deleted": None, "existed": False}
+                raise
+        finally:
+            client.close()
+    run(go, json_flag)
+
+
+@app.command()
+def send(
+    source: str = typer.Argument(..., help="File, directory, or '-' for stdin"),
+    code: Optional[str] = typer.Option(None, help="Channel code (default: auto word-word)"),
+    timeout: int = typer.Option(300, help="Seconds to wait for the receiver"),
+    server: Optional[str] = ServerOpt,
+    token: Optional[str] = TokenOpt,
+    json_flag: bool = JsonOpt,
+):
+    """Stream directly to another client via the server (data never stored).
+
+    Emits NDJSON events: code → done. Give the code to the receiver:
+    flyfile recv <code>
+    """
+    def go():
+        client = get_client(server, token)
+        try:
+            json_mode = out.is_json_mode(json_flag)
+
+            def on_event(ev: dict):
+                if json_mode:
+                    out.emit_event(ev)
+                elif ev["event"] == "code":
+                    print(f"code: {ev['code']}\nwaiting for receiver... "
+                          f"(flyfile recv {ev['code']})", file=sys.stderr)
+                elif ev["event"] == "done":
+                    sys.stderr.write("\r\x1b[K")
+                    print(f"sent ({out.fmt_size(ev['bytes'])} on wire)", file=sys.stderr)
+
+            client.send(source, code, timeout, on_event,
+                        progress=out.progress_printer("send"))
+            return None
+        finally:
+            client.close()
+    run(go, json_flag)
+
+
+@app.command()
+def recv(
+    code: str = typer.Argument(..., help="Channel code from the sender"),
+    output: Optional[str] = typer.Option(None, "-o", "--output"),
+    force: bool = typer.Option(False, "--force"),
+    timeout: int = typer.Option(300, help="Seconds to wait for the sender"),
+    server: Optional[str] = ServerOpt,
+    token: Optional[str] = TokenOpt,
+    json_flag: bool = JsonOpt,
+):
+    """Receive a direct transfer by channel code."""
+    def go():
+        client = get_client(server, token)
+        try:
+            prog = out.progress_printer("recv")
+            result = client.recv(code, output, force, timeout, progress=prog)
+            if prog:
+                sys.stderr.write("\r\x1b[K")
+            if result.get("output") == "-":
+                return None
+            if out.is_json_mode(json_flag):
+                return result
+            print(f"{result['name']} -> {result['output']}")
+            return None
+        finally:
+            client.close()
+    run(go, json_flag)
+
+
+@app.command()
+def serve(
+    host: str = typer.Option("0.0.0.0"),
+    port: int = typer.Option(8632),
+    data_dir: Optional[Path] = typer.Option(None, help="Default: ~/.local/share/flyfile"),
+    token: Optional[str] = typer.Option(None, help="Empty = no auth (LAN only!)"),
+):
+    """Run the flyfile server (single worker; relay pairing lives in-process)."""
+    import uvicorn
+    from flyfile.server.app import create_app
+    from flyfile.server.config import ServerConfig
+
+    kw = {}
+    if data_dir:
+        kw["data_dir"] = data_dir
+    if token is not None:
+        kw["token"] = token
+    uvicorn.run(create_app(ServerConfig(host=host, port=port, **kw)),
+                host=host, port=port, workers=1)
+
+
+@app.command()
+def stats(
+    server: Optional[str] = ServerOpt,
+    token: Optional[str] = TokenOpt,
+    json_flag: bool = JsonOpt,
+):
+    """Server-side storage stats."""
+    def go():
+        client = get_client(server, token)
+        try:
+            return client.stats()
+        finally:
+            client.close()
+    run(go, json_flag)
+
+
+@app.command()
+def schema(command: Optional[str] = typer.Argument(None)):
+    """Dump the command tree as JSON (for agent introspection)."""
+    def describe(cmd, name):
+        info = {"name": name, "help": (cmd.help or "").strip()}
+        if hasattr(cmd, "commands"):  # group（typer 可能 vendor click，不做 isinstance）
+            info["commands"] = [describe(sub, n) for n, sub in cmd.commands.items()]
+        else:
+            info["params"] = [
+                {"name": p.name, "opts": list(p.opts), "required": p.required,
+                 "default": None if p.default in (None, ...) else str(p.default),
+                 "help": getattr(p, "help", None)}
+                for p in cmd.params
+            ]
+        return info
+
+    root = typer.main.get_command(app)
+    if command:
+        cmd = root.commands.get(command)
+        if not cmd:
+            print(json.dumps({"error": "not_found", "message": f"no command '{command}'"}),
+                  file=sys.stderr)
+            raise typer.Exit(3)
+        print(json.dumps(describe(cmd, command), ensure_ascii=False, indent=2))
+    else:
+        print(json.dumps(describe(root, "flyfile"), ensure_ascii=False, indent=2))
+
+
+@app.command()
+def version(json_flag: bool = JsonOpt):
+    """Print version."""
+    if out.is_json_mode(json_flag):
+        print(json.dumps({"version": __version__}))
+    else:
+        print(__version__)
+
+
+@config_app.command("set")
+def config_set(key: str, value: str):
+    """Set a config key (server / token)."""
+    if key not in ("server", "token"):
+        print(json.dumps({"error": "usage", "message": f"unknown key '{key}', allowed: server, token"}),
+              file=sys.stderr)
+        raise typer.Exit(EXIT_USAGE)
+    import yaml
+    cfg = load_config()
+    cfg[key] = value
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(yaml.safe_dump(cfg, default_flow_style=False, allow_unicode=True))
+    print(json.dumps({key: value}))
+
+
+@config_app.command("get")
+def config_get(key: str):
+    cfg = load_config()
+    if key not in cfg:
+        raise typer.Exit(3)
+    print(cfg[key])
+
+
+@config_app.command("show")
+def config_show():
+    cfg = load_config()
+    if "token" in cfg:
+        cfg["token"] = cfg["token"][:4] + "***"
+    print(json.dumps(cfg, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    app()

flyfile/cli/output.py

@@ -0,0 +1,98 @@
+"""输出规范：数据走 stdout，进度/提示走 stderr；非 TTY 自动 JSON。"""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+
+
+def is_json_mode(json_flag: bool) -> bool:
+    return json_flag or not sys.stdout.isatty()
+
+
+def emit(data, json_mode: bool) -> None:
+    if json_mode:
+        print(json.dumps(_humanize(data), ensure_ascii=False))
+    else:
+        _pretty(data)
+
+
+def emit_event(event: dict) -> None:
+    """NDJSON 事件流（send 等长驻命令用），立即 flush。"""
+    print(json.dumps(event, ensure_ascii=False), flush=True)
+
+
+def _ts(v):
+    return datetime.fromtimestamp(v, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") if v else None
+
+
+def _humanize(data):
+    if isinstance(data, list):
+        return [_humanize(x) for x in data]
+    if isinstance(data, dict):
+        out = dict(data)
+        for k in ("created_at", "expires_at", "last_read_at"):
+            if k in out and isinstance(out[k], (int, float)):
+                out[k] = _ts(out[k])
+        out.pop("manifest", None) if out.get("kind") != "dir" else None
+        return out
+    return data
+
+
+def _size(n) -> str:
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if n < 1024 or unit == "TB":
+            return f"{n:.0f}{unit}" if unit == "B" else f"{n:.1f}{unit}"
+        n /= 1024
+
+
+def _pretty(data) -> None:
+    if isinstance(data, list):
+        if not data:
+            print("(empty)")
+            return
+        rows = [(o["id"], o["kind"], _size(o["size"]), ",".join(o.get("tags") or []) or "-",
+                 _ts(o["created_at"]), o["name"]) for o in data]
+        widths = [max(len(str(r[i])) for r in rows) for i in range(5)]
+        for r in rows:
+            print("  ".join(str(v).ljust(w) for v, w in zip(r[:5], widths)) + "  " + r[5])
+    elif isinstance(data, dict):
+        for k, v in _humanize(data).items():
+            if v is not None and k != "manifest":
+                print(f"{k}: {v}")
+    else:
+        print(data)
+
+
+def fmt_size(n: float) -> str:
+    return _size(n)
+
+
+def progress_printer(label: str):
+    """TTY 下的字节级进度 + 实时速度（stderr）；非 TTY 静默。
+    回调签名 (done_bytes, total_bytes)，渲染节流 10Hz。"""
+    if not sys.stderr.isatty():
+        return None
+
+    import time as _time
+    state = {"t0": None, "last": 0.0}
+
+    def show(done: int, total: int):
+        now = _time.monotonic()
+        if state["t0"] is None:
+            state["t0"] = now
+        if done < total and now - state["last"] < 0.1:
+            return
+        state["last"] = now
+        elapsed = now - state["t0"]
+        speed = f"{_size(done / elapsed)}/s" if elapsed > 0.5 else "--"
+        if total > 0:
+            pct = done * 100 // total
+            sys.stderr.write(f"\r\x1b[K{label}: {_size(done)}/{_size(total)} ({pct}%) {speed}")
+        else:  # 流式，总量未知（dir/stdin）
+            sys.stderr.write(f"\r\x1b[K{label}: {_size(done)} {speed}")
+        sys.stderr.flush()
+        if total > 0 and done >= total:
+            sys.stderr.write("\n")
+
+    return show