@khanhcan148/mk 0.1.15 → 0.1.17

package/README.md

@@ -81,15 +81,16 @@ cp -r .claude ~/.claude/
 /mk-audit          # Code archaeology chain: orientation, testing, heatmap, breaking-change analysis, technical debt, domain extraction
 /mk-selftest       # Self-validation checks on kit agents, skills, docs, workflows
 /mk-log-analysis   # Datadog + Azure App Insights log analysis with severity triage and Mermaid visual reports
+/mk-wiki           # Wiki management: staleness detection, batch refresh, bootstrap, stats, structural validation
 ```
 
 ## Structure
 
 ```
 ├── .claude/
-│   ├── agents/      # 31 agents (5 primary + 26 utility: implementers, quality, docs, specialized, concerns)
-│   ├── skills/      # 65 skill packages (SKILL.md + scripts/references/assets)
-│   │   ├── mk-*/    # 19 workflow commands (/mk-audit, /mk-brainstorm, /mk-log-analysis, /mk-overview, /mk-selftest, etc.)
+│   ├── agents/      # 32 agents (5 primary + 27 utility: implementers, quality, docs, specialized, concerns)
+│   ├── skills/      # 67 skill packages (SKILL.md + scripts/references/assets)
+│   │   ├── mk-*/    # 20 workflow commands (/mk-audit, /mk-brainstorm, /mk-log-analysis, /mk-overview, /mk-wiki, etc.)
 │   │   └── ...      # Domain skills (frontend, backend, testing, browser automation, etc.)
 │   └── workflows/   # Development protocols
 ├── bin/             # CLI entry point (mk command)
@@ -139,6 +140,7 @@ User → /mk-* command (skill) → spawns utility agents → agents use knowledg
 | `/mk-workflow` | Trace REST endpoint call chains with upstream caller detection, variant branching, side effects/feature flags, Mermaid diagrams |
 | `/mk-log-analysis` | Analyze production logs from Datadog or Azure Application Insights via MCP; progressive severity triage, pattern detection, mandatory stack trace investigation, mk-debug integration |
 | `/mk-selftest` | Run self-validation checks on kit agents, skills, docs, and workflows |
+| `/mk-wiki` | Manage wiki health: staleness detection, batch refresh, bootstrap, stats, structural validation |
 
 ## Primary Agents
 
@@ -166,12 +168,13 @@ Spawned by primary agents for domain-specific work:
 | **debugger** | Issue investigation and diagnosis |
 | **refactorer** | Refactoring with TFD-first safety workflow |
 
-**Docs & Project Management (3)**
+**Docs & Project Management (4)**
 | Agent | Purpose |
 |-------|---------|
 | **project-manager** | Progress tracking, roadmap updates |
 | **docs-manager** | Documentation maintenance |
 | **journal-writer** | Technical difficulty documentation |
