vibe-commander 0.2.0 → 0.2.1

package/dist/adapters/cli/stdin-parser.js

@@ -0,0 +1,109 @@
+/**
+ * stdin JSON → ParsedArgs 변환 — Layer 3 (Adapter)
+ *
+ * stdin을 통해 전달된 JSON 데이터를 ParsedArgs로 변환한다.
+ * 서브커맨드는 argv에서 결정되고, 인자/옵션은 stdin JSON에서 추출.
+ *
+ * @module
+ */
+import { ok, fail } from '../../types/index.js';
+/**
+ * stdin JSON 데이터로부터 ParsedArgs를 생성한다
+ *
+ * 서브커맨드는 argv에서 결정되고, 인자/옵션은 stdin JSON에서 추출.
+ * --stdin은 --no-prompt를 암시한다 (stdin이 JSON 데이터에 사용되므로 인터랙티브 불가).
+ *
+ * @param subcommand - argv에서 추출한 서브커맨드 이름
+ * @param data - stdin에서 파싱한 JSON 객체
+ * @param json - --json 플래그 여부
+ * @returns ParsedArgs 또는 에러
+ */
+export function parseStdinArgs(subcommand, data, json, rawArgs) {
+    switch (subcommand) {
+        case 'set-unit': {
+            const unitId = typeof data.unitId === 'string' ? data.unitId : undefined;
+            if (!unitId) {
+                return fail('STDIN_MISSING_FIELD', 'stdin JSON에 "unitId" (string) 필드가 필요합니다', '예시: {"unitId": "U-001[Mvp]"}');
+            }
+            const requestKeys = Array.isArray(data.requestKeys)
+                ? data.requestKeys.filter((k) => typeof k === 'string')
+                : [];
+            const dryRun = rawArgs?.includes('--dry-run') ?? false;
+            return ok({ command: 'set-unit', unitId, requestKeys, noPrompt: true, dryRun, json });
+        }
+        case 'update-commit': {
+            const modeValue = typeof data.mode === 'string' ? data.mode : undefined;
+            const mode = modeValue === 'append' ? 'append' : 'replace';
+            const section = typeof data.section === 'string' ? data.section : undefined;
+            const base = {
+                command: 'update-commit',
+                mode,
+                ...(section !== undefined && { section }),
+                json,
+            };
+            if (typeof data.sha === 'string') {
+                return ok({ ...base, commitMode: 'manual', sha: data.sha });
+            }
+            if (typeof data.count === 'number' && Number.isInteger(data.count) && data.count > 0) {
+                return ok({ ...base, commitMode: 'auto-recent', count: data.count });
+            }
+            return ok({ ...base, commitMode: 'auto-head' });
+        }
+        case 'list-units': {
+            const phase = typeof data.phase === 'string' ? data.phase : undefined;
+            return ok({
+                command: 'list-units',
+                ...(phase !== undefined && { phase }),
+                json,
+            });
+        }
+        case 'context': {
+            const unitId = typeof data.unitId === 'string' ? data.unitId : undefined;
+            if (!unitId) {
+                return fail('STDIN_MISSING_FIELD', 'stdin JSON에 "unitId" (string) 필드가 필요합니다', '예시: {"unitId": "U-001[Mvp]"}');
+            }
+            return ok({ command: 'context', unitId, json });
+        }
+        case 'validate':
+            return ok({ command: 'validate', json });
+        case 'init':
+            return ok({
+                command: 'init',
+                json,
+                stdinData: data,
+                fromExisting: rawArgs?.includes('--from-existing') ?? false,
+                force: rawArgs?.includes('--force') ?? false,
+            });
+        case 'skill': {
+            if (!rawArgs?.includes('install')) {
+                return fail('UNKNOWN_COMMAND', 'skill 서브커맨드가 필요합니다', '사용법: vc skill install --stdin --json');
+            }
+            const stdinTargets = Array.isArray(data.targets)
+                ? data.targets.filter((t) => t === 'cursor' || t === 'claude' || t === 'gemini')
+                : [];
+            const targets = stdinTargets.length > 0 ? stdinTargets : ['cursor', 'claude', 'gemini'];
+            return ok({
+                command: 'skill-install',
+                targets,
+                force: rawArgs.includes('--force'),
+                json,
+            });
+        }
+        case 'schema': {
+            const sub = typeof data.subcommand === 'string' ? data.subcommand : undefined;
+            if (sub && sub !== 'config' && sub !== 'commands' && sub !== 'types') {
+                return fail('UNKNOWN_SUBCOMMAND', `알 수 없는 schema 서브커맨드: ${sub}`, '사용 가능한 서브커맨드: config, commands, types');
+            }
+            const output = typeof data.output === 'string' ? data.output : undefined;
+            return ok({
+                command: 'schema',
+                ...(sub !== undefined && { subcommand: sub }),
+                json,
+                ...(output !== undefined && { output }),
+            });
+        }
+        default:
+            return fail('UNKNOWN_COMMAND', `알 수 없는 명령어: ${subcommand}`, '사용 가능한 명령어: init, set-unit, update-commit, list-units, context, validate, skill, schema');
+    }
+}
+//# sourceMappingURL=stdin-parser.js.map

