devbits 1.3.3__tar.gz → 1.4.1__tar.gz

{devbits-1.3.3 → devbits-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devbits
-Version: 1.3.3
+Version: 1.4.1
 Summary: A lightweight CLI toolkit for daily development utilities.
 Author: Bruce Chuang
 License-Expression: MIT
@@ -42,8 +42,8 @@ devbits <command> [options]
 Use `--help` on any command for detailed usage and parameter descriptions:
 
 ```bash
-devbits clipvideo --help
-clipvideo --help
+devbits editvideo --help
+editvideo --help
 ```
 
 ## Commands
@@ -52,7 +52,7 @@ clipvideo --help
 
 | Command | Description |
 |---------|-------------|
-| `clipvideo` | Trim a video by time (seconds) or frame range. Includes `--gui` for browser-based editing. |
+| `editvideo` | Trim a video by time (seconds) or frame range. Includes `--gui` for browser-based editing. (Formerly `clipvideo`, which still works but prints a rename notice.) |
 | `video2images` | Extract frames from a video. |
 | `video2gif` | Convert a video (or a portion) to animated GIF. |
 | `images2video` | Assemble an image sequence into an MP4 video. |
@@ -85,16 +85,17 @@ clipvideo --help
 | Command | Description |
 |---------|-------------|
 | `netscan` | List devices connected to your local network (Wi-Fi / router) with their IP, MAC, and hostname. `--lookup` adds the manufacturer. |
+| `netsurvey` | Map **every network segment** visible on the current link — your own interfaces, foreign subnets on the same switch, the addresses in use, and the conflicts between them. Built for shared networks (trade shows, offices). |
 | `wifi` | Manage Wi-Fi: `list`, `connect` (arrow-key picker + hidden password prompt), `on`, `off`, `forget`. Linux and Windows fully; macOS without `list`. |
 
 ## Examples
 
 ```bash
 # Trim video from 5s to 20s
-clipvideo movie.mp4 --start 5.0 --end 20.0
+editvideo movie.mp4 --start 5.0 --end 20.0
 
 # Open interactive clip editor in the browser
-clipvideo movie.mp4 --gui
+editvideo movie.mp4 --gui
 
 # Convert video to GIF (3.5s–10s at 15 fps)
 video2gif movie.mp4 --start 3.5 --end 10.0 --fps 15
@@ -124,6 +125,18 @@ netscan --lookup
 # Scan a specific subnet, faster, without hostname lookups
 netscan --network 192.168.1.0/24 --timeout 0.5 --no-resolve
 
+# Map every network segment and address around you (passive, ~2s)
+netsurvey
+
+# Segments and conflicts only, no address lists
+netsurvey --summary
+
+# Also ping-sweep your ranges and the discovered ones
+netsurvey --sweep
+
+# Check specific ranges before assigning them at a venue
+netsurvey --include 192.168.1.0/24 --include 10.0.0.0/24
+
 # Show the Wi-Fi networks in range (Linux / Windows)
 wifi list
 
@@ -146,6 +159,58 @@ wifi forget OldCafe
 > laptops that use a randomized/private MAC show up as `(private)` and can't be
 > attributed to a vendor.
 
+### Surveying a shared network
+
+`netscan` answers "who is on **my** subnet?". `netsurvey` answers "what is on
+this **wire**?" — the question that matters in an exhibition hall, an office, or
+a co-working space where other people's routers hand out their own ranges:
+
+```
+INTERFACES
+  en0         192.168.0.122/24      gateway 192.168.0.1
+  utun6       10.2.244.44/32
+
+SEGMENTS  (3 total, 2 yours, 9 address(es) in use)
+  192.168.0.0/24      local (en0)             swept     6 host(s)
+    192.168.0.1     06:f2:67:75:4d:e2   gateway,arp,ping      gateway / router
+    192.168.0.122   4e:e5:41:93:7c:1f   self,arp,mdns         this device
+    ...
+  10.77.0.0/24        foreign                 passive   2 host(s)
+    10.77.0.9       de:ad:be:ef:00:01   ssdp,arp
+
+CONFLICTS  (2)
+  ! [duplicate-ip] 192.168.0.50 answers from 2 MAC addresses (…) — two devices claim the same address
+  - [shared-l2] 1 foreign segment(s) share this link: 10.77.0.0/24
+```
+
+Three independent sources are combined, so segments you have no address in still
+show up:
+
+- **every local interface** with its real netmask (`ip` / `ifconfig` / `ipconfig`);
+- the **ARP / neighbour cache**, which lists link neighbours *regardless of
+  subnet* — this is what exposes somebody else's range on the same switch;
+- **SSDP and mDNS** answers, sent out of each interface (skip with `--no-passive`).
+
+The default pass is passive and takes about two seconds. `--sweep` additionally
+ping-sweeps your ranges and the discovered ones so each address list is complete;
+`--include CIDR` sweeps a specific range you are about to assign. Ranges larger
+than `--max-sweep` (4096 hosts) are narrowed to the /24 around your own address
+or skipped, with a note on stderr.
+
+Reported conflicts:
+
+| Kind | Meaning |
+|------|---------|
+| `duplicate-ip` | One address answers from two MACs — two devices claim it. |
+| `overlap` | A foreign range, or a second local interface (VPN!), overlaps one of your subnets. |
+| `no-dhcp` | An interface self-assigned a `169.254.x.x` address; no DHCP server answered. |
+| `router-bridge` | One MAC answers for addresses in several segments — a router joining them. |
+| `shared-l2` | Foreign segments are present on your link (informational). |
+
+> Survey only networks you are entitled to. `netsurvey` sends ordinary pings and
+> standard discovery multicast — nothing privileged — but probing networks you
+> don't administer may still violate policy or law.
+
 ### Wi-Fi
 
 `wifi connect` lists everything in range — move with ↑/↓, press Enter to join,
@@ -225,7 +290,7 @@ dependency for one platform, devbits doesn't scan on macOS at all.
 When `-o` / `--output` is omitted, the output filename is derived from the input:
 
 ```
-clipvideo movie.mp4          →  movie_clip.mp4
+editvideo movie.mp4          →  movie_clip.mp4
 video2gif movie.mp4          →  movie.gif
 resizeimage photo.jpg        →  photo_resized.jpg
 recolor logo.png             →  logo_revised.png

{devbits-1.3.3 → devbits-1.4.1}/README.md

@@ -25,8 +25,8 @@ devbits <command> [options]
 Use `--help` on any command for detailed usage and parameter descriptions:
 
 ```bash
-devbits clipvideo --help
-clipvideo --help
+devbits editvideo --help
+editvideo --help
 ```
 
 ## Commands
@@ -35,7 +35,7 @@ clipvideo --help
 
 | Command | Description |
 |---------|-------------|
-| `clipvideo` | Trim a video by time (seconds) or frame range. Includes `--gui` for browser-based editing. |
+| `editvideo` | Trim a video by time (seconds) or frame range. Includes `--gui` for browser-based editing. (Formerly `clipvideo`, which still works but prints a rename notice.) |
 | `video2images` | Extract frames from a video. |
 | `video2gif` | Convert a video (or a portion) to animated GIF. |
 | `images2video` | Assemble an image sequence into an MP4 video. |
@@ -68,16 +68,17 @@ clipvideo --help
 | Command | Description |
 |---------|-------------|
 | `netscan` | List devices connected to your local network (Wi-Fi / router) with their IP, MAC, and hostname. `--lookup` adds the manufacturer. |
+| `netsurvey` | Map **every network segment** visible on the current link — your own interfaces, foreign subnets on the same switch, the addresses in use, and the conflicts between them. Built for shared networks (trade shows, offices). |
 | `wifi` | Manage Wi-Fi: `list`, `connect` (arrow-key picker + hidden password prompt), `on`, `off`, `forget`. Linux and Windows fully; macOS without `list`. |
 
 ## Examples
 
 ```bash
 # Trim video from 5s to 20s
-clipvideo movie.mp4 --start 5.0 --end 20.0
+editvideo movie.mp4 --start 5.0 --end 20.0
 
 # Open interactive clip editor in the browser
-clipvideo movie.mp4 --gui
+editvideo movie.mp4 --gui
 
 # Convert video to GIF (3.5s–10s at 15 fps)
 video2gif movie.mp4 --start 3.5 --end 10.0 --fps 15
@@ -107,6 +108,18 @@ netscan --lookup
 # Scan a specific subnet, faster, without hostname lookups
 netscan --network 192.168.1.0/24 --timeout 0.5 --no-resolve
 
+# Map every network segment and address around you (passive, ~2s)
+netsurvey
+
+# Segments and conflicts only, no address lists
+netsurvey --summary
+
+# Also ping-sweep your ranges and the discovered ones
+netsurvey --sweep
+
+# Check specific ranges before assigning them at a venue
+netsurvey --include 192.168.1.0/24 --include 10.0.0.0/24
+
 # Show the Wi-Fi networks in range (Linux / Windows)
 wifi list
 
@@ -129,6 +142,58 @@ wifi forget OldCafe
 > laptops that use a randomized/private MAC show up as `(private)` and can't be
 > attributed to a vendor.
 
+### Surveying a shared network
+
+`netscan` answers "who is on **my** subnet?". `netsurvey` answers "what is on
+this **wire**?" — the question that matters in an exhibition hall, an office, or
+a co-working space where other people's routers hand out their own ranges:
+
+```
+INTERFACES
+  en0         192.168.0.122/24      gateway 192.168.0.1
+  utun6       10.2.244.44/32
+
+SEGMENTS  (3 total, 2 yours, 9 address(es) in use)
+  192.168.0.0/24      local (en0)             swept     6 host(s)
+    192.168.0.1     06:f2:67:75:4d:e2   gateway,arp,ping      gateway / router
+    192.168.0.122   4e:e5:41:93:7c:1f   self,arp,mdns         this device
+    ...
+  10.77.0.0/24        foreign                 passive   2 host(s)
+    10.77.0.9       de:ad:be:ef:00:01   ssdp,arp
+
+CONFLICTS  (2)
+  ! [duplicate-ip] 192.168.0.50 answers from 2 MAC addresses (…) — two devices claim the same address
+  - [shared-l2] 1 foreign segment(s) share this link: 10.77.0.0/24
+```
+
+Three independent sources are combined, so segments you have no address in still
+show up:
+
+- **every local interface** with its real netmask (`ip` / `ifconfig` / `ipconfig`);
+- the **ARP / neighbour cache**, which lists link neighbours *regardless of
+  subnet* — this is what exposes somebody else's range on the same switch;
+- **SSDP and mDNS** answers, sent out of each interface (skip with `--no-passive`).
+
+The default pass is passive and takes about two seconds. `--sweep` additionally
+ping-sweeps your ranges and the discovered ones so each address list is complete;
+`--include CIDR` sweeps a specific range you are about to assign. Ranges larger
+than `--max-sweep` (4096 hosts) are narrowed to the /24 around your own address
+or skipped, with a note on stderr.
+
+Reported conflicts:
+
+| Kind | Meaning |
+|------|---------|
+| `duplicate-ip` | One address answers from two MACs — two devices claim it. |
+| `overlap` | A foreign range, or a second local interface (VPN!), overlaps one of your subnets. |
+| `no-dhcp` | An interface self-assigned a `169.254.x.x` address; no DHCP server answered. |
+| `router-bridge` | One MAC answers for addresses in several segments — a router joining them. |
+| `shared-l2` | Foreign segments are present on your link (informational). |
+
+> Survey only networks you are entitled to. `netsurvey` sends ordinary pings and
+> standard discovery multicast — nothing privileged — but probing networks you
+> don't administer may still violate policy or law.
+
 ### Wi-Fi
 
 `wifi connect` lists everything in range — move with ↑/↓, press Enter to join,
@@ -208,7 +273,7 @@ dependency for one platform, devbits doesn't scan on macOS at all.
 When `-o` / `--output` is omitted, the output filename is derived from the input:
 
 ```
-clipvideo movie.mp4          →  movie_clip.mp4
+editvideo movie.mp4          →  movie_clip.mp4
 video2gif movie.mp4          →  movie.gif
 resizeimage photo.jpg        →  photo_resized.jpg
 recolor logo.png             →  logo_revised.png

{devbits-1.3.3 → devbits-1.4.1}/devbits/__init__.py

@@ -1,3 +1,3 @@
 """devbits: A lightweight CLI toolkit for daily development utilities."""
 
-__version__ = "1.3.3"
+__version__ = "1.4.1"

{devbits-1.3.3 → devbits-1.4.1}/devbits/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import ipaddress
 import os
 import shutil
 import sys
@@ -33,6 +34,9 @@ _ANSI = {
     "signal": "\033[32m",
     "lock": "\033[33m",
     "dim": "\033[2m",
+    "segment": "\033[1;36m",
+    "warn": "\033[1;31m",
+    "note": "\033[2m",
     "reset": "\033[0m",
 }
 
@@ -191,20 +195,20 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Output size as 'width,height' in pixels, e.g. 640,360.")
     p.set_defaults(func=cmd_video2gif)
 
-    # ── clipvideo ──────────────────────────────────────────────
+    # ── editvideo ──────────────────────────────────────────────
     p = sub.add_parser(
-        "clipvideo",
-        help="Clip (trim) a video by time range or frame range.",
+        "editvideo",
+        help="Edit (trim) a video by time range or frame range.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         description=(
             "Trim a portion of a video. You can specify the range in seconds\n"
             "(--start / --end) or in frame indices (--start-frame / --end-frame).\n"
             "If no range is given, the interactive browser-based editor opens.\n\n"
             "Examples:\n"
-            "  devbits clipvideo movie.mp4                 # opens the GUI editor\n"
-            "  devbits clipvideo movie.mp4 --start 5.0 --end 20.0\n"
-            "  devbits clipvideo movie.mp4 --start-frame 150 --end-frame 600\n"
-            "  devbits clipvideo --gui                     # GUI with no initial video"
+            "  devbits editvideo movie.mp4                 # opens the GUI editor\n"
+            "  devbits editvideo movie.mp4 --start 5.0 --end 20.0\n"
+            "  devbits editvideo movie.mp4 --start-frame 150 --end-frame 600\n"
+            "  devbits editvideo --gui                     # GUI with no initial video"
         ),
     )
     p.add_argument("video", type=Path, nargs="?", default=None,
@@ -221,7 +225,7 @@ def build_parser() -> argparse.ArgumentParser:
                    help="End frame index (0-based, inclusive).")
     p.add_argument("--gui", action="store_true",
                    help="Open interactive browser-based clip editor.")
