single-html-dashboard

name	single-html-dashboard
description	Generic project progress dashboard. Per-project `.dashboard/` directory + a single self-contained HTML file that carries its own data + editor UI. Save back to server (or download) to persist edits. Forward the HTML and the recipient has the full product. Triggers on "dashboard", "项目 dashboard", "init dashboard", "dashboard render", "save dashboard".

Single-HTML-Dashboard

A project-agnostic, full-featured browser-side dashboard packed into one HTML file.

Philosophy

The HTML is the product. It contains:

• All items (embedded in a getInitialData() JS function)
• The full editor UI (kanban, modal forms, password-protected unlock, per-item page editor)
• Browser-side SQLite via sql.js (WASM)
• Save-to-Server / Save-to-Local buttons
• Stats, filters, recent updates, export/import

Forward the HTML file → recipient has everything. Open it locally → fully usable read-only.

Two layers

~/.claude/skills/single-html-dashboard/         # skill engine (global)
├── SKILL.md
├── scripts/
│   ├── dashboard.py         # CRUD + render + serve dispatcher
│   └── save_server.py       # generic save endpoint (per-project)
├── templates/
│   └── dashboard.html.src   # canonical raw HTML template (full-feature dashboard)
└── schemas/
    └── default.yaml

<project-root>/.dashboard/                      # per-project state
├── config.yaml             # project name/id, status seed, save endpoint, publish target
├── items.json              # git-friendly mirror (canonical: HTML; mirror: items.json)
├── public/
│   ├── latest.html         # render output (served by save_server at GET /)
│   └── dashboard_YYYYMMDD_HHMM.html  # versioned saves
└── backups/
    └── latest_*.html       # backup of prior latest.html on each save

Quick start (in any project)

SCRIPT=$HOME/.claude/skills/single-html-dashboard/scripts/dashboard.py

cd ~/my-project
python3 $SCRIPT init --name "My Project"

# CLI editing
python3 $SCRIPT add --json '{"title":"Wire up CI","progressStatus":"Todo","assignee":"me"}'
python3 $SCRIPT add --json '{"title":"Ship v0.1","progressStatus":"In Progress","dependencies":["auth"]}'
python3 $SCRIPT update --id <id> --json '{"progressStatus":"Done"}'
python3 $SCRIPT list
python3 $SCRIPT summary

# Start the per-project save server
python3 $SCRIPT serve
# → http://127.0.0.1:9876/  (browser-visible dashboard with Save-to-Server)

# Open .dashboard/public/latest.html locally → fully editable, Save-to-Local downloads HTML

Save-to-Server flow

1. Browser loads dashboard (data embedded in getInitialData())
2. User edits in browser (status changes, page-editor notes, new items via modal)
3. Click "💾 Save to Server" → POST full HTML to config.serve.endpoint (default /api/save)
4. save_server.py writes:
   • public/dashboard_YYYYMMDD_HHMM.html (versioned)
   • public/latest.html (canonical)
   • backups/latest_<ts>.html (previous version)
   • items.json (extracted from the saved HTML via regex on getInitialData())
5. Old versions pruned (keeps last serve.max_versions, default 10)

If POST fails → button falls back to local download. HTML is always portable.

Project config (.dashboard/config.yaml)

project_id: my-project
project_name: My Project
default_password: my-project       # initial unlock password (changeable from settings ⚙️)
data_version: "2.0"

# Seed values that get "branded" tag colors. Anything else gets hash-based color.
# Free-text inputs allow any value at runtime; this just seeds the autocomplete.
status_options: []                 # [] = no defaults; all values come from data
source_options: []

serve:
  port: 9876
  bind: 127.0.0.1
  endpoint: /api/save
  host_match: ""                   # "" = always try server; set to "example.com" to gate
  max_versions: 10

publish:
  type: local                      # local | nginx | github
  target: <project>/.dashboard/public

GitHub sync

Push your dashboard to a GitHub repository for version-controlled backup and collaboration. Useful when a dashboard runs on one device but its data needs to be visible from others (or just for a free off-device snapshot).

