@yeongjaeyou/claude-code-config 0.13.0 → 0.15.0

package/.claude/guidelines/work-guidelines.md

@@ -13,10 +13,42 @@ Common guidelines for all Claude Code commands and development workflow.
 - Do not use emoji in code or documentation
 - Never add Claude attribution (e.g., "Generated with Claude", "Co-Authored-By: Claude") to commits, PRs, or issues
 
+### Writing Style (Anti-AI)
+Write like a human, not a chatbot. Applies to ALL text: responses, documentation, comments, commit messages.
+
+**NEVER use these AI-ish patterns:**
+- Filler openers: "Certainly!", "Of course!", "Absolutely!", "I'd be happy to", "Great question!"
+- Excessive affirmation: "That's a great idea", "You're absolutely right", "Excellent point"
+- Redundant summaries: "To summarize...", "In conclusion...", "To recap..."
+- Over-explanation: Explaining obvious things, restating the question
+- Hedging phrases: "I think maybe...", "It might be possible that..."
+- Hollow transitions: "Now, let's...", "Moving on to...", "Next, we'll..."
+- Colon headers: "**항목:** 설명", "**Topic:** content" - just write naturally without label-colon-content structure
+
+**DO:**
+- Get to the point immediately
+- Be direct and concise
+- Use natural, conversational tone
+- Skip pleasantries unless genuinely warranted
+
 ### Uncertainty Handling
 - If you are uncertain, confused, or lack clarity about the requirements or approach, **STOP immediately** and ask the user for clarification
 - Do not proceed with assumptions or guesses that could lead to incorrect implementations
-- If any instruction/requirement is unclear, ambiguous, or potentially incorrect, use the `AskUserQuestion` tool (do not ask inline in the response text)
+- **NEVER** ask questions inline in response text - always use `AskUserQuestion` tool
+
+### Question Policy (MANDATORY)
+- **ALL questions MUST use `AskUserQuestion` tool** - no exceptions
+- Never ask questions as plain text in responses
+- This includes:
+  - Clarification questions
+  - Option/choice selection
+  - Confirmation requests
+  - Any user input needed
+
+**Why:**
+- Plain text questions get buried in long responses
+- Tool-based questions provide clear UI separation
+- Ensures user doesn't miss important decisions
 
 ### User Confirmation Required
 Always confirm with the user before:

package/.claude/skills/notion-md-uploader/SKILL.md

@@ -25,16 +25,22 @@ Before using this skill, ensure the following setup is complete:
 
 ### 2. Environment Configuration
 
-Set the API key in the environment:
+Set the API key in the environment. The script automatically loads `.env` files if `python-dotenv` is installed:
 
 ```bash
-# In .env file
+# In .env file (recommended - auto-loaded)
 NOTION_API_KEY=ntn_xxxxx
 
 # Or export directly
 export NOTION_API_KEY=ntn_xxxxx
 ```
 
+To install dotenv support:
+
+```bash
+uv add python-dotenv
+```
+
 ### 3. Page Access
 
 Share the target parent page with the integration:
@@ -65,6 +71,8 @@ uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
 
 ### Dry Run (Preview)
 
+Preview parsing results and validate local images before uploading:
+
 ```bash
 uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
     docs/analysis.md \
@@ -72,6 +80,11 @@ uv run python .claude/skills/notion-md-uploader/scripts/upload_md.py \
     --dry-run
 ```
 
+The dry run validates:
+- Markdown block parsing
+- Local image file existence
+- Conversion to Notion blocks
+
 ## Supported Markdown Elements
 
 | Element | Markdown Syntax | Notion Block |

package/.claude/skills/notion-md-uploader/scripts/upload_md.py

@@ -18,10 +18,17 @@ import sys
 from pathlib import Path
 from typing import Any
 
+# Load .env file if python-dotenv is available
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # python-dotenv not installed, use env vars directly
+
 # Add scripts directory to path for imports
 sys.path.insert(0, str(Path(__file__).parent))
 
-from markdown_parser import MarkdownParser
+from markdown_parser import BlockType, MarkdownParser
 from notion_client import NotionClient, NotionAPIError, NotionConfig
 from notion_converter import NotionBlockConverter
 
@@ -236,8 +243,8 @@ Setup:
         print(f"Parsing: {args.md_file}")
         content = md_path.read_text(encoding="utf-8")
 
-        parser = MarkdownParser(base_path=str(md_path.parent))
-        blocks = parser.parse(content)
+        md_parser = MarkdownParser(base_path=str(md_path.parent))
+        blocks = md_parser.parse(content)
 
         print(f"Found {len(blocks)} blocks:")
         for i, block in enumerate(blocks[:10]):
