heymark 1.0.1 → 1.0.2

package/README.md

@@ -86,7 +86,7 @@ npm install --save-dev heymark
 최초 1회만 설정하면 됩니다.
 
 ```bash
-# 규칙 소스 설정 (프로젝트 루트에 .heymark.json 생성)
+# 규칙 소스 설정 (.heymark/config.json 생성)
 npx heymark init <GitHub-저장소-URL>
 ```
 
@@ -103,7 +103,13 @@ npx heymark init git@github.com:org/my-rules.git
 npx heymark init https://github.com/org/my-rules.git --dir rules --branch main
 ```
 
-설정은 프로젝트 루트의 `.heymark.json`에 저장됩니다. 이후 `heymark` 실행 시 해당 저장소를 clone/pull 한 뒤 `.md` 파일들을 변환합니다.
+설정은 **`.heymark/config.json`**에, 캐시(클론된 저장소)는 `.heymark/cache/`에 생성됩니다.
+
+```gitignore
+.heymark/
+```
+
+이후 `heymark` 실행 시 해당 저장소를 clone/pull 한 뒤 `.md` 파일들을 변환합니다.
 
 ### Usage with npx
 
@@ -111,10 +117,10 @@ npx heymark init https://github.com/org/my-rules.git --dir rules --branch main
 규칙은 **원격 GitHub 저장소**에서 가져오며, 해당 저장소 안의 마크다운 파일을 각 AI 도구 형식으로 변환해 현재 프로젝트에 생성합니다.
 
 ```bash
-# .heymark.json에 설정된 외부 규칙 저장소에서 가져와 모든 도구 형식으로 변환 (기존 생성 파일 삭제 후 새로 생성)
+# .heymark/config.json에 설정된 외부 규칙 저장소에서 가져와 모든 도구 형식으로 변환 (기존 생성 파일 삭제 후 새로 생성)
 npx heymark
 
