sanjang 0.3.1 → 0.3.2

package/dist/bin/sanjang.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bin/sanjang.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+const args = process.argv.slice(2);
+const command = args[0];
+// Parse options
+let projectRoot = process.cwd();
+let port = 4000;
+let force = 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.js");
+    // Detect apps in subdirectories
+    const apps = detectApps(projectRoot);
+    let appDir;
+    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((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.js");
+    const initConfig = await loadConfig(projectRoot);
+    if (initConfig.setup) {
+        console.log("");
+        console.log("  의존성 캐시를 빌드합니다...");
+        const { buildCache } = await import("../lib/engine/cache.js");
+        const cacheResult = await buildCache(projectRoot, initConfig, (msg) => {
+            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.js");
+        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.js");
+    await startServer(projectRoot, { port });
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,19 @@
+import type { DetectedApp, DetectedProject, GenerateConfigResult, SanjangConfig } from "./types.ts";
+/**
+ * Load sanjang.config.js from project root.
+ * Returns merged config with defaults.
+ */
+export declare function loadConfig(projectRoot: string): Promise<SanjangConfig>;
+/**
+ * Auto-detect project type and generate config.
+ */
+export declare function detectProject(projectRoot: string): DetectedProject;
+/**
+ * Scan first-level subdirectories for app candidates.
+ * Returns array of { dir, framework, detected } sorted by dir name.
+ */
+export declare function detectApps(projectRoot: string): DetectedApp[];
+export declare function generateConfig(projectRoot: string, options?: {
+    appDir?: string;
+    force?: boolean;
+}): GenerateConfigResult;

package/dist/lib/config.js

@@ -0,0 +1,318 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { deepFindEnvFiles, detectSetupIssues } from "./engine/smart-init.js";
+const CONFIG_FILE = "sanjang.config.js";
+const DEFAULTS = {
+    dev: {
+        command: "npm run dev",
+        port: 3000,
+        portFlag: "--port",
+        cwd: ".",
+        env: {},
+    },
+    setup: null,
+    copyFiles: [],
+    backend: null,
+    ports: {
+        fe: { base: 3000, slots: 8 },
+        be: { base: 8000, slots: 8 },
+    },
+};
+/**
+ * Load sanjang.config.js from project root.
+ * Returns merged config with defaults.
+ */
+export async function loadConfig(projectRoot) {
+    const configPath = join(projectRoot, CONFIG_FILE);
+    if (!existsSync(configPath)) {
+        console.warn("⚠️ sanjang.config.js를 찾을 수 없습니다. 기본 설정을 사용합니다.");
+        console.warn("  → sanjang init 으로 프로젝트에 맞는 설정을 생성하세요.");
+        return { ...DEFAULTS, _autoDetected: false };
+    }
+    try {
+        const mod = await import(__rewriteRelativeImportExtension(pathToFileURL(configPath).href));
+        const userConfig = mod.default || mod;
+        return mergeConfig(userConfig);
+    }
+    catch (err) {
+        console.error(`sanjang.config.js 로드 실패: ${err.message}`);
+        return { ...DEFAULTS, _autoDetected: false };
+    }
+}
+function mergeConfig(user) {
+    const config = { ...DEFAULTS };
+    if (typeof user.dev === "string") {
+        config.dev = { ...DEFAULTS.dev, command: user.dev };
+    }
+    else if (user.dev) {
+        config.dev = { ...DEFAULTS.dev, ...user.dev };
+    }
+    if (user.setup)
+        config.setup = user.setup;
+    if (user.copyFiles)
+        config.copyFiles = user.copyFiles;
+    if (user.backend)
+        config.backend = user.backend;
+    if (user.ports) {
+        const userPorts = user.ports;
+        config.ports = {
+            fe: { ...DEFAULTS.ports.fe, ...userPorts.fe },
+            be: { ...DEFAULTS.ports.be, ...userPorts.be },
+        };
+    }
+    return config;
+}
+/**
+ * Auto-detect project type and generate config.
+ */
+export function detectProject(projectRoot) {
+    const has = (f) => existsSync(join(projectRoot, f));
+    const readJson = (f) => {
+        try {
+            return JSON.parse(readFileSync(join(projectRoot, f), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    };
+    // Framework detection
+    if (has("next.config.js") || has("next.config.mjs") || has("next.config.ts")) {
+        return {
+            framework: "Next.js",
+            dev: { command: "npx next dev", port: 3000, portFlag: "-p", cwd: ".", env: {} },
+            setup: has("bun.lockb") ? "bun install" : has("pnpm-lock.yaml") ? "pnpm install" : "npm install",
+            copyFiles: findEnvFiles(projectRoot),
+        };
+    }
+    if (has("nuxt.config.js") || has("nuxt.config.ts")) {
+        return {
+            framework: "Nuxt",
+            dev: { command: "npx nuxt dev", port: 3000, portFlag: "--port", cwd: ".", env: {} },
+            setup: detectPackageManager(projectRoot),
+            copyFiles: findEnvFiles(projectRoot),
+        };
+    }
+    if (has("svelte.config.js") || has("svelte.config.ts")) {
+        return {
+            framework: "SvelteKit",
+            dev: { command: "npx vite dev", port: 5173, portFlag: "--port", cwd: ".", env: {} },
+            setup: detectPackageManager(projectRoot),
+            copyFiles: findEnvFiles(projectRoot),
+        };
+    }
+    if (has("angular.json")) {
+        return {
+            framework: "Angular",
+            dev: { command: "npx ng serve", port: 4200, portFlag: "--port", cwd: ".", env: {} },
+            setup: "npm install",
+            copyFiles: findEnvFiles(projectRoot),
+        };
+    }
+    if (has("vite.config.js") || has("vite.config.ts") || has("vite.config.mjs")) {
+        return {
+            framework: "Vite",
+            dev: { command: "npx vite dev", port: 5173, portFlag: "--port", cwd: ".", env: {} },
+            setup: detectPackageManager(projectRoot),
+            copyFiles: findEnvFiles(projectRoot),
+        };
+    }
+    // ClojureScript / shadow-cljs (root or common subdirectories)
+    const shadowDirs = [".", "frontend", "client", "web", "app"];
+    for (const dir of shadowDirs) {
+        const prefix = dir === "." ? "" : `${dir}/`;
+        if (has(`${prefix}shadow-cljs.edn`)) {
+            const hasBb = has(`${prefix}bb.edn`);
+            return {
+                framework: "shadow-cljs",
+                dev: { command: hasBb ? "bb dev" : "npx shadow-cljs watch app", port: 3000, portFlag: null, cwd: dir, env: {} },
+                setup: "npm install",
+                copyFiles: findEnvFiles(projectRoot),
+            };
+        }
+    }
+    // Monorepo detection
+    if (has("turbo.json")) {
+        const mainApp = detectTurboMainApp(projectRoot);
+        const filter = mainApp ? ` --filter=${mainApp.name}` : "";
+        const port = mainApp?.port ?? 3000;
+        return {
+            framework: "Turborepo",
+            dev: { command: `npx turbo run dev${filter}`, port, portFlag: null, cwd: ".", env: {} },
+            setup: detectPackageManager(projectRoot),
+            copyFiles: findEnvFiles(projectRoot),
+            _note: mainApp
+                ? `Turborepo: filtered to ${mainApp.name} (port ${port}).`
+                : "Turborepo detected. You may need to adjust the dev command to filter a specific app.",
+        };
+    }
+    // Fallback: package.json scripts
+    const pkg = readJson("package.json");
+    if (pkg?.scripts?.dev) {
+        return {
+            framework: "Node.js",
+            dev: { command: "npm run dev", port: 3000, portFlag: "--port", cwd: ".", env: {} },
+            setup: detectPackageManager(projectRoot),
+            copyFiles: findEnvFiles(projectRoot),
+        };
+    }
+    return {
+        framework: "unknown",
+        dev: { command: "npm run dev", port: 3000, portFlag: "--port", cwd: ".", env: {} },
+        setup: "npm install",
+        copyFiles: [],
+    };
+}
+/**
+ * Scan first-level subdirectories for app candidates.
+ * Returns array of { dir, framework, detected } sorted by dir name.
+ */
+export function detectApps(projectRoot) {
+    const entries = readdirSync(projectRoot, { withFileTypes: true });
+    const ignore = new Set(["node_modules", ".git", ".sanjang", "dist", "build", ".next", ".nuxt"]);
+    const apps = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith(".") || ignore.has(entry.name))
+            continue;
+        const subPath = join(projectRoot, entry.name);
+        const detected = detectProject(subPath);
+        if (detected.framework === "unknown")
+            continue;
+        apps.push({
+            dir: entry.name,
+            framework: detected.framework,
+            detected,
+        });
+    }
+    return apps.sort((a, b) => a.dir.localeCompare(b.dir));
+}
+function detectTurboMainApp(root) {
+    // Scan apps/*/package.json for the main app (has dev script with --port or vite/next)
+    const appDirs = ["apps", "packages"];
+    const candidates = [];
+    for (const dir of appDirs) {
+        const base = join(root, dir);
+        if (!existsSync(base))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(base, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            // Skip storybook, demo, docs apps
+            if (/storybook|demo|docs|e2e|test/i.test(entry.name))
+                continue;
+            const pkgPath = join(base, entry.name, "package.json");
+            if (!existsSync(pkgPath))
+                continue;
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+                const scripts = pkg.scripts;
+                const devScript = scripts?.dev;
+                if (!devScript)
+                    continue;
+                const portMatch = devScript.match(/--port\s+(\d+)/);
+                const port = portMatch?.[1] ? parseInt(portMatch[1], 10) : 3000;
+                candidates.push({ name: entry.name, port });
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    // Prefer app with explicit port, then first candidate
+    return candidates.find(c => c.port !== 3000) ?? candidates[0] ?? null;
+}
+function detectPackageManager(root) {
+    if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")))
+        return "bun install";
+    if (existsSync(join(root, "pnpm-lock.yaml")))
+        return "pnpm install";
+    if (existsSync(join(root, "yarn.lock")))
+        return "yarn install";
+    return "npm install";
+}
+function findEnvFiles(root) {
+    const envFiles = [".env", ".env.local", ".env.development", ".env.development.local"];
+    return envFiles.filter((f) => existsSync(join(root, f)));
+}
+export function generateConfig(projectRoot, options = {}) {
+    const { appDir, force } = options;
+    const configPath = join(projectRoot, CONFIG_FILE);
+    if (existsSync(configPath) && !force) {
+        return { created: false, message: "sanjang.config.js already exists." };
+    }
+    // Detect from selected app subdirectory or root
+    const detectRoot = appDir ? join(projectRoot, appDir) : projectRoot;
+    const detected = detectProject(detectRoot);
+    // Override cwd and setup for subdirectory apps
+    if (appDir && appDir !== ".") {
+        detected.dev.cwd = appDir;
+        if (detected.setup) {
+            detected.setup = `cd '${appDir.replace(/'/g, "'\\''")}' && ${detected.setup}`;
+        }
+    }
+    // Smart env detection — scan entire project tree, not just root
+    detected.copyFiles = deepFindEnvFiles(projectRoot).filter(
+    // Exclude .env.example, .env.test, .env.template
+    (f) => !f.includes("example") && !f.includes("template") && !f.includes(".test"));
+    // Detect potential issues
+    const issues = detectSetupIssues(detectRoot);
+    const lines = [
+        "export default {",
+        `  // ${detected.framework} detected`,
+        "",
+        "  // Dev server command",
+        "  dev: {",
+        `    command: '${detected.dev.command}',`,
+        `    port: ${detected.dev.port},`,
+        `    portFlag: ${detected.dev.portFlag ? `'${detected.dev.portFlag}'` : "null"},`,
+        `    cwd: '${detected.dev.cwd}',`,
+        "  },",
+        "",
+    ];
+    if (detected.setup) {
+        lines.push(`  // Install dependencies after creating a camp`);
+        lines.push(`  setup: ${JSON.stringify(detected.setup)},`);
+        lines.push("");
+    }
+    if (detected.copyFiles.length) {
+        lines.push("  // Copy gitignored files from main repo");
+        lines.push(`  copyFiles: ${JSON.stringify(detected.copyFiles)},`);
+        lines.push("");
+    }
+    if (detected._note) {
+        lines.push(`  // NOTE: ${detected._note}`);
+        lines.push("");
+    }
+    lines.push("  // (optional) Backend server");
+    lines.push("  // backend: {");
+    lines.push("  //   command: 'npm run start:api',");
+    lines.push("  //   port: 8000,");
+    lines.push("  //   healthCheck: '/health',");
+    lines.push("  // },");
+    lines.push("};");
+    lines.push("");
+    writeFileSync(configPath, lines.join("\n"), "utf8");
+    return {
+        created: true,
+        framework: detected.framework,
+        configPath,
+        message: `sanjang.config.js created (${detected.framework} detected).`,
+    };
+}

package/dist/lib/engine/cache.d.ts

@@ -0,0 +1,7 @@
+import type { CacheApplyResult, CacheBuildResult, CacheValidation, LockfileInfo, SanjangConfig } from "../types.ts";
+export declare function findLockfile(dir: string): LockfileInfo | null;
+export declare function hashLockfile(lockfilePath: string): string;
+export declare function getCacheDir(projectRoot: string): string;
+export declare function isCacheValid(projectRoot: string, setupCwd: string): CacheValidation;
+export declare function buildCache(projectRoot: string, config: Pick<SanjangConfig, "dev" | "setup">, onLog?: (msg: string) => void): Promise<CacheBuildResult>;
+export declare function applyCacheToWorktree(projectRoot: string, wtPath: string, setupCwd: string): CacheApplyResult;

package/dist/lib/engine/cache.js

@@ -0,0 +1,183 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+const LOCKFILES = ["package-lock.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb", "bun.lock"];
+// ---------------------------------------------------------------------------
+// Lockfile helpers
+// ---------------------------------------------------------------------------
+export function findLockfile(dir) {
+    for (const name of LOCKFILES) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            return { path: p, name };
+    }
+    return null;
+}
+export function hashLockfile(lockfilePath) {
+    const content = readFileSync(lockfilePath);
+    return createHash("sha256").update(content).digest("hex");
+}
+// ---------------------------------------------------------------------------
+// Cache directory
+// ---------------------------------------------------------------------------
+export function getCacheDir(projectRoot) {
+    return join(projectRoot, ".sanjang", "cache");
+}
+function getCacheModulesDir(projectRoot, setupCwd) {
+    const base = getCacheDir(projectRoot);
+    return setupCwd === "." ? join(base, "node_modules") : join(base, setupCwd, "node_modules");
+}
+function getHashFile(projectRoot, setupCwd = ".") {
+    const base = getCacheDir(projectRoot);
+    const name = setupCwd === "." ? "lockfile.hash" : `lockfile-${setupCwd.replace(/\//g, "-")}.hash`;
+    return join(base, name);
+}
+// ---------------------------------------------------------------------------
+// Cache validation
+// ---------------------------------------------------------------------------
+export function isCacheValid(projectRoot, setupCwd) {
+    const cacheModules = getCacheModulesDir(projectRoot, setupCwd);
+    if (!existsSync(cacheModules)) {
+        return { valid: false, reason: "cache not found" };
+    }
+    const hashFile = getHashFile(projectRoot, setupCwd);
+    if (!existsSync(hashFile)) {
+        return { valid: false, reason: "no hash file" };
+    }
+    const srcDir = setupCwd === "." ? projectRoot : join(projectRoot, setupCwd);
+    const lockfile = findLockfile(srcDir);
+    if (!lockfile) {
+        return { valid: false, reason: "no lockfile in project" };
+    }
+    const storedHash = readFileSync(hashFile, "utf8").trim();
+    const currentHash = hashLockfile(lockfile.path);
+    if (storedHash !== currentHash) {
+        return { valid: false, reason: "lockfile changed" };
+    }
+    return { valid: true };
+}
+// ---------------------------------------------------------------------------
+// Find all node_modules dirs (monorepo support)
+// ---------------------------------------------------------------------------
+function findAllNodeModules(baseDir, maxDepth = 4) {
+    const results = [];
+    function walk(dir, depth) {
+        if (depth > maxDepth)
+            return;
+        if (!existsSync(dir))
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name === "node_modules") {
+                results.push(join(dir, entry.name));
+            }
+            else if (!entry.name.startsWith(".")) {
+                walk(join(dir, entry.name), depth + 1);
+            }
+        }
+    }
+    walk(baseDir, 0);
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Build cache
+// ---------------------------------------------------------------------------
+export async function buildCache(projectRoot, config, onLog) {
+    const start = Date.now();
+    const setupCwd = config.dev?.cwd || ".";
+    const srcDir = setupCwd === "." ? projectRoot : join(projectRoot, setupCwd);
+    const modulesDir = join(srcDir, "node_modules");
+    const lockfile = findLockfile(srcDir);
+    if (!lockfile) {
+        return { success: false, error: "lockfile not found", duration: Date.now() - start };
+    }
+    if (!existsSync(modulesDir)) {
+        if (!config.setup) {
+            return { success: false, error: "no setup command and no node_modules", duration: Date.now() - start };
+        }
+        onLog?.("node_modules가 없습니다. 설치를 실행합니다...");
+        const exitCode = await runSetup(config.setup, projectRoot, onLog);
+        if (exitCode !== 0) {
+            return { success: false, error: `setup failed (exit ${exitCode})`, duration: Date.now() - start };
+        }
+        if (!existsSync(modulesDir)) {
+            return { success: false, error: "setup completed but node_modules not found", duration: Date.now() - start };
+        }
+    }
+    const allModules = findAllNodeModules(srcDir);
+    onLog?.(`캐시에 node_modules를 저장합니다... (${allModules.length}개 디렉토리)`);
+    const cacheDir = getCacheDir(projectRoot);
+    const cacheBase = setupCwd === "." ? cacheDir : join(cacheDir, setupCwd);
+    if (existsSync(cacheBase)) {
+        rmSync(cacheBase, { recursive: true, force: true });
+    }
+    mkdirSync(cacheBase, { recursive: true });
+    try {
+        for (const modDir of allModules) {
+            const rel = relative(srcDir, modDir);
+            const target = join(cacheBase, rel);
+            mkdirSync(join(target, ".."), { recursive: true });
+            cpSync(modDir, target, { recursive: true });
+        }
+    }
+    catch (err) {
+        return { success: false, error: `cache copy failed: ${err.message}`, duration: Date.now() - start };
+    }
+    writeFileSync(getHashFile(projectRoot, setupCwd), hashLockfile(lockfile.path), "utf8");
+    const duration = Date.now() - start;
+    onLog?.(`캐시 저장 완료 (${allModules.length}개, ${(duration / 1000).toFixed(1)}초)`);
+    return { success: true, duration };
+}
+// ---------------------------------------------------------------------------
+// Apply cache to worktree
+// ---------------------------------------------------------------------------
+export function applyCacheToWorktree(projectRoot, wtPath, setupCwd) {
+    const start = Date.now();
+    const validity = isCacheValid(projectRoot, setupCwd);
+    if (!validity.valid) {
+        return { applied: false, reason: validity.reason };
+    }
+    const cacheBase = setupCwd === "." ? getCacheDir(projectRoot) : join(getCacheDir(projectRoot), setupCwd);
+    const targetBase = setupCwd === "." ? wtPath : join(wtPath, setupCwd);
+    const cachedModules = findAllNodeModules(cacheBase);
+    if (cachedModules.length === 0) {
+        return { applied: false, reason: "no cached node_modules found" };
+    }
+    try {
+        for (const cachedDir of cachedModules) {
+            const rel = relative(cacheBase, cachedDir);
+            const target = join(targetBase, rel);
+            mkdirSync(join(target, ".."), { recursive: true });
+            cpSync(cachedDir, target, { recursive: true });
+        }
+    }
+    catch (err) {
+        return { applied: false, reason: `clone failed: ${err.message}` };
+    }
+    return { applied: true, duration: Date.now() - start, count: cachedModules.length };
+}
+// ---------------------------------------------------------------------------
+// Internal: run setup command
+// ---------------------------------------------------------------------------
+function runSetup(command, cwd, onLog) {
+    return new Promise((resolve) => {
+        const proc = spawn(command, [], {
+            cwd,
+            shell: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        proc.stdout.on("data", (d) => onLog?.(d.toString().trimEnd()));
+        proc.stderr.on("data", (d) => onLog?.(d.toString().trimEnd()));
+        proc.on("close", (code) => resolve(code ?? 1));
+        proc.on("error", () => resolve(1));
+    });
+}

package/dist/lib/engine/config-hotfix.d.ts

@@ -0,0 +1,7 @@
+export interface ConfigFix {
+    type: "add-copyfiles" | "update-setup" | "info";
+    description: string;
+    patch: Record<string, unknown>;
+}
+export declare function suggestConfigFix(projectRoot: string, logs: string[]): ConfigFix | null;
+export declare function applyConfigFix(projectRoot: string, fix: ConfigFix): boolean;