@@ -251,6 +258,34 @@ Setup:
         if len(blocks) > 10:
             print(f"  ... and {len(blocks) - 10} more blocks")
 
+        # Validate image files
+        base_path = md_path.parent
+        image_blocks = [b for b in blocks if b.block_type == BlockType.IMAGE]
+        missing_images = []
+        found_images = []
+
+        for block in image_blocks:
+            img_src = block.metadata.get("url", "")
+            if img_src and not img_src.startswith(("http://", "https://")):
+                img_path = base_path / img_src
+                if img_path.exists():
+                    found_images.append(str(img_src))
+                else:
+                    missing_images.append(str(img_src))
+
+        if found_images:
+            print(f"\nLocal images ({len(found_images)}):")
+            for img in found_images[:5]:
+                print(f"  [OK] {img}")
+            if len(found_images) > 5:
+                print(f"  ... and {len(found_images) - 5} more")
+
+        if missing_images:
+            print(f"\nMissing images ({len(missing_images)}):")
+            for img in missing_images:
+                print(f"  [MISSING] {img}")
+            print("\nWarning: Missing images will cause upload to fail.")
+
         converter = NotionBlockConverter(base_path=str(md_path.parent))
         notion_blocks = converter.convert_blocks(blocks)
         print(f"\nConverted to {len(notion_blocks)} Notion blocks")
@@ -272,10 +307,13 @@ Setup:
 
         page_url = page.get("url", "")
         page_id = page.get("id", "")
+        image_count = len(uploader._uploaded_images)
 
         print(f"\nSuccess!")
         print(f"Page ID: {page_id}")
         print(f"URL: {page_url}")
+        if image_count > 0:
+            print(f"Images uploaded: {image_count}")
 
     except NotionAPIError as e:
         print(f"\nNotion API Error: {e}")

package/bin/cli.js

@@ -3,13 +3,17 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const readline = require('readline');
 
 const pkg = require('../package.json');
-const args = process.argv.slice(2);
+const {
+  INSTALL_FOLDERS,
+  askQuestion,
+  checkExistingFolders,
+  installFolders,
+  mergeSettingsJson
+} = require('../lib/cli-utils');
 
-// Installation target folders (non-user data only)
-const INSTALL_FOLDERS = ['commands', 'agents', 'skills', 'guidelines', 'hooks'];
+const args = process.argv.slice(2);
 
 // Parse options
 const isGlobal = args.includes('--global') || args.includes('-g');
@@ -57,232 +61,6 @@ const dest = isGlobal
   ? path.join(os.homedir(), '.claude')
   : path.join(process.cwd(), '.claude');
 
