From 131960e5261da66f9f22b2c0ae08346ab74417e4 Mon Sep 17 00:00:00 2001 From: KN Date: Wed, 16 Sep 2026 20:35:20 +0300 Subject: [PATCH 01/12] fix(daemon): stop rebuild loops, clean orphaned staging, rotate logs - ignore watch events from the daemon's own _daemon/ output dir - skip overlapping builds; 1.5s trailing debounce; --incremental rebuilds - watch each ~/.html-kit slug dir instead of a recursive KIT_HOME watch (macOS FSEvents fired spurious parent-dir events) - rotate out.log/daemon.log at 5 MB on startup - build-index: remove staged copies whose source is gone; warn and skip sources that vanish or fail to stage - gitignore .html-kit/_archive/ Co-Authored-By: Claude Opus 5 (1M context) --- .gitignore | 1 + scripts/build-index.ts | 52 ++++++++++++++++++++++++- scripts/html-kit-daemon.ts | 77 ++++++++++++++++++++++++++++++++++---- 3 files changed, 121 insertions(+), 9 deletions(-) diff --git a/.gitignore b/.gitignore index 6e6cd8e..87ef0d0 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/scripts/build-index.ts b/scripts/build-index.ts index 57086b5..65b4767 100644 --- a/scripts/build-index.ts +++ b/scripts/build-index.ts @@ -178,6 +178,45 @@ function stageFile(srcPath: string, project: string, args: Args): string { return stagedPath; } +// --- clean orphaned staging entries --------------------------------------- +// Remove staged files whose source artifact no longer exists on disk. +// This prevents ENOENT noise in pagefind and stale index entries. +function cleanOrphanedStaging(repos: ReposMap) { + if (!existsSync(STAGING_DIR)) return; + let projectDirs: string[]; + try { projectDirs = readdirSync(STAGING_DIR); } catch { return; } + + // Build a set of known source roots so we can check if a source still exists. + const sourceRoots: { project: string; dir: string }[] = []; + if (existsSync(KIT_HOME)) { + for (const entry of readdirSync(KIT_HOME)) { + if (entry === "_daemon" || entry.startsWith("_")) continue; + sourceRoots.push({ project: entry, dir: join(KIT_HOME, entry) }); + } + } + for (const [slug, repoDir] of Object.entries(repos)) { + sourceRoots.push({ project: slug, dir: join(repoDir, ".html-kit") }); + } + const sourceByProject = new Map(sourceRoots.map(r => [r.project, r.dir])); + + for (const project of projectDirs) { + const stagingProjectDir = join(STAGING_DIR, project); + let files: string[]; + try { files = readdirSync(stagingProjectDir); } catch { continue; } + + const srcDir = sourceByProject.get(project); + for (const file of files) { + // If no source dir for this project, or source file is gone → remove staged copy. + const srcPath = srcDir ? join(srcDir, file) : null; + if (!srcPath || !existsSync(srcPath)) { + const orphan = join(stagingProjectDir, file); + try { unlinkSync(orphan); process.stderr.write(`[build-index] cleaned orphan: ${project}/${file}\n`); } + catch { /* ignore */ } + } + } + } +} + // --- collect every artifact across HOME + repos -------------------------- function collectArtifacts(repos: ReposMap, args: Args): Artifact[] { const out: Artifact[] = []; @@ -188,9 +227,17 @@ function collectArtifacts(repos: ReposMap, args: Args): Artifact[] { if (seen.has(abs)) return; seen.add(abs); let st; - try { st = statSync(abs); } catch { return; } + try { st = statSync(abs); } catch { + process.stderr.write(`[build-index] warn: source gone, skipping ${abs}\n`); + return; + } if (!st.isFile()) return; - const stagedPath = stageFile(abs, project, args); + let stagedPath: string; + try { stagedPath = stageFile(abs, project, args); } + catch (e) { + process.stderr.write(`[build-index] warn: stage failed for ${abs}: ${String(e)}\n`); + return; + } let html = ""; try { html = readFileSync(stagedPath, "utf8"); } catch { /* keep empty */ } const filename = basename(abs); @@ -387,6 +434,7 @@ async function main() { } const repos = loadRepos(); + cleanOrphanedStaging(repos); const artifacts = collectArtifacts(repos, args); const projectSet = new Set(artifacts.map(a => a.project)); diff --git a/scripts/html-kit-daemon.ts b/scripts/html-kit-daemon.ts index 84e609a..13d6ead 100644 --- a/scripts/html-kit-daemon.ts +++ b/scripts/html-kit-daemon.ts @@ -3,7 +3,7 @@ // captures agent annotations, watches .html-kit/ dirs and rebuilds index on change. // Singleton on port 63839; PID lock at ~/.html-kit/_daemon/.pid. Errors to stderr. -import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync, watch, openSync, readSync, closeSync, appendFileSync } from "fs"; +import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync, watch, openSync, readSync, closeSync, appendFileSync, renameSync, readdirSync } from "fs"; import { join, resolve, sep } from "path"; import { homedir } from "os"; import { discoverRoots } from "./discover-roots"; @@ -18,6 +18,8 @@ const INDEX_HTML = join(DAEMON_DIR, "index.html"); const PAGEFIND_DIR = join(DAEMON_DIR, "pagefind"); const PATTERN_FILE = join(import.meta.dir, "..", "patterns", "annotation-strip.md"); const OVERRIDES_FILE = join(import.meta.dir, "..", "assets", "pagefind-overrides.css"); +const OUT_LOG = join(DAEMON_DIR, "out.log"); +const LOG_MAX_BYTES = 5 * 1024 * 1024; // 5 MB cap before rotation // Reserved URL prefixes that must NEVER be treated as slug routes. Order // matters only for the slug-name-collision rule in build-index.ts; here it @@ -133,37 +135,82 @@ function broadcastSSE(event: string, data: string) { } // --- filewatch + index rebuild ------------------------------------------- +// DAEMON_DIR is the directory build-index writes into (staging/, pagefind/, +// index.html). Watching it would cause every rebuild to trigger another rebuild +// (infinite loop). We filter it out from watch callbacks and also exclude it +// from the watched set entirely since KIT_HOME watch is recursive. +const DAEMON_DIR_SEP = DAEMON_DIR + sep; // e.g. ~/.html-kit/_daemon/ + let rebuildTimer: ReturnType | null = null; -function scheduleRebuild() { +let buildInFlight = false; // guard: skip-if-running to prevent overlapping builds + +function scheduleRebuild(triggerPath?: string) { + // Ignore events originating inside the daemon's own output dir. + if (triggerPath && (triggerPath === DAEMON_DIR || triggerPath.startsWith(DAEMON_DIR_SEP))) { + return; + } if (rebuildTimer) clearTimeout(rebuildTimer); rebuildTimer = setTimeout(() => { rebuildTimer = null; + if (buildInFlight) { + log("[html-kit-daemon] build already in flight, skipping duplicate trigger"); + return; + } const buildScript = join(import.meta.dir, "build-index.ts"); if (!existsSync(buildScript)) { log("[html-kit-daemon] build-index.ts not found, skipping rebuild"); broadcastSSE("index:updated", JSON.stringify({ ts: Date.now(), skipped: true })); return; } - const proc = Bun.spawn(["bun", buildScript], { stdout: "inherit", stderr: "inherit" }); + buildInFlight = true; + const proc = Bun.spawn(["bun", buildScript, "--incremental"], { stdout: "inherit", stderr: "inherit" }); proc.exited.then(() => { + buildInFlight = false; broadcastSSE("index:updated", JSON.stringify({ ts: Date.now() })); - }); - }, 500); + }).catch(() => { buildInFlight = false; }); + }, 1500); // 1.5s trailing debounce — coalesces rapid bursts } +// Slug dirs to skip inside KIT_HOME when enumerating per-slug watchers. +const KIT_HOME_SKIP = new Set(["_daemon", "_index", "_old_tmp", "_archive"]); + function setupWatchers(repos: ReposMap) { const dirs = new Set(); - if (existsSync(KIT_HOME)) dirs.add(KIT_HOME); + + // IMPORTANT: do NOT watch KIT_HOME recursively. macOS FSEvents fires spurious + // parent-dir events every ~1.5s on a recursive watcher which would re-trigger + // builds continuously even when no files change. Instead, watch each slug + // subdir inside KIT_HOME individually (non-recursive is enough: artifacts are + // flat *.html files directly inside each slug dir). + if (existsSync(KIT_HOME)) { + try { + for (const entry of readdirSync(KIT_HOME)) { + if (KIT_HOME_SKIP.has(entry) || entry.startsWith(".")) continue; + const slugDir = join(KIT_HOME, entry); + try { if (statSync(slugDir).isDirectory()) dirs.add(slugDir); } catch { /* skip */ } + } + } catch { /* ignore KIT_HOME read errors */ } + } + + // Watched repo dirs from repos.json. These contain user artifact .html-kit/ subdirs. for (const dir of Object.values(repos)) { if (existsSync(dir)) dirs.add(dir); } + for (const dir of dirs) { try { - watch(dir, { recursive: true }, () => scheduleRebuild()); + watch(dir, { recursive: true }, (_event, filename) => { + // Build an absolute path from the watch root + filename to filter daemon dir. + const abs = filename ? resolve(dir, filename) : dir; + scheduleRebuild(abs); + }); } catch (e) { log(`[html-kit-daemon] watch failed for ${dir}: ${String(e)}`); } } + // NOTE: new slug dirs added to KIT_HOME after startup won't be auto-watched. + // POST /api/repos and POST /api/discover already arm watchers for new dirs on + // demand, so this only affects dirs created outside those APIs. Acceptable. return dirs.size; } @@ -445,9 +492,25 @@ function serveArtifact(slug: string, tail: string, repos: ReposMap): Response { }); } +// --- log rotation --------------------------------------------------------- +// Rotate out.log on startup (daemon writes stderr there via shell redirect). +// Keep one prior generation (.1). Also truncate daemon.log if oversized. +function rotateLogs() { + for (const logPath of [OUT_LOG, join(DAEMON_DIR, "daemon.log")]) { + try { + if (!existsSync(logPath)) continue; + if (statSync(logPath).size < LOG_MAX_BYTES) continue; + const prev = logPath + ".1"; + try { if (existsSync(prev)) unlinkSync(prev); } catch { /* ignore */ } + try { renameSync(logPath, prev); } catch { /* ignore */ } + } catch { /* never crash the daemon over log rotation */ } + } +} + // --- main ----------------------------------------------------------------- async function main() { acquireLock(); + rotateLogs(); const cleanup = () => { releaseLock(); process.exit(0); }; process.on("SIGINT", cleanup); From 736a31a74bec588742ca1334189f246c62fdd761 Mon Sep 17 00:00:00 2001 From: KN Date: Wed, 16 Sep 2026 20:35:20 +0300 Subject: [PATCH 02/12] refactor: rename skill/ to skills/ for plugin auto-discovery Co-Authored-By: Claude Opus 5 (1M context) --- {skill => skills}/html-kit-add-to-patterns/SKILL.md | 0 {skill => skills}/html-kit-add-to-patterns/archetypes | 0 {skill => skills}/html-kit-add-to-patterns/assets | 0 {skill => skills}/html-kit-add-to-patterns/patterns | 0 {skill => skills}/html-kit-add-to-patterns/scripts | 0 {skill => skills}/html-kit-add-to-patterns/tokens | 0 {skill => skills}/html-kit-drain/SKILL.md | 0 {skill => skills}/html-kit-drain/archetypes | 0 {skill => skills}/html-kit-drain/assets | 0 {skill => skills}/html-kit-drain/patterns | 0 {skill => skills}/html-kit-drain/scripts | 0 {skill => skills}/html-kit-drain/tokens | 0 {skill => skills}/html-kit/SKILL.md | 0 {skill => skills}/html-kit/archetypes | 0 {skill => skills}/html-kit/assets | 0 {skill => skills}/html-kit/patterns | 0 {skill => skills}/html-kit/references/delegation-rationale.md | 0 {skill => skills}/html-kit/scripts | 0 {skill => skills}/html-kit/tokens | 0 19 files changed, 0 insertions(+), 0 deletions(-) rename {skill => skills}/html-kit-add-to-patterns/SKILL.md (100%) rename {skill => skills}/html-kit-add-to-patterns/archetypes (100%) rename {skill => skills}/html-kit-add-to-patterns/assets (100%) rename {skill => skills}/html-kit-add-to-patterns/patterns (100%) rename {skill => skills}/html-kit-add-to-patterns/scripts (100%) rename {skill => skills}/html-kit-add-to-patterns/tokens (100%) rename {skill => skills}/html-kit-drain/SKILL.md (100%) rename {skill => skills}/html-kit-drain/archetypes (100%) rename {skill => skills}/html-kit-drain/assets (100%) rename {skill => skills}/html-kit-drain/patterns (100%) rename {skill => skills}/html-kit-drain/scripts (100%) rename {skill => skills}/html-kit-drain/tokens (100%) rename {skill => skills}/html-kit/SKILL.md (100%) rename {skill => skills}/html-kit/archetypes (100%) rename {skill => skills}/html-kit/assets (100%) rename {skill => skills}/html-kit/patterns (100%) rename {skill => skills}/html-kit/references/delegation-rationale.md (100%) rename {skill => skills}/html-kit/scripts (100%) rename {skill => skills}/html-kit/tokens (100%) diff --git a/skill/html-kit-add-to-patterns/SKILL.md b/skills/html-kit-add-to-patterns/SKILL.md similarity index 100% rename from skill/html-kit-add-to-patterns/SKILL.md rename to skills/html-kit-add-to-patterns/SKILL.md diff --git a/skill/html-kit-add-to-patterns/archetypes b/skills/html-kit-add-to-patterns/archetypes similarity index 100% rename from skill/html-kit-add-to-patterns/archetypes rename to skills/html-kit-add-to-patterns/archetypes diff --git a/skill/html-kit-add-to-patterns/assets b/skills/html-kit-add-to-patterns/assets similarity index 100% rename from skill/html-kit-add-to-patterns/assets rename to skills/html-kit-add-to-patterns/assets diff --git a/skill/html-kit-add-to-patterns/patterns b/skills/html-kit-add-to-patterns/patterns similarity index 100% rename from skill/html-kit-add-to-patterns/patterns rename to skills/html-kit-add-to-patterns/patterns diff --git a/skill/html-kit-add-to-patterns/scripts b/skills/html-kit-add-to-patterns/scripts similarity index 100% rename from skill/html-kit-add-to-patterns/scripts rename to skills/html-kit-add-to-patterns/scripts diff --git a/skill/html-kit-add-to-patterns/tokens b/skills/html-kit-add-to-patterns/tokens similarity index 100% rename from skill/html-kit-add-to-patterns/tokens rename to skills/html-kit-add-to-patterns/tokens diff --git a/skill/html-kit-drain/SKILL.md b/skills/html-kit-drain/SKILL.md similarity index 100% rename from skill/html-kit-drain/SKILL.md rename to skills/html-kit-drain/SKILL.md diff --git a/skill/html-kit-drain/archetypes b/skills/html-kit-drain/archetypes similarity index 100% rename from skill/html-kit-drain/archetypes rename to skills/html-kit-drain/archetypes diff --git a/skill/html-kit-drain/assets b/skills/html-kit-drain/assets similarity index 100% rename from skill/html-kit-drain/assets rename to skills/html-kit-drain/assets diff --git a/skill/html-kit-drain/patterns b/skills/html-kit-drain/patterns similarity index 100% rename from skill/html-kit-drain/patterns rename to skills/html-kit-drain/patterns diff --git a/skill/html-kit-drain/scripts b/skills/html-kit-drain/scripts similarity index 100% rename from skill/html-kit-drain/scripts rename to skills/html-kit-drain/scripts diff --git a/skill/html-kit-drain/tokens b/skills/html-kit-drain/tokens similarity index 100% rename from skill/html-kit-drain/tokens rename to skills/html-kit-drain/tokens diff --git a/skill/html-kit/SKILL.md b/skills/html-kit/SKILL.md similarity index 100% rename from skill/html-kit/SKILL.md rename to skills/html-kit/SKILL.md diff --git a/skill/html-kit/archetypes b/skills/html-kit/archetypes similarity index 100% rename from skill/html-kit/archetypes rename to skills/html-kit/archetypes diff --git a/skill/html-kit/assets b/skills/html-kit/assets similarity index 100% rename from skill/html-kit/assets rename to skills/html-kit/assets diff --git a/skill/html-kit/patterns b/skills/html-kit/patterns similarity index 100% rename from skill/html-kit/patterns rename to skills/html-kit/patterns diff --git a/skill/html-kit/references/delegation-rationale.md b/skills/html-kit/references/delegation-rationale.md similarity index 100% rename from skill/html-kit/references/delegation-rationale.md rename to skills/html-kit/references/delegation-rationale.md diff --git a/skill/html-kit/scripts b/skills/html-kit/scripts similarity index 100% rename from skill/html-kit/scripts rename to skills/html-kit/scripts diff --git a/skill/html-kit/tokens b/skills/html-kit/tokens similarity index 100% rename from skill/html-kit/tokens rename to skills/html-kit/tokens From e4987b23a550b974e51c8db01c6d24f5b8c59293 Mon Sep 17 00:00:00 2001 From: KN Date: Wed, 16 Sep 2026 21:04:47 +0300 Subject: [PATCH 03/12] docs(archetypes): genericize recipe gotchas, add when: frontmatter - replace client, vendor and internal project names in recipe gotchas and patterns with generic descriptions; every lesson kept - move dated gotcha entries above the field-manual footer, date-ordered - every recipe.md starts with name/when frontmatter (routing phrase used to generate the SKILL.md cheatsheet) Co-Authored-By: Claude Opus 5 (1M context) --- archetypes/animation-sandbox/recipe.md | 5 +++++ archetypes/annotated-flowchart/recipe.md | 12 ++++++++++++ archetypes/blindspot-pass/recipe.md | 5 +++++ archetypes/buy-in-pitch/recipe.md | 5 +++++ archetypes/clickable-flow/recipe.md | 6 ++++++ archetypes/component-variants/recipe.md | 8 ++++++++ archetypes/design-reaction-review/recipe.md | 5 +++++ archetypes/design-system/recipe.md | 5 +++++ archetypes/explainer/recipe.md | 7 +++++++ archetypes/exploration-code-approaches/recipe.md | 7 +++++++ archetypes/exploration-visual-designs/recipe.md | 5 +++++ archetypes/feature-flag-editor/recipe.md | 5 +++++ archetypes/implementation-notes/recipe.md | 5 +++++ archetypes/implementation-plan/recipe.md | 7 ++++++- archetypes/incident-timeline/recipe.md | 5 +++++ archetypes/intervention-brainstorm/recipe.md | 5 +++++ archetypes/merge-quiz/recipe.md | 5 +++++ archetypes/module-map/recipe.md | 5 +++++ archetypes/pr-description/recipe.md | 5 +++++ archetypes/pr-review/recipe.md | 5 +++++ archetypes/prompt-tuner/recipe.md | 5 +++++ archetypes/reference-port-verify/recipe.md | 5 +++++ archetypes/requirements-interview/recipe.md | 5 +++++ archetypes/slide-deck/recipe.md | 5 +++++ archetypes/svg-figure-sheet/recipe.md | 5 +++++ archetypes/throwaway-mock/recipe.md | 5 +++++ archetypes/triage-board/recipe.md | 5 +++++ archetypes/tweakable-plan/recipe.md | 5 +++++ archetypes/vocab-teacher/recipe.md | 5 +++++ archetypes/weekly-status/recipe.md | 5 +++++ patterns/swimlane-flow.md | 2 +- 31 files changed, 167 insertions(+), 2 deletions(-) diff --git a/archetypes/animation-sandbox/recipe.md b/archetypes/animation-sandbox/recipe.md index e42f51c..cdc8c0f 100644 --- a/archetypes/animation-sandbox/recipe.md +++ b/archetypes/animation-sandbox/recipe.md @@ -1,3 +1,8 @@ +--- +name: animation-sandbox +when: use when tuning a single transition or animation in isolation with duration/easing sliders and a live preview +--- + # animation-sandbox **Use when:** tuning a single transition/animation in isolation — sliders for duration/easing, live preview. diff --git a/archetypes/annotated-flowchart/recipe.md b/archetypes/annotated-flowchart/recipe.md index e65d9d5..1af17e0 100644 --- a/archetypes/annotated-flowchart/recipe.md +++ b/archetypes/annotated-flowchart/recipe.md @@ -1,3 +1,8 @@ +--- +name: annotated-flowchart +when: use when explaining a process as a clickable flowchart with timings and failure paths +--- + # annotated-flowchart **Use when:** explaining a process (deploy pipeline, request flow, state machine) as a clickable flowchart with timings and failure paths. @@ -17,6 +22,13 @@ - 2026-05-13: artifacts must be fully self-contained. Inline + + +
+ +
+
HTML-KIT · INDEX · DAEMON :63839
+

