@ait-co/console-cli 0.1.4 → 0.1.6

package/dist/cli.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 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 { parse } from "yaml";
+import { imageSize } from "image-size";
 import { spawn } from "node:child_process";
 import { constants } from "node:fs";
-import { chmod, mkdir, mkdtemp, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
-import { homedir, tmpdir } from "node:os";
-import { basename, dirname, join, win32 } from "node:path";
 //#region src/api/http.ts
 var TossApiError = class extends Error {
 	constructor(status, errorCode, reason, errorType) {
@@ -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);
 	}
@@ -143,6 +160,1058 @@ async function requestConsoleApi(options) {
 	throw new TossApiError(res.status, parsed.error.errorCode, parsed.error.reason, parsed.error.errorType);
 }
 //#endregion
+//#region src/api/mini-apps.ts
+const BASE$2 = "https://apps-in-toss.toss.im/console/api-public/v3/appsintossconsole";
+async function fetchMiniApps(workspaceId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		url: `${BASE$2}/workspaces/${workspaceId}/mini-app`,
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (!Array.isArray(raw)) throw new Error(`Unexpected mini-app list shape for workspace=${workspaceId}`);
+	return raw.map((item, index) => normalizeMiniApp(item, workspaceId, index));
+}
+function normalizeMiniApp(item, workspaceId, index) {
+	if (item === null || typeof item !== "object") throw new Error(`Unexpected mini-app entry at index ${index} for workspace=${workspaceId}: not an object`);
+	const rec = item;
+	const rawId = rec.id ?? rec.miniAppId ?? rec.appId;
+	if (typeof rawId !== "string" && typeof rawId !== "number") throw new Error(`Unexpected mini-app entry at index ${index} for workspace=${workspaceId}: missing id`);
+	const rawName = rec.name ?? rec.miniAppName ?? rec.appName;
+	const name = typeof rawName === "string" ? rawName : void 0;
+	const { id: _id, miniAppId: _mid, appId: _aid, name: _n, miniAppName: _mn, appName: _an, ...extra } = rec;
+	return {
+		id: rawId,
+		name,
+		extra
+	};
+}
+async function fetchReviewStatus(workspaceId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		url: `${BASE$2}/workspaces/${workspaceId}/mini-apps/review-status`,
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (raw === null || typeof raw !== "object") throw new Error(`Unexpected review-status shape for workspace=${workspaceId}`);
+	const rec = raw;
+	const hasPolicyViolation = Boolean(rec.hasPolicyViolation);
+	const miniAppsRaw = rec.miniApps;
+	if (!Array.isArray(miniAppsRaw)) throw new Error(`Unexpected review-status shape for workspace=${workspaceId}: miniApps is not an array`);
+	return {
+		hasPolicyViolation,
+		miniApps: miniAppsRaw.map((m) => {
+			if (m === null || typeof m !== "object") return {};
+			return m;
+		})
+	};
+}
+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 = {
+	Ok: 0,
+	Generic: 1,
+	Usage: 2,
+	NotAuthenticated: 10,
+	NetworkError: 11,
+	LoginTimeout: 12,
+	LoginStateMismatch: 13,
+	LoginBrowserNotFound: 14,
+	LoginBrowserFailed: 15,
+	LoginCookieCaptureFailed: 16,
+	ApiError: 17,
+	UpgradeUnavailable: 20,
+	UpgradeAlreadyLatest: 21
+};
+//#endregion
+//#region src/flush.ts
+async function exitAfterFlush(code) {
+	await new Promise((resolve) => process.stdout.write("", () => resolve()));
+	process.exit(code);
+}
+//#endregion
+//#region src/paths.ts
+const APP_NAME = "aitcc";
+function configDir() {
+	if (process.platform === "win32") {
+		const appData = process.env.APPDATA;
+		if (appData && appData.length > 0) return join(appData, APP_NAME);
+		return join(homedir() || ".", "AppData", "Roaming", APP_NAME);
+	}
+	const xdg = process.env.XDG_CONFIG_HOME;
+	if (xdg && xdg.length > 0) return join(xdg, APP_NAME);
+	return join(homedir() || ".", ".config", APP_NAME);
+}
+function sessionFilePath() {
+	return join(configDir(), "session.json");
+}
+function cacheDir() {
+	if (process.platform === "win32") {
+		const localAppData = process.env.LOCALAPPDATA;
+		if (localAppData && localAppData.length > 0) return join(localAppData, APP_NAME, "Cache");
+		return join(homedir() || ".", "AppData", "Local", APP_NAME, "Cache");
+	}
+	const xdg = process.env.XDG_CACHE_HOME;
+	if (xdg && xdg.length > 0) return join(xdg, APP_NAME);
+	return join(homedir() || ".", ".cache", APP_NAME);
+}
+function upgradeCheckPath() {
+	return join(cacheDir(), "upgrade-check.json");
+}
+//#endregion
+//#region src/session.ts
+/**
+* Read the persisted session. Returns `null` when no session exists, when
+* the file is corrupt, or when the shape fails validation — each of those
+* emits a one-line warning on stderr for diagnostics.
+*
+* **Side effect**: a v1 session file is transparently rewritten to v2 on
+* the first successful read of this process. This keeps read-only callers
+* (`whoami`, `workspace ls`) from stranding users on an old schema. If the
+* rewrite fails, we warn once per process and continue with the in-memory
+* v2 value so the calling command still succeeds.
+*/
+async function readSession() {
+	const path = sessionFilePath();
+	let raw;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (err) {
+		const code = err.code;
+		if (code === "ENOENT") return null;
+		process.stderr.write(`warning: could not read session file at ${path}: ${code ?? "unknown"}\n`);
+		return null;
+	}
+	let rawParsed;
+	try {
+		rawParsed = JSON.parse(raw);
+	} catch {
+		process.stderr.write(`warning: session file at ${path} is corrupt and will be ignored\n`);
+		return null;
+	}
+	const schemaReason = validateSessionShape(rawParsed);
+	if (schemaReason) {
+		process.stderr.write(`warning: session file at ${path} ignored (${schemaReason}); re-run \`aitcc login\`\n`);
+		return null;
+	}
+	const validated = rawParsed;
+	if (validated.schemaVersion === 1) {
+		const upgraded = {
+			...validated,
+			schemaVersion: 2
+		};
+		try {
+			await writeSession(upgraded);
+		} catch (err) {
+			warnMigrationOnce(path, err.code);
+		}
+		return upgraded;
+	}
+	return validated;
+}
+let migrationWarned = false;
+function warnMigrationOnce(path, code) {
+	if (migrationWarned) return;
+	migrationWarned = true;
+	process.stderr.write(`warning: could not migrate session file at ${path} to schemaVersion 2: ${code ?? "unknown"}\n`);
+}
+function validateSessionShape(input) {
+	if (input === null || typeof input !== "object") return "root is not an object";
+	const parsed = input;
+	if (parsed.schemaVersion !== 1 && parsed.schemaVersion !== 2) return `unknown schemaVersion ${String(parsed.schemaVersion)}`;
+	if (!parsed.user || typeof parsed.user.id !== "string") return "missing user.id";
+	if (typeof parsed.user.email !== "string") return "missing user.email";
+	if (parsed.user.displayName !== void 0 && typeof parsed.user.displayName !== "string") return "user.displayName has wrong type";
+	if (!Array.isArray(parsed.cookies)) return "cookies is not an array";
+	if (parsed.origins !== void 0 && !Array.isArray(parsed.origins)) return "origins is not an array";
+	if (parsed.capturedAt !== void 0 && typeof parsed.capturedAt !== "string") return "capturedAt has wrong type";
+	if (parsed.currentWorkspaceId !== void 0) {
+		const wid = parsed.currentWorkspaceId;
+		if (typeof wid !== "number" || !Number.isInteger(wid) || wid <= 0) return "currentWorkspaceId has wrong type";
+	}
+	return null;
+}
+async function writeSession(session) {
+	await mkdir(dirname(sessionFilePath()), {
+		recursive: true,
+		mode: 448
+	});
+	await writeFile(sessionFilePath(), JSON.stringify(session, null, 2), { mode: 384 });
+	try {
+		await chmod(sessionFilePath(), 384);
+	} catch {}
+}
+/**
+* Persist a new `currentWorkspaceId` on an existing session. Returns the
+* updated session, or `null` if there is no session to update (callers
+* should surface "not logged in" in that case).
+*/
+async function setCurrentWorkspaceId(workspaceId) {
+	const session = await readSession();
+	if (!session) return null;
+	const updated = {
+		...session,
+		currentWorkspaceId: workspaceId
+	};
+	await writeSession(updated);
+	return updated;
+}
+async function clearSession() {
+	try {
+		await unlink(sessionFilePath());
+		return { existed: true };
+	} catch (err) {
+		if (err.code === "ENOENT") return { existed: false };
+		throw err;
+	}
+}
+function sessionPathForDiagnostics() {
+	return sessionFilePath();
+}
+//#endregion
+//#region src/commands/_shared.ts
+function emitJson(payload) {
+	process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+function emitNotAuthenticated(json, reason) {
+	if (json) emitJson(reason ? {
+		ok: true,
+		authenticated: false,
+		reason
+	} : {
+		ok: true,
+		authenticated: false
+	});
+	else {
+		process.stderr.write(reason === "session-expired" ? "Session is no longer valid. Run `aitcc login` again.\n" : "Not logged in. Run `aitcc login` to start a session.\n");
+		process.stderr.write(`Session file checked: ${sessionPathForDiagnostics()}\n`);
+	}
+}
+function emitNetworkError(json, message) {
+	if (json) emitJson({
+		ok: false,
+		reason: "network-error",
+		message
+	});
+	else process.stderr.write(`Network error reaching the console API: ${message}.\n`);
+}
+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);
+	return Number.isSafeInteger(n) ? n : null;
+}
+/**
+* Boilerplate wrapper for any workspace-scoped command (`app ls`,
+* `members ls`, `keys ls`, ...). Loads the session, resolves the workspace
+* id from `--workspace <id>` or the persisted selection, and handles the
+* three common failure branches (`no session`, `invalid id`, `no workspace
+* selected`). On success, the caller gets the session + resolved id back.
+*
+* The return type is `Promise<... | null>` but the `null` branch is never
+* observed at runtime: every failure path `await`s `exitAfterFlush` which
+* calls `process.exit(...)` and doesn't return. The `| null` is a type-
+* level handshake that forces callers to add `if (!ctx) return;`, keeping
+* the bail-out readable.
+*/
+async function resolveWorkspaceContext(args) {
+	const session = await readSession();
+	if (!session) {
+		emitNotAuthenticated(args.json);
+		await exitAfterFlush(ExitCode.NotAuthenticated);
+		return null;
+	}
+	let workspaceId;
+	if (args.workspace) {
+		const raw = String(args.workspace);
+		const parsed = parsePositiveInt(raw);
+		if (parsed === null) {
+			const message = `--workspace must be a positive integer (got ${raw})`;
+			if (args.json) emitJson({
+				ok: false,
+				reason: "invalid-id",
+				message
+			});
+			else process.stderr.write(`${message}\n`);
+			await exitAfterFlush(ExitCode.Usage);
+			return null;
+		}
+		workspaceId = parsed;
+	} else workspaceId = session.currentWorkspaceId;
+	if (workspaceId === void 0) {
+		if (args.json) emitJson({
+			ok: false,
+			reason: "no-workspace-selected"
+		});
+		else process.stderr.write("No workspace selected. Pass `--workspace <id>` or run `aitcc workspace use <id>`.\n");
+		await exitAfterFlush(ExitCode.Usage);
+		return null;
+	}
+	return {
+		session,
+		workspaceId
+	};
+}
+//#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);
+	for (const entry of reviewEntries) {
+		const candidate = entry.id ?? entry.miniAppId ?? entry.appId;
+		if (candidate !== void 0 && String(candidate) === target) return entry;
+	}
+	return null;
+}
+function reviewStateFor(entry) {
+	if (!entry) return void 0;
+	const raw = entry.reviewState ?? entry.status;
+	return typeof raw === "string" ? raw : void 0;
+}
+const appCommand = defineCommand({
+	meta: {
+		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`)."
+				},
+				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);
+					}
+					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);
+				}
+			}
+		}),
+		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
+				}
+			},
+			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
+const BASE$1 = "https://apps-in-toss.toss.im/console/api-public/v3/appsintossconsole";
+async function fetchApiKeys(workspaceId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		url: `${BASE$1}/workspaces/${workspaceId}/api-keys`,
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (!Array.isArray(raw)) throw new Error(`Unexpected api-keys shape for workspace=${workspaceId}: not an array`);
+	return raw.map((entry, index) => normalizeKey(entry, workspaceId, index));
+}
+function normalizeKey(raw, workspaceId, index) {
+	if (raw === null || typeof raw !== "object") throw new Error(`Unexpected api-key entry at index ${index} for workspace=${workspaceId}: not an object`);
+	const rec = raw;
+	const rawId = rec.id ?? rec.apiKeyId ?? rec.keyId;
+	if (typeof rawId !== "string" && typeof rawId !== "number") throw new Error(`Unexpected api-key entry at index ${index} for workspace=${workspaceId}: missing id`);
+	const rawName = rec.name ?? rec.apiKeyName ?? rec.keyName ?? rec.description;
+	const name = typeof rawName === "string" ? rawName : void 0;
+	const { id: _id, apiKeyId: _aid, keyId: _kid, name: _n, apiKeyName: _an, keyName: _kn, description: _d, ...extra } = rec;
+	return {
+		id: rawId,
+		name,
+		extra
+	};
+}
+const keysCommand = defineCommand({
+	meta: {
+		name: "keys",
+		description: "Inspect console API keys used for deploy automation."
+	},
+	subCommands: { ls: defineCommand({
+		meta: {
+			name: "ls",
+			description: "List console API keys in the selected workspace."
+		},
+		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
+			}
+		},
+		async run({ args }) {
+			const ctx = await resolveWorkspaceContext(args);
+			if (!ctx) return;
+			const { session, workspaceId } = ctx;
+			try {
+				const keys = await fetchApiKeys(workspaceId, session.cookies);
+				if (args.json) {
+					emitJson({
+						ok: true,
+						workspaceId,
+						keys: keys.map((k) => ({
+							id: k.id,
+							name: k.name ?? null,
+							extra: k.extra
+						})),
+						...keys.length === 0 ? { needsKey: true } : {}
+					});
+					return exitAfterFlush(ExitCode.Ok);
+				}
+				if (keys.length === 0) {
+					process.stdout.write(`No API keys in workspace ${workspaceId}.\n`);
+					process.stderr.write("Hint: issue a key from the console UI (API 키 → 발급받기) to enable deploy automation.\n");
+					return exitAfterFlush(ExitCode.Ok);
+				}
+				process.stdout.write(`${keys.length} API key(s) in workspace ${workspaceId}:\n`);
+				for (const k of keys) {
+					const name = k.name ?? "(unnamed)";
+					process.stdout.write(`${k.id}\t${name}\n`);
+				}
+				return exitAfterFlush(ExitCode.Ok);
+			} catch (err) {
+				return emitFailureFromError(args.json, err);
+			}
+		}
+	}) }
+});
+//#endregion
 //#region src/api/me.ts
 const MEMBER_USER_INFO_URL = "https://apps-in-toss.toss.im/console/api-public/v3/appsintossconsole/members/me/user-info";
 async function fetchConsoleMemberUserInfo(cookies, opts = {}) {
@@ -519,102 +1588,6 @@ async function launchChrome(options) {
 	};
 }
 //#endregion
-//#region src/exit.ts
-const ExitCode = {
-	Ok: 0,
-	Generic: 1,
-	Usage: 2,
-	NotAuthenticated: 10,
-	NetworkError: 11,
-	LoginTimeout: 12,
-	LoginStateMismatch: 13,
-	LoginBrowserNotFound: 14,
-	LoginBrowserFailed: 15,
-	LoginCookieCaptureFailed: 16,
-	ApiError: 17,
-	UpgradeUnavailable: 20,
-	UpgradeAlreadyLatest: 21
-};
-//#endregion
-//#region src/flush.ts
-async function exitAfterFlush(code) {
-	await new Promise((resolve) => process.stdout.write("", () => resolve()));
-	process.exit(code);
-}
-//#endregion
-//#region src/paths.ts
-const APP_NAME = "aitcc";
-function configDir() {
-	if (process.platform === "win32") {
-		const appData = process.env.APPDATA;
-		if (appData && appData.length > 0) return join(appData, APP_NAME);
-		return join(homedir() || ".", "AppData", "Roaming", APP_NAME);
-	}
-	const xdg = process.env.XDG_CONFIG_HOME;
-	if (xdg && xdg.length > 0) return join(xdg, APP_NAME);
-	return join(homedir() || ".", ".config", APP_NAME);
-}
-function sessionFilePath() {
-	return join(configDir(), "session.json");
-}
-//#endregion
-//#region src/session.ts
-async function readSession() {
-	const path = sessionFilePath();
-	let raw;
-	try {
-		raw = await readFile(path, "utf8");
-	} catch (err) {
-		const code = err.code;
-		if (code === "ENOENT") return null;
-		process.stderr.write(`warning: could not read session file at ${path}: ${code ?? "unknown"}\n`);
-		return null;
-	}
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		process.stderr.write(`warning: session file at ${path} is corrupt and will be ignored\n`);
-		return null;
-	}
-	const schemaReason = validateSessionShape(parsed);
-	if (schemaReason) {
-		process.stderr.write(`warning: session file at ${path} ignored (${schemaReason}); re-run \`aitcc login\`\n`);
-		return null;
-	}
-	return parsed;
-}
-function validateSessionShape(parsed) {
-	if (parsed.schemaVersion !== 1) return `unknown schemaVersion ${String(parsed.schemaVersion)}`;
-	if (!parsed.user || typeof parsed.user.id !== "string") return "missing user.id";
-	if (typeof parsed.user.email !== "string") return "missing user.email";
-	if (parsed.user.displayName !== void 0 && typeof parsed.user.displayName !== "string") return "user.displayName has wrong type";
-	if (!Array.isArray(parsed.cookies)) return "cookies is not an array";
-	return null;
-}
-async function writeSession(session) {
-	await mkdir(dirname(sessionFilePath()), {
-		recursive: true,
-		mode: 448
-	});
-	await writeFile(sessionFilePath(), JSON.stringify(session, null, 2), { mode: 384 });
-	try {
-		await chmod(sessionFilePath(), 384);
-	} catch {}
-}
-async function clearSession() {
-	try {
-		await unlink(sessionFilePath());
-		return { existed: true };
-	} catch (err) {
-		if (err.code === "ENOENT") return { existed: false };
-		throw err;
-	}
-}
-function sessionPathForDiagnostics() {
-	return sessionFilePath();
-}
-//#endregion
 //#region src/commands/login.ts
 const DEFAULT_AUTHORIZE_URL = "https://business.toss.im/account/sign-in?client_id=4uktpjgqd0cp9txybqzuxc2y6w0cuupb&redirect_uri=https%3A%2F%2Fapps-in-toss.toss.im%2Fsign-up&state=%2Fworkspace";
 const LOGIN_LANDING_HOST = "apps-in-toss.toss.im";
