@khanhcan148/mk 0.1.0

package/src/lib/copy.js

@@ -0,0 +1,130 @@
+import { join, relative } from 'node:path';
+import { statSync, lstatSync, existsSync } from 'node:fs';
+import fsExtra from 'fs-extra';
+import { KIT_SUBDIRS, COPY_FILTER_PATTERNS, WINDOWS_PATH_WARN_LENGTH } from './constants.js';
+
+/**
+ * Check if a path should be filtered out during copy.
+ * @param {string} filePath
+ * @returns {boolean} true if the file should be excluded
+ */
+function shouldFilter(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  for (const pattern of COPY_FILTER_PATTERNS) {
+    if (normalized.includes(pattern)) return true;
+  }
+  return false;
+}
+
+/**
+ * Collect all file paths recursively in a directory.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function collectFiles(dir) {
+  const results = [];
+  function walk(current) {
+    let entries;
+    try {
+      entries = fsExtra.readdirSync(current);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join(current, entry);
+      try {
+        // Use lstatSync (does not follow symlinks) to detect and skip symlinks.
+        // Symlinks inside the bundled .claude/ could otherwise redirect writes
+        // to arbitrary locations on the user's filesystem.
+        const lstat = lstatSync(fullPath);
+        if (lstat.isSymbolicLink()) continue;
+        if (lstat.isDirectory()) {
+          walk(fullPath);
+        } else {
+          results.push(fullPath);
+        }
+      } catch {
+        // skip inaccessible files
+      }
+    }
+  }
+  walk(dir);
+  return results;
+}
+
+/**
+ * Copy kit files from sourceDir (.claude/) to targetDir (.claude/).
+ * Only copies KIT_SUBDIRS (agents/, skills/, workflows/).
+ *
+ * @param {string} sourceDir - Absolute path to source .claude/
+ * @param {string} targetDir - Absolute path to target .claude/
+ * @param {{ dryRun: boolean }} options
+ * @returns {Array<{ relativePath: string, absolutePath: string, sourceAbsPath: string, size: number }>}
+ */
+export function copyKitFiles(sourceDir, targetDir, options = {}) {
+  const { dryRun = false } = options;
+  const fileList = [];
+  const warnings = [];
+
+  for (const subdir of KIT_SUBDIRS) {
+    const srcSubdir = join(sourceDir, subdir);
+    if (!existsSync(srcSubdir)) continue;
+
+    // Collect files in this subdir
+    const files = collectFiles(srcSubdir);
+
+    for (const absPath of files) {
+      if (shouldFilter(absPath)) continue;
+
+      const relFromSubdir = relative(srcSubdir, absPath);
+      const relPath = join('.claude', subdir, relFromSubdir).replace(/\\/g, '/');
+      const destAbs = join(targetDir, subdir, relFromSubdir);
+
+      // Windows path length check
+      if (destAbs.length > WINDOWS_PATH_WARN_LENGTH) {
+        warnings.push(`Warning: Long path (${destAbs.length} chars): ${destAbs}`);
+      }
+
+      let size = 0;
+      try {
+        size = statSync(absPath).size;
+      } catch {
+        // ignore
+      }
+
+      fileList.push({ relativePath: relPath, absolutePath: destAbs, sourceAbsPath: absPath, size });
+    }
+  }
+
+  // Print warnings
+  for (const w of warnings) {
+    process.stderr.write(w + '\n');
+  }
+
+  if (dryRun) {
+    return fileList;
+  }
+
+  // Actually copy each subdir using fs-extra
+  for (const subdir of KIT_SUBDIRS) {
+    const srcSubdir = join(sourceDir, subdir);
+    if (!existsSync(srcSubdir)) continue;
+    const destSubdir = join(targetDir, subdir);
+
+    fsExtra.copySync(srcSubdir, destSubdir, {
+      overwrite: true,
+      filter: (src) => {
+        if (shouldFilter(src)) return false;
+        try {
+          // Skip symlinks — prevents traversal to paths outside destSubdir
+          if (lstatSync(src).isSymbolicLink()) return false;
+        } catch {
+          return false;
+        }
+        return true;
+      }
+    });
+  }
+
+  return fileList;
+}

package/src/lib/download.js

