hstack 0.7.1 → 0.17.0

package/dist/lib/descriptions.js

@@ -0,0 +1,160 @@
+/**
+ * Description-budget scanner — ADR-0011's Option F.
+ *
+ * A Skill or subagent `description` is a routing trigger, not documentation:
+ * it is injected into every session, unconditionally, for every installed
+ * Skill and subagent, whether or not anything invokes it. ADR-0011 cut the 52
+ * descriptions from 19,234 words to one-sentence triggers under a 40-word
+ * budget, and deliberately left the enforcement out of that PR — "a linter for
+ * a size that no file currently respects would flag 52 findings on day one,
+ * and the rule should be established by the rewrite before it is enforced by a
+ * tool". The rewrite shipped in v0.14.0. This is the tool.
+ *
+ * It scans the PACKAGE's `template/` tree, not the consumer's `hstack/`. The
+ * consumer's copies are framework files that `hstack update` overwrites and
+ * that `doctor` already diffs against the template — a budget finding there
+ * would be a second report of the same drift. The regression this guards
+ * against is one made in this repo, so this repo is where it is measured.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * ADR-0011: "Budget: ≤ 40 words / ~250 characters per description."
+ *
+ * Words are the budget. The character figure carries a tilde in the ADR — it
+ * is the size 40 words implies, not a second independent limit — so it is
+ * enforced at the next round number above it. Three descriptions in the
+ * current template sit at 253 characters inside a 29–37 word trigger; those
+ * are the shape the ADR asked for, not the regression it guards against.
+ */
+export const WORD_BUDGET = 40;
+export const CHAR_BUDGET = 300;
+/**
+ * Named carve-outs. Empty since v0.17.
+ *
+ * ADR-0011 § Named carve-outs grants three, and only one ever needed a larger
+ * budget: `hstack-coord`, the single description that routed with no human
+ * typing anything — ADR-0007's hooks injected `HSTACK-COORD: N unread …` and
+ * the model had to invoke `check` mode on sight. v0.17 removed coord, and with
+ * it the only description that could argue for the exemption. The other two
+ * carve-outs (confusable families, status preconditions stated as triggers)
+ * always bought a clause rather than a budget: every file in those families is
+ * under 40 words.
+ *
+ * An entry here is a decision with a reason, not a snooze. Adding one means
+ * arguing that the description does routing work no body can do.
+ */
+export const BUDGET_CARVE_OUTS = new Map();
+/**
+ * Pull the `description:` value out of a frontmatter block.
+ *
+ * Deliberately not the full YAML subset `validate-spec.mjs` parses: this reads
+ * one known scalar out of a framework file whose shape this repo controls. It
+ * handles the two forms that occur — a single-line scalar (quoted or not) and
+ * a folded/literal block scalar — and returns null for anything else rather
+ * than guessing.
+ */
+export function extractDescription(text) {
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== "---")
+        return null;
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (t === "---" || t === "...") {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return null;
+    for (let i = 1; i < end; i++) {
+        const m = /^description:(.*)$/.exec(lines[i]);
+        if (!m)
+            continue;
+        const rest = m[1].trim();
+        if (rest === ">" || rest === "|" || /^[|>][-+]?$/.test(rest)) {
+            const out = [];
+            for (let j = i + 1; j < end; j++) {
+                const line = lines[j];
+                if (line.trim() === "") {
+                    out.push("");
+                    continue;
+                }
+                if (!/^\s/.test(line))
+                    break;
+                out.push(line.trim());
+            }
+            return out.join(" ").trim();
+        }
+        const unquoted = rest.replace(/^(["'])([\s\S]*)\1$/, "$2");
+        return unquoted.trim();
+    }
+    return null;
+}
+export function wordCount(s) {
+    return s.trim().split(/\s+/).filter(Boolean).length;
+}
+/** Every Skill and subagent description in the package template, measured. */
+export function measureDescriptions(templateDir) {
+    const out = [];
+    const push = (name, relpath, kind, abs) => {
+        let text;
+        try {
+            text = readFileSync(abs, "utf8");
+        }
+        catch {
+            return;
+        }
+        const desc = extractDescription(text);
+        if (desc === null)
+            return;
+        out.push({
+            name,
+            relpath,
+            kind,
+            words: wordCount(desc),
+            chars: desc.length,
+            carveOut: BUDGET_CARVE_OUTS.get(name) ?? null,
+        });
+    };
+    const skillsDir = join(templateDir, ".claude", "skills");
+    for (const entry of safeReaddir(skillsDir)) {
+        const abs = join(skillsDir, entry, "SKILL.md");
+        try {
+            if (!statSync(abs).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        push(entry, `.claude/skills/${entry}/SKILL.md`, "skill", abs);
+    }
+    const agentsDir = join(templateDir, ".claude", "agents");
+    for (const entry of safeReaddir(agentsDir)) {
+        if (!entry.endsWith(".md"))
+            continue;
+        const name = entry.replace(/\.md$/, "");
+        push(name, `.claude/agents/${entry}`, "agent", join(agentsDir, entry));
+    }
+    out.sort((a, b) => b.words - a.words || a.name.localeCompare(b.name));
+    return out;
+}
+/**
+ * The descriptions over budget, carve-outs removed. Empty is the healthy
+ * state — and is what the current template produces.
+ */
+export function descriptionsOverBudget(templateDir) {
+    return measureDescriptions(templateDir)
+        .filter((d) => d.carveOut === null && (d.words > WORD_BUDGET || d.chars > CHAR_BUDGET))
+        .map(({ carveOut: _carveOut, ...rest }) => rest);
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir).sort();
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=descriptions.js.map

package/dist/lib/descriptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptions.js","sourceRoot":"","sources":["../../src/lib/descriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC;AAC9B,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAE/B;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAgC,IAAI,GAAG,EAAE,CAAC;AAYxE;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;YAC/B,GAAG,GAAG,CAAC,CAAC;YACR,MAAM;QACR,CAAC;IACH,CAAC;IACD,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,CAAC,GAAG,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAEzB,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7D,MAAM,GAAG,GAAa,EAAE,CAAC;YACzB,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBACjC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACtB,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;oBACvB,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACb,SAAS;gBACX,CAAC;gBACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,MAAM;gBAC7B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YACxB,CAAC;YACD,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9B,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,IAAI,CAAC,CAAC;QAC3D,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;AACtD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CACjC,WAAmB;IAEnB,MAAM,GAAG,GAA+D,EAAE,CAAC;IAE3E,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,IAAuB,EAAE,GAAW,EAAE,EAAE;QACnF,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO;QAC1B,GAAG,CAAC,IAAI,CAAC;YACP,IAAI;YACJ,OAAO;YACP,IAAI;YACJ,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC;YACtB,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,QAAQ,EAAE,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI;SAC9C,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACzD,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QAC/C,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE;gBAAE,SAAS;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,kBAAkB,KAAK,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACzD,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAS;QACrC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,EAAE,kBAAkB,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACtE,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,OAAO,mBAAmB,CAAC,WAAW,CAAC;SACpC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,WAAW,IAAI,CAAC,CAAC,KAAK,GAAG,WAAW,CAAC,CAAC;SACtF,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/lib/diff.js

@@ -39,7 +39,7 @@ export async function filesEqual(a, b) {
  * Only paths under FRAMEWORK_PATHS are considered.
  *
  * `frameworkPaths` is the list of framework subpaths (relative to template root
- * and to consumer hstack root). Both top-level files (e.g., "CLAUDE.md") and
+ * and to consumer hstack root). Both top-level files (e.g., "KERNEL.md") and
  * directories (e.g., "templates/") are supported.
  */
 export async function diffFramework(templateDir, consumerHstackDir, frameworkPaths) {

package/dist/lib/git.js

@@ -13,6 +13,22 @@ export async function findGitRoot(start) {
         dir = parent;
     }
 }
+/**
+ * Move a repo-relative path with `git mv`, falling back to a plain rename when
+ * git refuses (file untracked, or no git available). Returns true when git
+ * recorded the rename — which is what keeps `git log --follow` working across
+ * the ADR-0010 kernel rename and lands the move already staged.
+ */
+export async function gitMove(cwd, from, to) {
+    try {
+        await execa("git", ["mv", from, to], { cwd });
+        return true;
+    }
+    catch {
+        await fs.move(resolve(cwd, from), resolve(cwd, to));
+        return false;
+    }
+}
 /** True if working tree has no uncommitted changes (staged or unstaged). */
 export async function isWorkingTreeClean(cwd) {
     try {

package/dist/lib/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/lib/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,MAAM,UAAU,CAAC;AAE1B,uGAAuG;AACvG,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAa;IAC7C,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzB,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAW;IAClD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAC1E,OAAO,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/lib/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,MAAM,UAAU,CAAC;AAE1B,uGAAuG;AACvG,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAa;IAC7C,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACzB,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAChC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,GAAW,EACX,IAAY,EACZ,EAAU;IAEV,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;QACpD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAW;IAClD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAC1E,OAAO,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}