@fluid-app/fluid-cli-portal 0.1.8 → 0.1.10

package/dist/index.mjs

@@ -1,13 +1,14 @@
+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 path, { 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, readFileSync } 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$1 from "path";
@@ -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";
@@ -1929,9 +1973,6 @@ 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) => {
@@ -2068,9 +2109,930 @@ 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
 /**
@@ -2138,7 +3100,7 @@ function insertImport(source, importLine) {
 */
 function insertIntoCustomWidgets(source, camelName) {
 	let matched = false;
-	const result = source.replace(/export const customWidgets:\s*WidgetManifest\[\]\s*=\s*\[([^\]]*)\]/, (_match, inner) => {
+	const result = source.replace(/(export const customWidgets(?::\s*WidgetManifest\[\])?)\s*=\s*\[([^\]]*)\]/, (_match, declaration, inner) => {
 		matched = true;
 		const lines = inner.split("\n");
 		const existingEntries = [];
@@ -2148,7 +3110,7 @@ function insertIntoCustomWidgets(source, camelName) {
 		}
 		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 `${declaration} = [${commentLines.length > 0 ? "\n" + commentLines.join("\n") : ""}\n${[...existingEntries, camelName].map((e) => `  ${e},`).join("\n")}\n]`;
 	});
 	return matched ? result : null;
 }
@@ -2251,12 +3213,9 @@ export { manifest } from "./manifest";
 	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`);
+	console.log(`  3. Run ${chalk.cyan("fluid portal dev")} to preview in the builder`);
 });
 const widgetCommand = new Command("widget").description("Manage custom portal widgets").addCommand(createSubcommand);
-function registerWidgetCommand(ctx) {
-	ctx.program.addCommand(widgetCommand);
-}
 //#endregion
 //#region src/commands/doctor.ts
 /** Files that are managed by the SDK and should match the canonical template. */
@@ -2416,25 +3375,155 @@ const doctorCommand = new Command("doctor").description("Check portal for scaffo
 	console.log(`  ${parts.join(", ")}\n`);
 	if (errors.length > 0) process.exit(1);
 });
-function registerDoctorCommand(ctx) {
-	ctx.program.addCommand(doctorCommand);
+//#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);
-		registerWidgetCommand(ctx);
-		registerDoctorCommand(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, doctorCommand, ensureGroup, fetchLocations, fileExists, getGcpProject, getInstallCommand, getRunCommand, getSdkVersion, getSdkVersionSafe, getTemplatePaths, installDependencies, isTemplateName, parseOrgList, pathExists, promptProjectConfig, provisionDatabase, readFileSafe, resolveFluidApiKey, resolveTursoConfig, runPackageManager, validateFluidApiKey, validateGcloudAuth, validateGcloudInstalled, validateLocation, validateTursoConfig, widgetCommand, 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