claude-ketchup 0.7.0

package/dist/src/state-manager.test.js

@@ -0,0 +1,85 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const vitest_1 = require("vitest");
+const state_manager_js_1 = require("./state-manager.js");
+(0, vitest_1.describe)('state-manager', () => {
+    (0, vitest_1.describe)('readState', () => {
+        let tempDir;
+        (0, vitest_1.beforeEach)(() => {
+            tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ketchup-state-'));
+        });
+        (0, vitest_1.afterEach)(() => {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        });
+        (0, vitest_1.it)('reads state from state.json', () => {
+            const stateData = { lastRun: '2024-01-01', counter: 5 };
+            fs.writeFileSync(path.join(tempDir, 'state.json'), JSON.stringify(stateData));
+            const result = (0, state_manager_js_1.readState)(tempDir);
+            (0, vitest_1.expect)(result).toEqual(stateData);
+        });
+        (0, vitest_1.it)('returns empty object when state.json does not exist', () => {
+            const result = (0, state_manager_js_1.readState)(tempDir);
+            (0, vitest_1.expect)(result).toEqual({});
+        });
+    });
+    (0, vitest_1.describe)('writeState', () => {
+        let tempDir;
+        (0, vitest_1.beforeEach)(() => {
+            tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ketchup-state-'));
+        });
+        (0, vitest_1.afterEach)(() => {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        });
+        (0, vitest_1.it)('writes state to state.json', () => {
+            const stateData = { lastRun: '2024-01-01', counter: 5 };
+            (0, state_manager_js_1.writeState)(tempDir, stateData);
+            const result = JSON.parse(fs.readFileSync(path.join(tempDir, 'state.json'), 'utf-8'));
+            (0, vitest_1.expect)(result).toEqual(stateData);
+        });
+        (0, vitest_1.it)('creates backup before overwriting existing state', () => {
+            const initialState = { counter: 1 };
+            const newState = { counter: 2 };
+            fs.writeFileSync(path.join(tempDir, 'state.json'), JSON.stringify(initialState));
+            (0, state_manager_js_1.writeState)(tempDir, newState);
+            const backup = JSON.parse(fs.readFileSync(path.join(tempDir, 'state.backup.json'), 'utf-8'));
+            (0, vitest_1.expect)(backup).toEqual(initialState);
+        });
+    });
+});
+//# sourceMappingURL=state-manager.test.js.map

package/dist/src/state-manager.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager.test.js","sourceRoot":"","sources":["../../src/state-manager.test.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,4CAA8B;AAC9B,4CAA8B;AAC9B,gDAAkC;AAElC,mCAAqE;AAErE,yDAA2D;AAE3D,IAAA,iBAAQ,EAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,IAAA,iBAAQ,EAAC,WAAW,EAAE,GAAG,EAAE;QACzB,IAAI,OAAe,CAAC;QAEpB,IAAA,mBAAU,EAAC,GAAG,EAAE;YACd,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;QAEH,IAAA,kBAAS,EAAC,GAAG,EAAE;YACb,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QAEH,IAAA,WAAE,EAAC,6BAA6B,EAAE,GAAG,EAAE;YACrC,MAAM,SAAS,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YACxD,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;YAE9E,MAAM,MAAM,GAAG,IAAA,4BAAS,EAAC,OAAO,CAAC,CAAC;YAElC,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;QAEH,IAAA,WAAE,EAAC,qDAAqD,EAAE,GAAG,EAAE;YAC7D,MAAM,MAAM,GAAG,IAAA,4BAAS,EAAC,OAAO,CAAC,CAAC;YAElC,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,IAAA,iBAAQ,EAAC,YAAY,EAAE,GAAG,EAAE;QAC1B,IAAI,OAAe,CAAC;QAEpB,IAAA,mBAAU,EAAC,GAAG,EAAE;YACd,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;QAEH,IAAA,kBAAS,EAAC,GAAG,EAAE;YACb,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QAEH,IAAA,WAAE,EAAC,4BAA4B,EAAE,GAAG,EAAE;YACpC,MAAM,SAAS,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YAExD,IAAA,6BAAU,EAAC,OAAO,EAAE,SAAS,CAAC,CAAC;YAE/B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;YACtF,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;QAEH,IAAA,WAAE,EAAC,kDAAkD,EAAE,GAAG,EAAE;YAC1D,MAAM,YAAY,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;YAChC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;YAEjF,IAAA,6BAAU,EAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAE9B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;YAC7F,IAAA,eAAM,EAAC,MAAM,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/src/subagent-classifier.d.ts

