@khanhcan148/mk 0.1.24 → 0.1.26

package/bin/mk.js

@@ -27,6 +27,7 @@ program.command('update')
   .description('Update kit files to the latest version, preserving user modifications')
   .option('--force', 'Overwrite user-modified files without warning')
   .option('--global', 'Update global installation in ~/.claude/')
+  .option('-v, --verbose', 'Print per-file changes and routine warnings')
   .action((options) => updateAction(options));
 
 program.command('remove')

package/package.json

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

package/scripts/convert-agents-to-codex.js

@@ -110,6 +110,11 @@ try {
   process.exit(1);
 }
 
+// Verbose flag: MK_VERBOSE=1 enables per-agent progress lines and IAC-1 warnings.
+// When spawned by runCodexConversion, the parent passes MK_VERBOSE based on its
+// verbose option so the child inherits the same quietness setting.
+const VERBOSE = process.env.MK_VERBOSE === '1';
+
 // ---------------------------------------------------------------------------
 // IAC-1 patterns: Claude-only constructs to flag in agent bodies
 // ---------------------------------------------------------------------------
@@ -127,6 +132,7 @@ const IAC1_PATTERNS = [
  * @param {string} body  Raw Markdown body (frontmatter stripped)
  */
 function checkIac1(agentName, body) {
+  if (!VERBOSE) return;
   const lines = body.split('\n');
   for (const { pattern, label } of IAC1_PATTERNS) {
     for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
@@ -341,10 +347,12 @@ for (const mdPath of mdFiles) {
   }
 }
 
-process.stdout.write(
-  `[convert-agents-to-codex] Done. ${successCount} converted, ${errorCount} errors.\n`
-);
-process.stdout.write(`[convert-agents-to-codex] Output: ${outputDir}\n`);
+if (VERBOSE) {
+  process.stdout.write(
+    `[convert-agents-to-codex] Done. ${successCount} converted, ${errorCount} errors.\n`
+  );
+  process.stdout.write(`[convert-agents-to-codex] Output: ${outputDir}\n`);
+}
 
 if (errors.length > 0) {
   process.stderr.write(`[convert-agents-to-codex] Errors:\n${errors.join('\n')}\n`);

package/scripts/convert-hooks-to-codex.js

@@ -154,6 +154,9 @@ function buildToml() {
 export async function convertHooksToCodex(opts = {}) {
   const projectRoot = opts.projectRoot ? resolve(opts.projectRoot) : PACKAGE_ROOT;
   const outputDir = opts.outputDir ? resolve(opts.outputDir) : join(projectRoot, '.codex');
+  // verbose: caller passes explicit boolean; fallback to MK_VERBOSE env var for
+  // the case where this module is imported by a spawned child process.
+  const verbose = opts.verbose ?? process.env.MK_VERBOSE === '1';
 
   const warnings = [];
   const dropped = [];
@@ -163,7 +166,9 @@ export async function convertHooksToCodex(opts = {}) {
     const msg = `[convert-hooks-to-codex] WARNING: Dropping ${name} (${source} event has no Codex equivalent)`;
     warnings.push(msg);
     dropped.push(name);
-    process.stderr.write(msg + '\n');
+    if (verbose) {
+      process.stderr.write(msg + '\n');
+    }
   }
 
   // Count emitted hooks

package/scripts/convert-skills-to-codex.js

@@ -88,6 +88,11 @@ for (let i = 0; i < args.length; i++) {
 
 const modelMap = loadModelMap(modelMapPath);
 
+// Verbose flag: MK_VERBOSE=1 enables per-skill progress lines.
+// When spawned by runCodexConversion, the parent passes MK_VERBOSE based on its
+// verbose option so the child inherits the same quietness setting.
+const VERBOSE = process.env.MK_VERBOSE === '1';
+
 const kitRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const inputDir = inputDirArg || join(kitRoot, '.claude', 'skills');
 const outputDir = outputDirArg || join(kitRoot, '.codex', 'skills');
@@ -219,7 +224,9 @@ let errorCount = 0;
 const errors = [];
 
 function logInfo(msg) {
-  process.stderr.write(`${LOG_PREFIX} ${msg}\n`);
+  if (VERBOSE) {
+    process.stderr.write(`${LOG_PREFIX} ${msg}\n`);
+  }
 }
 
 function logError(msg) {
@@ -336,10 +343,12 @@ for (const dirent of skillDirs) {
   }
 }
 
-process.stdout.write(
-  `${LOG_PREFIX} Done. ${successCount} converted, ${errorCount} errors.\n`
-);
-process.stdout.write(`${LOG_PREFIX} Output: ${outputDir}\n`);
+if (VERBOSE) {
+  process.stdout.write(
+    `${LOG_PREFIX} Done. ${successCount} converted, ${errorCount} errors.\n`
+  );
+  process.stdout.write(`${LOG_PREFIX} Output: ${outputDir}\n`);
+}
 
 if (errors.length > 0) {
   process.stderr.write(`${LOG_PREFIX} Errors:\n${errors.join('\n')}\n`);

package/src/commands/codex.js

@@ -158,9 +158,18 @@ function isDirectory(p) {
  *                                      path can never traverse outside its parent.
  * @param {string} [options.output]   - Override for agents output dir
  * @param {string} [options.modelMap] - Path to custom model-map JSON
+ * @param {boolean} [options.verbose=true] - When false, suppresses the per-directory
+ *                                      progress lines (`Converting`, `Mirroring`,
+ *                                      `✓ codex conversion complete`) and the
+ *                                      hook-drop warning. `console.error` calls
+ *                                      stay loud unconditionally. Defaults to `true`
+ *                                      to preserve direct `mk codex` ergonomics;
+ *                                      `maybeSyncCodex` passes `false` so the codex
+ *                                      sync inherits the host run's quietness.
  * @returns {Promise<{ exitCode: number, hooksResult?: object, errors: string[] }>}
  */
 export async function runCodexConversion(options = {}) {
+  const { verbose = true } = options;
   // S1: Reject `..` segments AFTER resolve to catch encoded traversal attempts
   // (e.g. "foo/../../../etc"). A full homedir-bound would break legitimate
   // `mk codex --cwd /tmp/…` invocations, so we use the lighter ..‑segment check.
@@ -235,7 +244,7 @@ export async function runCodexConversion(options = {}) {
   }
 
   // Emit progress lines upfront (before awaiting) so the user sees intent immediately.
-  if (isDirectory(skillsDir)) {
+  if (verbose && isDirectory(skillsDir)) {
     console.log(chalk.cyan(`Converting ${skillsDir}`));
     console.log(chalk.cyan(`        → ${skillsOut}`));
   }
@@ -244,8 +253,15 @@ export async function runCodexConversion(options = {}) {
   if (options.modelMap) {
     args.push('--model-map', resolve(options.modelMap));
   }
-  console.log(chalk.cyan(`Converting ${agentsDir}`));
-  console.log(chalk.cyan(`        → ${agentsOut}`));
+  if (verbose) {
+    console.log(chalk.cyan(`Converting ${agentsDir}`));
+    console.log(chalk.cyan(`        → ${agentsOut}`));
+  }
+
+  // Propagate verbose flag to child converter processes via MK_VERBOSE env var.
+  // Child processes use { stdio: 'inherit' } so their stdout/stderr bypass the
+  // parent-level verbose gate — the env var is the only way to suppress them.
+  const childEnv = { ...process.env, MK_VERBOSE: verbose ? '1' : '0' };
 
   // Start both spawns concurrently.
   const skillsPromise = isDirectory(skillsDir)
@@ -253,7 +269,7 @@ export async function runCodexConversion(options = {}) {
         const child = spawn(
           process.execPath,
           [SKILLS_CONVERTER_SCRIPT, '--input', skillsDir, '--output', skillsOut],
-          { stdio: 'inherit' }
+          { stdio: 'inherit', env: childEnv }
         );
         child.on('close', (exitCode) => resolveExit(exitCode ?? 1));
         child.on('error', (err) => {
@@ -264,7 +280,7 @@ export async function runCodexConversion(options = {}) {
     : Promise.resolve(0);
 
   const agentsPromise = new Promise((resolveExit) => {
-    const child = spawn(process.execPath, args, { stdio: 'inherit' });
+    const child = spawn(process.execPath, args, { stdio: 'inherit', env: childEnv });
     child.on('close', (exitCode) => resolveExit(exitCode ?? 1));
     child.on('error', (err) => {
       console.error(chalk.red(`error: failed to spawn converter: ${err.message}`));
@@ -288,20 +304,24 @@ export async function runCodexConversion(options = {}) {
   // Uses mirrorDirWithRewrite so .claude/<subdir>/ refs in .md/.txt/.toml files
   // are rewritten to .codex/<subdir>/ for Codex-runtime resolution.
   if (isDirectory(workflowsDir)) {
-    console.log(chalk.cyan(`Mirroring  ${workflowsDir}`));
-    console.log(chalk.cyan(`        → ${workflowsOut}`));
+    if (verbose) {
+      console.log(chalk.cyan(`Mirroring  ${workflowsDir}`));
+      console.log(chalk.cyan(`        → ${workflowsOut}`));
+    }
     mirrorDirWithRewrite(workflowsDir, workflowsOut);
   }
 
-  const hooksResult = await convertHooksToCodex({ projectRoot, outputDir: codexRoot });
-  if (hooksResult.dropped.length > 0) {
+  const hooksResult = await convertHooksToCodex({ projectRoot, outputDir: codexRoot, verbose });
+  if (verbose && hooksResult.dropped.length > 0) {
     console.warn(
       chalk.yellow(
         `Warning: dropped ${hooksResult.dropped.length} hooks (SubagentStart/TeammateIdle/TaskCompleted have no Codex equivalent)`
       )
     );
   }
-  console.log(chalk.green('✓ codex conversion complete'));
+  if (verbose) {
+    console.log(chalk.green('✓ codex conversion complete'));
+  }
   return { exitCode: 0, hooksResult, errors };
 }
 

package/src/commands/update.js

@@ -116,15 +116,18 @@ export function hasCodexInstall(codexDir) {
  * Throws a tagged error (`.codexSyncFailure = true`) on conversion failure so
  * callers can distinguish a codex-only problem from a core update failure.
  *
- * @param {{ projectRoot: string, codexRunner: Function }} opts
+ * @param {{ projectRoot: string, codexRunner: Function, verbose?: boolean }} opts
  * @param {string}   opts.projectRoot  - Absolute path to the project root
  * @param {Function} opts.codexRunner  - DI-injectable; defaults to runCodexConversion
+ * @param {boolean}  [opts.verbose=false] - When true, emits the "Syncing .codex/ mirror…" heartbeat
  */
-export async function maybeSyncCodex({ projectRoot, codexRunner }) {
+export async function maybeSyncCodex({ projectRoot, codexRunner, verbose = false }) {
   const codexDir = join(projectRoot, '.codex');
   if (!hasCodexInstall(codexDir)) return; // silent skip — no codex install detected
-  process.stdout.write(chalk.cyan('Syncing .codex/ mirror…\n'));
-  const result = await codexRunner({ cwd: projectRoot });
+  if (verbose) {
+    process.stdout.write(chalk.cyan('Syncing .codex/ mirror…\n'));
+  }
+  const result = await codexRunner({ cwd: projectRoot, verbose });
   if (result.exitCode !== 0) {
     const err = new Error(
       'Codex sync failed after .claude/ update completed. Retry manually: `mk codex`'
@@ -163,7 +166,8 @@ async function defaultPromptUser(question) {
  *   targetDir?: string,
  *   manifestPath?: string,
  *   force?: boolean,
- *   version?: string  - Kit version to store in manifest (defaults to pkg.version when omitted)
+ *   version?: string,  - Kit version to store in manifest (defaults to pkg.version when omitted)
+ *   verbose?: boolean  - When true, threads verbose=true to copyKitFiles and mergeSettingsJson
  * }} params
  * @returns {Promise<{ updated: string[], added: string[], removed: string[], conflicts: string[], unchanged: string[], upToDate: boolean }>}
  */
@@ -173,7 +177,8 @@ export async function runUpdate(params = {}) {
     targetDir = resolveTargetDir({ global: false }),
     manifestPath = resolveManifestPath({ global: false }),
     force = false,
-    version: explicitVersion
+    version: explicitVersion,
+    verbose = false
   } = params;
 
   // Read existing manifest
@@ -187,7 +192,7 @@ export async function runUpdate(params = {}) {
   // 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 sourceFileList = copyKitFiles(sourceDir, targetDir, { dryRun: true, verbose });
   // Fix 11-12 (performance): Build a Map for O(1) lookups in applyCopy.
   // 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).
@@ -241,7 +246,7 @@ export async function runUpdate(params = {}) {
     // 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);
+    mergeSettingsJson(sourceDir, targetDir, { verbose });
     // 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.
@@ -369,7 +374,7 @@ export async function runUpdate(params = {}) {
   }
 
   // Merge settings.json hooks — additive merge, never overwrites user keys
-  mergeSettingsJson(sourceDir, targetDir);
+  mergeSettingsJson(sourceDir, targetDir, { verbose });
 
   // Update manifest with new file map.
   // Use explicitVersion when provided (e.g. release.version from updateAction);
@@ -393,7 +398,7 @@ export async function runUpdate(params = {}) {
  * and applies a three-way diff. Falls back to the main-branch tarball if no
  * release information is available.
  *
- * @param {{ force: boolean, global: boolean }} options
+ * @param {{ force: boolean, global: boolean, verbose?: boolean }} options
  * @param {object} [deps] - Injected dependencies (for testing)
  */
 export async function updateAction(options = {}, deps = {}) {
@@ -409,7 +414,8 @@ export async function updateAction(options = {}, deps = {}) {
     // Injectable for tests — allows overriding resolved paths without touching CWD
     manifestPath: injectedManifestPath,
     targetDir: injectedTargetDir,
-    runCodexConversion: codexRunner = runCodexConversion
+    runCodexConversion: codexRunner = runCodexConversion,
+    runUpdate: runUpdateImpl = runUpdate
   } = deps;
 
   // Read local package version (used as fallback when manifest has no version)
@@ -425,6 +431,10 @@ export async function updateAction(options = {}, deps = {}) {
 
   let tempDir = null;
   try {
+    // MK_VERBOSE only honours the literal '1' to avoid CI surprises (e.g. 'true', 'false', '0').
+    // SECURITY: strict literal only — do not relax to truthy; coercion silently enables CI-break behaviour.
+    const verbose = options.verbose === true || process.env.MK_VERBOSE === '1';
+
     process.stdout.write('Authenticating with GitHub...\n');
     const token = await resolveAndLogin({
       readStored: readToken,
@@ -471,8 +481,9 @@ export async function updateAction(options = {}, deps = {}) {
         // 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);
-        await maybeSyncCodex({ projectRoot, codexRunner });
+        // Note: maybeSyncCodex is intentionally NOT called here — running codex conversion
+        // on every no-op invocation wastes wall-clock time with no benefit (PR #132 reversal).
+        mergeSettingsJson(resolveSourceDir(), targetDir, { verbose });
         return;
       }
 
@@ -511,7 +522,7 @@ export async function updateAction(options = {}, deps = {}) {
     // Pass releaseVersion so runUpdate stores it in the manifest.
     // When falling back to main branch (no release), releaseVersion is undefined and
     // runUpdate falls back to pkg.version — which is the correct behaviour for that path.
-    const result = await runUpdate({ sourceDir, targetDir, manifestPath, force: options.force, version: releaseVersion });
+    const result = await runUpdateImpl({ sourceDir, targetDir, manifestPath, force: options.force, version: releaseVersion, verbose });
 
     if (result.upToDate) {
       process.stdout.write(chalk.green('Already up to date.\n'));
@@ -524,26 +535,35 @@ 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 (verbose) {
+          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 (verbose) {
+          for (const f of result.orphans) {
+            process.stdout.write(`  Cleaned: ${f}\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`);
+        if (verbose) {
+          for (const f of result.conflicts) {
+            process.stdout.write(`  ${f}\n`);
+          }
         }
       }
+      if (!verbose && (result.removed.length > 0 || (result.orphans?.length > 0) || result.conflicts.length > 0)) {
+        process.stdout.write(chalk.dim('(re-run with --verbose to see per-file changes)\n'));
+      }
     }
-    await maybeSyncCodex({ projectRoot, codexRunner });
+    await maybeSyncCodex({ projectRoot, codexRunner, verbose });
   } catch (err) {
     // S3+S4: scrub tokens and absolute paths from error messages before surfacing
     let storedToken = null;

package/src/lib/copy.js

@@ -95,14 +95,14 @@ export function collectDiskFiles(targetDir) {
  *
  * @param {string} sourceDir - Absolute path to source .claude/
  * @param {string} targetDir - Absolute path to target .claude/
- * @param {{ dryRun: boolean }} options
+ * @param {{ dryRun: boolean, verbose: boolean }} options
  * @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.
  */
 export function copyKitFiles(sourceDir, targetDir, options = {}) {
-  const { dryRun = false } = options;
+  const { dryRun = false, verbose = false } = options;
   const fileList = [];
   const warnings = [];
 
@@ -136,9 +136,12 @@ export function copyKitFiles(sourceDir, targetDir, options = {}) {
     }
   }
 
-  // Print warnings
-  for (const w of warnings) {
-    process.stderr.write(w + '\n');
+  // Print warnings: always loud on real installs; suppressed only when doing a dry-run probe
+  // without verbose (the probe is internal and operators never see it).
+  if (!dryRun || verbose) {
+    for (const w of warnings) {
+      process.stderr.write(w + '\n');
+    }
   }
 
   if (dryRun) {
@@ -199,18 +202,21 @@ function isInSibling(siblingHooks, event, matcher) {
 
 /**
  * Filter kitEntries removing any whose event+matcher already exists in siblingHooks.
- * Emits a stderr info message per skipped entry.
+ * Emits a stderr info message per skipped entry (suppressed when verbose=false).
  * @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
+ * @param {boolean} [verbose] - When false, suppresses the skipped-hook stderr message
  * @returns {object[]} Entries not present in sibling
  */
-function dedupeAgainstSibling(kitEntries, siblingHooks, event) {
+function dedupeAgainstSibling(kitEntries, siblingHooks, event, verbose = false) {
   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`);
+      if (verbose) {
+        process.stderr.write(`mk: hook ${event}[${m}] skipped (exists in settings.local.json)\n`);
+      }
       return false;
     }
     return true;
@@ -229,11 +235,11 @@ function dedupeAgainstSibling(kitEntries, siblingHooks, event) {
  *
  * @param {string} sourceDir - Absolute path to source .claude/
  * @param {string} targetDir - Absolute path to target .claude/
- * @param {{ dryRun: boolean }} options
+ * @param {{ dryRun: boolean, verbose: boolean }} options
  * @returns {{ action: 'created'|'merged'|'skipped', merged?: string[], backup?: string }}
  */
 export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
-  const { dryRun = false } = options;
+  const { dryRun = false, verbose = false } = options;
   const srcPath = join(sourceDir, 'settings.json');
   const destPath = join(targetDir, 'settings.json');
 
@@ -266,7 +272,7 @@ export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
       const hooksOnly = {};
       if (kitSettings.hooks) {
         for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
-          const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event);
+          const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event, verbose);
           if (deduped.length > 0) hooksOnly[event] = deduped;
         }
       }
@@ -295,7 +301,7 @@ export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
     if (!userSettings.hooks) userSettings.hooks = {};
     for (const [event, kitEntries] of Object.entries(kitSettings.hooks)) {
       if (!userSettings.hooks[event]) {
-        const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event);
+        const deduped = dedupeAgainstSibling(kitEntries, siblingHooks, event, verbose);
         if (deduped.length > 0) {
           userSettings.hooks[event] = deduped;
           merged.push(event);
@@ -305,7 +311,9 @@ export function mergeSettingsJson(sourceDir, targetDir, options = {}) {
           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`);
+            if (verbose) {
+              process.stderr.write(`mk: hook ${event}[${kitMatcher}] skipped (exists in settings.local.json)\n`);
+            }
             continue;
           }
           const idx = userSettings.hooks[event].findIndex(