+| **wiki-maintainer** | Background wiki writes to docs/llm-wiki/ (spawned by mk-* skills) |
 
 **Research & Design (3)**
 | Agent | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {

package/src/commands/update.js

@@ -133,6 +133,10 @@ export async function runUpdate(params = {}) {
   const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
 
   if (upToDate) {
+    // Always merge settings.json hooks even when kit files are unchanged.
+    // A user who installed before hooks were added (or whose settings.json was
+    // edited/reset) would otherwise never receive hook updates via `mk update`.
+    mergeSettingsJson(sourceDir, targetDir);
     // Files are unchanged but we may still need to record the release version.
     // Without this, manifest.version stays at the old value and the next `mk update`
     // will always report "Update available" even though nothing changed on disk.
@@ -290,7 +294,8 @@ export async function updateAction(options = {}, deps = {}) {
     compareVersions: cmpVersions = compareVersions,
     promptUser = defaultPromptUser,
     // Injectable for tests — allows overriding resolved paths without touching CWD
-    manifestPath: injectedManifestPath
+    manifestPath: injectedManifestPath,
+    targetDir: injectedTargetDir
   } = deps;
 
   // Read local package version (used as fallback when manifest has no version)
@@ -298,7 +303,7 @@ export async function updateAction(options = {}, deps = {}) {
     readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8')
   );
 
-  const targetDir = resolveTargetDir(options);
+  const targetDir = injectedTargetDir ?? resolveTargetDir(options);
   const manifestPath = injectedManifestPath ?? resolveManifestPath(options);
 
   let tempDir = null;
@@ -345,6 +350,11 @@ export async function updateAction(options = {}, deps = {}) {
 
       if (!needsUpdate) {
         process.stdout.write(chalk.green(`Already up to date (v${local}).\n`));
+        // Still merge settings.json hooks from the bundled local source.
+        // The installed settings.json may be missing hooks if it was created
+        // before hooks were added to the kit or if it was manually edited.
+        // resolveSourceDir() points to the CLI package's own .claude/ — no download needed.
+        mergeSettingsJson(resolveSourceDir(), targetDir);
         return;
       }
 

package/src/lib/constants.js

@@ -8,6 +8,14 @@ export const KIT_SUBDIRS = ['agents', 'skills', 'workflows', 'hooks'];
  */
 export const MANIFEST_FILENAME = '.mk-manifest.json';
 
+/**
+ * Skills that are internal to the kit and must NOT be distributed to end users.
+ * Each entry is matched as a full directory segment: `/skills/<name>/`.
+ * The trailing `/` in the match pattern prevents false positives on substring names
+ * (e.g. `mk-selftest-extended` is NOT matched by `mk-selftest`).
+ */
+export const KIT_INTERNAL_SKILLS = ['mk-selftest'];
+
 /**
  * Files/patterns to exclude during copy
  */

package/src/lib/copy.js

@@ -1,7 +1,7 @@
 import { join, relative } from 'node:path';
 import { statSync, lstatSync, existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
 import fsExtra from 'fs-extra';
-import { KIT_SUBDIRS, COPY_FILTER_PATTERNS, WINDOWS_PATH_WARN_LENGTH } from './constants.js';
+import { KIT_SUBDIRS, COPY_FILTER_PATTERNS, KIT_INTERNAL_SKILLS, WINDOWS_PATH_WARN_LENGTH } from './constants.js';
 
 /**
  * Check if a path should be filtered out during copy.
@@ -13,6 +13,10 @@ function shouldFilter(filePath) {
   for (const pattern of COPY_FILTER_PATTERNS) {
     if (normalized.includes(pattern)) return true;
   }
+  // Exclude internal skills — see KIT_INTERNAL_SKILLS JSDoc in constants.js.
+  for (const skillName of KIT_INTERNAL_SKILLS) {
+    if (normalized.includes(`/skills/${skillName}/`)) return true;
+  }
   return false;
 }
 
@@ -85,6 +89,9 @@ export function collectDiskFiles(targetDir) {
  * @param {string} targetDir - Absolute path to target .claude/
  * @param {{ dryRun: boolean }} options
  * @returns {Array<{ relativePath: string, absolutePath: string, sourceAbsPath: string, size: number }>}
+ * @remarks Naming convention: `absolutePath` is the destination (under targetDir),
+ *       `sourceAbsPath` is the source (under sourceDir). The asymmetry is intentional —
+ *       renaming would break consumers (update.js). See DEBT-016.
  */
 export function copyKitFiles(sourceDir, targetDir, options = {}) {
   const { dryRun = false } = options;
@@ -172,6 +179,36 @@ function backupFile(filePath) {
   return backupPath;
 }
 
+/**
+ * Returns true if siblingHooks already has an entry for the given event+matcher.
+ * @param {object|null} siblingHooks - Parsed hooks from settings.local.json, or null
+ * @param {string} event - Hook event name (e.g. 'PostToolUse')
+ * @param {string} matcher - Hook matcher (e.g. '*', 'Task')
+ */
+function isInSibling(siblingHooks, event, matcher) {
+  return !!siblingHooks?.[event]?.some(s => (s.matcher || '*') === matcher);
+}
+
+/**
+ * Filter kitEntries removing any whose event+matcher already exists in siblingHooks.
+ * Emits a stderr info message per skipped entry.
+ * @param {object[]} kitEntries - Hook entries from kit source
+ * @param {object|null} siblingHooks - Parsed hooks from settings.local.json, or null
+ * @param {string} event - Hook event name
+ * @returns {object[]} Entries not present in sibling
+ */
+function dedupeAgainstSibling(kitEntries, siblingHooks, event) {
+  if (!siblingHooks?.[event]) return kitEntries;
+  return kitEntries.filter(ke => {
+    const m = ke.matcher || '*';
+    if (isInSibling(siblingHooks, event, m)) {
+      process.stderr.write(`mk: hook ${event}[${m}] skipped (exists in settings.local.json)\n`);
+      return false;
+    }
+    return true;
+  });
+}
+
 /**
  * Merge kit's settings.json into user's existing settings.json.
  * Strategy: merge "hooks" key from kit source; preserve all other user keys.
@@ -201,14 +238,33 @@ export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
     return { action: 'skipped' };
   }
 
+  // Read settings.local.json once for sibling dedup guard.
+  // Applies to both the 'created' and 'merged' paths — Claude Code loads hooks from
+  // all settings files simultaneously; if a user already has a hook in settings.local.json,
+  // writing the same event+matcher to settings.json would cause both to fire.
+  let siblingHooks = null;
+  try {
+    const siblingPath = join(targetDir, 'settings.local.json');
+    siblingHooks = JSON.parse(readFileSync(siblingPath, 'utf-8')).hooks || null;
+  } catch {
+    // Missing or malformed sibling — proceed as if no sibling exists.
+  }
+
   // No existing user settings — create with hooks only (not permissions or other keys).
   // Copying the full kit settings.json would duplicate permissions.deny entries when both
   // global (~/.claude/settings.json) and project (.claude/settings.json) are initialised.
   if (!existsSync(destPath)) {
     if (!dryRun) {
-      const hooksOnly = kitSettings.hooks ? { hooks: kitSettings.hooks } : {};
+      const hooksOnly = {};
+      if (kitSettings.hooks) {
+        for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
+          const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event);
+          if (deduped.length > 0) hooksOnly[event] = deduped;
+        }
+      }
       mkdirSync(targetDir, { recursive: true });
-      writeFileSync(destPath, JSON.stringify(hooksOnly, null, 2) + '\n', 'utf-8');
+      const payload = Object.keys(hooksOnly).length > 0 ? { hooks: hooksOnly } : {};
+      writeFileSync(destPath, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
     }
     return { action: 'created' };
   }
@@ -231,11 +287,19 @@ export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
     if (!userSettings.hooks) userSettings.hooks = {};
     for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
       if (!userSettings.hooks[event]) {
-        userSettings.hooks[event] = kitEntries;
-        merged.push(event);
+        const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event);
+        if (deduped.length > 0) {
+          userSettings.hooks[event] = deduped;
+          merged.push(event);
+        }
       } else {
         for (const kitEntry of kitEntries) {
           const kitMatcher = kitEntry.matcher || '*';
+          // Dedup guard: skip if sibling already has this event+matcher
+          if (isInSibling(siblingHooks, event, kitMatcher)) {
+            process.stderr.write(`mk: hook ${event}[${kitMatcher}] skipped (exists in settings.local.json)\n`);
+            continue;
+          }
           const idx = userSettings.hooks[event].findIndex(
             e => (e.matcher || '*') === kitMatcher
           );