@webmate-studio/cli 0.3.61 → 0.4.0

package/src/commands/dev.js

@@ -1,22 +1,10 @@
 import { startPreviewServer } from '@webmate-studio/preview';
 import { logger } from '@webmate-studio/core';
-import { isLoggedIn, loadAuth } from '../utils/auth.js';
-import pc from 'picocolors';
 
 /**
  * Dev command - start preview server
- * Login is optional - if logged in, design tokens will be loaded
  */
 export async function devCommand(options) {
-	// Check if logged in (optional)
-	if (isLoggedIn()) {
-		const auth = loadAuth();
-		logger.info(`Projekt: ${pc.cyan(auth.tenant.name)}`);
-	} else {
-		logger.info('Nicht eingeloggt - verwende Standard Design Tokens');
-		logger.info(`Tipp: ${pc.cyan('wm login')} um Design Tokens vom CMS zu laden`);
-	}
-
 	try {
 		await startPreviewServer(options);
 	} catch (error) {

package/src/commands/doctor.js

@@ -0,0 +1,192 @@
+/**
+ * `wm doctor` — scan the workspace for common setup issues and print a
+ * checklist with one-line fixes. Offline by design: every check works
+ * against local files only, so the command runs the same whether or
+ * not the user is logged in or has network access. Intended as the
+ * first thing to try when something feels off.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { resolve, join, basename } from 'path';
+import pc from 'picocolors';
+import { logger } from '@webmate-studio/core';
+import { readMeta } from '../utils/webmate-meta.js';
+import { readAuth } from '../utils/auth-storage.js';
+
+function readWorkspaceConfig(rootDir) {
+	const configPath = join(rootDir, '.webmate', 'config.json');
+	if (!existsSync(configPath)) return null;
+	try {
+		return JSON.parse(readFileSync(configPath, 'utf8'));
+	} catch {
+		return null;
+	}
+}
+
+function listComponentDirs(rootDir) {
+	const componentsDir = join(rootDir, 'components');
+	if (!existsSync(componentsDir)) return [];
+	if (!statSync(componentsDir).isDirectory()) return [];
+	return readdirSync(componentsDir)
+		.map((name) => join(componentsDir, name))
+		.filter((p) => {
+			let stat;
+			try { stat = statSync(p); } catch { return false; }
+			return stat.isDirectory() && existsSync(join(p, 'component.json'));
+		});
+}
+
+function check(label, status, hint = null) {
+	return { label, status, hint };
+}
+
+function runChecks(rootDir) {
+	const checks = [];
+	const wsConfig = readWorkspaceConfig(rootDir);
+	const workspaceRepoId = wsConfig?.repositoryId ?? null;
+
+	// 1. Authentication
+	const auth = readAuth();
+	if (!auth) {
+		checks.push(check('Authentifizierung', 'warn', 'Kein Login gefunden — führe `wm login` aus für Sync-Funktionen.'));
+	} else {
+		checks.push(check(`Authentifizierung (${auth.email ?? 'unknown'})`, 'ok'));
+	}
+
+	// 2. Workspace binding
+	if (!wsConfig) {
+		checks.push(check('Workspace-Bindung', 'warn', 'Kein .webmate/config.json — dieser Ordner ist kein gecloneter Workspace.'));
+	} else if (!workspaceRepoId) {
+		checks.push(check('Workspace-Bindung', 'warn', '.webmate/config.json ohne repositoryId — das Workspace ist an kein Projekt gebunden.'));
+	} else {
+		checks.push(check(`Workspace gebunden an ${wsConfig.repositoryName ?? workspaceRepoId}`, 'ok'));
+	}
+
+	// 3. Component dirs sanity
+	const componentDirs = listComponentDirs(rootDir);
+	if (componentDirs.length === 0) {
+		checks.push(check('Komponenten', 'warn', 'Kein components/-Unterordner mit component.json gefunden.'));
+		return checks;
+	}
+	checks.push(check(`${componentDirs.length} Komponente(n) gefunden`, 'ok'));
+
+	// 4. Foreign-origin metas (the classic copy-from-other-workspace case)
+	let foreignOrigin = 0;
+	let staleNoOrigin = 0;
+	let unlinked = 0;
+	for (const dir of componentDirs) {
+		const meta = readMeta(dir);
+		if (!meta) {
+			unlinked++;
+			continue;
+		}
+		if (!meta.baseVersion) continue;
+		if (meta.originRepositoryId && workspaceRepoId && meta.originRepositoryId !== workspaceRepoId) {
+			foreignOrigin++;
+		} else if (!meta.originRepositoryId) {
+			// Legacy meta — we can't be sure if it's stale; only flag as
+			// suspicious, not as an error.
+			staleNoOrigin++;
+		}
+	}
+	if (foreignOrigin > 0) {
+		checks.push(
+			check(
+				`${foreignOrigin} Komponente(n) zeigen auf ein anderes Projekt`,
+				'error',
+				`Führe \`wm reset\` aus, um die Sync-Pointer für dieses Workspace zurückzusetzen.`
+			)
+		);
+	}
+	if (unlinked > 0) {
+		checks.push(
+			check(
+				`${unlinked} Komponente(n) ohne .webmate.json`,
+				'warn',
+				`Führe \`wm reset\` aus, um sie als „neu" zu adoptieren.`
+			)
+		);
+	}
+	if (foreignOrigin === 0 && unlinked === 0 && staleNoOrigin > 0) {
+		checks.push(
+			check(
+				`${staleNoOrigin} Komponente(n) ohne Origin-Stempel`,
+				'info',
+				`Alter Meta-Stand. Beim nächsten Push wird das Feld nachgetragen.`
+			)
+		);
+	}
+
+	// 5. component.json integrity
+	const dupIds = new Map();
+	const missingIds = [];
+	for (const dir of componentDirs) {
+		const componentJsonPath = join(dir, 'component.json');
+		try {
+			const data = JSON.parse(readFileSync(componentJsonPath, 'utf8'));
+			if (!data?.id) {
+				missingIds.push(basename(dir));
+			} else {
+				const list = dupIds.get(data.id) ?? [];
+				list.push(basename(dir));
+				dupIds.set(data.id, list);
+			}
+		} catch {
+			missingIds.push(basename(dir));
+		}
+	}
+	if (missingIds.length > 0) {
+		checks.push(
+			check(
+				`${missingIds.length} component.json ohne id`,
+				'error',
+				`Betroffen: ${missingIds.join(', ')}. Jede Komponente braucht eine UUID/CUID im id-Feld.`
+			)
+		);
+	}
+	const dups = [...dupIds.entries()].filter(([, list]) => list.length > 1);
+	if (dups.length > 0) {
+		const lines = dups.map(([id, list]) => `  ${pc.dim(id.slice(0, 8) + '…')}: ${list.join(' / ')}`).join('\n');
+		checks.push(
+			check(
+				`${dups.length} component.json-id mehrfach vergeben`,
+				'error',
+				`Doppelte IDs lassen Pushes silent überschreiben. Vergib neue UUIDs:\n${lines}`
+			)
+		);
+	}
+
+	return checks;
+}
+
+const DOT = {
+	ok: pc.green('●'),
+	warn: pc.yellow('●'),
+	error: pc.red('●'),
+	info: pc.cyan('●')
+};
+
+export async function doctorCommand(dirArg) {
+	const rootDir = resolve(process.cwd(), dirArg ?? '.');
+	if (!existsSync(rootDir)) {
+		logger.error(`Directory not found: ${rootDir}`);
+		process.exit(1);
+	}
+
+	const checks = runChecks(rootDir);
+	console.log();
+	console.log(`  ${pc.bold('wm doctor')} — ${pc.dim(rootDir)}`);
+	console.log();
+	for (const c of checks) {
+		console.log(`  ${DOT[c.status]}  ${c.label}`);
+		if (c.hint) {
+			for (const line of c.hint.split('\n')) {
+				console.log(`     ${pc.gray(line)}`);
+			}
+		}
+	}
+	console.log();
+
+	const hasError = checks.some((c) => c.status === 'error');
+	if (hasError) process.exit(1);
+}

package/src/commands/install.js

@@ -0,0 +1,312 @@
+import { existsSync, readFileSync, readdirSync, statSync, rmSync } from 'fs';
+import { join } from 'path';
+import { spawn } from 'child_process';
+import { loadConfig, logger } from '@webmate-studio/core';
+import { confirm } from '@inquirer/prompts';
+import pc from 'picocolors';
+
+/**
+ * `wm install` — installs npm dependencies for the project root and every
+ * component that ships its own package.json. Skips paths that already have
+ * a node_modules folder unless --force is passed. After all targets have
+ * been processed, prints a summary table showing what was added vs. left
+ * untouched, so component-heavy projects don't drown in npm chatter.
+ *
+ * Why this exists: the build service runs `npm install` per component as
+ * part of the build, but the preview server can't bundle islands whose
+ * imports come from those un-installed dependencies. This brings the
+ * preview into parity with the build service.
+ */
+export async function installCommand(options = {}) {
+	const cwd = process.cwd();
+	const force = !!options.force;
+	const prune = !!options.prune;
+
+	const config = await loadConfig().catch(() => null);
+	const componentsPath = config?.components?.path || 'components';
+	const componentsDir = join(cwd, componentsPath);
+
+	if (prune) {
+		const result = await runPrune(cwd, componentsDir);
+		if (result === 'aborted') return;
+		process.stdout.write('\n');
+	}
+
+	const targets = [];
+	let emptyPackageCount = 0;
+	if (existsSync(join(cwd, 'package.json'))) {
+		if (readDepCount(cwd) > 0) targets.push({ label: 'project root', dir: cwd });
+		else emptyPackageCount++;
+	}
+	if (existsSync(componentsDir)) {
+		for (const entry of readdirSync(componentsDir)) {
+			const componentDir = join(componentsDir, entry);
+			let stat;
+			try { stat = statSync(componentDir); } catch { continue; }
+			if (!stat.isDirectory()) continue;
+			const pkg = join(componentDir, 'package.json');
+			if (!existsSync(pkg)) continue;
+			// Skip empty package.json files (no dependencies/devDependencies).
+			// `wm generate` and `wm init` emit a stub package.json by default —
+			// running npm install in them just creates noisy empty lockfiles.
+			if (readDepCount(componentDir) === 0) {
+				emptyPackageCount++;
+				continue;
+			}
+			targets.push({ label: `components/${entry}`, dir: componentDir });
+		}
+	}
+
+	if (targets.length === 0) {
+		if (emptyPackageCount > 0) {
+			logger.info(`Found ${emptyPackageCount} package.json file${emptyPackageCount === 1 ? '' : 's'} but none with dependencies — nothing to install.`);
+		} else {
+			logger.info('No package.json found in project root or any component directory.');
+		}
+		return;
+	}
+
+	const targetLine = `Found ${pc.cyan(targets.length)} package.json file${targets.length === 1 ? '' : 's'} with dependencies`;
+	const skipLine = emptyPackageCount > 0 ? pc.gray(` (skipped ${emptyPackageCount} empty)`) : '';
+	logger.info(targetLine + skipLine + '.');
+
+	const results = [];
+
+	for (const target of targets) {
+		const nodeModules = join(target.dir, 'node_modules');
+		const depCount = readDepCount(target.dir);
+
+		if (!force && existsSync(nodeModules)) {
+			results.push({ label: target.label, status: 'skipped', depCount, added: 0, removed: 0, durationMs: 0, error: null });
+			printRow(target.label, 'skipped', '—');
+			continue;
+		}
+
+		const start = Date.now();
+		try {
+			const output = await runNpmInstall(target.dir);
+			const durationMs = Date.now() - start;
+			const { added, removed, upToDate } = parseNpmOutput(output);
+			const status = upToDate ? 'up-to-date' : (added > 0 ? 'added' : 'installed');
+			results.push({ label: target.label, status, depCount, added, removed, durationMs, error: null });
+			printRow(target.label, status, formatChange(added, removed, durationMs));
+		} catch (err) {
+			const durationMs = Date.now() - start;
+			results.push({ label: target.label, status: 'failed', depCount, added: 0, removed: 0, durationMs, error: err.message });
+			printRow(target.label, 'failed', err.message);
+		}
+	}
+
+	printSummary(results);
+
+	maybePrintCopiedComponentsHint(componentsDir);
+
+	if (results.some(r => r.status === 'failed')) process.exit(1);
+}
+
+/**
+ * After a fresh install, look for the telltale sign of a workspace seeded
+ * by copying components from somewhere else: `.webmate.json` files that
+ * already carry a baseVersion pointing at a different project's CMS. The
+ * preview-server status scanner would then mark them as "Im CMS gelöscht",
+ * which is misleading. Suggest `wm reset` so the user knows the fix
+ * exists without having to discover it by accident.
+ *
+ * The hint is intentionally a soft suggestion, not a hard claim — we
+ * can't tell offline whether the baseVersion is legitimately pointing
+ * at this workspace's CMS or at a foreign one.
+ */
+function maybePrintCopiedComponentsHint(componentsDir) {
+	if (!existsSync(componentsDir)) return;
+	let pinned = 0;
+	for (const entry of readdirSync(componentsDir)) {
+		const metaPath = join(componentsDir, entry, '.webmate.json');
+		if (!existsSync(metaPath)) continue;
+		try {
+			const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+			if (meta?.baseVersion) pinned++;
+		} catch {
+			// ignore malformed metas — they'll surface elsewhere
+		}
+	}
+	if (pinned === 0) return;
+
+	process.stdout.write(
+		'  ' + pc.cyan('ℹ') + ` ${pc.gray('Falls du Komponenten aus einem anderen Workspace kopiert hast,')}` + '\n' +
+		'  ' + '  ' + pc.gray(`führe ${pc.bold('wm reset')} aus, um veraltete Sync-Pointer zurückzusetzen.`) + '\n\n'
+	);
+}
+
+/**
+ * Walk project root + components looking for stub package.json files
+ * (no dependencies / devDependencies) that nonetheless have a
+ * package-lock.json or node_modules/ sitting next to them — left
+ * behind by an earlier `wm install` before the stub-filter landed.
+ *
+ * The package.json itself is left in place so the user's later
+ * `npm install <pkg>` works against it. Only the lockfile and
+ * node_modules/ are removed, with explicit confirmation.
+ */
+async function runPrune(cwd, componentsDir) {
+	const candidates = [];
+	const scan = (dir, label) => {
+		if (!existsSync(join(dir, 'package.json'))) return;
+		if (readDepCount(dir) !== 0) return;
+		const hasLock = existsSync(join(dir, 'package-lock.json'));
+		const hasNm = existsSync(join(dir, 'node_modules'));
+		if (!hasLock && !hasNm) return;
+		candidates.push({ label, dir, hasLock, hasNm });
+	};
+
+	scan(cwd, 'project root');
+	if (existsSync(componentsDir)) {
+		for (const entry of readdirSync(componentsDir)) {
+			const componentDir = join(componentsDir, entry);
+			let stat;
+			try { stat = statSync(componentDir); } catch { continue; }
+			if (!stat.isDirectory()) continue;
+			scan(componentDir, `components/${entry}`);
+		}
+	}
+
+	if (candidates.length === 0) {
+		logger.info('Nothing to prune — no leftover lockfiles or node_modules under stub package.json files.');
+		return 'nothing';
+	}
+
+	logger.info(`Found ${pc.cyan(candidates.length)} stub package.json file${candidates.length === 1 ? '' : 's'} with leftover artefacts:`);
+	for (const c of candidates) {
+		const parts = [];
+		if (c.hasLock) parts.push('package-lock.json');
+		if (c.hasNm) parts.push('node_modules/');
+		const truncated = c.label.length > LABEL_COL ? c.label.slice(0, LABEL_COL - 1) + '…' : c.label.padEnd(LABEL_COL);
+		process.stdout.write(`  ${pc.gray('•')}  ${truncated}  ${pc.gray(parts.join(' + '))}\n`);
+	}
+	process.stdout.write(`  ${pc.gray('package.json itself is kept so future `npm install <pkg>` works.')}\n\n`);
+
+	const ok = await confirm({
+		message: `Delete these from ${candidates.length} ${candidates.length === 1 ? 'directory' : 'directories'}?`,
+		default: false
+	});
+
+	if (!ok) {
+		logger.info('Prune aborted.');
+		return 'aborted';
+	}
+
+	for (const c of candidates) {
+		try {
+			if (c.hasLock) rmSync(join(c.dir, 'package-lock.json'), { force: true });
+			if (c.hasNm) rmSync(join(c.dir, 'node_modules'), { recursive: true, force: true });
+			process.stdout.write(`  ${pc.green('✓')}  ${c.label}\n`);
+		} catch (err) {
+			process.stdout.write(`  ${pc.red('✗')}  ${c.label}  ${pc.gray(err.message)}\n`);
+		}
+	}
+	return 'done';
+}
+
+function readDepCount(dir) {
+	try {
+		const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+		return Object.keys(pkg.dependencies || {}).length + Object.keys(pkg.devDependencies || {}).length;
+	} catch {
+		return 0;
+	}
+}
+
+function runNpmInstall(cwd) {
+	return new Promise((resolve, reject) => {
+		const child = spawn('npm', ['install', '--no-audit', '--no-fund', '--loglevel=error'], {
+			cwd,
+			stdio: ['ignore', 'pipe', 'pipe'],
+			shell: process.platform === 'win32'
+		});
+		let stdout = '';
+		let stderr = '';
+		child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+		child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+		child.on('error', reject);
+		child.on('close', (code) => {
+			if (code === 0) resolve(stdout);
+			else reject(new Error(stderr.trim().split('\n')[0] || `npm install exited with code ${code}`));
+		});
+	});
+}
+
+function parseNpmOutput(stdout) {
+	const added = (stdout.match(/added (\d+) packages?/) || [, 0])[1];
+	const removed = (stdout.match(/removed (\d+) packages?/) || [, 0])[1];
+	const upToDate = /up to date/.test(stdout) && Number(added) === 0;
+	return { added: Number(added), removed: Number(removed), upToDate };
+}
+
+function formatChange(added, removed, durationMs) {
+	const parts = [];
+	if (added) parts.push(`+${added}`);
+	if (removed) parts.push(`-${removed}`);
+	if (parts.length === 0) parts.push('no change');
+	parts.push(pc.gray(`${durationMs}ms`));
+	return parts.join(' ');
+}
+
+const LABEL_COL = 38;
+
+function printRow(label, status, detail) {
+	const dot = STATUS_DOT[status] || pc.gray('•');
+	const truncated = label.length > LABEL_COL ? label.slice(0, LABEL_COL - 1) + '…' : label.padEnd(LABEL_COL);
+	const coloredStatus = colorStatus(status).padEnd(12);
+	process.stdout.write(`  ${dot}  ${truncated}  ${coloredStatus}  ${detail}\n`);
+}
+
+const STATUS_DOT = {
+	'added':       pc.green('●'),
+	'installed':   pc.green('●'),
+	'up-to-date':  pc.gray('●'),
+	'skipped':     pc.gray('○'),
+	'failed':      pc.red('●')
+};
+
+function colorStatus(status) {
+	switch (status) {
+		case 'added':      return pc.green('added');
+		case 'installed':  return pc.green('installed');
+		case 'up-to-date': return pc.gray('up-to-date');
+		case 'skipped':    return pc.gray('skipped');
+		case 'failed':     return pc.red('failed');
+		default:           return status;
+	}
+}
+
+function printSummary(results) {
+	const added       = results.filter(r => r.status === 'added').length;
+	const installed   = results.filter(r => r.status === 'installed').length;
+	const upToDate    = results.filter(r => r.status === 'up-to-date').length;
+	const skipped     = results.filter(r => r.status === 'skipped').length;
+	const failed     = results.filter(r => r.status === 'failed').length;
+	const totalAdded  = results.reduce((s, r) => s + r.added, 0);
+	const totalRemoved = results.reduce((s, r) => s + r.removed, 0);
+
+	process.stdout.write('\n');
+	const parts = [];
+	if (added + installed)   parts.push(pc.green(`${added + installed} installed`));
+	if (upToDate)           parts.push(pc.gray(`${upToDate} up-to-date`));
+	if (skipped)            parts.push(pc.gray(`${skipped} skipped`));
+	if (failed)             parts.push(pc.red(`${failed} failed`));
+	process.stdout.write('  ' + parts.join('  ·  ') + '\n');
+
+	if (totalAdded || totalRemoved) {
+		const change = [];
+		if (totalAdded)   change.push(pc.green(`+${totalAdded} packages`));
+		if (totalRemoved) change.push(pc.yellow(`-${totalRemoved} packages`));
+		process.stdout.write('  ' + change.join('  ·  ') + '\n');
+	}
+
+	if (failed > 0) {
+		process.stdout.write('\n  ' + pc.red('Failed targets:') + '\n');
+		for (const r of results.filter(x => x.status === 'failed')) {
+			process.stdout.write(`    ${pc.red(r.label)}  ${pc.gray(r.error)}\n`);
+		}
+	}
+	process.stdout.write('\n');
+}

package/src/commands/login.js

@@ -0,0 +1,158 @@
+import { confirm } from '@inquirer/prompts';
+import { exec } from 'child_process';
+import ora from 'ora';
+import { logger } from '@webmate-studio/core';
+import pc from 'picocolors';
+import { writeAuth, getAuthFilePath, readAuth } from '../utils/auth-storage.js';
+import { apiFetch, ApiError } from '../utils/api-client.js';
+import { getDefaultBaseUrl } from '../utils/auth-resolver.js';
+import { startDeviceAuthorization, pollForDeviceToken, DeviceFlowError } from '../utils/device-flow.js';
+
+function openInBrowser(url) {
+	const platform = process.platform;
+	const cmd =
+		platform === 'darwin' ? `open "${url}"`
+		: platform === 'win32' ? `start "" "${url}"`
+		: `xdg-open "${url}"`;
+	exec(cmd, () => {});
+}
+
+async function validateAndFetchIdentity({ token, baseUrl }) {
+	const me = await apiFetch('/api/auth/me', { token, baseUrl });
+	const user = me?.data ?? me?.user ?? me;
+	return {
+		userId: user?.id ?? null,
+		email: user?.email ?? null,
+		organizationId: user?.organizationId ?? null,
+		organizationSlug: user?.organizationSlug ?? null,
+		firstName: user?.firstName ?? null,
+		lastName: user?.lastName ?? null
+	};
+}
+
+async function loginViaDeviceFlow(baseUrl) {
+	const init = ora('Requesting device code from Webmate…').start();
+	let authz;
+	try {
+		authz = await startDeviceAuthorization(baseUrl);
+		init.succeed('Device code received.');
+	} catch (err) {
+		init.fail(`Could not reach ${baseUrl}: ${err.message}`);
+		process.exit(1);
+	}
+
+	const { userCode, verificationUrl, expiresIn, pollInterval } = authz;
+
+	console.log();
+	console.log(pc.bold('  Open this URL in your browser to authorize:'));
+	console.log(`  ${pc.cyan(verificationUrl)}`);
+	console.log();
+	console.log(`  Verification code: ${pc.bold(pc.yellow(userCode))}`);
+	console.log(pc.dim(`  (Expires in ${Math.round(expiresIn / 60)} minutes)`));
+	console.log();
+
+	openInBrowser(verificationUrl);
+
+	const spinner = ora('Waiting for browser authorization…').start();
+
+	let result;
+	try {
+		result = await pollForDeviceToken(baseUrl, userCode, {
+			intervalSeconds: pollInterval,
+			expiresInSeconds: expiresIn,
+			onTick: (tick) => {
+				if (tick.status === 'network-error') {
+					spinner.text = `Waiting for browser authorization… (transient network error, retrying)`;
+				}
+			}
+		});
+		spinner.succeed('Authorization approved.');
+	} catch (err) {
+		if (err instanceof DeviceFlowError) {
+			spinner.fail(err.message);
+		} else {
+			spinner.fail(`Unexpected error: ${err.message}`);
+		}
+		process.exit(1);
+	}
+
+	return {
+		token: result.token,
+		email: result.user?.email ?? null,
+		userId: result.user?.id ?? null,
+		firstName: result.user?.firstName ?? null,
+		lastName: result.user?.lastName ?? null,
+		organizationId: result.organization?.id ?? null,
+		organizationSlug: result.organization?.slug ?? null
+	};
+}
+
+async function loginViaToken({ token, baseUrl }) {
+	const spinner = ora('Validating token…').start();
+	let identity;
+	try {
+		identity = await validateAndFetchIdentity({ token, baseUrl });
+		spinner.succeed('Token accepted.');
+	} catch (err) {
+		if (err instanceof ApiError) {
+			spinner.fail(`Token rejected by ${baseUrl} (HTTP ${err.status}): ${err.message}`);
+		} else {
+			spinner.fail(`Could not reach ${baseUrl}: ${err.message}`);
+		}
+		process.exit(1);
+	}
+	return { token, ...identity };
+}
+
+export async function loginCommand(options = {}) {
+	const existing = readAuth();
+	if (existing && !options.force) {
+		const overwrite = await confirm({
+			message: `Already logged in as ${pc.cyan(existing.email ?? existing.userId ?? 'unknown')} at ${pc.dim(existing.baseUrl)}. Overwrite?`,
+			default: false
+		});
+		if (!overwrite) {
+			logger.info('Login cancelled.');
+			return;
+		}
+	}
+
+	let baseUrl;
+	let baseUrlNote = null;
+	if (options.baseUrl) {
+		baseUrl = options.baseUrl;
+	} else {
+		const resolved = getDefaultBaseUrl();
+		baseUrl = resolved.baseUrl;
+		if (resolved.source === 'workspace') {
+			baseUrlNote = `using baseUrl from ${resolved.path}`;
+		} else if (resolved.source === 'env') {
+			baseUrlNote = 'using WEBMATE_BASE_URL environment variable';
+		}
+	}
+	baseUrl = baseUrl.replace(/\/+$/, '');
+	if (baseUrlNote) {
+		console.log(pc.dim(`  ${baseUrlNote}`));
+	}
+
+	const session = options.token
+		? await loginViaToken({ token: options.token, baseUrl })
+		: await loginViaDeviceFlow(baseUrl);
+
+	const saved = writeAuth({
+		baseUrl,
+		token: session.token,
+		userId: session.userId,
+		email: session.email,
+		organizationId: session.organizationId,
+		organizationSlug: session.organizationSlug
+	});
+
+	const who = session.email ?? session.userId ?? 'unknown user';
+	logger.success(`Logged in as ${pc.cyan(who)}`);
+	console.log(`  Base URL: ${pc.dim(saved.baseUrl)}`);
+	if (session.organizationId) {
+		console.log(`  Organization: ${pc.dim(session.organizationSlug ?? session.organizationId)}`);
+	}
+	console.log(`  Stored in: ${pc.dim(getAuthFilePath())}`);
+}