sanjang 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Jeong
+
+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,218 @@
+# 산장 (Sanjang)
+
+> 바이브코더를 위한 로컬 개발 환경 매니저
+
+브랜치 하나로 격리된 dev 환경을 띄우고, 프리뷰하고, 관리하는 도구입니다.
+Git worktree 기반으로 동시에 여러 작업 환경(캠프)을 운영할 수 있습니다.
+
+## 주요 기능
+
+- **포털 홈**: 이어하기(열린 PR + 캠프)와 새로 시작(자연어 퀵스타트)로 대시보드 첫 화면 구성
+- **캠프 생성**: 브랜치 선택 → 자동 worktree + 의존성 설치 + dev 서버 시작
+- **의존성 캐시**: `init` 시 node_modules 프리빌드, 캠프 생성 시 캐시 클론으로 수초 만에 완료
+- **멀티앱 감지**: 모노레포에서 여러 앱을 자동 감지하고 init 시 인터랙티브 선택
+- **포트 자동 관리**: 캠프마다 다른 포트 자동 할당, 충돌 없음
+- **대시보드**: 브라우저에서 모든 캠프 상태 확인 + 시작/중지/삭제
+- **스냅샷**: 현재 상태 저장/복원 (git stash 기반)
+- **일 시키기**: 대시보드에서 Claude에게 작업 지시 (claude -p 연동)
+- **팀에 보내기**: 변경사항 commit + push → PR 생성 플로우
+- **프로젝트 자동 감지**: Next.js, Vite, SvelteKit, Angular, shadow-cljs, Turborepo 등 자동 인식
+
+---
+
+## 설치 (for AI Assistants)
+
+> 이 섹션은 Claude Code 같은 AI 어시스턴트가 읽고 실행하는 용도입니다.
+> 사용자가 이 GitHub URL을 던지면 아래 절차를 따라 설치하세요.
+
+### 자동 설치 절차
+
+1. **대상 프로젝트의 git root로 이동합니다.**
+
+2. **산장을 설치하고 시작합니다:**
+```bash
+npx sanjang init
+```
+이 명령이 자동으로:
+- 프로젝트를 분석하여 `sanjang.config.js` 생성
+- `.gitignore`에 `.sanjang/` 추가
+- 대시보드 서버 시작 (http://localhost:4000)
+
+3. **사용자에게 안내합니다:**
+```
+⛰ 산장 설치 완료!
+  대시보드: http://localhost:4000
+  "+ 새 캠프" 버튼으로 브랜치별 작업 환경을 만들 수 있습니다.
+```
+
+### 설치 후 사용법 안내
+
+- **새로 시작**: 포털 홈에서 "뭘 하고 싶어?" 입력 → 자동으로 브랜치+캠프 생성
+- **캠프 생성**: 대시보드에서 "+ 새 캠프" → 브랜치 선택 → 자동 생성+시작
+- **이어하기**: 포털 홈에서 열린 PR이나 기존 캠프 클릭 → 바로 작업 재개
+- **프리뷰**: 각 캠프 카드의 URL 클릭
+- **일 시키기**: 캠프 카드의 입력창에 프롬프트 입력 → Claude가 해당 worktree에서 작업
+- **팀에 보내기**: 변경 완료 후 "팀에 보내기" 버튼 → commit + push
+
+---
+
+## 설치 (사람용)
+
+### 방법 1: npx (추천)
+
+```bash
+cd your-project
+npx sanjang init
+```
+
+config만 생성하고 서버는 나중에 시작하려면:
+
+```bash
+npx sanjang init --no-start
+npx sanjang
+```
+
+### 방법 2: 글로벌 설치
+
+```bash
+npm install -g sanjang
+cd your-project
+sanjang init
+```
+
+---
+
+## 설정 (`sanjang.config.js`)
+
+`sanjang init`이 자동으로 생성하지만, 직접 작성/수정할 수도 있습니다.
+
+```js
+export default {
+  // 프론트엔드 개발 서버
+  dev: {
+    command: 'npm run dev',    // 실행 명령
+    port: 3000,                // 기본 포트 (캠프별 +1씩 증가)
+    portFlag: '--port',        // 포트 오버라이드 플래그
+    cwd: '.',                  // worktree 기준 상대 경로
+    env: {},                   // 추가 환경변수
+  },
+
+  // (선택) 설치 명령 — 캠프 생성 시 자동 실행
+  setup: 'npm install',
+
+  // (선택) 복사할 파일 — gitignored 파일을 메인에서 복사
+  copyFiles: ['.env', '.env.local'],
+
+  // (선택) 백엔드 — 전체 캠프가 공유하는 서버
+  backend: {
+    command: 'npm run start:api',
+    port: 8000,
+    healthCheck: '/health',
+  },
+
+  // (선택) 포트 범위
+  ports: {
+    fe: { base: 3000, slots: 8 },
+    be: { base: 8000, slots: 8 },
+  },
+};
+```
+
+### 프레임워크별 예시
+
+**Next.js:**
+```js
+export default {
+  dev: { command: 'npx next dev', port: 3000, portFlag: '-p' },
+  setup: 'npm install',
+  copyFiles: ['.env.local'],
+};
+```
+
+**Vite (React/Vue/Svelte):**
+```js
+export default {
+  dev: { command: 'npx vite dev', port: 5173, portFlag: '--port' },
+  setup: 'npm install',
+};
+```
+
+**Turborepo (monorepo):**
+```js
+export default {
+  dev: {
+    command: 'npx turbo run dev --filter=my-app',
+    port: 3000,
+    portFlag: '--port',
+    cwd: '.',
+  },
+  setup: 'npm install',
+  copyFiles: ['.env', 'apps/my-app/.env.local'],
+};
+```
+
+---
+
+## 자연어 퀵스타트
+
+포털 홈에서 자연어로 작업을 설명하면 자동으로 캠프가 만들어집니다:
+
+```
+"로그인 버튼 색상 변경" → camp/login-button-color-change 브랜치 생성
+"대시보드 필터 추가"     → camp/dashboard-filter-add 브랜치 생성
+```
+
+한국어와 영어 모두 지원합니다. 내부적으로 한국어 개발 용어를 영문 kebab-case로 변환합니다.
+
+---
+
+## 의존성 캐시
+
+`sanjang init` 시 node_modules를 프리빌드하여 `.sanjang/cache/`에 저장합니다. 이후 캠프 생성 시 `npm install` 대신 캐시를 복사하여 수초 만에 완료됩니다.
+
+- 캐시는 lockfile 해시로 유효성을 검증합니다
+- lockfile이 변경되면 자동으로 캐시를 무효화합니다
+- `POST /api/cache/rebuild`로 수동 리빌드 가능합니다
+
+---
+
+## 개념
+
+| 용어 | 설명 |
+|------|------|
+| **산장** | 이 도구 전체. 대시보드 서버 + 캠프 매니저 |
+| **캠프** | 개별 작업 환경. git worktree + dev 서버 |
+| **포털** | 대시보드 첫 화면. 이어하기 + 새로 시작 |
+| **스냅샷** | 캠프의 현재 상태를 저장한 것 (git stash) |
+| **캐시** | 의존성 프리빌드. 캠프 생성 속도 향상 |
+
+---
+
+## 개발
+
+TypeScript로 작성되었습니다. 빌드 스텝 없이 Node.js의 `--experimental-transform-types`로 직접 실행합니다.
+
+```bash
+# 테스트
+npm test
+
+# 타입 체크
+npm run typecheck
+
+# 린트
+npm run lint
+```
+
+---
+
+## 요구사항
+
+- Node.js 22+ (`--experimental-transform-types` 지원)
+- Git 2.20+ (worktree 지원)
+- (선택) Claude Code — "일 시키기" 기능용
+
+---
+
+## 라이선스
+
+MIT

package/bin/__tests__/sanjang.test.ts

@@ -0,0 +1,42 @@
+// Tests for bin/sanjang.js CLI flag parsing logic
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+describe("sanjang CLI flag parsing", () => {
+  it("detects --no-start flag in args array", () => {
+    const args = ["init", "--no-start"];
+    const noStart = args.includes("--no-start");
+    assert.equal(noStart, true);
+  });
+
+  it("does not detect --no-start when absent", () => {
+    const args = ["init"];
+    const noStart = args.includes("--no-start");
+    assert.equal(noStart, false);
+  });
+
+  it("parses --port value correctly", () => {
+    const args = ["init", "--port", "5000"];
+    let port = 4000;
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === "--port" && args[i + 1]) {
+        port = parseInt(args[i + 1]!);
+        i++;
+      }
+    }
+    assert.equal(port, 5000);
+  });
+
+  it("uses default port 4000 when --port not specified", () => {
+    const args = ["init"];
+    let port = 4000;
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === "--port" && args[i + 1]) {
+        port = parseInt(args[i + 1]!);
+        i++;
+      }
+    }
+    assert.equal(port, 4000);
+  });
+});