-# 이번에만 다른 외부 저장소 사용 (.heymark.json 무시)
+# 이번에만 다른 외부 저장소 사용 (.heymark/config.json 무시)
 npx heymark --source https://github.com/org/other-rules.git
 
 # 특정 도구만 변환

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "heymark",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "description": "Centralized AI coding tool conventions with auto-conversion to multiple formats",
     "main": "scripts/sync.js",
     "bin": {
@@ -27,6 +27,11 @@
         "url": "https://github.com/i2na"
     },
     "contributors": [
+        {
+            "name": "i2na",
+            "email": "yena.e121@gmail.com",
+            "url": "https://github.com/i2na"
+        },
         {
             "name": "yezzero",
             "email": "yeyeonggim06@gmail.com",

package/scripts/lib/config.js

@@ -3,7 +3,10 @@
 const fs = require("fs");
 const path = require("path");
 
-const CONFIG_FILENAME = ".heymark.json";
+const CONFIG_DIR = ".heymark";
+const CONFIG_FILENAME = "config.json";
+/** 프로젝트 루트 기준 설정 파일 경로 (표시용) */
+const CONFIG_RELATIVE = path.join(CONFIG_DIR, CONFIG_FILENAME);
 
 /**
  * rulesSource: GitHub 저장소 URL (https://github.com/org/repo 또는 git@github.com:org/repo.git)
@@ -13,12 +16,12 @@ const CONFIG_FILENAME = ".heymark.json";
  */
 
 /**
- * 프로젝트 루트에서 .heymark.json을 읽습니다.
+ * 프로젝트 루트에서 .heymark/config.json을 읽습니다.
  * @param {string} projectRoot - 프로젝트 루트 (보통 process.cwd())
  * @returns {RuleBookConfig | null}
  */
 function loadConfig(projectRoot) {
-    const configPath = path.join(projectRoot, CONFIG_FILENAME);
+    const configPath = path.join(projectRoot, CONFIG_DIR, CONFIG_FILENAME);
     if (!fs.existsSync(configPath)) return null;
 
     try {
@@ -38,12 +41,16 @@ function loadConfig(projectRoot) {
 }
 
 /**
- * 초기 설정 파일을 생성합니다. (원격 GitHub 저장소 URL 사용)
+ * 초기 설정 파일을 생성합니다. (원격 GitHub 저장소 URL 사용) .heymark/config.json에 저장합니다.
  * @param {string} projectRoot
  * @param {RuleBookConfig} config - { rulesSource: repoUrl, branch?, rulesSourceDir? }
  */
 function writeConfig(projectRoot, config) {
-    const configPath = path.join(projectRoot, CONFIG_FILENAME);
+    const configDir = path.join(projectRoot, CONFIG_DIR);
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    const configPath = path.join(configDir, CONFIG_FILENAME);
     const toWrite = {
         rulesSource: config.rulesSource,
         branch: config.branch || "main",
@@ -56,7 +63,9 @@ function writeConfig(projectRoot, config) {
 }
 
 module.exports = {
+    CONFIG_DIR,
     CONFIG_FILENAME,
+    CONFIG_RELATIVE,
     loadConfig,
     writeConfig,
 };

package/scripts/lib/repo.js

@@ -4,7 +4,7 @@ const fs = require("fs");
 const path = require("path");
 const { execSync } = require("child_process");
 
-const CACHE_DIR_NAME = ".heymark-cache";
+const CACHE_DIR_NAME = path.join(".heymark", "cache");
 
 /**
  * 저장소 URL에서 캐시 폴더명으로 쓸 수 있는 문자열 추출

package/scripts/sync.js

@@ -4,7 +4,7 @@
 const fs = require("fs");
 const path = require("path");
 const { loadRules } = require("./lib/parser");
-const { CONFIG_FILENAME, loadConfig, writeConfig } = require("./lib/config");
+const { CONFIG_RELATIVE, loadConfig, writeConfig } = require("./lib/config");
 const { getRulesDirFromRepo } = require("./lib/repo");
 
 const SCRIPT_DIR = __dirname;
@@ -88,11 +88,11 @@ tool-specific configuration files for various AI coding assistants.
 Same rules everywhere: A computer, B computer, same remote repo.
 
 Usage:
-  heymark init <repo-url>     Set rules source (creates ${CONFIG_FILENAME})
+  heymark init <repo-url>     Set rules source (creates ${CONFIG_RELATIVE})
   heymark [options]           Sync from configured or --source repo
 
 Options:
-  --source, -s <url>   GitHub repo URL for this run (overrides ${CONFIG_FILENAME})
+  --source, -s <url>   GitHub repo URL for this run (overrides ${CONFIG_RELATIVE})
   --tools, -t <list>   Comma-separated tool names (default: all)
   --clean, -c          Remove all generated files
   --preview, -p        Preview what will be generated without writing
@@ -100,7 +100,7 @@ Options:
 
 Rules source (in order):
   1. --source <repo-url>
-  2. ${CONFIG_FILENAME} (set via 'heymark init <repo-url>')
+  2. ${CONFIG_RELATIVE} (set via 'heymark init <repo-url>')
   Private repos: use SSH (git@github.com:org/repo.git) or HTTPS with token.
 
 Available tools:

package/rules/ai-behavior.md

@@ -1,87 +0,0 @@
----
-description: "AI assistant behavior: surgical code changes, communication style, and commenting philosophy"
-alwaysApply: true
----
-
-# AI Behavior
-
-## Code Modification
-
-- Modify **only** lines directly causing the problem; change the **minimum** required
-- **Never** refactor, reorganize, or reformat unrelated code
-- Maintain original file structure, patterns, and coding style
-- Implement only when **100% certain**; ask clarifying questions if insufficient context
-- Present multiple options with trade-offs when several valid solutions exist
-- Provide **full, exact code** for all changed lines
-- Use `// ... existing code` only for truly unchanged sections
-- Never use placeholders (`// TODO: implement`) or omit error handling
-- Favor clarity over cleverness; use early returns for error conditions
-
-## Commenting
-
-Code must be self-documenting. Add comments **only** with approved tags:
-
-| Tag             | Usage                                        |
-| :-------------- | :------------------------------------------- |
-| `@note`         | Critical context or non-obvious behavior     |
-| `@todo(owner):` | Future work with assigned owner (mandatory)  |
-| `@wip`          | Temporary code, remove before merge          |
-| `@deprecated`   | Marked for removal, must specify alternative |
-
-- English only, lowercase after tags, one line max
-- **Prohibited:** decorative separators (`// ===`, `// ---`), obvious statements, chatty explanations, uncommented dead code
-
-## Communication
-
-| Context                 | Language |
-| :---------------------- | :------- |
-| User-facing             | Korean   |
-| Code, comments, commits | English  |
-
-- **Tone:** Direct, concise. No filler, no hedging ("maybe", "possibly"), no pleasantries
-- **Structure:** Root cause (1-2 sentences) → Solution (code) → Reasoning (only if non-obvious)
-
-**Bad:** "안녕하세요! 도와드리겠습니다. 이 문제는 여러 원인이 있을 수 있는데..."
-**Good:** "`userId`가 `number | undefined`인데 `string`을 기대합니다. 타입 가드를 추가합니다."
-
-## Anti-Defensive Coding
-
-Write for the **expected successful flow**. Trust TypeScript compiler-enforced types. Let errors propagate naturally unless catching is required.
-
-**Avoid:**
-
-- Redundant null checks: `if (data && data.user && data.user.name)`
-- Unnecessary fallbacks: `const name = user?.name || "Unknown"`
-- Blanket try-catch around every function
-- Runtime type checks for TS-enforced types: `if (typeof id === 'number')`
-
-**Exceptions** — defensive code IS appropriate at:
-
-- Public API boundaries (user input, external API responses)
-- Security or financial operations
-- Known unreliable sources (legacy systems, third-party APIs)
-
-```typescript
-// ❌ Over-defensive
-function getUserEmail(userId: number): string {
-    try {
-        if (!userId || typeof userId !== "number") return "";
-        const user = database.getUser(userId);
-        if (!user || !user.email || typeof user.email !== "string") return "";
-        return user.email || "no-email@example.com";
-    } catch {
-        return "";
-    }
-}
-
-// ✅ Happy path
-function getUserEmail(userId: number): string {
-    return database.getUser(userId).email;
-}
-```
-
-## Decision Priority
-
-When rules conflict: **Security** > **User requirements** > **This guide** > **Language conventions** > **Preference**
-
-When uncertain: ask clarifying questions, state assumptions explicitly, admit knowledge gaps.

package/rules/code-conventions.md

@@ -1,98 +0,0 @@
----
-description: "TypeScript and React naming conventions, file structure, and type patterns"
-globs: "**/*.ts,**/*.tsx,**/*.js,**/*.jsx"
-alwaysApply: true
----
-
-# TypeScript & React Conventions
-
-## File Naming
-
-| Type              | Convention               | Example                |
-| :---------------- | :----------------------- | :--------------------- |
-| Utility / Service | `kebab-case.ts`          | `user-service.ts`      |
-| React Component   | `PascalCase.tsx`         | `DashboardLayout.tsx`  |
-| CSS Module        | `PascalCase.module.scss` | `Button.module.scss`   |
-| Test              | `*.test.ts(x)`           | `user-service.test.ts` |
-| Type Definition   | `*.types.ts`             | `api.types.ts`         |
-| Constants         | `*.constants.ts`         | `routes.constants.ts`  |
-
-## Code Naming
-
-| Element        | Convention             | Example                  |
-| :------------- | :--------------------- | :----------------------- |
-| Variable       | `camelCase`            | `userName`, `isActive`   |
-| Function       | `camelCase`            | `getUserData()`          |
-| Constant       | `UPPER_SNAKE_CASE`     | `API_BASE_URL`           |
-| Private member | `_camelCase`           | `_internalCache`         |
-| Boolean        | `is/has/should` prefix | `isLoading`, `hasAccess` |
-| Component      | `PascalCase`           | `UserCard`               |
-| Hook           | `use` prefix           | `useAuth()`              |
-| HOC            | `with` prefix          | `withAuth()`             |
-| Event handler  | `handle` prefix        | `handleSubmit()`         |
-| Render helper  | `render` prefix        | `renderHeader()`         |
-
-## Types & Interfaces
-
-| Type       | Convention              | Example                     |
-| :--------- | :---------------------- | :-------------------------- |
-| Interface  | `I` + PascalCase        | `IUser`, `IApiResponse`     |
-| Type alias | `T` + PascalCase        | `TConfig`, `TRequestBody`   |
-| Enum       | `E` + PascalCase        | `EUserRole`, `EStatus`      |
-| Props      | ComponentName + `Props` | `ButtonProps`, `ModalProps` |
-| Generic    | Single uppercase        | `T`, `K`, `V`               |
-
-Usage: **Interface** → object shapes, **Type alias** → unions/intersections, **Enum** → fixed value sets (string values in `UPPER_CASE`)
-
-```typescript
-interface IUser {
-    id: number;
-    email: string;
-    role: EUserRole;
-}
-
-type TApiResponse<T> = TSuccessResponse<T> | TErrorResponse;
-
-enum EUserRole {
-    Admin = "ADMIN",
-    User = "USER",
-    Guest = "GUEST",
-}
-```
-
-- Avoid `any`; use `unknown` or generics
-- Explicit return types for public API functions
-- Use type guards for runtime narrowing
-
-## File Structure
-
-Import order (separate each group with a blank line):
-
-1. React / framework (`react`, `next`)
-2. External libraries (`axios`, `lodash`)
-3. Internal aliases (`@/components`, `@/hooks`)
-4. Relative imports (`./`, `../`)
-5. Type-only imports (`import type`)
-6. Styles (`.module.scss`)
-
-Within-file order: **Imports → Types → Constants → Private helpers → Public exports**
-
-## Component Pattern
-
-```typescript
-// Named function export (preferred over React.FC)
-export function UserCard({ userId }: UserCardProps) {
-    // 1. hooks
-    // 2. state (descriptive names: isLoading, userData — not loading, data)
-    // 3. effects (all deps in dependency array)
-    // 4. handlers (handleXxx)
-    // 5. render helpers (renderXxx)
-    // 6. return JSX
-}
-```
-
-## Formatting
-
-- Max **100 characters** per line
-- Prefer destructuring: `const { email, role } = user`
-- Optional chaining `?.` max 2 levels deep

package/rules/readme-writing.md

@@ -1,69 +0,0 @@
----
-description: "README document writing guide: structure, style, and format conventions"
-globs: "README.md"
-alwaysApply: false
----
-
-# README Writing Guide
-
-## Structure
-
-README는 다음 순서를 따른다:
-
-1. **Title** — 프로젝트를 대표하는 심플한 영어 이름
-2. **Intro** — 1-2줄 한국어 프로젝트 소개
-3. **Table of Contents** — 마크다운 테이블 형태
-4. **Overview** — 프로젝트 배경과 핵심 가치 (3-5문장)
-5. **Features** — 핵심 기능만 (추상적 설명 금지)
-6. **Tech Stack** — 핵심 기술만 (사소한 라이브러리 제외)
-7. **Getting Started** — 설치 및 실행 (최소 단계)
-
-## Format
-
-### Language
-
-- 제목, 소제목: **영어**
-- 본문: **한국어**
-- 코드, 명령어: 영어
-
-### Style
-
-- 이모지 금지
-- 장황한 설명 금지; 간결하고 공식적인 어조
-- 바뀌기 쉬운 파일명, 변수명, 경로는 언급하지 않음
-- HTML 태그 최소화
-
-### Table of Contents
-
-```markdown
-1. [Overview](#overview)
-2. [Features](#features)
-3. [Tech Stack](#tech-stack)
-4. [Getting Started](#getting-started)
-```
-
-### Features
-
-- 실제로 **구분 가능한 대표 기능**만 나열
-- 각 기능은 한 줄 설명
-- 추상적 표현 금지: ~~"강력한 성능"~~, ~~"혁신적인 아키텍처"~~
-
-### Tech Stack
-
-- 프레임워크, 언어, 핵심 인프라만
-- 유틸 라이브러리, 개발 도구 제외
-- 테이블 또는 간단한 리스트
-
-### Getting Started
-
-- Prerequisites (필요 시만)
-- 설치 명령어 (코드 블록)
-- 실행 명령어 (코드 블록)
-
-## Anti-Patterns
-
-- 7개 이상 섹션의 장황한 README
-- 뱃지, 이모지, 장식적 요소
-- 추상적 기능 소개
-- 자주 변하는 파일명/변수명 언급
-- 불필요한 Contributing, License, Changelog 섹션

package/rules/research-workflow.md

@@ -1,79 +0,0 @@
----
-description: "Technical research workflow for generating in-depth reports with web search and analysis"
-globs: ""
-alwaysApply: false
----
-
-# Research Workflow
-
-Activate when user explicitly requests research ("research X", "investigate Y", "compare Z"). Not for simple coding questions, quick fact-checks, debugging, or routine implementation.
-
-## Principles
-
-- Base conclusions on **official docs, technical blogs, papers, whitepapers**
-- **Never** speculate or present assumptions as facts
-- Cite all sources with direct URLs
-- No emojis in research documents
-- Explain **how** things work, not just features; identify limitations and edge cases
-- Use clear technical language; avoid marketing language ("blazingly fast", "revolutionary")
-
-## Process
-
-### Phase 1: Multi-Angle Search (5+ queries)
-
-1. Official documentation (include version numbers and year)
-2. Technical comparisons and benchmarks
-3. Implementation guides and best practices
-4. Known issues and limitations
-5. Alternative solutions
-
-Start broad, narrow based on findings.
-
-### Phase 2: Deep Extraction
-
-Fetch full content of 3-5 critical URLs:
-- API specs, technical references
-- Architecture and system design docs
-- Benchmark data, performance analyses
-- Security advisories
-
-### Phase 3: Synthesis
-
-- Identify patterns and contradictions across sources
-- Evaluate trade-offs between approaches
-- Assess feasibility for the specific use case
-- Form architectural recommendations
-
-## Report Format
-
-```
-# [Topic]
-
-**Date:** YYYY-MM-DD
-**Scope:** [Brief description]
-**Key Finding:** [One sentence]
-
-## Executive Summary
-3-5 sentences: what, why, key findings, constraints.
-
-## [Thematic Sections]
-Organize by theme, not by source:
-- Technical Feasibility
-- Architecture Considerations
-- Performance Characteristics
-- Alternative Approaches
-
-## Conclusion
-Recommendations, next steps, risks/unknowns.
-
-## Sources
-1. [Title](URL) - Description
-```
-
-## Output
-
-- **Filename:** descriptive English, kebab-case (`redis-vs-memcached-comparison.md`)
-- **Location:** `/research/`, `/docs/research/`, or project root
-- **Format:** Markdown with code blocks, mermaid diagrams, comparison tables
-- **Language:** English, present tense, active voice, define acronyms on first use
-- Include minimal runnable code examples where relevant

package/rules/rule-writing.md

@@ -1,71 +0,0 @@
----
-description: "Guide for creating rule documents: structure, token efficiency, and writing principles"
-globs: "rules/*.md"
-alwaysApply: false
----
-
-# Rule Writing Guide
-
-Rules in `rules/` are consumed by AI coding assistants. Every token loads per request — **brevity is critical**.
-
-## Frontmatter
-
-```yaml
----
-description: "One-line summary for AI relevance judgment"
-globs: "**/*.ts,**/*.tsx" # File patterns for auto-attachment (empty if N/A)
-alwaysApply: true # true = always loaded, false = conditional
----
-```
-
-- `description`: AI가 자동 로딩 여부를 판단할 때 참조하는 요약
-- `globs`: 해당 파일 패턴 작업 시 자동 적용
-- `alwaysApply`: 항상 로드 여부
-
-## Structure
-
-1. **Title** (`# Rule Name`) — short, descriptive
-2. **Scope** (optional) — one sentence on when this rule activates
-3. **Sections** — organized by theme
-4. No redundant sections (stated rules should not be restated as checklists)
-
-## Writing Principles
-
-### Token Efficiency
-
-- Every line must be an **actionable instruction**
-- Remove meta-sentences: ~~"This rule defines how the AI should..."~~
-- Remove knowledge AI already possesses
-- **Tables** for mappings (most token-efficient format)
-- **Bullet lists** for constraints, not paragraphs
-- One code example per concept max; omit if a table already conveys it
-
-### Clarity
-
-- **Imperative voice:** "Use camelCase" not "You should use camelCase"
-- **Bold** key terms and constraints
-- Concrete examples over abstract descriptions
-- No hedging: use "always", "never", "must" — not "try to", "consider"
-
-### Completeness
-
-- Cover all conventions without redundancy
-- Include ✅/❌ examples only when the rule is counterintuitive
-- Add inline context only when the rule needs explanation
-
-## Anti-Patterns
-
-- Chatty introductions: ~~"Welcome! This document will help you..."~~
-- Redundant checklists restating earlier rules
-- Over-documenting _why_ a rule exists (unless non-obvious)
-- Emojis, excessive separators, decorative formatting
-- Stale references to specific file names or paths that change frequently
-
-## Quality Test
-
-A well-written rule document:
-
-- Can be followed by any AI without ambiguity
-- Contains **zero** filler sentences
-- Uses ≤50% tokens of a verbose equivalent
-- Handles edge cases inline, not in separate sections