@khanhcan148/mk 0.1.17 → 0.1.19

package/README.md

@@ -88,7 +88,7 @@ cp -r .claude ~/.claude/
 
 ```
 ├── .claude/
-│   ├── agents/      # 32 agents (5 primary + 27 utility: implementers, quality, docs, specialized, concerns)
+│   ├── agents/      # 36 agents (5 primary + 31 utility: implementers, quality, docs, specialized, concerns, brainstorm critics)
 │   ├── 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.)

package/package.json

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

package/src/commands/auth.js

@@ -138,6 +138,17 @@ export async function statusAction(deps = {}) {
     process.stdout.write(chalk.green('Repo access: granted\n'));
   } else {
     process.stdout.write(chalk.red('Repo access: denied\n'));
-    process.stdout.write('Contact the repository owner for collaborator access.\n');
+    const hasRepoScope = access.scopes?.some((s) => s === 'repo');
+    if (access.status === 404 && access.scopes && !hasRepoScope) {
+      // 404 with no 'repo' scope usually means the token can't see the private
+      // KIT_REPO — re-authenticating picks up the new default scope.
+      const current = access.scopes.length ? access.scopes.join(', ') : 'none';
+      process.stdout.write(
+        `Token is missing the 'repo' scope (current scopes: ${current}).\n` +
+        "Run 'mk auth logout && mk auth login' to re-authenticate with the required scope.\n"
+      );
+    } else {
+      process.stdout.write('Contact the repository owner for collaborator access.\n');
+    }
   }
 }

package/src/commands/init.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { copyKitFiles, mergeSettingsJson } from '../lib/copy.js';
 import { writeManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
+import { pLimit, DEFAULT_CONCURRENCY_CAP } from '../lib/concurrency.js';
 import { resolveSourceDir, resolveTargetDir, resolveManifestPath } from '../lib/paths.js';
 import { MANIFEST_FILENAME } from '../lib/constants.js';
 import { resolveTokenOrLogin } from '../lib/auth.js';
@@ -59,13 +60,18 @@ export async function runInit(params = {}) {
     'utf8'
   ));
 
-  const files = {};
-  for (const entry of fileList) {
-    if (existsSync(entry.absolutePath)) {
-      const checksum = computeChecksum(entry.absolutePath);
-      files[entry.relativePath] = { checksum, size: entry.size };
-    }
-  }
+  // Compute checksums in bounded parallel — pLimit(cap=16) keeps concurrent
+  // file descriptors well under macOS default ulimit 256 so large installs
+  // never hit EMFILE. Output order matches input (see pLimit contract).
+  const existingEntries = fileList.filter(entry => existsSync(entry.absolutePath));
+  const fileChecksumEntries = await pLimit(
+    existingEntries.map((entry) => async () => {
+      const checksum = await computeChecksum(entry.absolutePath);
+      return [entry.relativePath, { checksum, size: entry.size }];
+    }),
+    DEFAULT_CONCURRENCY_CAP
+  );
+  const files = Object.fromEntries(fileChecksumEntries);
 
   // Write manifest.
   // Use explicitVersion when provided (e.g. release.version from initAction);

package/src/commands/update.js

@@ -5,6 +5,7 @@ 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 { pLimit, DEFAULT_CONCURRENCY_CAP } from '../lib/concurrency.js';
 import { copyKitFiles, collectDiskFiles, mergeSettingsJson } from '../lib/copy.js';
 import { resolveSourceDir, resolveTargetDir, resolveManifestPath, deriveProjectRoot, assertSafePath } from '../lib/paths.js';
 import { resolveTokenOrLogin } from '../lib/auth.js';
@@ -31,7 +32,7 @@ import { isEmptyDir } from '../lib/fs-utils.js';
  * @param {string} str
  * @returns {string}
  */
-function stripTerminalEscapes(str) {
+export function stripTerminalEscapes(str) {
   return str
     .replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')         // CSI sequences
     .replace(/\x1b\].*?(\x07|\x1b\\)/gs, '')         // OSC sequences (dotAll for multiline)
@@ -97,14 +98,19 @@ export async function runUpdate(params = {}) {
   // Previously sourceFileList.find() in applyCopy was O(n) per call, causing O(n²)
   // behaviour when many files need updating. The Map is built once in O(n).
   const sourceFileMap = new Map(sourceFileList.map(e => [e.relativePath, e]));
-  const sourceFiles = {};
-  for (const entry of sourceFileList) {
-    const checksum = computeChecksum(entry.sourceAbsPath);
-    sourceFiles[entry.relativePath] = { checksum, size: entry.size };
-  }
+  // Compute source checksums under a bounded pool (M3) — see concurrency.js.
+  const sourceChecksumEntries = await pLimit(
+    sourceFileList.map((entry) => async () => {
+      const checksum = await computeChecksum(entry.sourceAbsPath);
+      return [entry.relativePath, { checksum, size: entry.size }];
+    }),
+    DEFAULT_CONCURRENCY_CAP
+  );
+  const sourceFiles = Object.fromEntries(sourceChecksumEntries);
 
-  // Get disk checksums for files currently in manifest
-  const diskChecksums = {};
+  // Get disk checksums for files currently in manifest.
+  // Filter to only existing safe paths first, then parallelise checksum I/O.
+  const safeManifestPaths = [];
   for (const relPath of Object.keys(manifest.files)) {
     // relPath is like '.claude/agents/foo.md' — relative to project root
     const absPath = join(projectRoot, relPath);
@@ -116,9 +122,14 @@ export async function runUpdate(params = {}) {
       continue;
     }
     if (existsSync(absPath)) {
-      diskChecksums[relPath] = computeChecksum(absPath);
+      safeManifestPaths.push({ relPath, absPath });
     }
   }
+  const diskChecksumEntries = await pLimit(
+    safeManifestPaths.map(({ relPath, absPath }) => async () => [relPath, await computeChecksum(absPath)]),
+    DEFAULT_CONCURRENCY_CAP
+  );
+  const diskChecksums = Object.fromEntries(diskChecksumEntries);
 
   // Three-way diff
   const diff = diffManifest(manifest, sourceFiles, diskChecksums);
@@ -209,7 +220,9 @@ export async function runUpdate(params = {}) {
   const orphanParentDirs = new Set();
   for (const relPath of diskFiles) {
     if (relPath in sourceFiles) continue; // present in new source — keep
-    const absPath = join(projectRoot, relPath);
+    // M7: pre-resolve so assertSafePath checks the canonical absolute path
+    // (not a `..`-relative traversal that slipped through the manifest).
+    const absPath = resolve(join(projectRoot, relPath));
     try {
       assertSafePath(absPath, claudeRoot, `orphan "${relPath}"`);
     } catch (err) {
@@ -220,8 +233,14 @@ export async function runUpdate(params = {}) {
       unlinkSync(absPath);
       orphans.push(relPath);
       orphanParentDirs.add(dirname(absPath));
-    } catch {
-      // Already missing — skip
+    } catch (err) {
+      // M7: ENOENT is benign (already missing). Anything else — EACCES, EPERM,
+      // EBUSY — is surfaced so operators can react instead of losing signal.
+      if (err && err.code !== 'ENOENT') {
+        // Use err.code only — err.message on fs errors embeds the absolute path, which
+        // we already redact elsewhere (H4, H6). Fall through to a generic label.
+        process.stderr.write(chalk.yellow(`  warning: orphan delete failed for ${relPath}: ${err.code || 'unknown error'}\n`));
+      }
     }
   }
 

package/src/lib/auth.js

@@ -82,8 +82,15 @@ export async function validateToken(token) {
 /**
  * Check whether the token has access to the kit repository.
  *
+ * Returns the HTTP status and any scopes reported via the `x-oauth-scopes`
+ * response header so callers can disambiguate common failure modes:
+ *   - 404 + no 'repo' scope  → token lacks scope (most common for a private KIT_REPO)
+ *   - 404 + has 'repo' scope → authenticated account is not a collaborator
+ *   - 403                    → SSO or rate-limit block
+ *   - 0                      → network error
+ *
  * @param {string} token
- * @returns {Promise<{ accessible: boolean }>}
+ * @returns {Promise<{ accessible: boolean, status: number, scopes: string[] }>}
  */
 export async function checkRepoAccess(token) {
   try {
@@ -93,12 +100,17 @@ export async function checkRepoAccess(token) {
         Accept: 'application/vnd.github.v3+json'
       }
     });
-    return { accessible: res.ok };
+    return { accessible: res.ok, status: res.status, scopes: parseScopes(res) };
   } catch {
-    return { accessible: false };
+    return { accessible: false, status: 0, scopes: [] };
   }
 }
 
+function parseScopes(res) {
+  const raw = res.headers?.get?.('x-oauth-scopes') || '';
+  return raw.split(',').map((s) => s.trim()).filter(Boolean);
+}
+
 // ---------------------------------------------------------------------------
 // OAuth Device Flow
 // ---------------------------------------------------------------------------
@@ -127,9 +139,15 @@ export async function startDeviceFlow(opts = {}) {
       'Content-Type': 'application/x-www-form-urlencoded',
       Accept: 'application/json'
     },
-    // Empty scope sufficient for public repos (5000 req/hr). Set MK_OAUTH_SCOPE=repo for private forks.
+    // KIT_REPO is private, so 'repo' scope is required to read it. Default to 'repo'.
+    // Override with MK_OAUTH_SCOPE for public forks (e.g. MK_OAUTH_SCOPE='' for no scope,
+    // or MK_OAUTH_SCOPE='public_repo' for public-only access).
+    // `??` (not `||`) so an explicit empty string is honored as an opt-out.
     // Use URLSearchParams to prevent parameter injection via env var containing '&' chars.
-    body: new URLSearchParams({ client_id: GITHUB_CLIENT_ID, scope: process.env.MK_OAUTH_SCOPE || '' }).toString()
+    body: new URLSearchParams({
+      client_id: GITHUB_CLIENT_ID,
+      scope: process.env.MK_OAUTH_SCOPE ?? 'repo'
+    }).toString()
   });
 
   if (!codeRes.ok) {
@@ -155,7 +173,13 @@ export async function startDeviceFlow(opts = {}) {
         '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`
