@khanhcan148/mk 0.1.31 → 0.1.33

package/README.md

@@ -39,6 +39,9 @@ mk update            Update kit files (preserves your edits by default); auto-sy
 mk update --force    Update and overwrite user-modified files
 mk codex             Mirror .claude/ to .codex/ for OpenAI Codex CLI (see docs/codex/COMMAND.md)
 mk codex --cwd DIR   Convert a project at a different path
+mk env               List all MK_* environment variables grouped by scope
+mk env <NAME>        Show full details for a single variable (scope, type, default, current value)
+mk env --format json Output all variables as JSON
 mk remove            Remove all kit files tracked by manifest
 mk --version         Show installed CLI version
 mk --help            Show help
@@ -91,7 +94,7 @@ cp -r .claude ~/.claude/
 ```
 ├── .claude/
 │   ├── agents/      # 36 agents (5 primary + 31 utility: implementers, quality, docs, specialized, concerns, brainstorm critics)
-│   ├── skills/      # 65 skill packages (SKILL.md + scripts/references/assets)
+│   ├── skills/      # 62 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.)
 │   └── workflows/   # Development protocols
@@ -240,6 +243,7 @@ python .claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-fold
 | [Product Domain Glossary](docs/product-domain-glossary.md) | Core domain concepts, terminology, and ecosystem definitions |
 | [Quick Reference](docs/quick-reference.md) | Common commands and quick lookup |
 | [Common Workflows](docs/common-workflows.md) | Practical workflow examples |
+| [Environment Variables](.claude/env-vars.md) | All MK_* env vars with type, default, and description; run `mk env` for live values, or `mk env --markdown` to regenerate this table |
 
 ## Core Principles
 

package/bin/mk.js

@@ -8,6 +8,7 @@ import { updateAction } from '../src/commands/update.js';
 import { removeAction } from '../src/commands/remove.js';
 import { loginAction, logoutAction, statusAction } from '../src/commands/auth.js';
 import { codexAction } from '../src/commands/codex.js';
+import { envAction } from '../src/commands/env.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -60,4 +61,10 @@ auth.command('status')
   .description('Show current authentication status')
   .action(() => statusAction());
 
+program.command('env [name]')
+  .description('List or describe MK_* environment variables')
+  .option('--format <fmt>', 'Output format: text (default) or json')
+  .option('--markdown', 'Emit the full env-vars table as markdown (same as .claude/env-vars.md)')
+  .action((name, options) => envAction(name, options));
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "test": "node --test test/lib/*.test.js test/commands/*.test.js test/scripts/*.test.js test/integration/*.test.js test/characterization/*.characterization.test.js .claude/hooks/tests/*.test.cjs",
     "lint": "node --check src/**/*.js bin/**/*.js 2>/dev/null",
     "selftest": "python3 .claude/skills/mk-selftest/scripts/validate_kit.py",
+    "gen:env-docs": "node scripts/gen-env-docs.js",
     "codex:convert": "node bin/mk.js codex",
     "codex:convert-and-diff": "node scripts/codex-diff-check.js"
   },

package/scripts/bench-privacy-block.cjs

@@ -0,0 +1,31 @@
+'use strict';
+process.env.NODE_TEST_CONTEXT = '1';
+const { isSensitive } = require('../.claude/hooks/privacy-block.cjs');
+
+const cases = [
+  ['.env', ''],
+  ['.env.example', ''],
+  ['server.pem', ''],
+  ['/home/user/.ssh/id_rsa', ''],
+  ['token-budget-protocol.md', ''],
+  ['secrets.json', ''],
+  ['tokenize.md', ''],
+  ['api-token-cache.test.ts', ''],
+  ['../secrets', 'Bash'],
+  ['access_key', 'Bash'],
+];
+
+const ITER = 10_000;
+// Warmup
+for (let i = 0; i < 1000; i++) for (const [f, t] of cases) isSensitive(f, t);
+// Measure
+const t0 = process.hrtime.bigint();
+for (let i = 0; i < ITER; i++) for (const [f, t] of cases) isSensitive(f, t);
+const t1 = process.hrtime.bigint();
+const totalNs = Number(t1 - t0);
+const perCallUs = totalNs / (ITER * cases.length) / 1000;
+console.log(`Calls: ${ITER * cases.length}`);
+console.log(`Total: ${(totalNs / 1e6).toFixed(2)}ms`);
+console.log(`Per call (avg): ${perCallUs.toFixed(3)}μs`);
+console.log(`Budget: <5000μs (5ms) per call`);
+console.log(perCallUs < 5000 ? 'PASS: within latency budget' : 'FAIL: exceeds 5ms budget');

package/scripts/gen-env-docs.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * gen-env-docs.js — Generate .claude/env-vars.md from the env registry.
+ *
+ * Usage: node scripts/gen-env-docs.js
+ * npm script: npm run gen:env-docs
+ *
+ * Output is deterministic: entries sorted by scope then name.
+ *
+ * Output lives under .claude/ because that is the only directory shipped to
+ * user projects by `mk init`/`mk update` (the GitHub tarball extractor filters
+ * to paths containing `.claude/`). Anything under `docs/` is repo-only and
+ * never reaches users — see src/lib/download.js TarExtractor.
+ *
+ * The markdown-building logic is exported as `renderMarkdown(entries)` so the
+ * CLI can serve `mk env --markdown` from the same source — no static-file drift.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { ENTRIES } from '../src/lib/env-registry.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = resolve(__dirname, '..');
+const OUT_FILE = resolve(KIT_ROOT, '.claude', 'env-vars.md');
+
+// ---------------------------------------------------------------------------
+// Scope labels (single source of truth for grouping)
+// ---------------------------------------------------------------------------
+
+export const SCOPE_LABELS = {
+  'sql-guard': 'SQL Guard',
+  vault: 'Vault Knowledge',
+  cli: 'CLI',
+  auth: 'Auth',
+  team: 'Team Mode',
+  codex: 'Codex',
+};
+
+export function scopeLabel(scope) {
+  return SCOPE_LABELS[scope] ?? scope;
+}
+
+// ---------------------------------------------------------------------------
+// renderMarkdown — pure function. Used by both the file writer below AND
+// by `mk env --markdown` (src/commands/env.js).
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the env-vars registry as a markdown document.
+ * @param {ReadonlyArray<object>} entries — the env-registry ENTRIES array
+ * @returns {string} markdown content (newline-terminated)
+ */
+export function renderMarkdown(entries) {
+  const sorted = [...entries].sort((a, b) => {
+    if (a.scope < b.scope) return -1;
+    if (a.scope > b.scope) return 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+
+  const groups = new Map();
+  for (const entry of sorted) {
+    if (!groups.has(entry.scope)) groups.set(entry.scope, []);
+    groups.get(entry.scope).push(entry);
+  }
+
+  const lines = [];
+  lines.push('# MK_* Environment Variables');
+  lines.push('');
+  lines.push(
+    '> Auto-generated by `npm run gen:env-docs` (or `mk env --markdown`). Do not edit manually.'
+  );
+  lines.push('');
+  lines.push(
+    'All `MK_*` environment variables recognized by the kit. ' +
+    'Run `mk env` for an interactive overview, or `mk env <NAME>` for details on a single variable.'
+  );
+  lines.push('');
+
+  for (const [scope, scopeEntries] of groups) {
+    lines.push(`## ${scopeLabel(scope)}`);
+    lines.push('');
+    lines.push('| Name | Type | Default | Description |');
+    lines.push('|------|------|---------|-------------|');
+
+    for (const entry of scopeEntries) {
+      const def = entry.default !== undefined ? `\`${entry.default}\`` : '—';
+      const desc = entry.description.replace(/\|/g, '\\|');
+      lines.push(`| \`${entry.name}\` | ${entry.type} | ${def} | ${desc} |`);
+    }
+
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('');
+  lines.push(`_${entries.length} variables documented. Run \`mk env\` for live values._`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point: write to disk
+// ---------------------------------------------------------------------------
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const content = renderMarkdown(ENTRIES);
+  writeFileSync(OUT_FILE, content, 'utf8');
+  process.stdout.write(`Written: .claude/env-vars.md (${ENTRIES.length} entries)\n`);
+}