@@ -776,7 +1749,7 @@ const loginCommand = defineCommand({
 			return exitWith(authFailed ? ExitCode.LoginCookieCaptureFailed : ExitCode.ApiError);
 		}
 		const session = {
-			schemaVersion: 1,
+			schemaVersion: 2,
 			user: {
 				id: String(user.id),
 				email: user.email,
@@ -902,6 +1875,96 @@ const logoutCommand = defineCommand({
 	}
 });
 //#endregion
+//#region src/api/members.ts
+const BASE = "https://apps-in-toss.toss.im/console/api-public/v3/appsintossconsole";
+async function fetchWorkspaceMembers(workspaceId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		url: `${BASE}/workspaces/${workspaceId}/members`,
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	if (!Array.isArray(raw)) throw new Error(`Unexpected members shape for workspace=${workspaceId}: not an array`);
+	return raw.map((entry, index) => normalizeMember(entry, workspaceId, index));
+}
+function normalizeMember(raw, workspaceId, index) {
+	if (raw === null || typeof raw !== "object") throw new Error(`Unexpected member entry at index ${index} for workspace=${workspaceId}: not an object`);
+	const rec = raw;
+	const stringField = (k) => {
+		const v = rec[k];
+		if (typeof v !== "string") throw new Error(`Unexpected member entry at index ${index} for workspace=${workspaceId}: missing ${k}`);
+		return v;
+	};
+	const numField = (k) => {
+		const v = rec[k];
+		if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`Unexpected member entry at index ${index} for workspace=${workspaceId}: missing ${k}`);
+		return v;
+	};
+	return {
+		workspaceId: numField("workspaceId"),
+		bizUserNo: numField("bizUserNo"),
+		name: stringField("name"),
+		email: stringField("email"),
+		status: stringField("status"),
+		role: stringField("role"),
+		isOwnerDelegationRequested: Boolean(rec.isOwnerDelegationRequested),
+		isAdult: Boolean(rec.isAdult)
+	};
+}
+const membersCommand = defineCommand({
+	meta: {
+		name: "members",
+		description: "Inspect workspace members."
+	},
+	subCommands: { ls: defineCommand({
+		meta: {
+			name: "ls",
+			description: "List members of the selected workspace."
+		},
+		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
+			}
+		},
+		async run({ args }) {
+			const ctx = await resolveWorkspaceContext(args);
+			if (!ctx) return;
+			const { session, workspaceId } = ctx;
+			try {
+				const members = await fetchWorkspaceMembers(workspaceId, session.cookies);
+				if (args.json) {
+					emitJson({
+						ok: true,
+						workspaceId,
+						members: members.map((m) => ({
+							bizUserNo: m.bizUserNo,
+							name: m.name,
+							email: m.email,
+							status: m.status,
+							role: m.role,
+							isOwnerDelegationRequested: m.isOwnerDelegationRequested
+						}))
+					});
+					return exitAfterFlush(ExitCode.Ok);
+				}
+				if (members.length === 0) {
+					process.stdout.write(`No members in workspace ${workspaceId}.\n`);
+					return exitAfterFlush(ExitCode.Ok);
+				}
+				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) {
+				return emitFailureFromError(args.json, err);
+			}
+		}
+	}) }
+});
+//#endregion
 //#region src/github.ts
 const REPO_OWNER = "apps-in-toss-community";
 const REPO_NAME = "console-cli";
