@khanhcan148/mk 0.1.0

package/src/commands/remove.js

@@ -0,0 +1,146 @@
+import chalk from 'chalk';
+import { existsSync, unlinkSync, rmdirSync, readdirSync } from 'node:fs';
+import { join, dirname, resolve, sep } from 'node:path';
+import { readManifest } from '../lib/manifest.js';
+import { resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
+
+/**
+ * Run the remove command.
+ *
+ * @param {{
+ *   targetDir?: string,
+ *   manifestPath?: string
+ * }} params
+ * @returns {Promise<{ removed: number, skipped: number, dirsCleaned: number }>}
+ */
+export async function runRemove(params = {}) {
+  const {
+    targetDir = resolveTargetDir({ global: false }),
+    manifestPath = resolveManifestPath({ global: false })
+  } = params;
+
+  // Read manifest
+  let manifest;
+  try {
+    manifest = readManifest(manifestPath);
+  } catch (err) {
+    throw new Error(`Not installed (no manifest found). Kit has not been installed here. (${err.message})`);
+  }
+
+  const projectRoot = deriveProjectRoot(manifest, manifestPath);
+  const claudeRoot = resolve(join(projectRoot, '.claude'));
+  const files = manifest.files || {};
+
+  let removed = 0;
+  let skipped = 0;
+  const parentDirs = new Set();
+
+  // Delete each file in manifest
+  for (const relPath of Object.keys(files)) {
+    const absPath = join(projectRoot, relPath);
+    // Bounds check: relPath from manifest must not escape .claude/ subtree
+    try {
+      assertSafePath(absPath, claudeRoot, `manifest key "${relPath}"`);
+    } catch (err) {
+      process.stderr.write(`Warning: Skipping unsafe path from manifest: ${err.message}\n`);
+      skipped++;
+      continue;
+    }
+    if (existsSync(absPath)) {
+      try {
+        unlinkSync(absPath);
+        removed++;
+        // Track parent directory for cleanup
+        parentDirs.add(dirname(absPath));
+      } catch (err) {
+        process.stderr.write(`Warning: Could not delete ${absPath}: ${err.message}\n`);
+        skipped++;
+      }
+    } else {
+      skipped++;
+    }
+  }
+
+  // Clean up empty directories (bottom-up — deepest first)
+  const sortedDirs = [...parentDirs].sort((a, b) => {
+    // More path separators = deeper
+    const depthA = a.split(/[/\\]/).length;
+    const depthB = b.split(/[/\\]/).length;
+    return depthB - depthA;
+  });
+
+  let dirsCleaned = 0;
+  for (const dir of sortedDirs) {
+    if (isEmptyDir(dir)) {
+      try {
+        rmdirSync(dir);
+        dirsCleaned++;
+        // Also try parent directories, but never delete targetDir or above
+        const resolvedTarget = resolve(targetDir);
+        let current = dirname(dir);
+        let prev = dir;
+        while (current !== prev && isEmptyDir(current)) {
+          const resolvedCurrent = resolve(current);
+          // Stop at targetDir boundary — never delete .claude/ root or anything above it
+          if (resolvedCurrent === resolvedTarget || !resolvedCurrent.startsWith(resolvedTarget + sep)) {
+            break;
+          }
+          try {
+            rmdirSync(current);
+            dirsCleaned++;
+          } catch {
+            break;
+          }
+          prev = current;
+          current = dirname(current);
+        }
+      } catch {
+        // Non-empty or permission error — skip
+      }
+    }
+  }
+
+  // Delete manifest itself
+  try {
+    unlinkSync(manifestPath);
+  } catch {
+    // If manifest already gone, that's fine
+  }
+
+  return { removed, skipped, dirsCleaned };
+}
+
+/**
+ * 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 remove'.
+ * @param {{ global: boolean }} options
+ */
+export async function removeAction(options = {}) {
+  const targetDir = resolveTargetDir(options);
+  const manifestPath = resolveManifestPath(options);
+
+  try {
+    process.stdout.write('Removing MyClaudeKit files...\n');
+    const result = await runRemove({ targetDir, manifestPath });
+    process.stdout.write(
+      chalk.green(
+        `\nSummary: ${result.removed} files removed, ${result.skipped} already missing, ${result.dirsCleaned} directories cleaned.\n`
+      )
+    );
+  } catch (err) {
+    process.stderr.write(chalk.red(`Error: ${err.message}\n`));
+    process.exit(1);
+  }
+}

package/src/commands/update.js

@@ -0,0 +1,221 @@
+import chalk from 'chalk';
+import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync } 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 { resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
+import { resolveTokenOrLogin } from '../lib/auth.js';
+import { writeToken, readStoredToken } from '../lib/config.js';
+import { downloadAndExtractKit, cleanupTempDir } from '../lib/download.js';
+
+/**
+ * Run the update command.
+ *
+ * @param {{
+ *   sourceDir?: string,
+ *   targetDir?: string,
+ *   manifestPath?: string,
+ *   force?: boolean
+ * }} params
+ * @returns {Promise<{ updated: string[], added: string[], removed: string[], conflicts: string[], unchanged: string[], upToDate: boolean }>}
+ */
+export async function runUpdate(params = {}) {
+  const {
+    sourceDir = resolveSourceDir(),
+    targetDir = resolveTargetDir({ global: false }),
+    manifestPath = resolveManifestPath({ global: false }),
+    force = false
+  } = params;
+
+  // Read existing manifest
+  let manifest;
+  try {
+    manifest = readManifest(manifestPath);
+  } catch (err) {
+    throw new Error(`Not installed (no manifest found). Run 'mk init' first. (${err.message})`);
+  }
+
+  // Derive project root from manifest scope (global: homedir, project: dirname(manifestPath))
+  const projectRoot = deriveProjectRoot(manifest, manifestPath);
+  const claudeRoot = resolve(join(projectRoot, '.claude'));
+  const sourceFileList = copyKitFiles(sourceDir, targetDir, { dryRun: true });
+  const sourceFiles = {};
+  for (const entry of sourceFileList) {
+    const checksum = computeChecksum(entry.sourceAbsPath);
+    sourceFiles[entry.relativePath] = { checksum, size: entry.size };
+  }
+
+  // Get disk checksums for files currently in manifest
+  const diskChecksums = {};
+  for (const relPath of Object.keys(manifest.files)) {
+    // relPath is like '.claude/agents/foo.md' — relative to project root
+    const absPath = join(projectRoot, relPath);
+    // Bounds check: manifest keys must not escape .claude/ subtree
+    try {
+      assertSafePath(absPath, claudeRoot, `manifest key "${relPath}"`);
+    } catch {
+      process.stderr.write(`Warning: Skipping unsafe path in manifest: ${relPath}\n`);
+      continue;
+    }
+    if (existsSync(absPath)) {
+      diskChecksums[relPath] = computeChecksum(absPath);
+    }
+  }
+
+  // Three-way diff
+  const diff = diffManifest(manifest, sourceFiles, diskChecksums);
+
+  const upToDate =
+    diff.updated.length === 0 &&
+    diff.added.length === 0 &&
+    diff.removed.length === 0 &&
+    diff.conflicts.length === 0;
+
+  if (upToDate) {
+    return { ...diff, upToDate: true };
+  }
+
+  // Read package version (fileURLToPath handles Windows drive-letter prefix correctly)
+  const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+
+  const newFiles = { ...manifest.files };
+
+  /**
+   * Copy a source file entry to its destination.
+   * @param {string} relPath
+   */
+  function applyCopy(relPath) {
+    const entry = sourceFileList.find(f => f.relativePath === relPath);
+    if (!entry) return;
+    const destAbs = join(projectRoot, relPath);
+    // Bounds check: destination must stay inside .claude/ subtree
+    assertSafePath(destAbs, claudeRoot, `copy destination for "${relPath}"`);
+    mkdirSync(dirname(destAbs), { recursive: true });
+    copyFileSync(entry.sourceAbsPath, destAbs);
+    // Reuse source checksum — copy is bit-for-bit identical, no need to re-hash
+    newFiles[relPath] = { checksum: sourceFiles[relPath].checksum, size: entry.size };
+  }
+
+  // Apply safe updates
+  for (const relPath of diff.updated) {
+    applyCopy(relPath);
+  }
+
+  // Handle conflicts
+  const skippedConflicts = [];
+  for (const relPath of diff.conflicts) {
+    if (force) {
+      applyCopy(relPath);
+    } else {
+      skippedConflicts.push(relPath);
+    }
+  }
+
+  // Add new files
+  for (const relPath of diff.added) {
+    applyCopy(relPath);
+  }
+
+  // Remove deleted kit files
+  for (const relPath of diff.removed) {
+    const absPath = join(projectRoot, relPath);
+    // Bounds check: removal must stay inside .claude/ subtree
+    try {
+      assertSafePath(absPath, claudeRoot, `removal target "${relPath}"`);
+    } catch (err) {
+      process.stderr.write(`Warning: Skipping unsafe removal path: ${err.message}\n`);
+      continue;
+    }
+    try {
+      unlinkSync(absPath);
+    } catch {
+      // Already missing — skip
+    }
+    delete newFiles[relPath];
+  }
+
+  // Update manifest with new file map
+  updateManifest(manifestPath, newFiles, pkg.version);
+
+  return {
+    updated: diff.updated,
+    added: diff.added,
+    removed: diff.removed,
+    conflicts: skippedConflicts,
+    unchanged: diff.unchanged,
+    upToDate: false
+  };
+}
+
+/**
+ * CLI action handler for 'mk update'.
+ * Downloads fresh kit from GitHub and applies three-way diff.
+ *
+ * @param {{ force: boolean, global: boolean }} options
+ * @param {object} [deps] - Injected dependencies (for testing)
+ */
+export async function updateAction(options = {}, deps = {}) {
+  const {
+    resolveTokenOrLogin: resolveAndLogin = resolveTokenOrLogin,
+    downloadAndExtractKit: download = downloadAndExtractKit,
+    cleanupTempDir: cleanup = cleanupTempDir,
+    writeToken: storeToken = writeToken,
+    readStoredToken: readToken = readStoredToken
+  } = deps;
+
+  const targetDir = resolveTargetDir(options);
+  const manifestPath = resolveManifestPath(options);
+
+  let tempDir = null;
+  try {
+    process.stdout.write('Authenticating with GitHub...\n');
+    const token = await resolveAndLogin({
+      readStored: readToken,
+      writeStored: storeToken,
+      display: ({ userCode, verificationUri, expiresIn }) => {
+        process.stdout.write('\n');
+        process.stdout.write(chalk.bold('To authenticate, visit:  ') + chalk.cyan(verificationUri) + '\n');
+        process.stdout.write(chalk.bold('And enter the code:      ') + chalk.yellow(userCode) + '\n');
+        process.stdout.write(`(Code expires in ${Math.round(expiresIn / 60)} minutes)\n\n`);
+        process.stdout.write('Waiting for authorization...\n');
+      }
+    });
+
+    process.stdout.write('Downloading latest kit from GitHub...\n');
+    tempDir = await download(token);
+    const sourceDir = join(tempDir, '.claude');
+
+    const result = await runUpdate({ sourceDir, targetDir, manifestPath, force: options.force });
+
+    if (result.upToDate) {
+      process.stdout.write(chalk.green('Already up to date.\n'));
+    } else {
+      if (result.updated.length > 0) {
+        process.stdout.write(chalk.green(`Updated: ${result.updated.length} files\n`));
+      }
+      if (result.added.length > 0) {
+        process.stdout.write(chalk.green(`Added: ${result.added.length} new files\n`));
+      }
+      if (result.removed.length > 0) {
+        process.stdout.write(chalk.yellow(`Removed: ${result.removed.length} files\n`));
+      }
+      if (result.conflicts.length > 0) {
+        process.stdout.write(
+          chalk.yellow(`Skipped: ${result.conflicts.length} user-modified files (use --force to overwrite)\n`)
+        );
+        for (const f of result.conflicts) {
+          process.stdout.write(`  ${f}\n`);
+        }
+      }
+    }
+  } catch (err) {
+    process.stderr.write(chalk.red(`Error: ${err.message}\n`));
+    process.exit(1);
+  } finally {
+    if (tempDir) {
+      cleanup(tempDir);
+    }
+  }
+}

package/src/lib/auth.js

@@ -0,0 +1,211 @@
+import { readStoredToken, writeToken } from './config.js';
+import { GITHUB_API, KIT_REPO } from './constants.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const GITHUB_CLIENT_ID = 'Ov23li35aA2A1xVa01B6';
+export const GITHUB_DEVICE_CODE_URL = 'https://github.com/login/device/code';
+export const GITHUB_TOKEN_URL = 'https://github.com/login/oauth/access_token';
+
+// Default sleep helper (real delay in production, overridable in tests)
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// ---------------------------------------------------------------------------
+// Token resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the current token from env vars or stored file.
+ * Priority: GITHUB_TOKEN > GH_TOKEN > stored file > null
+ *
+ * @param {{ readStored?: () => string|null }} [opts]
+ * @returns {string|null}
+ */
+export function resolveToken(opts = {}) {
+  const readStored = opts.readStored ?? readStoredToken;
+
+  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
+  if (process.env.GH_TOKEN) return process.env.GH_TOKEN;
+  return readStored() ?? null;
+}
+
+/**
+ * Identify the source of a token value.
+ *
+ * @param {string} token
+ * @param {{ readStored?: () => string|null }} [opts]
+ * @returns {'env:GITHUB_TOKEN' | 'env:GH_TOKEN' | 'stored' | 'unknown'}
+ */
+export function tokenSource(token, opts = {}) {
+  const readStored = opts.readStored ?? readStoredToken;
+
+  if (process.env.GITHUB_TOKEN === token) return 'env:GITHUB_TOKEN';
+  if (process.env.GH_TOKEN === token) return 'env:GH_TOKEN';
+  if (readStored() === token) return 'stored';
+  return 'unknown';
+}
+
+// ---------------------------------------------------------------------------
+// Token validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a token by calling the GitHub /user endpoint.
+ *
+ * @param {string} token
+ * @returns {Promise<{ valid: boolean, username?: string }>}
+ */
+export async function validateToken(token) {
+  try {
+    const res = await fetch(`${GITHUB_API}/user`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github.v3+json'
+      }
+    });
+    if (res.ok) {
+      const data = await res.json();
+      return { valid: true, username: data.login };
+    }
+    return { valid: false };
+  } catch {
+    return { valid: false };
+  }
+}
+
+/**
+ * Check whether the token has access to the kit repository.
+ *
+ * @param {string} token
+ * @returns {Promise<{ accessible: boolean }>}
+ */
+export async function checkRepoAccess(token) {
+  try {
+    const res = await fetch(`${GITHUB_API}/repos/${KIT_REPO}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github.v3+json'
+      }
+    });
+    return { accessible: res.ok };
+  } catch {
+    return { accessible: false };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// OAuth Device Flow
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the GitHub OAuth Device Flow and return the access token.
+ *
+ * @param {{
+ *   display: (info: { userCode: string, verificationUri: string, expiresIn: number }) => void,
+ *   writeStored?: (token: string) => void,
+ *   sleep?: (ms: number) => Promise<void>
+ * }} opts
+ * @returns {Promise<string>} Access token
+ */
+export async function startDeviceFlow(opts = {}) {
+  const {
+    display,
+    writeStored = writeToken,
+    sleep = defaultSleep
+  } = opts;
+
+  // Step 1: Request device + user code
+  const codeRes = await fetch(GITHUB_DEVICE_CODE_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json'
+    },
+    body: `client_id=${GITHUB_CLIENT_ID}&scope=repo`
+  });
+
+  if (!codeRes.ok) {
+    throw new Error(`Device flow failed: ${codeRes.status} ${codeRes.statusText}`);
+  }
+
+  const codeData = await codeRes.json();
+  const { device_code, user_code, verification_uri, interval = 5, expires_in = 900 } = codeData;
+
+  // Display instructions to the user
+  display({ userCode: user_code, verificationUri: verification_uri, expiresIn: expires_in });
+
+  // Step 2: Poll for the access token
+  const deadline = Date.now() + expires_in * 1000;
+  let pollInterval = interval * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(pollInterval);
+
+    const tokenRes = await fetch(GITHUB_TOKEN_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json'
+      },
+      body: `client_id=${GITHUB_CLIENT_ID}&device_code=${device_code}&grant_type=urn:ietf:params:oauth:grant-type:device_code`
+    });
+
+    const tokenData = await tokenRes.json();
+
+    if (tokenData.access_token) {
+      const token = tokenData.access_token;
+      writeStored(token);
+      return token;
+    }
+
+    switch (tokenData.error) {
+      case 'authorization_pending':
+        // User hasn't authorized yet — keep polling
+        break;
+      case 'slow_down':
+        // GitHub asks us to slow down
+        pollInterval += 5000;
+        break;
+      case 'expired_token':
+        throw new Error('Authentication timed out. Please try \'mk auth login\' again.');
+      case 'access_denied':
+        throw new Error('Access denied by user. Authentication cancelled.');
+      default:
+        throw new Error(`Device flow error: ${tokenData.error}`);
+    }
+  }
+
+  throw new Error('Authentication timed out. Please try \'mk auth login\' again.');
+}
+
+// ---------------------------------------------------------------------------
+// Combined: resolve or trigger login
+// ---------------------------------------------------------------------------
+
+/**
+ * Return an existing token, or run the device flow if none is available.
+ *
+ * @param {{
+ *   readStored?: () => string|null,
+ *   writeStored?: (token: string) => void,
+ *   display: (info: object) => void,
+ *   sleep?: (ms: number) => Promise<void>
+ * }} opts
+ * @returns {Promise<string>}
+ */
+export async function resolveTokenOrLogin(opts = {}) {
+  const {
+    readStored = readStoredToken,
+    writeStored = writeToken,
+    display,
+    sleep = defaultSleep
+  } = opts;
+
+  const existing = resolveToken({ readStored });
+  if (existing) return existing;
+
+  // No token — run device flow
+  return startDeviceFlow({ display, writeStored, sleep });
+}

package/src/lib/checksum.js

@@ -0,0 +1,13 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+
+/**
+ * Compute SHA-256 checksum of a file.
+ * @param {string} filePath - Absolute path to file
+ * @returns {string} Checksum string prefixed with 'sha256:'
+ */
+export function computeChecksum(filePath) {
+  const content = readFileSync(filePath);
+  const hash = createHash('sha256').update(content).digest('hex');
+  return `sha256:${hash}`;
+}

package/src/lib/config.js

@@ -0,0 +1,72 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync, chmodSync, existsSync } from 'node:fs';
+
+/**
+ * Returns the config directory for mk.
+ * XDG-compliant: ~/.config/mk on Unix/macOS, %APPDATA%/mk on Windows.
+ * @returns {string}
+ */
+export function getConfigDir() {
+  const appData = process.env.APPDATA;
+  // Reject UNC paths (\\server\share) — these could redirect token storage to attacker-controlled
+  // network shares. Fall back to the XDG path if APPDATA looks suspicious.
+  if (appData && !appData.startsWith('\\\\')) {
+    return join(appData, 'mk');
+  }
+  return join(homedir(), '.config', 'mk');
+}
+
+/**
+ * Returns the token file path.
+ * @returns {string}
+ */
+export function getTokenPath() {
+  return join(getConfigDir(), 'token');
+}
+
+/**
+ * Read the stored token from disk.
+ * @returns {string|null} Token string or null if not found.
+ */
+export function readStoredToken() {
+  const tokenPath = getTokenPath();
+  if (!existsSync(tokenPath)) {
+    return null;
+  }
+  try {
+    return readFileSync(tokenPath, 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the token to disk. Creates config dir if needed. Sets chmod 600 on Unix.
+ * @param {string} token
+ */
+export function writeToken(token) {
+  const configDir = getConfigDir();
+  const tokenPath = getTokenPath();
+  mkdirSync(configDir, { recursive: true });
+  // Write with mode 0o600 atomically — prevents TOCTOU window between write and chmod.
+  // On Windows the mode flag is ignored; home-dir ACLs provide equivalent protection.
+  writeFileSync(tokenPath, token, { encoding: 'utf8', mode: 0o600 });
+  if (process.platform !== 'win32') {
+    // Explicit chmod ensures mode is set even if umask overrides the O_CREAT mode.
+    chmodSync(tokenPath, 0o600);
+  }
+}
+
+/**
+ * Delete the stored token file.
+ * Does not throw if the file does not exist.
+ */
+export function deleteToken() {
+  const tokenPath = getTokenPath();
+  try {
+    unlinkSync(tokenPath);
+  } catch {
+    // File doesn't exist — that's fine
+  }
+}

package/src/lib/constants.js

@@ -0,0 +1,37 @@
+/**
+ * Kit subdirectories to copy/manage (relative to .claude/)
+ */
+export const KIT_SUBDIRS = ['agents', 'skills', 'workflows'];
+
+/**
+ * Manifest file name
+ */
+export const MANIFEST_FILENAME = '.mk-manifest.json';
+
+/**
+ * Files/patterns to exclude during copy
+ */
+export const COPY_FILTER_PATTERNS = [
+  '__pycache__',
+  '.pyc',
+  '.pyo',
+  'node_modules',
+  '.DS_Store',
+  'package-lock.json',
+  '.env'
+];
+
+/**
+ * Windows path length warning threshold (leave 20 chars of buffer)
+ */
+export const WINDOWS_PATH_WARN_LENGTH = 240;
+
+/**
+ * GitHub API base URL
+ */
+export const GITHUB_API = 'https://api.github.com';
+
+/**
+ * Kit repository (owner/repo)
+ */
+export const KIT_REPO = 'khanhtran148/mk-kit';