@staff0rd/assist 0.751.0 → 0.753.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@staff0rd/assist",
-	"version": "0.751.0",
+	"version": "0.753.0",
 	"type": "module",
 	"main": "dist/index.js",
 	"bin": {

package/claude/commands/handover.md

@@ -1,65 +0,0 @@
----
-description: Write a session handover note for the next conversation
----
-
-Write a concise handover note for the next session working on this repo, then save it to the backlog database. The note captures everything the next session needs to pick up where this one left off.
-
-Handover notes are stored in the backlog DB (scoped by git origin), never on disk. `/handover` can be run any number of times — each run appends a new note.
-
-## Step 1: Compose the note
-
-Always operate on the current working directory. Compose the note body using the following sections, in this order, and omit none even if empty (use a single "—" placeholder line):
-
-```markdown
-# Handover
-
-## Current Task
-
-What is actively being worked on right now — one or two sentences. Include the backlog item ID or PR number if applicable.
-
-## Just Done
-
-The most recent things completed in this session. Bullet list. Include file paths where relevant.
-
-## Next Steps
-
-What the next session should do next, in order. Bullet list. Be concrete — name files, commands, or decisions.
-
-## Key Files
-
-Files that the next session will most likely need to read or edit. Bullet list of `path:line` references where useful.
-
-## Open Decisions
-
-Choices that have not yet been made, or were deferred. State the options briefly so the next session can resume the deliberation.
-
-## Watch Out For
-
-Non-obvious gotchas, in-flight refactors, broken tests, half-applied changes, or anything that could trip up the next session.
-
-## Don't Do
-
-Things that have been ruled out, attempted unsuccessfully, or that the user has explicitly asked not to do. Saves the next session from repeating dead ends.
-```
-
-## Step 2: Save the note
-
-Author a one-line summary (under 100 chars) describing the note — this is what `/recall` shows when listing notes. Then save it by piping the composed note into `assist handover save` via stdin:
-
-```bash
-assist handover save --summary "<one-line summary>" <<'HANDOVER_EOF'
-# Handover
-
-## Current Task
-...
-HANDOVER_EOF
-```
-
-Use a quoted heredoc delimiter (`<<'HANDOVER_EOF'`) so nothing in the note body is expanded by the shell. The command resolves the repo's git origin and inserts a new row in the backlog DB.
-
-## Guidelines
-
-- Keep each section terse — bullets, not paragraphs. The next session will read this cold.
-- Reference concrete file paths and line numbers wherever it helps orientation.
-- Do not summarise context that is already obvious from the code or git history.
-- Do not write `.assist/HANDOVER.md` or any other file — handovers live only in the backlog DB.

package/claude/commands/journal.md

@@ -1,74 +0,0 @@
----
-description: Append a journal entry summarising recent work, decisions, and notable observations
-allowed_args: "[optional focus or note]"
----
-
-Append a structured journal entry to today's daily file. This should be fast — do not read existing journal files or attempt to deduplicate.
-
-## Step 1: Determine the date and file
-
-**IMPORTANT:** Do not rely on your own sense of the current date — it may be stale in long-running sessions. Always run `date +%Y-%m-%d` and `date +%H:%M` via Bash to get the actual current date and time.
-
-The journal lives in `~/.claude/journal/`, one file per day, named `YYYY-MM-DD.md`.
-
-If today's file doesn't exist, create it with a heading:
-
-```markdown
-# YYYY-MM-DD
-```
-
-## Step 2: Resolve project context
-
-Determine the current project by matching the working directory against `~/.claude/skills/projects.json`. If not inside a registered project, use "general" as the project name.
-
-## Step 3: Write the entry
-
-Append an entry to the daily file. Each entry should follow this structure:
-
-```markdown
-## HH:MM — {project name} #{project name}
-
-{Summary of what was done — keep it concise but capture the key points}
-
-**Decisions:** {any notable decisions made and why, or "None"}
-
-**Topics:** {flag anything blog-worthy, reusable, or worth revisiting — or "None"}
-```
-
-Tag the project name in the heading (e.g., `#project1`, `#general`). When flagging topics, prefix with `#blog-worthy`, `#reusable`, or `#demo-worthy`:
-
-Guidelines:
-
-- Summarise what was accomplished, not every step taken
-- Capture the "why" behind decisions — this is what you'll forget
-- Flag blog-worthy topics with a brief note on why it's interesting
-- Flag reusable patterns, utilities, or approaches worth extracting
-- Flag demo-worthy work — things that would make a good presentation, show-and-tell, or live walkthrough
-- If the user provided `$ARGUMENTS`, use it to focus or annotate the entry
-- Keep entries concise — a few lines per section, not paragraphs
-
-## Step 4: Write detail files (when topics are flagged)
-
-When a topic is flagged as blog-worthy or reusable, create a supporting detail file that captures the context needed to act on it later. Without this, the journal flags opportunities but loses the detail needed to follow through.
-
-Detail files live in `~/.claude/journal/details/` and are named `YYYY-MM-DD-{slug}.md`.
-
-Link them from the journal entry:
-
-```markdown
-**Topics:**
-
-- #blog-worthy Teaching Claude to reflect — [detail](details/2026-02-13-reflect-workflow.md)
-- #reusable The skill/hook pattern — [detail](details/2026-02-13-starter-kit.md)
-```
-
-Each detail file should include whichever of the following are relevant:
-
-- **Context** — what problem was being solved and why
-- **Approach** — what was tried, including dead ends and alternatives considered
-- **Key code** — relevant snippets, patterns, or configurations that were created
-- **Outcome** — what worked, what didn't, and why
-- **Blog angle** — if blog-worthy, what makes it interesting to write about
-- **Extraction notes** — if reusable, what could be extracted and how it might be generalised
-
-These files are meant to preserve enough context that someone (including a future Claude session) could flesh out a blog post or extract reusable code without the original conversation.

package/claude/commands/recall.md

@@ -1,55 +0,0 @@
----
-description: Recall context from the most recent prior session in this repo
----
-
-Load the most recent handover note for this repo so the current session can pick up where the last one left off. Always operate on the current working directory; do not ask which repo to recall.
-
-Handover notes are stored in the backlog database (scoped by git origin), authored by `/handover`. `/recall` reads only those notes — it does not read session transcripts or any disk files.
-
-## Step 1: List unrecalled notes
-
-Run:
-
-```bash
-assist handover list
-```
-
-This prints one unrecalled handover per line, most recent first, as tab-separated `id`, ISO-8601 created timestamp, and one-line summary.
-
-- **No output** — there are no unrecalled handovers. Skip to Step 3 and emit the "no handover" block.
-- **Exactly one line** — recall it directly in Step 2 with no id.
-- **More than one line** — present the summaries (with their created timestamps) to the user and ask which to recall, then pass the chosen `id` in Step 2.
-
-## Step 2: Recall the chosen note
-
-Run:
-
-```bash
-assist handover recall [id]
-```
-
-With no argument this recalls the most recent unrecalled handover; with an `id` it recalls that specific note. Either way it prints the note's content to stdout and marks it recalled (so it drops out of the SessionStart advisory and future recalls).
-
-## Step 3: Surface it
-
-If the command printed content, present it to the user as a `# Recall` block so they can resume:
-
-```markdown
-# Recall
-
-<the recalled handover content>
-```
-
-If the command printed nothing, there are no unrecalled handovers — emit:
-
-```markdown
-# Recall
-
-No handover found for this repo.
-```
-
-## Guidelines
-
-- Always operate on the current working directory — never guess or substitute another repo.
-- `/recall` is the counterpart to `/handover`: it reads notes the previous session authored, nothing else.
-- Do not write or modify any files.

package/claude/commands/standup.md

@@ -1,35 +0,0 @@
----
-description: Summarise recent journal entries as a standup update
-allowed_args: "[days back, default 1] [project name]"
----
-
-Summarise recent journal entries.
-
-## Step 1: Determine the range
-
-Parse `$ARGUMENTS` for:
-
-- A number (days to look back, default 1)
-- A project name (filter to that project only, default all)
-
-Examples:
-
-- `/standup` — yesterday's entries, all projects
-- `/standup 3` — last 3 days, all projects
-- `/standup project1` — yesterday's entries for project1
-- `/standup 7 project2` — last 7 days for project2
-
-## Step 2: Read journal files
-
-Read the daily files from `~/.claude/journal/` for the date range. Files are named `YYYY-MM-DD.md`.
-
-## Step 3: Present the summary
-
-Summarise the entries concisely, grouped by day and project. Highlight:
-
-- What was accomplished
-- Key decisions made
-- Any flagged blog topics or reusable IP
-- Anything left in progress
-
-Keep it brief — this is a standup, not a report.

package/claude/commands/voice-logs.md

@@ -1,5 +0,0 @@
----
-description: Show recent voice daemon logs
----
-
-Run `assist voice logs 2>&1` to show recent voice daemon logs. Show the result to the user.

package/claude/commands/voice-setup.md

@@ -1,5 +0,0 @@
----
-description: Download required voice models (VAD, STT)
----
-
-Run `assist voice setup 2>&1` to download the required voice models. Show the result to the user.

package/claude/commands/voice-start.md

@@ -1,5 +0,0 @@
----
-description: Start the voice interaction daemon
----
-
-Run `assist voice start 2>&1` to start the voice daemon. If it fails, show the error to the user.

package/claude/commands/voice-status.md

@@ -1,5 +0,0 @@
----
-description: Check voice daemon status
----
-
-Run `assist voice status 2>&1` to check the voice daemon status. Show the result to the user.

package/claude/commands/voice-stop.md

@@ -1,5 +0,0 @@
----
-description: Stop the voice interaction daemon
----
-
-Run `assist voice stop 2>&1` to stop the voice daemon. Show the result to the user.

package/dist/commands/voice/python/CLAUDE.md

@@ -1,11 +0,0 @@
-Never use `pip install` directly. All Python dependency management uses `uv`.
-
-**The venv MUST live in `~/.assist/voice/.venv`, NEVER in this directory or anywhere in the repo.**
-
-Every `uv` command that touches this project MUST set `UV_PROJECT_ENVIRONMENT` to point to the home dir venv. This includes `uv sync`, `uv run`, and any other uv command. There must be no `.venv/`, `__pycache__/`, `*.egg-info/`, or any other generated artifacts in this directory.
-
-- Dependencies are declared in `pyproject.toml`
-- Runtime deps (torch, nemo, etc.) are in the `runtime` optional group; dev tools (ruff, xenon, radon) are in `dev`
-- Bootstrap uses `uv sync --project <dir> --extra runtime --no-install-project` with `UV_PROJECT_ENVIRONMENT=~/.assist/voice/.venv`
-- To add a dependency: edit `pyproject.toml`, then run `UV_PROJECT_ENVIRONMENT=~/.assist/voice/.venv uv lock --project src/commands/voice/python`
-- No build system — this is a virtual project, not an installable package

package/dist/commands/voice/python/audio_capture.py

@@ -1,52 +0,0 @@
-"""Microphone capture via sounddevice (16kHz PCM)."""
-
-import os
-import queue
-import numpy as np
-import sounddevice as sd
-
-from logger import log
-
-SAMPLE_RATE = 16000
-BLOCK_SIZE = 512  # Silero VAD requires exactly 512 samples at 16kHz
-
-
-class AudioCapture:
-    def __init__(self):
-        self._queue: queue.Queue[np.ndarray] = queue.Queue()
-        self._stream: sd.InputStream | None = None
-        device_name = os.environ.get("VOICE_MIC")
-        self._device = device_name if device_name else None
-
-    def _callback(self, indata: np.ndarray, frames: int, time_info, status) -> None:
-        if status:
-            log("audio_status", str(status), level="warn")
-        self._queue.put(indata[:, 0].copy())
-
-    def start(self) -> None:
-        log(
-            "audio_start",
-            f"device={self._device}, rate={SAMPLE_RATE}, block={BLOCK_SIZE}",
-        )
-        self._stream = sd.InputStream(
-            samplerate=SAMPLE_RATE,
-            channels=1,
-            dtype="float32",
-            blocksize=BLOCK_SIZE,
-            device=self._device,
-            callback=self._callback,
-        )
-        self._stream.start()
-
-    def read(self, timeout: float = 1.0) -> np.ndarray | None:
-        try:
-            return self._queue.get(timeout=timeout)
-        except queue.Empty:
-            return None
-
-    def stop(self) -> None:
-        if self._stream:
-            self._stream.stop()
-            self._stream.close()
-            self._stream = None
-            log("audio_stop")

package/dist/commands/voice/python/check_mi.py

@@ -1,21 +0,0 @@
-"""Check file-level maintainability index using radon."""
-
-import glob
-import sys
-
-from radon.metrics import mi_visit
-
-MIN_MI = 20  # Grade B threshold
-
-failed = []
-for path in sorted(glob.glob("src/commands/voice/python/**/*.py", recursive=True)):
-    with open(path) as f:
-        mi = mi_visit(f.read(), True)
-    if mi < MIN_MI:
-        failed.append((path, mi))
-
-if failed:
-    print("Files with low maintainability index:")
-    for path, mi in failed:
-        print(f"  {path} - MI: {mi:.1f}")
-    sys.exit(1)

package/dist/commands/voice/python/dispatch.py

@@ -1,14 +0,0 @@
-"""Dispatch — keyboard-based input into the active terminal."""
-
-from logger import log
-
-import keyboard
-
-
-def dispatch(command: str) -> str:
-    """Type the command and press Enter."""
-    log("dispatch_start", command)
-    keyboard.type_text(command)
-    keyboard.press_enter()
-    log("dispatch_done", command)
-    return command

package/dist/commands/voice/python/keyboard.py

@@ -1,73 +0,0 @@
-"""Simulate keyboard input on Windows via SendInput."""
-
-import ctypes
-import ctypes.wintypes as w
-
-user32 = ctypes.windll.user32
-
-INPUT_KEYBOARD = 1
-KEYEVENTF_UNICODE = 0x0004
-KEYEVENTF_KEYUP = 0x0002
-KEYEVENTF_SCANCODE = 0x0008
-VK_RETURN = 0x0D
-VK_BACK = 0x08
-SCAN_RETURN = 0x1C
-SCAN_BACK = 0x0E
-
-
-class KEYBDINPUT(ctypes.Structure):
-    _fields_ = [
-        ("wVk", w.WORD),
-        ("wScan", w.WORD),
-        ("dwFlags", w.DWORD),
-        ("time", w.DWORD),
-        ("dwExtraInfo", ctypes.POINTER(ctypes.c_ulong)),
-    ]
-
-
-class MOUSEINPUT(ctypes.Structure):
-    _fields_ = [
-        ("dx", ctypes.c_long),
-        ("dy", ctypes.c_long),
-        ("mouseData", w.DWORD),
-        ("dwFlags", w.DWORD),
-        ("time", w.DWORD),
-        ("dwExtraInfo", ctypes.POINTER(ctypes.c_ulong)),
-    ]
-
-
-class INPUT(ctypes.Structure):
-    class _INPUT(ctypes.Union):
-        _fields_ = [("mi", MOUSEINPUT), ("ki", KEYBDINPUT)]
-
-    _anonymous_ = ("_input",)
-    _fields_ = [("type", w.DWORD), ("_input", _INPUT)]
-
-
-def _send_key(vk: int = 0, scan: int = 0, flags: int = 0) -> None:
-    inp = INPUT(type=INPUT_KEYBOARD)
-    inp.ki.wVk = vk
-    inp.ki.wScan = scan
-    inp.ki.dwFlags = flags
-    user32.SendInput(1, ctypes.byref(inp), ctypes.sizeof(inp))
-
-
-def type_text(text: str) -> None:
-    """Type a string by sending Unicode keystrokes."""
-    for ch in text:
-        code = ord(ch)
-        _send_key(scan=code, flags=KEYEVENTF_UNICODE)
-        _send_key(scan=code, flags=KEYEVENTF_UNICODE | KEYEVENTF_KEYUP)
-
-
-def backspace(n: int = 1) -> None:
-    """Press backspace n times."""
-    for _ in range(n):
-        _send_key(vk=VK_BACK, scan=SCAN_BACK)
-        _send_key(vk=VK_BACK, scan=SCAN_BACK, flags=KEYEVENTF_KEYUP)
-
-
-def press_enter() -> None:
-    """Press the Enter key."""
-    _send_key(vk=VK_RETURN, scan=SCAN_RETURN)
-    _send_key(vk=VK_RETURN, scan=SCAN_RETURN, flags=KEYEVENTF_KEYUP)

package/dist/commands/voice/python/list_devices.py

@@ -1,20 +0,0 @@
-"""List available audio input devices."""
-
-import sounddevice as sd
-
-
-def main() -> None:
-    devices = sd.query_devices()
-    print("Audio input devices:\n")
-    for i, dev in enumerate(devices):
-        if dev["max_input_channels"] > 0:
-            default = " (default)" if i == sd.default.device[0] else ""
-            print(f"  [{i}] {dev['name']}{default}")
-            ch = dev["max_input_channels"]
-            rate = dev["default_samplerate"]
-            print(f"      channels={ch}, rate={rate}")
-            print()
-
-
-if __name__ == "__main__":
-    main()

package/dist/commands/voice/python/logger.py

@@ -1,38 +0,0 @@
-"""JSON Lines structured logging to voice.log."""
-
-import json
-import os
-import sys
-from datetime import datetime, timezone
-
-
-LOG_FILE = os.environ.get(
-    "VOICE_LOG_FILE", os.path.expanduser("~/.assist/voice/voice.log")
-)
-
-DEBUG = os.environ.get("VOICE_DEBUG", "") == "1"
-
-
-def _write(entry: dict) -> None:
-    entry["timestamp"] = datetime.now(timezone.utc).isoformat()
-    line = json.dumps(entry)
-    try:
-        with open(LOG_FILE, "a", encoding="utf-8") as f:
-            f.write(line + "\n")
-    except OSError:
-        pass
-    if DEBUG:
-        ts = entry["timestamp"][11:19]
-        level = entry.get("level", "info").upper()
-        event = entry.get("event", "")
-        msg = entry.get("message", "")
-        print(f"{ts} {level:5s} [{event}] {msg}", file=sys.stderr, flush=True)
-
-
-def log(event: str, message: str = "", *, level: str = "info", **data) -> None:
-    entry: dict = {"event": event, "level": level}
-    if message:
-        entry["message"] = message
-    if data:
-        entry["data"] = data
-    _write(entry)

package/dist/commands/voice/python/pyproject.toml

@@ -1,26 +0,0 @@
-[project]
-name = "assist-voice"
-version = "0.1.0"
-requires-python = ">=3.10"
-dependencies = []
-
-[project.optional-dependencies]
-runtime = [
-	"onnxruntime>=1.17",
-	"sounddevice>=0.4",
-	"numpy>=1.24",
-	"nemo_toolkit[asr]>=1.22",
-	"silero-vad>=5.1",
-	"torch>=2.0",
-]
-dev = ["radon>=6.0", "ruff>=0.8", "xenon>=0.9"]
-
-[[tool.uv.index]]
-name = "pytorch-cu124"
-url = "https://download.pytorch.org/whl/cu124"
-explicit = true
-
-[tool.uv.sources]
-torch = { index = "pytorch-cu124" }
-torchaudio = { index = "pytorch-cu124" }
-

package/dist/commands/voice/python/setup_models.py

@@ -1,91 +0,0 @@
-"""Download and prepare all required voice models."""
-
-import os
-import sys
-
-from logger import log
-
-
-def get_models_dir() -> str:
-    return os.environ.get(
-        "VOICE_MODELS_DIR",
-        os.path.expanduser("~/.assist/voice/models"),
-    )
-
-
-def setup_silero_vad(models_dir: str) -> None:
-    target = os.path.join(models_dir, "silero_vad.onnx")
-    if os.path.exists(target):
-        print("  silero_vad.onnx already exists")
-        return
-
-    print("  Downloading Silero VAD ONNX model...")
-    import urllib.request
-
-    url = "https://github.com/snakers4/silero-vad/raw/master/src/silero_vad/data/silero_vad.onnx"
-    urllib.request.urlretrieve(url, target)
-    log("setup_vad", f"Downloaded to {target}")
-    print("  silero_vad.onnx downloaded")
-
-
-def setup_smart_turn(models_dir: str) -> None:
-    target = os.path.join(models_dir, "smart-turn-v3.2-cpu.onnx")
-    if os.path.exists(target):
-        print("  smart-turn-v3.2-cpu.onnx already exists")
-        return
-
-    print("  Downloading Smart Turn ONNX model from HuggingFace...")
-    from huggingface_hub import hf_hub_download
-
-    path = hf_hub_download(
-        repo_id="pipecat-ai/smart-turn-v3",
-        filename="smart-turn-v3.2-cpu.onnx",
-        local_dir=models_dir,
-    )
-    log("setup_smart_turn", f"Downloaded to {path}")
-    print("  smart-turn-v3.2-cpu.onnx downloaded")
-
-
-def setup_stt(models_dir: str) -> None:
-    model_name = os.environ.get("VOICE_MODEL_STT", "nvidia/parakeet-ctc-1.1b")
-    print(f"  Downloading STT model: {model_name}...")
-    print("  (this may take a while on first run)")
-
-    import nemo.collections.asr as nemo_asr
-
-    nemo_asr.models.EncDecCTCModelBPE.from_pretrained(model_name)
-    log("setup_stt", f"Model ready: {model_name}")
-    print(f"  STT model ready: {model_name}")
-
-
-def main() -> None:
-    models_dir = get_models_dir()
-    os.makedirs(models_dir, exist_ok=True)
-    print(f"Models directory: {models_dir}\n")
-
-    print("[1/3] Silero VAD")
-    try:
-        setup_silero_vad(models_dir)
-    except Exception as e:
-        log("setup_vad_error", str(e), level="error")
-        print(f"  ERROR: {e}", file=sys.stderr)
-
-    print("\n[2/3] Smart Turn (pipecat-ai)")
-    try:
-        setup_smart_turn(models_dir)
-    except Exception as e:
-        log("setup_smart_turn_error", str(e), level="error")
-        print(f"  ERROR: {e}", file=sys.stderr)
-
-    print("\n[3/3] Parakeet STT (NeMo)")
-    try:
-        setup_stt(models_dir)
-    except Exception as e:
-        log("setup_stt_error", str(e), level="error")
-        print(f"  ERROR: {e}", file=sys.stderr)
-
-    print("\nSetup complete.")
-
-
-if __name__ == "__main__":
-    main()