@@ -0,0 +1,4 @@
+export type SubagentType = 'explore' | 'work' | 'unknown';
+export declare function classifySubagent(taskDescription: string): SubagentType;
+export declare function extractTaskDescription(transcript: string): string | undefined;
+//# sourceMappingURL=subagent-classifier.d.ts.map

package/dist/src/subagent-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-classifier.d.ts","sourceRoot":"","sources":["../../src/subagent-classifier.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AA8B1D,wBAAgB,gBAAgB,CAAC,eAAe,EAAE,MAAM,GAAG,YAAY,CAgBtE;AAID,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO7E"}

package/dist/src/subagent-classifier.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySubagent = classifySubagent;
+exports.extractTaskDescription = extractTaskDescription;
+const EXPLORE_PATTERNS = [
+    /\bsearch\b/i,
+    /\bfind\b/i,
+    /\bunderstand\b/i,
+    /\binvestigate\b/i,
+    /\banalyze\b/i,
+    /\blook\s+for\b/i,
+    /\bresearch\b/i,
+    /\bexplore\b/i,
+    /\bdiscover\b/i,
+    /\blocate\b/i,
+];
+const WORK_PATTERNS = [
+    /\bimplement\b/i,
+    /\bcreate\b/i,
+    /\bwrite\b/i,
+    /\bfix\b/i,
+    /\brefactor\b/i,
+    /\bupdate\b/i,
+    /\badd\b/i,
+    /\bbuild\b/i,
+    /\bmodify\b/i,
+    /\bchange\b/i,
+    /\bremove\b/i,
+    /\bdelete\b/i,
+];
+function classifySubagent(taskDescription) {
+    if (!taskDescription) {
+        return 'unknown';
+    }
+    const isExplore = EXPLORE_PATTERNS.some((p) => p.test(taskDescription));
+    const isWork = WORK_PATTERNS.some((p) => p.test(taskDescription));
+    if (isExplore && !isWork) {
+        return 'explore';
+    }
+    if (isWork && !isExplore) {
+        return 'work';
+    }
+    return 'unknown';
+}
+const TASK_DESCRIPTION_PATTERN = /<invoke name="Task">[\s\S]*?<parameter name="description">(.+?)<\/parameter>/;
+function extractTaskDescription(transcript) {
+    if (!transcript) {
+        return undefined;
+    }
+    const match = transcript.match(TASK_DESCRIPTION_PATTERN);
+    return match?.[1];
+}
+//# sourceMappingURL=subagent-classifier.js.map

package/dist/src/subagent-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-classifier.js","sourceRoot":"","sources":["../../src/subagent-classifier.ts"],"names":[],"mappings":";;AA8BA,4CAgBC;AAID,wDAOC;AAvDD,MAAM,gBAAgB,GAAG;IACvB,aAAa;IACb,WAAW;IACX,iBAAiB;IACjB,kBAAkB;IAClB,cAAc;IACd,iBAAiB;IACjB,eAAe;IACf,cAAc;IACd,eAAe;IACf,aAAa;CACd,CAAC;AAEF,MAAM,aAAa,GAAG;IACpB,gBAAgB;IAChB,aAAa;IACb,YAAY;IACZ,UAAU;IACV,eAAe;IACf,aAAa;IACb,UAAU;IACV,YAAY;IACZ,aAAa;IACb,aAAa;IACb,aAAa;IACb,aAAa;CACd,CAAC;AAEF,SAAgB,gBAAgB,CAAC,eAAuB;IACtD,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;IACxE,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;IAElE,IAAI,SAAS,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,wBAAwB,GAAG,8EAA8E,CAAC;AAEhH,SAAgB,sBAAsB,CAAC,UAAkB;IACvD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IACzD,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC"}

package/dist/src/subagent-classifier.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=subagent-classifier.test.d.ts.map

package/dist/src/subagent-classifier.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-classifier.test.d.ts","sourceRoot":"","sources":["../../src/subagent-classifier.test.ts"],"names":[],"mappings":""}

