@jean.gnc/harness-kit 0.5.0

package/dist/skill/includes.js

@@ -0,0 +1,81 @@
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { parsePlaceholders } from "../placeholders/index.js";
+import { err, ok } from "../result.js";
+export async function expandIncludes(body, fromFile, skillDir) {
+    const errors = [];
+    const resolved = new Set();
+    const expanded = await expand(body, fromFile, skillDir, [resolve(fromFile)], errors, resolved);
+    if (errors.length > 0)
+        return err(errors);
+    return ok({ body: expanded, resolvedIncludes: resolved });
+}
+export function formatIncludeError(error) {
+    switch (error.tag) {
+        case "include-cycle":
+            return `include cycle: ${error.chain.join(" → ")}`;
+        case "include-missing":
+            return `include target not found: ${error.path} (from ${error.from})`;
+        case "include-escapes-skill":
+            return `include path "${error.path}" escapes the skill directory ${error.skillDir}`;
+        case "include-not-md":
+            return `include only supports .md files (got ${error.path})`;
+        case "include-absolute":
+            return `include path must be relative (got ${error.raw})`;
+        case "include-empty":
+            return `expected {{include:<relative-path>.md}} (got ${error.raw})`;
+    }
+}
+async function expand(body, fromFile, skillDir, chain, errors, resolved) {
+    const tokens = parsePlaceholders(body).filter((t) => t.prefix === "include");
+    if (tokens.length === 0)
+        return body;
+    let out = "";
+    let cursor = 0;
+    for (const token of tokens) {
+        out += body.slice(cursor, token.start);
+        cursor = token.end;
+        if (token.value === null) {
+            errors.push({ tag: "include-empty", raw: token.raw });
+            out += token.raw;
+            continue;
+        }
+        const rel = token.value.trim();
+        if (isAbsolute(rel)) {
+            errors.push({ tag: "include-absolute", raw: token.raw });
+            out += token.raw;
+            continue;
+        }
+        if (!rel.endsWith(".md")) {
+            errors.push({ tag: "include-not-md", path: rel });
+            out += token.raw;
+            continue;
+        }
+        const target = resolve(dirname(fromFile), rel);
+        const fromSkill = relative(skillDir, target);
+        if (fromSkill.startsWith("..") || isAbsolute(fromSkill)) {
+            errors.push({ tag: "include-escapes-skill", path: rel, skillDir });
+            out += token.raw;
+            continue;
+        }
+        if (chain.includes(target)) {
+            errors.push({ tag: "include-cycle", chain: [...chain, target] });
+            out += token.raw;
+            continue;
+        }
+        let raw;
+        try {
+            raw = await readFile(target, "utf8");
+        }
+        catch {
+            errors.push({ tag: "include-missing", path: rel, from: fromFile });
+            out += token.raw;
+            continue;
+        }
+        resolved.add(target);
+        out += await expand(raw, target, skillDir, [...chain, target], errors, resolved);
+    }
+    out += body.slice(cursor);
+    return out;
+}
+//# sourceMappingURL=includes.js.map