-/**
- * Ask user a question and get answer
- * @param {string} question - Question content
- * @returns {Promise<string>} - User answer
- */
-function askQuestion(question) {
-  // Detect non-interactive environment (CI/CD, pipelines, etc.)
-  if (!process.stdin.isTTY) {
-    console.log('Non-interactive environment detected. Using default (update).');
-    return Promise.resolve('update');
-  }
-
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase());
-    });
-  });
-}
-
-/**
- * Check existing installation folders
- * @returns {string[]} - List of existing folders
- */
-function checkExistingFolders() {
-  const existing = [];
-  for (const folder of INSTALL_FOLDERS) {
-    const folderPath = path.join(dest, folder);
-    if (fs.existsSync(folderPath)) {
-      existing.push(folder);
-    }
-  }
-  return existing;
-}
-
-/**
- * Copy folder recursively
- * @param {string} src - Source path
- * @param {string} dst - Destination path
- * @param {string} mode - Installation mode: 'merge' | 'update'
- */
-function copyFolder(src, dst, mode = 'merge') {
-  if (!fs.existsSync(src)) {
-    return;
-  }
-
-  // Create destination folder
-  if (!fs.existsSync(dst)) {
-    try {
-      fs.mkdirSync(dst, { recursive: true });
-    } catch (err) {
-      throw new Error(`Failed to create folder: ${dst} - ${err.message}`);
-    }
-  }
-
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const dstPath = path.join(dst, entry.name);
-
-    if (entry.isDirectory()) {
-      copyFolder(srcPath, dstPath, mode);
-    } else {
-      // In merge mode, keep existing files (skip if exists)
-      if (mode === 'merge' && fs.existsSync(dstPath)) {
-        continue;
-      }
-      // In update mode, overwrite existing files + add new files
-      // Custom files (only in dest) are preserved since we don't delete them
-      try {
-        fs.copyFileSync(srcPath, dstPath);
-        // Set execute permission for shell scripts
-        if (entry.name.endsWith('.sh')) {
-          fs.chmodSync(dstPath, 0o755);
-        }
-      } catch (err) {
-        throw new Error(`Failed to copy file: ${srcPath} -> ${dstPath} - ${err.message}`);
-      }
-    }
-  }
-}
-
-/**
- * Selectively copy installation target folders
- * @param {string} mode - 'merge' | 'update'
- */
-function installFolders(mode) {
-  for (const folder of INSTALL_FOLDERS) {
-    const srcFolder = path.join(source, folder);
-    const dstFolder = path.join(dest, folder);
-
-    if (!fs.existsSync(srcFolder)) {
-      continue;
-    }
-
-    // Both modes now preserve custom files
-    // - merge: skip existing files, add new files only
-    // - update: overwrite existing files, add new files, keep custom files
-    copyFolder(srcFolder, dstFolder, mode);
-  }
-}
-
-// Default hook configuration for inject-guidelines
-const DEFAULT_HOOKS_CONFIG = {
-  UserPromptSubmit: [
-    {
-      matcher: '',
-      hooks: [
-        {
-          type: 'command',
-          command: 'bash .claude/hooks/inject-guidelines.sh'
-        }
-      ]
-    }
-  ]
-};
-
-// Global-only notification hooks (OSC desktop alerts)
-const GLOBAL_NOTIFICATION_HOOKS = {
-  Stop: [
-    {
-      hooks: [
-        {
-          type: 'command',
-          command: '~/.claude/hooks/notify_osc.sh',
-          timeout: 10
-        }
-      ]
-    }
-  ],
-  Notification: [
-    {
-      matcher: '',
-      hooks: [
-        {
-          type: 'command',
-          command: '~/.claude/hooks/notify_osc.sh',
-          timeout: 10
-        }
-      ]
-    }
-  ]
-};
-
-/**
- * Check if a hook with the same command already exists
- * @param {Array} hooks - Existing hooks array
- * @param {string} command - Command to check
- * @returns {boolean}
- */
-function hookExists(hooks, command) {
-  if (!Array.isArray(hooks)) return false;
-  return hooks.some(hook => {
-    if (!hook.hooks || !Array.isArray(hook.hooks)) return false;
-    return hook.hooks.some(h => h.command === command);
-  });
-}
-
-/**
- * Merge settings.json with default hooks configuration
- * Preserves existing user settings and only adds new hooks
- */
-function mergeSettingsJson() {
-  const settingsPath = path.join(dest, 'settings.json');
-  let settings = {};
-
-  // Load existing settings if exists
-  if (fs.existsSync(settingsPath)) {
-    try {
-      const content = fs.readFileSync(settingsPath, 'utf8');
-      settings = JSON.parse(content);
-    } catch (err) {
-      console.log('Warning: Could not parse existing settings.json, creating new one.');
-      settings = {};
-    }
-  }
-
-  // Initialize hooks object if not exists
-  if (!settings.hooks) {
-    settings.hooks = {};
-  }
-
-  // Initialize UserPromptSubmit array if not exists
-  if (!settings.hooks.UserPromptSubmit) {
-    settings.hooks.UserPromptSubmit = [];
-  }
-
-  // Add default hooks if not already present
-  const targetCommand = DEFAULT_HOOKS_CONFIG.UserPromptSubmit[0].hooks[0].command;
-  if (!hookExists(settings.hooks.UserPromptSubmit, targetCommand)) {
-    settings.hooks.UserPromptSubmit.push(DEFAULT_HOOKS_CONFIG.UserPromptSubmit[0]);
-    console.log('Added inject-guidelines hook to settings.json');
-  } else {
-    console.log('inject-guidelines hook already exists in settings.json');
-  }
-
-  // Add notification hooks for global install only
-  if (isGlobal) {
-    for (const [event, hookConfigs] of Object.entries(GLOBAL_NOTIFICATION_HOOKS)) {
-      if (!settings.hooks[event]) {
-        settings.hooks[event] = [];
-      }
-      const notifCommand = hookConfigs[0].hooks[0].command;
-      if (!hookExists(settings.hooks[event], notifCommand)) {
-        settings.hooks[event].push(hookConfigs[0]);
-        console.log(`Added ${event} notification hook to settings.json`);
-      } else {
-        console.log(`${event} notification hook already exists in settings.json`);
-      }
-    }
-  }
-
-  // Write merged settings
-  try {
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-  } catch (err) {
-    throw new Error(`Failed to write settings.json: ${err.message}`);
-  }
-}
-
 /**
  * Main function
  */
