@fluid-app/fluid-cli-portal 0.1.7 → 0.1.9

package/dist/index.mjs

@@ -1,16 +1,17 @@
+import { A as deleteFluidOSNavigation, B as updateFluidOSScreen, C as writeMappings, D as createFluidOSScreen, E as createFluidOSProfile, F as listFluidOSNavigationItems, H as updateFluidOSVersion, I as listFluidOSVersions, L as updateFluidOSNavigation, M as deleteFluidOSProfile, N as deleteFluidOSScreen, O as createFluidOSTheme, P as deleteFluidOSTheme, R as updateFluidOSNavigationItem, S as updateMapping, T as createFluidOSNavigationItem, U as createFetchClient, V as updateFluidOSTheme, _ as deriveSlug, a as buildThemeIdToSlugMap, b as resolveIdToSlug, c as transformNavigationItems, d as transformTheme, f as buildSnapshot, g as writeSnapshot, h as readSnapshot, i as buildNavigationIdToSlugMap, j as deleteFluidOSNavigationItem, k as createFluidOSVersion, l as transformProfile, m as diffAgainstSnapshot, o as deriveScreenSlug, p as computeFileHash, r as buildIdToSlugMap, s as transformNavigation, t as pullCommand, u as transformScreen, v as readMappings, w as createFluidOSNavigation, x as resolveSlugToId, y as removeMapping, z as updateFluidOSProfile } from "./pull-p1mSVa5W.mjs";
 import { Command } from "commander";
 import chalk from "chalk";
 import ora from "ora";