-    p.set_defaults(func=cmd_clipvideo)
+    p.set_defaults(func=cmd_editvideo)
 
     # ── resizevideo ────────────────────────────────────────────
     p = sub.add_parser(
@@ -491,6 +495,58 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Disable colored output (also honors NO_COLOR).")
     p.set_defaults(func=cmd_netscan)
 
+    # ── netsurvey ──────────────────────────────────────────────
+    p = sub.add_parser(
+        "netsurvey",
+        help="Map every network segment and address in use around you.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=(
+            "Survey the whole environment instead of a single subnet: list your own\n"
+            "interfaces and their ranges, every segment visible on the same wire, the\n"
+            "addresses in use in each, and the clashes between them.\n\n"
+            "Built for shared networks — a trade-show hall, an office, a co-working\n"
+            "space — where someone else's router hands out an overlapping range and\n"
+            "traffic quietly goes to the wrong place. Reports duplicate IPs, ranges\n"
+            "that overlap your own, links with no DHCP, and routers bridging two\n"
+            "segments.\n\n"
+            "The default pass is passive and takes a couple of seconds: it reads the\n"
+            "ARP / neighbour cache (which lists neighbours on *foreign* subnets too)\n"
+            "and asks for SSDP and mDNS answers. --sweep additionally ping-sweeps\n"
+            "your ranges and the discovered ones so each address list is complete.\n\n"
+            "Survey only networks you are entitled to; probing networks you don't\n"
+            "administer may violate policy or law.\n\n"
+            "Examples:\n"
+            "  devbits netsurvey                              # quick passive map\n"
+            "  devbits netsurvey --summary                     # segments only\n"
+            "  devbits netsurvey --sweep                       # also enumerate every host\n"
+            "  devbits netsurvey --include 192.168.1.0/24 --include 10.0.0.0/24\n"
+            "  devbits netsurvey --sweep --group-prefix 16 --timeout 0.4"
+        ),
+    )
+    p.add_argument("--sweep", action="store_true",
+                   help="Also ping-sweep your own and the discovered segments (slower, complete).")
+    p.add_argument("--include", metavar="CIDR", action="append", default=[],
+                   help="Extra range to sweep, e.g. 10.0.0.0/24. Repeatable.")
+    p.add_argument("--group-prefix", type=int, default=24, metavar="N",
+                   help="Prefix used to group addresses outside your own subnets. Default: 24")
+    p.add_argument("--timeout", type=float, default=0.6,
+                   help="Per-host ping timeout in seconds. Default: 0.6")
+    p.add_argument("--workers", type=int, default=128,
+                   help="Number of concurrent ping workers. Default: 128")
+    p.add_argument("--discover-timeout", type=float, default=2.0, metavar="SECONDS",
+                   help="How long to listen for SSDP / mDNS answers. Default: 2.0")
+    p.add_argument("--no-passive", action="store_true",
+                   help="Skip the multicast discovery step; read the ARP cache only.")
+    p.add_argument("--resolve", action="store_true",
+                   help="Reverse-DNS each address for its hostname (slower).")
+    p.add_argument("--max-sweep", type=int, default=4096, metavar="HOSTS",
+                   help="Refuse to sweep a range larger than this. Default: 4096")
+    p.add_argument("--summary", action="store_true",
+                   help="List segments and conflicts only, without the addresses.")
+    p.add_argument("--no-color", action="store_true",
+                   help="Disable colored output (also honors NO_COLOR).")
+    p.set_defaults(func=cmd_netsurvey)
+
     # ── wifi ───────────────────────────────────────────────────
     p = sub.add_parser(
         "wifi",
@@ -644,7 +700,7 @@ def cmd_video2gif(args: argparse.Namespace) -> None:
     print(video_to_gif(video, output, args.fps, args.start, args.end, args.size))
 
 
-def cmd_clipvideo(args: argparse.Namespace) -> None:
+def cmd_editvideo(args: argparse.Namespace) -> None:
     has_range = any(v is not None for v in (args.start, args.end, args.start_frame, args.end_frame))
     # Open the interactive editor when --gui is set, or by default when a video
     # is provided without an explicit trim range.
@@ -741,8 +797,6 @@ def cmd_samplefiles(args: argparse.Namespace) -> None:
 
 
 def cmd_netscan(args: argparse.Namespace) -> None:
-    import ipaddress
-
     color = _use_color(False if args.no_color else None)
     network = ipaddress.ip_network(args.network, strict=False) if args.network else None
 
@@ -771,6 +825,85 @@ def cmd_netscan(args: argparse.Namespace) -> None:
     print(f"Found {len(devices)} device(s).")
 
 
+def _survey_source_label(sources: set[str], width: int = 22) -> str:
+    """Condense a device's discovery sources into a stable, readable column."""
+    order = ["self", "gateway", "arp", "ping", "ssdp", "mdns"]
+    label = ",".join(source for source in order if source in sources) or "-"
+    if len(label) > width - 1:
+        label = label[: width - 2] + "…"
+    return f"{label:<{width}}"
+
+
+def cmd_netsurvey(args: argparse.Namespace) -> None:
+    from .network import survey_network
+
+    color = _use_color(False if args.no_color else None)
+    if not 8 <= args.group_prefix <= 32:
+        raise ValueError("--group-prefix must be between 8 and 32")
+
+    survey, notes = survey_network(
+        include=args.include,
+        group_prefix=args.group_prefix,
+        sweep=args.sweep,
+        passive=not args.no_passive,
+        timeout=args.timeout,
+        workers=args.workers,
+        discover_timeout=args.discover_timeout,
+        resolve=args.resolve,
+        max_sweep_hosts=args.max_sweep,
+        progress=lambda message: print(message, file=sys.stderr),
+    )
+
+    print(_colorize("INTERFACES", "header", color))
+    for nic in survey.interfaces:
+        note = "gateway " + survey.gateway if survey.gateway and \
+            ipaddress.ip_address(survey.gateway) in nic.network else ""
+        if nic.is_link_local:
+            note = "self-assigned (no DHCP)"
+        name_col = _colorize(f"{nic.name:<12}", "self" if nic.ip == survey.self_ip else "dim", color)
+        print(f"  {name_col}{f'{nic.ip}/{nic.prefix}':<22}{_colorize(note, 'note', color)}".rstrip())
+
+    print()
+    local_count = sum(1 for segment in survey.segments if segment.is_local)
+    print(_colorize(
+        f"SEGMENTS  ({len(survey.segments)} total, {local_count} yours, "
+        f"{survey.device_count} address(es) in use)", "header", color,
+    ))
+    for segment in survey.segments:
+        scope = f"local ({', '.join(segment.interfaces)})" if segment.is_local else "foreign"
+        how = "swept" if segment.swept else "passive"
+        head = f"  {str(segment.network):<20}{scope:<24}{how:<10}{len(segment.devices)} host(s)"
+        print(_colorize(head.rstrip(), "segment" if segment.is_local else "warn", color))
+        if args.summary:
+            continue
+        for device in segment.devices:
+            note = "this device" if device.is_self else ("gateway / router" if device.is_gateway else "")
+            kind = "self" if device.is_self else ("gateway" if device.is_gateway else None)
+            ip_col = _colorize(f"{device.ip:<16}", kind, color) if kind else f"{device.ip:<16}"
+            mac_col = _colorize(f"{device.mac or '-':<20}", "mac", color)
+            host_col = _colorize(f"{device.hostname or '-':<28}", "host", color) if args.resolve else ""
+            seen_col = _colorize(_survey_source_label(device.sources), "note", color)
+            print(f"    {ip_col}{mac_col}{host_col}{seen_col}{note}".rstrip())
+
+    print()
+    if survey.conflicts:
+        print(_colorize(f"CONFLICTS  ({len(survey.conflicts)})", "header", color))
+        for conflict in survey.conflicts:
+            marker = "!" if conflict.kind != "shared-l2" else "-"
+            kind = "warn" if conflict.kind != "shared-l2" else "note"
+            print(_colorize(f"  {marker} [{conflict.kind}] {conflict.message}", kind, color))
+    else:
+        print("No address or range conflicts detected.")
+
+    for note in notes:
+        print(_colorize(f"  note: {note}", "note", color), file=sys.stderr)
+    if not args.sweep and not args.include:
+        print(_colorize(
+            "Passive pass only — run with --sweep to enumerate every address in each segment.",
+            "note", color,
+        ), file=sys.stderr)
+
+
 # ---------------------------------------------------------------------------
 # wifi
 # ---------------------------------------------------------------------------
@@ -1008,6 +1141,15 @@ def cmd_wifi_forget(args: argparse.Namespace) -> None:
 
 
 def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "clipvideo":
+        # Deprecated alias kept so existing invocations keep working.
+        print(
+            "Note: 'clipvideo' has been renamed to 'editvideo' and will be "
+            "removed in a future release. Please use 'editvideo' instead.",
+            file=sys.stderr,
+        )
+        argv[0] = "editvideo"
     parser = build_parser()
     args = parser.parse_args(argv)
     try: