nekocat 0.1.0__tar.gz

nekocat-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+# Gitignore settings for ESPHome
+# This is an example and may include too much for your use-case.
+# You can modify this file to suit your needs.
+/.esphome/
+/secrets.yaml

nekocat-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: nekocat
+Version: 0.1.0
+Summary: A LAN communication platform — chat, files, shell, and more over your local network
+Project-URL: Homepage, https://github.com/nekocat/nekocat
+Project-URL: Issues, https://github.com/nekocat/nekocat/issues
+License: MIT
+Keywords: chat,communication,daemon,file-transfer,lan,network
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: click>=8.1
+Requires-Dist: cryptography>=41.0
+Requires-Dist: plyer>=2.1
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# NekoCat 🐱
+
+> A LAN communication platform. Chat, share files, send notifications, open remote shells — all over your local network with a single `pip install`.
+
+```
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+XX  /\_/\  XX  nekocat                   XX
+XX ( o.o ) XX  a lan communication       XX
+XX  >   <  XX  package                   XX
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+```
+
+## Quick Start
+
+```bash
+pip install nekocat
+neko setup
+```
+
+That's it. The daemon starts automatically and will restart on every boot.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `neko setup` | First-time setup: generate keys, register autostart, start daemon |
+| `neko look` | Discover NekoCat devices on your LAN |
+| `neko throw file.txt Laptop` | Send a file (or folder) to a device |
+| `neko catch` | Wait for incoming transfers |
+| `neko chat` | Open LAN broadcast chat |
+| `neko meow "Hello!"` | Send a desktop notification |
+| `neko shell Laptop` | Open a remote terminal |
+| `neko share ~/Projects` | Share a folder read-only |
+| `neko pair Laptop` | Pair with a new device |
+| `neko open` | Open the received-files directory |
+| `neko logs` | View transfer, chat, and error history |
+| `neko status` | Show daemon status |
+| `neko enable` | Enable autostart on boot |
+| `neko disable` | Disable autostart on boot |
+| `neko uwu` | ✨ |
+
+## Architecture
+
+```
+neko (CLI)  ──IPC─►  nekod (Daemon)  ──LAN─►  peers
+   localhost:54320           port:54322
+```
+
+The CLI never touches the network directly. Every LAN operation is handled by `nekod`, which runs as a background service.
+
+## Security
+
+- Each installation generates a unique **Node ID** and an **Ed25519 identity key pair**.
+- All sessions use **X25519 ephemeral key exchange** so traffic is encrypted with a fresh key each time.
+- First-time connections show a **6-digit pairing code** that must match on both devices.
+- Once paired, devices are trusted automatically.
+
+## Configuration
+
+| OS | Path |
+|----|------|
+| Windows | `%APPDATA%\NekoCat\` |
+| Linux | `~/.config/nekocat/` |
+| macOS | `~/Library/Application Support/NekoCat/` |
+
+Config files:
+- `config.json` — general settings
+- `trusted_peers.json` — paired devices and their public keys
+- `nekocat.db` — SQLite database for peer cache and all logs
+
+## License
+
+MIT

nekocat-0.1.0/README.md

@@ -0,0 +1,73 @@
+# NekoCat 🐱
+
+> A LAN communication platform. Chat, share files, send notifications, open remote shells — all over your local network with a single `pip install`.
+
+```
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+XX  /\_/\  XX  nekocat                   XX
+XX ( o.o ) XX  a lan communication       XX
+XX  >   <  XX  package                   XX
+XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+```
+
+## Quick Start
+
+```bash
+pip install nekocat
+neko setup
+```
+
+That's it. The daemon starts automatically and will restart on every boot.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `neko setup` | First-time setup: generate keys, register autostart, start daemon |
+| `neko look` | Discover NekoCat devices on your LAN |
+| `neko throw file.txt Laptop` | Send a file (or folder) to a device |
+| `neko catch` | Wait for incoming transfers |
+| `neko chat` | Open LAN broadcast chat |
+| `neko meow "Hello!"` | Send a desktop notification |
+| `neko shell Laptop` | Open a remote terminal |
+| `neko share ~/Projects` | Share a folder read-only |
+| `neko pair Laptop` | Pair with a new device |
+| `neko open` | Open the received-files directory |
+| `neko logs` | View transfer, chat, and error history |
+| `neko status` | Show daemon status |
+| `neko enable` | Enable autostart on boot |
+| `neko disable` | Disable autostart on boot |
+| `neko uwu` | ✨ |
+
+## Architecture
+
+```
+neko (CLI)  ──IPC─►  nekod (Daemon)  ──LAN─►  peers
+   localhost:54320           port:54322
+```
+
+The CLI never touches the network directly. Every LAN operation is handled by `nekod`, which runs as a background service.
+
+## Security
+
+- Each installation generates a unique **Node ID** and an **Ed25519 identity key pair**.
+- All sessions use **X25519 ephemeral key exchange** so traffic is encrypted with a fresh key each time.
+- First-time connections show a **6-digit pairing code** that must match on both devices.
+- Once paired, devices are trusted automatically.
+
+## Configuration
+
+| OS | Path |
+|----|------|
+| Windows | `%APPDATA%\NekoCat\` |
+| Linux | `~/.config/nekocat/` |
+| macOS | `~/Library/Application Support/NekoCat/` |
+
+Config files:
+- `config.json` — general settings
+- `trusted_peers.json` — paired devices and their public keys
+- `nekocat.db` — SQLite database for peer cache and all logs
+
+## License
+
+MIT

nekocat-0.1.0/nekocat/__init__.py

@@ -0,0 +1,5 @@
+"""NekoCat — a LAN communication platform."""
+
+from nekocat.__version__ import __version__
+
+__all__ = ["__version__"]

nekocat-0.1.0/nekocat/__version__.py

@@ -0,0 +1,7 @@
+"""Version information for NekoCat."""
+
+__version__ = "0.1.0"
+__version_info__ = (0, 1, 0)
+
+#: LAN wire-protocol version negotiated between peers.
+PROTOCOL_VERSION: int = 1

nekocat-0.1.0/nekocat/cli/__init__.py

@@ -0,0 +1,9 @@
+"""
+NekoCat CLI package.
+
+Every command imports the shared IPC client and the banner printer from here.
+"""
+
+from nekocat.cli.main import BANNER
+
+__all__ = ["BANNER"]

nekocat-0.1.0/nekocat/cli/cmd_catch.py

@@ -0,0 +1,132 @@
+"""
+``nekocat catch`` — wait for and accept incoming file transfers.
+
+Listens for push events from the daemon and prompts the user to accept
+or reject each incoming transfer.  Displays a progress bar while receiving.
+
+Usage
+-----
+    nekocat catch
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import click
+from rich.console import Console
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TransferSpeedColumn,
+    TimeRemainingColumn,
+    TextColumn,
+)
+
+from nekocat.ipc.client import IPCClient
+from nekocat.ipc.protocol import CMD, IPCRequest
+
+console = Console()
+
+
+@click.command()
+def catch() -> None:
+    """Wait for incoming files from peers."""
+    asyncio.run(_catch())
+
+
+async def _catch() -> None:
+    console.print("[cyan]Waiting for incoming files… (Ctrl+C to stop)[/cyan]")
+
+    async with IPCClient() as client:
+        await client.send(IPCRequest(cmd=CMD.RECEIVE_START))
+
+        active_tasks: dict[str, object] = {}
+
+        with Progress(
+            TextColumn("[bold blue]{task.fields[filename]}"),
+            BarColumn(),
+            DownloadColumn(),
+            TransferSpeedColumn(),
+            TimeRemainingColumn(),
+            console=console,
+        ) as progress:
+            try:
+                async for push in client.stream_push():
+                    if push.cmd == CMD.PUSH_INCOMING_TRANSFER:
+                        d = push.data
+                        from_name = d.get("from", "Unknown")
+                        file_name = d.get("file_name", "?")
+                        file_size = int(d.get("file_size", 0))
+                        job_id = d.get("job_id", "")
+
+                        console.print(
+                            f"\n[bold]{from_name}[/bold] wants to send "
+                            f"[cyan]{file_name}[/cyan] "
+                            f"({_human_size(file_size)})"
+                        )
+                        answer = click.prompt(
+                            "Accept? [Y/n]",
+                            default="Y",
+                            show_default=False,
+                        ).strip().lower()
+
+                        if answer in ("", "y", "yes"):
+                            await client.send(
+                                IPCRequest(
+                                    cmd=CMD.ACCEPT_TRANSFER,
+                                    payload={"job_id": job_id},
+                                )
+                            )
+                            task_id = progress.add_task(
+                                "Receiving…",
+                                total=file_size,
+                                filename=file_name,
+                            )
+                            active_tasks[job_id] = task_id
+                        else:
+                            await client.send(
+                                IPCRequest(
+                                    cmd=CMD.REJECT_TRANSFER,
+                                    payload={"job_id": job_id},
+                                )
+                            )
+                            console.print("[yellow]Rejected.[/yellow]")
+
+                    elif push.cmd == CMD.PUSH_TRANSFER_PROGRESS:
+                        d = push.data
+                        job_id = d.get("job_id", "")
+                        task_id = active_tasks.get(job_id)
+                        if task_id is not None:
+                            progress.update(
+                                task_id,  # type: ignore[arg-type]
+                                completed=d.get("transferred_bytes", 0),
+                            )
+
+                    elif push.cmd == CMD.PUSH_TRANSFER_COMPLETE:
+                        d = push.data
+                        job_id = d.get("job_id", "")
+                        task_id = active_tasks.pop(job_id, None)
+                        if task_id is not None:
+                            progress.update(task_id, completed=progress.tasks[0].total)  # type: ignore
+                        console.print(
+                            f"[green]✓ Saved to:[/green] {d.get('save_path', '(unknown)')}"
+                        )
+
+                    elif push.cmd == CMD.PUSH_TRANSFER_ERROR:
+                        d = push.data
+                        job_id = d.get("job_id", "")
+                        active_tasks.pop(job_id, None)
+                        console.print(f"[red]✗ Transfer error:[/red] {d.get('error')}")
+
+            except (KeyboardInterrupt, asyncio.CancelledError):
+                pass
+
+
+def _human_size(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024:
+            return f"{n:.1f} {unit}"
+        n //= 1024
+    return f"{n:.1f} TB"

nekocat-0.1.0/nekocat/cli/cmd_chat.py

@@ -0,0 +1,85 @@
+"""
+``nekocat chat`` — interactive LAN group chat.
+
+Opens a live chat session.  Messages from other peers arrive in real time
+via daemon push events.  Ctrl+C exits.
+
+Usage
+-----
+    nekocat chat
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+
+import click
+from rich.console import Console
+from rich.markup import escape
+
+from nekocat.ipc.client import IPCClient
+from nekocat.ipc.protocol import CMD, IPCRequest
+
+console = Console()
+
+
+@click.command()
+@click.option("--history", "show_history", is_flag=True, default=True,
+              help="Show recent chat history on startup.")
+def chat(show_history: bool) -> None:
+    """Open an interactive LAN chat session."""
+    asyncio.run(_chat(show_history))
+
+
+async def _chat(show_history: bool) -> None:
+    async with IPCClient() as client:
+        if show_history:
+            resp = await client.send(IPCRequest(cmd=CMD.CHAT_HISTORY, payload={"limit": 50}))
+            if resp.status == "ok":
+                msgs = resp.data.get("messages", [])
+                if msgs:
+                    console.print("[dim]── recent history ──[/dim]")
+                    for m in msgs:
+                        _print_message(m)
+                    console.print("[dim]────────────────────[/dim]")
+
+        console.print("[cyan]LAN chat — type and press Enter.  Ctrl+C to exit.[/cyan]\n")
+
+        # Register as subscriber for push events
+        await client.send(IPCRequest(cmd=CMD.CHAT_SEND, payload={"content": ""}))
+
+        # Run input and receive loops concurrently
+        input_task = asyncio.create_task(_input_loop(client))
+        recv_task = asyncio.create_task(_recv_loop(client))
+
+        try:
+            await asyncio.gather(input_task, recv_task)
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            input_task.cancel()
+            recv_task.cancel()
+
+
+async def _input_loop(client: IPCClient) -> None:
+    """Read lines from stdin and send them as chat messages."""
+    loop = asyncio.get_running_loop()
+    while True:
+        line = await loop.run_in_executor(None, input)
+        line = line.strip()
+        if not line:
+            continue
+        await client.send(IPCRequest(cmd=CMD.CHAT_SEND, payload={"content": line}))
+
+
+async def _recv_loop(client: IPCClient) -> None:
+    """Listen for push events and print incoming chat messages."""
+    async for push in client.stream_push():
+        if push.cmd == CMD.PUSH_CHAT_MESSAGE:
+            _print_message(push.data)
+
+
+def _print_message(m: dict) -> None:
+    ts = datetime.datetime.fromtimestamp(m.get("timestamp", 0)).strftime("%H:%M")
+    user = escape(f"{m.get('from_username', '?')}@{m.get('from_hostname', '?')}")
+    content = escape(m.get("content", ""))
+    console.print(f"[dim]{ts}[/dim] [bold cyan]{user}[/bold cyan]: {content}")

nekocat-0.1.0/nekocat/cli/cmd_disable.py

@@ -0,0 +1,48 @@
+"""
+``nekocat disable`` — disable daemon autostart on boot.
+
+Usage
+-----
+    nekocat disable
+"""
+
+from __future__ import annotations
+
+import platform
+import subprocess
+import sys
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.command()
+def disable() -> None:
+    """Disable the daemon autostart on boot."""
+    system = platform.system()
+    try:
+        if system == "Windows":
+            subprocess.run(
+                "schtasks /Delete /F /TN \"NekoCat Daemon\"",
+                shell=True, check=True, capture_output=True,
+            )
+        elif system == "Linux":
+            subprocess.run(["systemctl", "--user", "disable", "nekod"], check=False)
+            from pathlib import Path
+            svc = Path.home() / ".config" / "systemd" / "user" / "nekod.service"
+            if svc.exists():
+                svc.unlink()
+        elif system == "Darwin":
+            from pathlib import Path
+            plist = Path.home() / "Library" / "LaunchAgents" / "com.nekocat.daemon.plist"
+            if plist.exists():
+                subprocess.run(["launchctl", "unload", str(plist)], check=False)
+                plist.unlink()
+        else:
+            console.print(f"[yellow]Autostart not supported on {system}.[/yellow]")
+            return
+        console.print("[green]✓[/green] Autostart disabled.")
+    except Exception as exc:
+        console.print(f"[red]Error disabling autostart:[/red] {exc}")

nekocat-0.1.0/nekocat/cli/cmd_enable.py

@@ -0,0 +1,23 @@
+"""
+``nekocat enable`` — enable daemon autostart on boot.
+
+Usage
+-----
+    nekocat enable
+"""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+
+from nekocat.cli.cmd_setup import _register_autostart
+
+console = Console()
+
+
+@click.command()
+def enable() -> None:
+    """Enable the daemon to start automatically on boot."""
+    _register_autostart()
+    console.print("[green]✓[/green] Autostart enabled.")

nekocat-0.1.0/nekocat/cli/cmd_logs.py

@@ -0,0 +1,86 @@
+"""
+``nekocat logs`` — view transfer, chat, and error history.
+
+Usage
+-----
+    nekocat logs
+    nekocat logs --limit 20
+    nekocat logs --type transfer
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from nekocat.ipc.client import IPCClient
+from nekocat.ipc.protocol import CMD, IPCRequest
+
+console = Console()
+
+
+@click.command()
+@click.option("--limit", default=50, help="Number of log entries to show (default 50).")
+@click.option(
+    "--type", "event_type", default=None,
+    help="Filter by type: transfer, chat, notification, shell_session, pair, error.",
+)
+def logs(limit: int, event_type: str | None) -> None:
+    """View activity history (transfers, chat, notifications, errors)."""
+    asyncio.run(_logs(limit, event_type))
+
+
+async def _logs(limit: int, event_type: str | None) -> None:
+    payload: dict = {"limit": limit}
+    if event_type:
+        payload["event_type"] = event_type
+
+    async with IPCClient() as client:
+        resp = await client.send(IPCRequest(cmd=CMD.LOGS_QUERY, payload=payload))
+
+    if resp.status == "error":
+        console.print(f"[red]Error:[/red] {resp.error}")
+        return
+
+    data = resp.data
+    entries = data.get("entries", [])
+
+    if not entries:
+        console.print("[yellow]No log entries found.[/yellow]")
+        return
+
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Time", style="dim")
+    table.add_column("Type")
+    table.add_column("Peer")
+    table.add_column("Summary")
+
+    for e in entries:
+        ts = e.get("timestamp", 0)
+        time_str = datetime.datetime.fromtimestamp(ts).strftime("%Y-%m-%d %H:%M:%S")
+        etype = e.get("event_type", "?")
+        peer = e.get("display_name") or e.get("node_id", "") or ""
+        summary = e.get("summary", "")
+
+        type_colors = {
+            "transfer": "blue",
+            "chat": "cyan",
+            "notification": "magenta",
+            "shell_session": "green",
+            "pair": "yellow",
+            "error": "red",
+        }
+        color = type_colors.get(etype, "white")
+
+        table.add_row(
+            time_str,
+            f"[{color}]{etype}[/{color}]",
+            f"[dim]{peer}[/dim]",
+            summary,
+        )
+
+    console.print(table)

nekocat-0.1.0/nekocat/cli/cmd_look.py

@@ -0,0 +1,81 @@
+"""
+``nekocat look`` — discover and list peers on the LAN.
+
+Shows online peers discovered by the daemon and, if --all is passed,
+also shows cached offline peers with their last-seen timestamp.
+
+Usage
+-----
+    nekocat look
+    nekocat look --all
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from nekocat.ipc.client import IPCClient
+from nekocat.ipc.protocol import CMD, IPCRequest
+
+console = Console()
+
+
+@click.command()
+@click.option("--all", "show_all", is_flag=True, help="Include offline cached peers.")
+def look(show_all: bool) -> None:
+    """List peers visible on the LAN."""
+    asyncio.run(_look(show_all))
+
+
+async def _look(show_all: bool) -> None:
+    async with IPCClient() as client:
+        resp = await client.send(IPCRequest(cmd=CMD.LOOK, payload={"all": show_all}))
+
+    if resp.status == "error":
+        console.print(f"[red]Error:[/red] {resp.error}")
+        return
+
+    peers: list[dict] = resp.data.get("peers", [])
+
+    if not peers:
+        console.print("[yellow]No peers found on the LAN.[/yellow]")
+        return
+
+    table = Table(title="LAN Peers", show_header=True, header_style="bold cyan")
+    table.add_column("Name", style="bold")
+    table.add_column("Hostname")
+    table.add_column("IP Address")
+    table.add_column("Status")
+    table.add_column("Trusted", justify="center")
+    table.add_column("Last Seen")
+
+    for p in peers:
+        status = p.get("status", "unknown")
+        status_style = "green" if status == "online" else "dim"
+        trusted = "✓" if p.get("trusted") else ""
+        name = f"{p.get('username', '?')}@{p.get('hostname', '?')}"
+
+        import time
+        last_seen = p.get("last_seen", 0.0)
+        delta = time.time() - last_seen
+        if delta < 60:
+            seen = f"{int(delta)}s ago"
+        elif delta < 3600:
+            seen = f"{int(delta/60)}m ago"
+        else:
+            seen = f"{int(delta/3600)}h ago"
+
+        table.add_row(
+            name,
+            p.get("hostname", "?"),
+            p.get("ip", "?"),
+            f"[{status_style}]{status}[/{status_style}]",
+            f"[green]{trusted}[/green]",
+            seen,
+        )
+
+    console.print(table)