@byh3071/vhk 1.3.1 → 1.4.0

package/README.md

@@ -1,12 +1,12 @@
 ---
 id: vhk-readme
 date: 2026-05-28
-tags: [vhk, cli, readme, v1.3.0, ga]
+tags: [vhk, cli, readme, v1.4.0, ga]
 ---
 
 # 🔧 VHK — Vibe Harness Kit
 
-> 🎉 **v1.3.0** — 바이브코더의 올인원 CLI. 컨텍스트 + 자율 하네스.
+> 🎉 **v1.4.0** — 바이브코더의 올인원 CLI. 컨텍스트 + 자율 하네스 + 포터빌리티.
 >
 > AI 코딩 에이전트를 부리는 사람을 위한 **한국어 풀사이클 CLI**.
 >
@@ -115,11 +115,13 @@ vhk 기획 끝났고 바로 시작
 | `vhk gate` | `검증`, `아이디어` | 아이디어 검증 (퀵 5문항 / 풀 13문항 / 스킵) |
 | `vhk init` | `시작`, `만들기` | 프로젝트 초기화 + 하네스 생성 |
 | `vhk recap` | `정리`, `오늘` | Git 변경 → `docs/log/` 세션 로그 |
-| `vhk sync` | `규칙`, `맞추기` | RULES.md → `.cursorrules` + CLAUDE.md |
+| `vhk sync` | `규칙`, `맞추기` | RULES.md → `.cursorrules` + CLAUDE.md + `.windsurfrules` |
 | `vhk check` | `점검`, `린트` | RULES.md 규칙 위반 검사 |
 | `vhk secure` | `보안` | 시크릿·키 유출 스캔 (`scan` / `스캔` 동일). **CRITICAL/HIGH 발견 시 exit code 1** (CI용) |
 | `vhk ship` | `출하` | 배포 체크리스트 + 회고 + 빌드 로그 |
 | `vhk doctor` | `환경`, `진단` | Node / npm / pnpm / Git 환경 점검 |
+| `vhk cloud push` | `클라우드`, `올리기` | `.vhk/` 를 GitHub secret gist 로 백업 (gh CLI 인증 사용) |
+| `vhk cloud pull` | `내리기` | gist 에서 `.vhk/` 복원 (`vhk cloud pull <gistId>` 또는 cloud.json) |
 | `vhk save` | `저장`, `커밋` | git add · commit · push 한 번에 |
 | `vhk undo` | `되돌리기`, `취소` | 최근 커밋 soft reset (변경은 staged 유지) |
 | `vhk diff` | `변경`, `차이` | staged / unstaged / 새 파일 요약 (줄 수 합계는 tracked·HEAD 기준) |
@@ -340,8 +342,26 @@ vhk ref open 1          # 1번 레퍼런스를 브라우저로 열기
 - `docs/PRD.md`, `docs/ARCHITECTURE.md`
 - `docs/adr/`, `docs/log/`, `docs/troubleshooting/`
 - `COMMANDS.md`, `BACKLOG.md` (프로젝트 유형에 따라)
+- `.vhk/README.md` + `.vhk/context.md` (유형별 씨앗 — 규격: [`docs/spec.md`](docs/spec.md))
+- `.vhk/.gitignore` + `.vhkignore` (로컬 전용·클라우드 제외 규칙)
+- 루트 `.gitignore` (`.env`·`node_modules`·`dist` 보호 — 기존 파일은 보존하고 누락분만 추가)
 - `package.json` scripts: `save`, `check`, `scan`, `recap`, `ship`, `doctor` → `vhk` 호출
 
+## 클라우드 백업 (vhk cloud)
+
+`.vhk/` 프로젝트 맥락을 GitHub **secret gist** 로 백업·복원합니다. 컴퓨터를 바꿔도
+규칙·맥락이 따라옵니다. 규격은 [`docs/spec.md`](docs/spec.md) 참조.
+
+```bash
+vhk cloud push          # .vhk/ → secret gist 백업 (gist id 는 .vhk/cloud.json 에 저장)
+vhk cloud pull          # cloud.json 의 gist 에서 복원
+vhk cloud pull <gistId> # 새 환경에서 gist id 로 직접 복원
+```
+
+- **인증:** `gh` CLI 사용 (`gh auth login`, gist 권한). 코드·설정에 토큰을 저장하지 않습니다.
+- **프라이버시:** gist 는 secret(비공개). 개인 메모(`memory.json`)·참고링크(`refs.json`)·
+  `HARD_STOP` 은 기본 제외됩니다. 추가 제외는 루트 `.vhkignore` 에 한 줄씩 적으세요.
+
 ## 자연어 예시
 
 | 말하면 | 실행 |

package/dist/{chunk-6S3JYYZ3.js → chunk-3DV7AEN4.js}