# .dashboard/config.yaml
publish:
  type: github
  repo_path: /path/to/local/repo       # local clone of the target GitHub repo
  branch: main                          # branch to push to (default: main)
  commit_prefix: "dashboard:"           # prefix for auto commit messages
  html_filename: dashboard.html         # filename in the repo (default: dashboard.html)
                                        # can be nested, e.g. "team-a/dashboard.html"
  push_items_json: true                 # also push items.json for clean diffs (default: true)
  auto_push: true                       # auto push after commit (default: true)

# Render and push in one step
python3 $SCRIPT render --publish

# Push current dashboard without re-rendering
python3 $SCRIPT sync

What gets pushed

• dashboard.html — Self-contained HTML (the full product)
• items.json — Extracted data array (git-friendly, clean diffs)

The items.json file is derived from the HTML's getInitialData() function. It exists purely for readable diffs in git history. The HTML remains the canonical artifact. When html_filename is nested under a subdirectory, items.json is written alongside it so multiple dashboards can coexist in one repo.

Built-in features

Everything. UI is unchanged. Functions kept verbatim:

• Password-protected unlock with view-only default
• Project Settings (⚙️) — editable project name, locked project ID
• Save to Server + Save to Local (with download fallback)
• Unsaved changes indicator + beforeunload warning
• Stats bar (now dynamic: one card per observed status, always Total first)
• Recent Updates section (last 10 modified items)
• Search input + status filter + dependencies filter
• Add / Edit / Delete / View / Page per row
• Full-screen Page editor (notes textarea per item, lastSaved timestamp)
• Export Database (.db sqlite), Export JSON, Export CSV
• Import Database (.db), Import JSON
• Clear All
• Hash-based dynamic colors for unknown statuses/sources
• Back to top floating button
• Toast notifications

What's generalized

• Status / source / dependencies → free-text with datalist autocomplete that learns from your data
• Stats bar dynamic — one card per observed status (was 7 hardcoded Chinese labels)
• Filter dropdowns dynamic — populated from observed values
• PROJECT_CONFIG parameterized from config.yaml
• Save endpoint URL parameterized (hardcoded prior to v1)
• Smart save detection — checks protocol !== 'file:' by default; configurable via serve.host_match
• Save server — reads .dashboard/config.yaml for port / bind / endpoint / path
• Runtime injections stripped — browser-extension and runtime-injected tracking scripts are removed at render time

Commands

Command	Purpose
init --name "<project>"	Scaffold .dashboard/ in CWD + render initial HTML
add --json '{...}'	Add item; auto re-renders HTML
update --id <id> --json '{...}'	Patch item; auto re-renders HTML
remove --id <id>	Delete item; auto re-renders HTML
list [--status X] [--search "..."] [--json]	List items
get --id <id>	Print single item JSON
render [--publish]	Regenerate latest.html (publish copies to config.publish.target)
sync	Push current latest.html + items.json to GitHub (requires publish.type: github)
summary	Count items by status
serve	Start save server using config.serve.*

Item schema

{
  "id": "item_<unix_ts>_<random>",
  "progressStatus": "<free-text>",
  "title": "<question or short label>",
  "description": "<the requirement / detail>",
  "component": "<which subsystem>",
  "technicalDetails": "<specs, deadlines>",
  "assignee": "<who owns this>",
  "dependencies": ["<list of free-text labels>"],
  "source": "<where this came from>",
  "lastUpdated": "YYYY-MM-DD",
  "lastModified": "<ISO timestamp>",
  "attachments": ["<relative paths>"],
  "pageContent": "<notes textarea>",
  "pageLastSaved": "<localized timestamp>"
}

Triggers

Activate when the user says:

• "dashboard", "项目 dashboard", "tracker", "进度看板"
• "init dashboard", "set up dashboard for this project"
• "add dashboard item", "update progress status"
• "save dashboard", "dashboard 保存到服务器"
• "render dashboard", "dashboard 重新生成"