sayren 0.16.1 → 0.17.0

package/dist/index.mjs

@@ -5,7 +5,7 @@ import { createInterface } from "node:readline/promises";
 import { APP_DEPLOY_KEY_PATTERN, APP_README_MAX_BYTES, APP_SECRET_PATTERNS, APP_SERVER_BUNDLE_MAX_GZIP_BYTES, APP_UI_MAX_BYTES, APP_UI_MAX_FILES, ApiError, ApprovalPendingError, STOREFRONT_BUILD_TERMINAL_STATUSES, STOREFRONT_SOURCE_BLOB_BATCH_MAX, STORE_CODE_PATTERN, appIconProblem, appManifestProblems, appManifestSchema, createStoreClient, normalizeStorefrontPath } from "@sayren/store-sdk";
 import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
-import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { delimiter, dirname, extname, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { gzipSync } from "node:zlib";
 import { createHash, randomBytes } from "node:crypto";
@@ -6621,6 +6621,42 @@ const cli_edit_session_open = ((inputs = {}, options = {}) => {
 	return ko_cli_edit_session_open(inputs);
 });
 
+//#endregion
+//#region src/paraglide/messages/cli_env_approval.js
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+/** @typedef {{}} Cli_Env_ApprovalInputs */
+const ko_cli_env_approval = () => {
+	return `env 변경은 승인 대기입니다. 상점 플랫폼에서 승인하면 반영됩니다`;
+};
+/**
+
+* @param {Cli_Env_ApprovalInputs} inputs
+* @param {{ locale?: "ko" }} options
+* @returns {LocalizedString}
+*/
+const cli_env_approval = ((inputs = {}, options = {}) => {
+	experimentalStaticLocale ?? options.locale ?? getLocale();
+	return ko_cli_env_approval(inputs);
+});
+
+//#endregion
+//#region src/paraglide/messages/cli_env_empty.js
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+/** @typedef {{}} Cli_Env_EmptyInputs */
+const ko_cli_env_empty = () => {
+	return `설정한 env가 없습니다. npx sayren env add <키> <값>으로 추가하십시오`;
+};
+/**
+
+* @param {Cli_Env_EmptyInputs} inputs
+* @param {{ locale?: "ko" }} options
+* @returns {LocalizedString}
+*/
+const cli_env_empty = ((inputs = {}, options = {}) => {
+	experimentalStaticLocale ?? options.locale ?? getLocale();
+	return ko_cli_env_empty(inputs);
+});
+
 //#endregion
 //#region src/paraglide/messages/cli_env_not_linked.js
 /** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
@@ -6639,6 +6675,24 @@ const cli_env_not_linked = ((inputs, options = {}) => {
 	return ko_cli_env_not_linked(inputs);
 });
 
+//#endregion
+//#region src/paraglide/messages/cli_env_pull_skipped.js
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+/** @typedef {{ keys: NonNullable<unknown> }} Cli_Env_Pull_SkippedInputs */
+const ko_cli_env_pull_skipped = (i) => {
+	return `.env 한 줄로 같은 값을 쓸 수 없어 건너뛴 env가 있습니다: ${i?.keys}. 로컬에서는 직접 넣으십시오`;
+};
+/**
+
+* @param {Cli_Env_Pull_SkippedInputs} inputs
+* @param {{ locale?: "ko" }} options
+* @returns {LocalizedString}
+*/
+const cli_env_pull_skipped = ((inputs, options = {}) => {
+	experimentalStaticLocale ?? options.locale ?? getLocale();
+	return ko_cli_env_pull_skipped(inputs);
+});
+
 //#endregion
 //#region src/paraglide/messages/cli_env_pulled.js
 /** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
@@ -6657,6 +6711,78 @@ const cli_env_pulled = ((inputs, options = {}) => {
 	return ko_cli_env_pulled(inputs);
 });
 
+//#endregion
+//#region src/paraglide/messages/cli_env_pulled_vars.js
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+/** @typedef {{ file: NonNullable<unknown>, count: NonNullable<unknown> }} Cli_Env_Pulled_VarsInputs */
+const ko_cli_env_pulled_vars = (i) => {
+	return `${i?.file}에 일반 env ${i?.count}개를 썼습니다(비밀 값은 배포된 사이트에만 들어가 받지 않습니다)`;
+};
+/**
+
+* @param {Cli_Env_Pulled_VarsInputs} inputs
+* @param {{ locale?: "ko" }} options
+* @returns {LocalizedString}
+*/
+const cli_env_pulled_vars = ((inputs, options = {}) => {
+	experimentalStaticLocale ?? options.locale ?? getLocale();
+	return ko_cli_env_pulled_vars(inputs);
+});
+
+//#endregion
+//#region src/paraglide/messages/cli_env_removed.js
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+/** @typedef {{ key: NonNullable<unknown> }} Cli_Env_RemovedInputs */
+const ko_cli_env_removed = (i) => {
+	return `env ${i?.key}을(를) 지웠습니다. 올라가 있는 버전에서도 곧바로 빠집니다`;
+};
+/**
+
+* @param {Cli_Env_RemovedInputs} inputs
+* @param {{ locale?: "ko" }} options
+* @returns {LocalizedString}
+*/
+const cli_env_removed = ((inputs, options = {}) => {
+	experimentalStaticLocale ?? options.locale ?? getLocale();
+	return ko_cli_env_removed(inputs);
+});
+
+//#endregion
+//#region src/paraglide/messages/cli_env_secret_mask.js
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+/** @typedef {{}} Cli_Env_Secret_MaskInputs */
+const ko_cli_env_secret_mask = () => {
+	return `(비밀 값)`;
+};
+/**
+
+* @param {Cli_Env_Secret_MaskInputs} inputs
+* @param {{ locale?: "ko" }} options
+* @returns {LocalizedString}
+*/
+const cli_env_secret_mask = ((inputs = {}, options = {}) => {
+	experimentalStaticLocale ?? options.locale ?? getLocale();
+	return ko_cli_env_secret_mask(inputs);
+});
+
+//#endregion
+//#region src/paraglide/messages/cli_env_set.js
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+/** @typedef {{ key: NonNullable<unknown> }} Cli_Env_SetInputs */
+const ko_cli_env_set = (i) => {
+	return `env ${i?.key}을(를) 설정했습니다. 올라가 있는 버전에 곧바로 반영됩니다`;
+};
+/**
+
+* @param {Cli_Env_SetInputs} inputs
+* @param {{ locale?: "ko" }} options
+* @returns {LocalizedString}
+*/
+const cli_env_set = ((inputs, options = {}) => {
+	experimentalStaticLocale ?? options.locale ?? getLocale();
+	return ko_cli_env_set(inputs);
+});
+
 //#endregion
 //#region src/paraglide/messages/cli_env_store_code_unknown.js
 /** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
@@ -6680,7 +6806,7 @@ const cli_env_store_code_unknown = ((inputs = {}, options = {}) => {
 /** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
 /** @typedef {{}} Cli_Env_UsageInputs */
 const ko_cli_env_usage = () => {
-	return `사용법: npx sayren env pull [--dir <폴더>]`;
+	return `사용법: npx sayren env pull [--dir <폴더>] · env ls · env add <키> <값> [--secret] · env rm <키>`;
 };
 /**
 
@@ -10070,7 +10196,7 @@ async function selectStore(auth, client, io, candidates, folderStore = null) {
 
 //#endregion
 //#region package.json
-var version = "0.16.1";
+var version = "0.17.0";
 
 //#endregion
 //#region src/client.ts
@@ -11086,11 +11212,114 @@ async function appMain(positional, flags, io) {
 	}
 }
 
+//#endregion
+//#region ../../apps/hosting-sandbox/src/project-config.ts
+/**
+* 프로젝트 설정 `sayren.json`(#298 P1). 셀러 계약은 `package.json` 스크립트와 이 파일뿐이다 — 플랫폼은 프레임워크를 감지하거나 빌드를 보정하지 않는다.
+* - `buildCommand`: 빌드 명령. 없으면 `package.json`의 `build` 스크립트, 그것도 없으면 빌드하지 않는다(순수 HTML)
+* - `output.static`: 정적 파일 폴더(작업 트리 기준). `.`은 루트
+* - `output.server`: Web 표준 fetch 핸들러(`export default { fetch(request, env) }`)를 내보내는 ES 모듈. 없으면 정적 전용 사이트다
+*
+* 파일이 없으면 #298 이전 사이트(옛 basic·시작 코드)의 경로를 기본값으로 쓴다. 파일이 있으면 적힌 그대로다(`output.server`를 빼면 정적 전용).
+* 런타임 이름(Workers·wrangler)은 이 계약에 넣지 않는다 — 런타임을 옮겨도(#333) 이 파일은 그대로 둔다.
+* Node API를 쓰지 않는다(Sandbox Worker·CLI가 같이 쓴다).
+*/
+const PROJECT_CONFIG_FILE = "sayren.json";
+/** `sayren.json`이 없는 사이트의 기본값 — #298 이전 빌드가 쓰던 TanStack Start 출력 경로 */
+const LEGACY_PROJECT_CONFIG = {
+	buildCommand: null,
+	output: {
+		static: "dist/client",
+		server: "dist/server/server.js"
+	}
+};
+const MAX_COMMAND_LENGTH = 1e3;
+const MAX_OUTPUT_PATH_LENGTH = 256;
+const OUTPUT_SEGMENT_RE = /^[A-Za-z0-9._@+-]+$/;
+/** 출력 경로 문제(없으면 null). 작업 트리 안의 상대 경로만 — 설치물·비밀 값 파일은 가리킬 수 없다 */
+function outputPathProblem(path, allowRoot) {
+	if (path === ".") return allowRoot ? null : "루트(.)는 쓸 수 없습니다";
+	if (path.length === 0 || path.length > MAX_OUTPUT_PATH_LENGTH) return "길이가 맞지 않습니다";
+	if (path.startsWith("/")) return "작업 트리 기준 상대 경로여야 합니다";
+	for (const seg of path.split("/")) {
+		if (seg === "" || seg === "." || seg === "..") return "빈 조각·.·..은 쓸 수 없습니다";
+		if (!OUTPUT_SEGMENT_RE.test(seg)) return "영문·숫자·._@+-만 쓸 수 있습니다";
+		if (seg === "node_modules" || seg.startsWith(".env")) return "설치물·.env 파일은 가리킬 수 없습니다";
+	}
+	return null;
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** 트리(경로 → 내용)에서 `sayren.json` 내용을 꺼낸다. 없으면 null, UTF-8이 아니면 JSON 오류로 보이게 빈 문자열 */
+function projectConfigOf(files) {
+	const bytes = files.get(PROJECT_CONFIG_FILE);
+	if (!bytes) return null;
+	try {
+		return new TextDecoder("utf-8", {
+			fatal: true,
+			ignoreBOM: false
+		}).decode(bytes);
+	} catch {
+		return "";
+	}
+}
+/** `sayren.json` 내용(없으면 null)을 읽는다. 모르는 키는 거절한다(오타가 조용히 기본값으로 빌드되지 않게) */
+function parseProjectConfig(content) {
+	if (content === null) return {
+		ok: true,
+		config: LEGACY_PROJECT_CONFIG
+	};
+	const fail = (error) => ({
+		ok: false,
+		error: `${PROJECT_CONFIG_FILE}: ${error}`
+	});
+	let raw;
+	try {
+		raw = JSON.parse(content);
+	} catch {
+		return fail("JSON 형식이 아닙니다");
+	}
+	if (!isRecord(raw)) return fail("객체여야 합니다");
+	const unknownKey = Object.keys(raw).find((k) => k !== "buildCommand" && k !== "output");
+	if (unknownKey !== void 0) return fail(`모르는 키입니다: ${unknownKey}`);
+	let buildCommand = null;
+	if (raw.buildCommand !== void 0) {
+		const cmd = raw.buildCommand;
+		if (typeof cmd !== "string" || !cmd.trim()) return fail("buildCommand는 빈 문자열이 아니어야 합니다");
+		if (cmd.length > MAX_COMMAND_LENGTH || cmd.includes("\0")) return fail(`buildCommand는 ${MAX_COMMAND_LENGTH}자 이하여야 합니다`);
+		buildCommand = cmd;
+	}
+	const output = raw.output;
+	if (!isRecord(output)) return fail("output.static이 필요합니다");
+	const outKey = Object.keys(output).find((k) => k !== "static" && k !== "server");
+	if (outKey !== void 0) return fail(`모르는 키입니다: output.${outKey}`);
+	if (typeof output.static !== "string") return fail("output.static이 필요합니다");
+	const staticProblem = outputPathProblem(output.static, true);
+	if (staticProblem) return fail(`output.static — ${staticProblem}`);
+	let server = null;
+	if (output.server !== void 0) {
+		if (typeof output.server !== "string") return fail("output.server는 문자열이어야 합니다");
+		const serverProblem = outputPathProblem(output.server, false);
+		if (serverProblem) return fail(`output.server — ${serverProblem}`);
+		if (!/\.m?js$/.test(output.server)) return fail("output.server는 .js·.mjs 모듈이어야 합니다");
+		server = output.server;
+	}
+	return {
+		ok: true,
+		config: {
+			buildCommand,
+			output: {
+				static: output.static,
+				server
+			}
+		}
+	};
+}
+
 //#endregion
 //#region ../mcp/src/rules.ts
-/** 규칙의 심각도 — 없으면 `error` */
+/** 규칙의 심각도 — 없으면 `warning` */
 function severityOf(rule) {
-	return rule?.severity ?? "error";
+	return rule?.severity ?? "warning";
 }
 /** 문서 사이트 — `doc` 경로를 절대 주소로 만들 때 쓴다 */
 const DOCS_BASE_URL = "https://docs.sayren.io";
@@ -11131,12 +11360,13 @@ const RULES = [
 	}),
 	defineRule({
 		id: "no-module-token",
+		severity: "error",
 		title: mcp_rule_no_module_token_title,
 		why: mcp_rule_no_module_token_why,
 		fix: mcp_rule_no_module_token_fix,
 		example: mcp_rule_no_module_token_example,
 		doc: "/guides/storefront-auth",
-		templateFile: "src/lib/session.server.ts"
+		templateFile: "src/lib/api.server.ts"
 	}),
 	defineRule({
 		id: "loader-first",
@@ -11145,7 +11375,7 @@ const RULES = [
 		fix: mcp_rule_loader_first_fix,
 		example: mcp_rule_loader_first_example,
 		doc: "/guides/mcp-customize",
-		templateFile: "src/routes/products.index.tsx"
+		templateFile: "src/routes/index.tsx"
 	}),
 	defineRule({
 		id: "payment-browser-launch",
@@ -11153,8 +11383,7 @@ const RULES = [
 		why: mcp_rule_payment_browser_launch_why,
 		fix: mcp_rule_payment_browser_launch_fix,
 		example: mcp_rule_payment_browser_launch_example,
-		doc: "/guides/checkout-flow",
-		templateFile: "src/lib/payments.ts"
+		doc: "/guides/checkout-flow"
 	}),
 	defineRule({
 		id: "payment-return-route",
@@ -11162,8 +11391,7 @@ const RULES = [
 		why: mcp_rule_payment_return_route_why,
 		fix: mcp_rule_payment_return_route_fix,
 		example: "useEffect(() => {\n  void payments.result().then((result) => {\n    if (result.status === \"COMPLETED\") navigate({ to: \"/checkout/complete\", search: { orderId: result.orderId } });\n  });\n}, []);",
-		doc: "/guides/checkout-flow",
-		templateFile: "src/routes/checkout.return.tsx"
+		doc: "/guides/checkout-flow"
 	}),
 	defineRule({
 		id: "payment-processing-status",
@@ -11171,8 +11399,7 @@ const RULES = [
 		why: mcp_rule_payment_processing_status_why,
 		fix: mcp_rule_payment_processing_status_fix,
 		example: mcp_rule_payment_processing_status_example,
-		doc: "/guides/checkout-flow",
-		templateFile: "src/routes/checkout.return.tsx"
+		doc: "/guides/checkout-flow"
 	}),
 	defineRule({
 		id: "payment-amounts-final",
@@ -11180,8 +11407,7 @@ const RULES = [
 		why: mcp_rule_payment_amounts_final_why,
 		fix: mcp_rule_payment_amounts_final_fix,
 		example: mcp_rule_payment_amounts_final_example,
-		doc: "/guides/shipping-fees",
-		templateFile: "src/routes/checkout.index.tsx"
+		doc: "/guides/shipping-fees"
 	}),
 	defineRule({
 		id: "payment-retry",
@@ -11189,8 +11415,7 @@ const RULES = [
 		why: mcp_rule_payment_retry_why,
 		fix: mcp_rule_payment_retry_fix,
 		example: mcp_rule_payment_retry_example,
-		doc: "/guides/checkout-flow",
-		templateFile: "src/routes/checkout.return.tsx"
+		doc: "/guides/checkout-flow"
 	}),
 	defineRule({
 		id: "checkout-origin",
@@ -11198,8 +11423,7 @@ const RULES = [
 		why: mcp_rule_checkout_origin_why,
 		fix: mcp_rule_checkout_origin_fix,
 		example: "const returnUrl = new URL(PAYMENT_RETURN_PATH, new URL(getRequestUrl()).origin);\nawait api.checkout.startPayment(checkoutId, { option, returnUrl: returnUrl.toString() });",
-		doc: "/guides/payment-settings",
-		templateFile: "src/routes/checkout.index.tsx"
+		doc: "/guides/payment-settings"
 	}),
 	defineRule({
 		id: "delivery-quote-preview",
@@ -11207,11 +11431,11 @@ const RULES = [
 		why: mcp_rule_delivery_quote_preview_why,
 		fix: mcp_rule_delivery_quote_preview_fix,
 		example: mcp_rule_delivery_quote_preview_example,
-		doc: "/guides/shipping-fees",
-		templateFile: "src/routes/checkout.index.tsx"
+		doc: "/guides/shipping-fees"
 	}),
 	defineRule({
 		id: "buyer-token-cookie",
+		severity: "error",
 		title: mcp_rule_buyer_token_cookie_title,
 		why: mcp_rule_buyer_token_cookie_why,
 		fix: mcp_rule_buyer_token_cookie_fix,
@@ -11225,8 +11449,7 @@ const RULES = [
 		why: mcp_rule_buyer_session_refresh_why,
 		fix: mcp_rule_buyer_session_refresh_fix,
 		example: mcp_rule_buyer_session_refresh_example,
-		doc: "/guides/storefront-auth",
-		templateFile: "src/lib/session.server.ts"
+		doc: "/guides/storefront-auth"
 	}),
 	defineRule({
 		id: "buyer-reconsent",
@@ -11234,8 +11457,7 @@ const RULES = [
 		why: mcp_rule_buyer_reconsent_why,
 		fix: mcp_rule_buyer_reconsent_fix,
 		example: mcp_rule_buyer_reconsent_example,
-		doc: "/guides/storefront-auth",
-		templateFile: "src/routes/account.tsx"
+		doc: "/guides/storefront-auth"
 	}),
 	defineRule({
 		id: "buyer-signup",
@@ -11243,8 +11465,7 @@ const RULES = [
 		why: mcp_rule_buyer_signup_why,
 		fix: mcp_rule_buyer_signup_fix,
 		example: mcp_rule_buyer_signup_example,
-		doc: "/guides/storefront-auth",
-		templateFile: "src/routes/signup.tsx"
+		doc: "/guides/storefront-auth"
 	}),
 	defineRule({
 		id: "buyer-signout",
@@ -11252,8 +11473,7 @@ const RULES = [
 		why: mcp_rule_buyer_signout_why,
 		fix: mcp_rule_buyer_signout_fix,
 		example: "const logout = createServerFn({ method: \"POST\" }).handler(async () => {\n  const accessToken = readToken();\n  if (accessToken) await authFor().signOut(accessToken).catch(() => undefined);\n  clearSessionCookie();\n});",
-		doc: "/guides/storefront-auth",
-		templateFile: "src/routes/account.tsx"
+		doc: "/guides/storefront-auth"
 	}),
 	defineRule({
 		id: "analytics-start",
@@ -11275,12 +11495,12 @@ const RULES = [
 	}),
 	defineRule({
 		id: "custom-input-private",
+		severity: "error",
 		title: mcp_rule_custom_input_private_title,
 		why: mcp_rule_custom_input_private_why,
 		fix: mcp_rule_custom_input_private_fix,
 		example: mcp_rule_custom_input_private_example,
-		doc: "/guides/product-options",
-		templateFile: "src/lib/direct-checkout.server.ts"
+		doc: "/guides/product-options"
 	}),
 	defineRule({
 		id: "checkout-availability",
@@ -11288,9 +11508,7 @@ const RULES = [
 		why: mcp_rule_checkout_availability_why,
 		fix: mcp_rule_checkout_availability_fix,
 		example: mcp_rule_checkout_availability_example,
-		doc: "/guides/storefront-sdk",
-		templateFile: "src/lib/ordering.ts",
-		severity: "warning"
+		doc: "/guides/storefront-sdk"
 	}),
 	defineRule({
 		id: "product-link",
@@ -11298,9 +11516,7 @@ const RULES = [
 		why: mcp_rule_product_link_why,
 		fix: mcp_rule_product_link_fix,
 		example: mcp_rule_product_link_example,
-		doc: "/guides/order-numbers",
-		templateFile: "src/lib/product-path.ts",
-		severity: "warning"
+		doc: "/guides/order-numbers"
 	}),
 	defineRule({
 		id: "server-only-import",
@@ -11368,7 +11584,7 @@ function verifySources(files, options = {}) {
 			detail
 		});
 	};
-	/** 프로젝트 전체를 보고 판정한 위반 — 고칠 자리는 규칙의 `templateFile`이 알려 준다 */
+	/** 프로젝트 전체를 보고 판정한 위반 — 고칠 방법은 규칙의 `fix`, 시작 코드에 있는 자리는 `templateFile`이 알려 준다 */
 	const inProject = (ruleId, detail) => {
 		findings.push({
 			ruleId,
@@ -12095,6 +12311,8 @@ function runLocalChecks(tree) {
 	const report$1 = verifyTree(map);
 	const blockingRules = report$1.results.filter((result) => result.status === "violation" && result.severity !== "warning");
 	const problems = [...limitProblems(tree)];
+	const project = parseProjectConfig(projectConfigOf(map));
+	if (!project.ok) problems.push(project.error);
 	const warnings = [];
 	const text = (path) => {
 		const bytes = map.get(path);
@@ -12201,8 +12419,20 @@ function withGuideSkill(files) {
 const OUTPUT_TAIL_LINES = 40;
 /** 모아 두는 출력 상한(문자) — 긴 빌드 로그를 다 쥐고 있지 않는다 */
 const OUTPUT_KEEP_CHARS = 64 * 1024;
-/** 빌드를 돌릴 수 있는 폴더인가 — `build` 스크립트와 설치된 의존성(`node_modules`)이 있어야 한다 */
+/**
+* 빌드를 돌릴 수 있는 폴더인가 — 서버 빌드와 같은 순서로 명령을 고른다(`sayren.json` buildCommand → `build` 스크립트).
+* `package.json`이 있으면 설치된 의존성(`node_modules`)이 있어야 한다
+*/
 function planLocalBuild(dir) {
+	const hasManifest = existsSync(join(dir, "package.json"));
+	const command = buildCommandOf(dir);
+	if (command !== null) {
+		if (hasManifest && !existsSync(join(dir, "node_modules"))) return { kind: "no-deps" };
+		return {
+			kind: "run",
+			command
+		};
+	}
 	let scripts;
 	try {
 		scripts = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).scripts;
@@ -12212,16 +12442,33 @@ function planLocalBuild(dir) {
 	const build = scripts && typeof scripts === "object" ? scripts.build : void 0;
 	if (typeof build !== "string" || !build.trim()) return { kind: "no-script" };
 	if (!existsSync(join(dir, "node_modules"))) return { kind: "no-deps" };
-	return { kind: "run" };
+	return {
+		kind: "run",
+		command: null
+	};
 }
-/** `npm run build`를 돌린다. 출력은 모아 두고(실패할 때 꼬리를 보여 준다) 화면에 흘리지 않는다 */
-function runNpmBuild(dir, env) {
+/** `sayren.json`의 buildCommand. 파일이 없거나 형식이 틀리면 null(형식 오류는 로컬 검사가 먼저 막는다) */
+function buildCommandOf(dir) {
+	let content;
+	try {
+		content = readFileSync(join(dir, PROJECT_CONFIG_FILE), "utf8");
+	} catch {
+		return null;
+	}
+	const parsed = parseProjectConfig(content);
+	return parsed.ok ? parsed.config.buildCommand : null;
+}
+/**
+* 빌드를 돌린다 — `command`가 없으면 `npm run build`, 있으면 그 명령을 셸로(셀러가 자기 컴퓨터에서 적은 명령이다, `node_modules/.bin`을 PATH에 얹는다).
+* 출력은 모아 두고(실패할 때 꼬리를 보여 준다) 화면에 흘리지 않는다
+*/
+function runNpmBuild(dir, env, command = null) {
 	return new Promise((resolve$1, reject) => {
 		let output = "";
 		const keep = (chunk) => {
 			output = (output + chunk.toString("utf8")).slice(-OUTPUT_KEEP_CHARS);
 		};
-		const child = spawn("npm", ["run", "build"], {
+		const child = command === null ? spawn("npm", ["run", "build"], {
 			cwd: dir,
 			env,
 			stdio: [
@@ -12230,6 +12477,18 @@ function runNpmBuild(dir, env) {
 				"pipe"
 			],
 			shell: process.platform === "win32"
+		}) : spawn(command, {
+			cwd: dir,
+			env: {
+				...env,
+				PATH: [join(dir, "node_modules", ".bin"), env.PATH].filter(Boolean).join(delimiter)
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			shell: true
 		});
 		child.stdout?.on("data", keep);
 		child.stderr?.on("data", keep);
@@ -12602,14 +12861,96 @@ async function envPull(flags, io) {
 		store: state.storeId
 	}, dir, state, io);
 	const storeCode = await storeCodeOf(client, state.storeId);
+	const lines = (await client.storefront.listVars().then((r) => r.vars.filter((v) => !v.secret)).catch((error) => {
+		if (error instanceof ApiError && (error.status === 403 || error.status === 404)) return [];
+		throw error;
+	})).map((v) => ({
+		key: v.key,
+		line: dotenvValue(v.value ?? "")
+	}));
+	const skipped = lines.filter((l) => l.line === null).map((l) => l.key);
 	writeStoreEnv(dir, auth.apiOrigin, storeCode);
+	updateEnvFile(dir, Object.fromEntries(lines.filter((l) => l.line !== null).map((l) => [l.key, l.line])));
 	ensureGitignore(dir);
 	io.out(cli_env_pulled({
 		file: ENV_FILE,
 		storeCode
 	}));
+	if (lines.length > skipped.length) io.out(cli_env_pulled_vars({
+		file: ENV_FILE,
+		count: lines.length - skipped.length
+	}));
+	if (skipped.length > 0) io.err(cli_env_pull_skipped({ keys: skipped.join(", ") }));
+	return 0;
+}
+/**
+* `.env` 한 줄의 값(dotenv + Vite `loadEnv`의 dotenv-expand 규칙) — `$`는 `\$`로 막아 확장되지 않게 한다. 안전한 문자만이면 그대로,
+* 작은따옴표·줄바꿈이 없으면 작은따옴표(안의 문자를 그대로 읽는다), 줄바꿈만 있고 큰따옴표가 없으면 큰따옴표(`\n`). 작은따옴표와 줄바꿈이
+* 같이 있거나 큰따옴표와 줄바꿈이 같이 있으면 같은 값으로 읽히게 쓸 수 없어 null이다(쓰지 않고 알린다)
+*/
+function dotenvValue(value) {
+	const escaped = value.replaceAll("$", "\\$");
+	if (/^[A-Za-z0-9_./:@+,=-]*$/.test(value)) return value;
+	if (!value.includes("'") && !/[\r\n]/.test(value)) return `'${escaped}'`;
+	if (!value.includes("\"") && !value.includes("\\")) return `"${escaped.replace(/\r?\n/g, "\\n")}"`;
+	return null;
+}
+/** 연결된 폴더의 관리 API 클라이언트 — 셀러 env 명령(`env ls·add·rm`) */
+async function linkedClient(flags, io) {
+	const dir = resolve(io.cwd, flags.dir ?? ".");
+	migrateLegacy(dir, io.out);
+	const state = readState(dir);
+	if (!state) throw new CliError(cli_env_not_linked({ file: STATE_FILE }));
+	return (await apiFor({
+		...flags,
+		store: state.storeId
+	}, dir, state, io)).client;
+}
+/** `sayren env ls` — 셀러 env 목록(비밀 값은 값 없이) */
+async function envList(flags, io) {
+	const { vars } = await (await linkedClient(flags, io)).storefront.listVars();
+	if (vars.length === 0) {
+		io.out(cli_env_empty());
+		return 0;
+	}
+	for (const v of vars) io.out(`${v.key}=${v.secret ? cli_env_secret_mask() : v.value ?? ""}`);
 	return 0;
 }
+/** `sayren env add <키> <값> [--secret]` — 넣거나 바꾼다. 에이전트 토큰이면 승인 대기다 */
+async function envAdd(flags, io) {
+	if (!flags.key || flags.value === void 0) throw new CliError(cli_env_usage());
+	const client = await linkedClient(flags, io);
+	try {
+		await client.storefront.putVar(flags.key, {
+			value: flags.value,
+			secret: flags.secret === true
+		});
+	} catch (error) {
+		if (error instanceof ApprovalPendingError) return envApprovalPending(error, io);
+		throw error;
+	}
+	io.out(cli_env_set({ key: flags.key }));
+	return 0;
+}
+/** `sayren env rm <키>` */
+async function envRemove(flags, io) {
+	if (!flags.key) throw new CliError(cli_env_usage());
+	const client = await linkedClient(flags, io);
+	try {
+		await client.storefront.deleteVar(flags.key);
+	} catch (error) {
+		if (error instanceof ApprovalPendingError) return envApprovalPending(error, io);
+		throw error;
+	}
+	io.out(cli_env_removed({ key: flags.key }));
+	return 0;
+}
+function envApprovalPending(error, io) {
+	io.out(cli_env_approval());
+	if (error.approval.approvalUrl) io.out(cli_approval_url({ url: error.approval.approvalUrl }));
+	else io.out(cli_approval_id({ id: error.approvalId }));
+	return EXIT_APPROVAL_PENDING;
+}
 async function verify(flags, io) {
 	const dir = resolve(io.cwd, flags.dir ?? ".");
 	const tree = collectTree(dir);
@@ -12775,7 +13116,7 @@ async function localBuild(dir, skip, io) {
 	const started = io.now?.() ?? Date.now();
 	let result;
 	try {
-		result = await (io.runBuild ?? ((at) => runNpmBuild(at, io.env)))(dir);
+		result = await (io.runBuild ?? ((at, command) => runNpmBuild(at, io.env, command)))(dir, plan.command);
 	} catch (error) {
 		throw new CliError(cli_deploy_build_local_spawn_failed({ message: error instanceof Error ? error.message : String(error) }));
 	}
@@ -13471,12 +13812,24 @@ async function main(argv, io) {
 			template: str(parsed.flags.template)
 		}, io);
 		case "link": return link(common, io);
-		case "env":
-			if (parsed.positional[0] !== "pull") throw new CliError(cli_env_usage());
-			return envPull({
+		case "env": switch (parsed.positional[0]) {
+			case "pull": return envPull({
 				...common,
 				dir: str(parsed.flags.dir) ?? parsed.positional[1]
 			}, io);
+			case "ls": return envList(common, io);
+			case "add": return envAdd({
+				...common,
+				key: parsed.positional[1],
+				value: parsed.positional[2],
+				secret: parsed.flags.secret === true
+			}, io);
+			case "rm": return envRemove({
+				...common,
+				key: parsed.positional[1]
+			}, io);
+			default: throw new CliError(cli_env_usage());
+		}
 		case "init": return init();
 		case "pull": return pull({
 			...common,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sayren",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "type": "module",
   "imports": {
     "#paraglide/*": "./src/paraglide/*"
@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "esbuild": "^0.28.2",
-    "@sayren/store-sdk": "^0.58.0"
+    "@sayren/store-sdk": "^0.59.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",
@@ -28,8 +28,8 @@
     "tsx": "^4.20.3",
     "typescript": "^6.0.3",
     "vitest": "^5.0.1",
-    "@sayren/mcp": "0.30.0",
-    "@sayren/app": "0.9.0"
+    "@sayren/app": "0.9.0",
+    "@sayren/mcp": "0.31.0"
   },
   "publishConfig": {
     "access": "public"