@@ -921,6 +1984,29 @@ async function fetchLatestRelease() {
 	if (!res.ok) throw new Error(`GitHub releases/latest returned ${res.status} ${res.statusText}`);
 	return await res.json();
 }
+/**
+* Conditional GET against `releases/latest`. If the server returns 304 we
+* learn "no change" without consuming a core rate-limit slot. Intended for
+* the background update check, which re-runs often; `fetchLatestRelease()`
+* remains the right call when the upgrade command actually needs the body.
+*/
+async function fetchLatestReleaseConditional(previousEtag) {
+	const url = `https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest`;
+	const headers = defaultHeaders();
+	if (previousEtag && previousEtag.length > 0) headers["If-None-Match"] = previousEtag;
+	const res = await fetch(url, { headers });
+	const etag = res.headers.get("etag") ?? void 0;
+	if (res.status === 304) return {
+		status: "not-modified",
+		etag
+	};
+	if (!res.ok) throw new Error(`GitHub releases/latest returned ${res.status} ${res.statusText}`);
+	return {
+		status: "updated",
+		release: await res.json(),
+		etag
+	};
+}
 function versionFromTag(tag) {
 	const at = tag.lastIndexOf("@");
 	const candidate = at >= 0 ? tag.slice(at + 1) : tag;
@@ -991,7 +2077,7 @@ function resolveVersion() {
 		if (typeof injected === "string" && injected.length > 0) return injected;
 	} catch {}
 	try {
-		return "0.1.4";
+		return "0.1.6";
 	} catch {}
 	return "0.0.0-dev";
 }
