@davevdveen/spec-reader 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dave van der Veen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# SpecReader
+
+Beautiful reading experience for [OpenSpec](https://openspec.dev) specification files and project documentation.
+
+## Why
+
+AI-assisted development generates specs, proposals, and designs faster than ever. But reviewing structured markdown in a terminal or a GitHub diff is painful. When specs are hard to read, they don't get read.
+
+SpecReader gives your specifications a proper reading experience. Collapsible requirements, themed reading modes, and structured navigation make it natural to review proposals and specs, whether they're yours or someone else's.
+
+## Quick start
+
+```bash
+npx @davevdveen/spec-reader
+```
+
+Works on any project directory. Auto-detects OpenSpec folders and renders everything readable: specs, proposals, READMEs, configs, and more.
+
+Try it on the [OpenSpec framework](https://github.com/Fission-AI/OpenSpec) itself:
+
+```bash
+git clone https://github.com/Fission-AI/OpenSpec && cd OpenSpec && npx @davevdveen/spec-reader
+```
+
+## AI coding agent skill
+
+SpecReader includes a skill for AI coding agents (Claude Code, OpenCode) that opens the viewer for any PR or branch:
+
+```
+/read-specs              # open specs for current branch
+/read-specs 42           # checkout PR #42 and open its specs
+/read-specs feature/xyz  # checkout branch and open specs
+```
+
+Install the skill in your project:
+
+```bash
+npx @davevdveen/spec-reader init
+```
+
+This auto-detects your agent (Claude Code, OpenCode, or both) and installs the skill in the right place.
+
+## Scopes
+
+| Scope | Shows |
+|-------|-------|
+| Specs | OpenSpec files |
+| Docs | All markdown files |
+| All | All readable files (.md, .yaml, .yml, .txt, extensionless) |
+| Search | Filter across all files |
+
+## Themes
+
+Four reading themes, each with light and dark variants:
+
+| Theme | Font |
+|-------|------|
+| Original | Sans-serif |
+| Paper | Georgia serif |
+| Calm | Serif, warm tones |
+| Mono | Monospace |
+
+Follows system light/dark preference with manual override.
+
+## Commands
+
+```bash
+spec-reader                          # serve current directory
+spec-reader ~/projects/myapp         # serve any project
+spec-reader export openspec/ dist/   # export static site
+spec-reader init                     # install AI agent skill
+view-proposal add-dark-mode          # open viewer on a proposal
+```
+
+## Keyboard shortcuts
+
+| Key | Action |
+|-----|--------|
+| `←` `→` | Previous / next page |
+| `↑` `↓` | Scroll content |
+| `-` | Expand / collapse all sections in the document |
+| `Cmd+Shift+R` | Toggle sidebar |
+
+## How it works
+
+A single HTML file served by a shell script that walks your directory, generates a manifest, and starts Python's built-in HTTP server. Zero runtime dependencies beyond Python 3.
+
+File changes are detected every 3 seconds. Edit a spec, see it update in the viewer.
+
+## Prerequisites
+
+- **Python 3** (used to serve files locally)
+- **Node.js** (for `npx` installation only)
+- **gh CLI** (optional, for the `/read-specs` skill to checkout PRs)
+
+Works on macOS, Linux, and Windows (WSL). Tested in Safari, should work in any modern browser.
+
+## Install
+
+```bash
+npm install -g @davevdveen/spec-reader
+npx @davevdveen/spec-reader
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@davevdveen/spec-reader",
+  "version": "0.1.2",
+  "description": "Beautiful reading experience for OpenSpec specification files",
+  "bin": {
+    "spec-reader": "./spec-reader",
+    "view-proposal": "./view-proposal"
+  },
+  "files": [
+    "spec-reader",
+    "read-specs",
+    "view-proposal",
+    "spec-viewer.html",
+    "skills/"
+  ],
+  "keywords": [
+    "openspec",
+    "markdown",
+    "viewer",
+    "specification",
+    "documentation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/davevdveen/spec-reader"
+  }
+}

package/read-specs

@@ -0,0 +1,210 @@
+#!/bin/bash
+# read-specs — Discover files, generate manifest, and serve the viewer.
+#
+# Usage:
+#   ./read-specs [directory]           Serve the viewer for the given directory (default: .)
+#   ./read-specs --manifest-only [dir] Generate manifest.json without starting a server
+#
+# The viewer HTML stays in this script's directory. Nothing is copied to the
+# target directory — only a temporary manifest.json is created there and
+# cleaned up on exit.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TARGET_DIR="${2:-${1:-.}}"
+MANIFEST_ONLY=false
+FOCUS=""
+PORT="${PORT:-3333}"
+
+# Parse flags
+if [[ "${1:-}" == "--manifest-only" ]]; then
+  MANIFEST_ONLY=true
+  TARGET_DIR="${2:-.}"
+elif [[ "${1:-}" == "--focus" ]]; then
+  FOCUS="${2:-}"
+  TARGET_DIR="${3:-.}"
+elif [[ "${1:-}" == --* ]]; then
+  echo "Unknown flag: $1" >&2
+  exit 1
+fi
+
+# Resolve target directory
+TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
+
+# ── Generate manifest.json ──
+generate_manifest() {
+  local dir="$1"
+  local output="$2"
+  local first=true
+
+  local absdir
+  absdir="$(cd "$dir" && pwd)"
+  echo '{"generated":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","root":"'"$absdir"'","files":[' > "$output"
+
+  while IFS= read -r filepath; do
+    # Strip leading ./
+    filepath="${filepath#./}"
+
+    # Skip build artifacts, git, and dependency folders
+    [[ "$filepath" == .git/* ]] && continue
+    [[ "$filepath" == .build/* ]] && continue
+    [[ "$filepath" == */.build/* ]] && continue
+    [[ "$filepath" == node_modules/* ]] && continue
+    [[ "$filepath" == */node_modules/* ]] && continue
+    [[ "$filepath" == Pods/* ]] && continue
+    [[ "$filepath" == */Pods/* ]] && continue
+    [[ "$filepath" == Carthage/* ]] && continue
+    [[ "$filepath" == */Carthage/* ]] && continue
+    [[ "$filepath" == */checkouts/* ]] && continue
+    [[ "$filepath" == *.docc/* ]] && continue
+    [[ "$filepath" == manifest.json ]] && continue
+    [[ "$(basename "$filepath")" == .openspec.yaml ]] && continue
+
+    local name
+    name="$(basename "$filepath")"
+
+    # Calculate task counts for tasks.md files
+    local task_checked="" task_total=""
+    if [[ "$name" == "tasks.md" ]]; then
+      local checked unchecked total
+      checked=$(grep -c '\- \[x\]' "$dir/$filepath" 2>/dev/null || true)
+      unchecked=$(grep -c '\- \[ \]' "$dir/$filepath" 2>/dev/null || true)
+      checked=${checked:-0}
+      unchecked=${unchecked:-0}
+      checked=$(echo "$checked" | tr -d '[:space:]')
+      unchecked=$(echo "$unchecked" | tr -d '[:space:]')
+      total=$((checked + unchecked))
+      if [[ $total -gt 0 ]]; then
+        task_checked=$checked
+        task_total=$total
+      fi
+    fi
+
+    # Emit JSON — just path and name, no section classification
+    if $first; then
+      first=false
+    else
+      printf ',' >> "$output"
+    fi
+
+    if [[ -n "$task_checked" ]]; then
+      printf '{"path":"%s","name":"%s","taskChecked":%s,"taskTotal":%s}' \
+        "$filepath" "$name" "$task_checked" "$task_total" >> "$output"
+    else
+      printf '{"path":"%s","name":"%s"}' \
+        "$filepath" "$name" >> "$output"
+    fi
+
+  done < <(cd "$dir" && find . -type f \( \
+    -name '*.md' -o -name '*.yaml' -o -name '*.yml' -o -name '*.txt' \
+    -o -name 'Brewfile' -o -name 'Gemfile' -o -name 'Podfile' -o -name 'Fastfile' \
+    -o -name 'Appfile' -o -name 'Matchfile' -o -name 'Pluginfile' -o -name 'Dangerfile' \
+    -o -name 'Dockerfile' -o -name 'Makefile' -o -name 'CODEOWNERS' -o -name 'LICENSE' \
+  \) | sort)
+
+  echo ']}' >> "$output"
+}
+
+# ── Main ──
+
+# Generate manifest in a temp location
+MANIFEST="$(mktemp)"
+generate_manifest "$TARGET_DIR" "$MANIFEST"
+echo "Generated manifest with $(grep -o '"path"' "$MANIFEST" | wc -l | tr -d ' ') files"
+
+if $MANIFEST_ONLY; then
+  cp "$MANIFEST" "$TARGET_DIR/manifest.json"
+  rm -f "$MANIFEST"
+  echo "Wrote manifest.json to $TARGET_DIR"
+  exit 0
+fi
+
+# Start a Python server that serves:
+#   /spec-viewer.html  → from SCRIPT_DIR
+#   /manifest.json     → from temp file
+#   everything else    → from TARGET_DIR
+python3 -u - "$SCRIPT_DIR" "$TARGET_DIR" "$MANIFEST" "$PORT" <<'PYSERVER' &
+import http.server
+import os
+import sys
+import urllib.parse
+
+script_dir = sys.argv[1]
+target_dir = sys.argv[2]
+manifest_path = sys.argv[3]
+port = int(sys.argv[4])
+
+class SpecHandler(http.server.SimpleHTTPRequestHandler):
+    def do_GET(self):
+        clean_path = self.path.split('?', 1)[0].split('#', 1)[0].lstrip('/')
+        if clean_path == 'api/refresh':
+            import subprocess
+            subprocess.run(
+                [os.path.join(script_dir, 'read-specs'), '--manifest-only', target_dir],
+                capture_output=True
+            )
+            import shutil
+            generated = os.path.join(target_dir, 'manifest.json')
+            if os.path.exists(generated):
+                shutil.copy(generated, manifest_path)
+                os.remove(generated)
+            self.send_response(200)
+            self.send_header('Content-Type', 'application/json')
+            self.send_header('Access-Control-Allow-Origin', '*')
+            self.end_headers()
+            self.wfile.write(b'{"ok":true}')
+            return
+        super().do_GET()
+
+    def translate_path(self, path):
+        # Strip query string and fragment
+        path = path.split('?', 1)[0].split('#', 1)[0]
+        # URL-decode (handles %20 for spaces, etc.)
+        path = urllib.parse.unquote(path)
+        # Remove leading /
+        path = path.lstrip('/')
+
+        # Serve viewer HTML from the script directory
+        if path == 'spec-viewer.html':
+            return os.path.join(script_dir, 'spec-viewer.html')
+
+        # Serve manifest from temp file
+        if path == 'manifest.json':
+            return manifest_path
+
+        # Everything else from target directory
+        return os.path.join(target_dir, path)
+
+    def log_message(self, format, *args):
+        pass  # Silence request logs
+
+server = http.server.HTTPServer(('', port), SpecHandler)
+print(f"Serving specs from {target_dir}", flush=True)
+server.serve_forever()
+PYSERVER
+SERVER_PID=$!
+
+cleanup() {
+  kill "$SERVER_PID" 2>/dev/null
+  rm -f "$MANIFEST"
+}
+trap cleanup EXIT
+
+sleep 1
+
+URL="http://localhost:$PORT/spec-viewer.html"
+if [[ -n "$FOCUS" ]]; then
+  ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$FOCUS")
+  URL="${URL}#${ENCODED}"
+fi
+echo "Viewer: $URL"
+
+if command -v open &>/dev/null; then
+  open "$URL"
+elif command -v xdg-open &>/dev/null; then
+  xdg-open "$URL"
+fi
+
+echo "Press Ctrl+C to stop"
+wait

package/skills/read-specs/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: read-specs
+description: Open the SpecReader viewer to read OpenSpec specifications, proposals, designs, tasks, and project documentation in a themed reading experience. Use this skill whenever the user wants to read specs, review a proposal, browse documentation, view OpenSpec files, read READMEs, or says "open specs", "read specs", "show me the specs", "review the proposal", "open the viewer", or "/read-specs". Also trigger when the user wants to review specs from a specific PR or branch.
+---
+
+Open the SpecReader viewer for the current repo's OpenSpec files and documentation, or for a specific PR or branch.
+
+Works with Claude Code and OpenCode.
+
+## Usage
+
+- `/read-specs` — open specs for the current branch
+- `/read-specs 42` — checkout PR #42 and open its specs
+- `/read-specs feature/my-branch` — checkout branch and open its specs
+
+## Steps
+
+1. If an argument is provided:
+   - If it's a number, run `gh pr checkout <number>` (requires gh CLI)
+   - If it's a branch name, run `git checkout <branch>`
+
+2. Find the project root (look for `.git` directory).
+
+3. Run the viewer in the background:
+   ```bash
+   npx @davevdveen/spec-reader &
+   ```
+   This starts a local server and opens the browser.
+
+4. Tell the user:
+   - "Spec viewer is open at http://localhost:3333"
+   - "Changes are auto-detected every 3 seconds"
+   - "Use arrow keys to navigate between pages"
+   - "Use the scope bar to switch between Specs, Docs, All, or Search"
+   - "Use the Aa button to change themes and light/dark mode"

package/spec-reader

@@ -0,0 +1,104 @@
+#!/bin/bash
+set -euo pipefail
+
+# spec-reader — View, export, or set up SpecReader
+#
+# Usage:
+#   spec-reader [directory]              Serve the viewer (default: .)
+#   spec-reader export [dir] [output]    Export static site to a directory
+#   spec-reader init                     Install the /read-specs skill for your AI coding agent
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "${1:-}" in
+  init)
+    SKILL_SRC="$SCRIPT_DIR/skills/read-specs/SKILL.md"
+    installed=false
+
+    if [[ -d ".claude" ]]; then
+      mkdir -p .claude/skills/read-specs
+      cp "$SKILL_SRC" .claude/skills/read-specs/SKILL.md
+      echo "Installed skill to .claude/skills/read-specs/"
+      installed=true
+    fi
+
+    if [[ -d ".opencode" ]]; then
+      mkdir -p .opencode/skills/read-specs
+      cp "$SKILL_SRC" .opencode/skills/read-specs/SKILL.md
+      echo "Installed skill to .opencode/skills/read-specs/"
+      installed=true
+    fi
+
+    if [[ "$installed" == false ]]; then
+      echo "No .claude/ or .opencode/ directory found."
+      echo ""
+      echo "Which agent do you use?"
+      echo "  1) Claude Code  (.claude/skills/)"
+      echo "  2) OpenCode     (.opencode/skills/)"
+      echo "  3) Both"
+      read -rp "Choice [1/2/3]: " choice
+      case "$choice" in
+        1)
+          mkdir -p .claude/skills/read-specs
+          cp "$SKILL_SRC" .claude/skills/read-specs/SKILL.md
+          echo "Installed skill to .claude/skills/read-specs/"
+          ;;
+        2)
+          mkdir -p .opencode/skills/read-specs
+          cp "$SKILL_SRC" .opencode/skills/read-specs/SKILL.md
+          echo "Installed skill to .opencode/skills/read-specs/"
+          ;;
+        3)
+          mkdir -p .claude/skills/read-specs .opencode/skills/read-specs
+          cp "$SKILL_SRC" .claude/skills/read-specs/SKILL.md
+          cp "$SKILL_SRC" .opencode/skills/read-specs/SKILL.md
+          echo "Installed skill to .claude/skills/read-specs/ and .opencode/skills/read-specs/"
+          ;;
+        *)
+          echo "Cancelled."
+          exit 1
+          ;;
+      esac
+    fi
+
+    echo ""
+    echo "You can now use /read-specs in your AI coding agent."
+    ;;
+
+  export)
+    SOURCE_DIR="${2:-.}"
+    OUTPUT_DIR="${3:-spec-site}"
+
+    echo "Exporting spec site from $SOURCE_DIR to $OUTPUT_DIR..."
+
+    mkdir -p "$OUTPUT_DIR"
+
+    # Copy spec files
+    cd "$SOURCE_DIR"
+    find . -type f \( -name '*.md' -o -name '*.yaml' -o -name '*.yml' \) | while read -r f; do
+      f="${f#./}"
+      [[ "$f" == .git/* ]] && continue
+      [[ "$f" == */.build/* ]] && continue
+      [[ "$f" == */node_modules/* ]] && continue
+      mkdir -p "$OUTPUT_DIR/$(dirname "$f")"
+      cp "$f" "$OUTPUT_DIR/$f"
+    done
+    cd - > /dev/null
+
+    # Generate manifest
+    "$SCRIPT_DIR/read-specs" --manifest-only "$SOURCE_DIR"
+    mv "$SOURCE_DIR/manifest.json" "$OUTPUT_DIR/manifest.json"
+
+    # Copy viewer as index.html
+    cp "$SCRIPT_DIR/spec-viewer.html" "$OUTPUT_DIR/index.html"
+
+    echo "Spec site exported to $OUTPUT_DIR/"
+    echo "  Files: $(find "$OUTPUT_DIR" -type f | wc -l | tr -d ' ')"
+    echo "  Serve: cd $OUTPUT_DIR && python3 -m http.server 3333"
+    ;;
+
+  *)
+    # Serve mode — serve from the given directory
+    exec "$SCRIPT_DIR/read-specs" "${1:-.}"
+    ;;
+esac