package/dist/src/subagent-classifier.test.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const subagent_classifier_js_1 = require("./subagent-classifier.js");
+(0, vitest_1.describe)('subagent-classifier', () => {
+    (0, vitest_1.describe)('classifySubagent', () => {
+        (0, vitest_1.it)('classifies explore patterns', () => {
+            const exploreDescriptions = [
+                'Search for files matching pattern',
+                'Find the implementation of this function',
+                'Understand how the auth system works',
+                'Investigate the error',
+                'Analyze the codebase structure',
+                'Look for usages of this API',
+                'Research existing patterns',
+            ];
+            for (const desc of exploreDescriptions) {
+                (0, vitest_1.expect)((0, subagent_classifier_js_1.classifySubagent)(desc)).toBe('explore');
+            }
+        });
+        (0, vitest_1.it)('classifies work patterns', () => {
+            const workDescriptions = [
+                'Implement the new feature',
+                'Create a user registration form',
+                'Write tests for the login component',
+                'Fix the bug in the parser',
+                'Refactor the database layer',
+                'Update the configuration',
+                'Add error handling',
+                'Build the API endpoint',
+            ];
+            for (const desc of workDescriptions) {
+                (0, vitest_1.expect)((0, subagent_classifier_js_1.classifySubagent)(desc)).toBe('work');
+            }
+        });
+        (0, vitest_1.it)('returns unknown for ambiguous descriptions', () => {
+            const ambiguousDescriptions = ['Process the request', 'Handle the response', 'Do something with the data'];
+            for (const desc of ambiguousDescriptions) {
+                (0, vitest_1.expect)((0, subagent_classifier_js_1.classifySubagent)(desc)).toBe('unknown');
+            }
+        });
+        (0, vitest_1.it)('is case insensitive', () => {
+            (0, vitest_1.expect)((0, subagent_classifier_js_1.classifySubagent)('SEARCH for files')).toBe('explore');
+            (0, vitest_1.expect)((0, subagent_classifier_js_1.classifySubagent)('IMPLEMENT feature')).toBe('work');
+        });
+        (0, vitest_1.it)('returns unknown for empty description', () => {
+            (0, vitest_1.expect)((0, subagent_classifier_js_1.classifySubagent)('')).toBe('unknown');
+        });
+    });
+    (0, vitest_1.describe)('extractTaskDescription', () => {
+        (0, vitest_1.it)('extracts description from Task tool invocation', () => {
+            const transcript = [
+                '<invoke name="Task">',
+                '<parameter name="description">Search for auth implementation</parameter>',
+                '<parameter name="prompt">Find all files</parameter>',
+                '</invoke>',
+            ].join('\n');
+            (0, vitest_1.expect)((0, subagent_classifier_js_1.extractTaskDescription)(transcript)).toBe('Search for auth implementation');
+        });
+        (0, vitest_1.it)('returns undefined when no Task invocation found', () => {
+            const transcript = [
+                '<invoke name="Read">',
+                '<parameter name="file_path">/some/file.ts</parameter>',
+                '</invoke>',
+            ].join('\n');
+            (0, vitest_1.expect)((0, subagent_classifier_js_1.extractTaskDescription)(transcript)).toBeUndefined();
+        });
+        (0, vitest_1.it)('returns undefined for empty transcript', () => {
+            (0, vitest_1.expect)((0, subagent_classifier_js_1.extractTaskDescription)('')).toBeUndefined();
+        });
+        (0, vitest_1.it)('extracts first Task description when multiple present', () => {
+            const transcript = [
+                '<invoke name="Task">',
+                '<parameter name="description">First task</parameter>',
+                '</invoke>',
+                '<invoke name="Task">',
+                '<parameter name="description">Second task</parameter>',
+                '</invoke>',
+            ].join('\n');
+            (0, vitest_1.expect)((0, subagent_classifier_js_1.extractTaskDescription)(transcript)).toBe('First task');
+        });
+    });
+});
+//# sourceMappingURL=subagent-classifier.test.js.map

package/dist/src/subagent-classifier.test.js.map

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

package/dist/src/validator-loader.d.ts

@@ -0,0 +1,9 @@
+export interface Validator {
+    name: string;
+    description: string;
+    enabled: boolean;
+    content: string;
+    path: string;
+}
+export declare function loadValidators(dirs: string[]): Validator[];
+//# sourceMappingURL=validator-loader.d.ts.map

