Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"name": "html-kit",
"description": "Self-hosted marketplace for the html-kit plugin.",
"owner": {
"name": "KN",
"url": "https://github.com/nyashkn"
},
"plugins": [
{
"name": "html-kit",
"source": "./",
"description": "Turn any plan, spec, decision doc, synth, or dataset into a polished, self-contained single-page HTML artifact, styled in the Anthropic palette, with one /html-kit command inside Claude Code."
}
]
}
19 changes: 19 additions & 0 deletions .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"name": "html-kit",
"version": "0.5.0",
"description": "Turn any plan, spec, decision doc, synth, or dataset into a polished, self-contained single-page HTML artifact in the Anthropic palette. Skills: html-kit, html-kit-drain, html-kit-add-to-patterns.",
"author": {
"name": "KN",
"url": "https://github.com/nyashkn"
},
"homepage": "https://github.com/nyashkn/html-kit",
"repository": "https://github.com/nyashkn/html-kit",
"license": "MIT",
"keywords": [
"html",
"artifacts",
"skills",
"visualization",
"claude-code"
]
}
34 changes: 21 additions & 13 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ adding a new archetype.

## Dev setup

Prerequisites: [Bun](https://bun.sh) and Claude Code.
Prerequisites: [Bun](https://bun.sh) >= 1.1 and Claude Code.

```bash
bun install # dev deps: Playwright, Pagefind, @types/bun
Expand All @@ -21,9 +21,9 @@ re-run after pulling updates or adding a skill.
The suite is [Playwright](https://playwright.dev):

```bash
bun test # headless run
bun test:headed # visible browser
bun test:ui # Playwright UI mode
bun run test # headless run
bun run test:headed # visible browser
bun run test:ui # Playwright UI mode
```

If this is your first run, install the browser binaries once:
Expand All @@ -39,20 +39,28 @@ An archetype is just a directory under `archetypes/`. To add one:
1. Create `archetypes/<slug>/exemplar.html` — a complete, self-contained page
(inline CSS / SVG / JS, no external assets) using the Anthropic palette
tokens from `tokens/anthropic-palette.css`. If it's vendored from a
third-party source, keep the inline `<!-- source: … | MIT license -->`
comment at the top and add it to `ATTRIBUTION.md`.
2. Create `archetypes/<slug>/recipe.md` — *when to use* this archetype, the
*expected data shape*, and a `## Gotchas` section. The router skill reads
these to choose between archetypes, so be specific.
3. Add a row to the "Archetype selection cheatsheet" in
`skill/html-kit/SKILL.md`.
4. If the README's archetype count changes, update it.
third-party source, keep its license header/provenance comment at the top
and add it to `ATTRIBUTION.md` (note the exact license — upstream sources
can change license over time, don't assume MIT).
2. Create `archetypes/<slug>/recipe.md` starting with frontmatter:
```yaml
---
name: <slug>
when: <one-line routing phrase the router skill matches on>
---
```
followed by *when to use* this archetype, the *expected data shape*, and a
`## Gotchas` section.
3. Run `bun run cheatsheet` — it regenerates the "Archetype selection
cheatsheet" in `skills/html-kit/SKILL.md` and the archetype count in
`README.md` from every `recipe.md`'s frontmatter. Don't hand-edit either
table. CI runs `bun run cheatsheet --check` and fails if you forgot.

No installer edit is needed — archetypes are discovered at render time.

## Adding a skill

Drop a directory under `skill/<name>/` with a `SKILL.md` (YAML frontmatter +
Drop a directory under `skills/<name>/` with a `SKILL.md` (YAML frontmatter +
body) and re-run `./install.sh`. Skills are auto-discovered; no edits to the
installer are required.

Expand Down
170 changes: 170 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
name: CI

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
test:
name: Playwright suite
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4

- uses: oven-sh/setup-bun@v2
with:
bun-version: latest

- name: Install dependencies
run: bun install

- name: Check generated cheatsheet is up to date
run: bun run cheatsheet --check

- name: Install Playwright browsers
run: bunx playwright install --with-deps chromium

# playwright.config.ts targets a singleton daemon on :63839 rather than
# a webServer block (the daemon is PID-locked and shouldn't be
# respawned per test run), so start and health-check it ourselves.
#
# Health-check hits /api/repos rather than "/": "/" 404s until
# ~/.html-kit/_daemon/index.html has been built (never true yet here —
# HOME is the runner's empty home), while /api/repos always returns
# 200 JSON regardless of build state. Playwright's globalSetup
# (tests/global-setup.ts) registers this repo and builds the index.
- name: Start html-kit daemon
run: |
bun scripts/html-kit-daemon.ts > daemon.log 2>&1 &
for i in $(seq 1 30); do
if curl -sf http://localhost:63839/api/repos > /dev/null; then
echo "daemon is up"
exit 0
fi
sleep 1
done
echo "daemon did not become healthy in time"
cat daemon.log
exit 1

- name: Run Playwright suite
run: bun run test

plugin-eval-free:
name: Plugin eval (free graders)
needs: []
runs-on: ubuntu-latest
timeout-minutes: 30
if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
steps:
- uses: actions/checkout@v4

- uses: oven-sh/setup-bun@v2
with:
bun-version: latest

- name: Install dependencies
run: bun install

- name: Install sandbox backend (bubblewrap + socat)
run: |
sudo apt-get update -qq && sudo apt-get install -y -qq bubblewrap socat
if [ "$(sysctl -n kernel.apparmor_restrict_unprivileged_userns 2>/dev/null)" = "1" ]; then
printf 'abi <abi/4.0>,\ninclude <tunables/global>\nprofile bwrap /usr/bin/bwrap flags=(unconfined) {\n userns,\n include if exists <local/bwrap>\n}\n' | sudo tee /etc/apparmor.d/bwrap >/dev/null
sudo systemctl reload apparmor
fi

- name: Install Claude Code CLI
run: |
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.273
echo "$HOME/.local/bin" >> "$GITHUB_PATH"

- name: Run free-grader eval cases
env:
CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
run: |
claude plugin eval . \
--tag free \
--trust-plugin \
--scaffold \
--allow-tools Bash Write Edit \
--ablation none \
--model claude-haiku-4-5 \
--threshold 0.8 \
--max-cost-usd 5 \
--no-publish \
--json evals/results/free-result.json

- name: Summarize free eval results
if: always()
run: |
jq -r '.cases[] | .name as $n | .arms.with[] | "\($n): score=\(.score) error=\(.error // "none")", (.graders[]? | " \(.name): \(.passed)")' evals/results/free-result.json || true

- name: Upload free eval report
if: always()
uses: actions/upload-artifact@v4
with:
name: eval-free-report
path: evals/results/
if-no-files-found: ignore

plugin-eval-paid:
name: Plugin eval (llm/baseline graders)
runs-on: ubuntu-latest
timeout-minutes: 30
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v4

- uses: oven-sh/setup-bun@v2
with:
bun-version: latest

- name: Install dependencies
run: bun install

- name: Install sandbox backend (bubblewrap + socat)
run: |
sudo apt-get update -qq && sudo apt-get install -y -qq bubblewrap socat
if [ "$(sysctl -n kernel.apparmor_restrict_unprivileged_userns 2>/dev/null)" = "1" ]; then
printf 'abi <abi/4.0>,\ninclude <tunables/global>\nprofile bwrap /usr/bin/bwrap flags=(unconfined) {\n userns,\n include if exists <local/bwrap>\n}\n' | sudo tee /etc/apparmor.d/bwrap >/dev/null
sudo systemctl reload apparmor
fi

- name: Install Claude Code CLI
run: |
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.273
echo "$HOME/.local/bin" >> "$GITHUB_PATH"

- name: Run paid-grader eval cases
env:
CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
run: |
claude plugin eval . \
--tag paid \
--trust-plugin \
--allow-tools Bash Write Edit \
--model claude-haiku-4-5 \
--judge-model claude-haiku-4-5 \
--threshold 0.8 \
--max-cost-usd 15 \
--no-publish \
--json evals/results/paid-result.json

- name: Summarize paid eval results
if: always()
run: |
jq -r '.cases[] | .name as $n | .arms.with[] | "\($n): score=\(.score) error=\(.error // "none")", (.graders[]? | " \(.name): \(.passed)")' evals/results/paid-result.json || true

- name: Upload paid eval report
if: always()
uses: actions/upload-artifact@v4
with:
name: eval-paid-report
path: evals/results/
if-no-files-found: ignore
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@ playwright-report/
!.html-kit/.config.json
!.html-kit/01_v0.3.0-before-after-eval.html
!.html-kit/02_v0.4.0-interaction-loop.html
.html-kit/_archive/
42 changes: 40 additions & 2 deletions ATTRIBUTION.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
# Third-party attribution

## Vendored exemplars — `thariqs/html-effectiveness`
All HTML exemplars under `archetypes/<slug>/exemplar*.html` are vendored from
[ThariqS/html-effectiveness](https://github.com/ThariqS/html-effectiveness).
That upstream repo relicensed from MIT to Apache-2.0 on 2026-05-18; which
license applies to a given exemplar depends on when it was vendored (see the
two sections below and each file's own header comment).

The HTML exemplars under `archetypes/<slug>/exemplar*.html` are vendored from:
## Vendored exemplars — MIT (`thariqs/html-effectiveness`, root-level)

The exemplars vendored on 2026-05-14 (before the upstream relicense) are:

- **Source:** [ThariqS/html-effectiveness](https://github.com/ThariqS/html-effectiveness)
- **License:** MIT
Expand All @@ -19,6 +25,38 @@ The exemplars have been adapted (Anthropic palette tokens, `data-component`
annotations, structural trims) for use as html-kit archetype templates; the
original MIT terms continue to apply to the upstream-derived portions.

## Vendored exemplars — Apache-2.0 (`thariqs/html-effectiveness`, `unknowns/`)

Upstream relicensed from MIT to Apache-2.0 on 2026-05-18. The 11 files below
were vendored on 2026-09-05 (commit `82fa96f`), after the relicense, from the
`unknowns/` sub-page — they carry Apache-2.0 in their own file headers and are
**unmodified** copies of the upstream source (no palette/structural edits):

| html-kit file | Upstream source |
|---|---|
| `archetypes/blindspot-pass/exemplar.html` | `unknowns/01-blindspot-pass.html` |
| `archetypes/vocab-teacher/exemplar.html` | `unknowns/02-color-grading-explainer.html` |
| `archetypes/design-reaction-review/exemplar.html` | `unknowns/03-design-directions.html` |
| `archetypes/throwaway-mock/exemplar.html` | `unknowns/04-toolbar-mock.html` |
| `archetypes/intervention-brainstorm/exemplar.html` | `unknowns/05-churn-brainstorm.html` |
| `archetypes/requirements-interview/exemplar.html` | `unknowns/06-interview.html` |
| `archetypes/reference-port-verify/exemplar.html` | `unknowns/07-reference-port.html` |
| `archetypes/tweakable-plan/exemplar.html` | `unknowns/08-implementation-plan.html` |
| `archetypes/implementation-notes/exemplar.html` | `unknowns/09-implementation-notes.html` |
| `archetypes/buy-in-pitch/exemplar.html` | `unknowns/10-pitch-doc.html` |
| `archetypes/merge-quiz/exemplar.html` | `unknowns/11-change-quiz.html` |

Each file's header comment reads:

```html
<!-- Copyright 2026 Anthropic PBC · SPDX-License-Identifier: Apache-2.0 -->
```

Upstream copyright: **Copyright 2026 Anthropic PBC**. Full license text:
[`LICENSES/Apache-2.0.txt`](LICENSES/Apache-2.0.txt). Upstream carries no
`NOTICE` file (checked at repo root), so there is nothing to reproduce under
Apache-2.0 §4(d).

## Other dependencies

Runtime/dev dependencies are declared in `package.json` and carry their own
Expand Down
46 changes: 46 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,52 @@ are pinned in `package.json` / skill manifests; the heading dates use ISO-8601.

## [Unreleased]

## [0.5.0] - Unreleased

Plugin packaging: html-kit installs via `/plugin` alongside the existing
`install.sh` path.

### Added

- `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` — plugin
manifest and self-hosted single-plugin marketplace (`source: "./"`).
- `hooks/hooks.json` — `PostToolUse` hook runs render-audit on every Write/Edit
and feeds audit failures back to Claude after each write (the write itself
already happened — `PostToolUse` doesn't block it). `render-audit.ts` also
gained external-asset checks (fails a render that references a CDN
script/style/font/image — artifacts must be self-contained) and an opt-out
for the palette-token check via
`<meta name="html-kit:palette" content="custom">`.
- `scripts/build-cheatsheet.ts` (`bun run cheatsheet`, `--check` for CI) —
regenerates the archetype cheatsheet in `skills/html-kit/SKILL.md` and the
archetype count in `README.md` from each `archetypes/<slug>/recipe.md`
frontmatter (`name` + `when`), replacing hand-edited rows.
- `recipe.md` frontmatter — `name:` and `when:` (a one-line routing phrase)
are now required at the top of every archetype's `recipe.md`, consumed by
`build-cheatsheet.ts`.
- `evals/` — plugin eval cases (`claude plugin eval`).
- `.github/workflows/ci.yml` — CI: Playwright suite + plugin evals.
- Licence attribution fix — upstream `ThariqS/html-effectiveness` relicensed
MIT → Apache-2.0 on 2026-05-18; the 11 exemplars vendored after that date
(commit `82fa96f`) are Apache-2.0, not MIT. `ATTRIBUTION.md` now splits
vendored exemplars by license and per-file source mapping, and
`LICENSES/Apache-2.0.txt` carries the full license text.

### Changed

- `skill/` renamed to `skills/` for plugin auto-discovery.
- All 3 `SKILL.md` files call bundled scripts via
`bun ${CLAUDE_SKILL_DIR}/scripts/<script>.ts`, with a matching
`allowed-tools: Bash(bun ${CLAUDE_SKILL_DIR}/scripts/*)` frontmatter rule,
so scripts run without a permission prompt regardless of cwd.
- `build-index.ts` / `discover-roots.ts` no longer default to a hardcoded
scan root — an empty `scanRoots` means no scan until configured.

### Fixed

- Daemon rebuild loop stopped; orphaned staging directories cleaned up; logs
now rotate instead of growing unbounded.

## [0.4.1] - 2026-05-19

Polish on top of v0.4.0 — modal skin matches the rest of html-kit, and a
Expand Down
Loading
Loading