@@ -1137,7 +2223,113 @@ const upgradeCommand = defineCommand({
 	}
 });
 //#endregion
+//#region src/update-check.ts
+const UPDATE_CHECK_INTERVAL_MS = 1440 * 60 * 1e3;
+async function readCache() {
+	let raw;
+	try {
+		raw = await readFile(upgradeCheckPath(), "utf8");
+	} catch {
+		return null;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!parsed || typeof parsed !== "object") return null;
+	const obj = parsed;
+	if (typeof obj.lastCheckedAt !== "string") return null;
+	if (obj.latestTag !== void 0 && typeof obj.latestTag !== "string") return null;
+	if (obj.etag !== void 0 && typeof obj.etag !== "string") return null;
+	return {
+		lastCheckedAt: obj.lastCheckedAt,
+		...obj.latestTag !== void 0 ? { latestTag: obj.latestTag } : {},
+		...obj.etag !== void 0 ? { etag: obj.etag } : {}
+	};
+}
+async function writeCache(entry) {
+	const path = upgradeCheckPath();
+	await mkdir(dirname(path), { recursive: true });
+	const tmp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+	try {
+		await writeFile(tmp, JSON.stringify(entry, null, 2), { mode: 384 });
+		await rename(tmp, path);
+	} catch (err) {
+		await unlink(tmp).catch(() => {});
+		throw err;
+	}
+}
+/** Has the throttle window elapsed since the last recorded check? */
+function isDueForCheck(cache, now = Date.now(), intervalMs = UPDATE_CHECK_INTERVAL_MS) {
+	if (!cache) return true;
+	const last = Date.parse(cache.lastCheckedAt);
+	if (!Number.isFinite(last)) return true;
+	if (now < last) return true;
+	return now - last >= intervalMs;
+}
+/**
+* Perform the throttled update check. Returns the final cache entry (for
+* testing) or null when skipped. Never throws — network errors are
+* intentionally swallowed so they never interrupt the foreground command.
+*/
+async function maybeCheckForUpdate(opts = {}) {
+	const env = opts.env ?? process.env;
+	const isTTY = opts.isTTY ?? Boolean(process.stderr.isTTY);
+	const now = opts.now ?? Date.now();
+	const intervalMs = opts.intervalMs ?? 864e5;
+	const optOut = env.AITCC_NO_UPDATE_CHECK;
+	if (optOut && optOut !== "0" && optOut.toLowerCase() !== "false") return null;
+	if (!isTTY) return null;
+	const cache = await readCache();
+	if (!isDueForCheck(cache, now, intervalMs)) return null;
+	const nowIso = new Date(now).toISOString();
+	const placeholder = {
+		lastCheckedAt: nowIso,
+		...cache?.latestTag !== void 0 ? { latestTag: cache.latestTag } : {},
+		...cache?.etag !== void 0 ? { etag: cache.etag } : {}
+	};
+	await writeCache(placeholder).catch(() => {});
+	const previousEtag = cache?.etag;
+	let entry = placeholder;
+	try {
+		const result = await fetchLatestReleaseConditional(previousEtag);
+		if (result.status === "not-modified") entry = {
+			lastCheckedAt: nowIso,
+			...cache?.latestTag !== void 0 ? { latestTag: cache.latestTag } : {},
+			...result.etag !== void 0 ? { etag: result.etag } : cache?.etag !== void 0 ? { etag: cache.etag } : {}
+		};
+		else entry = {
+			lastCheckedAt: nowIso,
+			latestTag: result.release.tag_name,
+			...result.etag !== void 0 ? { etag: result.etag } : {}
+		};
+		await writeCache(entry).catch(() => {});
+	} catch {}
+	maybeEmitNotice(entry, env);
+	return entry;
+}
+function maybeEmitNotice(entry, env) {
+	if (!entry.latestTag) return;
+	if (VERSION.startsWith("0.0.0-dev")) return;
+	const latest = versionFromTag(entry.latestTag);
+	if (!latest) return;
+	if (compareSemver(latest, VERSION) <= 0) return;
+	const dim = env.NO_COLOR ? "" : "\x1B[2m";
+	const reset = env.NO_COLOR ? "" : "\x1B[0m";
+	process.stderr.write(`\n${dim}(aitcc ${latest} is available — run \`aitcc upgrade\` to install)${reset}\n`);
+}
+//#endregion
 //#region src/commands/whoami.ts
