@apps-in-toss/cli 3.0.1 → 3.0.2

package/dist/index.js

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { Builtins, Cli, Command, Option } from "clipanion";
 import * as p from "@clack/prompts";
 import path from "path";
 import { appendFile, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
-import path$1, { extname, join, resolve } from "node:path";
+import path$1, { basename, dirname, extname, join, parse, resolve } from "node:path";
 import { AppsInTossBundle, PlatformType } from "@apps-in-toss/ait-format";
 import { loadConfig } from "c12";
 import { uuidv7 } from "uuidv7";
-import fs, { existsSync } from "node:fs";
+import fs, { existsSync, readFileSync } from "node:fs";
 import assert from "node:assert";
 import os from "node:os";
 import { setTimeout } from "node:timers/promises";
 import jscodeshift from "jscodeshift";
+import { spawn } from "node:child_process";
 //#region src/utils/getPackageRoot.ts
 function getPackageRoot(base) {
 	let dirPath = base;
@@ -430,12 +432,227 @@ var DeployCommand = class extends Command {
 	}
 };
 //#endregion
+//#region src/utils/jscodeshift.ts
+/**
+* 설정 파일 확장자에 맞는 파서를 골라요.
+* 기본 파서는 JavaScript 전용이라 .ts 설정 파일의 type 선언, satisfies 같은
+* TypeScript 문법에서 파싱이 실패해요.
+*/
+function getParserForFile(filepath) {
+	switch (extname(filepath)) {
+		case ".ts":
+		case ".mts":
+		case ".cts": return jscodeshift.withParser("ts");
+		case ".tsx": return jscodeshift.withParser("tsx");
+		default: return jscodeshift.withParser("babel");
+	}
+}
+/**
+* 이름이 있는 오브젝트 프로퍼티만 골라내요.
+* 파서에 따라 Property(estree) 또는 ObjectProperty(babel) 노드로 파싱되므로 둘 다 확인해요.
+*/
+function asNamedProperty(prop) {
+	if ((jscodeshift.Property.check(prop) || jscodeshift.ObjectProperty.check(prop)) && jscodeshift.Identifier.check(prop.key)) return prop;
+	return null;
+}
+//#endregion
+//#region src/utils/devtools.ts
+const DEVTOOLS_PACKAGE_NAME = "@apps-in-toss/devtools";
+const DEVTOOLS_UNPLUGIN_SPECIFIER = "@apps-in-toss/devtools/unplugin";
+const DEVTOOLS_IMPORT_NAME = "aitDevtools";
+/**
+* changesets fixed 그룹으로 CLI와 devtools가 항상 같은 버전으로 배포돼요.
+* 그래서 CLI 자신의 버전이 곧 함께 설치할 devtools의 호환 버전이에요.
+*/
+function getDevtoolsVersionRange() {
+	const { version } = createRequire(import.meta.url)("@apps-in-toss/cli/package.json");
+	return `^${version}`;
+}
+const BUNDLER_CONFIG_BASES = [
+	["vite.config", "vite"],
+	["webpack.config", "webpack"],
+	["rspack.config", "rspack"],
+	["rollup.config", "rollup"]
+];
+const CONFIG_EXTENSIONS = [
+	".ts",
+	".mts",
+	".cts",
+	".js",
+	".mjs",
+	".cjs"
+];
+/**
+* 프로젝트 루트에서 devtools unplugin을 꽂을 번들러 설정 파일을 찾아요.
+*/
+function findBundlerConfig(projectRoot) {
+	for (const [base, bundler] of BUNDLER_CONFIG_BASES) for (const extension of CONFIG_EXTENSIONS) {
+		const path = join(projectRoot, `${base}${extension}`);
+		if (existsSync(path)) return {
+			path,
+			bundler
+		};
+	}
+	return null;
+}
+/**
+* 번들러 설정 소스의 plugins 배열 맨 앞에 devtools unplugin을 꽂아요.
+* 맨 앞이어야 SDK → mock alias가 다른 플러그인의 resolve보다 먼저 걸려요.
+*
+* 파일에 쓰지 않고 변환된 소스만 돌려줘요. 변환할 수 없는 모양(CommonJS 설정,
+* plugins 배열 없음)이면 needs-manual로 알려서 호출부가 수동 안내를 하게 해요.
+*/
+function injectDevtoolsPlugin(source, configPath, bundler) {
+	if (source.includes("@apps-in-toss/devtools/unplugin")) return { status: "already-installed" };
+	if (/\bmodule\.exports\b|\brequire\s*\(/.test(source)) return {
+		status: "needs-manual",
+		reason: "CommonJS 형식 설정 파일은 자동으로 수정하지 않아요."
+	};
+	const j = getParserForFile(configPath);
+	let root;
+	try {
+		root = j(source);
+	} catch (error) {
+		return {
+			status: "needs-manual",
+			reason: `설정 파일을 파싱하지 못했어요: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+	let pluginsArray = null;
+	root.find(jscodeshift.ObjectExpression).forEach((path) => {
+		if (pluginsArray != null) return;
+		for (const rawProp of path.value.properties) {
+			const prop = asNamedProperty(rawProp);
+			if (prop?.key.name === "plugins" && jscodeshift.ArrayExpression.check(prop.value)) {
+				pluginsArray = prop.value;
+				return;
+			}
+		}
+	});
+	if (pluginsArray == null) return {
+		status: "needs-manual",
+		reason: "설정 파일에서 plugins 배열을 찾지 못했어요."
+	};
+	const pluginCall = jscodeshift.callExpression(jscodeshift.memberExpression(jscodeshift.identifier(DEVTOOLS_IMPORT_NAME), jscodeshift.identifier(bundler)), []);
+	pluginsArray.elements.unshift(pluginCall);
+	const importDecl = jscodeshift.importDeclaration([jscodeshift.importDefaultSpecifier(jscodeshift.identifier(DEVTOOLS_IMPORT_NAME))], jscodeshift.stringLiteral(DEVTOOLS_UNPLUGIN_SPECIFIER));
+	const imports = root.find(jscodeshift.ImportDeclaration);
+	if (imports.size() > 0) imports.at(imports.size() - 1).insertAfter(importDecl);
+	else root.get().node.program.body.unshift(importDecl);
+	return {
+		status: "transformed",
+		source: root.toSource()
+	};
+}
+/**
+* 자동 주입에 실패했을 때 보여줄 수동 설치 안내예요.
+*/
+function devtoolsManualGuide(bundler = "vite") {
+	return [
+		`번들러 설정의 plugins 배열 맨 앞에 devtools를 직접 추가해주세요.`,
+		"",
+		`  import ${DEVTOOLS_IMPORT_NAME} from "${DEVTOOLS_UNPLUGIN_SPECIFIER}";`,
+		"",
+		`  plugins: [${DEVTOOLS_IMPORT_NAME}.${bundler}(), /* 기존 플러그인들 */]`
+	].join("\n");
+}
+//#endregion
 //#region src/utils/ensureSelect.ts
 async function ensureSelect({ value, prompt }) {
 	if (value) return value;
 	return await prompt();
 }
 //#endregion
+//#region src/utils/installDependencies.ts
+function asPackageManager(name) {
+	if (name === "npm" || name === "yarn" || name === "pnpm" || name === "bun") return name;
+	return null;
+}
+/**
+* CLI를 실행한 패키지 매니저를 `npm_config_user_agent`에서 읽어요.
+* `yarn ait ...`, `npx ait ...`처럼 매니저를 거쳐 실행되면 항상 세팅되는 값이라
+* lockfile 추측보다 정확해요. 예: "yarn/4.12.0 npm/? node/v24.14.0 darwin arm64"
+*/
+function packageManagerFromUserAgent(userAgent) {
+	return asPackageManager(userAgent?.split("/")[0]);
+}
+/**
+* 프로젝트에서 위로 올라가며 package.json의 `packageManager` 필드를 찾아요.
+* 모노레포처럼 필드가 상위 디렉토리에 있는 경우까지 커버해요.
+*/
+function packageManagerFromField(projectRoot) {
+	let dir = projectRoot;
+	const { root } = parse(dir);
+	while (true) {
+		const packageJsonPath = join(dir, "package.json");
+		if (existsSync(packageJsonPath)) try {
+			const { packageManager } = JSON.parse(readFileSync(packageJsonPath, { encoding: "utf-8" }));
+			const found = asPackageManager(packageManager?.split("@")[0]);
+			if (found != null) return found;
+		} catch {}
+		if (dir === root) return null;
+		dir = dirname(dir);
+	}
+}
+/**
+* 의존성을 설치할 패키지 매니저를 알아내요.
+* CLI를 실행한 매니저(`npm_config_user_agent`)가 1순위, 직접 실행됐을 때는
+* `packageManager` 필드로 폴백하고, 둘 다 없으면 npm을 써요.
+*/
+function detectPackageManager(projectRoot) {
+	return packageManagerFromUserAgent(process.env.npm_config_user_agent) ?? packageManagerFromField(projectRoot) ?? "npm";
+}
+/**
+* 감지한 패키지 매니저로 의존성 설치를 한 번 실행해요.
+* 실패해도 전체 흐름을 멈추지 않고, 직접 실행할 명령어를 안내해요.
+*/
+async function installDependencies(projectRoot) {
+	const packageManager = detectPackageManager(projectRoot);
+	const spinner = p.spinner();
+	spinner.start(`의존성을 설치하는 중... (${packageManager} install)`);
+	const { code, output } = await runInstall(packageManager, projectRoot);
+	if (code === 0) {
+		spinner.stop(`의존성을 설치했어요. (${packageManager} install)`);
+		return;
+	}
+	spinner.stop(`${packageManager} install 실행에 실패했어요.`);
+	const outputTail = output.trim().split("\n").slice(-15).join("\n");
+	if (outputTail.length > 0) p.log.message(outputTail);
+	p.log.warn(`직접 실행해주세요: ${packageManager} install`);
+}
+function runInstall(packageManager, cwd) {
+	return new Promise((resolvePromise) => {
+		const child = spawn(packageManager, ["install"], {
+			cwd,
+			shell: process.platform === "win32",
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let output = "";
+		child.stdout.on("data", (chunk) => {
+			output += chunk.toString();
+		});
+		child.stderr.on("data", (chunk) => {
+			output += chunk.toString();
+		});
+		child.on("error", (error) => {
+			resolvePromise({
+				code: null,
+				output: `${output}\n${error.message}`
+			});
+		});
+		child.on("close", (code) => {
+			resolvePromise({
+				code,
+				output
+			});
+		});
+	});
+}
+//#endregion
 //#region src/utils/kebabCase.ts
 /**
 * 문자열을 케밥-케이스로 변환해요. (예: "My App" -> "my-app", "myApp" -> "my-app")
@@ -484,6 +701,11 @@ async function templateWebFramework({ appName, cwd, skipInput }) {
 	packageJson.scripts ??= {};
 	if (packageJson.scripts.build) packageJson.scripts.build = packageJson.scripts.build + " && ait build";
 	packageJson.scripts.deploy = "ait deploy";
+	p.log.step(`${DEVTOOLS_PACKAGE_NAME}를 devDependencies에 추가하는 중...`);
+	packageJson.devDependencies = {
+		...packageJson.devDependencies,
+		[DEVTOOLS_PACKAGE_NAME]: getDevtoolsVersionRange()
+	};
 	await writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2), { encoding: "utf-8" });
 	p.log.step(".gitignore 파일을 업데이트하는 중...");
 	await appendFile(join(cwd, ".gitignore"), "\n*.ait\n");
@@ -502,6 +724,33 @@ async function templateWebFramework({ appName, cwd, skipInput }) {
 		webBundleDir
 	});
 	await writeFile(join(cwd, "apps-in-toss.config.ts"), config, { encoding: "utf-8" });
+	await setupDevtoolsPlugin(cwd);
+	await installDependencies(cwd);
+}
+/**
+* 번들러 설정의 plugins 맨 앞에 devtools unplugin을 자동으로 꽂아줘요.
+* 자동 주입이 어려운 모양이면 파일을 건드리지 않고 수동 안내만 보여줘요.
+*/
+async function setupDevtoolsPlugin(cwd) {
+	const bundlerConfig = findBundlerConfig(cwd);
+	if (bundlerConfig == null) {
+		p.note(devtoolsManualGuide(), "devtools 수동 설치 안내");
+		return;
+	}
+	const result = injectDevtoolsPlugin(await readFile(bundlerConfig.path, { encoding: "utf-8" }), bundlerConfig.path, bundlerConfig.bundler);
+	switch (result.status) {
+		case "transformed":
+			await writeFile(bundlerConfig.path, result.source, { encoding: "utf-8" });
+			p.log.step(`${basename(bundlerConfig.path)}에 devtools 플러그인을 추가했어요.`);
+			break;
+		case "already-installed":
+			p.log.info("devtools 플러그인이 이미 설정되어 있어요.");
+			break;
+		case "needs-manual":
+			p.log.warn(result.reason);
+			p.note(devtoolsManualGuide(bundlerConfig.bundler), "devtools 수동 설치 안내");
+			break;
+	}
 }
 var InitCommand = class extends Command {
 	static paths = [["init"]];
@@ -560,14 +809,15 @@ async function migrateWebFrameworkV3() {
 		process.exit(1);
 	}
 	await runMigration(plan);
+	await installDependencies(projectRoot);
 	p.log.success("마이그레이션이 완료됐어요.");
-	printPostMigrationNotes(plan.appName);
+	printPostMigrationNotes(plan);
 }
 /**
 * 마이그레이션 이후 개발자가 꼭 알아야 하는 유의사항을 안내해요.
 */
-function printPostMigrationNotes(appName) {
-	const host = appName ?? "<appName>";
+function printPostMigrationNotes(plan) {
+	const host = plan.appName ?? "<appName>";
 	p.note([
 		"1. SDK 3.x 출시 후 롤백이 안돼요",
 		"   SDK 3.x 이상이 적용된 앱 번들을 출시하면 SDK 2.x 버전으로 롤백할 수 없어요.",
@@ -579,8 +829,13 @@ function printPostMigrationNotes(appName) {
 		"   Origin 허용 목록에 다음 도메인을 등록하세요.",
 		"",
 		`   - https://${host}.web.tossmini.com : 실제 서비스 환경`,
-		`   - https://${host}.private-web.tossmini.com : 콘솔 QR 테스트 환경`
+		`   - https://${host}.private-web.tossmini.com : 콘솔 QR 테스트 환경`,
+		"",
+		`3. 개발용 devtools가 함께 설치돼요`,
+		`   ${DEVTOOLS_PACKAGE_NAME}가 devDependencies에 추가됐어요.`,
+		"   브라우저에서 mock SDK와 devtools 패널로 미니앱을 개발할 수 있어요."
 	].join("\n"), "유의사항");
+	if (plan.devtoolsManualBundler != null) p.note(devtoolsManualGuide(plan.devtoolsManualBundler), "devtools 수동 설치 안내");
 }
 /**
 * 파일을 변경하기 전에 모든 조건을 검증하고, 실행할 변경 내용을 준비해요.
@@ -662,8 +917,13 @@ async function planMigration(projectRoot) {
 			...packageJson.parsed.scripts,
 			dev: devCommand,
 			build: `${buildCommand} && ait build`
+		},
+		devDependencies: {
+			...packageJson.parsed.devDependencies,
+			[DEVTOOLS_PACKAGE_NAME]: getDevtoolsVersionRange()
 		}
 	};
+	const { bundlerConfig, devtoolsManualBundler } = await planDevtoolsPluginInjection(projectRoot);
 	const appName = graniteConfig.config.appName;
 	return {
 		issues,
@@ -676,33 +936,74 @@ async function planMigration(projectRoot) {
 			hasExistingAppsInTossConfig,
 			packageJsonPath,
 			packageJsonSource: packageJson.source,
-			nextPackageJsonSource: JSON.stringify(nextPackageJson, null, 2) + (packageJson.source.endsWith("\n") ? "\n" : "")
+			nextPackageJsonSource: JSON.stringify(nextPackageJson, null, 2) + (packageJson.source.endsWith("\n") ? "\n" : ""),
+			bundlerConfig,
+			devtoolsManualBundler
 		}
 	};
 }
 /**
+* devtools unplugin을 꽂을 번들러 설정 변경을 메모리에서만 준비해요.
+* 자동으로 못 꽂는 모양이면 파일을 건드리지 않고 수동 안내 대상만 정해요.
+*/
+async function planDevtoolsPluginInjection(projectRoot) {
+	const found = findBundlerConfig(projectRoot);
+	if (found == null) return {
+		bundlerConfig: null,
+		devtoolsManualBundler: "vite"
+	};
+	const source = (await readFile(found.path)).toString();
+	const result = injectDevtoolsPlugin(source, found.path, found.bundler);
+	switch (result.status) {
+		case "transformed": return {
+			bundlerConfig: {
+				path: found.path,
+				source,
+				nextSource: result.source
+			},
+			devtoolsManualBundler: null
+		};
+		case "already-installed": return {
+			bundlerConfig: null,
+			devtoolsManualBundler: null
+		};
+		case "needs-manual": return {
+			bundlerConfig: null,
+			devtoolsManualBundler: found.bundler
+		};
+	}
+}
+/**
 * 준비된 변경 내용을 트랜잭션으로 실행해요.
 * 스텝이 하나라도 실패하면 완료된 스텝을 역순으로 되돌리고 종료해요.
 * 기존 apps-in-toss.config가 있으면 백업해뒀다가, 모두 성공하면 백업을 지워요.
 */
 async function runMigration(plan) {
 	const backupPath = `${plan.appsInTossConfigPath}.bak`;
+	const backupSteps = plan.hasExistingAppsInTossConfig ? [{
+		description: "기존 apps-in-toss.config 파일을 백업해요.",
+		run: () => rename(plan.appsInTossConfigPath, backupPath),
+		undo: () => rename(backupPath, plan.appsInTossConfigPath)
+	}] : [];
+	const bundlerConfig = plan.bundlerConfig;
+	const bundlerConfigSteps = bundlerConfig == null ? [] : [{
+		description: "번들러 설정에 devtools 플러그인을 추가해요.",
+		run: () => atomicWriteFile(bundlerConfig.path, bundlerConfig.nextSource),
+		undo: () => atomicWriteFile(bundlerConfig.path, bundlerConfig.source)
+	}];
 	await executeTransaction([
-		...plan.hasExistingAppsInTossConfig ? [{
-			description: "기존 apps-in-toss.config 파일을 백업해요.",
-			run: () => rename(plan.appsInTossConfigPath, backupPath),
-			undo: () => rename(backupPath, plan.appsInTossConfigPath)
-		}] : [],
+		...backupSteps,
 		{
 			description: "granite.config를 apps-in-toss.config로 마이그레이션해요.",
 			run: () => atomicWriteFile(plan.appsInTossConfigPath, plan.appsInTossConfigSource),
 			undo: () => rm(plan.appsInTossConfigPath, { force: true })
 		},
 		{
-			description: "package.json의 dev, build 스크립트를 수정해요.",
+			description: "package.json의 dev, build 스크립트를 수정하고 devtools를 추가해요.",
 			run: () => atomicWriteFile(plan.packageJsonPath, plan.nextPackageJsonSource),
 			undo: () => atomicWriteFile(plan.packageJsonPath, plan.packageJsonSource)
 		},
+		...bundlerConfigSteps,
 		{
 			description: "granite.config 파일을 삭제해요.",
 			run: () => rm(plan.graniteConfigPath),
@@ -789,28 +1090,6 @@ function transformGraniteConfig(source, configPath) {
 	});
 	return root.toSource();
 }
-/**
-* granite.config 파일 확장자에 맞는 파서를 골라요.
-* 기본 파서는 JavaScript 전용이라 .ts 설정 파일의 type 선언, satisfies 같은
-* TypeScript 문법에서 파싱이 실패해요.
-*/
-function getParserForFile(filepath) {
-	switch (extname(filepath)) {
-		case ".ts":
-		case ".mts":
-		case ".cts": return jscodeshift.withParser("ts");
-		case ".tsx": return jscodeshift.withParser("tsx");
-		default: return jscodeshift.withParser("babel");
-	}
-}
-/**
-* 이름이 있는 오브젝트 프로퍼티만 골라내요.
-* 파서에 따라 Property(estree) 또는 ObjectProperty(babel) 노드로 파싱되므로 둘 다 확인해요.
-*/
-function asNamedProperty(prop) {
-	if ((jscodeshift.Property.check(prop) || jscodeshift.ObjectProperty.check(prop)) && jscodeshift.Identifier.check(prop.key)) return prop;
-	return null;
-}
 function getErrorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apps-in-toss/cli",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "license": "BSD-3-Clause",
   "bin": {
     "ait": "dist/index.js"