@@ -319,7 +97,7 @@ async function main() {
   }
 
   // Check existing installation folders
-  const existingFolders = checkExistingFolders();
+  const existingFolders = checkExistingFolders(dest);
   let installMode = 'update';
 
   if (existingFolders.length > 0) {
@@ -358,10 +136,10 @@ async function main() {
   }
 
   // Install folders
-  installFolders(installMode);
+  installFolders(source, dest, installMode);
 
   // Merge settings.json with hooks configuration
-  mergeSettingsJson();
+  mergeSettingsJson(dest, isGlobal);
 
   console.log('');
   console.log('.claude/ folder installed successfully!');

package/lib/cli-utils.js

@@ -0,0 +1,271 @@
+/**
+ * CLI Utility Functions
+ * Modularized from bin/cli.js for testability
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// Installation target folders (non-user data only)
+const INSTALL_FOLDERS = ['commands', 'agents', 'skills', 'guidelines', 'hooks'];
+
+// Default hook configuration for inject-guidelines
+const DEFAULT_HOOKS_CONFIG = {
+  UserPromptSubmit: [
+    {
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: 'bash .claude/hooks/inject-guidelines.sh'
+        }
+      ]
+    }
+  ]
+};
+
+// Global-only notification hooks (OSC desktop alerts)
+const GLOBAL_NOTIFICATION_HOOKS = {
+  Stop: [
+    {
+      hooks: [
+        {
+          type: 'command',
+          command: '~/.claude/hooks/notify_osc.sh',
+          timeout: 10
+        }
+      ]
+    }
+  ],
+  Notification: [
+    {
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: '~/.claude/hooks/notify_osc.sh',
+          timeout: 10
+        }
+      ]
+    }
+  ]
+};
+
+/**
+ * Ask user a question and get answer
+ * @param {string} question - Question content
+ * @param {Object} options - Options for readline
+ * @param {NodeJS.ReadStream} options.input - Input stream (default: process.stdin)
+ * @param {NodeJS.WriteStream} options.output - Output stream (default: process.stdout)
+ * @returns {Promise<string>} - User answer
+ */
+function askQuestion(question, options = {}) {
+  const input = options.input || process.stdin;
+  const output = options.output || process.stdout;
+
+  // Detect non-interactive environment (CI/CD, pipelines, etc.)
+  if (!input.isTTY) {
+    console.log('Non-interactive environment detected. Using default (update).');
+    return Promise.resolve('update');
+  }
+
+  const rl = readline.createInterface({
+    input,
+    output
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+/**
+ * Check existing installation folders
+ * @param {string} dest - Destination path
+ * @returns {string[]} - List of existing folders
+ */
+function checkExistingFolders(dest) {
+  const existing = [];
+  for (const folder of INSTALL_FOLDERS) {
+    const folderPath = path.join(dest, folder);
+    if (fs.existsSync(folderPath)) {
+      existing.push(folder);
+    }
+  }
+  return existing;
+}
+
+/**
+ * Copy folder recursively
+ * @param {string} src - Source path
+ * @param {string} dst - Destination path
+ * @param {string} mode - Installation mode: 'merge' | 'update'
+ */
+function copyFolder(src, dst, mode = 'merge') {
+  if (!fs.existsSync(src)) {
+    return;
+  }
+
+  // Create destination folder
+  if (!fs.existsSync(dst)) {
+    try {
+      fs.mkdirSync(dst, { recursive: true });
+    } catch (err) {
+      throw new Error(`Failed to create folder: ${dst} - ${err.message}`);
+    }
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const dstPath = path.join(dst, entry.name);
+
+    if (entry.isDirectory()) {
+      copyFolder(srcPath, dstPath, mode);
+    } else {
+      // In merge mode, keep existing files (skip if exists)
+      if (mode === 'merge' && fs.existsSync(dstPath)) {
+        continue;
+      }
+      // In update mode, overwrite existing files + add new files
+      // Custom files (only in dest) are preserved since we don't delete them
+      try {
+        fs.copyFileSync(srcPath, dstPath);
+        // Set execute permission for shell scripts
+        if (entry.name.endsWith('.sh')) {
+          fs.chmodSync(dstPath, 0o755);
+        }
+      } catch (err) {
+        throw new Error(`Failed to copy file: ${srcPath} -> ${dstPath} - ${err.message}`);
+      }
+    }
+  }
+}
+
+/**
+ * Selectively copy installation target folders
+ * @param {string} source - Source base path
+ * @param {string} dest - Destination base path
+ * @param {string} mode - 'merge' | 'update'
+ */
+function installFolders(source, dest, mode) {
+  for (const folder of INSTALL_FOLDERS) {
+    const srcFolder = path.join(source, folder);
+    const dstFolder = path.join(dest, folder);
+
+    if (!fs.existsSync(srcFolder)) {
+      continue;
+    }
+
+    // Both modes now preserve custom files
+    // - merge: skip existing files, add new files only
+    // - update: overwrite existing files, add new files, keep custom files
+    copyFolder(srcFolder, dstFolder, mode);
+  }
+}
+
+/**
+ * Check if a hook with the same command already exists
+ * @param {Array} hooks - Existing hooks array
+ * @param {string} command - Command to check
+ * @returns {boolean}
+ */
+function hookExists(hooks, command) {
+  if (!Array.isArray(hooks)) return false;
+  return hooks.some(hook => {
+    if (!hook.hooks || !Array.isArray(hook.hooks)) return false;
+    return hook.hooks.some(h => h.command === command);
+  });
+}
+
+/**
+ * Merge settings.json with default hooks configuration
+ * Preserves existing user settings and only adds new hooks
+ * @param {string} dest - Destination path (.claude folder)
+ * @param {boolean} isGlobal - Whether this is a global installation
+ * @param {Object} options - Optional overrides for testing
+ * @param {Object} options.defaultHooksConfig - Override DEFAULT_HOOKS_CONFIG
+ * @param {Object} options.globalNotificationHooks - Override GLOBAL_NOTIFICATION_HOOKS
+ */
+function mergeSettingsJson(dest, isGlobal, options = {}) {
+  const defaultHooksConfig = options.defaultHooksConfig || DEFAULT_HOOKS_CONFIG;
+  const globalNotificationHooks = options.globalNotificationHooks || GLOBAL_NOTIFICATION_HOOKS;
+
+  const settingsPath = path.join(dest, 'settings.json');
+  let settings = {};
+
+  // Load existing settings if exists
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const content = fs.readFileSync(settingsPath, 'utf8');
+      settings = JSON.parse(content);
+    } catch (err) {
+      console.log('Warning: Could not parse existing settings.json, creating new one.');
+      settings = {};
+    }
+  }
+
+  // Initialize hooks object if not exists
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  // Initialize UserPromptSubmit array if not exists
+  if (!settings.hooks.UserPromptSubmit) {
+    settings.hooks.UserPromptSubmit = [];
+  }
+
+  // Add default hooks if not already present
+  const targetCommand = defaultHooksConfig.UserPromptSubmit[0].hooks[0].command;
+  if (!hookExists(settings.hooks.UserPromptSubmit, targetCommand)) {
+    settings.hooks.UserPromptSubmit.push(defaultHooksConfig.UserPromptSubmit[0]);
+    console.log('Added inject-guidelines hook to settings.json');
+  } else {
+    console.log('inject-guidelines hook already exists in settings.json');
+  }
+
+  // Add notification hooks for global install only
+  if (isGlobal) {
+    for (const [event, hookConfigs] of Object.entries(globalNotificationHooks)) {
+      if (!settings.hooks[event]) {
+        settings.hooks[event] = [];
+      }
+      const notifCommand = hookConfigs[0].hooks[0].command;
+      if (!hookExists(settings.hooks[event], notifCommand)) {
+        settings.hooks[event].push(hookConfigs[0]);
+        console.log(`Added ${event} notification hook to settings.json`);
+      } else {
+        console.log(`${event} notification hook already exists in settings.json`);
+      }
+    }
+  }
+
+  // Write merged settings
+  try {
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  } catch (err) {
+    throw new Error(`Failed to write settings.json: ${err.message}`);
+  }
+
+  return settings;
+}
+
+module.exports = {
+  // Constants
+  INSTALL_FOLDERS,
+  DEFAULT_HOOKS_CONFIG,
+  GLOBAL_NOTIFICATION_HOOKS,
+
+  // Functions
+  askQuestion,
+  checkExistingFolders,
+  copyFolder,
+  installFolders,
+  hookExists,
+  mergeSettingsJson
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeongjaeyou/claude-code-config",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Claude Code CLI custom commands, agents, and skills",
   "bin": {
     "claude-code-config": "./bin/cli.js"
@@ -8,8 +8,14 @@
   "files": [
     ".claude",
     ".mcp.json",
-    "bin"
+    "bin",
+    "lib"
   ],
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
   "keywords": [
     "claude-code",
     "cli",
@@ -29,5 +35,12 @@
   "homepage": "https://github.com/YoungjaeDev/claude-code-config#readme",
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "mock-fs": "^5.4.1"
+  },
+  "engines": {
+    "node": ">=14.0.0"
   }
 }