package/dist/src/validator-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator-loader.d.ts","sourceRoot":"","sources":["../../src/validator-loader.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAiC1D"}

package/dist/src/validator-loader.js

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadValidators = loadValidators;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+function loadValidators(dirs) {
+    const validators = [];
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir)) {
+            continue;
+        }
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+            if (!file.endsWith('.md')) {
+                continue;
+            }
+            const filePath = path.join(dir, file);
+            const fileContent = fs.readFileSync(filePath, 'utf8');
+            const { data, content } = (0, gray_matter_1.default)(fileContent);
+            if (data.enabled === false) {
+                continue;
+            }
+            validators.push({
+                name: data.name,
+                description: data.description,
+                enabled: data.enabled,
+                content: content.trim(),
+                path: filePath,
+            });
+        }
+    }
+    return validators;
+}
+//# sourceMappingURL=validator-loader.js.map

package/dist/src/validator-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator-loader.js","sourceRoot":"","sources":["../../src/validator-loader.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaA,wCAiCC;AA9CD,4CAA8B;AAC9B,gDAAkC;AAElC,8DAAiC;AAUjC,SAAgB,cAAc,CAAC,IAAc;IAC3C,MAAM,UAAU,GAAgB,EAAE,CAAC;IAEnC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1B,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACtC,MAAM,WAAW,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YACtD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAA,qBAAM,EAAC,WAAW,CAAC,CAAC;YAE9C,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;gBAC3B,SAAS;YACX,CAAC;YAED,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;gBACvB,IAAI,EAAE,QAAQ;aACf,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/src/validator-loader.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validator-loader.test.d.ts.map

package/dist/src/validator-loader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator-loader.test.d.ts","sourceRoot":"","sources":["../../src/validator-loader.test.ts"],"names":[],"mappings":""}

package/dist/src/validator-loader.test.js