@@ -0,0 +1,262 @@
+import { createGunzip } from 'node:zlib';
+import { mkdirSync, writeFileSync, rmSync, mkdtempSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { Writable, Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { GITHUB_API, KIT_REPO } from './constants.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const KIT_BRANCH = 'main';
+const TARBALL_URL = `${GITHUB_API}/repos/${KIT_REPO}/tarball/${KIT_BRANCH}`;
+
+// ---------------------------------------------------------------------------
+// Manual tar stream parser (zero-dependency, handles regular files + dirs)
+// ---------------------------------------------------------------------------
+
+/**
+ * A Writable stream that parses tar format and writes matching entries to disk.
+ * Only processes entries whose paths contain '.claude/' after stripping the root prefix.
+ *
+ * Tar format: 512-byte header blocks followed by data blocks (padded to 512 bytes).
+ * Two consecutive 512-byte zero blocks mark end of archive.
+ */
+class TarExtractor extends Writable {
+  /**
+   * @param {string} destDir - Destination directory (resolved to absolute path)
+   */
+  constructor(destDir) {
+    super();
+    this.destDir = resolve(destDir);
+    // Chunk list avoids O(n²) Buffer.concat on every write
+    this._chunks = [];
+    this._totalLen = 0;
+    this._state = 'header'; // 'header' | 'data' | 'skip'
+    this._remaining = 0;    // bytes left in current entry data
+    this._paddedSize = 0;   // padded size of current entry (multiple of 512)
+    this._currentPath = '';  // relative path being written ('' if not .claude/)
+    this._rootPrefix = null; // first root directory prefix to strip
+    this._zeroBlocks = 0;
+  }
+
+  _write(chunk, encoding, callback) {
+    this._chunks.push(chunk);
+    this._totalLen += chunk.length;
+    try {
+      this._process();
+      callback();
+    } catch (err) {
+      callback(err);
+    }
+  }
+
+  /** Consolidate pending chunks into one Buffer (lazy — only when access needed). */
+  _getBuffer() {
+    if (this._chunks.length !== 1) {
+      this._chunks = [Buffer.concat(this._chunks)];
+    }
+    return this._chunks[0];
+  }
+
+  /** Consume n bytes from the front of the chunk list. */
+  _consumeBuffer(n) {
+    const buf = this._getBuffer();
+    const remaining = buf.slice(n);
+    this._chunks = remaining.length > 0 ? [remaining] : [];
+    this._totalLen -= n;
+  }
+
+  _process() {
+    while (this._totalLen >= 512) {
+      if (this._state === 'header') {
+        this._parseHeader();
+      } else if (this._state === 'data') {
+        this._readData();
+      } else if (this._state === 'skip') {
+        this._skipData();
+      }
+
+      // Don't loop if we can't make progress
+      if (this._state === 'data' && this._totalLen < 512) break;
+      if (this._state === 'skip' && this._totalLen < 512) break;
+    }
+  }
+
+  /**
+   * Assert that resolvedPath is safely contained within this.destDir.
+   * Throws if the path would escape the destination directory.
+   * @param {string} resolvedPath
+   */
+  _assertSafe(resolvedPath) {
+    if (resolvedPath !== this.destDir && !resolvedPath.startsWith(this.destDir + sep)) {
+      throw new Error(`Path traversal detected: "${resolvedPath}" escapes destination directory`);
+    }
+  }
+
+  _parseHeader() {
+    const block = this._getBuffer().slice(0, 512);
+
+    // Check for zero block (end of archive)
+    if (block[0] === 0 && block.every(b => b === 0)) {
+      this._zeroBlocks++;
+      this._consumeBuffer(512);
+      return;
+    }
+    this._zeroBlocks = 0;
+
+    // Parse header fields
+    const rawName = block.slice(0, 100).toString('utf8').replace(/\0+$/, '');
+    const prefix = block.slice(345, 500).toString('utf8').replace(/\0+$/, '');
+    const fullName = prefix ? `${prefix}/${rawName}` : rawName;
+
+    const sizeOctal = block.slice(124, 136).toString('utf8').replace(/\0/g, '').trim();
+    const size = sizeOctal ? parseInt(sizeOctal, 8) : 0;
+
+    const typeFlag = String.fromCharCode(block[156]) || '0';
+
+    // Detect and strip root prefix (first directory component)
+    if (this._rootPrefix === null) {
+      const firstSlash = fullName.indexOf('/');
+      this._rootPrefix = firstSlash >= 0 ? fullName.slice(0, firstSlash + 1) : '';
+    }
+
+    const strippedName = fullName.startsWith(this._rootPrefix)
+      ? fullName.slice(this._rootPrefix.length)
+      : fullName;
+
+    this._consumeBuffer(512);
+
+    // Block symlinks and hard links entirely — prevents symlink-based escapes
+    if (typeFlag === '1' || typeFlag === '2') {
+      this._state = 'header';
+      return;
+    }
+
+    // Only process entries under .claude/
+    const isClaudePath = strippedName.startsWith('.claude/');
+
+    if (typeFlag === '5' || typeFlag === '\0' || typeFlag === '') {
+      // Directory entry
+      if (isClaudePath && strippedName) {
+        const dirPath = resolve(join(this.destDir, strippedName));
+        this._assertSafe(dirPath);
+        mkdirSync(dirPath, { recursive: true });
+      }
+      this._state = 'header';
+      return;
+    }
+
+    // Regular file entry (typeFlag '0' or empty/null)
+    if (size === 0) {
+      if (isClaudePath) {
+        const filePath = resolve(join(this.destDir, strippedName));
+        this._assertSafe(filePath);
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, Buffer.alloc(0));
+      }
+      this._state = 'header';
+      return;
+    }
+
+    this._remaining = size;
+    this._paddedSize = Math.ceil(size / 512) * 512;
+
+    if (isClaudePath) {
+      this._currentPath = strippedName;
+      this._state = 'data';
+    } else {
+      this._state = 'skip';
+    }
+  }
+
+  _readData() {
+    if (this._totalLen < this._paddedSize && this._totalLen < 512) {
+      return; // Wait for more data
+    }
+
+    if (this._totalLen >= this._paddedSize) {
+      // We have all the data for this entry
+      const buf = this._getBuffer();
+      const rawData = buf.slice(0, this._remaining);
+      this._consumeBuffer(this._paddedSize);
+
+      const filePath = resolve(join(this.destDir, this._currentPath));
+      this._assertSafe(filePath);
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, rawData);
+
+      this._currentPath = '';
+      this._state = 'header';
+    }
+    // else: not enough data yet — wait
+  }
+
+  _skipData() {
+    if (this._totalLen < this._paddedSize) {
+      return; // Wait for more data
+    }
+    this._consumeBuffer(this._paddedSize);
+    this._state = 'header';
+  }
+
+  _final(callback) {
+    callback();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Download the kit repository as a tarball and extract .claude/ to targetDir.
+ *
+ * @param {string} token - GitHub Bearer token
+ * @param {{ targetDir?: string }} [opts]
+ * @returns {Promise<string>} The targetDir path
+ */
+export async function downloadAndExtractKit(token, opts = {}) {
+  const { targetDir = mkdtempSync(join(tmpdir(), 'mk-kit-')) } = opts;
+
+  let res;
+  try {
+    res = await fetch(TARBALL_URL, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github.v3+json'
+      },
+      redirect: 'follow'
+    });
+  } catch (err) {
+    throw new Error(`Network connection failed: ${err.message}`);
+  }
+
+  if (!res.ok) {
+    throw new Error(`GitHub API error: ${res.status} ${res.statusText}`);
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+
+  const gunzip = createGunzip();
+  const extractor = new TarExtractor(targetDir);
+
+  await pipeline(
+    Readable.fromWeb(res.body),
+    gunzip,
+    extractor
+  );
+
+  return targetDir;
+}
+
+/**
+ * Remove a temp directory created by downloadAndExtractKit.
+ *
+ * @param {string} tempDir
+ */
+export function cleanupTempDir(tempDir) {
+  rmSync(tempDir, { recursive: true, force: true });
+}

package/src/lib/manifest.js

@@ -0,0 +1,115 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+
+/**
+ * Write a manifest file to disk.
+ * @param {string} manifestPath - Absolute path to write
+ * @param {Object} files - Map of relativePath -> { checksum, size }
+ * @param {string} version - Kit version
+ * @param {'project'|'global'} scope
+ */
+export function writeManifest(manifestPath, files, version, scope) {
+  const now = new Date().toISOString();
+  const manifest = {
+    version,
+    installedAt: now,
+    updatedAt: now,
+    scope,
+    files
+  };
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+}
+
+/**
+ * Update an existing manifest's files, version, and updatedAt.
+ * @param {string} manifestPath
+ * @param {Object} files - New files map
+ * @param {string} version - New kit version
+ */
+export function updateManifest(manifestPath, files, version) {
+  const existing = readManifest(manifestPath);
+  const updated = {
+    ...existing,
+    version,
+    updatedAt: new Date().toISOString(),
+    files
+  };
+  writeFileSync(manifestPath, JSON.stringify(updated, null, 2), 'utf8');
+}
+
+/**
+ * Read and parse a manifest file.
+ * @param {string} manifestPath
+ * @returns {Object} Parsed manifest
+ * @throws {Error} If file not found or invalid JSON
+ */
+export function readManifest(manifestPath) {
+  let raw;
+  try {
+    raw = readFileSync(manifestPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`Manifest not found: ${manifestPath}`);
+    }
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Invalid JSON in manifest: ${manifestPath} (${err.message})`);
+  }
+}
+
+/**
+ * Perform a three-way diff between manifest, source files, and current disk state.
+ *
+ * @param {Object} manifest - Parsed manifest object
+ * @param {Object} sourceFiles - Map of relativePath -> { checksum, size } from source
+ * @param {Object} diskChecksums - Map of relativePath -> checksum of current disk state
+ * @returns {{ unchanged: string[], updated: string[], conflicts: string[], added: string[], removed: string[] }}
+ */
+export function diffManifest(manifest, sourceFiles, diskChecksums) {
+  const result = {
+    unchanged: [],
+    updated: [],
+    conflicts: [],
+    added: [],
+    removed: []
+  };
+
+  const manifestFiles = manifest.files || {};
+
+  // Check all source files against manifest
+  for (const [relPath, sourceEntry] of Object.entries(sourceFiles)) {
+    const sourceChecksum = sourceEntry.checksum;
+
+    if (!(relPath in manifestFiles)) {
+      // New file in source not in manifest -> ADD
+      result.added.push(relPath);
+    } else {
+      const manifestChecksum = manifestFiles[relPath].checksum;
+      if (sourceChecksum === manifestChecksum) {
+        // Source matches manifest -> UNCHANGED
+        result.unchanged.push(relPath);
+      } else {
+        // Source differs from manifest -> kit updated this file
+        const diskChecksum = diskChecksums[relPath];
+        if (!diskChecksum || diskChecksum === manifestChecksum) {
+          // Disk is same as manifest (user didn't modify) -> SAFE UPDATE
+          result.updated.push(relPath);
+        } else {
+          // Disk differs from manifest (user modified) AND kit changed -> CONFLICT
+          result.conflicts.push(relPath);
+        }
+      }
+    }
+  }
+
+  // Check manifest files not in source -> REMOVED from kit
+  for (const relPath of Object.keys(manifestFiles)) {
+    if (!(relPath in sourceFiles)) {
+      result.removed.push(relPath);
+    }
+  }
+
+  return result;
+}

package/src/lib/paths.js

@@ -0,0 +1,70 @@
+import { join, dirname, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve the source .claude/ directory from the npm package root.
+ * When installed via npm, the package root is two levels up from src/lib/.
+ * @returns {string} Absolute path to the package's .claude/ directory
+ */
+export function resolveSourceDir() {
+  // src/lib/paths.js -> src/lib -> src -> packageRoot
+  const packageRoot = join(__dirname, '..', '..');
+  return join(packageRoot, '.claude');
+}
+
+/**
+ * Resolve the target .claude/ directory.
+ * @param {{ global: boolean }} options
+ * @returns {string} Absolute path to target .claude/ directory
+ */
+export function resolveTargetDir(options) {
+  if (options.global) {
+    return join(homedir(), '.claude');
+  }
+  return join(process.cwd(), '.claude');
+}
+
+/**
+ * Resolve the manifest file path.
+ * @param {{ global: boolean }} options
+ * @returns {string} Absolute path to .mk-manifest.json
+ */
+export function resolveManifestPath(options) {
+  if (options.global) {
+    return join(homedir(), '.claude', '.mk-manifest.json');
+  }
+  return join(process.cwd(), '.mk-manifest.json');
+}
+
+/**
+ * Derive project root from manifest scope and path.
+ * For project installs the manifest is at cwd/.mk-manifest.json → root = cwd.
+ * For global installs the manifest is at ~/.claude/.mk-manifest.json → root = homedir,
+ * because all relPaths start with '.claude/' and the actual files live at ~/.<file>.
+ * @param {Object} manifest - Parsed manifest object
+ * @param {string} manifestPath - Absolute path to .mk-manifest.json
+ * @returns {string} Absolute project root path
+ */
+export function deriveProjectRoot(manifest, manifestPath) {
+  return manifest.scope === 'global' ? homedir() : dirname(manifestPath);
+}
+
+/**
+ * Assert that absPath is safely inside rootDir (prevent path-traversal from manifest keys).
+ * Throws if the resolved path escapes the allowed directory.
+ * @param {string} absPath - Path to validate
+ * @param {string} rootDir - Allowed root directory
+ * @param {string} [label] - Label for error messages
+ */
+export function assertSafePath(absPath, rootDir, label = 'path') {
+  const resolved = resolve(absPath);
+  const root = resolve(rootDir);
+  if (resolved !== root && !resolved.startsWith(root + sep)) {
+    throw new Error(
+      `Security: ${label} "${absPath}" resolves outside allowed directory "${rootDir}"`
+    );
+  }
+}