package/dist/skill/includes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"includes.js","sourceRoot":"","sources":["../../src/skill/includes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,cAAc,CAAC;AAepD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,QAAgB,EAChB,QAAgB;IAEhB,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/F,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAmB;IACpD,QAAQ,KAAK,CAAC,GAAG,EAAE,CAAC;QAClB,KAAK,eAAe;YAClB,OAAO,kBAAkB,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrD,KAAK,iBAAiB;YACpB,OAAO,6BAA6B,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC,IAAI,GAAG,CAAC;QACxE,KAAK,uBAAuB;YAC1B,OAAO,iBAAiB,KAAK,CAAC,IAAI,iCAAiC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACtF,KAAK,gBAAgB;YACnB,OAAO,wCAAwC,KAAK,CAAC,IAAI,GAAG,CAAC;QAC/D,KAAK,kBAAkB;YACrB,OAAO,sCAAsC,KAAK,CAAC,GAAG,GAAG,CAAC;QAC5D,KAAK,eAAe;YAClB,OAAO,gDAAgD,KAAK,CAAC,GAAG,GAAG,CAAC;IACxE,CAAC;AACH,CAAC;AAED,KAAK,UAAU,MAAM,CACnB,IAAY,EACZ,QAAgB,EAChB,QAAgB,EAChB,KAAwB,EACxB,MAAsB,EACtB,QAAqB;IAErB,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IAC7E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAErC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC;QAEnB,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;YACtD,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC;YACjB,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,kBAAkB,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;YACzD,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC;YACjB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;YAClD,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC;YACjB,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC;QAC/C,MAAM,SAAS,GAAG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACxD,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,uBAAuB,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC;YACnE,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC;YACjB,SAAS;QACX,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;YACjE,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC;YACjB,SAAS;QACX,CAAC;QACD,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,iBAAiB,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;YACnE,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC;YACjB,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrB,GAAG,IAAI,MAAM,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IACnF,CAAC;IACD,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/skill/index.d.ts

@@ -0,0 +1,8 @@
+export { CompanionSchema, SkillSchema, defineSkill, isReservedCompanionFilename, } from "./schema.js";
+export type { Companion, Skill } from "./schema.js";
+export { findSkillFile, formatLoadSkillError, loadSkill } from "./source.js";
+export type { FindSkillFileError, LoadSkillError, LoadedSkill, SkillFile, SkillSource, } from "./source.js";
+export { checkCompanionFiles } from "./invariants.js";
+export { expandIncludes, formatIncludeError } from "./includes.js";
+export type { ExpandedBody, IncludeError } from "./includes.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/skill/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skill/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,WAAW,EACX,WAAW,EACX,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,SAAS,EACT,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/skill/index.js

@@ -0,0 +1,5 @@
+export { CompanionSchema, SkillSchema, defineSkill, isReservedCompanionFilename, } from "./schema.js";
+export { findSkillFile, formatLoadSkillError, loadSkill } from "./source.js";
+export { checkCompanionFiles } from "./invariants.js";
+export { expandIncludes, formatIncludeError } from "./includes.js";
+//# sourceMappingURL=index.js.map

package/dist/skill/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/skill/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,WAAW,EACX,WAAW,EACX,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/skill/invariants.d.ts

@@ -0,0 +1,3 @@
+import type { Companion } from "./schema.js";
+export declare function checkCompanionFiles(companions: readonly Companion[] | undefined, siblings: readonly string[]): string[];
+//# sourceMappingURL=invariants.d.ts.map

package/dist/skill/invariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.d.ts","sourceRoot":"","sources":["../../src/skill/invariants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,EAC5C,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,MAAM,EAAE,CAeV"}

package/dist/skill/invariants.js

@@ -0,0 +1,17 @@
+export function checkCompanionFiles(companions, siblings) {
+    const declared = new Set((companions ?? []).map((c) => c.file));
+    const onDisk = new Set(siblings);
+    const errors = [];
+    for (const c of companions ?? []) {
+        if (!onDisk.has(c.file)) {
+            errors.push(`companion "${c.file}" declared but not present in skill folder`);
+        }
+    }
+    for (const file of siblings) {
+        if (!declared.has(file)) {
+            errors.push(`companion "${file}" exists in folder but is not declared in companions`);
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=invariants.js.map

package/dist/skill/invariants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariants.js","sourceRoot":"","sources":["../../src/skill/invariants.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,mBAAmB,CACjC,UAA4C,EAC5C,QAA2B;IAE3B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,UAAU,IAAI,EAAE,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,4CAA4C,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,cAAc,IAAI,sDAAsD,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/skill/schema.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+export declare function isReservedCompanionFilename(name: string): boolean;
+export declare const CompanionSchema: z.ZodObject<{
+    file: z.ZodEffects<z.ZodString, string, string>;
+    summary: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    summary: string;
+}, {
+    file: string;
+    summary: string;
+}>;
+export type Companion = z.infer<typeof CompanionSchema>;
+export declare const SkillSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodEffects<z.ZodString, string, string>;
+    companions: z.ZodEffects<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        file: z.ZodEffects<z.ZodString, string, string>;
+        summary: z.ZodEffects<z.ZodString, string, string>;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        summary: string;
+    }, {
+        file: string;
+        summary: string;
+    }>, "many">>, {
+        file: string;
+        summary: string;
+    }[] | undefined, {
+        file: string;
+        summary: string;
+    }[] | undefined>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    companions?: {
+        file: string;
+        summary: string;
+    }[] | undefined;
+}, {
+    name: string;
+    description: string;
+    companions?: {
+        file: string;
+        summary: string;
+    }[] | undefined;
+}>;
+export type Skill = z.infer<typeof SkillSchema>;
+export declare function defineSkill(skill: Skill): Skill;
+//# sourceMappingURL=schema.d.ts.map

package/dist/skill/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/skill/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,eAAO,MAAM,eAAe;;;;;;;;;EAY1B,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmBb,CAAC;AAEZ,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAE/C"}

package/dist/skill/schema.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+const RESERVED_COMPANION_FILENAMES = new Set(["body.md", "SKILL.md"]);
+export function isReservedCompanionFilename(name) {
+    return RESERVED_COMPANION_FILENAMES.has(name);
+}
+export const CompanionSchema = z.object({
+    file: z
+        .string()
+        .regex(/^[a-z0-9-]+\.md$/, "companion file must be a kebab-case .md filename")
+        .refine((f) => !isReservedCompanionFilename(f), (f) => ({ message: `"${f}" is reserved and cannot be used as a companion filename` })),
+    summary: z
+        .string()
+        .min(1)
+        .refine((s) => !s.includes("\n"), "companion summary cannot contain newlines"),
+});
+export const SkillSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .regex(/^[a-z0-9-]+$/, "name must be lowercase kebab-case"),
+    description: z
+        .string()
+        .min(1)
+        .max(1024)
+        .refine((s) => !s.includes("\n"), "description cannot contain newlines"),
+    companions: z
+        .array(CompanionSchema)
+        .optional()
+        .refine((arr) => !arr || new Set(arr.map((c) => c.file)).size === arr.length, "companion files must be unique"),
+})
+    .strict();
+export function defineSkill(skill) {
+    return SkillSchema.parse(skill);
+}
+//# sourceMappingURL=schema.js.map