package/dist/config/schema.d.ts

@@ -202,13 +202,4 @@ export type InferredCommandSectionsConfig = z.infer<typeof commandSectionsSchema
 export type InferredProjectConfig = z.infer<typeof projectConfigSchema>;
 /** 설정 파일명 */
 export declare const CONFIG_FILENAME = "vibe-commander.config.json";
-/**
- * 프로젝트 설정 스키마를 JSON Schema (Draft 2020-12) 형식으로 반환한다
- *
- * Zod 4의 z.toJSONSchema() 내장 기능을 활용하여 변환.
- * 에이전트가 설정 파일 구조를 런타임에 조회할 수 있도록 한다.
- *
- * @returns JSON Schema 호환 객체
- */
-export declare function getConfigJsonSchema(): Record<string, unknown>;
 //# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.js

@@ -12,27 +12,43 @@ import { z } from 'zod';
 /** 기본 경로 설정 스키마 */
 export const pathsSchema = z.object({
     /** 커맨드 파일 경로 (프로젝트 루트 기준) */
-    commands: z.string().default('commands.md'),
+    commands: z
+        .string()
+        .default('commands.md')
+        .describe('Command file path where unit context sections are managed'),
     /** 로드맵 파일 경로. null이면 list-units 비활성화 */
-    roadmap: z.string().nullable().default('roadmap.md'),
+    roadmap: z
+        .string()
+        .nullable()
+        .default('roadmap.md')
+        .describe('Roadmap/backlog file path. Set to null to disable list-units command'),
     /** 역할별 문서 루트 디렉토리 (키: 역할명, 값: 상대 경로) */
-    docRoots: z.record(z.string(), z.string()).default({
+    docRoots: z
+        .record(z.string(), z.string())
+        .default({
         plan: 'unit-plans',
         result: 'unit-results',
         runbook: 'unit-runbooks',
-    }),
+    })
+        .describe('Document root directories by role (key: role name, value: relative path)'),
     /** 리팩토링 서브유닛 디렉토리. null이면 서브유닛 미사용 */
-    refactorSubDir: z.string().nullable().default(null),
+    refactorSubDir: z
+        .string()
+        .nullable()
+        .default(null)
+        .describe('Refactoring sub-unit directory. Set to null if sub-units are not used'),
 });
 // ── 유닛 유형 ──
 /** 유닛 유형 정의 스키마 */
 export const unitTypeSchema = z.object({
     /** 유형 키 (예: "implement", "refactor") */
-    key: z.string(),
+    key: z.string().describe("Unique type key (e.g. 'implement', 'refactor', 'feature')"),
     /** 표시 이름 (예: "유닛 구현"). 미제공 시 key 값 활용 */
-    displayName: z.string().optional(),
+    displayName: z.string().optional().describe('Human-readable display name for this type'),
     /** 유닛 ID 매칭 정규식 패턴 (예: "^(U-\\d+|CP-).*") */
-    idPattern: z.string().refine((val) => {
+    idPattern: z
+        .string()
+        .refine((val) => {
         try {
             new RegExp(val);
             return true;
@@ -40,46 +56,83 @@ export const unitTypeSchema = z.object({
         catch {
             return false;
         }
-    }, { message: '유효한 정규식 문자열이어야 합니다' }),
+    }, { message: '유효한 정규식 문자열이어야 합니다' })
+        .describe("Regex pattern to match unit IDs (e.g. '^U-\\\\d+.*', '^FEAT-\\\\d+$')"),
     /** 계획서 디렉토리 (paths.docRoots 키 참조) */
-    planDir: z.string(),
+    planDir: z.string().describe('Document root key (from paths.docRoots) where plans are stored'),
     /** 커맨드 파일 내 대상 섹션 헤더 (예: "# 유닛 구현") */
-    commandSection: z.string(),
+    commandSection: z
+        .string()
+        .describe("Target section header in the command file (e.g. '# Unit Implementation')"),
     /** 의존성 수집 여부 */
-    collectDeps: z.boolean(),
+    collectDeps: z
+        .boolean()
+        .describe('Whether to collect dependency documents and commits for this type'),
     /** 섹션 헤더 템플릿. {{unitId}}, {{title}} 등 변수 치환 지원 */
-    headerTemplate: z.string(),
+    headerTemplate: z
+        .string()
+        .describe('Section header template with variable interpolation: {{unitId}}, {{title}}, {{titleOnly}}, {{planPath}}, {{shortId}}'),
 });
 // ── 문서 탐색 ──
 /** 개별 문서 역할의 탐색 규칙 스키마 */
 export const docDiscoveryRuleSchema = z.object({
     /** 파일 탐색 패턴 (예: "{{unitId}}.md") */
-    pattern: z.string(),
+    pattern: z
+        .string()
+        .describe('File search pattern. Supports {{unitId}} and {{shortId}} variables'),
     /** glob 패턴 사용 여부 (기본: false) */
-    glob: z.boolean().optional().default(false),
+    glob: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Whether to use glob matching (true) or exact match (false)'),
 });
 /** 문서 탐색 설정 스키마 (역할별 규칙 맵) */
-export const docDiscoverySchema = z.record(z.string(), docDiscoveryRuleSchema);
+export const docDiscoverySchema = z
+    .record(z.string(), docDiscoveryRuleSchema)
+    .describe('Document discovery rules by role. Defines file name patterns for finding unit documents');
 // ── 계획서 파싱 ──
 /** 메타데이터 테이블 파싱 설정 스키마 */
 export const metadataTableSchema = z.object({
     /** ID 필드명 */
-    idField: z.string().default('Unit ID'),
+    idField: z
+        .string()
+        .default('Unit ID')
+        .describe('Field name for the unit ID in the metadata table'),
     /** Phase 필드명 */
-    phaseField: z.string().default('Phase'),
+    phaseField: z
+        .string()
+        .default('Phase')
+        .describe('Field name for the phase in the metadata table'),
     /** 의존성 필드명 */
-    dependsField: z.string().default('의존성'),
+    dependsField: z
+        .string()
+        .default('의존성')
+        .describe('Field name for dependencies in the metadata table'),
 });
 /** 계획서 파싱 설정 스키마 */
 export const planParsingSchema = z.object({
     /** 제목 추출 소스 ("h1" | "frontmatter:title") */
-    titleSource: z.enum(['h1', 'frontmatter:title']).default('h1'),
+    titleSource: z
+        .enum(['h1', 'frontmatter:title'])
+        .default('h1')
+        .describe("How to extract the unit title: 'h1' from first heading, 'frontmatter:title' from YAML frontmatter"),
     /** 의존성 추출 소스 ("section" | "frontmatter" | "metadata-table") */
-    dependsSource: z.enum(['section', 'frontmatter', 'metadata-table']).default('section'),
+    dependsSource: z
+        .enum(['section', 'frontmatter', 'metadata-table'])
+        .default('section')
+        .describe("How to extract dependencies: 'section' from markdown section, 'frontmatter' from YAML, 'metadata-table' from 2-column table"),
     /** 의존성 섹션 헤더명. null이면 섹션 기반 추출 비활성화 */
-    dependsSectionName: z.string().nullable().default('이전 작업에서 가져올 것'),
+    dependsSectionName: z
+        .string()
+        .nullable()
+        .default('이전 작업에서 가져올 것')
+        .describe('Dependency section header name. Set to null to disable section-based extraction'),
     /** 페어링 질문 섹션 헤더명 */
-    pairingQuestionSection: z.string().default('페어링 질문'),
+    pairingQuestionSection: z
+        .string()
+        .default('페어링 질문')
+        .describe('Section header name for pairing questions (checkbox items)'),
     /** 메타데이터 테이블 파싱 설정 */
     metadataTable: metadataTableSchema.prefault({}),
 });
@@ -87,24 +140,28 @@ export const planParsingSchema = z.object({
 /** 상태 표시 매핑 스키마 */
 export const statusMapSchema = z.object({
     /** 대기 상태 표시 */
-    ready: z.string().default('⏸️'),
+    ready: z.string().default('⏸️').describe('Ready/waiting status indicator'),
     /** 진행중 상태 표시 */
-    inProgress: z.string().default('🚧'),
+    inProgress: z.string().default('🚧').describe('In-progress status indicator'),
     /** 완료 상태 표시 */
-    completed: z.string().default('✅'),
+    completed: z.string().default('✅').describe('Completed status indicator'),
     /** 차단 상태 표시 */
-    blocked: z.string().default('❌'),
+    blocked: z.string().default('❌').describe('Blocked status indicator'),
 });
 /** 백로그(로드맵) 파싱 설정 스키마 */
 export const backlogParsingSchema = z.object({
     /** 백로그 섹션 시작 헤더 */
-    sectionHeader: z.string().default('## 작업 백로그'),
+    sectionHeader: z
+        .string()
+        .default('## 작업 백로그')
+        .describe('Backlog section start header in the roadmap file'),
     /** 백로그 항목 매칭 정규식 (named group 지원) */
     entryPattern: z
         .string()
-        .default('ID=\\[(?<id>.+?)\\]\\((?<path>[^)]+)\\)\\s*\\|\\s*(?<title>[^|]+)\\|\\s*Depends=(?<deps>[^|]*)\\|\\s*(?<status>.+)'),
+        .default('ID=\\[(?<id>.+?)\\]\\((?<path>[^)]+)\\)\\s*\\|\\s*(?<title>[^|]+)\\|\\s*Depends=(?<deps>[^|]*)\\|\\s*(?<status>.+)')
+        .describe('Regex pattern with named groups (id, path, title, deps, status) to match backlog entries'),
     /** 완료된 유닛 섹션 헤더 */
-    completedSection: z.string().default('### 완료'),
+    completedSection: z.string().default('### 완료').describe('Section header for completed units'),
     /** 상태 문자열 ↔ 내부 상태 키 매핑 */
     statusMap: statusMapSchema.prefault({}),
 });
@@ -112,40 +169,64 @@ export const backlogParsingSchema = z.object({
 /** 커밋 탐색 설정 스키마 */
 export const commitSearchSchema = z.object({
     /** 탐색 전략 ("git-log-grep" | "conventional-commit" | "disabled") */
-    strategy: z.string().default('git-log-grep'),
+    strategy: z
+        .string()
+        .default('git-log-grep')
+        .describe("Search strategy: 'git-log-grep', 'conventional-commit', or 'disabled'"),
     /** grep에 사용할 ID 변환 방식 (예: "shortId") */
-    extractId: z.string().default('shortId'),
+    extractId: z
+        .string()
+        .default('shortId')
+        .describe("ID transformation for grep: 'shortId' removes phase tag (e.g. U-001[Mvp] → U-001)"),
     /** 최대 결과 수 */
-    maxResults: z.number().default(5),
+    maxResults: z.number().default(5).describe('Maximum number of commits to return per dependency'),
     /**
      * 제외할 경로 glob 패턴 목록.
      * 변경 파일이 모두 이 패턴에 매칭되는 커밋은 필터링됨 (문서 전용 커밋 제거).
      * 기본값 [] → 필터 미적용
      */
-    excludePaths: z.array(z.string()).default([]),
+    excludePaths: z
+        .array(z.string())
+        .default([])
+        .describe("Glob patterns for paths to exclude (e.g. 'docs/**' to filter doc-only commits)"),
     /**
      * 필수 포함 경로 glob 패턴 목록.
      * 변경 파일 중 하나라도 이 패턴에 매칭되어야 통과 (소스 코드 커밋만 허용).
      * 기본값 [] → 필터 미적용
      */
-    requirePaths: z.array(z.string()).default([]),
+    requirePaths: z
+        .array(z.string())
+        .default([])
+        .describe("Glob patterns that at least one changed file must match (e.g. 'src/**' for source-only commits)"),
 });
 // ── 커맨드 파일 섹션 ──
 /** 커맨드 파일 섹션 설정 스키마 */
 export const commandSectionsSchema = z.object({
     /** 섹션 구분자 문자열 */
-    separator: z.string().default('---------------------------------------------------'),
+    separator: z
+        .string()
+        .default('---------------------------------------------------')
+        .describe('Section separator string in the command file'),
     /** 다른 섹션 보존 여부 */
-    preserveOtherSections: z.boolean().default(true),
+    preserveOtherSections: z
+        .boolean()
+        .default(true)
+        .describe('Whether to preserve sections not managed by the current unit type'),
     /** Commit SHA를 기록할 필드 키워드 (기본: "Commit") */
-    commitFieldName: z.string().default('Commit'),
+    commitFieldName: z
+        .string()
+        .default('Commit')
+        .describe('Field keyword for recording commit SHA in the command file'),
     /**
      * HTML 주석 마커 사용 여부.
      * true이면 섹션 경계에 `<!-- vc:begin:{key} -->` / `<!-- vc:end:{key} -->` 마커를 삽입하고,
      * 섹션 탐색 시 마커를 우선 사용한다 (Fallback으로 기존 헤더 기반 탐색).
      * 기본값 false로 기존 프로젝트 하위 호환 보장.
      */
-    useMarkers: z.boolean().default(false),
+    useMarkers: z
+        .boolean()
+        .default(false)
+        .describe('Use HTML comment markers (<!-- vc:begin/end -->) for safer section boundary detection'),
 });
 // ── 최상위 설정 ──
 /** 기본 문서 탐색 설정 */
@@ -157,13 +238,16 @@ export const DEFAULT_DOC_DISCOVERY = {
 /** 프로젝트 설정 스키마 (vibe-commander.config.json) */
 export const projectConfigSchema = z.object({
     /** JSON Schema URL (IDE 자동완성용) */
-    $schema: z.string().optional(),
+    $schema: z.string().optional().describe('JSON Schema URL for IDE autocomplete and validation'),
     /** 설정 파일 버전 (현재 1 고정) */
-    version: z.literal(1),
+    version: z.literal(1).describe('Configuration file version (currently 1)'),
     /** 기본 경로 설정 */
     paths: pathsSchema.prefault({}),
     /** 유닛 유형 정의 배열 (순서 = ID 매칭 우선순위, 최소 1개 필수) */
-    unitTypes: z.array(unitTypeSchema).min(1),
+    unitTypes: z
+        .array(unitTypeSchema)
+        .min(1)
+        .describe('Unit type definitions. Array order determines ID matching priority (first match wins)'),
     /** 문서 탐색 규칙 (역할별) */
     docDiscovery: docDiscoverySchema.default(DEFAULT_DOC_DISCOVERY),
     /** 계획서 파싱 규칙 */
@@ -175,23 +259,21 @@ export const projectConfigSchema = z.object({
     /** 커맨드 파일 섹션 설정 */
     commandSections: commandSectionsSchema.prefault({}),
     /** 기본 특별 요청사항 목록 */
-    defaultSpecialRequests: z.array(z.string()).default([]),
+    defaultSpecialRequests: z
+        .array(z.string())
+        .default([])
+        .describe('Default special request strings appended to every unit context'),
     /** 유닛 유형별 추가 특별 요청사항 (키: unitType.key) */
-    specialRequestsByType: z.record(z.string(), z.array(z.string())).default({}),
+    specialRequestsByType: z
+        .record(z.string(), z.array(z.string()))
+        .default({})
+        .describe('Additional special requests per unit type (key: unitType.key, value: string array)'),
     /** 키 기반 선택적 특별 요청사항 (--request 옵션용, 키: 사용자 정의 식별자, 값: 텍스트) */
-    customRequests: z.record(z.string(), z.string()).default({}),
+    customRequests: z
+        .record(z.string(), z.string())
+        .default({})
+        .describe('Named special requests selectable via --request option (key: identifier, value: text)'),
 });
 /** 설정 파일명 */
 export const CONFIG_FILENAME = 'vibe-commander.config.json';
-/**
- * 프로젝트 설정 스키마를 JSON Schema (Draft 2020-12) 형식으로 반환한다
- *
- * Zod 4의 z.toJSONSchema() 내장 기능을 활용하여 변환.
- * 에이전트가 설정 파일 구조를 런타임에 조회할 수 있도록 한다.
- *
- * @returns JSON Schema 호환 객체
- */
-export function getConfigJsonSchema() {
-    return z.toJSONSchema(projectConfigSchema);
-}
 //# sourceMappingURL=schema.js.map

package/dist/core/renderers/index.d.ts

@@ -12,6 +12,6 @@ export { updateSection, updateField } from './section-updater.js';
 export type { UpdateResult, MarkerOptions } from './section-updater.js';
 export { createBeginMarker, createEndMarker, findMarkerRange, isValidSectionKey, wrapWithMarkers, stripMarkers, } from './marker-utils.js';
 export type { MarkerRange } from './marker-utils.js';
-export { COMMAND_REGISTRY, SCHEMA_SUBCOMMANDS, renderCommandsSchema, renderTypesSchema, } from './schema-renderer.js';
+export { COMMAND_REGISTRY, SCHEMA_SUBCOMMANDS, renderConfigSchema, renderCommandsSchema, renderTypesSchema, } from './schema-renderer.js';
 export type { ArgSchema, FlagSchema, CommandSchema, TypeSchemaEntry, SchemaSubcommandInfo, SchemaResult, } from './schema-renderer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/renderers/index.js

@@ -16,5 +16,5 @@ export { updateSection, updateField } from './section-updater.js';
 // 마커 유틸리티
 export { createBeginMarker, createEndMarker, findMarkerRange, isValidSectionKey, wrapWithMarkers, stripMarkers, } from './marker-utils.js';
 // 스키마 렌더러
-export { COMMAND_REGISTRY, SCHEMA_SUBCOMMANDS, renderCommandsSchema, renderTypesSchema, } from './schema-renderer.js';
+export { COMMAND_REGISTRY, SCHEMA_SUBCOMMANDS, renderConfigSchema, renderCommandsSchema, renderTypesSchema, } from './schema-renderer.js';
 //# sourceMappingURL=index.js.map

package/dist/core/renderers/marker-utils.js

@@ -10,10 +10,12 @@
  * @module
  */
 import { stripCR } from '../parsers/md-utils.js';
+/** HTML 주석 마커의 네임스페이스 접두어 */
+const MARKER_PREFIX = 'vc';
 /** sectionKey 허용 패턴: 영문 소문자 시작, 소문자+숫자+하이픈 */
 const SECTION_KEY_RE = /^[a-z][a-z0-9-]*$/;
 /** 마커 라인 매칭 정규식 */
-const MARKER_LINE_RE = /^<!--\s*vc:(begin|end):([a-z][a-z0-9-]*)\s*-->$/;
+const MARKER_LINE_RE = new RegExp(`^<!--\\s*${MARKER_PREFIX}:(begin|end):([a-z][a-z0-9-]*)\\s*-->$`);
 /**
  * sectionKey가 유효한지 검증한다
  *
@@ -28,7 +30,7 @@ export function isValidSectionKey(key) {
  * @example createBeginMarker('implement') → '<!-- vc:begin:implement -->'
  */
 export function createBeginMarker(sectionKey) {
-    return `<!-- vc:begin:${sectionKey} -->`;
+    return `<!-- ${MARKER_PREFIX}:begin:${sectionKey} -->`;
 }
 /**
  * end 마커 문자열을 생성한다
@@ -36,7 +38,7 @@ export function createBeginMarker(sectionKey) {
  * @example createEndMarker('implement') → '<!-- vc:end:implement -->'
  */
 export function createEndMarker(sectionKey) {
-    return `<!-- vc:end:${sectionKey} -->`;
+    return `<!-- ${MARKER_PREFIX}:end:${sectionKey} -->`;
 }
 /**
  * 라인 배열에서 지정된 sectionKey의 마커 범위를 찾는다

package/dist/core/renderers/schema-renderer.d.ts

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { z } from 'zod';
 import type { UnitTypeConfig } from '../../types/index.js';
 /** CLI 커맨드 인자 스키마 */
 export interface ArgSchema {
@@ -69,6 +70,21 @@ export type SchemaResult = {
 export declare const COMMAND_REGISTRY: CommandSchema[];
 /** schema 서브커맨드 도움말 정보 */
 export declare const SCHEMA_SUBCOMMANDS: SchemaSubcommandInfo[];
+/**
+ * 프로젝트 설정 스키마를 JSON Schema (Draft 2020-12) 형식으로 렌더링한다
+ *
+ * Zod 4의 z.toJSONSchema() 내장 기능을 활용하여 변환.
+ * 에이전트가 설정 파일 구조를 런타임에 조회할 수 있도록 한다.
+ *
+ * @param schema - 변환할 Zod 스키마
+ * @param metadata - 스키마 메타데이터 ($id, title, description)
+ * @returns JSON Schema 호환 객체
+ */
+export declare function renderConfigSchema(schema: z.ZodType, metadata?: {
+    id?: string;
+    title?: string;
+    description?: string;
+}): Record<string, unknown>;
 /**
  * 커맨드 메타데이터를 구조화된 형태로 렌더링한다
  *

package/dist/core/renderers/schema-renderer.js

@@ -7,6 +7,7 @@
  *
  * @module
  */
+import { z } from 'zod';
 // ── 커맨드 레지스트리 (정적 메타데이터) ──
 const GLOBAL_FLAGS = [
     { name: '--help', alias: '-h', type: 'boolean', description: '도움말 출력' },
@@ -127,6 +128,26 @@ export const SCHEMA_SUBCOMMANDS = [
     { name: 'types', description: '현재 프로젝트의 유닛 유형 목록 + ID 패턴 출력' },
 ];
 // ── 공개 API ──
+/**
+ * 프로젝트 설정 스키마를 JSON Schema (Draft 2020-12) 형식으로 렌더링한다
+ *
+ * Zod 4의 z.toJSONSchema() 내장 기능을 활용하여 변환.
+ * 에이전트가 설정 파일 구조를 런타임에 조회할 수 있도록 한다.
+ *
+ * @param schema - 변환할 Zod 스키마
+ * @param metadata - 스키마 메타데이터 ($id, title, description)
+ * @returns JSON Schema 호환 객체
+ */
+export function renderConfigSchema(schema, metadata) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+    const jsonSchema = z.toJSONSchema(schema);
+    return {
+        ...jsonSchema,
+        ...(metadata?.id && { $id: metadata.id }),
+        ...(metadata?.title && { title: metadata.title }),
+        ...(metadata?.description && { description: metadata.description }),
+    };
+}
 /**
  * 커맨드 메타데이터를 구조화된 형태로 렌더링한다
  *

package/dist/core/resolvers/index.d.ts

@@ -8,8 +8,6 @@
 export { resolveDepDocs } from './dep-doc-resolver.js';
 export type { DepDocPattern } from './dep-doc-resolver.js';
 export { findDepCommits } from './dep-commit-resolver.js';
-export type { CommitEntry } from './dep-commit-resolver.js';
 export { filterCommitsByChangedFiles, matchesGlobPattern } from './commit-filter.js';
-export type { CommitWithFiles, CommitFilterOptions } from './commit-filter.js';
 export { mergeConfigs, isPlainObject } from './config-merger.js';
 //# sourceMappingURL=index.d.ts.map

package/examples/nextjs-web.config.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://raw.githubusercontent.com/viilab/vibe-commander/main/schemas/config-schema.json",
+  "version": 1,
+
+  "paths": {
+    "commands": ".cursor/context.md",
+    "roadmap": "docs/backlog.md",
+    "docRoots": {
+      "spec": "docs/specs",
+      "result": "docs/results"
+    },
+    "refactorSubDir": null
+  },
+
+  "unitTypes": [
+    {
+      "key": "feature",
+      "displayName": "Feature",
+      "idPattern": "^FEAT-\\d+$",
+      "planDir": "spec",
+      "commandSection": "# Current Feature",
+      "collectDeps": true,
+      "headerTemplate": "### Feature: {{title}}\n- Spec: @{{planPath}}\n- Latest Commit: -"
+    },
+    {
+      "key": "bugfix",
+      "displayName": "Bugfix",
+      "idPattern": "^BUG-\\d+$",
+      "planDir": "spec",
+      "commandSection": "# Current Bugfix",
+      "collectDeps": true,
+      "headerTemplate": "### Bugfix: {{title}}\n- Spec: @{{planPath}}\n- Latest Commit: -"
+    }
+  ],
+
+  "planParsing": {
+    "titleSource": "frontmatter:title",
+    "dependsSource": "frontmatter",
+    "dependsSectionName": null,
+    "pairingQuestionSection": "Open Questions"
+  },
+
+  "backlogParsing": {
+    "sectionHeader": "## Backlog",
+    "entryPattern": "- \\[(?<status>.)\\] (?<id>\\S+) — (?<title>.+?)(?:\\s*\\(deps: (?<deps>[^)]+)\\))?$",
+    "completedSection": "### Done",
+    "statusMap": {
+      "ready": " ",
+      "inProgress": "~",
+      "completed": "x",
+      "blocked": "!"
+    }
+  },
+
+  "commitSearch": {
+    "strategy": "git-log-grep",
+    "extractId": "shortId",
+    "maxResults": 3,
+    "excludePaths": ["docs/**", "*.md"],
+    "requirePaths": ["src/**", "app/**"]
+  },
+
+  "commandSections": {
+    "separator": "---",
+    "preserveOtherSections": true,
+    "useMarkers": false
+  },
+
+  "defaultSpecialRequests": [
+    "**Use Next.js App Router patterns**",
+    "**Run `pnpm test` before marking complete**"
+  ]
+}