@@ -696,7 +696,9 @@ var ko = {
     gitHintCommand: 'git init && git add . && git commit -m "feat: \uD504\uB85C\uC81D\uD2B8 \uC2DC\uC791"',
     startDev: "\uC774\uC81C \uAC1C\uBC1C\uD574 \uBCF4\uC138\uC694! \u{1F680}",
     commandsMdDone: "\u{1F4CB} COMMANDS.md \uC0DD\uC131",
-    scriptsDone: "\u{1F4E6} package.json scripts \uCD94\uAC00"
+    scriptsDone: "\u{1F4E6} package.json scripts \uCD94\uAC00",
+    gitignoreCreated: "\u{1F512} .gitignore \uC0DD\uC131 (.env\xB7node_modules\xB7dist \uC81C\uC678)",
+    gitignoreUpdated: "\u{1F512} .gitignore \uBCF4\uAC15 (\uB204\uB77D \uD56D\uBAA9 \uCD94\uAC00)"
   },
   recap: {
     title: "\u{1F4DD} \uC624\uB298 \uD55C \uC77C \uC815\uB9AC",
@@ -752,8 +754,22 @@ var ko = {
     noRules: "\u26A0\uFE0F RULES.md \uD30C\uC77C\uC774 \uC5C6\uC5B4\uC694.",
     cursorrulesDone: "\u2705 .cursorrules \uB9DE\uCDA4 \uC644\uB8CC",
     claudeDone: "\u2705 CLAUDE.md \uB9DE\uCDA4 \uC644\uB8CC",
+    windsurfDone: "\u2705 .windsurfrules \uB9DE\uCDA4 \uC644\uB8CC",
     done: "\u{1F504} \uB9DE\uCD94\uAE30 \uC644\uB8CC!"
   },
+  cloud: {
+    pushTitle: "\u2601\uFE0F .vhk \uD074\uB77C\uC6B0\uB4DC \uBC31\uC5C5 (gist \uC62C\uB9AC\uAE30)",
+    pullTitle: "\u2601\uFE0F .vhk \uD074\uB77C\uC6B0\uB4DC \uBCF5\uC6D0 (gist \uB0B4\uB9AC\uAE30)",
+    noGh: "gh CLI \uAC00 \uC124\uCE58\uB418\uC5B4 \uC788\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+    noAuth: "gh \uC778\uC99D\uC774 \uD544\uC694\uD569\uB2C8\uB2E4 (gist \uAD8C\uD55C).",
+    noVhkDir: ".vhk/ \uD3F4\uB354\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4. vhk init \uB610\uB294 vhk context \uB97C \uBA3C\uC800 \uC2E4\uD589\uD558\uC138\uC694.",
+    nothingToSync: "\uBC31\uC5C5\uD560 \uD30C\uC77C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4 (.vhkignore \uB85C \uBAA8\uB450 \uC81C\uC678\uB428).",
+    noGistId: "\uBCF5\uC6D0\uD560 gist id \uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.",
+    pushDone: "\u2705 \uD074\uB77C\uC6B0\uB4DC \uBC31\uC5C5 \uC644\uB8CC",
+    pullDone: "\u2705 \uD074\uB77C\uC6B0\uB4DC \uBCF5\uC6D0 \uC644\uB8CC",
+    pushFail: "\u274C \uBC31\uC5C5 \uC2E4\uD328",
+    pullFail: "\u274C \uBCF5\uC6D0 \uC2E4\uD328"
+  },
   ship: {
     title: "\u{1F680} \uBC30\uD3EC \uCCB4\uD06C\uB9AC\uC2A4\uD2B8",
     checklist: "\u{1F4CB} \uBC30\uD3EC \uC804 \uCCB4\uD06C\uB9AC\uC2A4\uD2B8",
@@ -2134,9 +2150,11 @@ async function startMcpServer() {
 }
 
 export {
+  __toESM,
   ko,
   t,
   printNextStep,
+  require_ignore,
   printSecurityWarnings,
   filterTrackedPaths,
   readJsonFile,

package/dist/index.js

@@ -2,6 +2,7 @@
 import {
   MAX_SCAN_FILE_BYTES,
   MAX_SECRET_FINDINGS,
+  __toESM,
   audit,
   deploy,
   env,
@@ -14,11 +15,12 @@ import {
   printSecurityWarnings,
   publish,
   readJsonFile,
+  require_ignore,
   safeExecFile,
   scanProjectForSecrets,
   startMcpServer,
   t
-} from "./chunk-6S3JYYZ3.js";
+} from "./chunk-3DV7AEN4.js";
 
 // src/index.ts
 import { Command, Help } from "commander";
@@ -40,6 +42,19 @@ function matchesKeywords(text, command) {
   return keywords.some((kw) => text.includes(kw.toLowerCase()));
 }
 var RULES = [
+  // 영문 `vhk cloud push|pull [id]` 은 commander 가 직접 처리(가로채기 금지) — 한국어 표현만 매칭.
+  {
+    command: "cloud-pull",
+    explanation: "\uD074\uB77C\uC6B0\uB4DC\uC5D0\uC11C .vhk \uBCF5\uC6D0 (vhk cloud pull)",
+    confidence: "high",
+    test: (t2) => (/(클라우드|gist)\s*(에서)?\s*(복원|내려받?|내리|받아)/.test(t2) || /(\.?vhk\s*)?(복원해|복구해|복원\s*하|복구\s*하)/.test(t2)) && !/백업|올려|올리/.test(t2)
+  },
+  {
+    command: "cloud-push",
+    explanation: ".vhk \uB97C \uD074\uB77C\uC6B0\uB4DC\uC5D0 \uBC31\uC5C5 (vhk cloud push)",
+    confidence: "high",
+    test: (t2) => (/(클라우드|gist)\s*(에)?\s*(백업|올려|올리)/.test(t2) || /(\.?vhk\s*)?백업\s*해|(\.?vhk\s*)?백업하/.test(t2)) && !/복원|내려|내리|복구/.test(t2)
+  },
   {
     command: "start",
     explanation: "\uB178\uC158\uC5D0\uC11C \uAC00\uC838\uC640 \uC0C8 \uD504\uB85C\uC81D\uD2B8 \uC2DC\uC791 \uB9C8\uBC95\uC0AC (vhk start --from-notion)",
@@ -177,7 +192,7 @@ var RULES = [
     command: "save",
     explanation: "Git\uC5D0 \uC800\uC7A5 (vhk \uC800\uC7A5)",
     confidence: "high",
-    test: (t2) => (matchesKeywords(t2, "save") || /깃허브|github/.test(t2)) && !/정리|recap|되돌|취소|rollback|reset|리셋|롤백|원래대로/.test(t2)
+    test: (t2) => (matchesKeywords(t2, "save") || /깃허브|github/.test(t2)) && !/정리|recap|되돌|취소|rollback|reset|리셋|롤백|원래대로|클라우드|cloud|gist/.test(t2)
   },
   {
     command: "recap",
@@ -352,6 +367,8 @@ var KNOWN_COMMAND_TOKENS = /* @__PURE__ */ new Set([
   "\uAE30\uC5B5",
   "brief",
   "\uBE0C\uB9AC\uD551",
+  "cloud",
+  "\uD074\uB77C\uC6B0\uB4DC",
   "goal",
   "\uBAA9\uD45C",
   "blocker",
@@ -383,7 +400,7 @@ function detectNaturalLanguageInput(argv) {
 }
 
 // src/lib/nlp-run.ts
-import chalk26 from "chalk";
+import chalk27 from "chalk";
 import inquirer11 from "inquirer";
 
 // src/commands/gate.ts
@@ -738,6 +755,70 @@ function COMMANDS_MD_TEMPLATE() {
   ].join("\n");
 }
 
+// src/templates/vhk-dir.ts
+function VHK_README_TEMPLATE() {
+  return [
+    "# `.vhk/` \u2014 VHK runtime state",
+    "",
+    "\uC774 \uB514\uB809\uD1A0\uB9AC\uB294 VHK\uAC00 \uD504\uB85C\uC81D\uD2B8\uBCC4 \uC0C1\uD0DC\uB97C \uC800\uC7A5\uD558\uB294 \uACF3\uC785\uB2C8\uB2E4.",
+    "\uC804\uCCB4 \uADDC\uACA9\uC740 `docs/spec.md` (spec_version 1.0) \uCC38\uC870.",
+    "",
+    "## \uD2B8\uB798\uD0B9 \uC815\uCC45",
+    "",
+    "| \uD30C\uC77C | \uD2B8\uB798\uD0B9 | \uC6A9\uB3C4 |",
+    "| --- | --- | --- |",
+    "| `README.md` | \u2705 | \uBCF8 \uC548\uB0B4 |",
+    "| `context.md` | \u2705 | \uD504\uB85C\uC81D\uD2B8 \uB9E5\uB77D (`vhk context` \uB85C \uAC31\uC2E0) |",
+    "| `brief.md` | \u2705 | \uC0C1\uD0DC \uC694\uC57D \uBE0C\uB9AC\uD551 (`vhk brief`) |",
+    "| `memory.json` | \u274C \uB85C\uCEEC \uC804\uC6A9 | \uC758\uC0AC\uACB0\uC815 \uBA54\uBAA8 (`vhk memory add`) |",
+    "| `refs.json` | \u274C \uB85C\uCEEC \uC804\uC6A9 | \uCC38\uACE0 URL (`vhk ref add`) |",
+    "| `HARD_STOP` | \u274C \uB85C\uCEEC \uC804\uC6A9 | \uC874\uC7AC\uD558\uBA74 \uBAA8\uB4E0 \uC790\uB3D9\uD654 \uC989\uC2DC \uC911\uB2E8 |",
+    "",
+    "> `memory.json`\xB7`refs.json` \uC740 \uAC1C\uC778 \uBA54\uBAA8 \uB178\uCD9C \uBC29\uC9C0\uB97C \uC704\uD574 `.gitignore` \uC5D0 \uB4F1\uB85D\uB429\uB2C8\uB2E4.",
+    "> `HARD_STOP` \uD574\uC81C\uB294 `vhk resume --confirm` \uC73C\uB85C\uB9CC \uAC00\uB2A5\uD569\uB2C8\uB2E4.",
+    ""
+  ].join("\n");
+}
+function VHK_GITIGNORE_TEMPLATE() {
+  return [
+    "# VHK \uB85C\uCEEC \uC804\uC6A9 \u2014 \uAC1C\uC778 \uBA54\uBAA8/\uCC38\uACE0\uB9C1\uD06C/\uC548\uC804\uC2E0\uD638 (docs/spec.md \uD2B8\uB798\uD0B9 \uC815\uCC45)",
+    "memory.json",
+    "refs.json",
+    "HARD_STOP",
+    ""
+  ].join("\n");
+}
+function VHK_IGNORE_TEMPLATE() {
+  return [
+    "# vhk cloud push \uBC31\uC5C5\uC5D0\uC11C \uC81C\uC678\uD560 .vhk/ \uD30C\uC77C (\uD55C \uC904\uC5D0 \uD558\uB098)",
+    "# \uAE30\uBCF8 \uC81C\uC678(\uC790\uB3D9): memory.json, refs.json, HARD_STOP, cloud.json, .gitignore",
+    "# \uC608) \uC544\uB798 \uC8FC\uC11D\uC744 \uD480\uBA74 brief.md \uB3C4 \uBC31\uC5C5\uC5D0\uC11C \uC81C\uC678\uB429\uB2C8\uB2E4.",
+    "# brief.md",
+    ""
+  ].join("\n");
+}
+function VHK_CONTEXT_SEED(name, type, stack) {
+  const stackList = stack.map((s) => "- " + s).join("\n");
+  return [
+    "# " + name + " \u2014 \uD504\uB85C\uC81D\uD2B8 \uB9E5\uB77D",
+    "",
+    "> \u26A1 \uC774 \uD30C\uC77C\uC740 vhk init \uC774 \uC0DD\uC131\uD55C \uC528\uC557\uC785\uB2C8\uB2E4. `vhk context` \uB85C \uAC31\uC2E0\uD558\uC138\uC694.",
+    "",
+    "## \uD504\uB85C\uC81D\uD2B8 \uC720\uD615",
+    "- " + type,
+    "",
+    "## \uAE30\uC220 \uC2A4\uD0DD",
+    stackList,
+    "",
+    "## \uC8FC\uC694 \uACB0\uC815\uC0AC\uD56D",
+    "- (\uC544\uC9C1 \uC5C6\uC74C \u2014 `vhk memory add` \uB85C \uAE30\uB85D)",
+    "",
+    "## \uB2E4\uC74C \uB2E8\uACC4",
+    "- docs/PRD.md \uC791\uC131",
+    ""
+  ].join("\n");
+}
+
 // src/utils/logger.ts
 import chalk2 from "chalk";
 var log = {
@@ -995,7 +1076,7 @@ ${ko.init.recommendedStack} ${stack.join(" + ")}
     }
   }
   const cwd = process.cwd();
-  const files = generateFiles(answers.name, answers.description, stack, prdContent);
+  const files = generateFiles(answers.name, answers.description, stack, prdContent, answers.type);
   log.step(ko.init.filesGenerating);
   for (const [filePath, content] of Object.entries(files)) {
     const fullPath = path2.join(cwd, filePath);
@@ -1040,7 +1121,7 @@ ${ko.init.nextSteps}`));
     alternative: "VS Code/Cursor\uC5D0\uC11C \uD3F4\uB354\uB97C \uC5F4\uC5B4\uB3C4 \uB429\uB2C8\uB2E4"
   });
 }
-function generateFiles(name, description, stack, prdContent = {}) {
+function generateFiles(name, description, stack, prdContent = {}, type = "") {
   const stackStr = stack.join(" + ");
   const prd = {
     tagline: description,
@@ -1065,7 +1146,12 @@ function generateFiles(name, description, stack, prdContent = {}) {
 ## v1.1 \uD6C4\uBCF4
 
 - 
-`
+`,
+    // .vhk/ 씨앗 — 규격: docs/spec.md (spec_version 1.0)
+    ".vhk/README.md": VHK_README_TEMPLATE(),
+    ".vhk/context.md": VHK_CONTEXT_SEED(name, type || "unknown", stack),
+    ".vhk/.gitignore": VHK_GITIGNORE_TEMPLATE(),
+    ".vhkignore": VHK_IGNORE_TEMPLATE()
   };
 }
 var VHK_PACKAGE_SCRIPTS = {
@@ -1076,6 +1162,32 @@ var VHK_PACKAGE_SCRIPTS = {
   ship: "vhk ship",
   doctor: "vhk doctor"
 };
+var ROOT_GITIGNORE_ENTRIES = [
+  ".env",
+  ".env.local",
+  ".env.*.local",
+  "node_modules/",
+  "dist/",
+  "*.tsbuildinfo",
+  ".DS_Store"
+];
+function ensureRootGitignore(projectDir) {
+  const gitignorePath = path2.join(projectDir, ".gitignore");
+  if (!fs2.existsSync(gitignorePath)) {
+    fs2.writeFileSync(gitignorePath, ROOT_GITIGNORE_ENTRIES.join("\n") + "\n", "utf-8");
+    return "created";
+  }
+  const content = fs2.readFileSync(gitignorePath, "utf-8");
+  const existing = new Set(content.split("\n").map((l) => l.trim()));
+  const missing = ROOT_GITIGNORE_ENTRIES.filter((e) => !existing.has(e));
+  if (missing.length === 0) return "unchanged";
+  const prefix = content.endsWith("\n") ? "" : "\n";
+  fs2.appendFileSync(gitignorePath, `${prefix}
+# vhk init
+${missing.join("\n")}
+`, "utf-8");
+  return "updated";
+}
 function enhancePackageScripts(projectDir) {
   const pkgPath = path2.join(projectDir, "package.json");
   if (!fs2.existsSync(pkgPath)) return false;
@@ -1106,6 +1218,12 @@ async function writeInitExtras(projectDir) {
   if (enhancePackageScripts(projectDir)) {
     log.success(ko.init.scriptsDone);
   }
+  const gitignoreResult = ensureRootGitignore(projectDir);
+  if (gitignoreResult === "created") {
+    log.success(ko.init.gitignoreCreated);
+  } else if (gitignoreResult === "updated") {
+    log.success(ko.init.gitignoreUpdated);
+  }
 }
 
 // src/commands/recap.ts
@@ -1579,6 +1697,27 @@ function toCursorrules(sections, projectName) {
   }
   return lines.join("\n");
 }
+function toWindsurfrules(sections, projectName) {
+  const codingSections = sections.filter(
+    (s) => CURSORRULES_KEYS.some((k) => s.title.includes(k))
+  );
+  const lines = [
+    `# ${projectName} \u2014 Windsurf Rules`,
+    "",
+    "> \uCF54\uB529/\uB514\uC790\uC778 \uC804\uC6A9. \uAE30\uB85D/\uC6B4\uC601 \u2192 CLAUDE.md \uCC38\uC870.",
+    "> \u26A1 \uC774 \uD30C\uC77C\uC740 RULES.md\uC5D0\uC11C \uC790\uB3D9 \uC0DD\uC131\uB428 (vhk sync). \uC9C1\uC811 \uC218\uC815 \uAE08\uC9C0.",
+    "",
+    "## \uD544\uC218 \uCC38\uC870",
+    "- docs/PRD.md \xB7 docs/ARCHITECTURE.md \xB7 CLAUDE.md \xB7 RULES.md",
+    ""
+  ];
+  for (const section of codingSections) {
+    lines.push(`## ${section.title}`);
+    lines.push(section.content);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
 function toClaudeMd(sections, existing) {
   const recordSections = sections.filter(
     (s) => CLAUDE_MD_KEYS.some((k) => s.title.includes(k))
@@ -1638,9 +1777,12 @@ ${ko.sync.title}
 - **\uB9C8\uC9C0\uB9C9 \uC5C5\uB370\uC774\uD2B8:** ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}`;
   fs5.writeFileSync(claudePath, toClaudeMd(sections, existingClaude), "utf-8");
   console.log(chalk5.green(`  ${ko.sync.claudeDone}`));
+  const windsurfPath = path6.join(cwd, ".windsurfrules");
+  fs5.writeFileSync(windsurfPath, toWindsurfrules(sections, projectName), "utf-8");
+  console.log(chalk5.green(`  ${ko.sync.windsurfDone}`));
   console.log(chalk5.bold.green(`
 ${ko.sync.done}`));
-  console.log(chalk5.dim("  RULES.md (\uC6D0\uBCF8) \u2192 .cursorrules + CLAUDE.md (\uC790\uB3D9 \uC0DD\uC131)"));
+  console.log(chalk5.dim("  RULES.md (\uC6D0\uBCF8) \u2192 .cursorrules + CLAUDE.md + .windsurfrules (\uC790\uB3D9 \uC0DD\uC131)"));
   console.log(chalk5.dim("  \uADDC\uCE59 \uBCC0\uACBD\uC740 \uD56D\uC0C1 RULES.md\uC5D0\uC11C\uB9CC \uD558\uC138\uC694."));
   printNextStep({
     message: "\uADDC\uCE59 \uB3D9\uAE30\uD654 \uC644\uB8CC! \uC774\uC81C Cursor\uAC00 \uC0C8 \uADDC\uCE59\uC744 \uB530\uB985\uB2C8\uB2E4.",
@@ -4361,6 +4503,211 @@ ${ko.start.allDone}
   });
 }
 
+// src/commands/cloud.ts
+import fs13 from "fs";
+import path14 from "path";
+import chalk26 from "chalk";
+
+// src/lib/vhk-cloud.ts
+var import_ignore = __toESM(require_ignore(), 1);
+import fs12 from "fs";
+import path13 from "path";
+var DEFAULT_CLOUD_EXCLUDES = [
+  "memory.json",
+  // 개인 의사결정 메모
+  "refs.json",
+  // 개인 참고링크
+  "HARD_STOP",
+  // 로컬 안전 신호
+  "cloud.json",
+  // gist 포인터 (백업 대상 아님)
+  ".gitignore"
+  // .vhk/ 내부 gitignore
+];
+var VHK_DIR2 = ".vhk";
+var CLOUD_CONFIG_FILE = "cloud.json";
+function loadVhkignore(rootDir) {
+  const ig = (0, import_ignore.default)();
+  ig.add(DEFAULT_CLOUD_EXCLUDES);
+  const ignorePath = path13.join(rootDir, ".vhkignore");
+  if (fs12.existsSync(ignorePath)) {
+    ig.add(fs12.readFileSync(ignorePath, "utf-8"));
+  }
+  return ig;
+}
+function collectVhkFiles(rootDir, ig = loadVhkignore(rootDir)) {
+  const vhkDir = path13.join(rootDir, VHK_DIR2);
+  let entries;
+  try {
+    entries = fs12.readdirSync(vhkDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((e) => e.isFile()).map((e) => e.name).filter((name) => !ig.ignores(name)).sort();
+}
+function readCloudConfig(rootDir) {
+  const p = path13.join(rootDir, VHK_DIR2, CLOUD_CONFIG_FILE);
+  if (!fs12.existsSync(p)) return null;
+  try {
+    const parsed = JSON.parse(fs12.readFileSync(p, "utf-8"));
+    if (parsed && typeof parsed.gistId === "string" && parsed.gistId) {
+      return { gistId: parsed.gistId };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function writeCloudConfig(rootDir, config) {
+  const vhkDir = path13.join(rootDir, VHK_DIR2);
+  fs12.mkdirSync(vhkDir, { recursive: true });
+  const p = path13.join(vhkDir, CLOUD_CONFIG_FILE);
+  fs12.writeFileSync(p, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+// src/commands/cloud.ts
+function ensureGhReady() {
+  const ver = safeExecFile("gh", ["--version"]);
+  if (!ver.ok) {
+    console.log(chalk26.red(`  ${ko.cloud.noGh}`));
+    console.log(chalk26.dim("  \uC124\uCE58: https://cli.github.com/  (\uC124\uCE58 \uD6C4 `gh auth login`)"));
+    return false;
+  }
+  const auth = safeExecFile("gh", ["auth", "status"]);
+  if (!auth.ok) {
+    console.log(chalk26.red(`  ${ko.cloud.noAuth}`));
+    console.log(chalk26.dim("  \uC2E4\uD589: gh auth login  (gist \uAD8C\uD55C \uD544\uC694)"));
+    return false;
+  }
+  return true;
+}
+function parseGistId(output) {
+  const match = output.match(/gist\.github\.com\/(?:[^/]+\/)?([0-9a-f]+)/i);
+  if (match) return match[1];
+  const trimmed = output.trim();
+  if (/^[0-9a-f]{8,}$/i.test(trimmed)) return trimmed;
+  return null;
+}
+async function cloudPush() {
+  console.log(chalk26.bold(`
+${ko.cloud.pushTitle}
+`));
+  const cwd = process.cwd();
+  if (!fs13.existsSync(path14.join(cwd, VHK_DIR2))) {
+    console.log(chalk26.yellow(`  ${ko.cloud.noVhkDir}`));
+    return;
+  }
+  const files = collectVhkFiles(cwd);
+  if (files.length === 0) {
+    console.log(chalk26.yellow(`  ${ko.cloud.nothingToSync}`));
+    return;
+  }
+  if (!ensureGhReady()) {
+    process.exitCode = 1;
+    return;
+  }
+  const filePaths = files.map((f) => path14.join(cwd, VHK_DIR2, f));
+  console.log(chalk26.dim(`  \u{1F4E6} \uBC31\uC5C5 \uB300\uC0C1 ${files.length}\uAC1C: ${files.join(", ")}
+`));
+  const existing = readCloudConfig(cwd);
+  const desc = `vhk .vhk backup \u2014 ${path14.basename(cwd)}`;
+  if (existing) {
+    const gistFiles = listGistFiles(existing.gistId);
+    for (let i = 0; i < files.length; i++) {
+      const name = files[i];
+      const src = filePaths[i];
+      const args = gistFiles.includes(name) ? ["gist", "edit", existing.gistId, "-f", name, src] : ["gist", "edit", existing.gistId, "-a", src];
+      const res2 = safeExecFile("gh", args);
+      if (!res2.ok) {
+        console.log(chalk26.red(`  ${ko.cloud.pushFail}: ${name}`));
+        console.log(chalk26.dim(`    ${res2.err}`));
+        process.exitCode = 1;
+        return;
+      }
+    }
+    console.log(chalk26.green.bold(`  ${ko.cloud.pushDone}`));
+    console.log(chalk26.dim(`  gist: ${existing.gistId} (\uAC31\uC2E0)`));
+    printPushNext();
+    return;
+  }
+  const res = safeExecFile("gh", ["gist", "create", "--desc", desc, ...filePaths]);
+  if (!res.ok) {
+    console.log(chalk26.red(`  ${ko.cloud.pushFail}`));
+    console.log(chalk26.dim(`    ${res.err || res.out}`));
+    process.exitCode = 1;
+    return;
+  }
+  const gistId = parseGistId(res.out);
+  if (!gistId) {
+    console.log(chalk26.red(`  ${ko.cloud.pushFail} \u2014 gist id \uD30C\uC2F1 \uC2E4\uD328`));
+    console.log(chalk26.dim(`    \uCD9C\uB825: ${res.out}`));
+    process.exitCode = 1;
+    return;
+  }
+  writeCloudConfig(cwd, { gistId });
+  console.log(chalk26.green.bold(`  ${ko.cloud.pushDone}`));
+  console.log(chalk26.dim(`  gist: ${gistId} (\uC2E0\uADDC, secret) \u2192 .vhk/cloud.json \uC800\uC7A5`));
+  printPushNext();
+}
+async function cloudPull(gistIdArg) {
+  console.log(chalk26.bold(`
+${ko.cloud.pullTitle}
+`));
+  const cwd = process.cwd();
+  const gistId = gistIdArg || readCloudConfig(cwd)?.gistId;
+  if (!gistId) {
+    console.log(chalk26.yellow(`  ${ko.cloud.noGistId}`));
+    console.log(chalk26.dim("  \uC0AC\uC6A9\uBC95: vhk cloud pull <gistId>  (\uB610\uB294 cloud.json \uC774 \uC788\uB294 \uACF3\uC5D0\uC11C \uC2E4\uD589)"));
+    return;
+  }
+  if (!ensureGhReady()) {
+    process.exitCode = 1;
+    return;
+  }
+  const names = listGistFiles(gistId);
+  if (names.length === 0) {
+    console.log(chalk26.red(`  ${ko.cloud.pullFail} \u2014 gist \uBE44\uC5C8\uAC70\uB098 \uC811\uADFC \uBD88\uAC00: ${gistId}`));
+    process.exitCode = 1;
+    return;
+  }
+  const vhkDir = path14.join(cwd, VHK_DIR2);
+  fs13.mkdirSync(vhkDir, { recursive: true });
+  let restored = 0;
+  for (const name of names) {
+    const res = safeExecFile("gh", ["gist", "view", gistId, "-f", name, "--raw"]);
+    if (!res.ok) {
+      console.log(chalk26.red(`  ${ko.cloud.pullFail}: ${name}`));
+      console.log(chalk26.dim(`    ${res.err}`));
+      continue;
+    }
+    fs13.writeFileSync(path14.join(vhkDir, name), ensureTrailingNewline(res.out), "utf-8");
+    restored++;
+  }
+  writeCloudConfig(cwd, { gistId });
+  console.log(chalk26.green.bold(`  ${ko.cloud.pullDone}`));
+  console.log(chalk26.dim(`  ${restored}\uAC1C \uD30C\uC77C \uBCF5\uC6D0 (gist: ${gistId})`));
+  printNextStep({
+    message: "\uD074\uB77C\uC6B0\uB4DC\uC5D0\uC11C .vhk/ \uBCF5\uC6D0 \uC644\uB8CC!",
+    command: "vhk \uB9E5\uB77D",
+    cursorHint: "\uD504\uB85C\uC81D\uD2B8 \uB9E5\uB77D \uBCF4\uC5EC\uC918"
+  });
+}
+function listGistFiles(gistId) {
+  const res = safeExecFile("gh", ["gist", "view", gistId, "--files"]);
+  if (!res.ok) return [];
+  return res.out.split("\n").map((l) => l.trim()).filter(Boolean);
+}
+function ensureTrailingNewline(s) {
+  return s.endsWith("\n") ? s : s + "\n";
+}
+function printPushNext() {
+  printNextStep({
+    message: "\uD074\uB77C\uC6B0\uB4DC \uBC31\uC5C5 \uC644\uB8CC! \uB2E4\uB978 \uD658\uACBD\uC5D0\uC11C vhk cloud pull \uB85C \uBCF5\uC6D0\uD558\uC138\uC694.",
+    command: "vhk cloud pull",
+    cursorHint: "\uB2E4\uB978 \uCEF4\uD4E8\uD130\uC5D0\uC11C .vhk \uBCF5\uC6D0\uD574\uC918"
+  });
+}
+
 // src/lib/nlp-run.ts
 async function dispatchNlpRoute(route, input) {
   switch (route.command) {
@@ -4429,6 +4776,10 @@ async function dispatchNlpRoute(route, input) {
       return memoryList();
     case "brief":
       return brief();
+    case "cloud-push":
+      return cloudPush();
+    case "cloud-pull":
+      return cloudPull();
     case "goal": {
       const sub = route.args?.[0];
       if (sub === "next") return goalNext();
@@ -4441,14 +4792,14 @@ async function dispatchNlpRoute(route, input) {
 async function runNaturalLanguageRoute(input) {
   const route = routeNaturalLanguage(input);
   if (!route) {
-    console.log(chalk26.yellow(`
+    console.log(chalk27.yellow(`
   \u2753 "${input}" \u2014 ${ko.nlp.notMatched}
 `));
     return;
   }
   console.log("");
-  console.log(chalk26.cyan(`  \u{1F4AC} "${input}"`));
-  console.log(chalk26.cyan(`  \u2192 ${route.explanation}`));
+  console.log(chalk27.cyan(`  \u{1F4AC} "${input}"`));
+  console.log(chalk27.cyan(`  \u2192 ${route.explanation}`));
   if (route.confidence === "low") {
     const { confirm } = await inquirer11.prompt([{
       type: "confirm",
@@ -4457,7 +4808,7 @@ async function runNaturalLanguageRoute(input) {
       default: true
     }]);
     if (!confirm) {
-      console.log(chalk26.dim(`  ${ko.nlp.menuHint}`));
+      console.log(chalk27.dim(`  ${ko.nlp.menuHint}`));
       return;
     }
   }
@@ -4466,77 +4817,77 @@ async function runNaturalLanguageRoute(input) {
 }
 
 // src/commands/agent.ts
-import chalk27 from "chalk";
+import chalk28 from "chalk";
 function activeGoalId() {
   const goals = listGoals("goals");
   const id = selectActiveId(goals);
   return id ?? void 0;
 }
 async function blocker(description) {
-  console.log(chalk27.bold(`
+  console.log(chalk28.bold(`
 ${ko.agent.blockerTitle}
 `));
   if (!description || !description.trim()) {
-    console.log(chalk27.red("  \u274C \uBE14\uB85C\uCEE4 \uC124\uBA85\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."));
-    console.log(chalk27.dim('  \uC608: vhk blocker "tsc \uC5D0\uB7EC \u2014 simple-git \uD0C0\uC785 \uD638\uD658"'));
+    console.log(chalk28.red("  \u274C \uBE14\uB85C\uCEE4 \uC124\uBA85\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."));
+    console.log(chalk28.dim('  \uC608: vhk blocker "tsc \uC5D0\uB7EC \u2014 simple-git \uD0C0\uC785 \uD638\uD658"'));
     process.exitCode = 1;
     return;
   }
   const goalId = activeGoalId();
   const r = appendBlocker(description, goalId);
-  console.log(chalk27.green(`  \u2705 blocker \uAE30\uB85D (\uD604\uC7AC \uD65C\uC131 ${r.count}\uAC74)`));
+  console.log(chalk28.green(`  \u2705 blocker \uAE30\uB85D (\uD604\uC7AC \uD65C\uC131 ${r.count}\uAC74)`));
   if (r.hardStopTripped) {
-    console.log(chalk27.red.bold("  \u{1F6D1} HARD_STOP \uC790\uB3D9 \uC0DD\uC131 \u2014 \uBAA8\uB4E0 \uC790\uB3D9\uD654 \uC911\uB2E8."));
-    console.log(chalk27.yellow("     \uC0AC\uB78C \uAC80\uD1A0 \uD6C4 `vhk resume --confirm` \uC73C\uB85C\uB9CC \uD574\uC81C."));
+    console.log(chalk28.red.bold("  \u{1F6D1} HARD_STOP \uC790\uB3D9 \uC0DD\uC131 \u2014 \uBAA8\uB4E0 \uC790\uB3D9\uD654 \uC911\uB2E8."));
+    console.log(chalk28.yellow("     \uC0AC\uB78C \uAC80\uD1A0 \uD6C4 `vhk resume --confirm` \uC73C\uB85C\uB9CC \uD574\uC81C."));
     process.exitCode = 2;
   }
 }
 async function learn(lesson) {
-  console.log(chalk27.bold(`
+  console.log(chalk28.bold(`
 ${ko.agent.learnTitle}
 `));
   if (!lesson || !lesson.trim()) {
-    console.log(chalk27.red("  \u274C \uAD50\uD6C8 \uB0B4\uC6A9\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."));
-    console.log(chalk27.dim('  \uC608: vhk learn "PowerShell \uC5D0\uC11C\uB294 ; \uC0AC\uC6A9 (&& \uBBF8\uC9C0\uC6D0)"'));
+    console.log(chalk28.red("  \u274C \uAD50\uD6C8 \uB0B4\uC6A9\uC744 \uC785\uB825\uD574 \uC8FC\uC138\uC694."));
+    console.log(chalk28.dim('  \uC608: vhk learn "PowerShell \uC5D0\uC11C\uB294 ; \uC0AC\uC6A9 (&& \uBBF8\uC9C0\uC6D0)"'));
     process.exitCode = 1;
     return;
   }
   const goalId = activeGoalId();
   appendLearning(lesson, goalId);
-  console.log(chalk27.green("  \u2705 learnings.md append."));
+  console.log(chalk28.green("  \u2705 learnings.md append."));
   console.log(
-    chalk27.dim("  \uACB0\uC815\uC0AC\uD56D(decision)\uC740 `vhk memory add` \uB85C \uBCC4\uB3C4 \uAE30\uB85D \u2014 SoT \uBD84\uB9AC.")
+    chalk28.dim("  \uACB0\uC815\uC0AC\uD56D(decision)\uC740 `vhk memory add` \uB85C \uBCC4\uB3C4 \uAE30\uB85D \u2014 SoT \uBD84\uB9AC.")
   );
 }
 async function resume(opts = {}) {
-  console.log(chalk27.bold(`
+  console.log(chalk28.bold(`
 ${ko.agent.resumeTitle}
 `));
   if (!isHardStopActive()) {
-    console.log(chalk27.dim("  HARD_STOP \uD65C\uC131 \uC544\uB2D8 \u2014 \uD560 \uC77C \uC5C6\uC74C."));
+    console.log(chalk28.dim("  HARD_STOP \uD65C\uC131 \uC544\uB2D8 \u2014 \uD560 \uC77C \uC5C6\uC74C."));
     return;
   }
   const reason = readHardStopReason();
   if (reason) {
-    console.log(chalk27.yellow("  \u{1F4CB} HARD_STOP \uC0AC\uC720:"));
-    console.log(chalk27.dim(`     ${reason.split("\n").join("\n     ")}`));
+    console.log(chalk28.yellow("  \u{1F4CB} HARD_STOP \uC0AC\uC720:"));
+    console.log(chalk28.dim(`     ${reason.split("\n").join("\n     ")}`));
     console.log("");
   }
   if (!opts.confirm) {
     console.log(
-      chalk27.red(
+      chalk28.red(
         "  \u274C --confirm \uD50C\uB798\uADF8 \uC5C6\uC774\uB294 \uD574\uC81C\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4 (\uC790\uB3D9 \uD638\uCD9C \uAE08\uC9C0)."
       )
     );
-    console.log(chalk27.yellow("     \uC0AC\uC720\uB97C \uD655\uC778\uD55C \uD6C4 \uB2E4\uC2DC: vhk resume --confirm"));
+    console.log(chalk28.yellow("     \uC0AC\uC720\uB97C \uD655\uC778\uD55C \uD6C4 \uB2E4\uC2DC: vhk resume --confirm"));
     process.exitCode = 1;
     return;
   }
   const removed = clearHardStop();
   if (removed) {
-    console.log(chalk27.green("  \u2705 HARD_STOP \uD574\uC81C. \uC790\uB3D9\uD654 \uC7AC\uAC1C \uAC00\uB2A5."));
+    console.log(chalk28.green("  \u2705 HARD_STOP \uD574\uC81C. \uC790\uB3D9\uD654 \uC7AC\uAC1C \uAC00\uB2A5."));
   } else {
-    console.log(chalk27.dim("  \uD30C\uC77C\uC774 \uC774\uBBF8 \uC5C6\uC74C \u2014 no-op."));
+    console.log(chalk28.dim("  \uD30C\uC77C\uC774 \uC774\uBBF8 \uC5C6\uC74C \u2014 no-op."));
   }
 }
 
@@ -4612,6 +4963,15 @@ program.command("check").alias("\uC810\uAC80").alias("\uB9B0\uD2B8").option("--g
 });
 var secureCmd = program.command("secure").alias("\uBCF4\uC548").description("\uBCF4\uC548 \uB3C4\uAD6C \uBAA8\uC74C \u2014 scan: \uC2DC\uD06C\uB9BF\xB7\uD0A4 \uC720\uCD9C \uAC80\uC0AC").action(secure);
 secureCmd.command("scan").alias("\uC2A4\uCE94").description("\uC2DC\uD06C\uB9BF/\uD0A4 \uC720\uCD9C \uC2A4\uCE94").action(secure);
+var cloudCmd = program.command("cloud").alias("\uD074\uB77C\uC6B0\uB4DC").description(".vhk/ \uD074\uB77C\uC6B0\uB4DC \uBC31\uC5C5\xB7\uBCF5\uC6D0 (GitHub gist) \u2014 push: \uC62C\uB9AC\uAE30, pull: \uB0B4\uB9AC\uAE30").action(() => {
+  cloudCmd.help();
+});
+cloudCmd.command("push").alias("\uC62C\uB9AC\uAE30").description(".vhk/ \uB97C secret gist \uB85C \uBC31\uC5C5").action(async () => {
+  await cloudPush();
+});
+cloudCmd.command("pull").alias("\uB0B4\uB9AC\uAE30").argument("[gistId]", "\uBCF5\uC6D0\uD560 gist id (\uC0DD\uB7B5 \uC2DC .vhk/cloud.json \uC0AC\uC6A9)").description("gist \uC5D0\uC11C .vhk/ \uBCF5\uC6D0").action(async (gistId) => {
+  await cloudPull(gistId);
+});
 program.command("ship").alias("\uCD9C\uD558").description("\uBC30\uD3EC \uCCB4\uD06C\uB9AC\uC2A4\uD2B8 + \uD68C\uACE0 + \uBE4C\uB4DC \uB85C\uADF8 \uC0DD\uC131").action(ship);
 program.command("doctor").alias("\uD658\uACBD").alias("\uC9C4\uB2E8").description("\uAC1C\uBC1C \uD658\uACBD \uC810\uAC80 \u2014 Node/Git/npm \uC0C1\uD0DC \uD655\uC778").action(doctor);
 program.command("save").alias("\uC800\uC7A5").description("\uBCC0\uACBD\uC0AC\uD56D \uC800\uC7A5 (git add \u2192 commit \u2192 push)").action(async () => {

package/dist/mcp/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   startMcpServer
-} from "../chunk-6S3JYYZ3.js";
+} from "../chunk-3DV7AEN4.js";
 
 // src/mcp/index.ts
 startMcpServer().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byh3071/vhk",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Vibe Harness Kit — 바이브코딩 풀사이클 CLI",
   "bin": {
     "vhk": "dist/index.js",