@celsoft/coordinator 0.0.0 → 0.1.0

package/skills/extra/skills/serve/scripts/serve

@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+#
+# serve: start, list, and stop throwaway local HTTP servers.
+#
+# One python3 process per server, detached, with live reload, an idle timeout,
+# and a request log. State lives in one JSON file per server so `list` and
+# `stop` work from any session.
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SERVER="$HERE/server.py"
+STATE_DIR="$HOME/.cache/claude-serve"
+
+die() { echo "FAIL: $*" >&2; exit 1; }
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  serve start <file-or-dir> [--allow GLOB]... [--idle MIN]
+                            [--no-reload] [--bind WHERE]
+  serve list
+  serve stop <id|port|all>
+  serve log <id|port> [-n LINES]
+  serve hosts
+
+--allow takes a glob relative to the served root; repeat it for more.
+Without any --allow the whole tree is served, which can leak secrets.
+--bind is local (default), lan, tailscale, or a literal address.
+The port is chosen automatically (first free from 8000 up) and reported in the URL.
+Defaults: live reload on, 30 min idle timeout.
+USAGE
+}
+
+py() { command -v python3 >/dev/null 2>&1 || die "python3 not found"; }
+
+# Print the state file matching an id or port, or nothing.
+find_state() {
+  local want="$1" f
+  for f in "$STATE_DIR"/*.json; do
+    [ -e "$f" ] || continue
+    if [ "$(basename "$f" .json)" = "$want" ]; then echo "$f"; return; fi
+    if [ "$(field "$f" port)" = "$want" ]; then echo "$f"; return; fi
+  done
+}
+
+field() {
+  python3 - "$1" "$2" <<'PY'
+import json, sys
+try:
+    v = json.load(open(sys.argv[1])).get(sys.argv[2], "")
+    print(", ".join(v) if isinstance(v, list) else v)
+except Exception:
+    print("")
+PY
+}
+
+# Drop state files whose process is gone, and the logs left behind with them.
+reap() {
+  local f pid id
+  for f in "$STATE_DIR"/*.json; do
+    [ -e "$f" ] || continue
+    pid="$(field "$f" pid)"
+    if [ -z "$pid" ] || ! kill -0 "$pid" 2>/dev/null; then rm -f "$f"; fi
+  done
+  # A log outlives its server so `serve log` still works right after a stop.
+  # Anything older than a day has no reader left.
+  for f in "$STATE_DIR"/*.log; do
+    [ -e "$f" ] || continue
+    id="$(basename "$f" .log)"
+    [ -e "$STATE_DIR/$id.json" ] && continue
+    find "$f" -mtime +1 -delete 2>/dev/null || true
+  done
+}
+
+# --- bind targets -----------------------------------------------------------
+
+default_iface() {
+  route -n get default 2>/dev/null | awk '/interface:/{print $2; exit}'
+}
+
+lan_ip() {
+  local iface
+  iface="$(default_iface)"
+  if [ -n "$iface" ]; then
+    ipconfig getifaddr "$iface" 2>/dev/null && return
+  fi
+  ip -4 route get 1.1.1.1 2>/dev/null | awk '/src/{print $7; exit}'
+}
+
+ts_bin() {
+  command -v tailscale 2>/dev/null && return
+  [ -x /Applications/Tailscale.app/Contents/MacOS/Tailscale ] \
+    && echo /Applications/Tailscale.app/Contents/MacOS/Tailscale
+}
+
+ts_ip() {
+  local bin
+  bin="$(ts_bin)" || return 0
+  [ -n "$bin" ] || return 0
+  "$bin" ip -4 2>/dev/null | head -1
+}
+
+ts_name() {
+  local bin
+  bin="$(ts_bin)" || return 0
+  [ -n "$bin" ] || return 0
+  "$bin" status --json 2>/dev/null | python3 -c '
+import json, sys
+try:
+    print(json.load(sys.stdin).get("Self", {}).get("DNSName", "").rstrip("."))
+except Exception:
+    pass
+' 2>/dev/null
+}
+
+# Resolve a bind choice to "ADDR LABEL". Empty output means unavailable.
+resolve_bind() {
+  local choice="$1" addr label
+  case "$choice" in
+    local|localhost) echo "127.0.0.1 localhost" ;;
+    lan|host)
+      addr="$(lan_ip)"
+      [ -n "$addr" ] && echo "$addr $addr"
+      ;;
+    tailscale|ts)
+      addr="$(ts_ip)"
+      [ -n "$addr" ] || return 0
+      label="$(ts_name)"
+      echo "$addr ${label:-$addr}"
+      ;;
+    *) echo "$choice $choice" ;;
+  esac
+}
+
+cmd_hosts() {
+  local r
+  r="$(resolve_bind local)";     echo "local: $r"
+  r="$(resolve_bind lan)";       echo "lan: ${r:-UNAVAILABLE}"
+  r="$(resolve_bind tailscale)"; echo "tailscale: ${r:-UNAVAILABLE}"
+}
+
+cmd_start() {
+  py
+  local target="" idle=30 bind=local noreload=""
+  local -a allows
+  allows=()
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --idle) idle="$2"; shift 2 ;;
+      --no-reload) noreload="--no-reload"; shift ;;
+      --bind) bind="$2"; shift 2 ;;
+      --allow) allows+=("--allow" "$2"); shift 2 ;;
+      -h|--help) usage; exit 0 ;;
+      -*) die "unknown flag $1" ;;
+      *) target="$1"; shift ;;
+    esac
+  done
+  [ -n "$target" ] || die "no path given"
+  [ -e "$target" ] || die "no such path: $target"
+
+  local resolved host label
+  resolved="$(resolve_bind "$bind")"
+  [ -n "$resolved" ] || die "bind target '$bind' is unavailable; run: serve hosts"
+  host="${resolved%% *}"
+  label="${resolved##* }"
+
+  local root entry
+  if [ -d "$target" ]; then
+    root="$(cd "$target" && pwd)"
+    entry="/"
+  else
+    root="$(cd "$(dirname "$target")" && pwd)"
+    entry="/$(basename "$target")"
+    [ ${#allows[@]} -eq 0 ] && allows=("--allow" "$(basename "$target")")
+  fi
+
+  mkdir -p "$STATE_DIR"
+  reap
+  local id state log
+  id="$(python3 -c 'import secrets; print(secrets.token_hex(4))')"
+  state="$STATE_DIR/$id.json"
+  log="$STATE_DIR/$id.log"
+  : > "$log"
+
+  nohup python3 "$SERVER" \
+    --root "$root" --state "$state" --log "$log" --entry "$entry" \
+    --idle "$idle" --host "$host" --label "$label" "${allows[@]}" $noreload \
+    >>"$log" 2>&1 &
+  disown 2>/dev/null || true
+
+  local i=0
+  while [ $i -lt 60 ]; do
+    [ -s "$state" ] && break
+    sleep 0.1
+    i=$((i + 1))
+  done
+  [ -s "$state" ] || { echo "--- log ---"; tail -20 "$log"; die "server did not start"; }
+
+  echo "URL: $(field "$state" url)"
+  echo "ID: $id"
+  echo "ROOT: $root"
+  echo "RELOAD: $(field "$state" reload)"
+  echo "BIND: $host"
+  echo "ALLOW: $(field "$state" allow)"
+  echo "MATCHED: $(field "$state" matched) file(s)"
+  if [ ${#allows[@]} -eq 0 ]; then
+    echo "WARNING: no --allow given; the entire tree under ROOT is served."
+  fi
+  echo "IDLE_MINUTES: $idle"
+  echo "LOG: $log"
+}
+
+cmd_list() {
+  mkdir -p "$STATE_DIR"
+  reap
+  local f found=0
+  for f in "$STATE_DIR"/*.json; do
+    [ -e "$f" ] || continue
+    found=1
+    echo "$(basename "$f" .json)  $(field "$f" url)  $(field "$f" root)"
+  done
+  [ "$found" = 1 ] || echo "NONE"
+}
+
+cmd_stop() {
+  [ $# -ge 1 ] || die "stop needs an id, a port, or 'all'"
+  mkdir -p "$STATE_DIR"
+  if [ "$1" = "all" ]; then
+    local f pid stopped=0
+    for f in "$STATE_DIR"/*.json; do
+      [ -e "$f" ] || continue
+      pid="$(field "$f" pid)"
+      [ -n "$pid" ] && kill "$pid" 2>/dev/null || true
+      rm -f "$f"
+      stopped=$((stopped + 1))
+    done
+    echo "STOPPED: $stopped"
+    return
+  fi
+  local state pid
+  state="$(find_state "$1")"
+  [ -n "$state" ] || die "no server matching $1"
+  pid="$(field "$state" pid)"
+  [ -n "$pid" ] && kill "$pid" 2>/dev/null || true
+  rm -f "$state"
+  echo "STOPPED: $1"
+}
+
+cmd_log() {
+  [ $# -ge 1 ] || die "log needs an id or a port"
+  local state lines=40
+  state="$(find_state "$1")"
+  [ -n "$state" ] || die "no server matching $1"
+  shift
+  [ "${1:-}" = "-n" ] && lines="$2"
+  tail -n "$lines" "$(field "$state" log)"
+}
+
+case "${1:-}" in
+  start) shift; cmd_start "$@" ;;
+  list) shift; cmd_list "$@" ;;
+  stop) shift; cmd_stop "$@" ;;
+  log) shift; cmd_log "$@" ;;
+  hosts) shift; cmd_hosts "$@" ;;
+  -h|--help|"") usage ;;
+  *) usage; exit 1 ;;
+esac

package/skills/extra/skills/serve/scripts/server.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Static file server with live reload, an idle timeout, and a request log.
+
+Only files matching an explicit allowlist of glob patterns are served, listed,
+or watched. Patterns are relative to the served root and are re-evaluated per
+request, so a file created later that matches an existing pattern is served
+without a restart.
+
+Run by the `serve` wrapper, never directly. Binds, then writes its state file so
+the wrapper can report the port it actually got.
+"""
+
+import argparse
+import atexit
+import errno
+import glob
+import html
+import json
+import os
+import signal
+import sys
+import threading
+import time
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, unquote, urlparse
+
+MAX_MATCHES = 20000
+POLL_HOLD = 25.0
+
+state = {}
+last_request = time.monotonic()
+_token = ("", 0.0)
+_token_lock = threading.Lock()
+
+RELOAD_JS = """
+<script>(function(){var v=null;function poll(){fetch('/__reload'+(v?'?v='+encodeURIComponent(v):''),{cache:'no-store'})
+.then(function(r){return r.json()}).then(function(d){if(v===null){v=d.v;return poll()}
+if(d.v!==v){location.reload();return}poll()}).catch(function(){setTimeout(poll,1500)})}poll()})();</script>
+"""
+
+
+class Allowlist:
+    """The set of files this server will serve, from stdlib glob patterns.
+
+    Expanding the patterns (rather than matching a request path against them)
+    means `**`, `*`, `?` and character classes behave exactly as glob does, with
+    no pattern semantics reimplemented here. The expansion is cached briefly so
+    a burst of requests for one page costs one filesystem scan, and refreshes
+    often enough that a newly created matching file appears on its own.
+    """
+
+    TTL = 1.0
+
+    def __init__(self, root, patterns):
+        self.root = root
+        self.real_root = os.path.realpath(root)
+        self.patterns = patterns
+        self._files = frozenset()
+        self._stamp = 0.0
+        self._lock = threading.Lock()
+
+    def _expand(self):
+        found = set()
+        for pattern in self.patterns:
+            target = os.path.join(glob.escape(self.root), pattern)
+            for hit in glob.iglob(target, recursive=True):
+                if not os.path.isfile(hit):
+                    continue
+                # Patterns are relative to the root, so a match that resolves
+                # outside it (via a symlink) is not what was asked for.
+                real = os.path.realpath(hit)
+                if not real.startswith(self.real_root + os.sep):
+                    continue
+                found.add(os.path.relpath(hit, self.root))
+                if len(found) >= MAX_MATCHES:
+                    return found
+        return found
+
+    def files(self):
+        now = time.monotonic()
+        with self._lock:
+            if self._files is not None and now - self._stamp < self.TTL:
+                return self._files
+        expanded = frozenset(self._expand())
+        with self._lock:
+            self._files = expanded
+            self._stamp = now
+        return expanded
+
+    def allows(self, rel):
+        return rel in self.files()
+
+    def under(self, rel):
+        """Relative paths allowed beneath a directory, for listings."""
+        prefix = "" if rel in (".", "") else rel.rstrip("/") + "/"
+        return sorted(f for f in self.files() if f.startswith(prefix))
+
+
+def snapshot(allowlist):
+    latest = 0.0
+    count = 0
+    for rel in allowlist.files():
+        try:
+            mtime = os.stat(os.path.join(allowlist.root, rel)).st_mtime
+        except OSError:
+            continue
+        latest = max(latest, mtime)
+        count += 1
+    return "%.3f:%d" % (latest, count)
+
+
+def token(allowlist):
+    global _token
+    with _token_lock:
+        value, stamp = _token
+        now = time.monotonic()
+        if not value or now - stamp > 0.3:
+            value = snapshot(allowlist)
+            _token = (value, now)
+        return value
+
+
+def inject(body):
+    lower = body.lower()
+    idx = lower.rfind(b"</body>")
+    if idx == -1:
+        return body + RELOAD_JS.encode()
+    return body[:idx] + RELOAD_JS.encode() + body[idx:]
+
+
+class Handler(SimpleHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def __init__(self, *args, root=None, reload_enabled=True, log_path=None,
+                 allowlist=None, **kwargs):
+        self.root = root
+        self.reload_enabled = reload_enabled
+        self.log_path = log_path
+        self.allowlist = allowlist
+        super().__init__(*args, directory=root, **kwargs)
+
+    def log_message(self, fmt, *args):
+        line = "%s %s\n" % (time.strftime("%H:%M:%S"), fmt % args)
+        try:
+            with open(self.log_path, "a") as fh:
+                fh.write(line)
+        except OSError:
+            pass
+
+    def log_request(self, code="-", size="-"):
+        if urlparse(self.path).path == "/__reload":
+            return
+        super().log_request(code, size)
+
+    def rel_for(self, url_path):
+        """Requested URL path as a root-relative path, or None if it escapes."""
+        clean = unquote(urlparse(url_path).path)
+        joined = os.path.normpath(os.path.join(self.root, clean.lstrip("/")))
+        try:
+            rel = os.path.relpath(joined, self.root)
+        except ValueError:
+            return None
+        if rel == ".." or rel.startswith(".." + os.sep):
+            return None
+        return rel
+
+    def do_GET(self):
+        global last_request
+        last_request = time.monotonic()
+        if urlparse(self.path).path == "/__reload":
+            return self.serve_reload()
+
+        rel = self.rel_for(self.path)
+        if rel is None:
+            return self.send_error(404, "Not Found")
+
+        if self.allowlist.allows(rel):
+            target = os.path.join(self.root, rel)
+            if self.reload_enabled and rel.endswith((".html", ".htm")):
+                return self.serve_html(target)
+            return self.serve_file(target)
+
+        # A directory-ish request: fall back to its index, else list what is
+        # allowed beneath it.
+        for index in ("index.html", "index.htm"):
+            candidate = index if rel in (".", "") else rel.rstrip("/") + "/" + index
+            if self.allowlist.allows(candidate):
+                return self.serve_html(os.path.join(self.root, candidate))
+        under = self.allowlist.under(rel)
+        if under:
+            return self.list_allowed(rel, under)
+
+        self.log_message('BLOCKED "%s" (no allow pattern matches)', self.path)
+        return self.send_error(404, "Not Found")
+
+    def do_HEAD(self):
+        global last_request
+        last_request = time.monotonic()
+        rel = self.rel_for(self.path)
+        if rel is None or not self.allowlist.allows(rel):
+            return self.send_error(404, "Not Found")
+        return super().do_HEAD()
+
+    def send_body(self, body, ctype):
+        self.send_response(200)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def serve_file(self, target):
+        ctype = self.guess_type(target)
+        try:
+            with open(target, "rb") as fh:
+                body = fh.read()
+        except OSError:
+            return self.send_error(404, "Not Found")
+        self.send_body(body, ctype)
+
+    def serve_html(self, target):
+        try:
+            with open(target, "rb") as fh:
+                body = fh.read()
+        except OSError:
+            return self.send_error(404, "Not Found")
+        if self.reload_enabled:
+            body = inject(body)
+        self.send_body(body, "text/html; charset=utf-8")
+
+    def list_allowed(self, rel, under):
+        shown = html.escape(urlparse(self.path).path, quote=False)
+        base = "" if rel in (".", "") else rel.rstrip("/") + "/"
+        rows = []
+        for item in under:
+            label = html.escape(item[len(base):], quote=True)
+            rows.append('<li><a href="%s">%s</a></li>' % (label, label))
+        body = (
+            "<!doctype html><meta charset=utf-8><title>%s</title>"
+            "<h1>%s</h1><ul>%s</ul>" % (shown, shown, "".join(rows))
+        )
+        if self.reload_enabled:
+            body += RELOAD_JS
+        self.send_body(body.encode(), "text/html; charset=utf-8")
+
+    def serve_reload(self):
+        have = (parse_qs(urlparse(self.path).query).get("v") or [""])[0]
+        deadline = time.monotonic() + POLL_HOLD
+        current = token(self.allowlist)
+        while current == have and time.monotonic() < deadline:
+            time.sleep(0.4)
+            current = token(self.allowlist)
+        self.send_body(json.dumps({"v": current}).encode(), "application/json")
+
+
+def bind(host, span):
+    first = 8000
+    last = first + span
+    for port in range(first, last + 1):
+        try:
+            server = ThreadingHTTPServer((host, port), lambda *a, **k: None)
+        except OSError as exc:
+            if exc.errno in (errno.EADDRINUSE, errno.EACCES):
+                continue
+            raise
+        server.server_close()
+        return port
+    raise SystemExit("FAIL: no free port in %d-%d" % (first, last))
+
+
+def watchdog(idle_seconds, server):
+    while True:
+        time.sleep(5)
+        if time.monotonic() - last_request > idle_seconds:
+            server.shutdown()
+            return
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", required=True)
+    ap.add_argument("--state", required=True)
+    ap.add_argument("--log", required=True)
+    ap.add_argument("--entry", default="/")
+    ap.add_argument("--allow", action="append", default=[])
+    ap.add_argument("--idle", type=float, default=30.0)
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--label", default="")
+    ap.add_argument("--no-reload", action="store_true")
+    args = ap.parse_args()
+
+    root = os.path.abspath(args.root)
+    patterns = args.allow or ["**"]
+    allowlist = Allowlist(root, patterns)
+    port = bind(args.host, 99)
+    handler = partial(
+        Handler, root=root, reload_enabled=not args.no_reload, log_path=args.log,
+        allowlist=allowlist,
+    )
+    server = ThreadingHTTPServer((args.host, port), handler)
+    server.daemon_threads = True
+
+    host_label = args.label or args.host
+    state.update(
+        id=os.path.basename(args.state).removesuffix(".json"),
+        pid=os.getpid(),
+        port=port,
+        root=root,
+        entry=args.entry,
+        url="http://%s:%d%s" % (host_label, port, args.entry),
+        log=args.log,
+        reload=not args.no_reload,
+        allow=patterns,
+        matched=len(allowlist.files()),
+        idle_minutes=args.idle,
+        started=time.strftime("%Y-%m-%d %H:%M:%S"),
+    )
+    with open(args.state, "w") as fh:
+        json.dump(state, fh)
+
+    def cleanup(*_):
+        try:
+            os.unlink(args.state)
+        except OSError:
+            pass
+        os._exit(0)
+
+    atexit.register(lambda: cleanup())
+    signal.signal(signal.SIGTERM, cleanup)
+    signal.signal(signal.SIGINT, cleanup)
+
+    if args.idle > 0:
+        threading.Thread(
+            target=watchdog, args=(args.idle * 60.0, server), daemon=True
+        ).start()
+
+    try:
+        server.serve_forever()
+    finally:
+        cleanup()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/extra/skills/skill-dependencies/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: skill-dependencies
+description: "How a skill handles a tool it needs: declare it via uv or mise so it is never missing; react to a genuine miss with one install and one retry; stop and ask rather than improvise. Read when a skill's command fails because a tool is not found."
+verified: 2026-09-02
+---
+
+# Handling Missing Dependencies
+
+Every skill in this collection defers to this skill for missing-tool handling. Skills never
+precheck for tools and never hand-roll their own install logic.
+
+This skill owns the **posture**: when to declare, when to react, when to stop. Where the
+user has a skill of their own that installs a tool, follow it; otherwise use the tool's own
+official installer, never a second way you invent.
+
+## Core rule: assume, don't check
+
+Assume the tools are already installed. **Run the real command directly.** Never precheck
+(`command -v`, `which`, `--version`) before doing the work: that spends time on the normal
+path, where everything is present.
+
+Only **react** when a command fails because a tool is missing (`command not found`,
+exit 127).
+
+## Three tiers, in order
+
+1. **Declare it. The default, always first.** `uv` (PEP 723 `dependencies`) and mise
+   (`#MISE tools={...}`) each provision what they cover, so a script's real dependencies
+   belong in its own header, checked against `mise registry` for what mise can supply. A
+   declared dependency never goes missing, which is why this tier is not really about
+   failure handling at all.
+2. **React with one install, then one retry.** For a tool with an installer skill of its own,
+   follow it. For a script's tool dependency that `mise registry`
+   genuinely has no entry for, `brew install <formula>` and retry the original command once.
+   No approval needed here: a named formula is a known, deterministic, low-risk install.
+3. **Stop and ask.** If the install fails, or nothing packages the tool, present the user with
+   at least one concrete option and get approval. Do not improvise: no manual download, no
+   alternate package manager, no silently skipping the step.
+
+## Reacting to a missing tool
+
+`uv` and `mise` are peers. Neither provisions the other, and neither substitutes for the
+other: when a command calls `uv`, run `uv`; when it calls `mise`, run `mise`.
+
+- **`uv` missing:** `brew install uv`, then retry the original command exactly as written.
+- **`mise` missing:** install it from its own official installer (https://mise.jdx.dev),
+  not through Homebrew, then retry.
+- **`brew` missing:** install it from https://brew.sh at its standard prefix, then retry.
+- **A script's declared tool missing:** the script's own `#MISE tools={...}` header should
+  have covered it; fix the header rather than installing by hand.
+
+If `uv run …` fails because `uv` is not found, the fix is `brew install uv` then `uv run …`
+again. Never reach for mise to supply uv (`mise exec -- uv`, `mise use uv`), and never move a
+failing mise command onto uv. Install the tool that is missing; run the command that was
+written.
+
+## Never
+
+- Never precheck for a tool before using it.
+- Never provide a missing tool by routing it through another; install the missing tool itself.
+- Never substitute one tool for another; run the command that was written.
+- Never ask the user to install something a skill can install reactively.
+- Never use `sudo`, and never assume admin access. Where a tool genuinely needs privileges the
+  user may not have, its own skill says what to do, including when to escalate to IT.
+- Never improvise past a failed or unavailable install. That is tier 3: stop and ask.