@webmate-studio/cli 0.3.61 → 0.4.0

package/src/commands/core.js

@@ -0,0 +1,1039 @@
+/**
+ * `wm core` — SuperAdmin-only commands for authoring global Core Components.
+ *
+ * Subcommands:
+ *   wm core ls                 list all Core components
+ *   wm core clone <name>       pull source.json into the local directory
+ *   wm core clone (no arg)     clone every Core component into a workspace
+ *   wm core init [dir]         register a new Core record from local component.json
+ *   wm core init-all [dir]     bulk: init + push every subfolder of dir/components
+ *   wm core attach <name>      bind an existing (UI-created) server record to the local folder
+ *   wm core push [dir]         build + push a new version (or bulk from workspace root)
+ *   wm core status [name]      workspace overview or single-component info
+ *
+ * Targets /api/admin/core-components/... — auth is the same JWT/wms_-token
+ * flow as the org commands. The server rejects non-SuperAdmin callers, so
+ * non-platform users never accidentally hit a publish path.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'fs';
+import { basename, dirname, join, resolve } from 'path';
+import { confirm } from '@inquirer/prompts';
+import ora from 'ora';
+import pc from 'picocolors';
+import { logger } from '@webmate-studio/core';
+import { apiFetch, ApiError } from '../utils/api-client.js';
+import { readMeta, writeMeta } from '../utils/webmate-meta.js';
+import {
+	readComponentFiles,
+	writeComponentFiles,
+	computeFileHashesFromMap,
+	diffHashes,
+	getComponentId
+} from '../utils/component-files.js';
+import { autoSnapshot } from '../utils/git-snapshot.js';
+
+function resolveDir(arg) {
+	return arg ? resolve(process.cwd(), arg) : process.cwd();
+}
+
+function slugify(value) {
+	return (value || '')
+		.toString()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '');
+}
+
+const DEFAULT_WM_CONFIG = `export default {
+	components: {
+		path: './components',
+		styles: ['./tokens/tokens.css', './styles/base.css'],
+		fonts: [],
+		islands: {
+			path: './islands',
+			framework: 'lit'
+		}
+	},
+	preview: {
+		port: 5173,
+		theme: 'light',
+		viewport: { width: 1440, height: 900 }
+	}
+};
+`;
+
+/**
+ * Walk up from `start` toward the filesystem root looking for a
+ * `.webmate/config.json` that carries `coreWorkspace: true`. Used by
+ * `wm core push` / `wm core status` (no-arg) to detect that we are
+ * inside a bulk Core workspace and should iterate over every
+ * components/* subfolder instead of treating cwd as the component root.
+ */
+function findEnclosingCoreWorkspace(start) {
+	let dir = start;
+	while (true) {
+		const cfg = join(dir, '.webmate', 'config.json');
+		if (existsSync(cfg)) {
+			try {
+				const data = JSON.parse(readFileSync(cfg, 'utf-8'));
+				if (data && data.coreWorkspace === true) {
+					return { root: dir, config: data };
+				}
+			} catch {
+				/* malformed config — keep walking */
+			}
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+function listComponentSubfolders(workspaceRoot) {
+	const componentsDir = join(workspaceRoot, 'components');
+	if (!existsSync(componentsDir)) return [];
+	return readdirSync(componentsDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+		.map((d) => ({
+			name: d.name,
+			absPath: join(componentsDir, d.name)
+		}))
+		.filter((entry) => existsSync(join(entry.absPath, 'component.json')));
+}
+
+async function findCoreByName(name) {
+	const list = await apiFetch('/api/admin/core-components');
+	const components = list?.components ?? [];
+	return components.find((c) => c.name === name) ?? null;
+}
+
+/**
+ * Rewrite the local component.json's `id` (and optionally `name`) so it
+ * matches the server-assigned Core record. Without this the local source
+ * keeps its old UUID, which then disagrees with what the server stores
+ * and what `wm core clone` patches back on download. Called by both
+ * `init` and `attach`.
+ */
+function syncComponentJsonId(rootDir, { id, name }) {
+	const componentJsonPath = join(rootDir, 'component.json');
+	if (!existsSync(componentJsonPath)) return false;
+	let data;
+	try {
+		data = JSON.parse(readFileSync(componentJsonPath, 'utf-8'));
+	} catch {
+		return false;
+	}
+	let changed = false;
+	if (id && data.id !== id) {
+		data.id = id;
+		changed = true;
+	}
+	if (name && data.name !== name) {
+		data.name = name;
+		changed = true;
+	}
+	if (changed) {
+		writeFileSync(componentJsonPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+	}
+	return changed;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// wm core ls
+// ────────────────────────────────────────────────────────────────────────────
+
+export async function coreListCommand() {
+	let list;
+	try {
+		list = await apiFetch('/api/admin/core-components');
+	} catch (err) {
+		if (err instanceof ApiError && err.status === 403) {
+			logger.error('SuperAdmin permissions required. Are you logged in as a platform owner?');
+			process.exit(1);
+		}
+		logger.error(err.message);
+		process.exit(1);
+	}
+
+	const components = list?.components ?? [];
+	if (components.length === 0) {
+		logger.info('No Core components registered yet.');
+		return;
+	}
+
+	console.log();
+	console.log(pc.bold(`Core components (${components.length}):`));
+	console.log();
+	for (const c of components) {
+		const featured = c.featured ? pc.yellow(' ★') : '';
+		const inactive = c.active ? '' : pc.dim(' [inactive]');
+		const usage = c.usageCount > 0 ? pc.dim(` · used by ${c.usageCount}`) : '';
+		console.log(
+			`  ${pc.cyan(c.name.padEnd(28))} ${pc.dim('v' + (c.currentVersion || '—').padEnd(8))} ` +
+			`${(c.category || '—').padEnd(14)} ${c.displayName}${featured}${inactive}${usage}`
+		);
+	}
+	console.log();
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// wm core clone <name>
+// ────────────────────────────────────────────────────────────────────────────
+
+export async function coreCloneCommand(name, options = {}) {
+	if (!name) {
+		// No name → workspace mode: clone every Core component into a workspace
+		// skeleton, parallel to `wm clone <project>` for org repos.
+		return coreCloneWorkspaceCommand(options);
+	}
+
+	const targetDir = resolveDir(options.to);
+
+	if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !options.force) {
+		const proceed = await confirm({
+			message: `Target ${pc.cyan(targetDir)} is not empty. Continue and overwrite?`,
+			default: false
+		});
+		if (!proceed) {
+			logger.info('Clone cancelled.');
+			return;
+		}
+	}
+
+	const lookup = ora(`Resolving "${name}"…`).start();
+	let core;
+	try {
+		core = await findCoreByName(name);
+	} catch (err) {
+		lookup.fail(err.message);
+		process.exit(1);
+	}
+	if (!core) {
+		lookup.fail(`No Core component named "${name}" found.`);
+		process.exit(1);
+	}
+	lookup.succeed(`Found ${pc.cyan(core.name)} ${pc.dim('(' + core.id + ')')}`);
+
+	const downloadSpinner = ora('Downloading source…').start();
+	let payload;
+	try {
+		payload = await apiFetch(`/api/admin/core-components/${core.id}/files`);
+	} catch (err) {
+		if (err instanceof ApiError && err.status === 409 && err.body?.legacy) {
+			downloadSpinner.fail('Legacy ZIP-source — clone from webmate-premium-components and re-push.');
+		} else if (err instanceof ApiError && err.status === 404) {
+			downloadSpinner.fail('No published version yet. Use `wm core init` from a local copy and push first.');
+		} else {
+			downloadSpinner.fail(err.message);
+		}
+		process.exit(1);
+	}
+
+	const files = payload?.files ?? {};
+	if (Object.keys(files).length === 0) {
+		downloadSpinner.fail('Server returned no files.');
+		process.exit(1);
+	}
+	downloadSpinner.succeed(`Downloaded ${Object.keys(files).length} file(s) (v${payload.version})`);
+
+	writeComponentFiles(targetDir, files, { clean: !options.merge });
+	const fileHashes = computeFileHashesFromMap(files);
+
+	writeMeta(targetDir, {
+		componentId: core.id,
+		// Pin to the version we actually pulled so the gallery shows the
+		// component as in-sync, not "Neu"/never-pushed.
+		baseVersion: payload.versionId ?? null,
+		version: payload.version,
+		pulledAt: new Date().toISOString(),
+		fileHashes
+	});
+
+	logger.success(`Cloned ${pc.cyan(core.name)} into ${pc.dim(targetDir)}`);
+	console.log(`  Files:  ${pc.dim(Object.keys(files).length + ' file(s)')}`);
+	console.log(`  Edit, then run ${pc.bold('wm core push')} from this directory.`);
+}
+
+/**
+ * wm core clone (no arg) — clones every Core component into a fresh
+ * workspace folder. Mirrors `wm clone <project>` for org repos.
+ */
+async function coreCloneWorkspaceCommand(options = {}) {
+	const dirName = options.to || 'webmate-core';
+	const targetDir = resolve(process.cwd(), dirName);
+
+	if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !options.force) {
+		const proceed = await confirm({
+			message: `Target ${pc.cyan(targetDir)} is not empty. Continue?`,
+			default: false
+		});
+		if (!proceed) {
+			logger.info('Clone cancelled.');
+			return;
+		}
+	}
+
+	const listSpinner = ora('Listing Core components…').start();
+	let components;
+	try {
+		const res = await apiFetch('/api/admin/core-components');
+		components = Array.isArray(res?.components) ? res.components : [];
+		listSpinner.succeed(`Found ${pc.cyan(components.length)} Core component(s)`);
+	} catch (err) {
+		if (err instanceof ApiError && err.status === 403) {
+			listSpinner.fail('SuperAdmin permissions required.');
+		} else {
+			listSpinner.fail(err.message);
+		}
+		process.exit(1);
+	}
+
+	// Workspace skeleton — mirrors cloneProjectCommand layout so `wm dev`
+	// works identically. The `coreWorkspace: true` flag in
+	// .webmate/config.json is the marker used by findEnclosingCoreWorkspace.
+	mkdirSync(targetDir, { recursive: true });
+	mkdirSync(join(targetDir, 'components'), { recursive: true });
+
+	const configPath = join(targetDir, 'wm.config.js');
+	if (!existsSync(configPath)) {
+		writeFileSync(configPath, DEFAULT_WM_CONFIG, 'utf-8');
+	}
+
+	const dotWebmateDir = join(targetDir, '.webmate');
+	mkdirSync(dotWebmateDir, { recursive: true });
+	writeFileSync(
+		join(dotWebmateDir, 'config.json'),
+		JSON.stringify(
+			{
+				coreWorkspace: true,
+				componentsPath: './components',
+				clonedAt: new Date().toISOString()
+			},
+			null,
+			2
+		) + '\n',
+		'utf-8'
+	);
+
+	logger.success(`Workspace scaffolded at ${pc.dim(targetDir)}`);
+
+	let pulled = 0;
+	let skipped = 0;
+
+	for (const comp of components) {
+		const compSlug = slugify(comp.name) || comp.id.slice(0, 8);
+		const compDir = join(targetDir, 'components', compSlug);
+
+		const pullSpinner = ora(`Pulling ${comp.name}…`).start();
+		try {
+			const payload = await apiFetch(`/api/admin/core-components/${comp.id}/files`);
+			const files = payload?.files ?? {};
+			if (!Object.keys(files).length) {
+				pullSpinner.warn(`${comp.name}: empty source bundle — skipped`);
+				skipped++;
+				continue;
+			}
+			mkdirSync(compDir, { recursive: true });
+			writeComponentFiles(compDir, files, { clean: true });
+			const fileHashes = computeFileHashesFromMap(files);
+			writeMeta(compDir, {
+				componentId: comp.id,
+				// Pin the version we pulled so the gallery sees this as in-sync.
+				baseVersion: payload.versionId ?? null,
+				version: payload.version,
+				pulledAt: new Date().toISOString(),
+				fileHashes
+			});
+			pullSpinner.succeed(`${comp.name} ${pc.dim('v' + payload.version)}`);
+			pulled++;
+		} catch (err) {
+			if (err instanceof ApiError && err.status === 409 && err.body?.legacy) {
+				pullSpinner.warn(`${comp.name}: legacy ZIP-source — skipped, clone manually`);
+			} else if (err instanceof ApiError && err.status === 404) {
+				pullSpinner.warn(`${comp.name}: no published version — skipped`);
+			} else if (err instanceof ApiError) {
+				pullSpinner.fail(`${comp.name}: HTTP ${err.status} — ${err.message}`);
+			} else {
+				pullSpinner.fail(`${comp.name}: ${err.message}`);
+			}
+			skipped++;
+		}
+	}
+
+	console.log();
+	logger.success(`Cloned Core library — ${pulled} pulled, ${skipped} skipped`);
+	console.log();
+	console.log(pc.bold('Next steps:'));
+	console.log(`  ${pc.cyan('cd ' + dirName)}`);
+	console.log(`  ${pc.cyan('wm dev')} ${pc.dim('# see all Core components in the preview gallery')}`);
+	console.log(`  ${pc.cyan('wm core push')} ${pc.dim('# push every component that has local changes')}`);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// wm core init [dir]
+// ────────────────────────────────────────────────────────────────────────────
+
+export async function coreInitCommand(dirArg, options = {}) {
+	const rootDir = resolveDir(dirArg);
+	if (!existsSync(rootDir)) {
+		logger.error(`Directory not found: ${rootDir}`);
+		process.exit(1);
+	}
+
+	let componentInfo;
+	try {
+		componentInfo = getComponentId(rootDir);
+	} catch (err) {
+		logger.error(err.message);
+		process.exit(1);
+	}
+
+	// Use the folder name as the technical Core name unless component.json names one.
+	const techName = (componentInfo.raw?.name || basename(rootDir))
+		.toString()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '');
+
+	const displayName = options.displayName || componentInfo.raw?.displayName || techName;
+	const category = options.category || componentInfo.raw?.category || null;
+	const description = options.description || componentInfo.raw?.description || null;
+
+	const spinner = ora(`Registering ${pc.cyan(techName)} on the server…`).start();
+	let created;
+	try {
+		created = await apiFetch('/api/admin/core-components', {
+			method: 'POST',
+			body: {
+				name: techName,
+				displayName,
+				category,
+				description
+			}
+		});
+	} catch (err) {
+		if (err instanceof ApiError && err.status === 409) {
+			spinner.fail(
+				`A Core component named "${techName}" already exists. ` +
+				`Use \`wm core clone ${techName}\` to start editing it.`
+			);
+		} else if (err instanceof ApiError && err.status === 403) {
+			spinner.fail('SuperAdmin permissions required.');
+		} else {
+			spinner.fail(err.message);
+		}
+		process.exit(1);
+	}
+
+	spinner.succeed(`Registered ${pc.cyan(created.name)} ${pc.dim('(' + created.coreComponentId + ')')}`);
+
+	writeMeta(rootDir, {
+		componentId: created.coreComponentId,
+		baseVersion: null,
+		version: '0.0.0',
+		pulledAt: new Date().toISOString(),
+		fileHashes: {}
+	});
+
+	// Rewrite local component.json so its id matches the server. Without this
+	// the next push uploads source.json with a stale UUID inside component.json,
+	// which then conflicts with the server-side override on download.
+	const synced = syncComponentJsonId(rootDir, { id: created.coreComponentId, name: created.name });
+	if (synced) {
+		console.log(`  ${pc.dim('Updated component.json with the server-assigned id.')}`);
+	}
+
+	console.log(`  Next:   ${pc.bold('wm core push')} to upload the first version.`);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// wm core attach <name>
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Bind an already-existing Core record (typically just created in the
+ * admin UI) to the current local folder. Writes .webmate.json and
+ * patches component.json with the server-assigned id, but does NOT
+ * upload anything. The next `wm core push` becomes the first version.
+ */
+export async function coreAttachCommand(name, options = {}) {
+	if (!name) {
+		logger.error('Component name is required. Usage: wm core attach <name>');
+		process.exit(1);
+	}
+
+	const rootDir = resolveDir(options.dir);
+	if (!existsSync(rootDir)) {
+		logger.error(`Directory not found: ${rootDir}`);
+		process.exit(1);
+	}
+
+	const existing = readMeta(rootDir);
+	if (existing?.componentId && !options.force) {
+		logger.error(
+			`This folder is already attached to component ${existing.componentId}. ` +
+			`Use --force to overwrite.`
+		);
+		process.exit(1);
+	}
+
+	const lookup = ora(`Resolving "${name}"…`).start();
+	let core;
+	try {
+		core = await findCoreByName(name);
+	} catch (err) {
+		if (err instanceof ApiError && err.status === 403) {
+			lookup.fail('SuperAdmin permissions required.');
+		} else {
+			lookup.fail(err.message);
+		}
+		process.exit(1);
+	}
+	if (!core) {
+		lookup.fail(`No Core component named "${name}" found.`);
+		process.exit(1);
+	}
+	lookup.succeed(`Found ${pc.cyan(core.name)} ${pc.dim('(' + core.id + ')')}`);
+
+	writeMeta(rootDir, {
+		componentId: core.id,
+		baseVersion: null,
+		version: core.currentVersion || '0.0.0',
+		pulledAt: new Date().toISOString(),
+		fileHashes: {}
+	});
+
+	const synced = syncComponentJsonId(rootDir, { id: core.id, name: core.name });
+
+	logger.success(`Attached ${pc.cyan(core.name)} to ${pc.dim(rootDir)}`);
+	if (synced) {
+		console.log(`  ${pc.dim('Updated component.json with the server id.')}`);
+	}
+	console.log(`  Next:   ${pc.bold('wm core push')} to upload the first version.`);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// wm core push [dir]
+// ────────────────────────────────────────────────────────────────────────────
+
+export async function corePushCommand(dirArg, options = {}) {
+	const rootDir = resolveDir(dirArg);
+	if (!existsSync(rootDir)) {
+		logger.error(`Directory not found: ${rootDir}`);
+		process.exit(1);
+	}
+
+	// Workspace-mode: if the user runs `wm core push` (no dir, no .webmate.json
+	// here) from inside a Core workspace, iterate over every component subfolder
+	// and push each one that has local changes. Parallel to the org-workspace
+	// bulk push flow.
+	const meta = readMeta(rootDir);
+	if (!meta?.componentId) {
+		const ws = findEnclosingCoreWorkspace(rootDir);
+		if (ws) {
+			return corePushWorkspaceCommand(ws.root, options);
+		}
+		logger.error(
+			`No .webmate.json found in ${rootDir}. ` +
+			`Run \`wm core clone <name>\` or \`wm core init\` first.`
+		);
+		process.exit(1);
+	}
+
+	const { files, fileHashes } = readComponentFiles(rootDir);
+
+	const body = { files };
+	if (meta.baseVersion) body.baseVersion = meta.baseVersion;
+	if (options.message) body.commitMessage = options.message;
+
+	const spinner = ora('Uploading and building…').start();
+	let result;
+	try {
+		result = await apiFetch(`/api/admin/core-components/${meta.componentId}/versions`, {
+			method: 'POST',
+			body
+		});
+	} catch (err) {
+		if (err instanceof ApiError) {
+			if (err.status === 404) {
+				spinner.fail(
+					`Core component ${meta.componentId} not found on the server. ` +
+					`Run \`wm core init\` to register it first.`
+				);
+			} else if (err.status === 403) {
+				spinner.fail('SuperAdmin permissions required.');
+			} else if (err.status === 409) {
+				spinner.fail(
+					`Conflict: remote moved to v${err.body?.currentVersion ?? '?'}. ` +
+					`Run \`wm core clone ${meta.componentId}\` to refresh local source.`
+				);
+			} else if (err.status === 422) {
+				spinner.fail(`Build failed: ${err.body?.buildErrors?.join('; ') || err.message}`);
+			} else {
+				spinner.fail(`Push failed (HTTP ${err.status}): ${err.message}`);
+			}
+		} else {
+			spinner.fail(err.message);
+		}
+		process.exit(1);
+	}
+
+	spinner.succeed(`Built and published ${pc.cyan(result.version)} ${pc.dim('(' + result.versionId.slice(0, 8) + ')')}`);
+
+	writeMeta(rootDir, {
+		componentId: meta.componentId,
+		baseVersion: result.versionId,
+		version: result.version,
+		pulledAt: new Date().toISOString(),
+		fileHashes
+	});
+
+	logger.success(`Pushed Core component ${pc.cyan(meta.componentId)} as ${pc.cyan(result.version)}`);
+	if (result.previousVersion) {
+		console.log(`  Previous:  ${pc.dim(result.previousVersion)}`);
+	}
+	console.log(`  Files:     ${pc.dim(Object.keys(files).length + ' file(s)')}`);
+
+	const snap = await autoSnapshot(
+		rootDir,
+		options.message
+			? `wm core push ${result.version}: ${options.message}`
+			: `wm core push ${result.version}`,
+		{ skip: options.noGit }
+	);
+	if (snap.committed) {
+		console.log(`  Git:       ${pc.dim('committed ' + snap.sha)}`);
+	} else if (snap.skipped && snap.reason === 'no-git') {
+		console.log(`  Git:       ${pc.dim('skipped (no .git)')}`);
+	} else if (snap.skipped && snap.reason === 'no-changes') {
+		console.log(`  Git:       ${pc.dim('nothing to snapshot')}`);
+	}
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// wm core push (workspace bulk mode)
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Iterate over every components/<name>/ subfolder in a Core workspace,
+ * push the ones that have local changes. Per-component output is concise
+ * so a 64-component bulk push doesn't drown the terminal.
+ *
+ * Skips folders that:
+ *  - have no .webmate.json (not yet attached — caller should `wm core init` or `attach`)
+ *  - have no local diff against the last recorded fileHashes
+ *  - have a baseVersion=null but no files (never-pushed but also nothing to push)
+ *
+ * Build errors on one component don't abort the run — the next component
+ * still gets a chance. A summary at the end lists failures explicitly.
+ */
+async function corePushWorkspaceCommand(workspaceRoot, options = {}) {
+	const entries = listComponentSubfolders(workspaceRoot);
+	if (entries.length === 0) {
+		logger.info('No components found in this workspace.');
+		return;
+	}
+
+	console.log(pc.bold(`Core workspace: ${pc.dim(workspaceRoot)}`));
+	console.log(pc.dim(`  Scanning ${entries.length} component(s)…`));
+	console.log();
+
+	let pushed = 0;
+	let skipped = 0;
+	const failures = [];
+
+	for (const entry of entries) {
+		const meta = readMeta(entry.absPath);
+		if (!meta?.componentId) {
+			console.log(`  ${pc.dim('·')} ${entry.name}: ${pc.dim('not attached, skipped')}`);
+			skipped++;
+			continue;
+		}
+
+		const { files, fileHashes } = readComponentFiles(entry.absPath);
+
+		// Skip components that match the last recorded hashes AND have a
+		// baseVersion (= have been pushed at least once). First-time pushes
+		// (baseVersion=null) always go through, even if hashes look identical
+		// to whatever was set during clone.
+		if (meta.baseVersion && meta.fileHashes) {
+			const diff = diffHashes(fileHashes, meta.fileHashes);
+			if (diff.added.length + diff.modified.length + diff.removed.length === 0) {
+				if (!options.force) {
+					console.log(`  ${pc.dim('·')} ${entry.name}: ${pc.dim('in sync, skipped')}`);
+					skipped++;
+					continue;
+				}
+			}
+		}
+
+		const body = { files };
+		if (meta.baseVersion) body.baseVersion = meta.baseVersion;
+		if (options.message) body.commitMessage = options.message;
+
+		const spinner = ora(`${entry.name}: building…`).start();
+		try {
+			const result = await apiFetch(`/api/admin/core-components/${meta.componentId}/versions`, {
+				method: 'POST',
+				body
+			});
+			spinner.succeed(
+				`${entry.name}: v${pc.cyan(result.version)} ` +
+				`${pc.dim('(' + Object.keys(files).length + ' files)')}`
+			);
+			writeMeta(entry.absPath, {
+				componentId: meta.componentId,
+				baseVersion: result.versionId,
+				version: result.version,
+				pulledAt: new Date().toISOString(),
+				fileHashes
+			});
+			pushed++;
+		} catch (err) {
+			const detail =
+				err instanceof ApiError
+					? err.status === 422
+						? `build failed: ${err.body?.buildErrors?.join('; ') || err.message}`
+						: err.status === 409
+							? `conflict (remote at v${err.body?.currentVersion ?? '?'})`
+							: `HTTP ${err.status}: ${err.message}`
+					: err.message;
+			spinner.fail(`${entry.name}: ${detail}`);
+			failures.push({ name: entry.name, detail });
+		}
+	}
+
+	console.log();
+	logger.success(
+		`Bulk push done — ${pushed} pushed, ${skipped} skipped, ${failures.length} failed.`
+	);
+	if (failures.length > 0) {
+		console.log();
+		console.log(pc.bold('Failures:'));
+		for (const f of failures) {
+			console.log(`  ${pc.red('×')} ${f.name}: ${pc.dim(f.detail)}`);
+		}
+	}
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// wm core status [name]
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Show local vs. remote sync state. Two modes:
+ *   - no arg, inside a Core workspace → table for every components/* subfolder
+ *   - <name> arg → single component status (resolves name → server lookup)
+ */
+export async function coreStatusCommand(arg, options = {}) {
+	if (arg) {
+		return coreStatusSingleCommand(arg, options);
+	}
+
+	const ws = findEnclosingCoreWorkspace(process.cwd());
+	if (!ws) {
+		logger.error('Not inside a Core workspace. Pass a component name, or `cd` into a workspace.');
+		process.exit(1);
+	}
+
+	const entries = listComponentSubfolders(ws.root);
+	if (entries.length === 0) {
+		logger.info('No components in this workspace.');
+		return;
+	}
+
+	const lookup = ora('Fetching remote state…').start();
+	let remoteByName;
+	try {
+		const res = await apiFetch('/api/admin/core-components');
+		const components = res?.components ?? [];
+		remoteByName = new Map(components.map((c) => [c.name, c]));
+		lookup.succeed(`Remote: ${remoteByName.size} Core component(s)`);
+	} catch (err) {
+		if (err instanceof ApiError && err.status === 403) {
+			lookup.fail('SuperAdmin permissions required.');
+		} else {
+			lookup.fail(err.message);
+		}
+		process.exit(1);
+	}
+
+	console.log();
+	console.log(pc.bold('Core workspace status'));
+	console.log(pc.dim(`  ${ws.root}`));
+	console.log();
+
+	const localNames = new Set();
+
+	for (const entry of entries) {
+		localNames.add(entry.name);
+		const meta = readMeta(entry.absPath);
+		if (!meta?.componentId) {
+			console.log(`  ${pc.yellow('?')} ${pc.cyan(entry.name.padEnd(32))} ${pc.dim('not attached')}`);
+			continue;
+		}
+
+		const remote = remoteByName.get(entry.name);
+		const { fileHashes } = readComponentFiles(entry.absPath);
+		const hashDiff = meta.fileHashes
+			? diffHashes(fileHashes, meta.fileHashes)
+			: { added: [], modified: [], removed: [] };
+		const hasLocalChanges = hashDiff.added.length + hashDiff.modified.length + hashDiff.removed.length > 0;
+		const behindRemote = remote && meta.version && remote.currentVersion && remote.currentVersion !== meta.version;
+
+		let label;
+		if (!remote) {
+			label = pc.red('remote-missing');
+		} else if (hasLocalChanges && behindRemote) {
+			label = pc.magenta('diverged');
+		} else if (hasLocalChanges) {
+			label = pc.yellow('changes-local');
+		} else if (behindRemote) {
+			label = pc.cyan('behind-remote');
+		} else if (!meta.baseVersion) {
+			label = pc.yellow('never-pushed');
+		} else {
+			label = pc.green('in-sync');
+		}
+
+		const v = meta.version ? `v${meta.version}` : 'v?';
+		const rv = remote?.currentVersion ? `v${remote.currentVersion}` : 'v—';
+		console.log(`  ${label.padEnd(24)} ${pc.cyan(entry.name.padEnd(32))} ${pc.dim('local ' + v + ' / remote ' + rv)}`);
+	}
+
+	const remoteOnly = [...remoteByName.keys()].filter((n) => !localNames.has(n));
+	if (remoteOnly.length > 0) {
+		console.log();
+		console.log(pc.dim(`  ${remoteOnly.length} remote component(s) not in this workspace:`));
+		for (const n of remoteOnly) {
+			console.log(`    ${pc.dim('· ' + n)}`);
+		}
+		console.log(pc.dim(`  Run \`wm core clone\` again to pull them.`));
+	}
+}
+
+async function coreStatusSingleCommand(name, _options = {}) {
+	let core;
+	try {
+		core = await findCoreByName(name);
+	} catch (err) {
+		if (err instanceof ApiError && err.status === 403) {
+			logger.error('SuperAdmin permissions required.');
+		} else {
+			logger.error(err.message);
+		}
+		process.exit(1);
+	}
+	if (!core) {
+		logger.error(`No Core component named "${name}" found.`);
+		process.exit(1);
+	}
+
+	console.log(pc.bold(core.name));
+	console.log(`  Display:   ${core.displayName}`);
+	console.log(`  Category:  ${core.category || pc.dim('—')}`);
+	console.log(`  Version:   v${core.currentVersion || '—'}`);
+	console.log(`  Active:    ${core.active ? pc.green('yes') : pc.red('no')}`);
+	console.log(`  Featured:  ${core.featured ? pc.yellow('yes') : 'no'}`);
+	console.log(`  Used by:   ${core.usageCount ?? 0} site(s)`);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// wm core init-all [dir]
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Bulk-onboarding for the 64 legacy components: iterates over every
+ * subfolder of <dir>/components/ (or <dir> directly if it looks like a
+ * single components/ folder) and runs init + first push for each.
+ *
+ * Skips folders that:
+ *   - don't have a component.json
+ *   - already carry a .webmate.json (already initialised)
+ *
+ * Stops nothing on individual failures — collects them and reports at the end.
+ */
+export async function coreInitAllCommand(dirArg, options = {}) {
+	const rootDir = resolveDir(dirArg);
+	if (!existsSync(rootDir)) {
+		logger.error(`Directory not found: ${rootDir}`);
+		process.exit(1);
+	}
+
+	// If user passes the workspace root (./webmate-premium-components),
+	// pick up its components/ subfolder. If they pass the components/ folder
+	// directly, use that. Both work.
+	let componentsDir = rootDir;
+	if (!existsSync(join(rootDir, 'component.json')) && existsSync(join(rootDir, 'components'))) {
+		componentsDir = join(rootDir, 'components');
+	}
+
+	const entries = readdirSync(componentsDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+		.map((d) => ({ name: d.name, absPath: join(componentsDir, d.name) }))
+		.filter((e) => existsSync(join(e.absPath, 'component.json')));
+
+	if (entries.length === 0) {
+		logger.error(`No components with component.json found under ${componentsDir}`);
+		process.exit(1);
+	}
+
+	console.log(pc.bold(`Bulk Core onboarding`));
+	console.log(pc.dim(`  Components dir: ${componentsDir}`));
+	console.log(pc.dim(`  Found ${entries.length} component(s)`));
+	console.log();
+
+	if (!options.yes) {
+		const proceed = await confirm({
+			message: `Init + push ${pc.cyan(entries.length)} component(s) as Core records?`,
+			default: false
+		});
+		if (!proceed) {
+			logger.info('Cancelled.');
+			return;
+		}
+	}
+
+	// Pre-fetch every CoreComponent id the server currently knows about — used
+	// to validate that a .webmate.json on disk still points at a live record.
+	// After a server-side wipe (or manual delete) the local meta lingers and
+	// would otherwise short-circuit init, causing every subsequent push to 404.
+	const serverLookup = ora('Checking server inventory…').start();
+	let serverIds;
+	try {
+		const list = await apiFetch('/api/admin/core-components');
+		serverIds = new Set((list?.components ?? []).map((c) => c.id));
+		serverLookup.succeed(`Server inventory: ${serverIds.size} Core component(s) on record`);
+	} catch (err) {
+		serverLookup.fail(err.message);
+		process.exit(1);
+	}
+
+	let inited = 0;
+	let pushed = 0;
+	let skipped = 0;
+	const failures = [];
+
+	for (const entry of entries) {
+		const existingMeta = readMeta(entry.absPath);
+		const metaIsValid = existingMeta?.componentId && serverIds.has(existingMeta.componentId);
+		if (existingMeta?.componentId && !metaIsValid) {
+			console.log(
+				`  ${pc.yellow('!')} ${entry.name}: ${pc.dim('stale .webmate.json (id ' + existingMeta.componentId.slice(0, 8) + ' not on server) — re-initialising')}`
+			);
+		}
+		if (metaIsValid) {
+			console.log(`  ${pc.dim('·')} ${entry.name}: ${pc.dim('already attached, skipping init')}`);
+		} else {
+			// Inline init: parses component.json, posts create, writes .webmate.json,
+			// syncs component.json id. Same logic as coreInitCommand but quieter.
+			let componentInfo;
+			try {
+				componentInfo = getComponentId(entry.absPath);
+			} catch (err) {
+				failures.push({ name: entry.name, stage: 'read', detail: err.message });
+				console.log(`  ${pc.red('×')} ${entry.name}: ${pc.dim('component.json read failed')}`);
+				continue;
+			}
+
+			const techName = (componentInfo.raw?.name || entry.name)
+				.toString()
+				.toLowerCase()
+				.replace(/[^a-z0-9]+/g, '-')
+				.replace(/^-+|-+$/g, '');
+
+			const spinner = ora(`${entry.name}: registering…`).start();
+			let created;
+			try {
+				created = await apiFetch('/api/admin/core-components', {
+					method: 'POST',
+					body: {
+						name: techName,
+						displayName: componentInfo.raw?.displayName || techName,
+						category: componentInfo.raw?.category || null,
+						description: componentInfo.raw?.description || null
+					}
+				});
+				spinner.succeed(`${entry.name}: registered as ${pc.cyan(created.name)}`);
+				inited++;
+			} catch (err) {
+				if (err instanceof ApiError && err.status === 409) {
+					spinner.warn(`${entry.name}: name "${techName}" already exists on server — attaching`);
+					// Re-fetch by name and attach instead.
+					const existing = await findCoreByName(techName).catch(() => null);
+					if (!existing) {
+						failures.push({ name: entry.name, stage: 'init', detail: '409 but findByName failed' });
+						continue;
+					}
+					created = { coreComponentId: existing.id, name: existing.name };
+				} else {
+					failures.push({
+						name: entry.name,
+						stage: 'init',
+						detail: err instanceof ApiError ? `HTTP ${err.status}: ${err.message}` : err.message
+					});
+					spinner.fail(`${entry.name}: init failed`);
+					continue;
+				}
+			}
+
+			writeMeta(entry.absPath, {
+				componentId: created.coreComponentId,
+				baseVersion: null,
+				version: '0.0.0',
+				pulledAt: new Date().toISOString(),
+				fileHashes: {}
+			});
+			syncComponentJsonId(entry.absPath, { id: created.coreComponentId, name: created.name });
+		}
+
+		// Push first version (or next version if attaching).
+		const meta = readMeta(entry.absPath);
+		const { files, fileHashes } = readComponentFiles(entry.absPath);
+		const body = { files };
+		if (meta.baseVersion) body.baseVersion = meta.baseVersion;
+
+		const spinner = ora(`${entry.name}: building…`).start();
+		try {
+			const result = await apiFetch(
+				`/api/admin/core-components/${meta.componentId}/versions`,
+				{ method: 'POST', body }
+			);
+			spinner.succeed(
+				`${entry.name}: v${pc.cyan(result.version)} ` +
+				`${pc.dim('(' + Object.keys(files).length + ' files)')}`
+			);
+			writeMeta(entry.absPath, {
+				componentId: meta.componentId,
+				baseVersion: result.versionId,
+				version: result.version,
+				pulledAt: new Date().toISOString(),
+				fileHashes
+			});
+			pushed++;
+		} catch (err) {
+			const detail =
+				err instanceof ApiError
+					? err.status === 422
+						? `build failed: ${err.body?.buildErrors?.join('; ') || err.message}`
+						: `HTTP ${err.status}: ${err.message}`
+					: err.message;
+			spinner.fail(`${entry.name}: ${detail}`);
+			failures.push({ name: entry.name, stage: 'push', detail });
+			skipped++;
+		}
+	}
+
+	console.log();
+	logger.success(
+		`Bulk onboarding done — ${inited} initialised, ${pushed} pushed, ${failures.length} failed.`
+	);
+	if (failures.length > 0) {
+		console.log();
+		console.log(pc.bold('Failures:'));
+		for (const f of failures) {
+			console.log(`  ${pc.red('×')} ${f.name.padEnd(28)} ${pc.dim('[' + f.stage + ']')} ${f.detail}`);
+		}
+	}
+}