@ait-co/console-cli 0.1.5 → 0.1.6

package/dist/cli.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from "citty";
-import { chmod, mkdir, mkdtemp, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
-import { basename, dirname, join, win32 } from "node:path";
+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 { parse } from "yaml";
+import { imageSize } from "image-size";
 import { spawn } from "node:child_process";
 import { constants } from "node:fs";
 //#region src/api/http.ts
@@ -119,10 +121,25 @@ async function requestConsoleApi(options) {
 		headers["Content-Type"] = "application/json";
 		init.body = JSON.stringify(options.body);
 	}
-	const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+	return executeAndUnwrap(url, init, options.fetchImpl);
+}
+/**
+* Send a pre-built `RequestInit` against the console API and unwrap the
+* Toss envelope. Use this when the caller needs to build the body itself
+* (multipart uploads, binary requests, anything that can't live under
+* `requestConsoleApi`'s JSON-body assumption). Cookie header composition
+* and any additional headers remain the caller's responsibility.
+*
+* Exists so `uploadMiniAppResource` doesn't have to re-implement the
+* text→JSON→envelope→error branch in `requestConsoleApi`; drift between
+* the two paths has bitten us once (cf. the refactor in the
+* `app register` review).
+*/
+async function executeAndUnwrap(url, init, fetchImpl) {
+	const impl = fetchImpl ?? ((input, i) => fetch(input, i));
 	let res;
 	try {
-		res = await fetchImpl(url, init);
+		res = await impl(url, init);
 	} catch (err) {
 		throw new NetworkError(url.toString(), err);
 	}
@@ -187,6 +204,60 @@ async function fetchReviewStatus(workspaceId, cookies, opts = {}) {
 		})
 	};
 }
+async function createMiniApp(workspaceId, payload, cookies, opts = {}) {
+	return normalizeCreateResult(await requestConsoleApi({
+		url: `${BASE$2}/workspaces/${workspaceId}/mini-app/review`,
+		method: "POST",
+		cookies,
+		body: payload,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	}));
+}
+function normalizeCreateResult(raw) {
+	if (raw === null || typeof raw !== "object") return {
+		miniAppId: void 0,
+		reviewState: void 0,
+		extra: {}
+	};
+	const rec = raw;
+	const rawId = rec.miniAppId ?? rec.id ?? rec.appId;
+	const miniAppId = typeof rawId === "string" || typeof rawId === "number" ? rawId : void 0;
+	const rawState = rec.reviewState ?? rec.status;
+	return {
+		miniAppId,
+		reviewState: typeof rawState === "string" ? rawState : void 0,
+		extra: rec
+	};
+}
+/**
+* Upload an image to `/resource/:wid/upload?validWidth=W&validHeight=H`
+* and return the CDN URL the server hands back. The endpoint is a
+* multipart/form-data POST; we build a FormData with a single `resource`
+* field because that matches the bundle analysis for the console's
+* uploader, which pairs a `fileName` string field with a `resource`
+* Blob (see VALIDATION-RULES.md → iconUri). Dog-food #23 may reveal that
+* the field name is actually `file` — if so, swap it in one place here.
+*/
+async function uploadMiniAppResource(params, opts = {}) {
+	const url = new URL(`${BASE$2}/resource/${params.workspaceId}/upload`);
+	url.searchParams.set("validWidth", String(params.validWidth));
+	url.searchParams.set("validHeight", String(params.validHeight));
+	const form = new FormData();
+	const view = new Uint8Array(params.file.buffer.buffer, params.file.buffer.byteOffset, params.file.buffer.byteLength);
+	const blob = new Blob([view], { type: params.file.contentType });
+	form.append("resource", blob, params.file.fileName);
+	form.append("fileName", params.file.fileName);
+	const cookieHeader = cookieHeaderFor(url, params.cookies);
+	const headers = { Accept: "application/json, text/plain, */*" };
+	if (cookieHeader) headers.Cookie = cookieHeader;
+	const imageUrl = await executeAndUnwrap(url, {
+		method: "POST",
+		headers,
+		body: form
+	}, opts.fetchImpl);
+	if (typeof imageUrl !== "string") throw new MalformedResponseError(url.toString(), 200, `expected string imageUrl, got ${typeof imageUrl}`);
+	return imageUrl;
+}
 //#endregion
 //#region src/exit.ts
 const ExitCode = {
@@ -376,14 +447,48 @@ function emitNetworkError(json, message) {
 	});
 	else process.stderr.write(`Network error reaching the console API: ${message}.\n`);
 }