+      // Use URLSearchParams to prevent parameter injection if device_code ever contains '&' chars
+      // (mirrors the same safe pattern used in Step 1 above for the initial device-code request).
+      body: new URLSearchParams({
+        client_id: GITHUB_CLIENT_ID,
+        device_code,
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
+      }).toString()
     });
 
     const tokenData = await tokenRes.json();

package/src/lib/checksum.js

@@ -1,13 +1,28 @@
 import { createHash } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { createReadStream } from 'node:fs';
 
 /**
- * Compute SHA-256 checksum of a file.
+ * Compute SHA-256 checksum of a file asynchronously using a streaming pipeline.
+ * Using createReadStream avoids loading the entire file into memory, which is
+ * important for large binary assets in the kit. Promise.all callers can parallelise
+ * multiple checksums without blocking the event loop.
+ *
  * @param {string} filePath - Absolute path to file
- * @returns {string} Checksum string prefixed with 'sha256:'
+ * @returns {Promise<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}`;
+  return new Promise((resolve, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(filePath);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(`sha256:${hash.digest('hex')}`));
+    // H6: wrap the raw fs.Error so the absolute path in err.path never reaches
+    // user stderr while preserving the causal chain for debuggers. The top-level
+    // message is the errno code (callers branch on err.code; err.cause retains
+    // the original for stack-trace inspection when needed).
+    stream.on('error', (e) => {
+      const code = e && e.code ? e.code : 'checksum read failed';
+      reject(new Error(code, e ? { cause: e } : undefined));
+    });
+  });
 }

package/src/lib/concurrency.js

@@ -0,0 +1,36 @@
+/**
+ * Default in-flight worker cap for `pLimit` over file-descriptor-bound tasks.
+ *
+ * 16 is 8× typical disk parallelism and well under macOS default `ulimit -n 256`.
+ * Chosen empirically — higher values don't meaningfully speed up SHA-256 of
+ * kit-sized files, and lower values serialise too aggressively on SSD.
+ */
+export const DEFAULT_CONCURRENCY_CAP = 16;
+
+/**
+ * Bounded-concurrency helper for fan-out over async tasks.
+ *
+ * M3 — `Promise.all(items.map(computeChecksum))` opens N file descriptors at
+ * once. On installs with hundreds of files this blows past the default
+ * `ulimit -n` (256 on macOS) and causes EMFILE. `pLimit` caps the in-flight
+ * worker pool; results preserve input order via explicit index assignment.
+ *
+ * @template T
+ * @param {Array<() => Promise<T>>} tasks  Array of thunks. Each thunk is
+ *   invoked at most once by exactly one worker.
+ * @param {number} cap  Max concurrent workers (>=1).
+ * @returns {Promise<T[]>}  Results indexed to match `tasks`.
+ */
+export async function pLimit(tasks, cap) {
+  const results = new Array(tasks.length);
+  let next = 0;
+  const workerCount = Math.max(1, Math.min(cap, tasks.length));
+  const workers = Array.from({ length: workerCount }, async () => {
+    while (next < tasks.length) {
+      const idx = next++;
+      results[idx] = await tasks[idx]();
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}

package/src/lib/copy.js

@@ -81,6 +81,14 @@ export function collectDiskFiles(targetDir) {
   return results;
 }
 
+/**
+ * @typedef {Object} FileEntry
+ * @property {string} relativePath - Path relative to the target .claude/ (POSIX separators, e.g. ".claude/agents/foo.md")
+ * @property {string} absolutePath - Destination absolute path under targetDir (where the file is copied to)
+ * @property {string} sourceAbsPath - Source absolute path under sourceDir (where the file is copied from)
+ * @property {number} size - File size in bytes, captured at copy time
+ */
+
 /**
  * Copy kit files from sourceDir (.claude/) to targetDir (.claude/).
  * Only copies KIT_SUBDIRS (agents/, skills/, workflows/).
@@ -88,7 +96,7 @@ export function collectDiskFiles(targetDir) {
  * @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 }>}
+ * @returns {FileEntry[]}
  * @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.

package/src/lib/download.js

@@ -39,6 +39,24 @@ export function assertGitHubHostname(url) {
   } catch {
     throw new Error(`SSRF guard: invalid URL "${url}"`);
   }
+  // H9/H10: block non-TLS schemes. Plain http:// to github.com can be MITM-redirected,
+  // and the kit download path has no reason to accept anything but https.
+  if (parsed.protocol !== 'https:') {
+    // Truncate to guard against log injection via crafted long / newline-containing schemes.
+    const safeScheme = String(parsed.protocol).slice(0, 20);
+    throw new Error(
+      `SSRF guard: scheme "${safeScheme}" is not allowed. ` +
+      `Only https: is permitted for kit downloads.`
+    );
+  }
+  // Block userinfo-prefixed URLs (user:pass@host) — they can mask the true
+  // hostname in server-side url parsers or confuse logging/auditing.
+  if (parsed.username || parsed.password) {
+    throw new Error(
+      `SSRF guard: userinfo-prefixed URL is not allowed. ` +
+      `Credentials in the URL (user:pass@host) are rejected for kit downloads.`
+    );
+  }
   const { hostname } = parsed;
   if (!ALLOWED_HOSTS.has(hostname)) {
     throw new Error(