All artifacts

+

Cross-project search via ⌘K · live annotation loop

+
+ +
+
+ 17 docs · 7 projects · updated 2026-05-19 01:35 +
+
+ + + + + +
+ + + + + +
+ +
+ Daemon endpoints · what :63839 serves +
+

Single Bun process. All routes resolve against the per-repo .html-kit/ dir or its pagefind index.

+
# method  path                                purpose
+GET   /                                   # index page (this view)
+GET   /p/<slug>/                          # project listing
+GET   /p/<slug>/<file>.html              # single artifact, w/ injected head
+
+POST  /api/annotate                       # body: {path, selector, note}
+GET   /api/annotations/<path>             # list notes for one artifact
+POST  /api/repos                          # register a repo by abs path
+
+GET   /pagefind/*                         # static pagefind index + ui assets
+GET   /search?q=...                        # json search proxy (cross-repo)
+
+
+ +
+ Annotation injection · what daemon adds to every <head> +
+

When daemon serves an artifact, it streams the file and rewrites the head to wire in pagefind + the annotation strip. The original HTML stays self-contained on disk.

+
<head data-component="html-kit-injected">
+  <!-- original head preserved above this line -->
+
+  <link rel="stylesheet" href="/pagefind/pagefind-ui.css">
+  <script src="/pagefind/pagefind-ui.js" defer></script>
+
+  <script src="/_kit/annotation-strip.js" defer></script>
+  <link rel="stylesheet" href="/_kit/annotation-strip.css">
+
+  <meta name="html-kit:repo" content="example-startup-plans">
+  <meta name="html-kit:path" content="05_smtp-config.html">
+</head>
+
+
+ +
+ Register a new repo · bun run html-kit:register +
+

From inside any repo, register it with the running daemon. The repo's .html-kit/ dir gets watched and indexed; new artifacts appear in the index within ~1s.

+
# 1. start the daemon once (any terminal)
+bun run html-kit:daemon
+› html-kit daemon listening on :63839
+
+# 2. inside any repo with .html-kit/ artifacts
+cd ~/code/example-startup-plans
+bun run html-kit:register
+
+# under the hood, POST /api/repos
+curl -sX POST http://localhost:63839/api/repos \
+  -H "content-type: application/json" \
+  -d '{"path":"~/code/example-startup-plans","slug":"example-startup-plans"}'
+
+# response
+{ "ok": true, "slug": "example-startup-plans", "watched": 5 }
+
+
+ +
+ +
+ + + + + +
+ + + + + diff --git a/scripts/build-index.ts b/scripts/build-index.ts index 65b4767..02cffb5 100644 --- a/scripts/build-index.ts +++ b/scripts/build-index.ts @@ -37,9 +37,10 @@ const STAGING_DIR = join(DAEMON_DIR, "staging"); const PAGEFIND_DIR = join(DAEMON_DIR, "pagefind"); const REPOS_FILE = join(DAEMON_DIR, "repos.json"); const INDEX_HTML = join(DAEMON_DIR, "index.html"); -const TEMPLATE = resolve(import.meta.dir, "..", ".html-kit", "03_v0.4.0-index-mockup.html"); +const TEMPLATE = join(import.meta.dir, "..", "assets", "index-template.html"); -const SKIP_DIRS = new Set(["_daemon", "_index", "_old_tmp", "_archive"]); +// Any "_"-prefixed dir under ~/.html-kit is daemon/skill-internal state, not a +// project (e.g. _daemon, _archive, and skill-written _gotchas / _patterns). const STAGED_MARKER = ""; type Args = { incremental: boolean; verbose: boolean }; @@ -258,7 +259,7 @@ function collectArtifacts(repos: ReposMap, args: Args): Artifact[] { // ~/.html-kit//*.html if (existsSync(KIT_HOME)) { for (const entry of readdirSync(KIT_HOME)) { - if (SKIP_DIRS.has(entry)) continue; + if (entry.startsWith("_")) continue; const dir = join(KIT_HOME, entry); let st; try { st = statSync(dir); } catch { continue; } @@ -309,19 +310,22 @@ function renderRow(a: Artifact, project: string): string { } function prettyProjectLabel(project: string, repos: ReposMap): { primary: string; secondary: string } { - // Prefer registered repo path: primary = basename(dir), secondary = path under common dev root + // Prefer registered repo path: primary = basename(dir), secondary = path relative to HOME const dir = repos[project]; if (dir) { const segments = dir.split("/").filter(Boolean); const primary = segments[segments.length - 1] || project; - const devRoot = "code"; - const idx = dir.indexOf(devRoot); - const secondary = idx >= 0 ? dir.slice(idx + devRoot.length + 1) : dir; + // Strip HOME prefix to get relative path; if dir is outside HOME, use full dir + const secondary = dir.startsWith(HOME + "/") + ? dir.slice((HOME + "/").length) + : dir; return { primary, secondary }; } - // Fallback for ~/.html-kit// entries (slug = cwd path-mangled, slashes → '-') - // Strip common prefix; show remainder as secondary, last segment as primary. - const stripped = project.replace(/^Users-[^-]+-code-/, ""); + // Fallback for ~/.html-kit// entries (slug = cwd path-mangled, slashes → '-', + // leading dash stripped — see resolve-out-path.ts). Strip the actual mangled HOME + // prefix rather than guessing at "Users--", so hyphenated usernames work. + const homePrefix = HOME.replace(/\//g, "-").replace(/^-/, "") + "-"; + const stripped = project.startsWith(homePrefix) ? project.slice(homePrefix.length) : project; if (stripped !== project) { const tokens = stripped.split("-"); const primary = tokens.length > 1 ? tokens.slice(-2).join("-") : tokens[0]; diff --git a/scripts/discover-roots.ts b/scripts/discover-roots.ts index fb80568..0203d41 100644 --- a/scripts/discover-roots.ts +++ b/scripts/discover-roots.ts @@ -29,7 +29,7 @@ const DAEMON_DIR = join(KIT_HOME, "_daemon"); const CONFIG_FILE = join(DAEMON_DIR, "config.json"); const REPOS_FILE = join(DAEMON_DIR, "repos.json"); -const DEFAULT_SCAN_ROOTS = [join(HOME, "code")]; +const DEFAULT_SCAN_ROOTS: string[] = []; const DEFAULT_MAX_DEPTH = 6; const SKIP_NAMES = new Set([ "node_modules", ".git", ".html-kit", "_archive", @@ -44,6 +44,7 @@ export type DiscoverResult = { scanned: number; // total .html-kit dirs found on disk durationMs: number; scanRoots: string[]; + unconfigured?: true; // set when no scanRoots are configured at all }; type Config = { scanRoots: string[]; maxDepth: number }; @@ -110,7 +111,7 @@ function findHtmlKitDirs(root: string, maxDepth: number): string[] { } // Canonical slug = basename of repo dir. Matches existing short-slug convention -// already in repos.json (my-app, html-kit, example-insights, etc.). +// already in repos.json (e.g. my-app, html-kit). function slugFor(repoDir: string): string { return basename(repoDir); } @@ -123,6 +124,20 @@ export async function discoverRoots( const t0 = Date.now(); const cfg = loadConfig(); + + // If no scanRoots configured, emit hint and return empty result cleanly + if (cfg.scanRoots.length === 0) { + process.stderr.write("[discover] no scanRoots configured; set them in ~/.html-kit/_daemon/config.json\n"); + return { + added: [], + existing: 0, + scanned: 0, + durationMs: 0, + scanRoots: [], + unconfigured: true, + }; + } + const repos = loadRepos(); const existingDirs = new Set(Object.values(repos).map(p => resolve(p))); const existingCount = Object.keys(repos).length; diff --git a/scripts/html-kit-daemon.ts b/scripts/html-kit-daemon.ts index 13d6ead..e7df00c 100644 --- a/scripts/html-kit-daemon.ts +++ b/scripts/html-kit-daemon.ts @@ -172,7 +172,7 @@ function scheduleRebuild(triggerPath?: string) { } // Slug dirs to skip inside KIT_HOME when enumerating per-slug watchers. -const KIT_HOME_SKIP = new Set(["_daemon", "_index", "_old_tmp", "_archive"]); +const KIT_HOME_SKIP = new Set(["_daemon", "_index", "_old_tmp", "_archive", "_gotchas", "_patterns"]); function setupWatchers(repos: ReposMap) { const dirs = new Set(); From 6b3fbe93dcaa80a40012a7d81167766ad9cf35ed Mon Sep 17 00:00:00 2001 From: KN Date: Wed, 16 Sep 2026 21:04:47 +0300 Subject: [PATCH 05/12] feat(v0.5.0): package html-kit as a Claude Code plugin - .claude-plugin/plugin.json + self-hosted marketplace.json - skills call bundled scripts via ${CLAUDE_SKILL_DIR} with matching allowed-tools rules; daemon-check.ts and artifact-from-url.ts replace curl/jq snippets - user gotchas and patterns go to ~/.html-kit/_gotchas and _patterns so they survive plugin updates; repo edits only inside an html-kit checkout - build-cheatsheet.ts generates the SKILL.md cheatsheet and README counts from recipe frontmatter (--check for CI) - attribution: the 11 unknowns exemplars are Apache-2.0 (upstream relicensed 2026-05-18); add LICENSES/Apache-2.0.txt - README install matrix, namespaced plugin command names, spec doc Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/marketplace.json | 15 ++ .claude-plugin/plugin.json | 19 ++ .github/CONTRIBUTING.md | 34 ++-- ATTRIBUTION.md | 42 ++++- CHANGELOG.md | 46 +++++ LICENSES/Apache-2.0.txt | 202 +++++++++++++++++++++ README.md | 70 ++++---- docs/specs/2026-09-16-plugin-packaging.md | 154 ++++++++++++++++ install.sh | 18 +- package.json | 2 + scripts/artifact-from-url.ts | 84 +++++++++ scripts/build-cheatsheet.ts | 209 ++++++++++++++++++++++ scripts/daemon-check.ts | 24 +++ skills/html-kit-add-to-patterns/SKILL.md | 62 +++++-- skills/html-kit-drain/SKILL.md | 76 ++++---- skills/html-kit/SKILL.md | 195 ++++++++++++-------- 16 files changed, 1069 insertions(+), 183 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json create mode 100644 LICENSES/Apache-2.0.txt create mode 100644 docs/specs/2026-09-16-plugin-packaging.md create mode 100644 scripts/artifact-from-url.ts create mode 100644 scripts/build-cheatsheet.ts create mode 100644 scripts/daemon-check.ts diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..6483120 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -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." + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..e631fd8 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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" + ] +} diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ce3dda1..81da72a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -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 @@ -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: @@ -39,20 +39,28 @@ An archetype is just a directory under `archetypes/`. To add one: 1. Create `archetypes//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 `` - comment at the top and add it to `ATTRIBUTION.md`. -2. Create `archetypes//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//recipe.md` starting with frontmatter: + ```yaml + --- + name: + when: + --- + ``` + 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//` with a `SKILL.md` (YAML frontmatter + +Drop a directory under `skills//` with a `SKILL.md` (YAML frontmatter + body) and re-run `./install.sh`. Skills are auto-discovered; no edits to the installer are required. diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 51f6649..c1789e7 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -1,8 +1,14 @@ # Third-party attribution -## Vendored exemplars — `thariqs/html-effectiveness` +All HTML exemplars under `archetypes//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//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 @@ -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 + +``` + +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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 26ffe66..ec32146 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 + ``. +- `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//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/ bodies dropped, tags kept (so