@@ -0,0 +1,140 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const vitest_1 = require("vitest");
+const validator_loader_js_1 = require("./validator-loader.js");
+(0, vitest_1.describe)('loadValidators', () => {
+    let tempDir;
+    (0, vitest_1.beforeEach)(() => {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ketchup-validators-'));
+    });
+    (0, vitest_1.afterEach)(() => {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+    (0, vitest_1.it)('returns empty array when directory does not exist', () => {
+        const nonExistentDir = path.join(tempDir, 'validators');
+        const result = (0, validator_loader_js_1.loadValidators)([nonExistentDir]);
+        (0, vitest_1.expect)(result).toEqual([]);
+    });
+    (0, vitest_1.it)('parses single .md file with frontmatter', () => {
+        const validatorsDir = path.join(tempDir, 'validators');
+        fs.mkdirSync(validatorsDir);
+        const validatorContent = `---
+name: test-validator
+description: A test validator
+enabled: true
+---
+
+Check that tests pass.
+
+Respond with JSON: {"decision":"ACK"} or {"decision":"NACK","reason":"..."}`;
+        fs.writeFileSync(path.join(validatorsDir, 'test.md'), validatorContent);
+        const result = (0, validator_loader_js_1.loadValidators)([validatorsDir]);
+        (0, vitest_1.expect)(result).toEqual([
+            {
+                name: 'test-validator',
+                description: 'A test validator',
+                enabled: true,
+                content: 'Check that tests pass.\n\nRespond with JSON: {"decision":"ACK"} or {"decision":"NACK","reason":"..."}',
+                path: path.join(validatorsDir, 'test.md'),
+            },
+        ]);
+    });
+    (0, vitest_1.it)('filters disabled validators', () => {
+        const validatorsDir = path.join(tempDir, 'validators');
+        fs.mkdirSync(validatorsDir);
+        fs.writeFileSync(path.join(validatorsDir, 'enabled.md'), `---
+name: enabled-validator
+description: Enabled
+enabled: true
+---
+Content`);
+        fs.writeFileSync(path.join(validatorsDir, 'disabled.md'), `---
+name: disabled-validator
+description: Disabled
+enabled: false
+---
+Content`);
+        const result = (0, validator_loader_js_1.loadValidators)([validatorsDir]);
+        (0, vitest_1.expect)(result).toEqual([
+            {
+                name: 'enabled-validator',
+                description: 'Enabled',
+                enabled: true,
+                content: 'Content',
+                path: path.join(validatorsDir, 'enabled.md'),
+            },
+        ]);
+    });
+    (0, vitest_1.it)('loads from multiple directories', () => {
+        const dir1 = path.join(tempDir, 'validators1');
+        const dir2 = path.join(tempDir, 'validators2');
+        fs.mkdirSync(dir1);
+        fs.mkdirSync(dir2);
+        fs.writeFileSync(path.join(dir1, 'first.md'), `---
+name: first
+description: First validator
+enabled: true
+---
+First content`);
+        fs.writeFileSync(path.join(dir2, 'second.md'), `---
+name: second
+description: Second validator
+enabled: true
+---
+Second content`);
+        const result = (0, validator_loader_js_1.loadValidators)([dir1, dir2]);
+        (0, vitest_1.expect)(result).toEqual([
+            {
+                name: 'first',
+                description: 'First validator',
+                enabled: true,
+                content: 'First content',
+                path: path.join(dir1, 'first.md'),
+            },
+            {
+                name: 'second',
+                description: 'Second validator',
+                enabled: true,
+                content: 'Second content',
+                path: path.join(dir2, 'second.md'),
+            },
+        ]);
+    });
+});
+//# sourceMappingURL=validator-loader.test.js.map

package/dist/src/validator-loader.test.js.map

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

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "claude-ketchup",
+  "version": "0.7.0",
+  "authors": [
+    {
+      "name": "Sam Hatoum"
+    }
+  ],
+  "description": "Husky-style hooks and skills management for Claude Code",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BeOnAuto/claude-ketchup.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "bin": {
+    "claude-ketchup": "dist/bin/cli.js"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,json,md}": [
+      "biome check --write --no-errors-on-unmatched"
+    ]
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "hooks",
+    "skills",
+    "automation"
+  ],
+  "author": "Sam Hatoum",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "cosmiconfig": "^9.0.0",
+    "gray-matter": "^4.0.3",
+    "micromatch": "^4.0.8",
+    "yaml": "^2.3.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "@commitlint/cli": "^20.3.1",
+    "@commitlint/config-conventional": "^20.3.1",
+    "@types/micromatch": "^4.0.10",
+    "@types/node": "^20.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "tsx": "^4.0.0",
+    "turbo": "^2.7.5",
+    "typescript": "^5.0.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^1.0.0"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "templates/",
+    "scripts/",
+    "commands/",
+    "validators/",
+    "reminders/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "check": "turbo run build type-check test && pnpm lint",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm publish",
+    "postinstall": "node dist/bin/postinstall.js",
+    "preuninstall": "node dist/bin/preuninstall.js",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  }
+}

package/reminders/ketchup.md

@@ -0,0 +1,24 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Ketchup Package Active
+
+This project uses claude-ketchup for hook management.
+
+## Available Commands
+
+- `/ketchup` - Show status and manage symlinks
+- `/ketchup doctor` - Run diagnostics
+- `/ketchup repair` - Fix broken symlinks
+- `/ketchup reminders` - List active reminders
+
+## Configuration Files
+
+- `.claude/settings.json` - Hook configuration (auto-generated)
+- `.claude/settings.project.json` - Project-specific overrides
+- `.claude/settings.local.json` - Local overrides (gitignored)
+- `.claude/deny-list.project.txt` - Project deny patterns
+- `.claude/deny-list.local.txt` - Local deny patterns (gitignored)

package/reminders/reminder-documentation.md

@@ -0,0 +1,30 @@
+---
+when:
+  hook: SessionStart
+priority: 100
+---
+
+# Documentation Reminder
+
+Documentation is code. Outdated docs are bugs.
+
+## When to Update Docs
+
+Update documentation when:
+- Adding features
+- Changing APIs
+- Completing milestones
+
+## When NOT to Create New Docs
+
+Do not create new documentation files unless the feature explicitly requires them.
+
+Avoid:
+- Creating README files proactively
+- Adding markdown files "for completeness"
+- Documenting internal implementation details
+
+Prefer:
+- Self-documenting code
+- Updating existing docs
+- Inline JSDoc for public APIs only