package/dist/skill/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/skill/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,4BAA4B,GAAwB,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;AAE3F,MAAM,UAAU,2BAA2B,CAAC,IAAY;IACtD,OAAO,4BAA4B,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,KAAK,CAAC,kBAAkB,EAAE,kDAAkD,CAAC;SAC7E,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,EACtC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,0DAA0D,EAAE,CAAC,CACtF;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,2CAA2C,CAAC;CACjF,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,KAAK,CAAC,cAAc,EAAE,mCAAmC,CAAC;IAC7D,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,IAAI,CAAC;SACT,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,qCAAqC,CAAC;IAC1E,UAAU,EAAE,CAAC;SACV,KAAK,CAAC,eAAe,CAAC;SACtB,QAAQ,EAAE;SACV,MAAM,CACL,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,EACpE,gCAAgC,CACjC;CACJ,CAAC;KACD,MAAM,EAAE,CAAC;AAIZ,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,OAAO,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC"}

package/dist/skill/source.d.ts

@@ -0,0 +1,48 @@
+import { type FrontmatterError } from "../parsing/index.js";
+import { type Result } from "../result.js";
+import { type Skill } from "./schema.js";
+export type SkillSource = "ts" | "md";
+export interface SkillFile {
+    readonly path: string;
+    readonly source: SkillSource;
+}
+export interface LoadedSkill {
+    readonly skill: Skill;
+    readonly body: string;
+    readonly source: SkillSource;
+    readonly skillFilePath: string;
+    readonly bodyFilePath: string;
+    readonly skillDir: string;
+    readonly bodyOffset: number;
+}
+export interface FindSkillFileError {
+    readonly tag: "ambiguous-source";
+    readonly skillDir: string;
+}
+export type LoadSkillError = {
+    readonly tag: "ambiguous-source";
+    readonly skillDir: string;
+} | {
+    readonly tag: "no-source";
+    readonly skillDir: string;
+} | {
+    readonly tag: "schema-violation";
+    readonly path: string;
+    readonly issues: readonly string[];
+} | {
+    readonly tag: "missing-body";
+    readonly path: string;
+    readonly bodyPath: string;
+} | {
+    readonly tag: "forbidden-body";
+    readonly path: string;
+    readonly bodyPath: string;
+} | {
+    readonly tag: "invalid-frontmatter";
+    readonly path: string;
+    readonly cause: FrontmatterError;
+};
+export declare function findSkillFile(skillDir: string): Promise<Result<SkillFile | null, FindSkillFileError>>;
+export declare function loadSkill(skillDir: string): Promise<Result<LoadedSkill, LoadSkillError>>;
+export declare function formatLoadSkillError(error: LoadSkillError): readonly string[];
+//# sourceMappingURL=source.d.ts.map

package/dist/skill/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/skill/source.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC;AAEtC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC/F;IAAE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClF;IAAE,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpF;IACE,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;CAClC,CAAC;AAEN,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAUvD;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAO9F;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,MAAM,EAAE,CAiB7E"}

package/dist/skill/source.js