-import { dirname, join, resolve } from "node:path";
+import path, { basename, dirname, join, resolve } from "node:path";
 import { copyFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import prompts from "prompts";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import Handlebars from "handlebars";
-import { failure, getErrorMessage, success } from "@fluid-app/fluid-cli";
+import { failure, getActiveProfile, getAuthToken, getErrorMessage, success } from "@fluid-app/fluid-cli";
 import { execa } from "execa";
 import fs from "fs-extra";
-import path from "path";
+import path$1 from "path";
 import { config } from "dotenv";
 //#region src/types.ts
 /**
@@ -110,13 +111,13 @@ async function promptProjectConfig(projectName, options) {
 }
 //#endregion
 //#region src/utils/file-system.ts
-const _currentDir = dirname(fileURLToPath(import.meta.url));
+const _currentDir$1 = dirname(fileURLToPath(import.meta.url));
 /**
 * Find the package root by walking up from the current directory to the nearest package.json.
 * Works whether running from dist/ (bundled) or src/utils/ (tsx dev mode).
 */
 function findPackageRoot() {
-	let dir = _currentDir;
+	let dir = _currentDir$1;
 	while (!existsSync(join(dir, "package.json"))) {
 		const parent = dirname(dir);
 		if (parent === dir) throw new Error("Could not find package root");
@@ -450,12 +451,48 @@ const createCommand = new Command("create").description("Create a new Fluid port
 		process.exit(1);
 	}
 });
-function registerCreateCommand(ctx) {
-	ctx.program.addCommand(createCommand);
-}
 //#endregion
 //#region src/commands/dev.ts
-const devCommand = new Command("dev").description("Start the development server").option("-p, --port <port>", "Port to run the dev server on", "5173").option("--host", "Expose the dev server to the network").action(async (options) => {
+/**
+* `fluid portal dev` command
+*
+* Starts the Vite development server with the portal dev plugin,
+* which intercepts manifest API requests and serves content from
+* the local `portal/` directory.
+*
+* If no `portal/` directory exists, prompts the user to run `fluid portal pull`
+* or auto-pulls if they are logged in.
+*/
+const PORTAL_DIR$1 = "portal";
+/**
+* Check if the portal directory exists and has content files.
+* Returns true if at minimum `portal/definition.json` exists.
+*/
+function hasPortalContent(cwd) {
+	return existsSync(join(cwd, PORTAL_DIR$1, "definition.json"));
+}
+/**
+* Attempt to auto-pull portal content by invoking the pull command's action.
+* Falls back to a helpful error message if pull is not possible.
+*/
+async function autoPull(cwd) {
+	console.log();
+	console.log(chalk.yellow("No portal/ directory found.") + " Attempting to pull content...");
+	console.log();
+	try {
+		const { pullCommand } = await import("./pull-p1mSVa5W.mjs").then((n) => n.n);
+		await pullCommand.parseAsync([], { from: "user" });
+		return hasPortalContent(cwd);
+	} catch (err) {
+		console.log();
+		console.log(chalk.red("Auto-pull failed: ") + (err instanceof Error ? err.message : String(err)));
+		console.log();
+		console.log("Run " + chalk.cyan("fluid portal pull") + " manually to set up local content.");
+		console.log();
+		return false;
+	}
+}
+const devCommand = new Command("dev").description("Start the development server with local portal content serving").option("-p, --port <port>", "Port to run the dev server on", "5173").option("--host", "Expose the dev server to the network").option("--skip-pull", "Skip auto-pull if portal/ directory is missing").action(async (options) => {
 	const cwd = process.cwd();
 	if (!existsSync(join(cwd, "package.json"))) {
 		console.error(chalk.red("Error: No package.json found in current directory"));
@@ -467,6 +504,19 @@ const devCommand = new Command("dev").description("Start the development server"
 		console.error(chalk.yellow("This command must be run from a Fluid project directory"));
 		process.exit(1);
 	}
+	if (!hasPortalContent(cwd) && !options.skipPull) {
+		if (!await autoPull(cwd)) {
+			console.error(chalk.red("Cannot start dev server without portal content."));
+			console.error(chalk.yellow("Run " + chalk.cyan("fluid portal pull") + " to download content first."));
+			process.exit(1);
+		}
+	}
+	if (hasPortalContent(cwd)) {
+		console.log();
+		console.log(chalk.green("Portal dev mode: ") + "local content from " + chalk.cyan("portal/") + " will be served");
+		console.log(chalk.gray("  Manifest requests intercepted at /api/fluid_os/definitions/active"));
+		console.log(chalk.gray("  File changes in portal/ will trigger a page reload"));
+	}
 	const viteArgs = ["vite"];
 	if (options.port) viteArgs.push("--port", String(options.port));
 	if (options.host) viteArgs.push("--host");
@@ -484,9 +534,6 @@ const devCommand = new Command("dev").description("Start the development server"
 		process.exit(1);
 	}
 });
-function registerDevCommand(ctx) {
-	ctx.program.addCommand(devCommand);
-}
 //#endregion
 //#region src/commands/build.ts
 const buildCommand = new Command("build").description("Build the application for production").option("-o, --out-dir <dir>", "Output directory", "dist").action(async (options) => {
@@ -524,9 +571,6 @@ const buildCommand = new Command("build").description("Build the application for
 		process.exit(1);
 	}
 });
-function registerBuildCommand(ctx) {
-	ctx.program.addCommand(buildCommand);
-}
 //#endregion
 //#region src/utils/turso.ts
 const TURSO_API_BASE = "https://api.turso.tech/v1";
@@ -1314,7 +1358,7 @@ async function validateFluidApiKey(apiKey) {
 * Read project name from package.json
 */
 async function getProjectName(cwd) {
-	const packageJsonPath = path.join(cwd, "package.json");
+	const packageJsonPath = path$1.join(cwd, "package.json");
 	if (await fs.pathExists(packageJsonPath)) return (await fs.readJson(packageJsonPath)).name;
 }
 /**
@@ -1351,8 +1395,8 @@ const EXTRACT_FILENAME = "__fluid_extract_nav.ts";
 * @param projectDir - The project root directory containing src/navigation.config.ts
 */
 async function extractNavigation(projectDir) {
-	const configPath = path.join(projectDir, "src", "navigation.config.ts");
-	const extractFile = path.join(projectDir, EXTRACT_FILENAME);
+	const configPath = path$1.join(projectDir, "src", "navigation.config.ts");
+	const extractFile = path$1.join(projectDir, EXTRACT_FILENAME);
 	try {
 		const configSource = await fs.readFile(configPath, "utf-8");
 		if (!/export\s+(const|let)\s+navigation\s*=/.test(configSource)) return success(null);
@@ -1610,11 +1654,11 @@ async function syncNavigation(apiKey, codeItems) {
 * Detect if the project is a fullstack template (has server entry)
 */
 async function isFullstackProject(cwd) {
-	return fs.pathExists(path.join(cwd, "src", "server", "index.ts"));
+	return fs.pathExists(path$1.join(cwd, "src", "server", "index.ts"));
 }
 const deployCommand = new Command("deploy").description("Deploy the fullstack application to Cloud Run + Turso").option("--region <region>", "Cloud Run region", "us-central1").option("--gcp-project <id>", "GCP project ID (default: from gcloud config)").option("-p, --project <name>", "Service name override (default: from package.json)").option("--db-region <location>", "Turso database group location", "aws-us-east-1").option("--require-auth", "Require IAM authentication for the Cloud Run service (default: public)").option("--migrate", "Run database migrations (db:push) after successful deploy").option("--skip-local-build", "Skip the local Docker build check before deploying").option("--turso-org <slug>", "Turso organization slug (skips interactive org selection)").option("--fluid-company-api-key <key>", "Fluid company API key (skips env var lookup and prompt)").option("--skip-nav-sync", "Skip navigation sync from portal.config.ts").action(async (options) => {
 	const cwd = process.cwd();
-	config({ path: path.join(cwd, ".env") });
+	config({ path: path$1.join(cwd, ".env") });
 	console.log();
 	console.log(chalk.blue.bold("Fluid Deploy") + chalk.gray(" (Cloud Run + Turso)"));
 	console.log();
@@ -1646,7 +1690,7 @@ const deployCommand = new Command("deploy").description("Deploy the fullstack ap
 		process.exit(1);
 	}
 	spinner.succeed(`Fluid company: ${chalk.cyan(fluidResult.value.name)}`);
-	if (!await fs.pathExists(path.join(cwd, "Dockerfile"))) {
+	if (!await fs.pathExists(path$1.join(cwd, "Dockerfile"))) {
 		console.log(chalk.red("Error:") + " No Dockerfile found in current directory.");
 		console.log();
 		console.log("Fullstack projects created with the latest template include a Dockerfile.");
@@ -1845,7 +1889,7 @@ const deployCommand = new Command("deploy").description("Deploy the fullstack ap
 		console.log(chalk.gray("GCP Project:  ") + chalk.cyan(deployResult.value.gcpProject));
 		console.log();
 		if (!options.skipNavSync) {
-			const configPath = path.join(cwd, "src", "navigation.config.ts");
+			const configPath = path$1.join(cwd, "src", "navigation.config.ts");
 			if (await fs.pathExists(configPath)) {
 				const navSpinner = ora("Extracting navigation from navigation.config.ts...").start();
 				const extractResult = await extractNavigation(cwd);
@@ -1929,14 +1973,11 @@ const deployCommand = new Command("deploy").description("Deploy the fullstack ap
 		process.exit(1);
 	}
 });
-function registerDeployCommand(ctx) {
-	ctx.program.addCommand(deployCommand);
-}
 //#endregion
 //#region src/commands/destroy.ts
 const destroyCommand = new Command("destroy").description("Tear down deployed Cloud Run service and Turso database").option("--region <region>", "Cloud Run region", "us-central1").option("--gcp-project <id>", "GCP project ID (default: from gcloud config)").option("-p, --project <name>", "Service name override (default: from package.json)").option("--turso-org <slug>", "Turso organization slug (skips interactive org selection)").option("--fluid-company-api-key <key>", "Fluid company API key (skips env var lookup and prompt)").option("-y, --yes", "Skip confirmation prompt").action(async (options) => {
 	const cwd = process.cwd();
-	config({ path: path.join(cwd, ".env") });
+	config({ path: path$1.join(cwd, ".env") });
 	console.log();
 	console.log(chalk.red.bold("Fluid Destroy") + chalk.gray(" (Cloud Run + Turso)"));
 	console.log();
@@ -2068,23 +2109,1421 @@ const destroyCommand = new Command("destroy").description("Tear down deployed Cl
 	else console.log(chalk.yellow.bold("Destroy completed with warnings.") + " Some resources may need manual cleanup.");
 	console.log();
 });
-function registerDestroyCommand(ctx) {
-	ctx.program.addCommand(destroyCommand);
+//#endregion
+//#region src/utils/push-validation.ts
+/**
+* Cross-reference validation and change categorization utilities for the push command.
+*
+* Extracted into a standalone utility so that pure logic can be tested
+* without pulling in CLI dependencies (ora, chalk, prompts, etc.).
+*/
+/**
+* Extract the slug from a file path (e.g., "screens/home.json" -> "home").
+*/
+function slugFromPath(filePath) {
+	return basename(filePath, ".json");
+}
+/**
+* Extract the resource type directory from a file path (e.g., "screens/home.json" -> "screens").
+*/
+function resourceTypeFromPath(filePath) {
+	const dir = filePath.split("/")[0];
+	if (dir === "screens" || dir === "themes" || dir === "navigations" || dir === "profiles") return dir;
+	return null;
+}
+/**
+* Read and parse a JSON file from the portal directory.
+*/
+async function readPortalFile$1(portalDir, relativePath) {
+	const content = await readFile(join(portalDir, relativePath), "utf-8");
+	return JSON.parse(content);
+}
+/**
+* Categorize a snapshot diff into resource-type-specific change lists.
+*/
+function categorizeChanges(diff) {
+	const result = {
+		screens: {
+			new: [],
+			changed: [],
+			deleted: []
+		},
+		themes: {
+			new: [],
+			changed: [],
+			deleted: []
+		},
+		navigations: {
+			new: [],
+			changed: [],
+			deleted: []
+		},
+		profiles: {
+			new: [],
+			changed: [],
+			deleted: []
+		}
+	};
+	for (const file of diff.new) {
+		const type = resourceTypeFromPath(file);
+		if (type) result[type].new.push(file);
+	}
+	for (const file of diff.changed) {
+		const type = resourceTypeFromPath(file);
+		if (type) result[type].changed.push(file);
+	}
+	for (const file of diff.deleted) {
+		const type = resourceTypeFromPath(file);
+		if (type) result[type].deleted.push(file);
+	}
+	return result;
+}
+/**
+* Validate that all cross-references between local portal files are valid.
+*
+* Checks:
+* - Navigation items' "screen" slugs reference existing screen files or mappings
+* - Profile "navigation" and "mobile_navigation" slugs reference existing nav files or mappings
+* - Profile "themes" slugs reference existing theme files or mappings
+*/
+async function validateCrossReferences(portalDir, mappings, changes) {
+	const errors = [];
+	const validScreenSlugs = buildValidSlugsSet(portalDir, "screens", mappings);
+	const validNavSlugs = buildValidSlugsSet(portalDir, "navigations", mappings);
+	const validThemeSlugs = buildValidSlugsSet(portalDir, "themes", mappings);
+	for (const file of changes.screens.deleted) validScreenSlugs.delete(slugFromPath(file));
+	for (const file of changes.navigations.deleted) validNavSlugs.delete(slugFromPath(file));
+	for (const file of changes.themes.deleted) validThemeSlugs.delete(slugFromPath(file));
+	const navFilesToCheck = [...changes.navigations.new, ...changes.navigations.changed];
+	for (const file of navFilesToCheck) try {
+		validateNavigationItems((await readPortalFile$1(portalDir, file)).navigation_items, file, validScreenSlugs, errors);
+	} catch {
+		errors.push({
+			file,
+			message: "Failed to read navigation file"
+		});
+	}
+	const profileFilesToCheck = [...changes.profiles.new, ...changes.profiles.changed];
+	for (const file of profileFilesToCheck) try {
+		const profile = await readPortalFile$1(portalDir, file);
+		if (profile.navigation && !validNavSlugs.has(profile.navigation)) errors.push({
+			file,
+			message: `References navigation "${profile.navigation}" which does not exist`
+		});
+		if (profile.mobile_navigation && !validNavSlugs.has(profile.mobile_navigation)) errors.push({
+			file,
+			message: `References mobile_navigation "${profile.mobile_navigation}" which does not exist`
+		});
+		for (const themeSlug of profile.themes) if (!validThemeSlugs.has(themeSlug)) errors.push({
+			file,
+			message: `References theme "${themeSlug}" which does not exist`
+		});
+	} catch {
+		errors.push({
+			file,
+			message: "Failed to read profile file"
+		});
+	}
+	return errors;
+}
+/**
+* Build a set of valid slugs for a resource type by combining
+* existing mapping slugs with local file slugs on disk.
+*/
+function buildValidSlugsSet(portalDir, resourceType, mappings) {
+	const slugs = /* @__PURE__ */ new Set();
+	for (const slug of Object.keys(mappings[resourceType])) slugs.add(slug);
+	const dir = join(portalDir, resourceType);
+	if (existsSync(dir)) try {
+		const entries = readdirSync(dir);
+		for (const entry of entries) if (entry.endsWith(".json")) slugs.add(basename(entry, ".json"));
+	} catch {}
+	return slugs;
+}
+/**
+* Recursively validate navigation item screen references.
+*/
+function validateNavigationItems(items, file, validScreenSlugs, errors) {
+	for (const item of items) {
+		if (item.screen && !validScreenSlugs.has(item.screen)) errors.push({
+			file,
+			message: `Navigation item "${item.label ?? "(unlabeled)"}" references screen "${item.screen}" which does not exist`
+		});
+		if (item.children && item.children.length > 0) validateNavigationItems(item.children, file, validScreenSlugs, errors);
+	}
+}
+//#endregion
+//#region src/commands/push.ts
+/**
+* `fluid portal push` command
+*
+* Pushes local portal content changes to the Fluid OS API.
+* Detects changes since the last pull/push via snapshot diffing,
+* validates cross-references, and pushes resources in dependency order.
+*/
+const PORTAL_DIR = "portal";
+const PORTAL_SYNC_DIR$1 = ".portal-sync";
+/**
+* Convert the local array-form component_tree back to the object
+* the API expects. The pull command normalizes the API object into
+* an array for local convenience; this reverses that transformation.
+*/
+function toApiComponentTree(tree) {
+	if (tree.length === 0) return null;
+	if (tree.length === 1) return tree[0];
+	return { children: tree };
+}
+/**
+* Create an authenticated FetchClient using the stored CLI profile.
+*/
+function createClient$1() {
+	const token = getAuthToken();
+	if (!token) {
+		const profile = getActiveProfile();
+		if (!profile) throw new Error("Not logged in. Run " + chalk.cyan("fluid login") + " first.");
+		throw new Error("No auth token found for profile " + chalk.cyan(profile.name) + ". Run " + chalk.cyan("fluid login") + " to re-authenticate.");
+	}
+	return createFetchClient({
+		baseUrl: process.env["FLUID_API_BASE"] ?? "https://api.fluid.app",
+		getAuthToken: () => token
+	});
+}
+/**
+* Extract an enriched error message from a caught value.
+* Includes structured API error data when available.
+*/
+function enrichedErrorMessage(err) {
+	let msg = err instanceof Error ? err.message : String(err);
+	if (err && typeof err === "object" && "data" in err) msg += ` — ${JSON.stringify(err.data)}`;
+	return msg;
+}
+/**
+* Read and parse a JSON file from the portal directory.
+*/
+async function readPortalFile(portalDir, relativePath) {
+	const content = await readFile(join(portalDir, relativePath), "utf-8");
+	return JSON.parse(content);
+}
+/**
+* Push screen changes to the API.
+*/
+async function pushScreens(client, defId, portalDir, changes, mappings) {
+	const results = [];
+	let currentMappings = mappings;
+	for (const file of changes.new) {
+		const slug = slugFromPath(file);
+		try {
+			const local = await readPortalFile(portalDir, file);
+			const newId = (await createFluidOSScreen(client, defId, { screen: {
+				name: local.name,
+				slug,
+				component_tree: toApiComponentTree(local.component_tree)
+			} })).screen?.id;
+			if (newId != null) currentMappings = updateMapping(currentMappings, "screens", slug, newId);
+			results.push({
+				file,
+				action: "created",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "created",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	for (const file of changes.changed) {
+		const slug = slugFromPath(file);
+		const screenId = resolveSlugToId(currentMappings, "screens", slug);
+		if (screenId == null) {
+			results.push({
+				file,
+				action: "updated",
+				success: false,
+				error: `No mapping found for screen slug "${slug}"`
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+		try {
+			const local = await readPortalFile(portalDir, file);
+			await updateFluidOSScreen(client, defId, screenId, { screen: {
+				name: local.name,
+				slug,
+				component_tree: toApiComponentTree(local.component_tree)
+			} });
+			results.push({
+				file,
+				action: "updated",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "updated",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	for (const file of changes.deleted) {
+		const slug = slugFromPath(file);
+		const screenId = resolveSlugToId(currentMappings, "screens", slug);
+		if (screenId == null) {
+			results.push({
+				file,
+				action: "deleted",
+				success: false,
+				error: `No mapping found for screen slug "${slug}"`
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+		try {
+			await deleteFluidOSScreen(client, defId, screenId);
+			currentMappings = removeMapping(currentMappings, "screens", slug);
+			results.push({
+				file,
+				action: "deleted",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "deleted",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	return {
+		results,
+		mappings: currentMappings
+	};
+}
+/**
+* Push theme changes to the API.
+*/
+async function pushThemes(client, defId, portalDir, changes, mappings) {
+	const results = [];
+	let currentMappings = mappings;
+	for (const file of changes.new) {
+		const slug = slugFromPath(file);
+		try {
+			const local = await readPortalFile(portalDir, file);
+			const newId = (await createFluidOSTheme(client, defId, { theme: {
+				name: local.name,
+				active: local.active,
+				config: local.config
+			} })).theme?.id;
+			if (newId != null) currentMappings = updateMapping(currentMappings, "themes", slug, newId);
+			results.push({
+				file,
+				action: "created",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "created",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	for (const file of changes.changed) {
+		const slug = slugFromPath(file);
+		const themeId = resolveSlugToId(currentMappings, "themes", slug);
+		if (themeId == null) {
+			results.push({
+				file,
+				action: "updated",
+				success: false,
+				error: `No mapping found for theme slug "${slug}"`
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+		try {
+			const local = await readPortalFile(portalDir, file);
+			await updateFluidOSTheme(client, defId, themeId, { theme: {
+				name: local.name,
+				active: local.active,
+				config: local.config
+			} });
+			results.push({
+				file,
+				action: "updated",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "updated",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	for (const file of changes.deleted) {
+		const slug = slugFromPath(file);
+		const themeId = resolveSlugToId(currentMappings, "themes", slug);
+		if (themeId == null) {
+			results.push({
+				file,
+				action: "deleted",
+				success: false,
+				error: `No mapping found for theme slug "${slug}"`
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+		try {
+			await deleteFluidOSTheme(client, defId, themeId);
+			currentMappings = removeMapping(currentMappings, "themes", slug);
+			results.push({
+				file,
+				action: "deleted",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "deleted",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	return {
+		results,
+		mappings: currentMappings
+	};
+}
+/**
+* Resolve screen slug references to screen IDs in navigation items.
+* Returns a new tree with `screen_id` instead of `screen` slug,
+* shaped to match the FluidOSNavigationItemSyncItem schema.
+*/
+function resolveNavigationItemScreenIds(items, mappings) {
+	return items.map((item) => {
+		const screenId = item.screen ? resolveSlugToId(mappings, "screens", item.screen) ?? void 0 : void 0;
+		return {
+			...item.id ? { id: item.id } : {},
+			label: item.label ?? "",
+			position: item.position ?? 0,
+			icon: item.icon,
+			screen_id: screenId ?? null,
+			slug: item.slug,
+			source: item.source ?? "user",
+			parent_id: item.parent_id,
+			children: resolveNavigationItemScreenIds(item.children ?? [], mappings)
+		};
+	});
+}
+/**
+* Flatten a tree of navigation sync items into a flat list.
+* The API reconciliation logic requires a flat list to correctly
+* compare against the flat server response.
+*/
+function flattenNavigationItems(items) {
+	const flat = [];
+	for (const item of items) {
+		const { children, ...rest } = item;
+		flat.push(rest);
+		if (children && children.length > 0) flat.push(...flattenNavigationItems(children));
+	}
+	return flat;
+}
+/**
+* Push navigation changes to the API.
+*/
+async function pushNavigations(client, defId, portalDir, changes, mappings) {
+	const results = [];
+	let currentMappings = mappings;
+	for (const file of changes.new) {
+		const slug = slugFromPath(file);
+		try {
+			const local = await readPortalFile(portalDir, file);
+			const newId = (await createFluidOSNavigation(client, defId, { navigation: {
+				name: local.name,
+				platform: local.platform
+			} })).navigation?.id;
+			if (newId != null) {
+				currentMappings = updateMapping(currentMappings, "navigations", slug, newId);
+				const resolvedItems = flattenNavigationItems(resolveNavigationItemScreenIds(local.navigation_items, currentMappings));
+				const localToServerId = /* @__PURE__ */ new Map();
+				for (const item of resolvedItems) {
+					const resolvedParentId = item.parent_id != null ? localToServerId.get(item.parent_id) ?? item.parent_id : void 0;
+					const created = await createFluidOSNavigationItem(client, defId, newId, { navigation_item: {
+						label: item.label ?? "",
+						position: item.position ?? 0,
+						icon: item.icon ?? void 0,
+						screen_id: item.screen_id ?? void 0,
+						slug: item.slug ?? void 0,
+						source: item.source ?? void 0,
+						parent_id: resolvedParentId
+					} });
+					if (item.id != null && created.navigation_item?.id != null) localToServerId.set(item.id, created.navigation_item.id);
+				}
+			}
+			results.push({
+				file,
+				action: "created",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "created",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	for (const file of changes.changed) {
+		const slug = slugFromPath(file);
+		const navId = resolveSlugToId(currentMappings, "navigations", slug);
+		if (navId == null) {
+			results.push({
+				file,
+				action: "updated",
+				success: false,
+				error: `No mapping found for navigation slug "${slug}"`
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+		try {
+			const local = await readPortalFile(portalDir, file);
+			await updateFluidOSNavigation(client, defId, navId, { navigation: {
+				name: local.name,
+				platform: local.platform
+			} });
+			const resolvedItems = flattenNavigationItems(resolveNavigationItemScreenIds(local.navigation_items, currentMappings));
+			const serverItems = (await listFluidOSNavigationItems(client, defId, navId)).navigation_items ?? [];
+			const serverById = new Map(serverItems.map((s) => [s.id, s]));
+			const localIds = new Set(resolvedItems.filter((i) => i.id).map((i) => i.id));
+			for (const serverItem of serverItems) if (!localIds.has(serverItem.id)) await deleteFluidOSNavigationItem(client, defId, navId, serverItem.id);
+			const localToServerId = /* @__PURE__ */ new Map();
+			for (const item of resolvedItems) {
+				const resolvedParentId = item.parent_id != null ? localToServerId.get(item.parent_id) ?? item.parent_id : void 0;
+				const body = {
+					label: item.label,
+					position: item.position,
+					icon: item.icon ?? void 0,
+					screen_id: item.screen_id ?? void 0,
+					slug: item.slug ?? void 0,
+					source: item.source ?? void 0,
+					parent_id: resolvedParentId
+				};
+				if (item.id && serverById.has(item.id)) await updateFluidOSNavigationItem(client, defId, navId, item.id, { navigation_item: body });
+				else {
+					const created = await createFluidOSNavigationItem(client, defId, navId, { navigation_item: {
+						...body,
+						label: body.label ?? "",
+						position: body.position ?? 0
+					} });
+					if (item.id != null && created.navigation_item?.id != null) localToServerId.set(item.id, created.navigation_item.id);
+				}
+			}
+			results.push({
+				file,
+				action: "updated",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "updated",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	for (const file of changes.deleted) {
+		const slug = slugFromPath(file);
+		const navId = resolveSlugToId(currentMappings, "navigations", slug);
+		if (navId == null) {
+			results.push({
+				file,
+				action: "deleted",
+				success: false,
+				error: `No mapping found for navigation slug "${slug}"`
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+		try {
+			await deleteFluidOSNavigation(client, defId, navId);
+			currentMappings = removeMapping(currentMappings, "navigations", slug);
+			results.push({
+				file,
+				action: "deleted",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "deleted",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	return {
+		results,
+		mappings: currentMappings
+	};
+}
+/**
+* Push profile changes to the API.
+*/
+async function pushProfiles(client, defId, portalDir, changes, mappings) {
+	const results = [];
+	let currentMappings = mappings;
+	for (const file of changes.new) {
+		const slug = slugFromPath(file);
+		try {
+			const newId = (await createFluidOSProfile(client, defId, { profile: resolveProfileBody(await readPortalFile(portalDir, file), currentMappings) })).profile?.id;
+			if (newId != null) currentMappings = updateMapping(currentMappings, "profiles", slug, newId);
+			results.push({
+				file,
+				action: "created",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "created",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	for (const file of changes.changed) {
+		const slug = slugFromPath(file);
+		const profileId = resolveSlugToId(currentMappings, "profiles", slug);
+		if (profileId == null) {
+			results.push({
+				file,
+				action: "updated",
+				success: false,
+				error: `No mapping found for profile slug "${slug}"`
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+		try {
+			await updateFluidOSProfile(client, defId, profileId, { profile: resolveProfileBody(await readPortalFile(portalDir, file), currentMappings) });
+			results.push({
+				file,
+				action: "updated",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "updated",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	for (const file of changes.deleted) {
+		const slug = slugFromPath(file);
+		const profileId = resolveSlugToId(currentMappings, "profiles", slug);
+		if (profileId == null) {
+			results.push({
+				file,
+				action: "deleted",
+				success: false,
+				error: `No mapping found for profile slug "${slug}"`
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+		try {
+			await deleteFluidOSProfile(client, defId, profileId);
+			currentMappings = removeMapping(currentMappings, "profiles", slug);
+			results.push({
+				file,
+				action: "deleted",
+				success: true
+			});
+		} catch (err) {
+			results.push({
+				file,
+				action: "deleted",
+				success: false,
+				error: enrichedErrorMessage(err)
+			});
+			return {
+				results,
+				mappings: currentMappings
+			};
+		}
+	}
+	return {
+		results,
+		mappings: currentMappings
+	};
+}
+/**
+* Resolve profile slug references to API IDs for create/update request body.
+*/
+function resolveProfileBody(local, mappings) {
+	const body = {
+		name: local.name,
+		default: local.default,
+		permissions: local.permissions
+	};
+	if (local.navigation) {
+		const navId = resolveSlugToId(mappings, "navigations", local.navigation);
+		if (navId != null) body.navigation_id = navId;
+	}
+	if (local.mobile_navigation) {
+		const mobileNavId = resolveSlugToId(mappings, "navigations", local.mobile_navigation);
+		if (mobileNavId != null) body.mobile_navigation_id = mobileNavId;
+	}
+	body.theme_ids = local.themes.map((slug) => resolveSlugToId(mappings, "themes", slug)).filter((id) => id != null);
+	return body;
+}
+function printChangesSummary(diff, definitionName) {
+	console.log(chalk.blue("Changes to push for ") + chalk.white.bold(`"${definitionName}"`) + chalk.blue(":"));
+	console.log();
+	if (diff.new.length > 0) console.log(chalk.green("  New:     ") + diff.new.join(", "));
+	if (diff.changed.length > 0) console.log(chalk.yellow("  Changed: ") + diff.changed.join(", "));
+	if (diff.deleted.length > 0) console.log(chalk.red("  Deleted: ") + diff.deleted.join(", "));
+	console.log();
+}
+function printPushReport(results, skippedPhases) {
+	const succeeded = results.filter((r) => r.success);
+	const failed = results.filter((r) => !r.success);
+	if (succeeded.length > 0) {
+		console.log(chalk.green.bold("Succeeded:"));
+		for (const r of succeeded) console.log(chalk.green("  " + r.action + ": ") + r.file);
+	}
+	if (failed.length > 0) {
+		console.log();
+		console.log(chalk.red.bold("Failed:"));
+		for (const r of failed) console.log(chalk.red("  " + r.action + ": ") + r.file + chalk.gray(" — " + (r.error ?? "Unknown error")));
+	}
+	if (skippedPhases.length > 0) {
+		console.log();
+		console.log(chalk.yellow.bold("Skipped phases:"));
+		for (const phase of skippedPhases) console.log(chalk.yellow("  " + phase));
+	}
+}
+const pushCommand = new Command("push").description("Push local portal content changes to the Fluid OS API").option("--yes", "Skip confirmation prompt").action(async (options) => {
+	const cwd = process.cwd();
+	const portalDir = join(cwd, PORTAL_DIR);
+	const portalSyncDir = join(cwd, PORTAL_SYNC_DIR$1);
+	console.log();
+	console.log(chalk.blue.bold("Fluid Portal Push"));
+	console.log();
+	if (!existsSync(portalDir)) {
+		console.log(chalk.red("Error:") + " No portal/ directory found. Run " + chalk.cyan("fluid portal pull") + " first.");
+		console.log();
+		process.exit(1);
+	}
+	const snapshot = await readSnapshot(portalSyncDir);
+	if (!snapshot) {
+		console.log(chalk.red("Error:") + " No snapshot found in .portal-sync/. Run " + chalk.cyan("fluid portal pull") + " first.");
+		console.log();
+		process.exit(1);
+	}
+	const mappings = await readMappings(portalSyncDir);
+	if (!mappings) {
+		console.log(chalk.red("Error:") + " No mappings found in .portal-sync/. Run " + chalk.cyan("fluid portal pull") + " first.");
+		console.log();
+		process.exit(1);
+	}
+	const definitionId = snapshot.definition_id;
+	const definitionName = snapshot.definition;
+	console.log(chalk.gray("Definition: ") + chalk.white(definitionName) + chalk.gray(` (ID: ${definitionId})`));
+	console.log();
+	const spinner = ora();
+	spinner.start("Detecting changes...");
+	const diff = await diffAgainstSnapshot(portalDir, snapshot);
+	const totalChanges = diff.new.length + diff.changed.length + diff.deleted.length;
+	if (totalChanges === 0) {
+		spinner.succeed("Nothing to push.");
+		console.log();
+		return;
+	}
+	spinner.succeed(`Found ${totalChanges} change(s)`);
+	console.log();
+	printChangesSummary(diff, definitionName);
+	if (!options.yes) {
+		const { confirmed } = await prompts({
+			type: "confirm",
+			name: "confirmed",
+			message: `Push ${totalChanges} change(s) to Fluid OS?`,
+			initial: false
+		});
+		if (!confirmed) {
+			console.log();
+			console.log(chalk.gray("Push cancelled."));
+			console.log();
+			return;
+		}
+		console.log();
+	}
+	const changes = categorizeChanges(diff);
+	spinner.start("Validating cross-references...");
+	const validationErrors = await validateCrossReferences(portalDir, mappings, changes);
+	if (validationErrors.length > 0) {
+		spinner.fail("Cross-reference validation failed");
+		console.log();
+		for (const err of validationErrors) console.log(chalk.red("  " + err.file + ": ") + err.message);
+		console.log();
+		process.exit(1);
+	}
+	spinner.succeed("Cross-references valid");
+	spinner.start("Authenticating...");
+	let client;
+	try {
+		client = createClient$1();
+		spinner.succeed("Authenticated");
+	} catch (err) {
+		spinner.fail("Authentication failed");
+		console.log();
+		console.log(chalk.red("Error:") + " " + (err instanceof Error ? err.message : String(err)));
+		console.log();
+		process.exit(1);
+	}
+	const allResults = [];
+	const skippedPhases = [];
+	let currentMappings = mappings;
+	let aborted = false;
+	const hasScreenChanges = changes.screens.new.length > 0 || changes.screens.changed.length > 0 || changes.screens.deleted.length > 0;
+	const hasThemeChanges = changes.themes.new.length > 0 || changes.themes.changed.length > 0 || changes.themes.deleted.length > 0;
+	if (hasScreenChanges || hasThemeChanges) {
+		spinner.start("Phase 1: Pushing screens and themes...");
+		const phase1Tasks = [];
+		if (hasScreenChanges) phase1Tasks.push(pushScreens(client, definitionId, portalDir, changes.screens, currentMappings));
+		if (hasThemeChanges) phase1Tasks.push(pushThemes(client, definitionId, portalDir, changes.themes, currentMappings));
+		const phase1Results = await Promise.all(phase1Tasks);
+		for (const result of phase1Results) allResults.push(...result.results);
+		if (hasScreenChanges) currentMappings = {
+			...currentMappings,
+			screens: phase1Results[0].mappings.screens
+		};
+		if (hasThemeChanges) {
+			const idx = hasScreenChanges ? 1 : 0;
+			currentMappings = {
+				...currentMappings,
+				themes: phase1Results[idx].mappings.themes
+			};
+		}
+		if (phase1Results.some((r) => r.results.some((res) => !res.success))) {
+			spinner.fail("Phase 1 failed");
+			aborted = true;
+			skippedPhases.push("Phase 2: Navigations", "Phase 3: Profiles");
+		} else spinner.succeed("Phase 1 complete");
+	}
+	const hasNavChanges = changes.navigations.new.length > 0 || changes.navigations.changed.length > 0 || changes.navigations.deleted.length > 0;
+	if (!aborted && hasNavChanges) {
+		spinner.start("Phase 2: Pushing navigations...");
+		const navResult = await pushNavigations(client, definitionId, portalDir, changes.navigations, currentMappings);
+		allResults.push(...navResult.results);
+		currentMappings = {
+			...currentMappings,
+			navigations: navResult.mappings.navigations
+		};
+		if (navResult.results.some((r) => !r.success)) {
+			spinner.fail("Phase 2 failed");
+			aborted = true;
+			skippedPhases.push("Phase 3: Profiles");
+		} else spinner.succeed("Phase 2 complete");
+	} else if (aborted && hasNavChanges) {}
+	const hasProfileChanges = changes.profiles.new.length > 0 || changes.profiles.changed.length > 0 || changes.profiles.deleted.length > 0;
+	if (!aborted && hasProfileChanges) {
+		spinner.start("Phase 3: Pushing profiles...");
+		const profileResult = await pushProfiles(client, definitionId, portalDir, changes.profiles, currentMappings);
+		allResults.push(...profileResult.results);
+		currentMappings = {
+			...currentMappings,
+			profiles: profileResult.mappings.profiles
+		};
+		if (profileResult.results.some((r) => !r.success)) spinner.fail("Phase 3 failed");
+		else spinner.succeed("Phase 3 complete");
+	}
+	await writeMappings(portalSyncDir, currentMappings);
+	const successfulFiles = new Set(allResults.filter((r) => r.success).map((r) => r.file));
+	if (successfulFiles.size > 0) {
+		const updatedHashes = { ...snapshot.files };
+		for (const file of successfulFiles) {
+			const fullPath = join(portalDir, file);
+			if (existsSync(fullPath)) updatedHashes[file] = await computeFileHash(fullPath);
+			else delete updatedHashes[file];
+		}
+		await writeSnapshot(portalSyncDir, {
+			...snapshot,
+			files: updatedHashes
+		});
+	}
+	console.log();
+	if (allResults.every((r) => r.success) && !aborted) console.log(chalk.green.bold("Push complete!"));
+	else console.log(chalk.yellow.bold("Push completed with issues:"));
+	console.log();
+	printPushReport(allResults, skippedPhases);
+	console.log();
+});
+//#endregion
+//#region src/utils/widget-helpers.ts
+/**
+* Pure helper functions for widget scaffolding.
+* Extracted from widget-create command for testability.
+*/
+/**
+* Convert kebab-case name to PascalCase widget type.
+* e.g., "stock-ticker" → "StockTickerWidget"
+*/
+function toWidgetType(name) {
+	const pascal = name.split("-").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+	return pascal.endsWith("Widget") ? pascal : `${pascal}Widget`;
+}
+/**
+* Derive the component name from a widget type.
+* Strips the trailing "Widget" suffix, but only if the result is non-empty
+* and starts with a letter (not a digit).
+* e.g., "StockTickerWidget" → "StockTicker"
+*/
+function toComponentName(widgetType) {
+	if (widgetType === "Widget") return "Widget";
+	return widgetType.replace(/Widget$/, "") || widgetType;
+}
+/**
+* Convert kebab-case name to a display name.
+* e.g., "stock-ticker" → "Stock Ticker"
+*/
+function toDisplayName(name) {
+	return name.split("-").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join(" ");
+}
+/**
+* Convert kebab-case to camelCase.
+* e.g., "stock-ticker" → "stockTicker"
+*/
+function toCamelCase(name) {
+	return name.replace(/-./g, (x) => x.charAt(1).toUpperCase());
+}
+/**
+* Validate a widget name for scaffold.
+* Must be kebab-case, no trailing/consecutive dashes, no bare "widget".
+*/
+function validateWidgetName(name) {
+	if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name)) return "Widget name must be kebab-case with no trailing or consecutive dashes (e.g., stock-ticker).";
+	if (name === "widget") return "Widget name \"widget\" is reserved. Use a more descriptive name (e.g., custom-widget).";
+	return null;
+}
+/**
+* Insert an import line after the last import in a source file.
+* Skips if the import already exists (prevents duplicates on re-scaffold).
+* Returns null if no imports exist in the source.
+*/
+function insertImport(source, importLine) {
+	if (source.includes(importLine)) return source;
+	const lastImportIndex = source.lastIndexOf("import ");
+	if (lastImportIndex === -1) return null;
+	const lineEnd = source.indexOf("\n", lastImportIndex);
+	if (lineEnd === -1) return source + "\n" + importLine + "\n";
+	return source.slice(0, lineEnd + 1) + importLine + "\n" + source.slice(lineEnd + 1);
+}
+/**
+* Insert a manifest reference into the customWidgets array.
+* Preserves developer comments. Skips if already present.
+* Returns null if the array pattern isn't found.
+*/
+function insertIntoCustomWidgets(source, camelName) {
+	let matched = false;
+	const result = source.replace(/export const customWidgets:\s*WidgetManifest\[\]\s*=\s*\[([^\]]*)\]/, (_match, inner) => {
+		matched = true;
+		const lines = inner.split("\n");
+		const existingEntries = [];
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (trimmed && !trimmed.startsWith("//")) existingEntries.push(trimmed.replace(/,$/, ""));
+		}
+		if (existingEntries.includes(camelName)) return _match;
+		const commentLines = lines.filter((line) => line.trim().startsWith("//")).map((line) => line.trimEnd());
+		return `export const customWidgets: WidgetManifest[] = [${commentLines.length > 0 ? "\n" + commentLines.join("\n") : ""}\n${[...existingEntries, camelName].map((e) => `  ${e},`).join("\n")}\n]`;
+	});
+	return matched ? result : null;
 }
 //#endregion
+//#region src/commands/widget-create.ts
+const createSubcommand = new Command("create").description("Scaffold a new custom widget").argument("<name>", "Widget name in kebab-case (e.g., stock-ticker)").option("-c, --category <category>", "Widget category for palette grouping", "components").action(async (name, options) => {
+	const cwd = process.cwd();
+	const widgetDir = path.join(cwd, "src", "widgets", name);
+	const validationError = validateWidgetName(name);
+	if (validationError) {
+		console.error(chalk.red(`Error: ${validationError}`));
+		process.exit(1);
+	}
+	if (!fs.existsSync(path.join(cwd, "src", "portal.config.ts"))) {
+		console.error(chalk.red("Error: No src/portal.config.ts found."));
+		console.error(chalk.yellow("Run this command from a Fluid portal project root."));
+		process.exit(1);
+	}
+	if (fs.existsSync(widgetDir)) {
+		console.error(chalk.red(`Error: Widget directory already exists: src/widgets/${name}`));
+		process.exit(1);
+	}
+	const widgetType = toWidgetType(name);
+	const componentName = toComponentName(widgetType);
+	const displayName = toDisplayName(name);
+	const category = options.category ?? "components";
+	try {
+		await fs.ensureDir(widgetDir);
+		await fs.writeFile(path.join(widgetDir, "component.tsx"), `interface ${widgetType}Props {
+  title?: string;
+}
+
+export function ${componentName}({ title = "${displayName}" }: ${widgetType}Props) {
+  return (
+    <div className="p-4">
+      <h3 className="text-lg font-semibold">{title}</h3>
+      <p className="text-sm text-gray-500">
+        Edit this widget in src/widgets/${name}/component.tsx
+      </p>
+    </div>
+  );
+}
+`);
+		await fs.writeFile(path.join(widgetDir, "manifest.ts"), `import type { WidgetManifest } from "@fluid-app/portal-core/registries";
+import { ${componentName} } from "./component";
+
+export const manifest: WidgetManifest = {
+  manifestVersion: 1,
+  type: "${widgetType}",
+  component: ${componentName},
+  displayName: "${displayName}",
+  description: "A custom ${displayName.toLowerCase()} widget",
+  icon: "puzzle-piece",
+  category: "${category}",
+  propertySchema: {
+    widgetType: "${widgetType}",
+    displayName: "${displayName}",
+    fields: [{ key: "title", label: "Title", type: "text" }],
+  },
+  defaultProps: {
+    title: "${displayName}",
+  },
+};
+`);
+		await fs.writeFile(path.join(widgetDir, "index.ts"), `export { ${componentName} } from "./component";
+export { manifest } from "./manifest";
+`);
+	} catch (err) {
+		await fs.remove(widgetDir).catch(() => {});
+		console.error(chalk.red("Error: Failed to scaffold widget files."));
+		console.error(err);
+		process.exit(1);
+	}
+	const configPath = path.join(cwd, "src", "portal.config.ts");
+	const camelName = toCamelCase(name);
+	const importLine = `import { manifest as ${camelName} } from "./widgets/${name}";`;
+	const configSource = await fs.readFile(configPath, "utf-8");
+	const withImport = insertImport(configSource, importLine);
+	if (withImport === null) {
+		console.warn(chalk.yellow("Warning: Could not find import statements in portal.config.ts. Add the import manually:"));
+		console.warn(chalk.cyan(`  ${importLine}`));
+	}
+	const updated = insertIntoCustomWidgets(withImport ?? configSource, camelName);
+	if (updated === null) {
+		console.warn(chalk.yellow("Warning: Could not find customWidgets array in portal.config.ts. Add the manifest manually:"));
+		console.warn(chalk.cyan(`  ${camelName}`));
+	}
+	if (updated !== null) await fs.writeFile(configPath, updated, "utf-8");
+	else if (withImport !== null) await fs.writeFile(configPath, withImport, "utf-8");
+	console.log();
+	console.log(chalk.green("Created widget:") + ` src/widgets/${name}/`);
+	console.log(chalk.gray("  component.tsx  — React component"));
+	console.log(chalk.gray("  manifest.ts    — WidgetManifest"));
+	console.log(chalk.gray("  index.ts       — Re-exports"));
+	console.log();
+	if (updated !== null) {
+		console.log(chalk.green("Registered") + ` in ${chalk.cyan("src/portal.config.ts")}`);
+		console.log();
+	}
+	console.log(chalk.yellow("Next steps:"));
+	console.log(`  1. Edit the component in ${chalk.cyan(`src/widgets/${name}/component.tsx`)}`);
+	console.log(`  2. Customize the manifest fields in ${chalk.cyan(`src/widgets/${name}/manifest.ts`)}`);
+	console.log(`  3. Run ${chalk.cyan("fluid dev")} to preview in the builder`);
+});
+const widgetCommand = new Command("widget").description("Manage custom portal widgets").addCommand(createSubcommand);
+//#endregion
+//#region src/commands/doctor.ts
+/** Files that are managed by the SDK and should match the canonical template. */
+const INFRASTRUCTURE_FILES = [
+	"index.html",
+	"tsconfig.json",
+	"vite.config.ts",
+	".oxlintrc.json"
+];
+/** Entry files with expected content patterns after Phase 2 absorption. */
+const ENTRY_CHECKS = [{
+	file: "src/main.tsx",
+	expectedPattern: "createPortal",
+	hint: "main.tsx should use createPortal() from @fluid-app/portal-sdk. Run \"fluid create\" to see the latest template."
+}, {
+	file: "src/index.css",
+	expectedPattern: "@fluid-app/portal-sdk/globals.css",
+	hint: "index.css should import @fluid-app/portal-sdk/globals.css instead of inline theme tokens."
+}];
+/** Files that should NOT exist after Phase 2 (absorbed into SDK). */
+const REMOVED_FILES = [{
+	file: "src/App.tsx",
+	hint: "App.tsx is no longer needed — createPortal() handles the AppShell wiring internally."
+}, {
+	file: "src/fluid.config.ts",
+	hint: "fluid.config.ts is no longer needed — pass config overrides to createPortal() directly."
+}];
+function readFileOrNull(filePath) {
+	try {
+		return readFileSync(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+}
+const _currentDir = dirname(fileURLToPath(import.meta.url));
+function findTemplateDir() {
+	let dir = _currentDir;
+	while (!existsSync(join(dir, "package.json"))) {
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const templateDir = join(dir, "templates");
+	if (existsSync(join(templateDir, "base"))) return templateDir;
+	return null;
+}
+function checkInfrastructureDrift(cwd, templateDir) {
+	const diagnostics = [];
+	for (const file of INFRASTRUCTURE_FILES) {
+		const portalPath = join(cwd, file);
+		const templatePath = join(templateDir, "base", file);
+		if (!existsSync(portalPath)) {
+			diagnostics.push({
+				file,
+				severity: "warn",
+				message: `Missing file: ${file}`
+			});
+			continue;
+		}
+		if (!existsSync(templatePath)) continue;
+		const portalContent = readFileOrNull(portalPath);
+		const templateContent = readFileOrNull(templatePath);
+		if (portalContent !== null && templateContent !== null) {
+			if (portalContent.trim() !== templateContent.trim()) diagnostics.push({
+				file,
+				severity: "warn",
+				message: `Content differs from canonical template. Review and update if needed.`
+			});
+		}
+	}
+	return diagnostics;
+}
+function checkEntryPatterns(cwd) {
+	const diagnostics = [];
+	for (const check of ENTRY_CHECKS) {
+		const content = readFileOrNull(join(cwd, check.file));
+		if (content === null) {
+			diagnostics.push({
+				file: check.file,
+				severity: "error",
+				message: `Missing file. ${check.hint}`
+			});
+			continue;
+		}
+		if (!content.includes(check.expectedPattern)) diagnostics.push({
+			file: check.file,
+			severity: "warn",
+			message: `Does not contain expected pattern "${check.expectedPattern}". ${check.hint}`
+		});
+	}
+	return diagnostics;
+}
+function checkRemovedFiles(cwd) {
+	const diagnostics = [];
+	for (const check of REMOVED_FILES) if (existsSync(join(cwd, check.file))) diagnostics.push({
+		file: check.file,
+		severity: "info",
+		message: `File can be removed. ${check.hint}`
+	});
+	return diagnostics;
+}
+function formatDiagnostic(d) {
+	return `  ${d.severity === "error" ? chalk.red("ERROR") : d.severity === "warn" ? chalk.yellow(" WARN") : chalk.blue(" INFO")}  ${chalk.bold(d.file)}\n         ${chalk.dim(d.message)}`;
+}
+const doctorCommand = new Command("doctor").description("Check portal for scaffold drift and report stale infrastructure files").action(async () => {
+	const cwd = process.cwd();
+	const packageJsonPath = join(cwd, "package.json");
+	if (!existsSync(packageJsonPath)) {
+		console.error(chalk.red("Error: No package.json found in current directory"));
+		console.error(chalk.yellow("Make sure you're in a Fluid portal project directory"));
+		process.exit(1);
+	}
+	let packageJson;
+	try {
+		packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+	} catch {
+		console.error(chalk.red("Error: Could not parse package.json"));
+		console.error(chalk.yellow("Ensure package.json contains valid JSON"));
+		process.exit(1);
+	}
+	if (!{
+		...packageJson.dependencies,
+		...packageJson.devDependencies
+	}["@fluid-app/portal-sdk"]) {
+		console.error(chalk.red("Error: @fluid-app/portal-sdk not found in dependencies"));
+		console.error(chalk.yellow("This command must be run from a Fluid portal project directory"));
+		process.exit(1);
+	}
+	console.log();
+	console.log(chalk.bold("Fluid Portal Doctor"));
+	console.log(chalk.dim("Checking for scaffold drift...\n"));
+	const diagnostics = [];
+	diagnostics.push(...checkEntryPatterns(cwd));
+	diagnostics.push(...checkRemovedFiles(cwd));
+	const templateDir = findTemplateDir();
+	if (templateDir) diagnostics.push(...checkInfrastructureDrift(cwd, templateDir));
+	else console.log(chalk.dim("  (Skipping infrastructure diff — template files not available)\n"));
+	if (diagnostics.length === 0) {
+		console.log(chalk.green("  All clear — no drift detected.\n"));
+		return;
+	}
+	const errors = diagnostics.filter((d) => d.severity === "error");
+	const warns = diagnostics.filter((d) => d.severity === "warn");
+	const infos = diagnostics.filter((d) => d.severity === "info");
+	for (const d of [
+		...errors,
+		...warns,
+		...infos
+	]) {
+		console.log(formatDiagnostic(d));
+		console.log();
+	}
+	const parts = [];
+	if (errors.length > 0) parts.push(chalk.red(`${errors.length} error(s)`));
+	if (warns.length > 0) parts.push(chalk.yellow(`${warns.length} warning(s)`));
+	if (infos.length > 0) parts.push(chalk.blue(`${infos.length} info`));
+	console.log(`  ${parts.join(", ")}\n`);
+	if (errors.length > 0) process.exit(1);
+});
+//#endregion
+//#region src/commands/version.ts
+const PORTAL_SYNC_DIR = ".portal-sync";
+function getApiBase() {
+	return process.env["FLUID_API_BASE"] ?? "https://api.fluid.app";
+}
+function requireToken() {
+	const token = getAuthToken();
+	if (!token) {
+		console.error(chalk.red("Error:") + " Not logged in. Run " + chalk.cyan("`fluid login`") + " first.");
+		process.exit(1);
+	}
+	return token;
+}
+function createClient(token) {
+	return createFetchClient({
+		baseUrl: getApiBase(),
+		getAuthToken: () => token
+	});
+}
+async function requireDefinitionId() {
+	const cwd = process.cwd();
+	const mappings = await readMappings(path.join(cwd, PORTAL_SYNC_DIR));
+	if (!mappings) {
+		console.error(chalk.red("Error:") + " No definition pulled. Run " + chalk.cyan("`fluid portal pull`") + " first.");
+		process.exit(1);
+	}
+	return mappings.definition.id;
+}
+const createVersionCommand = new Command("create").description("Create a new version (snapshot) of the portal definition").option("--activate", "Activate the version immediately after creation").action(async (options) => {
+	const client = createClient(requireToken());
+	const definitionId = await requireDefinitionId();
+	console.log();
+	console.log(chalk.bold("Creating version..."));
+	let result;
+	try {
+		result = await createFluidOSVersion(client, definitionId);
+	} catch (err) {
+		console.error(chalk.red("Error:") + " Failed to create version — " + (err instanceof Error ? err.message : String(err)));
+		process.exit(1);
+	}
+	const version = result.version;
+	if (!version?.id) {
+		console.error(chalk.red("Error:") + " Failed to create version — unexpected response.");
+		process.exit(1);
+	}
+	console.log();
+	console.log(chalk.green("Version created successfully."));
+	console.log();
+	console.log(chalk.gray("Version ID: ") + chalk.white(version.id));
+	let active = version.active ?? false;
+	if (options.activate) {
+		console.log("Activating version...");
+		try {
+			await updateFluidOSVersion(client, definitionId, version.id, { version: { active: true } });
+		} catch (err) {
+			console.error(chalk.red("Error:") + " Failed to activate version — " + (err instanceof Error ? err.message : String(err)));
+			process.exit(1);
+		}
+		active = true;
+	}
+	console.log(chalk.gray("Active:     ") + (active ? chalk.green("yes") : chalk.gray("no")));
+	console.log();
+});
+const listVersionCommand = new Command("list").description("List all versions of the portal definition").action(async () => {
+	const client = createClient(requireToken());
+	const definitionId = await requireDefinitionId();
+	let result;
+	try {
+		result = await listFluidOSVersions(client, definitionId);
+	} catch (err) {
+		console.error(chalk.red("Error:") + " Failed to list versions — " + (err instanceof Error ? err.message : String(err)));
+		process.exit(1);
+	}
+	const versions = result.version;
+	if (!Array.isArray(versions) || versions.length === 0) {
+		console.log();
+		console.log(chalk.yellow("No versions found."));
+		console.log("Run " + chalk.cyan("`fluid portal version create`") + " to publish a version.");
+		console.log();
+		return;
+	}
+	console.log();
+	const COL_ID = "Version ID".padEnd(36);
+	const COL_ACT = "Active".padEnd(6);
+	console.log(chalk.gray(`  ${COL_ID}  ${COL_ACT}  Published`));
+	for (const v of versions) {
+		const id = String(v.id).padEnd(36);
+		const active = v.active ? chalk.green("✓") + "     " : "      ";
+		const published = v.published_at ? new Date(v.published_at).toLocaleString() : "—";
+		console.log(`  ${id}  ${active}  ${published}`);
+	}
+	console.log();
+});
+const activateVersionCommand = new Command("activate").description("Activate a specific version, making it the live version").argument("<version-id>", "The version ID to activate").option("-y, --yes", "Skip confirmation prompt").action(async (versionId, options) => {
+	const client = createClient(requireToken());
+	const definitionId = await requireDefinitionId();
+	if (!options.yes) {
+		const { confirm } = await prompts({
+			type: "confirm",
+			name: "confirm",
+			message: `Activate version ${versionId}? This will make it the live version.`,
+			initial: false
+		});
+		if (!confirm) {
+			console.log(chalk.yellow("Aborted."));
+			return;
+		}
+	}
+	console.log();
+	console.log(chalk.bold("Activating version..."));
+	try {
+		await updateFluidOSVersion(client, definitionId, versionId, { version: { active: true } });
+	} catch (err) {
+		console.error(chalk.red("Error:") + " Failed to activate version — " + (err instanceof Error ? err.message : String(err)));
+		process.exit(1);
+	}
+	console.log();
+	console.log(chalk.green("Version " + versionId + " is now active."));
+	console.log();
+});
+const versionCommand = new Command("version").description("Manage portal definition versions").addCommand(createVersionCommand).addCommand(listVersionCommand).addCommand(activateVersionCommand);
+//#endregion
 //#region src/index.ts
+/**
+* @fluid-app/fluid-cli-portal
+*
+* Fluid CLI plugin for building and deploying portal applications.
+* Auto-discovered by @fluid-app/fluid-cli via the fluid-cli-* naming convention.
+*/
 const plugin = {
 	name: "fluid-cli-portal",
 	version: "0.1.0",
 	async register(ctx) {
-		registerCreateCommand(ctx);
-		registerDevCommand(ctx);
-		registerBuildCommand(ctx);
-		registerDeployCommand(ctx);
-		registerDestroyCommand(ctx);
+		const portal = new Command("portal").description("Build, develop, and deploy portal applications");
+		portal.addCommand(createCommand);
+		portal.addCommand(devCommand);
+		portal.addCommand(buildCommand);
+		portal.addCommand(deployCommand);
+		portal.addCommand(destroyCommand);
+		portal.addCommand(pullCommand);
+		portal.addCommand(pushCommand);
+		portal.addCommand(widgetCommand);
+		portal.addCommand(doctorCommand);
+		portal.addCommand(versionCommand);
+		ctx.program.addCommand(portal);
 	}
 };
 //#endregion
-export { CLOUD_RUN_ERRORS, FILE_SYSTEM_ERRORS, FLUID_API_ERROR, TEMPLATES, TURSO_ERROR, copyTemplate, copyTemplateSafe, createCommand, createDatabase, createDatabaseToken, createDirectory, createDirectorySafe, plugin as default, deleteCloudRunService, deleteDatabase, deployToCloudRun, destroyCommand, directoryExists, ensureGroup, fetchLocations, fileExists, getGcpProject, getInstallCommand, getRunCommand, getSdkVersion, getSdkVersionSafe, getTemplatePaths, installDependencies, isTemplateName, parseOrgList, pathExists, promptProjectConfig, provisionDatabase, readFileSafe, resolveFluidApiKey, resolveTursoConfig, runPackageManager, validateFluidApiKey, validateGcloudAuth, validateGcloudInstalled, validateLocation, validateTursoConfig, writeFileSafe };
+export { CLOUD_RUN_ERRORS, FILE_SYSTEM_ERRORS, FLUID_API_ERROR, TEMPLATES, TURSO_ERROR, buildIdToSlugMap, buildNavigationIdToSlugMap, buildSnapshot, buildThemeIdToSlugMap, categorizeChanges, computeFileHash, copyTemplate, copyTemplateSafe, createCommand, createDatabase, createDatabaseToken, createDirectory, createDirectorySafe, plugin as default, deleteCloudRunService, deleteDatabase, deployToCloudRun, deriveScreenSlug, deriveSlug, destroyCommand, diffAgainstSnapshot, directoryExists, doctorCommand, ensureGroup, fetchLocations, fileExists, getGcpProject, getInstallCommand, getRunCommand, getSdkVersion, getSdkVersionSafe, getTemplatePaths, installDependencies, isTemplateName, parseOrgList, pathExists, promptProjectConfig, provisionDatabase, pullCommand, pushCommand, readFileSafe, readMappings, readSnapshot, removeMapping, resolveFluidApiKey, resolveIdToSlug, resolveSlugToId, resolveTursoConfig, runPackageManager, slugFromPath, transformNavigation, transformNavigationItems, transformProfile, transformScreen, transformTheme, updateMapping, validateCrossReferences, validateFluidApiKey, validateGcloudAuth, validateGcloudInstalled, validateLocation, validateTursoConfig, versionCommand, widgetCommand, writeFileSafe, writeMappings, writeSnapshot };
 
 //# sourceMappingURL=index.mjs.map