@rhseung/claude-mv 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyunseung Ryu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# claude-mv
+
+Claude Code는 프로젝트 상태를 절대 경로로 키를 삼아 저장한다. 그래서 디렉터리를 옮기면
+세션 기록을 더는 찾지 못한다. 이 도구는 디렉터리와 상태를 함께 옮긴다.
+
+```
+npx @rhseung/claude-mv doctor                     연결이 끊긴 상태가 있는지 확인
+npx @rhseung/claude-mv --dry-run <old> <new>      무엇이 바뀌는지만 확인
+npx @rhseung/claude-mv <old> <new>                디렉터리와 상태를 함께 이동
+npx @rhseung/claude-mv --state-only <old> <new>   이미 옮긴 디렉터리의 상태만 이관
+```
+
+## 설치
+
+```
+bun install -g @rhseung/claude-mv
+npm install -g @rhseung/claude-mv
+```
+
+## 명령
+
+| 명령                | 동작                                                             |
+| ------------------- | ---------------------------------------------------------------- |
+| `mv <src> <dst>`    | 디렉터리와 상태를 함께 옮긴다. 명령을 생략하면 이것이 기본값이다 |
+| `ls`                | Claude가 알고 있는 프로젝트를 전부 보여준다                      |
+| `info <경로>`       | 프로젝트 하나의 상태를 자세히 보여준다                           |
+| `doctor`            | 연결이 끊긴 상태를 찾아내고 어디로 옮겨졌는지 추정한다           |
+| `rm <경로>`         | 프로젝트 하나의 Claude 상태를 삭제한다 (백업 후 진행)            |
+| `merge <from> <to>` | 프로젝트 디렉터리 두 개를 합친다                                 |
+| `backup [경로]`     | 이동하지 않고 스냅샷만 만든다                                    |
+| `rollback [id]`     | 백업 목록을 보여주거나 지정한 백업으로 복구한다                  |
+| `export <경로>`     | 상태를 tarball로 내보낸다                                        |
+| `import <파일>`     | tarball에서 들여온다. `--to`를 지정하면 이어서 이관한다          |
+| `completion <셸>`   | 자동완성 스크립트를 출력한다                                     |
+
+| 플래그                 | 의미                                                     |
+| ---------------------- | -------------------------------------------------------- |
+| `-n, --dry-run`        | 계획만 보여주고 아무것도 기록하지 않는다                 |
+| `-y, --yes`            | 확인 프롬프트를 건너뛴다                                 |
+| `-f, --force`          | lock과 상태 충돌을 차단 대신 경고로 낮춘다               |
+| `--state-only`         | 디렉터리는 그대로 두고 상태만 옮긴다                     |
+| `--skip-live`          | 실행 중인 세션의 transcript는 건드리지 않는다            |
+| `--rewrite-prose`      | 대화 본문에 포함된 경로까지 바꾼다                       |
+| `--no-backup`          | 백업을 만들지 않는다. 이 경우 rollback도 불가능하다      |
+| `--json`               | 기계가 읽는 출력. 진행 상황은 stderr, 결과 하나는 stdout |
+| `--claude-home <경로>` | `~/.claude` 위치를 재지정한다                            |
+
+## 종료 코드
+
+| 코드 | 의미                                          |
+| ---- | --------------------------------------------- |
+| 0    | 성공                                          |
+| 2    | 사용법 오류                                   |
+| 10   | 계획 생성 완료. **실패가 아니다**             |
+| 11   | 연결이 끊긴 상태 발견                         |
+| 12   | 이관 대상 없음                                |
+| 20   | 옛 경로에서 세션 실행 중                      |
+| 21   | 대상 경로에 상태가 이미 존재                  |
+| 22   | 전제 조건 위반. 원본 없음 또는 dst가 src 내부 |
+| 30   | 실패 후 전체 복구 완료                        |
+| 31   | 실패 후 복구도 실패. 수동 복구 필요           |
+
+## 자동완성
+
+```
+eval "$(claude-mv completion zsh)"
+```
+
+후보는 셸이 CLI에 다시 질의해서 받아가므로, `claude-mv info <TAB>`은 일반 파일이 아니라
+Claude가 알고 있는 프로젝트 경로를 보여준다. zsh 스크립트는 `compadd`로 후보를 등록하기
+때문에 fzf-tab이 별도 설정 없이 동작한다. 인자를 생략하면 fzf picker가 나타난다
+(`CLAUDE_MV_PICKER=fzf|ink|none`).
+
+## 플러그인
+
+```
+/plugin marketplace add rhseung/claude-mv
+/plugin install claude-mv@rhseung
+```
+
+SessionStart hook은 현재 디렉터리에 프로젝트 기록이 없고 이름이 비슷하면서 연결이 끊긴
+상태가 남아 있을 때 이를 알려준다. 알림만 보내며 자동으로 옮기지는 않는다. `/claude-mv`
+슬래시 명령도 함께 설치된다.
+
+## 이관 대상
+
+`mv`를 한 번 실행하면 아래가 모두 원래 경로와의 연결을 잃는다.
+
+```
+~/.claude/projects/-Users-me-dev-old-name/                    세션 기록(transcript)
+~/.claude.json  projects["/Users/me/dev/old-name"]
+~/.claude/history.jsonl  의 project 필드
+~/Library/Caches/claude-cli-nodejs/-Users-me-dev-old-name/    MCP 로그
+~/.claude/plans/*.md  안의 경로 문자열
+```
+
+디렉터리 이름은 경로에서 영숫자가 아닌 문자를 전부 `-`로 바꾼 것이다. 이 변환은
+**되돌릴 수 없다.** `/a/b-c`와 `/a/b/c`가 같은 이름이 되기 때문이다. 따라서 디렉터리
+이름만 보고 원래 경로를 알아낼 수는 없고, 안에 들어 있는 transcript의 `cwd`를 읽어야 한다.
+
+`sessions/`, `file-history/`, `shell-snapshots/`, `session-env/`는 세션 id나 파일 해시를
+키로 삼고 있어 디렉터리 이름과 무관하므로 건드리지 않는다.
+
+## 수정 범위
+
+transcript의 필드를 두 갈래로 나눈다.
+
+**구조 필드**는 Claude Code가 실제로 읽는 값이다. `cwd`, `wireIngestContext.*.cwd`,
+`attachment.snapshot.workingDirectory`가 여기에 해당한다. 경로가 바뀌면 반드시 따라가야 한다.
+
+**서술 필드**는 대화 본문과 도구 출력이다. "그때 그 경로에서 이 명령을 실행했다"는 사실을
+남긴 기록이므로, 고치면 과거가 사실과 달라진다. 기본적으로 손대지 않으며, 필요하면
+`--rewrite-prose`로 포함시킨다.
+
+**plan 파일은 예외다.** 과거의 기록이 아니라 앞으로 따라야 할 지시서이므로, 낡은 경로가
+남아 있으면 그 경로를 따라 잘못된 작업을 하게 된다. 어떤 plan이 어느 프로젝트에 속하는지는
+transcript의 `planFilePath` 구조 필드로 판정한다. 전역 plan 디렉터리를 경로 문자열로 훑으면
+다른 프로젝트의 plan까지 수정하게 되기 때문이다.
+
+## 안전장치
+
+**백업.** 기록하기 전에 수정 대상 파일을 전부 스냅샷으로 남긴다. 같은 파일시스템이면
+복사 대신 하드링크를 걸기 때문에 상태가 수 GB에 이르러도 비용이 거의 들지 않는다.
+
+**commit barrier.** 느리지만 되돌릴 수 있는 작업을 전부 앞쪽에 모으고, 실제 교체는 뒤쪽에
+짧게 배치한다. 스테이징 단계에서 실패하면 사용자에게 보이는 상태는 전혀 바뀌지 않는다.
+
+**lock 감지.** 옛 경로에서 claude 세션이 실행 중이면 작업을 거부한다. pid 재사용을
+걸러내려고 프로세스 시작 시각까지 대조한다.
+
+**동시 수정 감지.** 재작성하는 동안 파일이 바뀌면 덮어쓰지 않고 실패한다. 실행 중인
+세션이 덧붙인 줄을 말없이 잃어버리는 것보다 낫기 때문이다.
+
+**rollback.** journal을 역순으로 재생해서 원래 상태로 복구한다. 복구 도중에 중단되어도
+다시 실행하면 이어서 마무리한다.
+
+## 개발
+
+```
+bun install
+bun run verify     format, lint, typecheck, test
+bun run build
+```
+
+`plugin/hooks/session-start.mjs`는 빌드 산출물이지만 저장소에 커밋한다. 플러그인 설치가
+빌드 단계 없는 `git clone`이라, 커밋하지 않으면 hook이 빠진 플러그인이 배포되기 때문이다.
+CI가 소스와 산출물이 어긋나지 않았는지 검사한다.
+
+## 라이선스
+
+MIT