package/bin/sanjang.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// Shell wrapper — delegates to the TypeScript entry point
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const tsEntry = join(__dirname, 'sanjang.ts');
+
+try {
+  execFileSync(process.execPath, ['--experimental-transform-types', tsEntry, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env: { ...process.env, NODE_NO_WARNINGS: '1' },
+  });
+} catch (err) {
+  process.exit(err?.status ?? 1);
+}

package/bin/sanjang.ts

@@ -0,0 +1,144 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const args: string[] = process.argv.slice(2);
+const command: string | undefined = args[0];
+
+// Parse options
+let projectRoot: string = process.cwd();
+let port: number = 4000;
+let force: boolean = false;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--project" && args[i + 1]) {
+    projectRoot = resolve(args[i + 1]!);
+    i++;
+  }
+  if (args[i] === "--port" && args[i + 1]) {
+    port = parseInt(args[i + 1]!);
+    i++;
+  }
+  if (args[i] === "--force") {
+    force = true;
+  }
+}
+
+// Find git root
+try {
+  projectRoot = execSync("git rev-parse --show-toplevel", {
+    cwd: projectRoot,
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "pipe"],
+  }).trim();
+} catch {
+  console.error("⛰ 산장: git 저장소를 찾을 수 없습니다.");
+  console.error("  git 저장소 안에서 실행해주세요.");
+  process.exit(1);
+}
+
+if (command === "init") {
+  const { generateConfig, detectApps } = await import("../lib/config.ts");
+
+  // Detect apps in subdirectories
+  const apps = detectApps(projectRoot);
+  let appDir: string | undefined;
+
+  if (apps.length >= 2) {
+    // Multi-app interview
+    console.log("");
+    console.log("⛰ 여러 앱이 감지되었습니다:");
+    for (let i = 0; i < apps.length; i++) {
+      console.log(`  ${i + 1}) ${apps[i]!.dir}/\t(${apps[i]!.framework})`);
+    }
+    console.log("");
+
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise<string>((resolve) => {
+      rl.question("  어떤 앱을 띄울까요? [번호]: ", resolve);
+    });
+    rl.close();
+
+    const idx = parseInt(answer) - 1;
+    if (idx < 0 || idx >= apps.length || isNaN(idx)) {
+      console.error("⛰ 잘못된 선택입니다.");
+      process.exit(1);
+    }
+    appDir = apps[idx]!.dir;
+    console.log(`  → ${appDir}/ (${apps[idx]!.framework}) 선택됨`);
+  } else if (apps.length === 1) {
+    appDir = apps[0]!.dir;
+  }
+
+  const result = generateConfig(projectRoot, { appDir, force });
+
+  if (result.created) {
+    console.log(`⛰ ${result.message}`);
+    console.log(`  프레임워크: ${result.framework}`);
+    console.log(`  설정 파일: ${result.configPath}`);
+  } else {
+    console.log(`⛰ ${result.message}`);
+  }
+
+  // Add .sanjang to .gitignore if not present
+  const gitignorePath = resolve(projectRoot, ".gitignore");
+  if (existsSync(gitignorePath)) {
+    const { readFileSync, appendFileSync } = await import("node:fs");
+    const content = readFileSync(gitignorePath, "utf8");
+    if (!content.includes(".sanjang")) {
+      appendFileSync(gitignorePath, "\n# Sanjang local dev camps\n.sanjang/\n");
+      console.log("  .gitignore에 .sanjang/ 추가됨");
+    }
+  }
+
+  // Prebuild dependency cache
+  const { loadConfig } = await import("../lib/config.ts");
+  const initConfig = await loadConfig(projectRoot);
+  if (initConfig.setup) {
+    console.log("");
+    console.log("  의존성 캐시를 빌드합니다...");
+    const { buildCache } = await import("../lib/engine/cache.ts");
+    const cacheResult = await buildCache(projectRoot, initConfig, (msg: string) => {
+      console.log(`  ${msg}`);
+    });
+    if (cacheResult.success) {
+      console.log(`  캐시 빌드 완료 ✓ (${(cacheResult.duration / 1000).toFixed(1)}초)`);
+    } else {
+      console.log(`  ⚠️ 캐시 빌드 실패: ${cacheResult.error}`);
+      console.log("  캠프 생성 시 일반 설치를 사용합니다.");
+    }
+  }
+
+  // Auto-start server unless --no-start
+  const noStart = args.includes("--no-start");
+  if (!noStart) {
+    console.log("");
+    console.log("  서버를 시작합니다...");
+    const { startServer } = await import("../lib/server.ts");
+    await startServer(projectRoot, { port });
+  } else {
+    console.log("");
+    console.log("  다음 단계: sanjang 또는 npx sanjang 으로 서버를 시작하세요.");
+  }
+} else if (command === "help" || command === "--help" || command === "-h") {
+  console.log(`
+⛰ 산장 (Sanjang) — 바이브코더를 위한 로컬 개발 환경 매니저
+
+사용법:
+  sanjang              서버 시작 (대시보드: http://localhost:4000)
+  sanjang init         프로젝트 분석 → sanjang.config.js 생성
+  sanjang help         이 도움말
+
+옵션:
+  --port <N>           대시보드 포트 (기본: 4000)
+  --project <path>     프로젝트 경로 (기본: 현재 디렉토리)
+  --force              기존 설정을 덮어쓰고 다시 생성
+
+자세히: https://github.com/paul-sherpas/sanjang
+`);
+} else {
+  // Default: start server
+  const { startServer } = await import("../lib/server.ts");
+  await startServer(projectRoot, { port });
+}