-function emitApiError(json, message) {
+function emitApiError(json, message, details) {
 	if (json) emitJson({
 		ok: false,
 		reason: "api-error",
+		...details?.status !== void 0 ? { status: details.status } : {},
+		...details?.errorCode !== void 0 ? { errorCode: details.errorCode } : {},
 		message
 	});
 	else process.stderr.write(`Unexpected error: ${message}\n`);
 }
+/**
+* Shared auth/network/api dispatch. Every session-scoped command's
+* `catch (err)` block boils down to the same sequence: TossApiError
+* (auth → exit 10, otherwise → exit 17 with status + errorCode),
+* NetworkError (exit 11), fallback (exit 17 with just a message).
+* Exists so we get a single source of truth for the api-error JSON
+* shape — previously each command duplicated the if/else ladder and
+* `register` diverged (it exposed `status`/`errorCode` that the others
+* didn't) until this extraction lined them up.
+*
+* Returns `Promise<void>` but never returns at runtime: every branch
+* awaits `exitAfterFlush` which calls `process.exit`.
+*/
+async function emitFailureFromError(json, err) {
+	if (err instanceof TossApiError && err.isAuthError) {
+		emitNotAuthenticated(json, "session-expired");
+		return exitAfterFlush(ExitCode.NotAuthenticated);
+	}
+	if (err instanceof TossApiError) {
+		emitApiError(json, err.message, {
+			status: err.status,
+			errorCode: err.errorCode
+		});
+		return exitAfterFlush(ExitCode.ApiError);
+	}
+	if (err instanceof NetworkError) {
+		emitNetworkError(json, err.message);
+		return exitAfterFlush(ExitCode.NetworkError);
+	}
+	emitApiError(json, err.message);
+	return exitAfterFlush(ExitCode.ApiError);
+}
 function parsePositiveInt(raw) {
 	if (!/^[1-9]\d*$/.test(raw)) return null;
 	const n = Number.parseInt(raw, 10);
@@ -441,6 +546,469 @@ async function resolveWorkspaceContext(args) {
 	};
 }
 //#endregion
+//#region src/config/app-manifest.ts
+var ManifestError = class extends Error {
+	kind;
+	field;
+	constructor(kind, message, field) {
+		super(message);
+		this.name = "ManifestError";
+		this.kind = kind;
+		this.field = field;
+	}
+};
+const DEFAULT_NAMES = ["aitcc.app.yaml", "aitcc.app.json"];
+async function fileExists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Resolve the manifest file path. When `explicit` is provided, we use it
+* verbatim (resolved against `cwd`) and require it to exist. Otherwise we
+* auto-detect `aitcc.app.yaml` then `aitcc.app.json` under `cwd`.
+*/
+async function resolveManifestPath(explicit, cwd) {
+	if (explicit) {
+		const abs = isAbsolute(explicit) ? explicit : resolve(cwd, explicit);
+		if (!await fileExists(abs)) throw new ManifestError("invalid-config", `manifest file not found at ${abs}`);
+		return abs;
+	}
+	for (const name of DEFAULT_NAMES) {
+		const abs = resolve(cwd, name);
+		if (await fileExists(abs)) return abs;
+	}
+	throw new ManifestError("invalid-config", `no app manifest found (looked for ${DEFAULT_NAMES.join(", ")} in ${cwd})`);
+}
+async function loadAppManifest(path) {
+	return validateManifest(parseManifestFile(path, await readFile(path, "utf8")), dirname(path));
+}
+function parseManifestFile(path, raw) {
+	const isJson = path.toLowerCase().endsWith(".json");
+	try {
+		const out = isJson ? JSON.parse(raw) : parse(raw);
+		if (out === null || typeof out !== "object" || Array.isArray(out)) throw new ManifestError("invalid-config", `manifest at ${path} is not a mapping`);
+		return out;
+	} catch (err) {
+		if (err instanceof ManifestError) throw err;
+		const msg = err.message;
+		throw new ManifestError("invalid-config", `failed to parse manifest at ${path}: ${msg}`);
+	}
+}
+function requireString(input, key) {
+	const v = input[key];
+	if (v === void 0 || v === null) throw new ManifestError("missing-required-field", `${key} is required`, key);
+	if (typeof v !== "string") throw new ManifestError("invalid-config", `${key} must be a string`, key);
+	if (v.trim().length === 0) throw new ManifestError("missing-required-field", `${key} is required`, key);
+	return v;
+}
+function optionalString(input, key) {
+	const v = input[key];
+	if (v === void 0 || v === null) return void 0;
+	if (typeof v !== "string") throw new ManifestError("invalid-config", `${key} must be a string when provided`, key);
+	return v;
+}
+function requirePath(input, key, configDir) {
+	const rel = requireString(input, key);
+	return isAbsolute(rel) ? rel : resolve(configDir, rel);
+}
+function optionalPath(input, key, configDir) {
+	const rel = optionalString(input, key);
+	if (rel === void 0) return void 0;
+	return isAbsolute(rel) ? rel : resolve(configDir, rel);
+}
+function requireNumberArray(input, key, { min }) {
+	const v = input[key];
+	if (!Array.isArray(v)) throw new ManifestError("invalid-config", `${key} must be an array of numbers`, key);
+	if (v.length < min) throw new ManifestError("invalid-config", `${key} must contain at least ${min} item(s)`, key);
+	return v.map((item, idx) => {
+		if (typeof item !== "number" || !Number.isInteger(item)) throw new ManifestError("invalid-config", `${key}[${idx}] must be an integer`, key);
+		return item;
+	});
+}
+function optionalStringArray(input, key, { max } = {}) {
+	const v = input[key];
+	if (v === void 0 || v === null) return [];
+	if (!Array.isArray(v)) throw new ManifestError("invalid-config", `${key} must be an array of strings`, key);
+	if (max !== void 0 && v.length > max) throw new ManifestError("invalid-config", `${key} accepts at most ${max} entries (got ${v.length})`, key);
+	return v.map((item, idx) => {
+		if (typeof item !== "string") throw new ManifestError("invalid-config", `${key}[${idx}] must be a string`, key);
+		return item;
+	});
+}
+function requirePathArray(input, key, configDir, { min }) {
+	const v = input[key];
+	if (!Array.isArray(v)) throw new ManifestError("invalid-config", `${key} must be an array of paths`, key);
+	if (v.length < min) throw new ManifestError("invalid-config", `${key} must contain at least ${min} item(s)`, key);
+	return v.map((item, idx) => {
+		if (typeof item !== "string" || item.trim().length === 0) throw new ManifestError("invalid-config", `${key}[${idx}] must be a non-empty string`, key);
+		return isAbsolute(item) ? item : resolve(configDir, item);
+	});
+}
+function optionalPathArray(input, key, configDir) {
+	const v = input[key];
+	if (v === void 0 || v === null) return [];
+	if (!Array.isArray(v)) throw new ManifestError("invalid-config", `${key} must be an array of paths`, key);
+	return v.map((item, idx) => {
+		if (typeof item !== "string" || item.trim().length === 0) throw new ManifestError("invalid-config", `${key}[${idx}] must be a non-empty string`, key);
+		return isAbsolute(item) ? item : resolve(configDir, item);
+	});
+}
+const EMAIL_REGEX = /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
+function isValidEmail(v) {
+	return EMAIL_REGEX.test(v.toLowerCase());
+}
+function isValidHttpUrl(v) {
+	try {
+		const parsed = new URL(v);
+		return parsed.protocol === "http:" || parsed.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+function validateManifest(raw, configDir) {
+	const titleKo = requireString(raw, "titleKo");
+	const titleEn = requireString(raw, "titleEn");
+	const appName = requireString(raw, "appName");
+	const csEmail = requireString(raw, "csEmail");
+	if (!isValidEmail(csEmail)) throw new ManifestError("invalid-config", `csEmail is not a valid email address (got ${csEmail})`, "csEmail");
+	const subtitle = requireString(raw, "subtitle");
+	if (subtitle.length > 20) throw new ManifestError("invalid-config", `subtitle must be 20 characters or fewer (got ${subtitle.length})`, "subtitle");
+	const description = requireString(raw, "description");
+	const homePageUri = optionalString(raw, "homePageUri");
+	if (homePageUri !== void 0 && !isValidHttpUrl(homePageUri)) throw new ManifestError("invalid-config", `homePageUri must be a http(s) URL (got ${homePageUri})`, "homePageUri");
+	return {
+		titleKo,
+		titleEn,
+		appName,
+		homePageUri,
+		csEmail,
+		logo: requirePath(raw, "logo", configDir),
+		logoDarkMode: optionalPath(raw, "logoDarkMode", configDir),
+		horizontalThumbnail: requirePath(raw, "horizontalThumbnail", configDir),
+		categoryIds: requireNumberArray(raw, "categoryIds", { min: 1 }),
+		subtitle,
+		description,
+		keywords: optionalStringArray(raw, "keywords", { max: 10 }),
+		verticalScreenshots: requirePathArray(raw, "verticalScreenshots", configDir, { min: 3 }),
+		horizontalScreenshots: optionalPathArray(raw, "horizontalScreenshots", configDir)
+	};
+}
+//#endregion
+//#region src/config/image-validator.ts
+var ImageDimensionError = class extends Error {
+	path;
+	expected;
+	actual;
+	reason;
+	constructor(args) {
+		super(args.message);
+		this.name = "ImageDimensionError";
+		this.path = args.path;
+		this.expected = args.expected;
+		this.actual = args.actual;
+		this.reason = args.reason;
+	}
+};
+function format(dim) {
+	return `${dim.width}x${dim.height}`;
+}
+async function validateImageDimensions(path, expected) {
+	let buffer;
+	try {
+		buffer = await readFile(path);
+	} catch (err) {
+		throw new ImageDimensionError({
+			path,
+			expected: format(expected),
+			actual: void 0,
+			reason: "unreadable",
+			message: `could not read image at ${path}: ${err.message}`
+		});
+	}
+	let dims;
+	try {
+		dims = imageSize(buffer);
+	} catch (err) {
+		throw new ImageDimensionError({
+			path,
+			expected: format(expected),
+			actual: void 0,
+			reason: "unreadable",
+			message: `could not decode image header at ${path}: ${err.message}`
+		});
+	}
+	if (typeof dims.width !== "number" || typeof dims.height !== "number") throw new ImageDimensionError({
+		path,
+		expected: format(expected),
+		actual: void 0,
+		reason: "unreadable",
+		message: `image header at ${path} did not expose width/height`
+	});
+	if (dims.width !== expected.width || dims.height !== expected.height) {
+		const actual = `${dims.width}x${dims.height}`;
+		throw new ImageDimensionError({
+			path,
+			expected: format(expected),
+			actual,
+			reason: "mismatch",
+			message: `image ${path} has dimensions ${actual}; expected ${format(expected)}`
+		});
+	}
+}
+const DIMENSIONS = {
+	logo: {
+		width: 600,
+		height: 600
+	},
+	horizontalThumbnail: {
+		width: 1932,
+		height: 828
+	},
+	verticalScreenshot: {
+		width: 636,
+		height: 1048
+	},
+	horizontalScreenshot: {
+		width: 1504,
+		height: 741
+	}
+};
+//#endregion
+//#region src/commands/register-payload.ts
+function buildSubmitPayload(manifest, urls) {
+	const images = [
+		{
+			imageUrl: urls.horizontalThumbnail,
+			imageType: "THUMBNAIL",
+			orientation: "HORIZONTAL"
+		},
+		...urls.verticalScreenshots.map((u) => ({
+			imageUrl: u,
+			imageType: "PREVIEW",
+			orientation: "VERTICAL"
+		})),
+		...urls.horizontalScreenshots.map((u) => ({
+			imageUrl: u,
+			imageType: "PREVIEW",
+			orientation: "HORIZONTAL"
+		}))
+	];
+	return {
+		miniApp: {
+			title: manifest.titleKo,
+			titleEn: manifest.titleEn,
+			appName: manifest.appName,
+			iconUri: urls.logo,
+			status: "PREPARE",
+			csEmail: manifest.csEmail,
+			description: manifest.subtitle,
+			detailDescription: manifest.description,
+			images,
+			...urls.logoDarkMode !== void 0 ? { darkModeIconUri: urls.logoDarkMode } : {},
+			...manifest.homePageUri !== void 0 ? { homePageUri: manifest.homePageUri } : {}
+		},
+		impression: {
+			keywordList: manifest.keywords,
+			categoryIds: manifest.categoryIds
+		}
+	};
+}
+//#endregion
+//#region src/commands/register.ts
+async function runRegister(args, deps = {}) {
+	const ctx = await resolveWorkspaceContext({
+		json: args.json,
+		...args.workspace !== void 0 ? { workspace: args.workspace } : {}
+	});
+	if (!ctx) return;
+	const { session, workspaceId } = ctx;
+	const manifest = await loadAndValidateManifest(args, deps);
+	if (!manifest) return;
+	if (!args.dryRun && !args.acceptTerms) {
+		emitTermsNotAccepted(args.json);
+		await exitAfterFlush(ExitCode.Usage);
+		return;
+	}
+	try {
+		if (args.dryRun) {
+			const payload = buildSubmitPayload(manifest, {
+				logo: "<dry-run:logo>",
+				logoDarkMode: manifest.logoDarkMode !== void 0 ? "<dry-run:logoDarkMode>" : void 0,
+				horizontalThumbnail: "<dry-run:horizontalThumbnail>",
+				verticalScreenshots: manifest.verticalScreenshots.map((_, i) => `<dry-run:verticalScreenshots[${i}]>`),
+				horizontalScreenshots: manifest.horizontalScreenshots.map((_, i) => `<dry-run:horizontalScreenshots[${i}]>`)
+			});
+			emitDryRun(args.json, workspaceId, payload);
+			return exitAfterFlush(ExitCode.Ok);
+		}
+		const payload = buildSubmitPayload(manifest, await uploadAllImages(workspaceId, manifest, session.cookies, deps));
+		const result = await (deps.submitImpl ?? ((wid, p, c) => createMiniApp(wid, p, c)))(workspaceId, payload, session.cookies);
+		emitSuccess(args.json, workspaceId, result);
+		return exitAfterFlush(ExitCode.Ok);
+	} catch (err) {
+		return emitFailureAndExit(args.json, err);
+	}
+}
+async function loadAndValidateManifest(args, deps) {
+	const cwd = deps.cwd ?? process.cwd();
+	let manifest;
+	try {
+		manifest = await loadAppManifest(await resolveManifestPath(args.config, cwd));
+	} catch (err) {
+		if (err instanceof ManifestError) {
+			emitManifestError(args.json, err);
+			await exitAfterFlush(ExitCode.Usage);
+			return null;
+		}
+		throw err;
+	}
+	try {
+		await validateImageDimensions(manifest.logo, DIMENSIONS.logo);
+		if (manifest.logoDarkMode !== void 0) await validateImageDimensions(manifest.logoDarkMode, DIMENSIONS.logo);
+		await validateImageDimensions(manifest.horizontalThumbnail, DIMENSIONS.horizontalThumbnail);
+		for (const p of manifest.verticalScreenshots) await validateImageDimensions(p, DIMENSIONS.verticalScreenshot);
+		for (const p of manifest.horizontalScreenshots) await validateImageDimensions(p, DIMENSIONS.horizontalScreenshot);
+	} catch (err) {
+		if (err instanceof ImageDimensionError) {
+			emitImageDimensionError(args.json, err);
+			await exitAfterFlush(ExitCode.Usage);
+			return null;
+		}
+		throw err;
+	}
+	return manifest;
+}
+async function uploadAllImages(workspaceId, manifest, cookies, deps) {
+	const uploadImpl = deps.uploadImpl ?? ((p) => uploadMiniAppResource(p));
+	const logo = await uploadOne(uploadImpl, {
+		workspaceId,
+		validWidth: DIMENSIONS.logo.width,
+		validHeight: DIMENSIONS.logo.height,
+		cookies,
+		path: manifest.logo
+	});
+	const logoDarkMode = manifest.logoDarkMode !== void 0 ? await uploadOne(uploadImpl, {
+		workspaceId,
+		validWidth: DIMENSIONS.logo.width,
+		validHeight: DIMENSIONS.logo.height,
+		cookies,
+		path: manifest.logoDarkMode
+	}) : void 0;
+	const horizontalThumbnail = await uploadOne(uploadImpl, {
+		workspaceId,
+		validWidth: DIMENSIONS.horizontalThumbnail.width,
+		validHeight: DIMENSIONS.horizontalThumbnail.height,
+		cookies,
+		path: manifest.horizontalThumbnail
+	});
+	const verticalScreenshots = [];
+	for (const p of manifest.verticalScreenshots) verticalScreenshots.push(await uploadOne(uploadImpl, {
+		workspaceId,
+		validWidth: DIMENSIONS.verticalScreenshot.width,
+		validHeight: DIMENSIONS.verticalScreenshot.height,
+		cookies,
+		path: p
+	}));
+	const horizontalScreenshots = [];
+	for (const p of manifest.horizontalScreenshots) horizontalScreenshots.push(await uploadOne(uploadImpl, {
+		workspaceId,
+		validWidth: DIMENSIONS.horizontalScreenshot.width,
+		validHeight: DIMENSIONS.horizontalScreenshot.height,
+		cookies,
+		path: p
+	}));
+	return {
+		logo,
+		logoDarkMode,
+		horizontalThumbnail,
+		verticalScreenshots,
+		horizontalScreenshots
+	};
+}
+async function uploadOne(uploadImpl, input) {
+	const buffer = await readFile(input.path);
+	return uploadImpl({
+		workspaceId: input.workspaceId,
+		validWidth: input.validWidth,
+		validHeight: input.validHeight,
+		cookies: input.cookies,
+		file: {
+			buffer,
+			fileName: basename(input.path),
+			contentType: "image/png"
+		}
+	});
+}
+function emitManifestError(json, err) {
+	if (json) if (err.kind === "missing-required-field") emitJson({
+		ok: false,
+		reason: "missing-required-field",
+		field: err.field ?? null,
+		message: err.message
+	});
+	else emitJson({
+		ok: false,
+		reason: "invalid-config",
+		message: err.message
+	});
+	else process.stderr.write(`${err.message}\n`);
+}
+function emitImageDimensionError(json, err) {
+	if (json) if (err.reason === "mismatch") emitJson({
+		ok: false,
+		reason: "image-dimension-mismatch",
+		path: err.path,
+		expected: err.expected,
+		actual: err.actual ?? null,
+		message: err.message
+	});
+	else emitJson({
+		ok: false,
+		reason: "image-unreadable",
+		path: err.path,
+		message: err.message
+	});
+	else process.stderr.write(`${err.message}\n`);
+}
+function emitTermsNotAccepted(json) {
+	const message = "The console requires several legal-agreement checkboxes before submitting a mini-app for review. Re-run with --accept-terms to attest that you have read and agree to each of them (see VALIDATION-RULES.md or the console UI), or use --dry-run to preview the payload without submitting.";
+	if (json) emitJson({
+		ok: false,
+		reason: "terms-not-accepted",
+		message
+	});
+	else process.stderr.write(`${message}\n`);
+}
+function emitDryRun(json, workspaceId, payload) {
+	if (json) emitJson({
+		ok: true,
+		dryRun: true,
+		workspaceId,
+		payload
+	});
+	else {
+		process.stdout.write("[dry-run] Would POST to ");
+		process.stdout.write(`https://apps-in-toss.toss.im/console/api-public/v3/appsintossconsole/workspaces/${workspaceId}/mini-app/review\n`);
+		process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+	}
+}
+function emitSuccess(json, workspaceId, result) {
+	if (json) emitJson({
+		ok: true,
+		workspaceId,
+		appId: result.miniAppId ?? null,
+		reviewState: result.reviewState ?? null
+	});
+	else process.stdout.write(`Registered mini-app ${result.miniAppId ?? "(id unknown)"} in workspace ${workspaceId} (reviewState=${result.reviewState ?? "unknown"}).\n`);
+}
+async function emitFailureAndExit(json, err) {
+	return emitFailureFromError(json, err);
+}
+//#endregion
 //#region src/commands/app.ts
 function findReviewEntry(reviewEntries, appId) {
 	const target = String(appId);
@@ -460,72 +1028,105 @@ const appCommand = defineCommand({
 		name: "app",
 		description: "Inspect mini-apps in a workspace."
 	},
-	subCommands: { ls: defineCommand({
-		meta: {
-			name: "ls",
-			description: "List mini-apps in the selected workspace."
-		},
-		args: {
-			workspace: {
-				type: "string",
-				description: "Workspace ID. Defaults to the selected workspace (`aitcc workspace use`)."
+	subCommands: {
+		ls: defineCommand({
+			meta: {
+				name: "ls",
+				description: "List mini-apps in the selected workspace."
 			},
-			json: {
-				type: "boolean",
-				description: "Emit machine-readable JSON to stdout.",
-				default: false
-			}
-		},
-		async run({ args }) {
-			const ctx = await resolveWorkspaceContext(args);
-			if (!ctx) return;
-			const { session, workspaceId } = ctx;
-			try {
-				const [apps, review] = await Promise.all([fetchMiniApps(workspaceId, session.cookies), fetchReviewStatus(workspaceId, session.cookies)]);
-				if (args.json) {
-					const joined = apps.map((app) => {
-						const reviewState = reviewStateFor(findReviewEntry(review.miniApps, app.id));
-						return {
-							id: app.id,
-							name: app.name ?? null,
-							...reviewState !== void 0 ? { reviewState } : {},
-							extra: app.extra
-						};
-					});
-					emitJson({
-						ok: true,
-						workspaceId,
-						hasPolicyViolation: review.hasPolicyViolation,
-						apps: joined
-					});
-					return exitAfterFlush(ExitCode.Ok);
+			args: {
+				workspace: {
+					type: "string",
+					description: "Workspace ID. Defaults to the selected workspace (`aitcc workspace use`)."
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON to stdout.",
+					default: false
 				}
-				if (apps.length === 0) {
-					process.stdout.write(`No apps in workspace ${workspaceId}.\n`);
+			},
+			async run({ args }) {
+				const ctx = await resolveWorkspaceContext(args);
+				if (!ctx) return;
+				const { session, workspaceId } = ctx;
+				try {
+					const [apps, review] = await Promise.all([fetchMiniApps(workspaceId, session.cookies), fetchReviewStatus(workspaceId, session.cookies)]);
+					if (args.json) {
+						const joined = apps.map((app) => {
+							const reviewState = reviewStateFor(findReviewEntry(review.miniApps, app.id));
+							return {
+								id: app.id,
+								name: app.name ?? null,
+								...reviewState !== void 0 ? { reviewState } : {},
+								extra: app.extra
+							};
+						});
+						emitJson({
+							ok: true,
+							workspaceId,
+							hasPolicyViolation: review.hasPolicyViolation,
+							apps: joined
+						});
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					if (apps.length === 0) {
+						process.stdout.write(`No apps in workspace ${workspaceId}.\n`);
+						if (review.hasPolicyViolation) process.stderr.write("Note: workspace-wide policy violation flag is set.\n");
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					for (const app of apps) {
+						const reviewState = reviewStateFor(findReviewEntry(review.miniApps, app.id)) ?? "-";
+						const name = app.name ?? "(unnamed)";
+						process.stdout.write(`${app.id}\t${name}\t${reviewState}\n`);
+					}
 					if (review.hasPolicyViolation) process.stderr.write("Note: workspace-wide policy violation flag is set.\n");
 					return exitAfterFlush(ExitCode.Ok);
+				} catch (err) {
+					return emitFailureFromError(args.json, err);
 				}
-				for (const app of apps) {
-					const reviewState = reviewStateFor(findReviewEntry(review.miniApps, app.id)) ?? "-";
-					const name = app.name ?? "(unnamed)";
-					process.stdout.write(`${app.id}\t${name}\t${reviewState}\n`);
-				}
-				if (review.hasPolicyViolation) process.stderr.write("Note: workspace-wide policy violation flag is set.\n");
-				return exitAfterFlush(ExitCode.Ok);
-			} catch (err) {
-				if (err instanceof TossApiError && err.isAuthError) {
-					emitNotAuthenticated(args.json, "session-expired");
-					return exitAfterFlush(ExitCode.NotAuthenticated);
-				}
-				if (err instanceof NetworkError) {
-					emitNetworkError(args.json, err.message);
-					return exitAfterFlush(ExitCode.NetworkError);
+			}
+		}),
+		register: defineCommand({
+			meta: {
+				name: "register",
+				description: "Register a mini-app in the selected workspace from a YAML/JSON manifest. Uploads logo/thumbnail/screenshots, then submits the create payload."
+			},
+			args: {
+				workspace: {
+					type: "string",
+					description: "Workspace ID. Defaults to the selected workspace (`aitcc workspace use`)."
+				},
+				config: {
+					type: "string",
+					description: "Path to the app manifest. Defaults to `./aitcc.app.yaml`, then `./aitcc.app.json`."
+				},
+				"dry-run": {
+					type: "boolean",
+					description: "Validate manifest + images and print the inferred submit payload; no uploads.",
+					default: false
+				},
+				"accept-terms": {
+					type: "boolean",
+					description: "Attest to the required console legal-agreement checkboxes (see VALIDATION-RULES.md). Required for real submits.",
+					default: false
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON to stdout.",
+					default: false
 				}
-				emitApiError(args.json, err.message);
-				return exitAfterFlush(ExitCode.ApiError);
+			},
+			async run({ args }) {
+				await runRegister({
+					json: args.json,
+					dryRun: args["dry-run"],
+					acceptTerms: args["accept-terms"],
+					...args.workspace !== void 0 ? { workspace: args.workspace } : {},
+					...args.config !== void 0 ? { config: args.config } : {}
+				});
 			}
-		}
-	}) }
+		})
+	}
 });
 //#endregion
 //#region src/api/api-keys.ts
@@ -605,16 +1206,7 @@ const keysCommand = defineCommand({
 				}
 				return exitAfterFlush(ExitCode.Ok);
 			} catch (err) {
-				if (err instanceof TossApiError && err.isAuthError) {
-					emitNotAuthenticated(args.json, "session-expired");
-					return exitAfterFlush(ExitCode.NotAuthenticated);
-				}
-				if (err instanceof NetworkError) {
-					emitNetworkError(args.json, err.message);
-					return exitAfterFlush(ExitCode.NetworkError);
-				}
-				emitApiError(args.json, err.message);
-				return exitAfterFlush(ExitCode.ApiError);
+				return emitFailureFromError(args.json, err);
 			}
 		}
 	}) }
@@ -1367,16 +1959,7 @@ const membersCommand = defineCommand({
 				for (const m of members) process.stdout.write(`${m.bizUserNo}\t${m.name}\t${m.email}\t${m.role}\t${m.status}\n`);
 				return exitAfterFlush(ExitCode.Ok);
 			} catch (err) {
-				if (err instanceof TossApiError && err.isAuthError) {
-					emitNotAuthenticated(args.json, "session-expired");
-					return exitAfterFlush(ExitCode.NotAuthenticated);
-				}
-				if (err instanceof NetworkError) {
-					emitNetworkError(args.json, err.message);
-					return exitAfterFlush(ExitCode.NetworkError);
-				}
-				emitApiError(args.json, err.message);
-				return exitAfterFlush(ExitCode.ApiError);
+				return emitFailureFromError(args.json, err);
 			}
 		}
 	}) }
@@ -1494,7 +2077,7 @@ function resolveVersion() {
 		if (typeof injected === "string" && injected.length > 0) return injected;
 	} catch {}
 	try {
-		return "0.1.5";
+		return "0.1.6";
 	} catch {}
 	return "0.0.0-dev";
 }
@@ -1928,16 +2511,7 @@ const workspaceCommand = defineCommand({
 					if (current === void 0) process.stderr.write("No workspace selected. Run `aitcc workspace use <id>`.\n");
 					return exitAfterFlush(ExitCode.Ok);
 				} catch (err) {
-					if (err instanceof TossApiError && err.isAuthError) {
-						emitNotAuthenticated(args.json, "session-expired");
-						return exitAfterFlush(ExitCode.NotAuthenticated);
-					}
-					if (err instanceof NetworkError) {
-						emitNetworkError(args.json, err.message);
-						return exitAfterFlush(ExitCode.NetworkError);
-					}
-					emitApiError(args.json, err.message);
-					return exitAfterFlush(ExitCode.ApiError);
+					return emitFailureFromError(args.json, err);
 				}
 			}
 		}),
