newsline-cli 0.1.1

package/README.md

@@ -0,0 +1,86 @@
+# newsline
+
+Locale-aware one-line news in your Claude Code status line — **fully local**, and it
+**composes with your existing status line** (e.g. an HUD) instead of replacing it.
+
+**English** · [한국어](readme/ko.md)
+
+## What it is
+
+A Claude Code status-line utility that shows a rotating, region-appropriate news
+headline at the bottom of your session. Everything runs locally on your machine —
+locale detection, feed fetch, parsing, caching, rendering. It never reads your code,
+prompts, files, or Claude conversations.
+
+## Install
+
+**curl | sh** (macOS / Linux / WSL):
+```sh
+curl -fsSL https://raw.githubusercontent.com/itdar/cc-plugin/master/install.sh | sh
+```
+
+**Homebrew:**
+```sh
+brew install itdar/tap/newsline
+```
+
+**From source:**
+```sh
+git clone https://github.com/itdar/cc-plugin && cd cc-plugin && ./install.sh
+```
+
+The **curl | sh** installer runs setup automatically — it prompts you for a language and
+topic, then wires the status line. For **Homebrew** or **from source**, run setup yourself:
+```sh
+newsline init
+```
+`init` asks for a language and topic (a menu — just pick a number), then registers the
+status line, **keeping whatever status line you already have** (your HUD stays visible,
+news shows on the line below). It appears on your next message to Claude — Claude Code
+hot-reloads settings, so no restart is needed.
+
+_(Skip auto-setup during install with `NEWSLINE_NO_INIT=1`.)_
+
+## Configure
+
+Choose during `newsline init`, or edit `~/.config/newsline/config.json` (or set the env var):
+
+| Key / env var | Default | Meaning |
+|---|---|---|
+| `lang` / `NEWSLINE_LANG` | `auto` | `ko` `ja` `en` `es` `fr` `de` `pt` `zh`, or `auto` |
+| `topic` / `NEWSLINE_TOPIC` | `general` | `general` `tech` `business` `world` `sports` `science` `health` `entertainment` |
+| `rotate` / `NEWSLINE_ROTATE` | `6` | seconds per headline |
+| `count` / `NEWSLINE_COUNT` | `15` | headlines cached for rotation |
+| `maxlen` / `NEWSLINE_MAXLEN` | `120` | max chars; `max` = no truncation; `NN%` ≈ of terminal width |
+| `icon` / `NEWSLINE_ICON` | `📰` | leading glyph; `none` to remove |
+| `linkhint` / `NEWSLINE_LINKHINT` | off | append a `↗` "opens externally" hint |
+| `api` / `NEWSLINE_API` | — | optional curation API (server-first, local fallback) |
+| `endpoint` / `NEWSLINE_ENDPOINT` | — | click-redirect wrapper |
+
+## How it works
+
+- **`newsline render`** (what the status line runs) prints instantly from cache and never
+  blocks; it kicks off a background refresh when the cache is stale.
+- **`newsline refresh`** fetches a keyless regional RSS/Atom feed locally, parses the top
+  headlines, dedupes, and caches them.
+- Headlines are clickable [OSC 8] links. Whether a plain click vs `Cmd`/`Ctrl`+click opens
+  them is decided by your terminal, not by newsline.
+
+## Uninstall
+
+```sh
+newsline uninstall      # removes the wiring and restores your previous status line
+```
+
+## Privacy
+
+Runs locally; detects locale from your system settings (no IP geolocation); fetches public
+feeds directly; never accesses your code, prompts, files, or Claude conversations. Clicks
+pass through a redirect so the project can measure engagement and, in future, use affiliate
+links to fund itself — disclosed here.
+
+## Requirements
+
+`bash`, `python3`. macOS and Linux natively; Windows via WSL or Git Bash.
+
+[OSC 8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

package/feeds.json

@@ -0,0 +1,39 @@
+{
+  "_comment": "locale language -> ordered keyless RSS/Atom feeds. National outlet first (in-language, higher quality), Google News locale feed last as a guaranteed fallback. fetch.py tries each in order; the first that yields an item wins, so a dead/blocked feed is skipped gracefully. All URLs here were reachability-validated. When adding feeds, also add the article-link domain to ../server/allowlist.json.",
+  "en": [
+    "https://feeds.bbci.co.uk/news/rss.xml",
+    "https://feeds.npr.org/1001/rss.xml",
+    "https://news.google.com/rss?hl=en-US&gl=US&ceid=US:en"
+  ],
+  "ko": [
+    "https://www.yna.co.kr/rss/news.xml",
+    "https://news.google.com/rss?hl=ko&gl=KR&ceid=KR:ko"
+  ],
+  "ja": [
+    "https://www.nhk.or.jp/rss/news/cat0.xml",
+    "https://news.google.com/rss?hl=ja&gl=JP&ceid=JP:ja"
+  ],
+  "es": [
+    "https://feeds.elpais.com/mrss-s/pages/ep/site/elpais.com/portada",
+    "https://news.google.com/rss?hl=es&gl=ES&ceid=ES:es"
+  ],
+  "fr": [
+    "https://www.lemonde.fr/rss/une.xml",
+    "https://news.google.com/rss?hl=fr&gl=FR&ceid=FR:fr"
+  ],
+  "de": [
+    "https://www.tagesschau.de/index~rss2.xml",
+    "https://www.spiegel.de/schlagzeilen/tops/index.rss",
+    "https://news.google.com/rss?hl=de&gl=DE&ceid=DE:de"
+  ],
+  "pt": [
+    "https://g1.globo.com/rss/g1/",
+    "https://news.google.com/rss?hl=pt-BR&gl=BR&ceid=BR:pt-419"
+  ],
+  "zh": [
+    "https://news.google.com/rss?hl=zh-CN&gl=CN&ceid=CN:zh-Hans"
+  ],
+  "default": [
+    "https://news.google.com/rss?hl=en-US&gl=US&ceid=US:en"
+  ]
+}

package/fetch.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""newsline · fetch + parse (stdlib only).
+
+Reads a locale-appropriate keyless feed on the USER'S machine, extracts the top
+N headlines, and prints one ready-to-render status line PER headline (newline
+separated). Each line is an OSC 8 terminal hyperlink whose target is the redirect
+wrapper, so the click destination can be swapped to an affiliate URL later,
+server-side, with no plugin change.
+
+Handles both RSS (<channel><item>) and Atom (<feed><entry>).
+
+Usage: fetch.py <lang> <feeds.json> <endpoint> [count]
+Exits non-zero on failure so refresh.sh keeps the previous cache.
+"""
+import os
+import re
+import sys
+import json
+import urllib.request
+import urllib.parse
+import xml.etree.ElementTree as ET
+
+TIMEOUT = 5
+def _maxlen():
+    # NEWSLINE_MAXLEN: a number (chars), "max"/"full" (no truncation), or "NN%"
+    # (approx of $COLUMNS, fallback 120 — exact terminal width isn't available at
+    # fetch time, so % is best-effort). Default 120.
+    raw = (os.environ.get("NEWSLINE_MAXLEN") or "").strip().lower()
+    if raw in ("max", "full", "0", "none"):
+        return 100000
+    if raw.endswith("%"):
+        try:
+            return max(20, int(os.environ.get("COLUMNS") or 120) * int(raw[:-1]) // 100)
+        except Exception:
+            return 120
+    try:
+        return int(raw)
+    except Exception:
+        return 120
+
+
+MAX_TITLE = _maxlen()  # headline truncation length
+
+# Leading glyph: default 📰; set NEWSLINE_ICON="none" to remove, or a custom glyph.
+_icon = os.environ.get("NEWSLINE_ICON", "\U0001F4F0")
+ICON = "" if _icon.strip().lower() in ("none", "off") else _icon
+# Optional trailing "opens externally" hint (↗); off by default.
+LINKHINT = (os.environ.get("NEWSLINE_LINKHINT") or "").strip().lower() in ("1", "true", "yes", "on")
+ATOM = "{http://www.w3.org/2005/Atom}"
+_ws = re.compile(r"\s+")
+
+
+def clean(title):
+    return _ws.sub(" ", title).strip()
+
+
+def parse_items(data):
+    """Return [(title, link), ...] from an RSS or Atom document."""
+    out = []
+    root = ET.fromstring(data)
+
+    # RSS
+    for it in root.findall(".//channel/item"):
+        t = clean(it.findtext("title") or "")
+        l = (it.findtext("link") or "").strip()
+        if t and l:
+            out.append((t, l))
+    if out:
+        return out
+
+    # Atom
+    for e in root.findall(f".//{ATOM}entry"):
+        t = clean(e.findtext(f"{ATOM}title") or "")
+        link = ""
+        for ln in e.findall(f"{ATOM}link"):
+            if ln.get("rel", "alternate") in ("alternate", ""):
+                link = ln.get("href", "").strip()
+                break
+        if t and link:
+            out.append((t, link))
+    return out
+
+
+def top_headlines(urls, count):
+    """First feed that yields items wins; return up to `count` unique ones."""
+    for u in urls:
+        try:
+            req = urllib.request.Request(u, headers={"User-Agent": "newsline/0.1"})
+            data = urllib.request.urlopen(req, timeout=TIMEOUT).read()
+            items = parse_items(data)
+        except Exception:
+            continue
+        seen, picked = set(), []
+        for title, link in items:
+            # collapse auto-generated series like "...시세표(16일)-1/-2/-3" to one
+            key = re.sub(r"\s*-\s*\d+\s*$", "", title).strip().lower()
+            if key in seen:
+                continue
+            seen.add(key)
+            picked.append((title, link))
+            if len(picked) >= count:
+                break
+        if picked:
+            return picked
+    return []
+
+
+def osc8(url, text):
+    esc = "\x1b"  # ESC]8;;URL ESC\  TEXT  ESC]8;;ESC\
+    return f"{esc}]8;;{url}{esc}\\{text}{esc}]8;;{esc}\\"
+
+
+def render(title, link, endpoint, lang):
+    wrapped = endpoint + "?" + urllib.parse.urlencode({"u": link, "c": lang})
+    if len(title) > MAX_TITLE:
+        title = title[: MAX_TITLE - 1] + "…"
+    label = f"{ICON} {title}" if ICON else title
+    if LINKHINT:
+        label = f"{label} ↗"
+    return osc8(wrapped, label)
+
+
+def main():
+    if len(sys.argv) < 4:
+        return 2
+    lang, feeds_path, endpoint = sys.argv[1], sys.argv[2], sys.argv[3]
+    count = int(sys.argv[4]) if len(sys.argv) > 4 else 5
+
+    with open(feeds_path, encoding="utf-8") as f:
+        feeds = json.load(f)
+    urls = feeds.get(lang) or feeds.get("default") or []
+    if not urls:
+        return 1
+
+    picked = top_headlines(urls, count)
+    if not picked:
+        return 1
+
+    for title, link in picked:
+        sys.stdout.write(render(title, link, endpoint, lang) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/install.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env sh
+# newsline · installer — works from a local checkout OR piped from the web:
+#     ./install.sh
+#     curl -fsSL https://raw.githubusercontent.com/itdar/cc-plugin/master/install.sh | sh
+# No build step; copies the scripts onto your PATH. Idempotent (safe to re-run).
+set -eu
+
+REPO="${NEWSLINE_REPO:-itdar/cc-plugin}"
+REF="${NEWSLINE_REF:-master}"
+PREFIX="${NEWSLINE_PREFIX:-$HOME/.local}"
+SHARE="$PREFIX/share/newsline"
+BIN="$PREFIX/bin"
+FILES="newsline statusline.sh refresh.sh fetch.py resolve.py feeds.json"
+
+command -v python3 >/dev/null 2>&1 || { echo "✗ newsline needs python3 (not found)"; exit 1; }
+
+# Source = a local checkout ONLY when actually run as ./install.sh; else (curl|sh) download.
+SELFDIR=""
+case "$0" in */install.sh|install.sh) SELFDIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd -P || true)" ;; esac
+if [ -n "$SELFDIR" ] && [ -f "$SELFDIR/newsline" ] && [ -f "$SELFDIR/fetch.py" ]; then
+  SRCDIR="$SELFDIR"
+else
+  command -v curl >/dev/null 2>&1 || { echo "✗ curl required to download"; exit 1; }
+  TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+  echo "↓ downloading $REPO@$REF …"
+  curl -fsSL "https://github.com/$REPO/archive/refs/heads/$REF.tar.gz" | tar -xz -C "$TMP"
+  SRCDIR="$(find "$TMP" -maxdepth 1 -mindepth 1 -type d | head -1)"
+fi
+
+mkdir -p "$SHARE" "$BIN"
+for f in $FILES; do cp "$SRCDIR/$f" "$SHARE/$f"; done
+chmod +x "$SHARE/newsline" "$SHARE/statusline.sh" "$SHARE/refresh.sh"
+ln -sf "$SHARE/newsline" "$BIN/newsline"
+
+echo "✔ installed: $BIN/newsline"
+
+# Register $BIN on PATH for future shells (idempotent), by shell rc file.
+case ":$PATH:" in
+  *":$BIN:"*)
+    :
+    ;;
+  *)
+    case "$(basename "${SHELL:-sh}")" in
+      zsh)  rc="$HOME/.zshrc"  ; line="export PATH=\"$BIN:\$PATH\"" ;;
+      bash) rc="$HOME/.bashrc" ; line="export PATH=\"$BIN:\$PATH\"" ;;
+      fish) rc="$HOME/.config/fish/config.fish" ; line="fish_add_path \"$BIN\"" ;;
+      *)    rc="$HOME/.profile" ; line="export PATH=\"$BIN:\$PATH\"" ;;
+    esac
+    mkdir -p "$(dirname "$rc")"
+    if [ -f "$rc" ] && grep -qF "$BIN" "$rc" 2>/dev/null; then
+      echo "✔ PATH already configured in $rc"
+    else
+      printf '\n# added by newsline installer\n%s\n' "$line" >> "$rc"
+      echo "✔ added $BIN to PATH in $rc"
+    fi
+    echo
+    echo "→ apply to THIS shell now:   source $rc"
+    echo "  (new terminals apply it automatically)"
+    ;;
+esac
+
+# Auto-setup: run init now (prompts via the terminal even under curl|sh) unless
+# disabled (NEWSLINE_NO_INIT=1) or there is no terminal to prompt from.
+if [ "${NEWSLINE_NO_INIT:-}" != "1" ] && { [ -t 0 ] || [ -r /dev/tty ]; }; then
+  echo
+  "$BIN/newsline" init
+else
+  echo "next:  newsline init"
+fi

package/newsline

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+# newsline — single CLI entrypoint for the local news status-line utility.
+#
+#   newsline init        interactive setup: language, topic, status-line wiring.
+#                        COMPOSES with an existing status line (e.g. your HUD),
+#                        so rate-limit / context info stays visible.
+#   newsline render      what settings.json runs each refresh (base HUD + news).
+#   newsline refresh     force a cache refresh now.
+#   newsline once        fetch + print headlines once (debug).
+#   newsline uninstall   remove the wiring, restore what was there.
+#   newsline help
+#
+# Test overrides: NEWSLINE_SETTINGS, NEWSLINE_CONFIG_DIR, NEWSLINE_CACHE.
+set -u
+
+# resolve our real dir even when invoked via a PATH symlink (so helpers are found)
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  case "$SOURCE" in /*) ;; *) SOURCE="$DIR/$SOURCE" ;; esac
+done
+HERE="$(cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd)"
+CONFIG_DIR="${NEWSLINE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/newsline}"
+CONFIG="$CONFIG_DIR/config.json"
+SETTINGS="${NEWSLINE_SETTINGS:-$HOME/.claude/settings.json}"
+
+# Command written into settings.json. ALWAYS an absolute path — Claude Code runs
+# the status line in a non-login shell whose PATH may not include ~/.local/bin.
+NL_BIN="$(command -v newsline 2>/dev/null || echo "$HERE/newsline")"
+RENDER_CMD="\"$NL_BIN\" render"
+
+# ---- tiny JSON helpers (python; no jq dependency) ----
+cfg_get() { # cfg_get <key>
+  python3 - "$CONFIG" "$1" <<'PY' 2>/dev/null
+import json,sys
+try: d=json.load(open(sys.argv[1]))
+except Exception: d={}
+v=d.get(sys.argv[2])
+print("" if v is None else v)
+PY
+}
+settings_statusline_cmd() { # print current statusLine.command of a settings file
+  python3 - "$1" <<'PY' 2>/dev/null
+import json,sys
+try: d=json.load(open(sys.argv[1]))
+except Exception: d={}
+sl=d.get("statusLine")
+print(sl.get("command","") if isinstance(sl,dict) else "")
+PY
+}
+
+load_config() {
+  [ -f "$CONFIG" ] || return 0
+  local lang topic rotate count api endpoint maxlen icon linkhint
+  lang=$(cfg_get lang);   topic=$(cfg_get topic);   rotate=$(cfg_get rotate)
+  count=$(cfg_get count); api=$(cfg_get api);       endpoint=$(cfg_get endpoint)
+  maxlen=$(cfg_get maxlen); icon=$(cfg_get icon);   linkhint=$(cfg_get linkhint)
+  [ -n "$lang" ] && [ "$lang" != "auto" ] && export NEWSLINE_LANG="$lang"
+  [ -n "$topic" ]    && export NEWSLINE_TOPIC="$topic"
+  [ -n "$rotate" ]   && export NEWSLINE_ROTATE="$rotate"
+  [ -n "$count" ]    && export NEWSLINE_COUNT="$count"
+  [ -n "$maxlen" ]   && export NEWSLINE_MAXLEN="$maxlen"
+  [ -n "$icon" ]     && export NEWSLINE_ICON="$icon"
+  [ -n "$linkhint" ] && export NEWSLINE_LINKHINT="$linkhint"
+  [ -n "$api" ]      && export NEWSLINE_API="$api"
+  [ -n "$endpoint" ] && export NEWSLINE_ENDPOINT="$endpoint"
+}
+
+detect_lang() {
+  local raw="${LC_ALL:-${LC_MESSAGES:-${LANG:-}}}"
+  if command -v defaults >/dev/null 2>&1; then
+    raw="$(defaults read NSGlobalDomain AppleLocale 2>/dev/null || echo "$raw")"
+  fi
+  raw="${raw%%.*}"; raw="${raw%%@*}"; local l="${raw%%_*}"; l="${l%%-*}"
+  echo "${l:-en}"
+}
+
+lang_label() {  # code -> native (English) display name
+  case "$1" in
+    ko) echo "한국어 (Korean)" ;;        ja) echo "日本語 (Japanese)" ;;
+    en) echo "English" ;;                 es) echo "Español (Spanish)" ;;
+    fr) echo "Français (French)" ;;       de) echo "Deutsch (German)" ;;
+    pt) echo "Português (Portuguese)" ;;  zh) echo "中文 (Chinese)" ;;
+    *)  echo "$1" ;;
+  esac
+}
+
+# choose <default_code> <code1> <label1> <code2> <label2> ...  -> sets $CHOICE
+CHOICE=""
+choose() {
+  local def="$1"; shift
+  local -a codes=() labels=()
+  while [ $# -gt 0 ]; do codes+=("$1"); labels+=("${2:-$1}"); shift 2; done
+  local i defnum=1
+  for i in "${!codes[@]}"; do
+    [ "${codes[$i]}" = "$def" ] && defnum=$((i + 1))
+    printf "  %2d) %s\n" "$((i + 1))" "${labels[$i]}" >&2
+  done
+  printf "  # [%d]: " "$defnum" >&2
+  local sel; read -r sel < "${NL_TTY:-/dev/stdin}"
+  case "$sel" in ''|*[!0-9]*) sel="$defnum" ;; esac
+  if [ "$sel" -ge 1 ] 2>/dev/null && [ "$sel" -le "${#codes[@]}" ] 2>/dev/null; then
+    CHOICE="${codes[$((sel - 1))]}"
+  else
+    CHOICE="$def"
+  fi
+}
+
+# ---- subcommands ----
+cmd_render() { # base (existing HUD) first, newsline below — never blocks
+  load_config
+  local base input=""
+  base=$(cfg_get base_statusline)
+  [ -t 0 ] || input=$(cat 2>/dev/null)     # consume the session JSON if piped
+  if [ -n "$base" ]; then
+    printf '%s' "$input" | eval "$base" 2>/dev/null   # your HUD, unchanged
+    printf '\n'
+  fi
+  "$HERE/statusline.sh"                                # the news line, below
+}
+
+cmd_refresh() { load_config; "$HERE/refresh.sh"; }
+
+cmd_once() {
+  load_config; "$HERE/refresh.sh"
+  local dir="${NEWSLINE_CACHE:-$HOME/.cache/newsline}"
+  [ -s "$dir/line" ] && cat "$dir/line" && echo
+}
+
+cmd_init() {
+  local lang="" topic="" api="" endpoint="" rotate="6" count="15" compose="auto" yes="0" base_override="" a
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --lang) lang="$2"; shift 2;;      --topic) topic="$2"; shift 2;;
+      --api) api="$2"; shift 2;;        --endpoint) endpoint="$2"; shift 2;;
+      --rotate) rotate="$2"; shift 2;;  --count) count="$2"; shift 2;;
+      --base) base_override="$2"; shift 2;;
+      --compose) compose="yes"; shift;; --no-compose) compose="no"; shift;;
+      --settings) SETTINGS="$2"; shift 2;; --yes|-y) yes="1"; shift;;
+      *) shift;;
+    esac
+  done
+
+  local detected; detected=$(detect_lang)
+  # Interactive input source: stdin if it's a tty, else the controlling terminal
+  # (/dev/tty) — this lets `curl … | sh` still prompt the user.
+  NL_TTY=""
+  if [ "$yes" = "0" ]; then
+    if [ "${NEWSLINE_FORCE_TTY:-}" = "1" ] || [ -t 0 ]; then NL_TTY=/dev/stdin
+    elif [ -r /dev/tty ]; then NL_TTY=/dev/tty; fi
+  fi
+  if [ -n "$NL_TTY" ]; then
+    if [ -z "$lang" ]; then
+      # languages that actually have bundled feeds, offered as a numbered menu
+      local avail c; local -a menu=(auto "Auto-detect (now: $(lang_label "$detected"))")
+      avail=$(python3 -c "import json,sys;d=json.load(open(sys.argv[1]));print(' '.join(k for k in d if k not in ('default','_comment')))" "$HERE/feeds.json" 2>/dev/null)
+      for c in $avail; do menu+=("$c" "$(lang_label "$c")"); done
+      echo "Select news language:" >&2
+      choose "$detected" "${menu[@]}"; lang="$CHOICE"
+    fi
+    if [ -z "$topic" ]; then
+      echo "Select topic:" >&2
+      choose general \
+        general "General" tech "Tech" business "Business" world "World" \
+        sports "Sports" science "Science" health "Health" entertainment "Entertainment"
+      topic="$CHOICE"
+    fi
+  else
+    lang="${lang:-$detected}"; topic="${topic:-general}"
+  fi
+
+  # Always KEEP an existing status line and show newsline below it (no prompt).
+  # Only --no-compose (or an explicit --base) changes this.
+  local existing base=""
+  if [ -n "$base_override" ]; then
+    base="$base_override"                       # caller supplied the base explicitly
+  elif [ "$compose" != "no" ]; then
+    existing=$(settings_statusline_cmd "$SETTINGS")
+    if [ -n "$existing" ] && ! printf '%s' "$existing" | grep -q "newsline"; then
+      base="$existing"                          # first run: capture the real status line
+    else
+      base=$(cfg_get base_statusline)           # re-init: KEEP the base we already saved
+    fi
+  fi
+
+  mkdir -p "$CONFIG_DIR"
+  python3 - "$CONFIG" "$lang" "$topic" "$rotate" "$count" "$api" "$endpoint" "$base" <<'PY'
+import json,sys
+_,path,lang,topic,rotate,count,api,endpoint,base=sys.argv
+d={"lang":lang,"topic":topic,"rotate":int(rotate),"count":int(count)}
+if api: d["api"]=api
+if endpoint: d["endpoint"]=endpoint
+if base: d["base_statusline"]=base
+json.dump(d,open(path,"w"),indent=2,ensure_ascii=False)
+PY
+
+  python3 - "$SETTINGS" "$RENDER_CMD" <<'PY'
+import json,os,sys
+path,cmd=sys.argv[1],sys.argv[2]
+try: d=json.load(open(path))
+except Exception: d={}
+d["statusLine"]={"type":"command","command":cmd,"refreshInterval":5}
+os.makedirs(os.path.dirname(path) or ".",exist_ok=True)
+json.dump(d,open(path,"w"),indent=2,ensure_ascii=False)
+PY
+
+  echo "✔ newsline installed (lang=$lang, topic=$topic)."
+  [ -n "$base" ] && echo "  composing with your existing status line — it stays visible above the news."
+  echo "  It appears on your next message to Claude — no restart needed."
+}
+
+cmd_uninstall() {
+  local base; base=$(cfg_get base_statusline)
+  python3 - "$SETTINGS" "$base" <<'PY'
+import json,sys
+path,base=sys.argv[1],sys.argv[2]
+try: d=json.load(open(path))
+except Exception: d={}
+sl=d.get("statusLine"); cmd=sl.get("command","") if isinstance(sl,dict) else ""
+if "newsline" in cmd:
+    if base: d["statusLine"]={"type":"command","command":base}
+    else: d.pop("statusLine",None)
+    json.dump(d,open(path,"w"),indent=2,ensure_ascii=False); print("reverted status line")
+else:
+    print("status line not managed by newsline; left as-is")
+PY
+  rm -f "$CONFIG" 2>/dev/null
+  echo "✔ newsline uninstalled."
+}
+
+usage() {
+  cat <<'EOF'
+newsline — local news status-line utility
+  newsline init [--lang ko] [--topic tech]   set up & wire the status line
+  newsline uninstall                          remove & restore previous status line
+EOF
+  if [ "${1:-}" = "--all" ]; then
+    cat <<'EOF'
+
+internal (Claude Code calls these automatically; for debugging only):
+  newsline render      draw the status line now (HUD + news)
+  newsline refresh     force a cache refresh
+  newsline once        fetch + print headlines once
+EOF
+  fi
+}
+
+case "${1:-help}" in
+  render) shift; cmd_render "$@";;
+  refresh) shift; cmd_refresh "$@";;
+  once) shift; cmd_once "$@";;
+  init) shift; cmd_init "$@";;
+  uninstall) shift; cmd_uninstall "$@";;
+  help|-h|--help) shift; usage "$@";;
+  *) usage; exit 1;;
+esac

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "newsline-cli",
+  "version": "0.1.1",
+  "description": "Locale-aware one-line news in your Claude Code status line — local, composes with your existing status line.",
+  "bin": {
+    "newsline": "newsline"
+  },
+  "files": [
+    "newsline",
+    "statusline.sh",
+    "refresh.sh",
+    "fetch.py",
+    "resolve.py",
+    "feeds.json",
+    "install.sh",
+    "README.md",
+    "readme/"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "keywords": [
+    "claude-code",
+    "statusline",
+    "news",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itdar/cc-plugin.git"
+  },
+  "homepage": "https://github.com/itdar/cc-plugin",
+  "license": "MIT"
+}

package/readme/ko.md

@@ -0,0 +1,83 @@
+# newsline
+
+Claude Code 상태줄에 지역·언어에 맞는 뉴스 한 줄 — **완전 로컬**, 그리고 기존 상태줄(예: HUD)을
+**덮지 않고 그 아래에 붙입니다(compose)**.
+
+[English](../README.md) · **한국어**
+
+## 무엇인가
+
+세션 하단에 지역 언어 뉴스 헤드라인을 **회전 표시**하는 Claude Code 상태줄 유틸리티입니다.
+로케일 감지·피드 수집·파싱·캐시·렌더링 전부 **로컬에서** 돌아갑니다. 코드·프롬프트·파일·Claude
+대화는 절대 읽지 않습니다.
+
+## 설치
+
+**curl | sh** (macOS / Linux / WSL):
+```sh
+curl -fsSL https://raw.githubusercontent.com/itdar/cc-plugin/master/install.sh | sh
+```
+
+**Homebrew:**
+```sh
+brew install itdar/tap/newsline
+```
+
+**소스에서:**
+```sh
+git clone https://github.com/itdar/cc-plugin && cd cc-plugin && ./install.sh
+```
+
+**curl | sh** 설치는 셋업까지 **자동**입니다 — 언어·분야를 물어본 뒤 상태줄을 연결해요.
+**Homebrew**나 **소스** 설치는 직접 실행:
+```sh
+newsline init
+```
+`init`이 언어·분야를 물어보고(메뉴에서 번호 선택), 상태줄을 등록합니다. **기존 상태줄은 그대로
+두고**(HUD 유지) 그 아래 줄에 뉴스를 보여줍니다. Claude Code가 설정을 핫리로드하므로 **재시작
+없이 다음 메시지 때 바로** 나타납니다.
+
+_(설치 중 자동 셋업을 끄려면 `NEWSLINE_NO_INIT=1`.)_
+
+## 설정
+
+`newsline init`에서 고르거나, `~/.config/newsline/config.json`을 편집(또는 환경변수 설정):
+
+| 키 / 환경변수 | 기본값 | 의미 |
+|---|---|---|
+| `lang` / `NEWSLINE_LANG` | `auto` | `ko` `ja` `en` `es` `fr` `de` `pt` `zh` 또는 `auto` |
+| `topic` / `NEWSLINE_TOPIC` | `general` | `general` `tech` `business` `world` `sports` `science` `health` `entertainment` |
+| `rotate` / `NEWSLINE_ROTATE` | `6` | 헤드라인당 노출 초 |
+| `count` / `NEWSLINE_COUNT` | `15` | 회전용으로 캐시할 헤드라인 수 |
+| `maxlen` / `NEWSLINE_MAXLEN` | `120` | 최대 글자수; `max`=무제한; `NN%`≈터미널 폭 비율 |
+| `icon` / `NEWSLINE_ICON` | `📰` | 앞 아이콘; `none`이면 제거 |
+| `linkhint` / `NEWSLINE_LINKHINT` | off | 끝에 `↗`(외부 열기) 힌트 추가 |
+| `api` / `NEWSLINE_API` | — | 선택: 큐레이션 API (서버 우선, 실패 시 로컬 폴백) |
+| `endpoint` / `NEWSLINE_ENDPOINT` | — | 클릭 리다이렉트 래퍼 |
+
+## 동작 방식
+
+- **`newsline render`** (상태줄이 호출) — 캐시에서 **즉시** 출력하고 절대 막지 않으며, 캐시가
+  낡았으면 백그라운드 refresh를 트리거합니다.
+- **`newsline refresh`** — keyless 지역 RSS/Atom 피드를 로컬에서 받아 상위 헤드라인을 파싱·중복
+  제거·캐시합니다.
+- 헤드라인은 클릭 가능한 [OSC 8] 링크입니다. 그냥 클릭 vs `Cmd`/`Ctrl`+클릭으로 열리는지는
+  newsline이 아니라 **터미널 설정**이 결정합니다.
+
+## 제거
+
+```sh
+newsline uninstall      # 연결을 제거하고 이전 상태줄로 복구
+```
+
+## 프라이버시
+
+로컬에서 실행되며, 로케일은 시스템 설정에서 감지(IP 지오로케이션 없음), 공개 피드를 직접
+받아옵니다. 코드·프롬프트·파일·Claude 대화는 접근하지 않습니다. 클릭은 리다이렉트를 거치는데,
+이는 참여도 측정과 향후 제휴 링크(운영 자금)를 위한 것이며 여기에 명시합니다.
+
+## 요구사항
+
+`bash`, `python3`. macOS·Linux는 기본 지원, Windows는 WSL 또는 Git Bash.
+
+[OSC 8]: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda

package/refresh.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# newsline · background refresh — detects locale, fetches a keyless regional
+# RSS feed LOCALLY, parses the top headline, and atomically writes the
+# ready-to-print status line (with an OSC 8 click link) to the cache.
+#
+# Safe to run detached (statusline.sh backgrounds it) or standalone for tests:
+#   NEWSLINE_ENDPOINT=http://localhost:8787/r ./refresh.sh && cat ~/.cache/newsline/line
+#
+# Only dependency: python3 (stdlib urllib — no curl, no API key, no server).
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_DIR="${NEWSLINE_CACHE:-$HOME/.cache/newsline}"
+CACHE_FILE="$CACHE_DIR/line"
+FEEDS="${NEWSLINE_FEEDS:-$HERE/feeds.json}"
+# The redirect wrapper you control. This is the ONE remote piece — clicks pass
+# through it so monetization can be switched on later WITHOUT re-shipping.
+ENDPOINT="${NEWSLINE_ENDPOINT:-https://newsline.thesockerrr.workers.dev/r}"
+COUNT="${NEWSLINE_COUNT:-15}"         # how many headlines to cache for rotation
+LOCK="$CACHE_DIR/refresh.lock"
+mkdir -p "$CACHE_DIR" 2>/dev/null
+
+# --- single-flight: if another refresh is already running, bail quietly ---
+if ! mkdir "$LOCK" 2>/dev/null; then exit 0; fi
+trap 'rmdir "$LOCK" 2>/dev/null' EXIT
+
+# --- detect locale language (region-appropriate news) ---
+# priority: explicit NEWSLINE_LANG > macOS system region > locale env vars > en.
+# (macOS terminals often have LANG=en_US even for non-US users, so the system
+#  region AppleLocale is the truer "where am I" signal for regional news.)
+raw="${NEWSLINE_LANG:-}"
+if [ -z "$raw" ] && command -v defaults >/dev/null 2>&1; then
+  raw="$(defaults read NSGlobalDomain AppleLocale 2>/dev/null)"   # e.g. ko_KR
+fi
+[ -z "$raw" ] && raw="${LC_ALL:-${LC_MESSAGES:-${LANG:-}}}"
+case "$raw" in ""|C|POSIX|C.*|POSIX.*) raw="en_US" ;; esac
+lang="${raw%%.*}"    # strip .UTF-8
+lang="${lang%%@*}"   # strip @variant
+lang="${lang%%_*}"   # strip _REGION
+lang="${lang%%-*}"   # strip -Script (e.g. zh-Hans)
+[ -z "$lang" ] && lang="en"
+
+# derive coarse country/region from raw (ko_KR -> KR); empty if none
+reg="${raw%%.*}"; reg="${reg%%@*}"
+case "$reg" in
+  *_*) country="${reg#*_}"; country="${country%%-*}" ;;
+  *)   country="" ;;
+esac
+
+# --- server-first feed selection (COARSE context only), local fallback ---
+# resolve.py tries $NEWSLINE_API/feed; on any failure it returns local feeds.json.
+# We send lang/country/localtime/dow/tz only — no personal data, no tracking id.
+RESOLVED="$CACHE_DIR/feeds.resolved.json"
+export NEWSLINE_COUNTRY="$country"
+export NEWSLINE_LOCALTIME="$(date +%H%M)"
+export NEWSLINE_DOW="$(date +%u)"
+export NEWSLINE_TZ="$(date +%z)"
+if ! python3 "$HERE/resolve.py" "$lang" "$FEEDS" "${NEWSLINE_API:-https://newsline.thesockerrr.workers.dev}" > "$RESOLVED" 2>/dev/null \
+   || [ ! -s "$RESOLVED" ]; then
+  cp "$FEEDS" "$RESOLVED" 2>/dev/null   # last-ditch fallback to bundled feeds
+fi
+
+# --- fetch + parse + build the line; write atomically, keep old cache on failure ---
+if python3 "$HERE/fetch.py" "$lang" "$RESOLVED" "$ENDPOINT" "$COUNT" > "$CACHE_DIR/line.tmp" 2>/dev/null \
+   && [ -s "$CACHE_DIR/line.tmp" ]; then
+  mv -f "$CACHE_DIR/line.tmp" "$CACHE_FILE"
+else
+  rm -f "$CACHE_DIR/line.tmp" 2>/dev/null   # graceful fallback: previous cache stays
+fi

package/resolve.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""newsline · resolve which feeds to use — server-first, local fallback, topic-aware.
+
+Tries the operator's curation API (NEWSLINE_API) with a short timeout, sending only
+COARSE CONTEXT (lang, country, localtime, dow, tz, topic) — never personal data. On
+ANY failure it falls back to the bundled feeds.json. If a topic preference is set
+(NEWSLINE_TOPIC), a keyless Google News topic feed is prepended so that topic leads.
+
+Prints a feeds.json-shaped object fetch.py consumes:  {"<lang>": [...], "default": [...]}
+
+Usage: resolve.py <lang> <local_feeds.json> [api_base]
+Context from env: NEWSLINE_COUNTRY, NEWSLINE_LOCALTIME, NEWSLINE_DOW, NEWSLINE_TZ, NEWSLINE_TOPIC
+"""
+import os
+import sys
+import json
+import urllib.request
+import urllib.parse
+
+TIMEOUT = float(os.environ.get("NEWSLINE_API_TIMEOUT") or 2)
+
+# user-friendly topic -> Google News section topic
+GN_TOPICS = {
+    "tech": "TECHNOLOGY", "technology": "TECHNOLOGY",
+    "business": "BUSINESS", "biz": "BUSINESS",
+    "sports": "SPORTS", "sport": "SPORTS",
+    "world": "WORLD", "international": "WORLD",
+    "science": "SCIENCE", "sci": "SCIENCE",
+    "health": "HEALTH",
+    "entertainment": "ENTERTAINMENT", "ent": "ENTERTAINMENT",
+    "nation": "NATION", "national": "NATION",
+}
+LANG_COUNTRY = {"ko": "KR", "ja": "JP", "en": "US", "de": "DE",
+                "fr": "FR", "es": "ES", "pt": "BR", "zh": "CN"}
+
+
+def topic_feed(lang, country, topic):
+    topic = (topic or "").strip().lower()
+    if topic in ("", "general", "all", "none"):
+        return None
+    t = GN_TOPICS.get(topic)
+    if not t:
+        return None
+    gl = country or LANG_COUNTRY.get(lang, lang.upper())
+    return (f"https://news.google.com/rss/headlines/section/topic/{t}"
+            f"?hl={lang}&gl={gl}&ceid={gl}:{lang}")
+
+
+def local_feeds(lang, path):
+    try:
+        feeds = json.load(open(path, encoding="utf-8"))
+    except Exception:
+        feeds = {}
+    default = feeds.get("default") or []
+    return (feeds.get(lang) or default or []), default
+
+
+def server_feeds(lang, api_base):
+    params = {
+        "lang": lang,
+        "country": os.environ.get("NEWSLINE_COUNTRY", ""),
+        "localtime": os.environ.get("NEWSLINE_LOCALTIME", ""),
+        "dow": os.environ.get("NEWSLINE_DOW", ""),
+        "tz": os.environ.get("NEWSLINE_TZ", ""),
+        "topic": os.environ.get("NEWSLINE_TOPIC", ""),
+    }
+    url = api_base.rstrip("/") + "/feed?" + urllib.parse.urlencode(params)
+    req = urllib.request.Request(url, headers={"User-Agent": "newsline/0.1"})
+    obj = json.loads(urllib.request.urlopen(req, timeout=TIMEOUT).read())
+    feeds = obj.get("feeds")
+    if isinstance(feeds, list) and feeds and all(isinstance(x, str) for x in feeds):
+        return feeds
+    return None
+
+
+def main():
+    if len(sys.argv) < 3:
+        return 2
+    lang, local_path = sys.argv[1], sys.argv[2]
+    api_base = sys.argv[3] if len(sys.argv) > 3 else os.environ.get("NEWSLINE_API", "")
+
+    local_urls, default = local_feeds(lang, local_path)
+
+    feeds = None
+    if api_base:
+        try:
+            feeds = server_feeds(lang, api_base)   # server-first
+        except Exception:
+            feeds = None                            # any issue -> local fallback
+    feeds = feeds or local_urls or default
+
+    # topic preference leads (keyless Google News topic feed), general as backup
+    tfeed = topic_feed(lang, os.environ.get("NEWSLINE_COUNTRY", ""), os.environ.get("NEWSLINE_TOPIC", ""))
+    if tfeed:
+        feeds = [tfeed] + [f for f in feeds if f != tfeed]
+
+    if not feeds:
+        return 1
+    sys.stdout.write(json.dumps({lang: feeds, "default": default or feeds}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/statusline.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# newsline · statusLine entry — MUST stay fast. Prints the cached headline
+# instantly and, if the cache is stale, kicks off a DETACHED background
+# refresh. It never fetches in the foreground, so the status line never lags.
+#
+# Wire it into ~/.claude/settings.json via settings.snippet.json.
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CACHE_DIR="${NEWSLINE_CACHE:-$HOME/.cache/newsline}"
+CACHE_FILE="$CACHE_DIR/line"
+TTL="${NEWSLINE_TTL:-900}"          # refresh cache older than this many seconds
+mkdir -p "$CACHE_DIR" 2>/dev/null
+
+# --- decide whether a refresh is due (missing or older than TTL) ---
+needs_refresh=1
+if [ -f "$CACHE_FILE" ]; then
+  now=$(date +%s)
+  mtime=$(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0)
+  if [ $((now - mtime)) -lt "$TTL" ]; then needs_refresh=0; fi
+fi
+
+# --- fire-and-forget background refresh; never block the status line ---
+if [ "$needs_refresh" = "1" ]; then
+  ( "$HERE/refresh.sh" >/dev/null 2>&1 & ) 2>/dev/null
+fi
+
+# --- print one headline, rotating across the cached set by wall-clock time ---
+# The cache holds N headlines (one per line). We show a different one every
+# NEWSLINE_ROTATE seconds — a ticker feel with zero stored state.
+if [ -s "$CACHE_FILE" ]; then
+  n=$(awk 'END{print NR}' "$CACHE_FILE" 2>/dev/null)
+  if [ "${n:-0}" -gt 0 ] 2>/dev/null; then
+    rot="${NEWSLINE_ROTATE:-6}"          # seconds each headline stays up
+    now="${NEWSLINE_NOW:-$(date +%s)}"   # NEWSLINE_NOW overrides clock (tests/debug)
+    idx=$(( (now / rot) % n + 1 ))
+    sed -n "${idx}p" "$CACHE_FILE"
+  else
+    printf '📰 …'
+  fi
+else
+  printf '📰 …'   # first run, before the first refresh lands
+fi