@@ -0,0 +1,114 @@
+import { stat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { formatZodIssues } from "../errors/index.js";
+import { formatFrontmatterError, parseFrontmatter, } from "../parsing/index.js";
+import { err, ok } from "../result.js";
+import { SkillSchema } from "./schema.js";
+export async function findSkillFile(skillDir) {
+    const tsPath = join(skillDir, "SKILL.ts");
+    const mdPath = join(skillDir, "SKILL.md");
+    const [tsExists, mdExists] = await Promise.all([pathExists(tsPath), pathExists(mdPath)]);
+    if (tsExists && mdExists) {
+        return err({ tag: "ambiguous-source", skillDir });
+    }
+    if (tsExists)
+        return ok({ path: tsPath, source: "ts" });
+    if (mdExists)
+        return ok({ path: mdPath, source: "md" });
+    return ok(null);
+}
+export async function loadSkill(skillDir) {
+    const file = await findSkillFile(skillDir);
+    if (!file.ok)
+        return err(file.error);
+    if (!file.value)
+        return err({ tag: "no-source", skillDir });
+    return file.value.source === "ts"
+        ? loadFromTs(file.value.path, skillDir)
+        : loadFromMd(file.value.path, skillDir);
+}
+export function formatLoadSkillError(error) {
+    switch (error.tag) {
+        case "ambiguous-source":
+            return [`both SKILL.ts and SKILL.md exist at ${error.skillDir} — pick one`];
+        case "no-source":
+            return [`no SKILL.ts or SKILL.md found at ${error.skillDir}`];
+        case "schema-violation":
+            return error.issues;
+        case "missing-body":
+            return [`missing sibling body.md at ${error.bodyPath}`];
+        case "forbidden-body":
+            return [
+                "body.md is forbidden when SKILL.md is the source — body lives inline below the frontmatter",
+            ];
+        case "invalid-frontmatter":
+            return [formatFrontmatterError(error.cause)];
+    }
+}
+async function loadFromTs(skillFilePath, skillDir) {
+    const mod = (await import(pathToFileURL(skillFilePath).href));
+    const parsed = SkillSchema.safeParse(mod.default);
+    if (!parsed.success) {
+        return err({
+            tag: "schema-violation",
+            path: skillFilePath,
+            issues: formatZodIssues(parsed.error),
+        });
+    }
+    const bodyPath = join(skillDir, "body.md");
+    let body;
+    try {
+        body = await readFile(bodyPath, "utf8");
+    }
+    catch {
+        return err({ tag: "missing-body", path: skillFilePath, bodyPath });
+    }
+    return ok({
+        skill: parsed.data,
+        body,
+        source: "ts",
+        skillFilePath,
+        bodyFilePath: bodyPath,
+        skillDir,
+        bodyOffset: 0,
+    });
+}
+async function loadFromMd(skillFilePath, skillDir) {
+    const bodyPath = join(skillDir, "body.md");
+    if (await pathExists(bodyPath)) {
+        return err({ tag: "forbidden-body", path: skillFilePath, bodyPath });
+    }
+    const raw = await readFile(skillFilePath, "utf8");
+    const fm = parseFrontmatter(raw);
+    if (!fm.ok) {
+        return err({ tag: "invalid-frontmatter", path: skillFilePath, cause: fm.error });
+    }
+    const parsed = SkillSchema.safeParse(fm.value.data);
+    if (!parsed.success) {
+        return err({
+            tag: "schema-violation",
+            path: skillFilePath,
+            issues: formatZodIssues(parsed.error),
+        });
+    }
+    return ok({
+        skill: parsed.data,
+        body: fm.value.body,
+        source: "md",
+        skillFilePath,
+        bodyFilePath: skillFilePath,
+        skillDir,
+        bodyOffset: fm.value.bodyOffset,
+    });
+}
+async function pathExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=source.js.map

package/dist/skill/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/skill/source.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@jean.gnc/harness-kit",
+  "version": "0.5.0",
+  "type": "module",
+  "description": "Typed framework for authoring Claude Code skills: schema, placeholder engine, and compile pipeline.",
+  "license": "MIT",
+  "author": "Jean Gonçalves <jean.gnc@gmail.com>",
+  "homepage": "https://github.com/jeangnc/harness-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeangnc/harness-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jeangnc/harness-kit/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "skills",
+    "plugin",
+    "markdown",
+    "typescript"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "harness-kit": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "imports": {
+    "#harness-kit": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli.ts",
+    "lint": "tsc --noEmit && prettier --check 'src/**/*.ts' && eslint 'src/**/*.ts'",
+    "lint:format": "prettier --check 'src/**/*.ts'",
+    "lint:code": "eslint 'src/**/*.ts'",
+    "format": "prettier --write 'src/**/*.ts'",
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "test:coverage": "c8 --reporter=text --reporter=lcov tsx --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit",
+    "typecheck:watch": "tsc --noEmit --watch",
+    "check": "pnpm lint && pnpm test",
+    "prepare": "husky",
+    "prepublishOnly": "pnpm lint && pnpm test && pnpm build"
+  },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "prettier --write",
+      "eslint --fix"
+    ]
+  },
+  "dependencies": {
+    "citty": "^0.2.2",
+    "js-yaml": "^4.1.1",
+    "markdownlint-cli2": "^0.18.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.20.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.6.0",
+    "c8": "^11.0.0",
+    "eslint": "^10.3.0",
+    "eslint-config-prettier": "^9.1.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.4.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.20.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@10.27.0"
+}