+async function runBackgroundUpdateCheck(json) {
+	if (json) return;
+	const timeoutMs = 500;
+	await Promise.race([maybeCheckForUpdate().catch(() => null), new Promise((resolve) => {
+		const t = setTimeout(() => resolve(null), timeoutMs);
+		if (typeof t.unref === "function") t.unref();
+	})]);
+}
 const whoamiCommand = defineCommand({
 	meta: {
 		name: "whoami",
@@ -1182,6 +2374,7 @@ const whoamiCommand = defineCommand({
 			const label = session.user.displayName ? `${session.user.displayName} <${session.user.email}>` : session.user.email;
 			process.stdout.write(`Logged in as ${label} (cached)\n`);
 			process.stdout.write(`Session captured: ${session.capturedAt}\n`);
+			await runBackgroundUpdateCheck(args.json);
 			return exitAfterFlush(ExitCode.Ok);
 		}
 		try {
@@ -1212,6 +2405,7 @@ const whoamiCommand = defineCommand({
 				process.stdout.write("Workspaces:\n");
 				for (const w of info.workspaces) process.stdout.write(`  - ${w.workspaceName} (id ${w.workspaceId}, ${w.role})\n`);
 			}
+			await runBackgroundUpdateCheck(args.json);
 			return exitAfterFlush(ExitCode.Ok);
 		} catch (err) {
 			if (err instanceof TossApiError && err.isAuthError) {
@@ -1244,6 +2438,213 @@ const whoamiCommand = defineCommand({
 	}
 });
 //#endregion
+//#region src/api/workspaces.ts
+const WORKSPACES_BASE = "https://apps-in-toss.toss.im/console/api-public/v3/appsintossconsole";
+async function fetchWorkspaceDetail(workspaceId, cookies, opts = {}) {
+	const raw = await requestConsoleApi({
+		url: `${WORKSPACES_BASE}/workspaces/${workspaceId}`,
+		cookies,
+		...opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}
+	});
+	const id = raw.id;
+	const name = raw.name;
+	if (typeof id !== "number" || !Number.isInteger(id) || id <= 0 || typeof name !== "string") throw new Error(`Unexpected workspace detail shape for id=${workspaceId}`);
+	const { id: _id, name: _name, ...extra } = raw;
+	return {
+		workspaceId: id,
+		workspaceName: name,
+		extra
+	};
+}
+//#endregion
+//#region src/commands/workspace.ts
+function formatScalar(v) {
+	if (v === null) return "null";
+	if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") return String(v);
+	return JSON.stringify(v);
+}
+const workspaceCommand = defineCommand({
+	meta: {
+		name: "workspace",
+		description: "Inspect and switch between the workspaces this account can access."
+	},
+	subCommands: {
+		ls: defineCommand({
+			meta: {
+				name: "ls",
+				description: "List workspaces the current user has access to."
+			},
+			args: { json: {
+				type: "boolean",
+				description: "Emit machine-readable JSON to stdout.",
+				default: false
+			} },
+			async run({ args }) {
+				const session = await readSession();
+				if (!session) {
+					emitNotAuthenticated(args.json);
+					return exitAfterFlush(ExitCode.NotAuthenticated);
+				}
+				try {
+					const info = await fetchConsoleMemberUserInfo(session.cookies);
+					const current = session.currentWorkspaceId;
+					if (args.json) {
+						emitJson({
+							ok: true,
+							workspaces: info.workspaces.map((w) => ({
+								workspaceId: w.workspaceId,
+								workspaceName: w.workspaceName,
+								role: w.role,
+								current: w.workspaceId === current
+							}))
+						});
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					if (info.workspaces.length === 0) {
+						process.stdout.write("No workspaces.\n");
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					for (const w of info.workspaces) {
+						const marker = w.workspaceId === current ? "* " : "  ";
+						process.stdout.write(`${marker}${w.workspaceId}  ${w.workspaceName}  (${w.role})\n`);
+					}
+					if (current === void 0) process.stderr.write("No workspace selected. Run `aitcc workspace use <id>`.\n");
+					return exitAfterFlush(ExitCode.Ok);
+				} catch (err) {
+					return emitFailureFromError(args.json, err);
+				}
+			}
+		}),
+		use: defineCommand({
+			meta: {
+				name: "use",
+				description: "Select the current workspace by ID. Subsequent commands use this."
+			},
+			args: {
+				id: {
+					type: "positional",
+					description: "Workspace ID",
+					required: true
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON to stdout.",
+					default: false
+				}
+			},
+			async run({ args }) {
+				const raw = String(args.id);
+				const parsed = parsePositiveInt(raw);
+				if (parsed === null) {
+					const message = `workspace id must be a positive integer (got ${raw})`;
+					if (args.json) emitJson({
+						ok: false,
+						reason: "invalid-id",
+						message
+					});
+					else process.stderr.write(`${message}\n`);
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				const session = await readSession();
+				if (!session) {
+					emitNotAuthenticated(args.json);
+					return exitAfterFlush(ExitCode.NotAuthenticated);
+				}
+				try {
+					const match = (await fetchConsoleMemberUserInfo(session.cookies)).workspaces.find((w) => w.workspaceId === parsed);
+					if (!match) {
+						if (args.json) emitJson({
+							ok: false,
+							reason: "not-found",
+							workspaceId: parsed
+						});
+						else process.stderr.write(`Workspace ${parsed} is not accessible from this account. Run \`aitcc workspace ls\` to see available workspaces.\n`);
+						return exitAfterFlush(ExitCode.Usage);
+					}
+					if (await setCurrentWorkspaceId(parsed) === null) {
+						emitNotAuthenticated(args.json);
+						return exitAfterFlush(ExitCode.NotAuthenticated);
+					}
+					if (args.json) emitJson({
+						ok: true,
+						workspaceId: match.workspaceId,
+						workspaceName: match.workspaceName
+					});
+					else process.stdout.write(`Using workspace ${match.workspaceId} (${match.workspaceName}).\n`);
+					return exitAfterFlush(ExitCode.Ok);
+				} catch (err) {
+					return emitFailureFromError(args.json, err);
+				}
+			}
+		}),
+		show: defineCommand({
+			meta: {
+				name: "show",
+				description: "Show details of the selected workspace (or the one passed with --workspace)."
+			},
+			args: {
+				workspace: {
+					type: "string",
+					description: "Workspace ID to inspect. Defaults to the selected workspace."
+				},
+				json: {
+					type: "boolean",
+					description: "Emit machine-readable JSON to stdout.",
+					default: false
+				}
+			},
+			async run({ args }) {
+				const session = await readSession();
+				if (!session) {
+					emitNotAuthenticated(args.json);
+					return exitAfterFlush(ExitCode.NotAuthenticated);
+				}
+				let workspaceId;
+				if (args.workspace) {
+					const raw = String(args.workspace);
+					const parsed = parsePositiveInt(raw);
+					if (parsed === null) {
+						const message = `--workspace must be a positive integer (got ${raw})`;
+						if (args.json) emitJson({
+							ok: false,
+							reason: "invalid-id",
+							message
+						});
+						else process.stderr.write(`${message}\n`);
+						return exitAfterFlush(ExitCode.Usage);
+					}
+					workspaceId = parsed;
+				} else workspaceId = session.currentWorkspaceId;
+				if (workspaceId === void 0) {
+					if (args.json) emitJson({
+						ok: false,
+						reason: "no-workspace-selected"
+					});
+					else process.stderr.write("No workspace selected. Pass `--workspace <id>` or run `aitcc workspace use <id>`.\n");
+					return exitAfterFlush(ExitCode.Usage);
+				}
+				try {
+					const detail = await fetchWorkspaceDetail(workspaceId, session.cookies);
+					if (args.json) {
+						emitJson({
+							ok: true,
+							workspaceId: detail.workspaceId,
+							workspaceName: detail.workspaceName,
+							extra: detail.extra ?? {}
+						});
+						return exitAfterFlush(ExitCode.Ok);
+					}
+					process.stdout.write(`Workspace ${detail.workspaceId}: ${detail.workspaceName}\n`);
+					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) {
+					return emitFailureFromError(args.json, err);
+				}
+			}
+		})
+	}
+});
+//#endregion
 //#region src/cli.ts
 runMain(defineCommand({
 	meta: {
@@ -1255,7 +2656,11 @@ runMain(defineCommand({
 		whoami: whoamiCommand,
 		login: loginCommand,
 		logout: logoutCommand,
-		upgrade: upgradeCommand
+		upgrade: upgradeCommand,
+		workspace: workspaceCommand,
+		app: appCommand,
+		members: membersCommand,
+		keys: keysCommand
 	}
 }));
 //#endregion