@ait-co/console-cli 0.1.4 → 0.1.5

package/dist/cli.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from "citty";
-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";
+import { homedir, tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
 //#region src/api/http.ts
 var TossApiError = class extends Error {
 	constructor(status, errorCode, reason, errorType) {
@@ -143,6 +143,483 @@ 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;
+		})
+	};
+}
+//#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) {
+	if (json) emitJson({
+		ok: false,
+		reason: "api-error",
+		message
+	});
+	else process.stderr.write(`Unexpected error: ${message}\n`);
+}
+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/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) {
+				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);
+			}
+		}
+	}) }
+});
+//#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) {
+				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);
+			}
+		}
+	}) }
+});
+//#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 +996,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 +1157,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 +1283,105 @@ 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) {
+				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);
+			}
+		}
+	}) }
+});
+//#endregion
 //#region src/github.ts
 const REPO_OWNER = "apps-in-toss-community";
 const REPO_NAME = "console-cli";
@@ -921,6 +1401,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 +1494,7 @@ function resolveVersion() {
 		if (typeof injected === "string" && injected.length > 0) return injected;
 	} catch {}
 	try {
-		return "0.1.4";
+		return "0.1.5";
 	} catch {}
 	return "0.0.0-dev";
 }
@@ -1137,7 +1640,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 +1791,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 +1822,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 +1855,240 @@ 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) {
+					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);
+				}
+			}
+		}),
+		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) {
+					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);
+				}
+			}
+		}),
+		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) {
+					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);
+				}
+			}
+		})
+	}
+});
+//#endregion
 //#region src/cli.ts
 runMain(defineCommand({
 	meta: {
@@ -1255,7 +2100,11 @@ runMain(defineCommand({
 		whoami: whoamiCommand,
 		login: loginCommand,
 		logout: logoutCommand,
-		upgrade: upgradeCommand
+		upgrade: upgradeCommand,
+		workspace: workspaceCommand,
+		app: appCommand,
+		members: membersCommand,
+		keys: keysCommand
 	}
 }));
 //#endregion