@ait-co/console-cli 0.1.14 → 0.1.16

package/dist/cli.mjs

@@ -3,6 +3,7 @@ import { defineCommand, runMain } from "citty";
 import { access, chmod, mkdir, mkdtemp, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve, win32 } from "node:path";
 import { homedir, tmpdir } from "node:os";
+import { unzipSync } from "fflate";
 import { parse } from "yaml";
 import { imageSize } from "image-size";
 import { spawn } from "node:child_process";
@@ -516,6 +517,138 @@ async function fetchDeployedBundle(workspaceId, miniAppId, cookies, opts = {}) {
 	if (typeof raw !== "object" || Array.isArray(raw)) throw new Error(`Unexpected deployed-bundle shape for app=${miniAppId}`);
 	return raw;
 }
+async function postDeploymentsInitialize(workspaceId, miniAppId, deploymentId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		method: "POST",
+		url: `${BASE$4}/workspaces/${workspaceId}/mini-app/${miniAppId}/deployments/initialize`,
+		body: { deploymentId },
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`Unexpected deployments/initialize shape for app=${miniAppId}`);
+	const data = raw;
+	const uploadUrl = data.uploadUrl;
+	if (typeof uploadUrl !== "string") throw new Error(`Unexpected deployments/initialize shape for app=${miniAppId}: missing uploadUrl`);
+	const deployment = data.deployment && typeof data.deployment === "object" ? data.deployment : {};
+	return {
+		uploadUrl,
+		deployment,
+		reviewStatus: typeof deployment.reviewStatus === "string" ? deployment.reviewStatus : "UNKNOWN"
+	};
+}
+async function postDeploymentsComplete(workspaceId, miniAppId, deploymentId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		method: "POST",
+		url: `${BASE$4}/workspaces/${workspaceId}/mini-app/${miniAppId}/deployments/complete`,
+		body: { deploymentId },
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+	return raw;
+}
+async function postBundleMemo(workspaceId, miniAppId, deploymentId, memo, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		method: "POST",
+		url: `${BASE$4}/workspaces/${workspaceId}/mini-app/${miniAppId}/bundles/memos`,
+		body: {
+			deploymentId,
+			memo
+		},
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+	return raw;
+}
+/**
+* PUT the raw .ait bytes to the S3 presigned URL returned by
+* `postDeploymentsInitialize`. This is a direct-to-S3 call with NO Toss
+* envelope — the response is empty on success (HTTP 200). Any cookies are
+* intentionally NOT sent because S3 would reject the signed request if
+* extra auth headers contradict the signature.
+*/
+async function putBundleToUploadUrl(uploadUrl, body, opts = {}) {
+	const impl = opts.fetchImpl ?? ((i, init) => fetch(i, init));
+	const view = new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+	let res;
+	try {
+		res = await impl(uploadUrl, {
+			method: "PUT",
+			headers: { "Content-Type": "application/zip" },
+			body: view
+		});
+	} catch (err) {
+		throw new Error(`PUT to upload URL failed: ${err.message}`);
+	}
+	if (!res.ok) {
+		const preview = await res.text().catch(() => "");
+		throw new Error(`PUT to upload URL returned HTTP ${res.status}: ${preview.slice(0, 200)}`);
+	}
+}
+async function postBundleReview(params, cookies, opts = {}) {
+	const url = `${BASE$4}/workspaces/${params.workspaceId}/mini-app/${params.miniAppId}/bundles/reviews`;
+	const body = {
+		deploymentId: params.deploymentId,
+		releaseNotes: params.releaseNotes
+	};
+	if (params.featureList !== void 0) body.featureList = params.featureList;
+	if (params.screenshotImagePaths !== void 0) body.screenshotImagePaths = params.screenshotImagePaths;
+	const raw = await requestConsoleApi({
+		method: "POST",
+		url,
+		body,
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+	return raw;
+}
+async function postBundleReviewWithdrawal(workspaceId, miniAppId, deploymentId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		method: "POST",
+		url: `${BASE$4}/workspaces/${workspaceId}/mini-app/${miniAppId}/bundles/reviews/withdrawal`,
+		body: { deploymentId },
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+	return raw;
+}
+async function postBundleRelease(params, cookies, opts = {}) {
+	const url = `${BASE$4}/workspaces/${params.workspaceId}/mini-app/${params.miniAppId}/bundles/release`;
+	const body = { deploymentId: params.deploymentId };
+	if (params.contentImages !== void 0) body.contentImages = params.contentImages;
+	const raw = await requestConsoleApi({
+		method: "POST",
+		url,
+		body,
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+	return raw;
+}
+async function postBundleTestPush(workspaceId, miniAppId, deploymentId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		method: "POST",
+		url: `${BASE$4}/workspaces/${workspaceId}/mini-app/${miniAppId}/bundles/test-push`,
+		body: { deploymentId },
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+	return raw;
+}
+async function fetchBundleTestLinks(workspaceId, miniAppId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		url: `${BASE$4}/workspaces/${workspaceId}/mini-app/${miniAppId}/bundles/test-links`,
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {};
+	return raw;
+}
 async function createMiniApp(workspaceId, payload, cookies, opts = {}) {
 	return normalizeCreateResult(await requestConsoleApi({
 		url: `${BASE$4}/workspaces/${workspaceId}/mini-app/review`,
@@ -873,6 +1006,460 @@ async function requireSession(json) {
 	return session;
 }
 //#endregion
+//#region src/config/ait-bundle.ts
+var AitBundleError = class extends Error {
+	path;
+	reason;
+	constructor(args) {
+		super(args.message);
+		this.name = "AitBundleError";
+		this.path = args.path;
+		this.reason = args.reason;
+	}
+};
+const AIT_MAGIC = new Uint8Array([
+	65,
+	73,
+	84,
+	66,
+	85,
+	78,
+	68,
+	76
+]);
+const ZIP_MAGIC = new Uint8Array([
+	80,
+	75,
+	3,
+	4
+]);
+function startsWith(bytes, prefix) {
+	if (bytes.length < prefix.length) return false;
+	for (let i = 0; i < prefix.length; i++) if (bytes[i] !== prefix[i]) return false;
+	return true;
+}
+function detectBundleFormat(bytes) {
+	if (startsWith(bytes, AIT_MAGIC)) return "ait";
+	if (startsWith(bytes, ZIP_MAGIC)) return "zip";
+	return "unknown";
+}
+/**
+* Read the `.ait` at `path` and pull out `deploymentId`, auto-detecting
+* whether the file is the modern AIT header format or a legacy plain
+* zip. Returns the raw bytes so the caller can forward them to S3
+* without re-reading the file.
+*/
+async function readAitBundle(path) {
+	let buf;
+	try {
+		buf = await readFile(path);
+	} catch (err) {
+		throw new AitBundleError({
+			path,
+			reason: "file-unreadable",
+			message: err.message
+		});
+	}
+	const bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+	const { deploymentId, format } = deploymentIdFromBundleBytes(bytes, path);
+	return {
+		deploymentId,
+		bytes,
+		format
+	};
+}
+/**
+* Pure helper split out so tests can feed raw bytes without a tmp file.
+* Throws `AitBundleError` on any parse failure. Returns the detected
+* format so callers that want to log it can.
+*/
+function deploymentIdFromBundleBytes(bytes, pathForError) {
+	const format = detectBundleFormat(bytes);
+	if (format === "ait") return {
+		deploymentId: deploymentIdFromAitHeader(bytes, pathForError),
+		format
+	};
+	if (format === "zip") return {
+		deploymentId: deploymentIdFromLegacyZip(bytes, pathForError),
+		format
+	};
+	throw new AitBundleError({
+		path: pathForError,
+		reason: "unrecognized-format",
+		message: "bundle does not start with AITBUNDL or PK magic bytes — not a valid .ait or legacy zip bundle"
+	});
+}
+const AIT_MAGIC_SIZE = 8;
+const AIT_VERSION_SIZE = 4;
+const AIT_HEADER_SIZE = AIT_MAGIC_SIZE + AIT_VERSION_SIZE + 8;
+function deploymentIdFromAitHeader(bytes, pathForError) {
+	if (bytes.length < AIT_HEADER_SIZE) throw new AitBundleError({
+		path: pathForError,
+		reason: "invalid-ait",
+		message: "buffer too small to be a valid AIT file"
+	});
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const bundleLen = Number(view.getBigUint64(AIT_MAGIC_SIZE + AIT_VERSION_SIZE, false));
+	if (!Number.isFinite(bundleLen) || bundleLen <= 0) throw new AitBundleError({
+		path: pathForError,
+		reason: "invalid-ait",
+		message: `AIT bundle length is invalid (${bundleLen})`
+	});
+	const bundleStart = AIT_HEADER_SIZE;
+	const bundleEnd = bundleStart + bundleLen;
+	if (bytes.length < bundleEnd) throw new AitBundleError({
+		path: pathForError,
+		reason: "invalid-ait",
+		message: "unexpected end of buffer reading AIT bundle protobuf"
+	});
+	const deploymentId = readProtobufStringFields(bytes.subarray(bundleStart, bundleEnd), [2, 3]).get(2);
+	if (typeof deploymentId !== "string" || deploymentId === "") throw new AitBundleError({
+		path: pathForError,
+		reason: "missing-deployment-id",
+		message: "AIT bundle protobuf is missing deploymentId (field 2)"
+	});
+	return deploymentId;
+}
+function readProtobufStringFields(bytes, wantedFieldNumbers) {
+	const wanted = new Set(wantedFieldNumbers);
+	const out = /* @__PURE__ */ new Map();
+	const decoder = new TextDecoder("utf-8", { fatal: false });
+	let offset = 0;
+	while (offset < bytes.length) {
+		const { value: tag, next } = readVarint(bytes, offset);
+		offset = next;
+		const fieldNumber = Number(tag >> 3n);
+		const wireType = Number(tag & 7n);
+		if (wireType === 0) offset = readVarint(bytes, offset).next;
+		else if (wireType === 1) offset += 8;
+		else if (wireType === 2) {
+			const { value: len, next: afterLen } = readVarint(bytes, offset);
+			offset = afterLen;
+			const payloadEnd = offset + Number(len);
+			if (payloadEnd > bytes.length) break;
+			if (wanted.has(fieldNumber)) out.set(fieldNumber, decoder.decode(bytes.subarray(offset, payloadEnd)));
+			offset = payloadEnd;
+		} else if (wireType === 5) offset += 4;
+		else break;
+	}
+	return out;
+}
+function readVarint(bytes, start) {
+	let value = 0n;
+	let shift = 0n;
+	let i = start;
+	for (let n = 0; n < 10 && i < bytes.length; n++, i++) {
+		const byte = bytes[i];
+		if (byte === void 0) break;
+		value |= BigInt(byte & 127) << shift;
+		if ((byte & 128) === 0) return {
+			value,
+			next: i + 1
+		};
+		shift += 7n;
+	}
+	return {
+		value,
+		next: i
+	};
+}
+function deploymentIdFromLegacyZip(bytes, pathForError) {
+	let entries;
+	try {
+		entries = unzipSync(bytes, { filter: (file) => file.name === "app.json" });
+	} catch (err) {
+		throw new AitBundleError({
+			path: pathForError,
+			reason: "invalid-zip",
+			message: `not a valid zip: ${err.message}`
+		});
+	}
+	const entry = entries["app.json"];
+	if (!entry) throw new AitBundleError({
+		path: pathForError,
+		reason: "missing-app-json",
+		message: "app.json is not present at the root of the bundle"
+	});
+	let parsed;
+	try {
+		parsed = JSON.parse(new TextDecoder().decode(entry));
+	} catch (err) {
+		throw new AitBundleError({
+			path: pathForError,
+			reason: "invalid-app-json",
+			message: `app.json is not valid JSON: ${err.message}`
+		});
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new AitBundleError({
+		path: pathForError,
+		reason: "invalid-app-json",
+		message: "app.json is not a JSON object"
+	});
+	const metadata = parsed._metadata;
+	if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) throw new AitBundleError({
+		path: pathForError,
+		reason: "missing-deployment-id",
+		message: "app.json._metadata is missing; is your build outputting the modern app.json schema?"
+	});
+	const deploymentId = metadata.deploymentId;
+	if (typeof deploymentId !== "string" || deploymentId === "") throw new AitBundleError({
+		path: pathForError,
+		reason: "missing-deployment-id",
+		message: "app.json._metadata.deploymentId is missing or empty; is your build outputting the modern app.json schema?"
+	});
+	return deploymentId;
+}
+//#endregion
+//#region src/commands/app-deploy.ts
+function parseAppIdStrict(raw) {
+	if (raw === "") return null;
+	if (!/^[1-9]\d*$/.test(raw)) return null;
+	const n = Number.parseInt(raw, 10);
+	return Number.isSafeInteger(n) ? n : null;
+}
+async function runDeploy(args, deps = {}) {
+	if (typeof args.app !== "string" || args.app === "") {
+		if (args.json) emitJson({
+			ok: false,
+			reason: "missing-app-id",
+			message: "--app <id> is required"
+		});
+		else process.stderr.write("app deploy: --app <id> is required.\n");
+		return exitAfterFlush(ExitCode.Usage);
+	}
+	const appId = parseAppIdStrict(args.app);
+	if (appId === null) {
+		if (args.json) emitJson({
+			ok: false,
+			reason: "invalid-id",
+			message: `--app must be a positive integer (got ${JSON.stringify(args.app)})`
+		});
+		else process.stderr.write(`app deploy: invalid --app ${JSON.stringify(args.app)}\n`);
+		return exitAfterFlush(ExitCode.Usage);
+	}
+	if (typeof args.path !== "string" || args.path === "") {
+		if (args.json) emitJson({
+			ok: false,
+			reason: "missing-path",
+			message: "path to .ait bundle is required"
+		});
+		else process.stderr.write("app deploy: path to .ait bundle is required.\n");
+		return exitAfterFlush(ExitCode.Usage);
+	}
+	const requestReview = Boolean(args.requestReview);
+	const release = Boolean(args.release);
+	const confirm = Boolean(args.confirm);
+	const releaseNotes = typeof args.releaseNotes === "string" ? args.releaseNotes : void 0;
+	if (requestReview && releaseNotes === void 0) {
+		if (args.json) emitJson({
+			ok: false,
+			reason: "missing-release-notes",
+			message: "--release-notes <text> is required with --request-review"
+		});
+		else process.stderr.write("app deploy: --release-notes <text> is required with --request-review.\n");
+		return exitAfterFlush(ExitCode.Usage);
+	}
+	if (release && !confirm) {
+		if (args.json) emitJson({
+			ok: false,
+			reason: "not-confirmed",
+			message: "--release is destructive; pass --confirm to proceed"
+		});
+		else process.stderr.write("app deploy: --release publishes the bundle to end users.\n  Re-run with --confirm to proceed.\n");
+		return exitAfterFlush(ExitCode.Usage);
+	}
+	const readBundle = deps.readBundleImpl ?? readAitBundle;
+	let bundleInfo;
+	try {
+		bundleInfo = await readBundle(args.path);
+	} catch (err) {
+		if (err instanceof AitBundleError) {
+			const reason = err.reason === "file-unreadable" ? "file-unreadable" : "invalid-bundle";
+			if (args.json) emitJson({
+				ok: false,
+				reason,
+				path: err.path,
+				bundleReason: err.reason,
+				message: err.message
+			});
+			else process.stderr.write(`app deploy: ${err.message}\n`);
+			return exitAfterFlush(ExitCode.Usage);
+		}
+		throw err;
+	}
+	const deploymentId = typeof args.deploymentId === "string" && args.deploymentId !== "" ? args.deploymentId : bundleInfo.deploymentId;
+	if (deploymentId === "") {
+		if (args.json) emitJson({
+			ok: false,
+			reason: "invalid-bundle",
+			path: args.path,
+			message: "deploymentId is empty"
+		});
+		else process.stderr.write("app deploy: deploymentId is empty.\n");
+		return exitAfterFlush(ExitCode.Usage);
+	}
+	const ctx = await resolveWorkspaceContext(args);
+	if (!ctx) return;
+	const { session, workspaceId } = ctx;
+	const memo = typeof args.memo === "string" && args.memo.length > 0 ? args.memo : void 0;
+	const steps = ["upload"];
+	if (requestReview) steps.push("review");
+	if (release) steps.push("release");
+	if (args.dryRun) {
+		if (args.json) emitJson({
+			ok: true,
+			dryRun: true,
+			workspaceId,
+			appId,
+			deploymentId,
+			bundleFormat: bundleInfo.format,
+			bytes: bundleInfo.bytes.byteLength,
+			steps,
+			memo: memo ?? null,
+			releaseNotes: releaseNotes ?? null,
+			confirmed: confirm
+		});
+		else {
+			const stepsLine = steps.map((s) => {
+				if (s === "review") return `review (releaseNotes: ${JSON.stringify(releaseNotes ?? "")})`;
+				if (s === "release") return `release (${confirm ? "confirmed" : "NOT confirmed"})`;
+				return s;
+			}).join(" → ");
+			process.stdout.write(`DRY RUN\n  app           ${appId}\n  workspace     ${workspaceId}\n  bundle        ${args.path} (${bundleInfo.bytes.byteLength} bytes)\n  deploymentId  ${deploymentId}\n  memo          ${memo ?? "(none)"}\n  steps         ${stepsLine}\n`);
+		}
+		return exitAfterFlush(ExitCode.Ok);
+	}
+	const apiOpts = deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {};
+	let uploaded = false;
+	let bundleRecord = null;
+	let reviewed = false;
+	let reviewResult = null;
+	try {
+		const init = await postDeploymentsInitialize(workspaceId, appId, deploymentId, session.cookies, apiOpts);
+		if (init.reviewStatus !== "PREPARE") {
+			if (args.json) emitJson({
+				ok: false,
+				reason: "bundle-not-prepare",
+				workspaceId,
+				appId,
+				deploymentId,
+				reviewStatus: init.reviewStatus,
+				message: "이미 존재하는 버전이에요."
+			});
+			else process.stderr.write(`app deploy: deployment ${deploymentId} is already in state ${init.reviewStatus}; upload refused.\n`);
+			return exitAfterFlush(ExitCode.Usage);
+		}
+		await putBundleToUploadUrl(init.uploadUrl, bundleInfo.bytes, apiOpts);
+		bundleRecord = await postDeploymentsComplete(workspaceId, appId, deploymentId, session.cookies, apiOpts);
+		if (memo !== void 0) await postBundleMemo(workspaceId, appId, deploymentId, memo, session.cookies, apiOpts);
+		uploaded = true;
+	} catch (err) {
+		return emitFailureFromError(args.json, err);
+	}
+	if (requestReview) try {
+		reviewResult = await postBundleReview({
+			workspaceId,
+			miniAppId: appId,
+			deploymentId,
+			releaseNotes: releaseNotes ?? ""
+		}, session.cookies, apiOpts);
+		reviewed = true;
+	} catch (err) {
+		return emitPartialFailure(args.json, err, {
+			workspaceId,
+			appId,
+			deploymentId,
+			uploaded: true,
+			reviewed: false,
+			released: false
+		});
+	}
+	let releaseResult = null;
+	if (release) try {
+		releaseResult = await postBundleRelease({
+			workspaceId,
+			miniAppId: appId,
+			deploymentId
+		}, session.cookies, apiOpts);
+	} catch (err) {
+		return emitPartialFailure(args.json, err, {
+			workspaceId,
+			appId,
+			deploymentId,
+			uploaded: true,
+			reviewed,
+			released: false
+		});
+	}
+	if (args.json) {
+		emitJson({
+			ok: true,
+			workspaceId,
+			appId,
+			deploymentId,
+			bundleFormat: bundleInfo.format,
+			uploaded,
+			reviewed,
+			released: release,
+			bundle: bundleRecord,
+			reviewResult,
+			releaseResult
+		});
+		return exitAfterFlush(ExitCode.Ok);
+	}
+	process.stdout.write(`Deployed bundle for app ${appId} (ws ${workspaceId})\n  deploymentId ${deploymentId}\n  bytes        ${bundleInfo.bytes.byteLength}\n  steps        ${steps.join(" → ")}\n`);
+	return exitAfterFlush(ExitCode.Ok);
+}
+/**
+* Partial-failure emitter. The upload succeeded (so the user does NOT
+* need to re-upload on retry) but a downstream step failed. Keeping the
+* `uploaded: true` bit in the JSON lets agent-plugin skip to the
+* specific failing step on retry instead of re-running the whole
+* pipeline.
+*/
+async function emitPartialFailure(json, err, progress) {
+	if (err instanceof TossApiError && err.isAuthError) {
+		if (json) emitJson({
+			ok: true,
+			authenticated: false,
+			reason: "session-expired",
+			...progress
+		});
+		else process.stderr.write("Session is no longer valid. Run `aitcc login` again.\n");
+		return exitAfterFlush(ExitCode.NotAuthenticated);
+	}
+	if (err instanceof TossApiError) {
+		if (json) emitJson({
+			ok: false,
+			reason: "api-error",
+			status: err.status,
+			...err.errorCode !== void 0 ? { errorCode: err.errorCode } : {},
+			message: err.message,
+			...progress
+		});
+		else process.stderr.write(`Unexpected error: ${err.message}\n`);
+		return exitAfterFlush(ExitCode.ApiError);
+	}
+	if (err instanceof NetworkError) {
+		if (json) emitJson({
+			ok: false,
+			reason: "network-error",
+			message: err.message,
+			...progress
+		});
+		else process.stderr.write(`Network error reaching the console API: ${err.message}.\n`);
+		return exitAfterFlush(ExitCode.NetworkError);
+	}
+	if (json) emitJson({
+		ok: false,
+		reason: "api-error",
+		message: err.message,
+		...progress
+	});
+	else process.stderr.write(`Unexpected error: ${err.message}\n`);
+	return exitAfterFlush(ExitCode.ApiError);
+}
+//#endregion
 //#region src/config/app-manifest.ts
 var ManifestError = class extends Error {
 	kind;
@@ -1945,7 +2532,7 @@ const reportsCommand = defineCommand({
 const bundlesCommand = defineCommand({
 	meta: {
 		name: "bundles",
-		description: "Inspect upload bundles for a mini-app."
+		description: "Inspect and manage upload bundles for a mini-app."
 	},
 	subCommands: {
 		ls: defineCommand({
@@ -2123,44 +2710,502 @@ const bundlesCommand = defineCommand({
 					return emitFailureFromError(args.json, err);
 				}
 			}
-		})
-	}
-});
-const certsCommand = defineCommand({
-	meta: {
-		name: "certs",
-		description: "Inspect mTLS certificates for a mini-app."
-	},
-	subCommands: { ls: defineCommand({
-		meta: {
-			name: "ls",
-			description: "List mTLS certificates issued for a mini-app."
-		},
-		args: {
-			id: {
-				type: "positional",
-				description: "Mini-app ID.",
-				required: true
-			},
-			workspace: {
-				type: "string",
-				description: "Workspace ID. Defaults to the selected workspace."
+		}),
+		upload: defineCommand({
+			meta: {
+				name: "upload",
+				description: "Upload an .ait bundle (initialize → PUT → complete [+ memo])."
 			},
-			json: {
-				type: "boolean",
-				description: "Emit machine-readable JSON.",
-				default: false
-			}
-		},
-		async run({ args }) {
-			const appId = parseAppId(args.id);
-			if (appId === null) {
-				if (args.json) emitJson({
-					ok: false,
-					reason: "invalid-id",
-					message: `app id must be a positive integer (got ${JSON.stringify(args.id)})`
-				});
-				else process.stderr.write(`app certs ls: invalid id ${JSON.stringify(args.id)}\n`);
+			args: {
+				id: {
+					type: "positional",
+					description: "Mini-app ID.",
+					required: true
+				},
+				path: {
+					type: "positional",
+					description: "Path to the .ait bundle file.",
+					required: true
+				},
+				"deployment-id": {
+					type: "string",
+					description: "deploymentId embedded in the bundle (from app.json._metadata.deploymentId)."
+				},
+				memo: {
+					type: "string",
+					description: "Optional memo attached to this bundle version."
+				},
+				workspace: {
+					type: "string",
+					description: "Workspace ID. Defaults to the selected workspace."
+				},
+				"dry-run": {
+					type: "boolean",
+					description: "Validate inputs and show what would be sent, without touching the server.",
+					default: false
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON.",
+					default: false
+				}
+			},
+			async run({ args }) {
+				const appId = parseAppId(args.id);
+				if (appId === null) {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "invalid-id",
+						message: `app id must be a positive integer (got ${JSON.stringify(args.id)})`
+					});
+					else process.stderr.write(`app bundles upload: invalid id ${JSON.stringify(args.id)}\n`);
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const deploymentId = typeof args["deployment-id"] === "string" ? args["deployment-id"] : "";
+				if (deploymentId === "") {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "missing-deployment-id",
+						message: "--deployment-id is required; read app.json._metadata.deploymentId from inside the .ait"
+					});
+					else process.stderr.write("app bundles upload: --deployment-id <uuid> is required.\n  The .ait bundle is a zip; read app.json inside and copy _metadata.deploymentId.\n");
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const filePath = typeof args.path === "string" ? args.path : "";
+				let bytes;
+				try {
+					const { readFile } = await import("node:fs/promises");
+					const buf = await readFile(filePath);
+					bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					if (args.json) emitJson({
+						ok: false,
+						reason: "file-unreadable",
+						path: filePath,
+						message
+					});
+					else process.stderr.write(`app bundles upload: cannot read ${filePath}: ${message}\n`);
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const ctx = await resolveWorkspaceContext(args);
+				if (!ctx) return;
+				const { session, workspaceId } = ctx;
+				const memo = typeof args.memo === "string" && args.memo.length > 0 ? args.memo : void 0;
+				if (args["dry-run"]) {
+					if (args.json) emitJson({
+						ok: true,
+						dryRun: true,
+						workspaceId,
+						appId,
+						deploymentId,
+						bytes: bytes.byteLength,
+						memo: memo ?? null
+					});
+					else process.stdout.write(`DRY RUN\n  workspace    ${workspaceId}\n  appId        ${appId}\n  deploymentId ${deploymentId}\n  bytes        ${bytes.byteLength}\n  memo         ${memo ?? "(none)"}\n`);
+					return exitAfterFlush(ExitCode.Ok);
+				}
+				try {
+					const init = await postDeploymentsInitialize(workspaceId, appId, deploymentId, session.cookies);
+					if (init.reviewStatus !== "PREPARE") {
+						if (args.json) emitJson({
+							ok: false,
+							reason: "bundle-not-prepare",
+							workspaceId,
+							appId,
+							deploymentId,
+							reviewStatus: init.reviewStatus,
+							message: "이미 존재하는 버전이에요."
+						});
+						else process.stderr.write(`app bundles upload: deployment ${deploymentId} is already in state ${init.reviewStatus}; bundle upload refused.\n`);
+						return exitAfterFlush(ExitCode.Usage);
+					}
+					await putBundleToUploadUrl(init.uploadUrl, bytes);
+					const bundle = await postDeploymentsComplete(workspaceId, appId, deploymentId, session.cookies);
+					let memoApplied = false;
+					if (memo !== void 0) {
+						await postBundleMemo(workspaceId, appId, deploymentId, memo, session.cookies);
+						memoApplied = true;
+					}
+					if (args.json) {
+						emitJson({
+							ok: true,
+							workspaceId,
+							appId,
+							deploymentId,
+							reviewStatus: init.reviewStatus,
+							bundle,
+							memoApplied
+						});
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					process.stdout.write(`Uploaded bundle for app ${appId} (ws ${workspaceId})\n  deploymentId ${deploymentId}\n  bytes        ${bytes.byteLength}\n  memo         ${memoApplied ? "applied" : "(none)"}\n`);
+					return exitAfterFlush(ExitCode.Ok);
+				} catch (err) {
+					return emitFailureFromError(args.json, err);
+				}
+			}
+		}),
+		review: defineCommand({
+			meta: {
+				name: "review",
+				description: "Submit (or withdraw) an uploaded bundle for review."
+			},
+			args: {
+				id: {
+					type: "positional",
+					description: "Mini-app ID.",
+					required: true
+				},
+				"deployment-id": {
+					type: "string",
+					description: "deploymentId of the uploaded bundle."
+				},
+				"release-notes": {
+					type: "string",
+					description: "Release notes shown to the reviewer. Ignored with --withdraw."
+				},
+				withdraw: {
+					type: "boolean",
+					description: "Withdraw the existing review request instead of submitting a new one.",
+					default: false
+				},
+				workspace: {
+					type: "string",
+					description: "Workspace ID. Defaults to the selected workspace."
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON.",
+					default: false
+				}
+			},
+			async run({ args }) {
+				const appId = parseAppId(args.id);
+				if (appId === null) {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "invalid-id",
+						message: `app id must be a positive integer (got ${JSON.stringify(args.id)})`
+					});
+					else process.stderr.write(`app bundles review: invalid id ${JSON.stringify(args.id)}\n`);
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const deploymentId = typeof args["deployment-id"] === "string" ? args["deployment-id"] : "";
+				if (deploymentId === "") {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "missing-deployment-id"
+					});
+					else process.stderr.write("app bundles review: --deployment-id <uuid> is required.\n");
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const withdraw = Boolean(args.withdraw);
+				const releaseNotes = typeof args["release-notes"] === "string" ? args["release-notes"] : void 0;
+				if (!withdraw && releaseNotes === void 0) {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "missing-release-notes"
+					});
+					else process.stderr.write("app bundles review: --release-notes <text> is required to submit for review.\n");
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const ctx = await resolveWorkspaceContext(args);
+				if (!ctx) return;
+				const { session, workspaceId } = ctx;
+				try {
+					if (withdraw) {
+						const result = await postBundleReviewWithdrawal(workspaceId, appId, deploymentId, session.cookies);
+						if (args.json) {
+							emitJson({
+								ok: true,
+								workspaceId,
+								appId,
+								deploymentId,
+								action: "withdraw",
+								result
+							});
+							return exitAfterFlush(ExitCode.Ok);
+						}
+						process.stdout.write(`Withdrew review for bundle ${deploymentId} (app ${appId}, ws ${workspaceId})\n`);
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					const result = await postBundleReview({
+						workspaceId,
+						miniAppId: appId,
+						deploymentId,
+						releaseNotes: releaseNotes ?? ""
+					}, session.cookies);
+					if (args.json) {
+						emitJson({
+							ok: true,
+							workspaceId,
+							appId,
+							deploymentId,
+							action: "submit",
+							result
+						});
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					const versionName = typeof result.versionName === "string" ? result.versionName : "";
+					process.stdout.write(`Submitted bundle ${deploymentId} for review (app ${appId}, ws ${workspaceId})` + (versionName ? ` — version ${versionName}` : "") + "\n");
+					return exitAfterFlush(ExitCode.Ok);
+				} catch (err) {
+					return emitFailureFromError(args.json, err);
+				}
+			}
+		}),
+		release: defineCommand({
+			meta: {
+				name: "release",
+				description: "Release (publish) an APPROVED bundle to end users."
+			},
+			args: {
+				id: {
+					type: "positional",
+					description: "Mini-app ID.",
+					required: true
+				},
+				"deployment-id": {
+					type: "string",
+					description: "deploymentId of the APPROVED bundle to publish."
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required to actually release — without it, the command refuses.",
+					default: false
+				},
+				workspace: {
+					type: "string",
+					description: "Workspace ID. Defaults to the selected workspace."
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON.",
+					default: false
+				}
+			},
+			async run({ args }) {
+				const appId = parseAppId(args.id);
+				if (appId === null) {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "invalid-id",
+						message: `app id must be a positive integer (got ${JSON.stringify(args.id)})`
+					});
+					else process.stderr.write(`app bundles release: invalid id ${JSON.stringify(args.id)}\n`);
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const deploymentId = typeof args["deployment-id"] === "string" ? args["deployment-id"] : "";
+				if (deploymentId === "") {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "missing-deployment-id"
+					});
+					else process.stderr.write("app bundles release: --deployment-id <uuid> is required.\n");
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				if (!args.confirm) {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "not-confirmed",
+						message: "release is destructive; pass --confirm to proceed"
+					});
+					else process.stderr.write("app bundles release: this publishes the bundle to end users.\n  Re-run with --confirm to proceed.\n");
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const ctx = await resolveWorkspaceContext(args);
+				if (!ctx) return;
+				const { session, workspaceId } = ctx;
+				try {
+					const result = await postBundleRelease({
+						workspaceId,
+						miniAppId: appId,
+						deploymentId
+					}, session.cookies);
+					if (args.json) {
+						emitJson({
+							ok: true,
+							workspaceId,
+							appId,
+							deploymentId,
+							result
+						});
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					process.stdout.write(`Released bundle ${deploymentId} for app ${appId} (ws ${workspaceId})\n`);
+					return exitAfterFlush(ExitCode.Ok);
+				} catch (err) {
+					return emitFailureFromError(args.json, err);
+				}
+			}
+		}),
+		"test-push": defineCommand({
+			meta: {
+				name: "test-push",
+				description: "Send a test push so the uploader can open this bundle on their device."
+			},
+			args: {
+				id: {
+					type: "positional",
+					description: "Mini-app ID.",
+					required: true
+				},
+				"deployment-id": {
+					type: "string",
+					description: "deploymentId of the bundle to test."
+				},
+				workspace: {
+					type: "string",
+					description: "Workspace ID. Defaults to the selected workspace."
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON.",
+					default: false
+				}
+			},
+			async run({ args }) {
+				const appId = parseAppId(args.id);
+				if (appId === null) {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "invalid-id",
+						message: `app id must be a positive integer (got ${JSON.stringify(args.id)})`
+					});
+					else process.stderr.write(`app bundles test-push: invalid id ${JSON.stringify(args.id)}\n`);
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const deploymentId = typeof args["deployment-id"] === "string" ? args["deployment-id"] : "";
+				if (deploymentId === "") {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "missing-deployment-id"
+					});
+					else process.stderr.write("app bundles test-push: --deployment-id <uuid> is required.\n");
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const ctx = await resolveWorkspaceContext(args);
+				if (!ctx) return;
+				const { session, workspaceId } = ctx;
+				try {
+					const result = await postBundleTestPush(workspaceId, appId, deploymentId, session.cookies);
+					if (args.json) {
+						emitJson({
+							ok: true,
+							workspaceId,
+							appId,
+							deploymentId,
+							result
+						});
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					process.stdout.write(`Sent test push for bundle ${deploymentId} (app ${appId})\n`);
+					return exitAfterFlush(ExitCode.Ok);
+				} catch (err) {
+					return emitFailureFromError(args.json, err);
+				}
+			}
+		}),
+		"test-links": defineCommand({
+			meta: {
+				name: "test-links",
+				description: "Show per-device test URLs for the mini-app."
+			},
+			args: {
+				id: {
+					type: "positional",
+					description: "Mini-app ID.",
+					required: true
+				},
+				workspace: {
+					type: "string",
+					description: "Workspace ID. Defaults to the selected workspace."
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON.",
+					default: false
+				}
+			},
+			async run({ args }) {
+				const appId = parseAppId(args.id);
+				if (appId === null) {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "invalid-id",
+						message: `app id must be a positive integer (got ${JSON.stringify(args.id)})`
+					});
+					else process.stderr.write(`app bundles test-links: invalid id ${JSON.stringify(args.id)}\n`);
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const ctx = await resolveWorkspaceContext(args);
+				if (!ctx) return;
+				const { session, workspaceId } = ctx;
+				try {
+					const links = await fetchBundleTestLinks(workspaceId, appId, session.cookies);
+					if (args.json) {
+						emitJson({
+							ok: true,
+							workspaceId,
+							appId,
+							links
+						});
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					const keys = Object.keys(links);
+					if (keys.length === 0) {
+						process.stdout.write(`App ${appId} (ws ${workspaceId}): no test links available\n`);
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					process.stdout.write(`App ${appId} (ws ${workspaceId}):\n`);
+					for (const k of keys) {
+						const v = links[k];
+						process.stdout.write(`  ${k}\t${typeof v === "string" ? v : JSON.stringify(v)}\n`);
+					}
+					return exitAfterFlush(ExitCode.Ok);
+				} catch (err) {
+					return emitFailureFromError(args.json, err);
+				}
+			}
+		})
+	}
+});
+const certsCommand = defineCommand({
+	meta: {
+		name: "certs",
+		description: "Inspect mTLS certificates for a mini-app."
+	},
+	subCommands: { ls: defineCommand({
+		meta: {
+			name: "ls",
+			description: "List mTLS certificates issued for a mini-app."
+		},
+		args: {
+			id: {
+				type: "positional",
+				description: "Mini-app ID.",
+				required: true
+			},
+			workspace: {
+				type: "string",
+				description: "Workspace ID. Defaults to the selected workspace."
+			},
+			json: {
+				type: "boolean",
+				description: "Emit machine-readable JSON.",
+				default: false
+			}
+		},
+		async run({ args }) {
+			const appId = parseAppId(args.id);
+			if (appId === null) {
+				if (args.json) emitJson({
+					ok: false,
+					reason: "invalid-id",
+					message: `app id must be a positive integer (got ${JSON.stringify(args.id)})`
+				});
+				else process.stderr.write(`app certs ls: invalid id ${JSON.stringify(args.id)}\n`);
 				return exitAfterFlush(ExitCode.Usage);
 			}
 			const ctx = await resolveWorkspaceContext(args);
@@ -2965,6 +4010,79 @@ const appCommand = defineCommand({
 					...args.config !== void 0 ? { config: args.config } : {}
 				});
 			}
+		}),
+		deploy: defineCommand({
+			meta: {
+				name: "deploy",
+				description: "Upload a bundle, optionally request review, optionally release. Auto-detects deploymentId from the .ait if --deployment-id is omitted."
+			},
+			args: {
+				path: {
+					type: "positional",
+					description: "Path to the .ait bundle file.",
+					required: true
+				},
+				app: {
+					type: "string",
+					description: "Mini-app ID. Required — no top-level \"selected app\" concept yet."
+				},
+				"deployment-id": {
+					type: "string",
+					description: "deploymentId of the bundle. Defaults to app.json._metadata.deploymentId inside the .ait."
+				},
+				memo: {
+					type: "string",
+					description: "Optional memo attached to the uploaded bundle."
+				},
+				"request-review": {
+					type: "boolean",
+					description: "After upload, submit the bundle for review.",
+					default: false
+				},
+				"release-notes": {
+					type: "string",
+					description: "Release notes for the review request. Required with --request-review."
+				},
+				release: {
+					type: "boolean",
+					description: "After review submit, publish the bundle. Requires the bundle to already be APPROVED; typically used on a second `app deploy` run.",
+					default: false
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required with --release — confirms the destructive publish step.",
+					default: false
+				},
+				workspace: {
+					type: "string",
+					description: "Workspace ID. Defaults to the selected workspace."
+				},
+				"dry-run": {
+					type: "boolean",
+					description: "Print the planned pipeline without touching the server.",
+					default: false
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON.",
+					default: false
+				}
+			},
+			async run({ args }) {
+				await runDeploy({
+					path: typeof args.path === "string" ? args.path : "",
+					app: typeof args.app === "string" ? args.app : void 0,
+					json: args.json,
+					dryRun: args["dry-run"],
+					requestReview: args["request-review"],
+					release: args.release,
+					confirm: args.confirm,
+					...args["deployment-id"] !== void 0 ? { deploymentId: args["deployment-id"] } : {},
+					...args.memo !== void 0 ? { memo: args.memo } : {},
+					...args["release-notes"] !== void 0 ? { releaseNotes: args["release-notes"] } : {},
+					...args.workspace !== void 0 ? { workspace: args.workspace } : {}
+				});
+			}
 		})
 	}
 });
@@ -4411,7 +5529,7 @@ function resolveVersion() {
 		if (typeof injected === "string" && injected.length > 0) return injected;
 	} catch {}
 	try {
-		return "0.1.14";
+		return "0.1.16";
 	} catch {}
 	return "0.0.0-dev";
 }