@khanhcan148/mk 0.1.8 → 0.1.10

package/README.md

@@ -2,12 +2,20 @@
 
 [![npm](https://img.shields.io/npm/v/@khanhcan148/mk)](https://www.npmjs.com/package/@khanhcan148/mk)
 
-**Built by** TRAN Le Khanh — developer and AI tooling author.
+**Built by** TRAN Le Khanh (khanhcan148@gmail.com) — developer and AI tooling author.
 
 Modular packages that extend Claude Code with specialized knowledge, workflows, and tool integrations.
 
 **Quick Navigation:** [Quick Reference](docs/QUICK-REFERENCE.md) | [Common Workflows](docs/COMMON-WORKFLOWS.md) | [Skill Index](docs/SKILL-INDEX.md)
 
+## 🔒 Access Notice
+
+**This package has limited access.** To get access to the npm package and repository:
+
+📧 **Email:** khanhcan148@gmail.com
+
+Include your use case and I'll send you an invitation.
+
 ## Quick Start
 
 ### CLI Installation (Recommended)
@@ -26,7 +34,7 @@ mk init --global
 mk init --dry-run
 ```
 
-**Note**: The source repository is private. Use the published npm package for installation.
+**Note**: This package has limited access. Email khanhcan148@gmail.com for an invitation to access the npm package and repository.
 
 ### CLI Commands
 
@@ -65,17 +73,20 @@ cp -r .claude ~/.claude/
 
 ```bash
 # Use a workflow command
-/mk-init          # Bootstrap new project
-/mk-brainstorm    # Explore options, debate trade-offs
-/mk-plan          # Create implementation plan
-/mk-implement     # End-to-end feature delivery
-/mk-test          # Run tests and validate
-/mk-review        # Code quality review
-/mk-debug         # Debug issues
-/mk-security      # Security scan and audit
-/mk-db            # Database operations
-/mk-docs          # Generate documentation
-/mk-git           # Git operations
+/mk-init           # Bootstrap new project
+/mk-brainstorm     # Explore options, debate trade-offs
+/mk-plan           # Create implementation plan
+/mk-implement      # End-to-end feature delivery
+/mk-test           # Run tests and validate
+/mk-review         # Code quality review
+/mk-debug          # Debug issues
+/mk-security       # Security scan and audit
+/mk-db             # Database operations
+/mk-docs           # Generate documentation
+/mk-git            # Git operations
+/mk-audit          # Code archaeology chain: orientation, testing, heatmap, breaking-change analysis, technical debt, domain extraction
+/mk-skill-creator  # Create and scaffold new Claude Code skills with automated validation
+/mk-selftest       # Self-validation checks on kit agents, skills, docs, workflows
 ```
 
 ## Structure
@@ -83,8 +94,8 @@ cp -r .claude ~/.claude/
 ```
 ├── .claude/
 │   ├── agents/      # 29 agents (5 primary + 24 utility: implementers, quality, docs, specialized, concerns)
-│   ├── skills/      # 53 skill packages (SKILL.md + scripts/references/assets)
-│   │   ├── mk-*/    # 14 workflow commands (/mk-brainstorm, /mk-selftest, etc.)
+│   ├── skills/      # 58 skill packages (SKILL.md + scripts/references/assets)
+│   │   ├── mk-*/    # 16 workflow commands (/mk-audit, /mk-brainstorm, /mk-skill-creator, /mk-selftest, etc.)
 │   │   └── ...      # Domain skills (frontend, backend, testing, etc.)
 │   └── workflows/   # Development protocols
 ├── bin/             # CLI entry point (mk command)
@@ -116,8 +127,8 @@ User → /mk-* command (skill) → spawns utility agents → agents use knowledg
 | Command | Purpose |
 |---------|---------|
 | `/mk-init` | Full project bootstrap from conception to deployment; includes brownfield detection (Phase 0 gate) and adoption workflow (B1-B4.5 stages) |
-| `/mk-brainstorm` | Ideation, requirements exploration, structured debate (analyzer opus agent); use `--domain` flag to extract and document domain knowledge |
-| `/mk-research` | Deep multi-source research on technical topics |
+| `/mk-brainstorm` | Ideation, requirements exploration, structured debate (analyzer opus agent) |
+| `/mk-audit` | Code archaeology chain: orientation report, characterization testing, topology heatmap, breaking-change analysis, technical debt dashboard, domain extraction |
 | `/mk-plan` | Create implementation plans with phases and tasks (opus) |
 | `/mk-design` | UI/UX wireframes, design systems, mockups |
 | `/mk-implement` | End-to-end feature delivery (sonnet) |
@@ -128,6 +139,8 @@ User → /mk-* command (skill) → spawns utility agents → agents use knowledg
 | `/mk-db` | Database operations: diagnose, optimize, design, migrate |
 | `/mk-docs` | Generate and update project documentation |
 | `/mk-git` | Git operations: branch, commit, push, PR, merge |
+| `/mk-research` | Deep multi-source research on technical topics |
+| `/mk-skill-creator` | Create and scaffold new Claude Code skills with automated SKILL.md, scripts, references, and agent |
 | `/mk-selftest` | Run self-validation checks on kit agents, skills, docs, and workflows |
 
 ## Primary Agents
@@ -203,11 +216,12 @@ Each skill contains:
 - `assets/` (optional) - Templates, images
 
 ```bash
-# Initialize new skill
-.claude/skills/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>
+# Create new skill (recommended)
+/mk-skill-creator
 
-# Package for distribution
-.claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>
+# Or use scripts directly
+.claude/skills/mk-skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>
+.claude/skills/mk-skill-creator/scripts/package_skill.py <path/to/skill-folder>
 ```
 
 ## Documentation

package/package.json

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

package/src/commands/update.js

@@ -1,11 +1,11 @@
 import chalk from 'chalk';
 import { createInterface } from 'node:readline';
-import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
+import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync, rmdirSync, readdirSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readManifest, updateManifest, diffManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
-import { copyKitFiles } from '../lib/copy.js';
+import { copyKitFiles, collectDiskFiles } from '../lib/copy.js';
 import { resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
 import { resolveTokenOrLogin } from '../lib/auth.js';
 import { writeToken, readStoredToken } from '../lib/config.js';
@@ -167,6 +167,58 @@ export async function runUpdate(params = {}) {
     delete newFiles[relPath];
   }
 
+  // Orphan cleanup: files on disk (in kit subdirs) that are not in the new source
+  const diskFiles = collectDiskFiles(targetDir);
+  const orphans = [];
+  const orphanParentDirs = new Set();
+  for (const relPath of diskFiles) {
+    if (relPath in sourceFiles) continue; // present in new source — keep
+    const absPath = join(projectRoot, relPath);
+    try {
+      assertSafePath(absPath, claudeRoot, `orphan "${relPath}"`);
+    } catch (err) {
+      process.stderr.write(`Warning: Skipping unsafe orphan path: ${err.message}\n`);
+      continue;
+    }
+    try {
+      unlinkSync(absPath);
+      orphans.push(relPath);
+      orphanParentDirs.add(dirname(absPath));
+    } catch {
+      // Already missing — skip
+    }
+  }
+
+  // Clean up empty directories bottom-up after orphan deletion
+  const resolvedTarget = resolve(targetDir);
+  const sortedOrphanDirs = [...orphanParentDirs].sort((a, b) => {
+    return b.split(/[/\\]/).length - a.split(/[/\\]/).length;
+  });
+  for (const dir of sortedOrphanDirs) {
+    if (isEmptyDir(dir)) {
+      try {
+        rmdirSync(dir);
+        let current = dirname(dir);
+        let prev = dir;
+        while (current !== prev && isEmptyDir(current)) {
+          const resolvedCurrent = resolve(current);
+          if (resolvedCurrent === resolvedTarget || !resolvedCurrent.startsWith(resolvedTarget + sep)) {
+            break;
+          }
+          try {
+            rmdirSync(current);
+          } catch {
+            break;
+          }
+          prev = current;
+          current = dirname(current);
+        }
+      } catch {
+        // Non-empty or permission error — skip
+      }
+    }
+  }
+
   // Update manifest with new file map.
   // Use explicitVersion when provided (e.g. release.version from updateAction);
   // fall back to pkg.version for direct runUpdate calls or main-branch fallback downloads.
@@ -178,10 +230,24 @@ export async function runUpdate(params = {}) {
     removed: diff.removed,
     conflicts: skippedConflicts,
     unchanged: diff.unchanged,
+    orphans,
     upToDate: false
   };
 }
 
+/**
+ * Check if a directory is empty.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function isEmptyDir(dir) {
+  try {
+    return readdirSync(dir).length === 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * CLI action handler for 'mk update'.
  * Checks GitHub Releases for a newer version, prompts the user, then downloads
@@ -305,6 +371,15 @@ export async function updateAction(options = {}, deps = {}) {
       }
       if (result.removed.length > 0) {
         process.stdout.write(chalk.yellow(`Removed: ${result.removed.length} files\n`));
+        for (const f of result.removed) {
+          process.stdout.write(`  Removed: ${f}\n`);
+        }
+      }
+      if (result.orphans && result.orphans.length > 0) {
+        process.stdout.write(chalk.yellow(`Cleaned: ${result.orphans.length} orphan files\n`));
+        for (const f of result.orphans) {
+          process.stdout.write(`  Cleaned: ${f}\n`);
+        }
       }
       if (result.conflicts.length > 0) {
         process.stdout.write(

package/src/lib/constants.js

@@ -13,6 +13,7 @@ export const MANIFEST_FILENAME = '.mk-manifest.json';
  */
 export const COPY_FILTER_PATTERNS = [
   '__pycache__',
+  '.pytest_cache',
   '.pyc',
   '.pyo',
   'node_modules',

package/src/lib/copy.js

@@ -52,6 +52,31 @@ function collectFiles(dir) {
   return results;
 }
 
+/**
+ * Collect all kit-managed files currently on disk under targetDir (.claude/).
+ * Only walks KIT_SUBDIRS (agents/, skills/, workflows/).
+ * Returns relative paths in the form `.claude/agents/foo.md`.
+ * Applies shouldFilter to exclude filtered patterns.
+ *
+ * @param {string} targetDir - Absolute path to target .claude/
+ * @returns {string[]} relative paths (relative to project root, e.g. `.claude/agents/foo.md`)
+ */
+export function collectDiskFiles(targetDir) {
+  const results = [];
+  for (const subdir of KIT_SUBDIRS) {
+    const subdirAbs = join(targetDir, subdir);
+    if (!existsSync(subdirAbs)) continue;
+    const files = collectFiles(subdirAbs);
+    for (const absPath of files) {
+      if (shouldFilter(absPath)) continue;
+      const relFromSubdir = relative(subdirAbs, absPath);
+      const relPath = join('.claude', subdir, relFromSubdir).replace(/\\/g, '/');
+      results.push(relPath);
+    }
+  }
+  return results;
+}
+
 /**
  * Copy kit files from sourceDir (.claude/) to targetDir (.claude/).
  * Only copies KIT_SUBDIRS (agents/, skills/, workflows/).