package/src/commands/env.js

@@ -0,0 +1,178 @@
+import { ENTRIES, findByName } from '../lib/env-registry.js';
+import { renderMarkdown } from '../../scripts/gen-env-docs.js';
+
+// ---------------------------------------------------------------------------
+// Scope display labels
+// ---------------------------------------------------------------------------
+
+const SCOPE_LABELS = {
+  'sql-guard': 'SQL Guard',
+  vault: 'Vault Knowledge',
+  cli: 'CLI',
+  auth: 'Auth',
+  team: 'Team Mode',
+  codex: 'Codex',
+};
+
+function scopeLabel(scope) {
+  return SCOPE_LABELS[scope] ?? scope;
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the current runtime value of an env var, or '(unset)'.
+ * If the entry has { secret: true }, redact the value.
+ *
+ * @param {object} entry
+ * @returns {string}
+ */
+function currentValue(entry) {
+  const raw = process.env[entry.name];
+  if (raw === undefined) return '(unset)';
+  if (entry.secret) return '(set — redacted)';
+  return raw;
+}
+
+/**
+ * Format a default value for display.
+ *
+ * @param {string|undefined} def
+ * @param {string} description
+ * @returns {string}
+ */
+function displayDefault(def) {
+  if (def === undefined) return '(none)';
+  return def;
+}
+
+// Column widths for list mode
+const COL_NAME = 32;
+const COL_VALUE = 16;
+
+function padRight(str, width) {
+  return str.length >= width ? str : str + ' '.repeat(width - str.length);
+}
+
+// ---------------------------------------------------------------------------
+// List mode — grouped by scope
+// ---------------------------------------------------------------------------
+
+function listMode(format) {
+  // Group entries by scope, preserving insertion order of first occurrence
+  const groups = new Map();
+  for (const entry of ENTRIES) {
+    if (!groups.has(entry.scope)) groups.set(entry.scope, []);
+    groups.get(entry.scope).push(entry);
+  }
+
+  if (format === 'json') {
+    const enriched = ENTRIES.map((e) => ({ ...e, current: currentValue(e) }));
+    process.stdout.write(JSON.stringify({ entries: enriched }, null, 2) + '\n');
+    return;
+  }
+
+  // Text mode — sorted scopes for deterministic output
+  const sortedScopes = [...groups.keys()].sort();
+
+  for (const scope of sortedScopes) {
+    const entries = groups.get(scope);
+    process.stdout.write(`${scopeLabel(scope)}\n`);
+
+    for (const entry of entries) {
+      const namePad = padRight(entry.name, COL_NAME);
+      const val = currentValue(entry);
+      const valPad = padRight(val, COL_VALUE);
+      const firstLine = `  ${namePad} ${valPad} ${entry.description}\n`;
+      process.stdout.write(firstLine);
+
+      // Show default on second line if there is one
+      if (entry.default !== undefined) {
+        const indent = ' '.repeat(2 + COL_NAME + 1 + COL_VALUE + 1);
+        process.stdout.write(`${indent}Default: ${entry.default}\n`);
+      }
+    }
+    process.stdout.write('\n');
+  }
+
+  const scopeCount = sortedScopes.length;
+  process.stdout.write(`Run \`mk env <NAME>\` for full details on a single variable.\n`);
+  process.stdout.write(`${ENTRIES.length} variables across ${scopeCount} scope${scopeCount === 1 ? '' : 's'}.\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Detail mode — single entry
+// ---------------------------------------------------------------------------
+
+function detailMode(name) {
+  const entry = findByName(name);
+  if (!entry) {
+    process.stderr.write(`Unknown env var: ${name}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const val = currentValue(entry);
+  const def = entry.default !== undefined
+    ? entry.default
+    : '(none)';
+
+  process.stdout.write(`${entry.name}\n\n`);
+  process.stdout.write(`  Scope:       ${entry.scope}\n`);
+  process.stdout.write(`  Type:        ${entry.type}\n`);
+  process.stdout.write(`  Applies to:  ${entry.applies_to}\n`);
+  process.stdout.write(`  Default:     ${def}\n`);
+  process.stdout.write(`  Current:     ${val}\n`);
+  if (entry.since) {
+    process.stdout.write(`  Since:       ${entry.since}\n`);
+  }
+  process.stdout.write(`\n  ${entry.description}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Detail mode with JSON format
+// ---------------------------------------------------------------------------
+
+function detailModeJson(name) {
+  const entry = findByName(name);
+  if (!entry) {
+    process.stderr.write(`Unknown env var: ${name}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(JSON.stringify({ entries: [{ ...entry, current: currentValue(entry) }] }, null, 2) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// envAction — exported for bin/mk.js and tests
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle 'mk env [name]'.
+ *
+ * @param {string|undefined} name  - Optional env var name for detail mode
+ * @param {{ format?: string }} options
+ */
+export function envAction(name, options = {}) {
+  const format = options.format ?? 'text';
+
+  // --markdown emits the same markdown that `npm run gen:env-docs` writes to disk.
+  // Useful for piping to a file in a user project: `mk env --markdown > ENV.md`.
+  // List mode only — ignores any name argument (markdown is always the full table).
+  if (options.markdown) {
+    process.stdout.write(renderMarkdown(ENTRIES));
+    return;
+  }
+
+  if (name) {
+    if (format === 'json') {
+      detailModeJson(name);
+    } else {
+      detailMode(name);
+    }
+  } else {
+    listMode(format);
+  }
+}

package/src/lib/env-registry.js

@@ -0,0 +1,159 @@
+/**
+ * Central registry of all MK_* environment variables recognized by the kit.
+ *
+ * Each entry is frozen and the array itself is frozen.
+ * Consumers: `mk env` CLI subcommand, gen-env-docs.js, selftest drift detector.
+ *
+ * Deliberate omissions:
+ * - MK_VAULT_AUDIT_FLOOR and MK_VAULT_RELAXED are *forbidden* vars (validators_vault.py
+ *   actively rejects any kit file that references them). Documenting them as supported
+ *   configuration would be misleading.
+ * - MK_COMMAND_RE, MK_FM_SCHEMA_*, MK_INIT_RE, MK_PLAN_SKILL_MD, MK_SKILLS, MK_TIER are
+ *   Python module-level constants in selftest scripts, not environment variables.
+ *
+ * If a var is secret-like (e.g. MK_*_TOKEN, MK_*_KEY, MK_*_SECRET) it should carry
+ * { secret: true } and `mk env` will redact its current value. None of the current
+ * vars are secret.
+ */
+
+const _RAW = [
+  {
+    name: 'MK_CACHE_DIR',
+    scope: 'vault',
+    default: undefined,
+    description:
+      'Override the cache directory used by vault_probe.py. ' +
+      'Resolution order: MK_CACHE_DIR → $XDG_CACHE_HOME/mk → ~/.cache/mk → OS tempdir.',
+    type: 'path',
+    applies_to: 'skill',
+    since: '0.1.21',
+  },
+  {
+    name: 'MK_FORCE_NO_TOOL_DIR',
+    scope: 'codex',
+    default: undefined,
+    description:
+      'When set to "1", convert-agents-to-codex.js aborts with exit 1 (simulates a missing ' +
+      'TOOL_DIR_NAME constant). Used exclusively in integration tests; do not set in production.',
+    type: 'boolean',
+    applies_to: 'cli',
+    since: '0.1.22',
+  },
+  {
+    name: 'MK_INTROSPECT_MAX_NOTES',
+    scope: 'vault',
+    default: undefined,
+    description:
+      'Maximum number of vault notes vault_introspect.py will enumerate before stopping. ' +
+      'Prevents runaway scanning on large vaults. Must be a positive integer.',
+    type: 'integer',
+    applies_to: 'skill',
+    since: '0.1.21',
+  },
+  {
+    name: 'MK_OAUTH_SCOPE',
+    scope: 'auth',
+    default: 'repo',
+    description:
+      'GitHub OAuth scope requested during the device flow. Defaults to "repo" (required to ' +
+      'access the private kit repository). Override only for testing or alternative scopes.',
+    type: 'string',
+    applies_to: 'cli',
+    since: '0.1.0',
+  },
+  {
+    name: 'MK_SQL_GUARD_ALLOWLIST',
+    scope: 'sql-guard',
+    default: '.claude/sql-guard.allowlist',
+    description:
+      'Path to the SQL guard allowlist file (kit-root-relative or absolute). ' +
+      'Used by sql-allowlist.cjs to load the list of approved SQL patterns.',
+    type: 'path',
+    applies_to: 'hook',
+    since: '0.1.26',
+  },
+  {
+    name: 'MK_SQL_GUARD_MAX_STDIN_BYTES',
+    scope: 'sql-guard',
+    default: '1048576',
+    description:
+      'Maximum stdin bytes the sql-guard hook will read before failing open (allowing the ' +
+      'command to proceed). Default is 1 048 576 bytes (1 MB). Increase for large queries.',
+    type: 'integer',
+    applies_to: 'hook',
+    since: '0.1.26',
+  },
+  {
+    name: 'MK_SQL_GUARD_TEST',
+    scope: 'sql-guard',
+    default: undefined,
+    description:
+      'When set to "1", sql-guard.cjs returns early at module load without executing the ' +
+      'stdin pipeline. Used exclusively by hook unit tests; do not set in production.',
+    type: 'boolean',
+    applies_to: 'hook',
+    since: '0.1.26',
+  },
+  {
+    name: 'MK_TEAM_MAX_ITERATIONS',
+    scope: 'team',
+    default: '8',
+    description:
+      'Maximum agent-team loop iterations enforced by loop-detector.js before the loop is ' +
+      'terminated. Applies to --team mode in mk-implement and mk-review.',
+    type: 'integer',
+    applies_to: 'skill',
+    since: '0.1.15',
+  },
+  {
+    name: 'MK_VAULT_CACHE_REBUILD',
+    scope: 'vault',
+    default: undefined,
+    description:
+      'When set to "1", vault_retrieval_plan.py ignores any cached retrieval plan and ' +
+      'rebuilds it from scratch. Useful after vault restructuring.',
+    type: 'boolean',
+    applies_to: 'skill',
+    since: '0.1.21',
+  },
+  {
+    name: 'MK_VAULT_ENABLED',
+    scope: 'vault',
+    default: undefined,
+    description:
+      'Privacy-by-default opt-in gate. Set to "1" to enable Obsidian vault consultation ' +
+      'across mk-* skills and agents. Any other value (or unset) means vault access is disabled.',
+    type: 'boolean',
+    applies_to: 'skill',
+    since: '0.1.21',
+  },
+  {
+    name: 'MK_VERBOSE',
+    scope: 'cli',
+    default: undefined,
+    description:
+      'When set to "1", enables verbose output in mk update and the Codex converters ' +
+      '(per-file change enumeration, routine warnings, long-path warnings). ' +
+      'Equivalent to passing --verbose on mk update.',
+    type: 'boolean',
+    applies_to: 'cli',
+    since: '0.1.25',
+  },
+];
+
+/**
+ * Frozen array of all known MK_* environment variables.
+ * @type {ReadonlyArray<{name:string,scope:string,default:string|undefined,description:string,type:string,applies_to:string,since?:string}>}
+ */
+export const ENTRIES = Object.freeze(_RAW.map(Object.freeze));
+
+/**
+ * Look up a registry entry by exact variable name.
+ *
+ * @param {string|undefined} name
+ * @returns {{ name:string, scope:string, default:string|undefined, description:string, type:string, applies_to:string, since?:string } | undefined}
+ */
+export function findByName(name) {
+  if (typeof name !== 'string') return undefined;
+  return ENTRIES.find((e) => e.name === name);
+}