package/dist/chunk-JJSX2UL6.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+// src/render/plain/reporter.ts
+import { createInterface } from "readline/promises";
+
+// src/render/format.ts
+import prettyBytes from "pretty-bytes";
+import prettyMs from "pretty-ms";
+import stringWidth from "string-width";
+function describeStep(step) {
+  switch (step.kind) {
+    case "move-project-dir":
+      return { label: "project dir", action: "rename", detail: `${step.files} files` };
+    case "rewrite-transcript":
+      return {
+        label: step.movesWithDir ? "transcript" : "transcript (\uC81C\uC790\uB9AC)",
+        action: "rewrite",
+        detail: `${step.affected}/${step.total} \uC904`
+      };
+    case "edit-config":
+      return {
+        label: "claude.json",
+        action: step.renameKey ? "rekey" : "edit",
+        detail: step.githubRepos.length ? `+ ${step.githubRepos.length} repo` : "1 key"
+      };
+    case "rewrite-history":
+      return { label: "history", action: "rewrite", detail: `${step.affected} \uC904` };
+    case "move-cache-dir":
+      return { label: "mcp logs", action: "rename", detail: "" };
+    case "rewrite-plan":
+      return { label: "plan", action: "rewrite", detail: basename(step.file) };
+    case "move-directory":
+      return { label: "working tree", action: "move", detail: "" };
+    case "repair-worktrees":
+      return { label: "worktrees", action: "repair", detail: "" };
+  }
+}
+function basename(path) {
+  return path.split(/[/\\]/).pop() ?? path;
+}
+function bytes(n) {
+  return prettyBytes(n);
+}
+function duration(ms) {
+  return prettyMs(ms, { compact: true });
+}
+function ago(ms) {
+  const delta = Date.now() - ms;
+  if (delta < 6e4) return "\uBC29\uAE08";
+  return `${prettyMs(delta, { compact: true })} \uC804`;
+}
+function pad(text, width) {
+  return text + " ".repeat(Math.max(0, width - stringWidth(text)));
+}
+function table(rows, gap = 2) {
+  const widths = rows[0]?.map((_, i) => Math.max(...rows.map((r) => stringWidth(r[i] ?? "")))) ?? [];
+  return rows.map(
+    (row) => row.map((cell, i) => i === row.length - 1 ? cell : pad(cell, widths[i] + gap)).join("").trimEnd()
+  );
+}
+
+// src/render/plain/reporter.ts
+var PlainReporter = class {
+  constructor(out = process.stdout, err = process.stderr) {
+    this.out = out;
+    this.err = err;
+  }
+  out;
+  err;
+  write(line) {
+    this.out.write(`${line}
+`);
+  }
+  plan(plan, opts) {
+    this.write(
+      `plan: ${plan.steps.length} steps${opts.backupId ? `, backup ${opts.backupId}` : ""}`
+    );
+    for (const step of plan.steps) {
+      const d = describeStep(step);
+      this.write(`  ${d.action.padEnd(8)}${d.label.padEnd(22)}${d.detail}`);
+    }
+    for (const warning of plan.warnings) this.warn(JSON.stringify(warning));
+    if (plan.proseLeftBehind > 0) {
+      this.write(`  skip    prose ${plan.proseLeftBehind}\uACF3 (--rewrite-prose \uB85C \uD3EC\uD568)`);
+    }
+  }
+  async confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+      const answer = await rl.question(`${question} [y/N] `);
+      return /^y(es)?$/i.test(answer.trim());
+    } finally {
+      rl.close();
+    }
+  }
+  progress(event) {
+    if (event.kind === "step-done") {
+      const d = describeStep(event.step);
+      this.write(`ok      ${d.label}${event.detail ? `  ${event.detail}` : ""}`);
+    } else if (event.kind === "step-failed") {
+      this.write(`failed  ${describeStep(event.step).label}  ${event.error.message}`);
+    }
+  }
+  applied(plan, opts) {
+    this.write(`done: ${plan.steps.length} steps in ${duration(opts.durationMs)}`);
+    if (opts.backupId) this.write(`rollback: claude-mv rollback ${opts.backupId}`);
+  }
+  failed(_plan, opts) {
+    this.err.write(`error: ${opts.error.message}
+`);
+    this.err.write(opts.rolledBack ? "\uC804\uBD80 \uC6D0\uB798\uB300\uB85C \uB3CC\uB838\uC2B5\uB2C8\uB2E4.\n" : "\uB418\uB3CC\uB9AC\uAE30\uB3C4 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4.\n");
+    if (opts.backupId) this.err.write(`backup: ${opts.backupId}
+`);
+  }
+  locks(report) {
+    for (const finding of report.findings) {
+      this.write(
+        `lock    pid ${finding.session.pid}  ${finding.verdict}  ${finding.relation}  ${finding.session.cwd}`
+      );
+    }
+  }
+  doctor(report) {
+    this.write(`orphans: ${report.orphans.length}, healthy: ${report.healthy.length}`);
+    for (const entry of report.orphans) {
+      this.write(`orphan  ${entry.project.primaryCwd ?? entry.project.dirName}`);
+      for (const s of entry.suggestions) {
+        this.write(
+          `  guess ${s.confidence.toFixed(2)}  ${s.candidate}  (${s.evidence.join(", ")})`
+        );
+      }
+    }
+    for (const c of report.collisions) this.warn(`collision ${c.dirName}: ${c.paths.join(" , ")}`);
+  }
+  list(projects) {
+    for (const p of projects) {
+      this.write(
+        `${p.health.padEnd(16)}${bytes(p.bytes).padStart(9)}  ${String(p.transcripts.length).padStart(3)}  ${p.primaryCwd ?? p.dirName}`
+      );
+    }
+  }
+  info(project) {
+    this.write(`path       ${project.primaryCwd ?? "(\uD310\uC815 \uBD88\uAC00)"}`);
+    this.write(`dir        ${project.dirPath}`);
+    this.write(`health     ${project.health}`);
+    this.write(`size       ${bytes(project.bytes)}`);
+    for (const t of project.transcripts) {
+      this.write(`  ${t.kind.padEnd(9)}${t.sessionId}  ${t.lines} \uC904  ${bytes(t.bytes)}`);
+    }
+    for (const [path, lines] of [...project.cwdCensus].sort((a, b) => b[1] - a[1])) {
+      this.write(`  cwd  ${String(lines).padStart(5)}  ${path}`);
+    }
+  }
+  backups(items) {
+    if (items.length === 0) {
+      this.write("\uBC31\uC5C5\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+      return;
+    }
+    for (const line of table(
+      items.map((b) => [
+        b.id,
+        ago(b.createdAt),
+        b.src,
+        "->",
+        b.dst,
+        b.restorable ? "" : "(\uB300\uC0C1 \uC5C6\uC74C)"
+      ])
+    )) {
+      this.write(line);
+    }
+  }
+  note(message) {
+    this.write(message);
+  }
+  warn(message) {
+    this.err.write(`warn: ${message}
+`);
+  }
+  async close() {
+  }
+};
+
+export {
+  describeStep,
+  duration,
+  pad,
+  PlainReporter
+};