nulltap 0.1.0__tar.gz → 0.1.1__tar.gz

nulltap-0.1.1/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: nulltap
+Version: 0.1.1
+Summary: Read Nulltap cybersecurity and AI articles from a terminal.
+Author: Justin Howe
+License-Expression: MIT
+Project-URL: Homepage, https://nulltap.sh
+Project-URL: Repository, https://github.com/JustinHowe/nulltap
+Project-URL: Issues, https://github.com/JustinHowe/nulltap/issues
+Project-URL: Releases, https://github.com/JustinHowe/nulltap/releases
+Keywords: cybersecurity,ai,news,cli,nulltap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nulltap
+
+Read [Nulltap](https://nulltap.sh) from a terminal. Browse recent cybersecurity and AI articles, search the feed, filter by topic, and read the full article without opening a browser.
+
+## Install
+
+Python 3.10 or newer is required. [pipx](https://pipx.pypa.io/) keeps the command in its own environment:
+
+```sh
+pipx install nulltap
+```
+
+To upgrade an existing installation:
+
+```sh
+pipx upgrade nulltap
+```
+
+A regular pip installation also works: `python -m pip install nulltap`.
+
+## Start here
+
+```sh
+nulltap                         # browse recent articles
+nulltap latest --days 7         # articles published in the last seven days
+nulltap topics                  # list every topic and its article count
+nulltap topic identity          # browse one topic
+nulltap search "token theft"    # search titles, summaries, and topic tags
+nulltap read 2                  # read the second result in the terminal
+```
+
+Interactive lists show five articles at a time. Enter a result number to read it, `n` or `p` to change pages, and `q` to leave. Use `--page-size N` if you want a different page size.
+
+Articles open in the terminal pager with headings, lists, quotations, code blocks, image descriptions, links, and primary sources formatted for the console. Press `q` to return to the article list.
+
+## Topics
+
+Nulltap currently publishes under these topics:
+
+```text
+endpoint
+cloud
+network
+identity
+appsec
+AI
+threats
+```
+
+`nulltap topics` reads the catalog from nulltap.sh and shows every topic, including topics that do not have a published article yet. Topic IDs are case-insensitive.
+
+## Search and recent filters
+
+Search runs locally over the feed already downloaded from nulltap.sh. Search words are not sent to Nulltap or another service.
+
+Every search word must match the title, summary, or a topic tag. Title matches rank first, followed by topic and summary matches. Publication date breaks ties.
+
+Use `--days N` with browsing, topics, or search to limit the downloaded feed by publication time:
+
+```sh
+nulltap search ransomware --days 30
+nulltap topic cloud --days 14
+nulltap topics --days 90
+```
+
+## Automation
+
+Use `--json` for structured output or `--plain` for stable text without menus, color, or a pager:
+
+```sh
+nulltap latest --days 7 --json
+nulltap search ransomware --json
+nulltap topics --plain
+```
+
+Redirected output automatically uses non-interactive mode. Article IDs and slugs remain accepted by `read` for scripts, but ordinary browsing does not require them.
+
+## Network and privacy
+
+Listing and search commands make one read-only request to the public feed. Reading an article makes one additional request for its text. The client has no analytics, account, background process, or local database. Feed and article text are stripped of terminal control sequences before display.
+
+Contributor setup, local feed overrides, and release checks are documented in [CONTRIBUTING.md](https://github.com/JustinHowe/nulltap/blob/main/CONTRIBUTING.md).
+
+Licensed under the MIT License.

nulltap-0.1.1/README.md

@@ -0,0 +1,84 @@
+# nulltap
+
+Read [Nulltap](https://nulltap.sh) from a terminal. Browse recent cybersecurity and AI articles, search the feed, filter by topic, and read the full article without opening a browser.
+
+## Install
+
+Python 3.10 or newer is required. [pipx](https://pipx.pypa.io/) keeps the command in its own environment:
+
+```sh
+pipx install nulltap
+```
+
+To upgrade an existing installation:
+
+```sh
+pipx upgrade nulltap
+```
+
+A regular pip installation also works: `python -m pip install nulltap`.
+
+## Start here
+
+```sh
+nulltap                         # browse recent articles
+nulltap latest --days 7         # articles published in the last seven days
+nulltap topics                  # list every topic and its article count
+nulltap topic identity          # browse one topic
+nulltap search "token theft"    # search titles, summaries, and topic tags
+nulltap read 2                  # read the second result in the terminal
+```
+
+Interactive lists show five articles at a time. Enter a result number to read it, `n` or `p` to change pages, and `q` to leave. Use `--page-size N` if you want a different page size.
+
+Articles open in the terminal pager with headings, lists, quotations, code blocks, image descriptions, links, and primary sources formatted for the console. Press `q` to return to the article list.
+
+## Topics
+
+Nulltap currently publishes under these topics:
+
+```text
+endpoint
+cloud
+network
+identity
+appsec
+AI
+threats
+```
+
+`nulltap topics` reads the catalog from nulltap.sh and shows every topic, including topics that do not have a published article yet. Topic IDs are case-insensitive.
+
+## Search and recent filters
+
+Search runs locally over the feed already downloaded from nulltap.sh. Search words are not sent to Nulltap or another service.
+
+Every search word must match the title, summary, or a topic tag. Title matches rank first, followed by topic and summary matches. Publication date breaks ties.
+
+Use `--days N` with browsing, topics, or search to limit the downloaded feed by publication time:
+
+```sh
+nulltap search ransomware --days 30
+nulltap topic cloud --days 14
+nulltap topics --days 90
+```
+
+## Automation
+
+Use `--json` for structured output or `--plain` for stable text without menus, color, or a pager:
+
+```sh
+nulltap latest --days 7 --json
+nulltap search ransomware --json
+nulltap topics --plain
+```
+
+Redirected output automatically uses non-interactive mode. Article IDs and slugs remain accepted by `read` for scripts, but ordinary browsing does not require them.
+
+## Network and privacy
+
+Listing and search commands make one read-only request to the public feed. Reading an article makes one additional request for its text. The client has no analytics, account, background process, or local database. Feed and article text are stripped of terminal control sequences before display.
+
+Contributor setup, local feed overrides, and release checks are documented in [CONTRIBUTING.md](https://github.com/JustinHowe/nulltap/blob/main/CONTRIBUTING.md).
+
+Licensed under the MIT License.

{nulltap-0.1.0 → nulltap-0.1.1}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nulltap"
-version = "0.1.0"
-description = "Read the nulltap.sh cybersecurity feed from a terminal."
+version = "0.1.1"
+description = "Read Nulltap cybersecurity and AI articles from a terminal."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 authors = [{ name = "Justin Howe" }]
-keywords = ["cybersecurity", "news", "cli", "nulltap"]
+keywords = ["cybersecurity", "ai", "news", "cli", "nulltap"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Environment :: Console",
@@ -29,6 +29,8 @@ nulltap = "nulltap.cli:main"
 [project.urls]
 Homepage = "https://nulltap.sh"
 Repository = "https://github.com/JustinHowe/nulltap"
+Issues = "https://github.com/JustinHowe/nulltap/issues"
+Releases = "https://github.com/JustinHowe/nulltap/releases"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{nulltap-0.1.0 → nulltap-0.1.1}/src/nulltap/__init__.py

@@ -1,3 +1,3 @@
 """nulltap command-line client."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{nulltap-0.1.0 → nulltap-0.1.1}/src/nulltap/cli.py

@@ -14,6 +14,7 @@ import urllib.request
 import webbrowser
 from collections import Counter
 from collections.abc import Callable, Iterable, Sequence
+from datetime import datetime, timedelta, timezone
 from typing import Any, TextIO
 
 from . import __version__
@@ -109,6 +110,35 @@ def normalize_item(raw: Any) -> dict[str, Any] | None:
     }
 
 
+def normalize_topic(raw: Any) -> dict[str, str] | None:
+    if not isinstance(raw, dict):
+        return None
+
+    topic_id = safe_text(raw.get("id") or raw.get("topic")).lower()
+    if not topic_id:
+        return None
+    return {
+        "topic": topic_id,
+        "label": safe_text(raw.get("label")) or topic_id,
+        "description": safe_text(raw.get("description")),
+    }
+
+
+def normalize_feed_payload(payload: Any) -> dict[str, list[dict[str, Any]]]:
+    if not isinstance(payload, dict) or not isinstance(payload.get("items"), list):
+        raise FeedError("feed does not contain an items array")
+
+    items = [item for raw in payload["items"] if (item := normalize_item(raw))]
+    raw_topics = payload.get("topics", [])
+    if not isinstance(raw_topics, list):
+        raw_topics = []
+    topics = [topic for raw in raw_topics if (topic := normalize_topic(raw))]
+    return {
+        "items": sorted(items, key=lambda item: item["date_published"], reverse=True),
+        "topics": list({topic["topic"]: topic for topic in topics}.values()),
+    }
+
+
 def _fetch_json(
     url: str,
     *,
@@ -150,11 +180,11 @@ def _fetch_json(
         raise FeedError(f"{label} returned invalid JSON") from exc
 
 
-def fetch_feed(
+def fetch_feed_document(
     url: str = DEFAULT_FEED_URL,
     timeout: float = 10.0,
     opener: Callable[..., Any] = urllib.request.urlopen,
-) -> list[dict[str, Any]]:
+) -> dict[str, list[dict[str, Any]]]:
     payload = _fetch_json(
         url,
         timeout=timeout,
@@ -163,11 +193,16 @@ def fetch_feed(
         accept="application/feed+json, application/json",
         opener=opener,
     )
-    if not isinstance(payload, dict) or not isinstance(payload.get("items"), list):
-        raise FeedError("feed does not contain an items array")
+    return normalize_feed_payload(payload)
 
-    items = [item for raw in payload["items"] if (item := normalize_item(raw))]
-    return sorted(items, key=lambda item: item["date_published"], reverse=True)
+
+def fetch_feed(
+    url: str = DEFAULT_FEED_URL,
+    timeout: float = 10.0,
+    opener: Callable[..., Any] = urllib.request.urlopen,
+) -> list[dict[str, Any]]:
+    """Return feed items for callers using the 0.1.0 list-based API."""
+    return fetch_feed_document(url, timeout, opener)["items"]
 
 
 def fetch_article(
@@ -219,6 +254,16 @@ def positive_int(value: str) -> int:
     return parsed
 
 
+def positive_days(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be an integer") from exc
+    if parsed < 1 or parsed > 36500:
+        raise argparse.ArgumentTypeError("must be between 1 and 36500")
+    return parsed
+
+
 def build_parser() -> argparse.ArgumentParser:
     common = argparse.ArgumentParser(add_help=False, argument_default=argparse.SUPPRESS)
     common.add_argument(
@@ -230,42 +275,82 @@ def build_parser() -> argparse.ArgumentParser:
     common.add_argument("--json", action="store_true", help="emit JSON for scripts")
     common.add_argument("--plain", action="store_true", help="print once without menus or a pager")
     common.add_argument("--page-size", type=positive_int, metavar="N", help="articles per page (default: 5)")
+    common.add_argument("--days", type=positive_days, metavar="N", help="limit the feed to the last N days")
     common.add_argument("--no-color", action="store_true", help="disable terminal color")
 
     parser = argparse.ArgumentParser(
         prog="nulltap",
         parents=[common],
-        description="Browse and read nulltap from a terminal.",
+        description="Read Nulltap articles without leaving the terminal.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent(
+            """
+            examples:
+              nulltap                         browse recent articles
+              nulltap latest --days 7         show the last seven days
+              nulltap topics                  list the current topic catalog
+              nulltap topic identity          browse one topic
+              nulltap search "token theft"    search titles, summaries, and tags
+              nulltap read 2                  read the second result in the terminal
+
+            Run 'nulltap COMMAND --help' for command-specific options.
+            """
+        ),
     )
     parser.add_argument("--version", action="version", version=f"nulltap {__version__}")
-    subparsers = parser.add_subparsers(dest="command")
+    subparsers = parser.add_subparsers(dest="command", title="commands", metavar="COMMAND")
 
-    browse = subparsers.add_parser("browse", parents=[common], help="browse recent articles")
-    browse.add_argument("-n", "--limit", type=positive_int, default=50)
+    browse = subparsers.add_parser(
+        "browse",
+        parents=[common],
+        help="browse the feed (default)",
+        description="Browse recent Nulltap articles, newest first.",
+    )
+    browse.add_argument("-n", "--limit", type=positive_int, default=50, help="maximum articles shown (default: 50)")
     browse.add_argument("-t", "--topic", help="limit results to one topic")
 
-    latest = subparsers.add_parser("latest", parents=[common], help="browse recent articles")
-    latest.add_argument("-n", "--limit", type=positive_int, default=50)
+    latest = subparsers.add_parser(
+        "latest",
+        parents=[common],
+        help="browse the newest articles",
+        description="Browse the newest Nulltap articles.",
+    )
+    latest.add_argument("-n", "--limit", type=positive_int, default=50, help="maximum articles shown (default: 50)")
     latest.add_argument("-t", "--topic", help="limit results to one topic")
 
-    subparsers.add_parser("topics", parents=[common], help="choose a topic")
+    subparsers.add_parser(
+        "topics",
+        parents=[common],
+        help="list topics or choose one interactively",
+        description="List every Nulltap topic and its article count.",
+    )
 
-    topic = subparsers.add_parser("topic", parents=[common], help="browse articles for one topic")
-    topic.add_argument("name", nargs="?", help="topic name, such as identity or cloud")
-    topic.add_argument("-n", "--limit", type=positive_int, default=100)
+    topic = subparsers.add_parser(
+        "topic",
+        parents=[common],
+        help="browse articles for one topic",
+        description="Browse articles filed under one topic.",
+    )
+    topic.add_argument("name", nargs="?", help="topic ID; run 'nulltap topics' to list them")
+    topic.add_argument("-n", "--limit", type=positive_int, default=100, help="maximum articles shown (default: 100)")
 
-    search = subparsers.add_parser("search", parents=[common], help="search and choose an article")
+    search = subparsers.add_parser(
+        "search",
+        parents=[common],
+        help="search titles, summaries, and topic tags",
+        description="Search article titles, summaries, and topic tags.",
+    )
     search.add_argument("query", nargs="*", help="words to search for")
     search.add_argument("-t", "--topic", help="limit results to one topic")
-    search.add_argument("-n", "--limit", type=positive_int, default=100)
+    search.add_argument("-n", "--limit", type=positive_int, default=100, help="maximum matches shown (default: 100)")
 
-    read = subparsers.add_parser("read", parents=[common], help="read an article or browse when omitted")
+    read = subparsers.add_parser("read", parents=[common], help="read in the terminal or browse when omitted")
     read.add_argument("target", nargs="?", help="result number, article ID, slug, or URL")
 
     show = subparsers.add_parser("show", parents=[common], help="alias for read")
     show.add_argument("target", nargs="?", help="result number, article ID, slug, or URL")
 
-    open_command = subparsers.add_parser("open", parents=[common], help="open one article in a browser")
+    open_command = subparsers.add_parser("open", parents=[common], help="optional handoff to a web browser")
     open_command.add_argument("target", help="result number, article ID, slug, or URL")
 
     return parser
@@ -278,6 +363,33 @@ def filter_topic(items: Iterable[dict[str, Any]], topic: str | None) -> list[dic
     return [item for item in items if wanted in item["tags"]]
 
 
+def filter_days(
+    items: Iterable[dict[str, Any]],
+    days: int | None,
+    *,
+    now: datetime | None = None,
+) -> list[dict[str, Any]]:
+    if not days:
+        return list(items)
+
+    current = now or datetime.now(timezone.utc)
+    if current.tzinfo is None:
+        current = current.replace(tzinfo=timezone.utc)
+    cutoff = current.astimezone(timezone.utc) - timedelta(days=days)
+    selected = []
+    for item in items:
+        raw_date = item.get("date_published", "")
+        try:
+            published = datetime.fromisoformat(raw_date.replace("Z", "+00:00"))
+        except (AttributeError, TypeError, ValueError):
+            continue
+        if published.tzinfo is None:
+            published = published.replace(tzinfo=timezone.utc)
+        if published.astimezone(timezone.utc) >= cutoff:
+            selected.append(item)
+    return selected
+
+
 def search_items(items: Iterable[dict[str, Any]], query: str) -> list[dict[str, Any]]:
     phrase = safe_text(query).lower()
     tokens = [token for token in phrase.split() if token]
@@ -609,23 +721,41 @@ def json_dump(value: Any, stream: TextIO) -> None:
     print(file=stream)
 
 
-def topic_counts(items: Iterable[dict[str, Any]]) -> list[dict[str, Any]]:
+def topic_counts(
+    items: Iterable[dict[str, Any]],
+    catalog: Iterable[dict[str, str]] = (),
+) -> list[dict[str, Any]]:
     counts = Counter(tag for item in items for tag in item["tags"])
-    return [
-        {"topic": topic, "articles": count}
-        for topic, count in sorted(counts.items(), key=lambda row: (-row[1], row[0]))
-    ]
+    rows = []
+    seen = set()
+    for entry in catalog:
+        topic = entry["topic"]
+        if topic in seen:
+            continue
+        seen.add(topic)
+        rows.append({**entry, "articles": counts.get(topic, 0)})
+    for topic, count in sorted(counts.items(), key=lambda row: (-row[1], row[0])):
+        if topic not in seen:
+            rows.append({"topic": topic, "label": topic, "description": "", "articles": count})
+    return rows
 
 
-def choose_topic(items: Sequence[dict[str, Any]], stdin: TextIO, stdout: TextIO, use_color: bool) -> str | None:
-    topics = topic_counts(items)
+def choose_topic(
+    items: Sequence[dict[str, Any]],
+    catalog: Sequence[dict[str, str]],
+    stdin: TextIO,
+    stdout: TextIO,
+    use_color: bool,
+) -> str | None:
+    topics = topic_counts(items, catalog)
     if not topics:
         print("No published topics yet.", file=stdout)
         return None
     print(file=stdout)
     print(paint("Topics", "1;38;5;214", use_color), file=stdout)
     for index, row in enumerate(topics, 1):
-        print(f"[{index}] {row['topic']:<12} {row['articles']} articles", file=stdout)
+        noun = "article" if row["articles"] == 1 else "articles"
+        print(f"[{index}] {row['label']:<12} {row['articles']} {noun}", file=stdout)
     choice = read_prompt("\nChoose a topic number, or q to quit\n> ", stdin, stdout).lower()
     if choice in {"q", "quit", "exit"}:
         return None
@@ -641,7 +771,7 @@ def run(
     stdin: TextIO = sys.stdin,
     stdout: TextIO = sys.stdout,
     stderr: TextIO = sys.stderr,
-    feed_loader: Callable[[str, float], list[dict[str, Any]]] = fetch_feed,
+    feed_loader: Callable[[str, float], Any] = fetch_feed_document,
     article_loader: Callable[[dict[str, Any], float], dict[str, Any]] = fetch_article,
     browser_opener: Callable[..., bool] = webbrowser.open,
     pager: Callable[[str], None] = pydoc.pager,
@@ -659,21 +789,31 @@ def run(
     if timeout <= 0 or timeout > 120:
         parser.error("--timeout must be greater than 0 and no more than 120 seconds")
 
-    items = feed_loader(feed_url, timeout)
+    loaded_feed = feed_loader(feed_url, timeout)
+    if isinstance(loaded_feed, dict):
+        feed = normalize_feed_payload(loaded_feed)
+    else:
+        feed = normalize_feed_payload({"items": list(loaded_feed), "topics": []})
+    items = filter_days(feed["items"], getattr(args, "days", None))
+    topic_catalog = feed["topics"]
     use_color = color_enabled(stdout, no_color)
     interactive = interactive_enabled(stdin, stdout, plain, json_output)
 
     if command == "topics":
-        topics = topic_counts(items)
+        topics = topic_counts(items, topic_catalog)
         if json_output:
             json_dump(topics, stdout)
             return 0
         if interactive:
-            chosen = choose_topic(items, stdin, stdout, use_color)
+            chosen = choose_topic(items, topic_catalog, stdin, stdout, use_color)
             if chosen:
+                chosen_label = next(
+                    (row["label"] for row in topics if row["topic"] == chosen),
+                    chosen,
+                )
                 return browse_items(
                     filter_topic(items, chosen),
-                    heading=f"Topic: {chosen}",
+                    heading=f"Topic: {chosen_label}",
                     page_size=page_size,
                     stdin=stdin,
                     stdout=stdout,
@@ -684,9 +824,9 @@ def run(
                 )
             return 0
         if topics:
-            width = max(len(row["topic"]) for row in topics)
+            width = max(len(row["label"]) for row in topics)
             for row in topics:
-                print(f"{row['topic']:<{width}}  {row['articles']}", file=stdout)
+                print(f"{row['label']:<{width}}  {row['articles']}", file=stdout)
         else:
             print("No published topics yet.", file=stdout)
         return 0
@@ -694,21 +834,24 @@ def run(
     if command == "topic":
         topic_name = args.name
         if not topic_name and interactive:
-            topic_name = choose_topic(items, stdin, stdout, use_color)
+            topic_name = choose_topic(items, topic_catalog, stdin, stdout, use_color)
             if not topic_name:
                 return 0
         if not topic_name:
             print("nulltap: provide a topic name or run this command in a terminal", file=stderr)
             return 1
         selected = filter_topic(items, topic_name)
-        if not selected and items:
-            available = ", ".join(row["topic"] for row in topic_counts(items))
+        available_rows = topic_counts(items, topic_catalog)
+        wanted_topic = safe_text(topic_name).lower()
+        if wanted_topic not in {row["topic"] for row in available_rows}:
+            available = ", ".join(row["topic"] for row in available_rows)
             print(f"nulltap: no topic named '{safe_text(topic_name)}'", file=stderr)
             if available:
                 print(f"available topics: {available}", file=stderr)
             return 1
         selected = selected[: args.limit]
-        heading = f"Topic: {safe_text(topic_name).lower()}"
+        label = next((row["label"] for row in available_rows if row["topic"] == wanted_topic), wanted_topic)
+        heading = f"Topic: {label}"
     elif command == "search":
         query = " ".join(args.query)
         if not query and interactive:

nulltap-0.1.1/src/nulltap.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: nulltap
+Version: 0.1.1
+Summary: Read Nulltap cybersecurity and AI articles from a terminal.
+Author: Justin Howe
+License-Expression: MIT
+Project-URL: Homepage, https://nulltap.sh
+Project-URL: Repository, https://github.com/JustinHowe/nulltap
+Project-URL: Issues, https://github.com/JustinHowe/nulltap/issues
+Project-URL: Releases, https://github.com/JustinHowe/nulltap/releases
+Keywords: cybersecurity,ai,news,cli,nulltap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nulltap
+
+Read [Nulltap](https://nulltap.sh) from a terminal. Browse recent cybersecurity and AI articles, search the feed, filter by topic, and read the full article without opening a browser.
+
+## Install
+
+Python 3.10 or newer is required. [pipx](https://pipx.pypa.io/) keeps the command in its own environment:
+
+```sh
+pipx install nulltap
+```
+
+To upgrade an existing installation:
+
+```sh
+pipx upgrade nulltap
+```
+
+A regular pip installation also works: `python -m pip install nulltap`.
+
+## Start here
+
+```sh
+nulltap                         # browse recent articles
+nulltap latest --days 7         # articles published in the last seven days
+nulltap topics                  # list every topic and its article count
+nulltap topic identity          # browse one topic
+nulltap search "token theft"    # search titles, summaries, and topic tags
+nulltap read 2                  # read the second result in the terminal
+```
+
+Interactive lists show five articles at a time. Enter a result number to read it, `n` or `p` to change pages, and `q` to leave. Use `--page-size N` if you want a different page size.
+
+Articles open in the terminal pager with headings, lists, quotations, code blocks, image descriptions, links, and primary sources formatted for the console. Press `q` to return to the article list.
+
+## Topics
+
+Nulltap currently publishes under these topics:
+
+```text
+endpoint
+cloud
+network
+identity
+appsec
+AI
+threats
+```
+
+`nulltap topics` reads the catalog from nulltap.sh and shows every topic, including topics that do not have a published article yet. Topic IDs are case-insensitive.
+
+## Search and recent filters
+
+Search runs locally over the feed already downloaded from nulltap.sh. Search words are not sent to Nulltap or another service.
+
+Every search word must match the title, summary, or a topic tag. Title matches rank first, followed by topic and summary matches. Publication date breaks ties.
+
+Use `--days N` with browsing, topics, or search to limit the downloaded feed by publication time:
+
+```sh
+nulltap search ransomware --days 30
+nulltap topic cloud --days 14
+nulltap topics --days 90
+```
+
+## Automation
+
+Use `--json` for structured output or `--plain` for stable text without menus, color, or a pager:
+
+```sh
+nulltap latest --days 7 --json
+nulltap search ransomware --json
+nulltap topics --plain
+```
+
+Redirected output automatically uses non-interactive mode. Article IDs and slugs remain accepted by `read` for scripts, but ordinary browsing does not require them.
+
+## Network and privacy
+
+Listing and search commands make one read-only request to the public feed. Reading an article makes one additional request for its text. The client has no analytics, account, background process, or local database. Feed and article text are stripped of terminal control sequences before display.
+
+Contributor setup, local feed overrides, and release checks are documented in [CONTRIBUTING.md](https://github.com/JustinHowe/nulltap/blob/main/CONTRIBUTING.md).
+
+Licensed under the MIT License.

{nulltap-0.1.0 → nulltap-0.1.1}/tests/test_cli.py

@@ -2,10 +2,20 @@ import io
 import json
 import re
 import unittest
+from datetime import datetime, timezone
 from pathlib import Path
 
 from nulltap import __version__
-from nulltap.cli import fetch_feed, normalize_item, render_article, run, search_items
+from nulltap.cli import (
+    build_parser,
+    fetch_feed,
+    fetch_feed_document,
+    filter_days,
+    normalize_item,
+    render_article,
+    run,
+    search_items,
+)
 
 
 ITEMS = [
@@ -35,6 +45,16 @@ ITEMS = [
     },
 ]
 
+TOPICS = [
+    {"id": "endpoint", "label": "endpoint", "description": "Endpoint security."},
+    {"id": "cloud", "label": "cloud", "description": "Cloud security."},
+    {"id": "network", "label": "network", "description": "Network security."},
+    {"id": "identity", "label": "identity", "description": "Identity security."},
+    {"id": "appsec", "label": "appsec", "description": "Application security."},
+    {"id": "ai", "label": "AI", "description": "AI security."},
+    {"id": "threats", "label": "threats", "description": "Threat activity."},
+]
+
 
 class FakeResponse:
     def __init__(self, payload):
@@ -70,7 +90,10 @@ class NulltapCliTests(unittest.TestCase):
             args,
             stdout=stdout,
             stderr=stderr,
-            feed_loader=lambda _url, _timeout: list(ITEMS if items is None else items),
+            feed_loader=lambda _url, _timeout: {
+                "items": list(ITEMS if items is None else items),
+                "topics": TOPICS,
+            },
             article_loader=lambda item, _timeout: {
                 **item,
                 "content_text": "## Access path\n\nThe token crossed a trust boundary.\n\n[Image: Token path]",
@@ -90,7 +113,10 @@ class NulltapCliTests(unittest.TestCase):
             stdin=stdin,
             stdout=stdout,
             stderr=stderr,
-            feed_loader=lambda _url, _timeout: list(ITEMS if items is None else items),
+            feed_loader=lambda _url, _timeout: {
+                "items": list(ITEMS if items is None else items),
+                "topics": TOPICS,
+            },
             article_loader=lambda item, _timeout: {
                 **item,
                 "content_text": "## Access path\n\nThe token crossed a trust boundary.",
@@ -117,8 +143,16 @@ class NulltapCliTests(unittest.TestCase):
         code, stdout, _ = self.invoke(["topics", "--json"])
         self.assertEqual(code, 0)
         topics = json.loads(stdout)
-        self.assertIn({"topic": "identity", "articles": 1}, topics)
-        self.assertIn({"topic": "ai", "articles": 1}, topics)
+        counts = {row["topic"]: row["articles"] for row in topics}
+        self.assertEqual(counts["identity"], 1)
+        self.assertEqual(counts["ai"], 1)
+        self.assertEqual(counts["endpoint"], 0)
+
+    def test_help_surfaces_examples_and_date_filter(self):
+        help_text = build_parser().format_help()
+        self.assertIn("nulltap latest --days 7", help_text)
+        self.assertIn("nulltap topics", help_text)
+        self.assertIn("limit the feed to the last N days", help_text)
 
     def test_search_uses_title_summary_and_tags(self):
         results = search_items(ITEMS, "production credentials")
@@ -177,13 +211,27 @@ class NulltapCliTests(unittest.TestCase):
         self.assertIn("The AI Gateway Had Root", pages[0])
 
     def test_topics_menu_opens_a_topic_and_article(self):
-        code, stdout, _, pages = self.invoke_interactive(["topics"], "1\n1\nq\n")
+        code, stdout, _, pages = self.invoke_interactive(["topics"], "6\n1\nq\n")
         self.assertEqual(code, 0)
         self.assertIn("Topics", stdout)
-        self.assertIn("Topic: ai", stdout)
+        self.assertIn("Topic: AI", stdout)
         self.assertEqual(len(pages), 1)
         self.assertIn("The AI Gateway Had Root", pages[0])
 
+    def test_known_empty_topic_is_not_reported_as_invalid(self):
+        code, stdout, stderr = self.invoke(["topic", "endpoint"])
+        self.assertEqual(code, 0)
+        self.assertIn("No published articles matched.", stdout)
+        self.assertEqual(stderr, "")
+
+    def test_days_filter_uses_publication_time(self):
+        selected = filter_days(
+            ITEMS,
+            1,
+            now=datetime(2026, 7, 26, 18, 0, tzinfo=timezone.utc),
+        )
+        self.assertEqual([item["id"] for item in selected], ["2026-07-26-cloud-token"])
+
     def test_direct_read_uses_pager_in_a_terminal(self):
         code, _, _, pages = self.invoke_interactive(["read", "1"], "")
         self.assertEqual(code, 0)
@@ -246,6 +294,16 @@ class NulltapCliTests(unittest.TestCase):
         self.assertEqual(len(items), 1)
         self.assertEqual(seen, {"url": "https://nulltap.sh/feed.json", "timeout": 3})
 
+    def test_fetch_feed_document_includes_topic_catalog(self):
+        payload = json.dumps({"items": ITEMS, "topics": TOPICS}).encode()
+        document = fetch_feed_document(
+            "https://nulltap.sh/feed.json",
+            3,
+            opener=lambda _request, timeout: FakeResponse(payload),
+        )
+        self.assertEqual(document["topics"][0]["topic"], "endpoint")
+        self.assertEqual(document["topics"][5]["label"], "AI")
+
     def test_unknown_topic_returns_helpful_error(self):
         code, _, stderr = self.invoke(["topic", "nope"])
         self.assertEqual(code, 1)

nulltap-0.1.0/PKG-INFO

@@ -1,98 +0,0 @@
-Metadata-Version: 2.4
-Name: nulltap
-Version: 0.1.0
-Summary: Read the nulltap.sh cybersecurity feed from a terminal.
-Author: Justin Howe
-License-Expression: MIT
-Project-URL: Homepage, https://nulltap.sh
-Project-URL: Repository, https://github.com/JustinHowe/nulltap
-Keywords: cybersecurity,news,cli,nulltap
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Security
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# nulltap
-
-Nulltap in your terminal. This client reads the public [nulltap.sh](https://nulltap.sh) JSON feed and prints cybersecurity and AI coverage without requiring an account.
-
-## Install
-
-Python 3.10 or newer is required. After the first PyPI release, install it with [pipx](https://pipx.pypa.io/):
-
-```sh
-pipx install nulltap
-```
-
-Until then, install the current version from GitHub with `pipx install git+https://github.com/JustinHowe/nulltap.git`.
-
-Run `nulltap --help` after installation.
-
-## Commands
-
-```sh
-nulltap                         # paginated recent articles; type a number to read
-nulltap browse                  # explicit form of the default command
-nulltap latest -n 20            # browse the newest 20 articles
-nulltap latest --topic identity
-nulltap topics                  # choose a topic, then choose an article
-nulltap topic ai                # paginated articles tagged AI
-nulltap topic                   # choose a topic interactively
-nulltap search                  # enter search words interactively
-nulltap search "token theft"
-nulltap search gateway --topic appsec
-nulltap read 1                  # directly read the newest article
-nulltap read                    # browse first when no number is supplied
-nulltap --plain                 # print once; no prompts or pager
-```
-
-Interactive lists show five articles per page so a page fits a normal terminal window. Enter the displayed number to read an article, `n` for the next page, `p` for the previous page, or `q` to leave. Use `--page-size N` to change the page size.
-
-Articles open in the terminal pager. Headings, lists, quotations, code blocks, images, inline links, and primary sources are formatted for terminal reading. Press `q` to leave the pager and return to the article list. No browser is required.
-
-When output is redirected, nulltap automatically disables menus and the pager. `--plain` does the same thing explicitly. Article IDs, slugs, and URLs remain accepted as direct targets for scripts, but ordinary readers should not need them.
-
-## Search
-
-Search belongs in the CLI because it is useful when the browser is not. It runs locally over article titles, summaries, and topic tags. Search terms are never sent to nulltap or another service.
-
-Every word in the query must match. Title matches rank above tag and summary matches, with publication date breaking ties.
-
-## Scripts
-
-Add `--json` to `browse`, `latest`, `topics`, `topic`, `search`, `read`, or `show`:
-
-```sh
-nulltap search ransomware --json
-nulltap topics --json
-```
-
-Use a different compatible feed during development:
-
-```sh
-nulltap --feed http://127.0.0.1:4321/feed.json
-# or
-NULLTAP_FEED_URL=http://127.0.0.1:4321/feed.json nulltap
-```
-
-Listing and search commands make one read-only feed request. Reading an article makes a second request for that article's text. The client has no analytics, login, local database, or background process. Feed and article text are stripped of terminal control sequences before display.
-
-## Development
-
-```sh
-python -m venv .venv
-# Windows: .venv\Scripts\activate
-# macOS/Linux: source .venv/bin/activate
-python -m pip install -e .
-python -m unittest discover -s tests -v
-```
-
-Licensed under the MIT License.

nulltap-0.1.0/README.md

@@ -1,76 +0,0 @@
-# nulltap
-
-Nulltap in your terminal. This client reads the public [nulltap.sh](https://nulltap.sh) JSON feed and prints cybersecurity and AI coverage without requiring an account.
-
-## Install
-
-Python 3.10 or newer is required. After the first PyPI release, install it with [pipx](https://pipx.pypa.io/):
-
-```sh
-pipx install nulltap
-```
-
-Until then, install the current version from GitHub with `pipx install git+https://github.com/JustinHowe/nulltap.git`.
-
-Run `nulltap --help` after installation.
-
-## Commands
-
-```sh
-nulltap                         # paginated recent articles; type a number to read
-nulltap browse                  # explicit form of the default command
-nulltap latest -n 20            # browse the newest 20 articles
-nulltap latest --topic identity
-nulltap topics                  # choose a topic, then choose an article
-nulltap topic ai                # paginated articles tagged AI
-nulltap topic                   # choose a topic interactively
-nulltap search                  # enter search words interactively
-nulltap search "token theft"
-nulltap search gateway --topic appsec
-nulltap read 1                  # directly read the newest article
-nulltap read                    # browse first when no number is supplied
-nulltap --plain                 # print once; no prompts or pager
-```
-
-Interactive lists show five articles per page so a page fits a normal terminal window. Enter the displayed number to read an article, `n` for the next page, `p` for the previous page, or `q` to leave. Use `--page-size N` to change the page size.
-
-Articles open in the terminal pager. Headings, lists, quotations, code blocks, images, inline links, and primary sources are formatted for terminal reading. Press `q` to leave the pager and return to the article list. No browser is required.
-
-When output is redirected, nulltap automatically disables menus and the pager. `--plain` does the same thing explicitly. Article IDs, slugs, and URLs remain accepted as direct targets for scripts, but ordinary readers should not need them.
-
-## Search
-
-Search belongs in the CLI because it is useful when the browser is not. It runs locally over article titles, summaries, and topic tags. Search terms are never sent to nulltap or another service.
-
-Every word in the query must match. Title matches rank above tag and summary matches, with publication date breaking ties.
-
-## Scripts
-
-Add `--json` to `browse`, `latest`, `topics`, `topic`, `search`, `read`, or `show`:
-
-```sh
-nulltap search ransomware --json
-nulltap topics --json
-```
-
-Use a different compatible feed during development:
-
-```sh
-nulltap --feed http://127.0.0.1:4321/feed.json
-# or
-NULLTAP_FEED_URL=http://127.0.0.1:4321/feed.json nulltap
-```
-
-Listing and search commands make one read-only feed request. Reading an article makes a second request for that article's text. The client has no analytics, login, local database, or background process. Feed and article text are stripped of terminal control sequences before display.
-
-## Development
-
-```sh
-python -m venv .venv
-# Windows: .venv\Scripts\activate
-# macOS/Linux: source .venv/bin/activate
-python -m pip install -e .
-python -m unittest discover -s tests -v
-```
-
-Licensed under the MIT License.

nulltap-0.1.0/src/nulltap.egg-info/PKG-INFO

@@ -1,98 +0,0 @@
-Metadata-Version: 2.4
-Name: nulltap
-Version: 0.1.0
-Summary: Read the nulltap.sh cybersecurity feed from a terminal.
-Author: Justin Howe
-License-Expression: MIT
-Project-URL: Homepage, https://nulltap.sh
-Project-URL: Repository, https://github.com/JustinHowe/nulltap
-Keywords: cybersecurity,news,cli,nulltap
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Security
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Dynamic: license-file
-
-# nulltap
-
-Nulltap in your terminal. This client reads the public [nulltap.sh](https://nulltap.sh) JSON feed and prints cybersecurity and AI coverage without requiring an account.
-
-## Install
-
-Python 3.10 or newer is required. After the first PyPI release, install it with [pipx](https://pipx.pypa.io/):
-
-```sh
-pipx install nulltap
-```
-
-Until then, install the current version from GitHub with `pipx install git+https://github.com/JustinHowe/nulltap.git`.
-
-Run `nulltap --help` after installation.
-
-## Commands
-
-```sh
-nulltap                         # paginated recent articles; type a number to read
-nulltap browse                  # explicit form of the default command
-nulltap latest -n 20            # browse the newest 20 articles
-nulltap latest --topic identity
-nulltap topics                  # choose a topic, then choose an article
-nulltap topic ai                # paginated articles tagged AI
-nulltap topic                   # choose a topic interactively
-nulltap search                  # enter search words interactively
-nulltap search "token theft"
-nulltap search gateway --topic appsec
-nulltap read 1                  # directly read the newest article
-nulltap read                    # browse first when no number is supplied
-nulltap --plain                 # print once; no prompts or pager
-```
-
-Interactive lists show five articles per page so a page fits a normal terminal window. Enter the displayed number to read an article, `n` for the next page, `p` for the previous page, or `q` to leave. Use `--page-size N` to change the page size.
-
-Articles open in the terminal pager. Headings, lists, quotations, code blocks, images, inline links, and primary sources are formatted for terminal reading. Press `q` to leave the pager and return to the article list. No browser is required.
-
-When output is redirected, nulltap automatically disables menus and the pager. `--plain` does the same thing explicitly. Article IDs, slugs, and URLs remain accepted as direct targets for scripts, but ordinary readers should not need them.
-
-## Search
-
-Search belongs in the CLI because it is useful when the browser is not. It runs locally over article titles, summaries, and topic tags. Search terms are never sent to nulltap or another service.
-
-Every word in the query must match. Title matches rank above tag and summary matches, with publication date breaking ties.
-
-## Scripts
-
-Add `--json` to `browse`, `latest`, `topics`, `topic`, `search`, `read`, or `show`:
-
-```sh
-nulltap search ransomware --json
-nulltap topics --json
-```
-
-Use a different compatible feed during development:
-
-```sh
-nulltap --feed http://127.0.0.1:4321/feed.json
-# or
-NULLTAP_FEED_URL=http://127.0.0.1:4321/feed.json nulltap
-```
-
-Listing and search commands make one read-only feed request. Reading an article makes a second request for that article's text. The client has no analytics, login, local database, or background process. Feed and article text are stripped of terminal control sequences before display.
-
-## Development
-
-```sh
-python -m venv .venv
-# Windows: .venv\Scripts\activate
-# macOS/Linux: source .venv/bin/activate
-python -m pip install -e .
-python -m unittest discover -s tests -v
-```
-
-Licensed under the MIT License.