@@ -1999,16 +2573,7 @@ const workspaceCommand = defineCommand({
 					else process.stdout.write(`Using workspace ${match.workspaceId} (${match.workspaceName}).\n`);
 					return exitAfterFlush(ExitCode.Ok);
 				} catch (err) {
-					if (err instanceof TossApiError && err.isAuthError) {
-						emitNotAuthenticated(args.json, "session-expired");
-						return exitAfterFlush(ExitCode.NotAuthenticated);
-					}
-					if (err instanceof NetworkError) {
-						emitNetworkError(args.json, err.message);
-						return exitAfterFlush(ExitCode.NetworkError);
-					}
-					emitApiError(args.json, err.message);
-					return exitAfterFlush(ExitCode.ApiError);
+					return emitFailureFromError(args.json, err);
 				}
 			}
 		}),
@@ -2073,16 +2638,7 @@ const workspaceCommand = defineCommand({
 					if (detail.extra) for (const [k, v] of Object.entries(detail.extra)) process.stdout.write(`  ${k}: ${formatScalar(v)}\n`);
 					return exitAfterFlush(ExitCode.Ok);
 				} catch (err) {
-					if (err instanceof TossApiError && err.isAuthError) {
-						emitNotAuthenticated(args.json, "session-expired");
-						return exitAfterFlush(ExitCode.NotAuthenticated);
-					}
-					if (err instanceof NetworkError) {
-						emitNetworkError(args.json, err.message);
-						return exitAfterFlush(ExitCode.NetworkError);
-					}
-					emitApiError(args.json, err.message);
-					return exitAfterFlush(ExitCode.ApiError);
+					return emitFailureFromError(args.json, err);
 				}
 			}
 		})