continuous-improvement 3.0.0 → 3.8.0

package/lib/resolve-home-dir.mjs

@@ -0,0 +1,43 @@
+// resolve-home-dir.mts — Single source of truth for the telemetry home dir
+// resolution rule shared by hooks/three-section-close.mjs and bin/hook-stats.mjs.
+//
+// Previously this 20-line function lived in three byte-equivalent copies; this
+// module collapses them. Behavior is unchanged.
+import { homedir } from "node:os";
+/**
+ * Resolve the home directory used to locate `.claude/hook-telemetry/`.
+ *
+ * Contract (AND-semantic opt-out):
+ *   - If BOTH `HOME` and `USERPROFILE` are explicitly set to the empty string
+ *     (set, not merely undefined), return `""`. This is the operator/test
+ *     opt-out signal: telemetry is intentionally disabled.
+ *   - Otherwise return the first truthy value from, in order:
+ *     `process.env.HOME`, `process.env.USERPROFILE`, `os.homedir()`.
+ *   - If none yields a truthy path, return `""`.
+ *
+ * The AND-semantic is deliberate: an OR-semantic would silently disable
+ * telemetry whenever a shell happened to clear one variable while the other
+ * still pointed at a valid path.
+ *
+ * Never throws. `os.homedir()` is wrapped in try/catch because it can throw
+ * in pathological env conditions.
+ */
+export function resolveHomeDir() {
+    const home = process.env.HOME;
+    const userProfile = process.env.USERPROFILE;
+    if (home === "" && userProfile === "")
+        return "";
+    if (home)
+        return home;
+    if (userProfile)
+        return userProfile;
+    try {
+        const fromOs = homedir();
+        if (fromOs)
+            return fromOs;
+    }
+    catch {
+        // os.homedir() can throw in pathological env conditions
+    }
+    return "";
+}

package/lib/skill-tiers.mjs

@@ -0,0 +1,137 @@
+// Tier-aware rendering for the bundled-skills README.
+//
+// Source-of-truth: each skills/<name>.md declares its own tier in YAML
+// frontmatter via a tier: field. The generator parses each file at build
+// time and groups them into sections in the bundled README. This is the
+// single source consumed by both the generator and its unit test, so the
+// two cannot drift.
+//
+// Recognized tier values:
+//   "featured"  — the recommended pairing for the 7 Laws
+//   "1"         — Tier 1: ships in beginner mode
+//   "2"         — Tier 2: ships in expert mode
+//   "companion" — always-bundled drop-in companion skill
+//   anything else (or absent) — falls into the "Other" bucket so the file
+//                                is still listed, visibly miscategorized
+//                                so the maintainer notices and assigns one
+const TIER_ORDER = ["core", "featured", "1", "2", "companion", "unknown"];
+const TIER_HEADINGS = {
+    core: "## Core skill",
+    featured: "## Featured companion",
+    "1": "## Tier 1 — beginner-mode pairing",
+    "2": "## Tier 2 — expert-mode add-ons",
+    companion: "## Always-bundled companions",
+    unknown: "## Other skills",
+};
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+export function parseSkillFrontmatter(content) {
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match)
+        return {};
+    const out = {};
+    const lines = match[1].split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = /^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        let value = m[2];
+        if (value === ">" || value === ">-" || value === "|" || value === "|-") {
+            // Block scalar — collect indented continuation lines until we hit an
+            // unindented line (a sibling top-level key) or end-of-frontmatter.
+            // Folded scalars (>, >-): join with spaces. Literal (|, |-): join with
+            // newlines. We use simple folding (single space) for everything since
+            // that's what we need for descriptions in this repo.
+            const bodyLines = [];
+            let j = i + 1;
+            while (j < lines.length) {
+                const next = lines[j];
+                if (/^\s*$/.test(next)) {
+                    bodyLines.push("");
+                    j++;
+                    continue;
+                }
+                if (/^\S/.test(next))
+                    break; // unindented — sibling key
+                bodyLines.push(next.trim());
+                j++;
+            }
+            value = bodyLines.filter((s) => s.length > 0).join(" ");
+            i = j - 1;
+        }
+        else if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+            value = value.slice(1, -1);
+        }
+        else if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+    }
+    return {
+        name: out.name,
+        tier: out.tier,
+        description: out.description,
+    };
+}
+export function normalizeTier(rawTier) {
+    if (!rawTier)
+        return "unknown";
+    const value = rawTier.trim().toLowerCase();
+    if (value === "core")
+        return "core";
+    if (value === "featured")
+        return "featured";
+    if (value === "1" || value === "tier1" || value === "tier-1")
+        return "1";
+    if (value === "2" || value === "tier2" || value === "tier-2")
+        return "2";
+    if (value === "companion")
+        return "companion";
+    return "unknown";
+}
+export function groupSkillsByTier(skills) {
+    const groups = {
+        core: [],
+        featured: [],
+        "1": [],
+        "2": [],
+        companion: [],
+        unknown: [],
+    };
+    for (const skill of skills) {
+        groups[skill.tier].push(skill);
+    }
+    for (const tier of TIER_ORDER) {
+        groups[tier].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    return groups;
+}
+export function renderBundledSkillsReadme(skills) {
+    const groups = groupSkillsByTier(skills);
+    const lines = [
+        "# Bundled Skills (generated)",
+        "",
+        "> **Do not edit anything in this directory.** It is regenerated by `npm run build`",
+        "> from the source skill files in the repo root (SKILL.md and skills/*.md).",
+        "> Any local edits here will be lost on the next build.",
+        "",
+        "Each skill below declares its own tier via the `tier:` field in its source",
+        "frontmatter. The build groups them into sections; this file is rendered from",
+        "those declarations so the table of contents cannot drift from the actual",
+        "skill set on disk.",
+    ];
+    for (const tier of TIER_ORDER) {
+        const inTier = groups[tier];
+        if (inTier.length === 0)
+            continue;
+        lines.push("", TIER_HEADINGS[tier]);
+        for (const skill of inTier) {
+            const marker = tier === "featured" ? " ⭐" : "";
+            const desc = skill.description ? ` — ${skill.description}` : "";
+            lines.push(`- \`${skill.name}\`${marker}${desc}`);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}