@fluid-app/fluid-cli-portal 0.1.38 → 0.1.39

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { A as fluid_os_v0_create_fluid_osversion, B as fluid_os_v0_update_fluid_osnavigation_item, C as writeMappings, D as fluid_os_v0_create_fluid_osprofile, E as fluid_os_v0_create_fluid_osnavigation_item, F as fluid_os_v0_delete_fluid_osscreen, G as createFetchClient, H as fluid_os_v0_update_fluid_osscreen, I as fluid_os_v0_delete_fluid_ostheme, L as fluid_os_v0_list_fluid_osnavigation_items, M as fluid_os_v0_delete_fluid_osnavigation, N as fluid_os_v0_delete_fluid_osnavigation_item, O as fluid_os_v0_create_fluid_osscreen, P as fluid_os_v0_delete_fluid_osprofile, R as fluid_os_v0_list_fluid_osversions, S as updateMapping, T as fluid_os_v0_create_fluid_osnavigation, U as fluid_os_v0_update_fluid_ostheme, V as fluid_os_v0_update_fluid_osprofile, W as fluid_os_v0_update_fluid_osversion, _ 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 fluid_os_v0_create_widget_package_version, k as fluid_os_v0_create_fluid_ostheme, 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 fluid_os_v0_complete_widget_package_version_upload, x as resolveSlugToId, y as removeMapping, z as fluid_os_v0_update_fluid_osnavigation } from "./pull-zrTaJuSb.mjs";
+import { A as fluid_os_v0_create_fluid_osversion, B as fluid_os_v0_update_fluid_osnavigation, C as writeMappings, D as fluid_os_v0_create_fluid_osprofile, E as fluid_os_v0_create_fluid_osnavigation_item, F as fluid_os_v0_delete_fluid_osscreen, G as fluid_os_v0_update_fluid_osversion, H as fluid_os_v0_update_fluid_osprofile, I as fluid_os_v0_delete_fluid_ostheme, K as createFetchClient, L as fluid_os_v0_list_fluid_osdefinitions, M as fluid_os_v0_delete_fluid_osnavigation, N as fluid_os_v0_delete_fluid_osnavigation_item, O as fluid_os_v0_create_fluid_osscreen, P as fluid_os_v0_delete_fluid_osprofile, R as fluid_os_v0_list_fluid_osnavigation_items, S as updateMapping, T as fluid_os_v0_create_fluid_osnavigation, U as fluid_os_v0_update_fluid_osscreen, V as fluid_os_v0_update_fluid_osnavigation_item, W as fluid_os_v0_update_fluid_ostheme, _ 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 fluid_os_v0_create_widget_package_version, k as fluid_os_v0_create_fluid_ostheme, 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 fluid_os_v0_complete_widget_package_version_upload, x as resolveSlugToId, y as removeMapping, z as fluid_os_v0_list_fluid_osversions } from "./pull-CG5dELOX.mjs";
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import chalk from "chalk";
@@ -575,6 +575,292 @@ async function gitInit(cwd) {
 		return false;
 	}
 }
+/** Is `cwd` inside a git work tree? Cheap, never throws. */
+async function isGitRepo(cwd) {
+	try {
+		const { stdout } = await execa("git", ["rev-parse", "--is-inside-work-tree"], { cwd });
+		return stdout.trim() === "true";
+	} catch {
+		return false;
+	}
+}
+/** Read `git remote get-url origin` (or null if no origin / not a repo). */
+async function getOriginUrl(cwd) {
+	try {
+		const { stdout } = await execa("git", [
+			"remote",
+			"get-url",
+			"origin"
+		], { cwd });
+		return stdout.trim();
+	} catch {
+		return null;
+	}
+}
+/**
+* Are there uncommitted changes (working tree or index)? `git status
+* --porcelain` is empty when clean. Returns false (never throws) when
+* `cwd` isn't a repo.
+*/
+async function hasUncommittedChanges(cwd) {
+	try {
+		const { stdout } = await execa("git", ["status", "--porcelain"], { cwd });
+		return stdout.trim().length > 0;
+	} catch {
+		return false;
+	}
+}
+/**
+* Fetch `branch` from a token-bearing remote URL, writing FETCH_HEAD so
+* `gitAheadBehindVsFetchHead` is meaningful. Token comes through
+* GIT_ASKPASS, never argv or `.git/config`.
+*/
+async function gitFetch(cwd, remoteUrl, branch = "main") {
+	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
+	try {
+		await execa("git", [
+			"-c",
+			"credential.helper=",
+			"fetch",
+			"--quiet",
+			cleanUrl,
+			branch
+		], {
+			cwd,
+			env
+		});
+	} catch (err) {
+		throw toGitError(err, "fetch");
+	}
+}
+/**
+* Count commits in local HEAD vs FETCH_HEAD (after `gitFetch`). Returns
+* `{ahead, behind}`. `0/0` means "in sync" (or no FETCH_HEAD yet).
+*/
+async function gitAheadBehindVsFetchHead(cwd) {
+	try {
+		const { stdout } = await execa("git", [
+			"rev-list",
+			"--left-right",
+			"--count",
+			"HEAD...FETCH_HEAD"
+		], { cwd });
+		const [a, b] = stdout.trim().split(/\s+/);
+		const ahead = Number.parseInt(a ?? "0", 10);
+		const behind = Number.parseInt(b ?? "0", 10);
+		return {
+			ahead: Number.isFinite(ahead) ? ahead : 0,
+			behind: Number.isFinite(behind) ? behind : 0
+		};
+	} catch {
+		return {
+			ahead: 0,
+			behind: 0
+		};
+	}
+}
+/** Does `cwd` have any commits yet? (false right after `git init`.) */
+async function hasCommits(cwd) {
+	try {
+		await execa("git", [
+			"rev-parse",
+			"--verify",
+			"HEAD"
+		], { cwd });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Does `branch` exist on the remote? Throws on transport/auth failure so
+* a network blip is never mistaken for an empty remote (which would skip
+* drift detection). Token via GIT_ASKPASS, never argv or .git/config.
+*/
+async function gitRemoteBranchExists(cwd, remoteUrl, branch = "main") {
+	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
+	try {
+		const { stdout } = await execa("git", [
+			"-c",
+			"credential.helper=",
+			"ls-remote",
+			"--heads",
+			cleanUrl,
+			`refs/heads/${branch}`
+		], {
+			cwd,
+			env
+		});
+		return stdout.trim().length > 0;
+	} catch (err) {
+		throw toGitError(err, "ls-remote");
+	}
+}
+/**
+* Adopt `FETCH_HEAD` as the current (unborn) branch's base: point the
+* branch ref at it and load its tree into the index, leaving the working
+* tree untouched. The next auto-commit then records the local project
+* tree as a child of the remote history — local files win, remote-only
+* files are recorded as deletions — so the push fast-forwards instead of
+* being rejected for unrelated history. Only call when `hasCommits` is
+* false; with local commits it would silently rewrite the branch ref.
+* Mirrors the widget CLI's first-push adoption (the backend provisions
+* repos with an auto-init/template commit, so a fresh root commit is
+* always unrelated history).
+*
+* Returns the number of remote commits adopted.
+*/
+async function gitAdoptFetchHead(cwd) {
+	try {
+		await execa("git", [
+			"reset",
+			"--mixed",
+			"FETCH_HEAD"
+		], { cwd });
+		const { stdout } = await execa("git", [
+			"rev-list",
+			"--count",
+			"FETCH_HEAD"
+		], { cwd });
+		const count = Number.parseInt(stdout.trim(), 10);
+		return Number.isFinite(count) ? count : 0;
+	} catch (err) {
+		throw toGitError(err, "adopt remote history");
+	}
+}
+/**
+* Normalize a git remote URL to `host/owner/repo` for identity
+* comparison — strips credentials, protocol, `.git`, and trailing
+* slashes so a token-bearing minted URL compares equal to the stored
+* origin. Returns null when the URL doesn't parse.
+*/
+function normalizedRepoIdentity(remoteUrl) {
+	const scp = remoteUrl.match(/^(?:[^@/\s]+@)?([^:/\s]+):([^/].*)$/);
+	if (scp?.[1] && scp[2] && !remoteUrl.includes("://")) {
+		const path = scp[2].replace(/\.git$/, "").replace(/\/+$/, "");
+		return `${scp[1]}/${path}`.toLowerCase();
+	}
+	if (remoteUrl.startsWith("/") || remoteUrl.startsWith(".")) return remoteUrl.replace(/\.git$/, "").replace(/\/+$/, "").toLowerCase();
+	try {
+		const u = new URL(remoteUrl);
+		const path = u.pathname.replace(/\.git$/, "").replace(/\/+$/, "").replace(/^\/+/, "");
+		return `${u.host}/${path}`.toLowerCase();
+	} catch {
+		return null;
+	}
+}
+/**
+* Do HEAD and FETCH_HEAD share any common ancestor? False for unrelated
+* histories — the guard that keeps a whole-tree auto-commit of the WRONG
+* repository from being pushed to a portal's remote. Never throws.
+*/
+async function hasCommonAncestorWithFetchHead(cwd) {
+	try {
+		await execa("git", [
+			"merge-base",
+			"HEAD",
+			"FETCH_HEAD"
+		], { cwd });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Fast-forward HEAD to FETCH_HEAD. Fails (non-zero exit) if not
+*  fast-forwardable — callers check the ahead-count first. */
+async function gitMergeFastForward(cwd) {
+	try {
+		await execa("git", [
+			"merge",
+			"--ff-only",
+			"FETCH_HEAD"
+		], { cwd });
+	} catch (err) {
+		throw toGitError(err, "fast-forward merge");
+	}
+}
+/**
+* `git add -A && git commit -m <message>`.
+*
+* `git add -A` intentionally stages the whole work tree: a portal's
+* provisioned repo tracks the entire project (it's seeded from the
+* starter template), and the "publish my changes" UX expects every edit
+* to ship — the same stance as `fluid mist push`. The exclusion boundary
+* is the project's `.gitignore` (the starter ignores `.env`,
+* `node_modules/`, `dist/`, `.portal-sync/`, logs, `*.tsbuildinfo`), so
+* generated output and local secrets stay out of the commit.
+*
+* Uses the repo's configured identity, else a synthetic Fluid bot
+* identity so the commit isn't rejected. "nothing to commit" is treated
+* as a no-op, not an error.
+*/
+async function gitAutoCommit(cwd, message) {
+	try {
+		await execa("git", ["add", "-A"], { cwd });
+	} catch (err) {
+		throw toGitError(err, "add");
+	}
+	let hasName = false;
+	let hasEmail = false;
+	try {
+		hasName = (await execa("git", ["config", "user.name"], { cwd })).stdout.trim().length > 0;
+	} catch {}
+	try {
+		hasEmail = (await execa("git", ["config", "user.email"], { cwd })).stdout.trim().length > 0;
+	} catch {}
+	const identityArgs = [...hasName ? [] : ["-c", "user.name=Fluid Portal CLI"], ...hasEmail ? [] : ["-c", "user.email=portal@fluid.app"]];
+	try {
+		await execa("git", [
+			...identityArgs,
+			"commit",
+			"-m",
+			message
+		], {
+			cwd,
+			stdio: [
+				"ignore",
+				"inherit",
+				"pipe"
+			]
+		});
+	} catch (err) {
+		const missing = gitMissingError(err);
+		if (missing) throw missing;
+		const e = err;
+		const streams = `${typeof e.stdout === "string" ? e.stdout : ""}\n${typeof e.stderr === "string" ? e.stderr : ""}`;
+		if (/nothing to commit/i.test(streams)) return;
+		throw toGitError(err, "commit");
+	}
+}
+/**
+* `git push <cleanUrl> HEAD:<branch>` — credentials supplied via
+* GIT_ASKPASS, never argv. `http.…/.extraheader=` clears any cached
+* Authorization header a CI-style config might inject.
+*/
+async function gitPush(cwd, remoteUrl, branch = "main") {
+	const { cleanUrl, env } = gitAuthSpawn(remoteUrl);
+	try {
+		await execa("git", [
+			"-c",
+			"credential.helper=",
+			"-c",
+			"http.https://github.com/.extraheader=",
+			"push",
+			cleanUrl,
+			`HEAD:${branch}`
+		], {
+			cwd,
+			env,
+			stdio: [
+				"ignore",
+				"inherit",
+				"inherit"
+			]
+		});
+	} catch (err) {
+		throw toGitError(err, "push");
+	}
+}
 //#endregion
 //#region src/utils/scaffold-github.ts
 /**
@@ -863,7 +1149,7 @@ async function autoPull(cwd) {
 	console.log(chalk.yellow("No portal/ directory found.") + " Attempting to pull content...");
 	console.log();
 	try {
-		const { pullCommand } = await import("./pull-zrTaJuSb.mjs").then((n) => n.n);
+		const { pullCommand } = await import("./pull-CG5dELOX.mjs").then((n) => n.n);
 		await pullCommand.parseAsync([], { from: "user" });
 		return hasPortalContent(cwd);
 	} catch (err) {
@@ -1541,6 +1827,181 @@ function validateNavigationItems(items, file, validScreenSlugs, errors) {
 	}
 }
 //#endregion
+//#region src/api/git-credential.ts
+/**
+* Build the portal git-credential path for a definition id.
+*
+* Matches GitSync Phase 006 (fluid-commerce/fluid #19596): a member
+* route on the company-scoped definitions resource —
+* `POST /api/company/fluid_os/definitions/:id/git_credential`.
+*/
+function portalGitCredentialPath(definitionId) {
+	return `/api/company/fluid_os/definitions/${definitionId}/git_credential`;
+}
+function extractErrorReason(body, fallback) {
+	if (body && typeof body === "object" && "error" in body) {
+		const error = body.error;
+		if (error && typeof error === "object" && "message" in error) {
+			const message = error.message;
+			if (typeof message === "string" && message.length > 0) return message;
+		}
+	}
+	return fallback;
+}
+/**
+* Request a git credential for the portal definition's provisioned repo.
+*
+* Never throws — every failure maps to an `unavailable`/`error` outcome
+* so the invisible-git sync is strictly best-effort.
+*/
+async function createPortalGitCredential(options) {
+	const { baseUrl, token, definitionId } = options;
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const url = `${baseUrl.replace(/\/$/, "")}${portalGitCredentialPath(definitionId)}`;
+	let resp;
+	try {
+		resp = await fetchImpl(url, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${token}`,
+				Accept: "application/json"
+			}
+		});
+	} catch (err) {
+		return {
+			status: "error",
+			reason: err instanceof Error ? err.message : String(err)
+		};
+	}
+	if (resp.status === 404) return {
+		status: "unavailable",
+		reason: "git sync isn't available for portals on this Fluid API yet"
+	};
+	const body = await resp.json().catch(() => null);
+	if (!resp.ok) {
+		const reason = extractErrorReason(body, `git credential request failed (HTTP ${resp.status})`);
+		if (resp.status === 409) return {
+			status: "unavailable",
+			reason
+		};
+		return {
+			status: "error",
+			reason
+		};
+	}
+	const credential = body?.git_credential;
+	if (!credential?.remote_url) return {
+		status: "error",
+		reason: "git credential response missing remote_url"
+	};
+	return {
+		status: "ok",
+		credential
+	};
+}
+//#endregion
+//#region src/lib/git-sync.ts
+/**
+* Invisible-git sync for `fluid portal push`.
+*
+* Before the normal content push, we best-effort mirror the local portal
+* project to its provisioned GitHub repo: fetch → fast-forward-pull if a
+* teammate pushed → auto-commit working-tree changes → push HEAD:main.
+* This mirrors `fluid mist push`, but is STRICTLY non-fatal: any problem
+* (no git, no repo, credential endpoint missing, diverged history,
+* network blip) degrades to a skip so the content push always proceeds.
+*/
+/**
+* Run the best-effort git sync. Returns a result describing what
+* happened; never throws. Callers surface `skipped` reasons as a dim
+* note and continue.
+*/
+async function runPortalGitSync(options) {
+	const { cwd, baseUrl, token, definitionId, commitMessage } = options;
+	const branch = options.branch ?? "main";
+	if (!await isGitRepo(cwd) && !await gitInit(cwd)) return {
+		status: "skipped",
+		reason: "not a git repository"
+	};
+	const outcome = await createPortalGitCredential({
+		baseUrl,
+		token,
+		definitionId,
+		fetchImpl: options.fetchImpl
+	});
+	if (outcome.status !== "ok") return {
+		status: "skipped",
+		reason: outcome.reason
+	};
+	const remoteUrl = outcome.credential.remote_url;
+	const origin = await getOriginUrl(cwd);
+	if (origin) {
+		const originId = normalizedRepoIdentity(origin);
+		const mintedId = normalizedRepoIdentity(remoteUrl);
+		if (mintedId && originId !== mintedId) return {
+			status: "skipped",
+			reason: `this directory's git origin (${originId ?? origin}) is not the portal's provisioned repository (${mintedId}) — are you in the right project directory?`
+		};
+	}
+	try {
+		if (!await hasCommits(cwd)) {
+			if (await gitRemoteBranchExists(cwd, remoteUrl, branch)) {
+				await gitFetch(cwd, remoteUrl, branch);
+				await gitAdoptFetchHead(cwd);
+			}
+			if (await hasUncommittedChanges(cwd)) await gitAutoCommit(cwd, commitMessage);
+			return await pushCommitted(cwd, remoteUrl, branch);
+		}
+		await gitFetch(cwd, remoteUrl, branch);
+		if (!await hasCommonAncestorWithFetchHead(cwd)) return {
+			status: "skipped",
+			reason: "this repository's history is unrelated to the portal's provisioned repository — are you in the right project directory?"
+		};
+		const { ahead, behind } = await gitAheadBehindVsFetchHead(cwd);
+		if (behind > 0 && ahead > 0) return {
+			status: "skipped",
+			reason: "local branch and origin have diverged — run `git pull --rebase` and retry"
+		};
+		if (behind > 0) {
+			if (await hasUncommittedChanges(cwd)) return {
+				status: "skipped",
+				reason: "origin has newer commits and you have uncommitted changes — run `git pull` and retry"
+			};
+			await gitMergeFastForward(cwd);
+		}
+		if (await hasUncommittedChanges(cwd)) await gitAutoCommit(cwd, commitMessage);
+		return await pushCommitted(cwd, remoteUrl, branch);
+	} catch (err) {
+		return {
+			status: "skipped",
+			reason: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+/**
+* The push gets its own failure boundary: by this point the auto-commit
+* (and any fast-forward) has already mutated local git state. A push
+* failure here is FATAL to the content push (matching `fluid widget
+* push`): publishing artifacts whose source never reached the repo is
+* exactly the drift the invisible-git model exists to prevent. The
+* local commit is durable — rerunning push finds the branch ahead and
+* retries the sync.
+*/
+async function pushCommitted(cwd, remoteUrl, branch) {
+	try {
+		await gitPush(cwd, remoteUrl, branch);
+	} catch (err) {
+		return {
+			status: "failed",
+			reason: `your changes are committed locally but couldn't be pushed (${err instanceof Error ? err.message : String(err)}) — nothing was published; rerun \`fluid portal push\` to retry`
+		};
+	}
+	return {
+		status: "synced",
+		pushed: true
+	};
+}
+//#endregion
 //#region src/commands/push.ts
 /**
 * `fluid portal push` command
@@ -1564,7 +2025,7 @@ function toApiComponentTree(tree) {
 /**
 * Create an authenticated FetchClient using the stored CLI profile.
 */
-function createClient$1() {
+function createClient$2() {
 	const token = getAuthToken();
 	if (!token) {
 		const profile = getActiveProfile();
@@ -1586,6 +2047,32 @@ function enrichedErrorMessage(err) {
 	return msg;
 }
 /**
+* Best-effort "invisible git" sync: commit the local project and push it
+* to the portal's provisioned GitHub repo before the content push. Never
+* throws — every failure is reported as a dim note and swallowed so the
+* content push always runs.
+*/
+async function runInvisibleGitSync(cwd, definitionId, definitionName) {
+	const token = getAuthToken();
+	if (!token) return;
+	const baseUrl = process.env["FLUID_API_BASE"] ?? "https://api.fluid.app";
+	const commitMessage = `Portal push: ${definitionName} · ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace("T", " ")}`;
+	const spinner = ora("Syncing project to git…").start();
+	const result = await runPortalGitSync({
+		cwd,
+		baseUrl,
+		token,
+		definitionId,
+		commitMessage
+	});
+	if (result.status === "synced") spinner.succeed("Synced project to git");
+	else if (result.status === "failed") {
+		spinner.fail("Git sync failed");
+		throw new Error(result.reason);
+	} else spinner.info(chalk.gray(`Skipped git sync — ${result.reason}`));
+	console.log();
+}
+/**
 * Read and parse a JSON file from the portal directory.
 */
 async function readPortalFile(portalDir, relativePath) {
@@ -2193,6 +2680,7 @@ const pushCommand = new Command("push").description("Push local portal content c
 	const definitionName = snapshot.definition;
 	console.log(chalk.gray("Definition: ") + chalk.white(definitionName) + chalk.gray(` (ID: ${definitionId})`));
 	console.log();
+	await runInvisibleGitSync(cwd, definitionId, definitionName);
 	const spinner = ora();
 	spinner.start("Detecting changes...");
 	const diff = await diffAgainstSnapshot(portalDir, snapshot);
@@ -2234,7 +2722,7 @@ const pushCommand = new Command("push").description("Push local portal content c
 	spinner.start("Authenticating...");
 	let client;
 	try {
-		client = createClient$1();
+		client = createClient$2();
 		spinner.succeed("Authenticated");
 	} catch (err) {
 		spinner.fail("Authentication failed");
@@ -2322,6 +2810,114 @@ const pushCommand = new Command("push").description("Push local portal content c
 	console.log();
 });
 //#endregion
+//#region src/commands/clone.ts
+/**
+* `fluid portal clone [app]` — mints a fresh git credential for a Fluid
+* OS portal definition and clones its provisioned GitHub repo into
+* `./<slug>/`. Mirrors `fluid mist clone` (credential → clone), but
+* against the portal git-credential endpoint.
+*
+* The credential endpoint is part of GitSync phase 006; until it ships
+* the request 404s and we print a friendly "not available yet" message
+* instead of a raw git error.
+*/
+function getBaseUrl() {
+	return process.env["FLUID_API_BASE"] ?? "https://api.fluid.app";
+}
+function createClient$1(token) {
+	return createFetchClient({
+		baseUrl: getBaseUrl(),
+		getAuthToken: () => token
+	});
+}
+/** Select a definition by --app name, else interactively. */
+async function selectDefinition(client, appName) {
+	const definitions = [];
+	let page = 1;
+	while (true) {
+		const response = await fluid_os_v0_list_fluid_osdefinitions(client, {
+			page,
+			per_page: 500
+		});
+		const batch = response.definitions ?? [];
+		definitions.push(...batch);
+		const totalPages = response.meta?.total_pages ?? 1;
+		if (page >= totalPages || batch.length === 0) break;
+		page++;
+	}
+	if (definitions.length === 0) throw new Error("No Fluid OS definitions found. Create one in the admin dashboard first.");
+	if (appName) {
+		const match = definitions.find((d) => d.name?.toLowerCase() === appName.toLowerCase());
+		if (!match || match.id == null) {
+			const available = definitions.map((d) => chalk.cyan(d.name ?? "(unnamed)")).join(", ");
+			throw new Error(`No definition found matching "${appName}". Available: ${available}`);
+		}
+		return {
+			id: match.id,
+			name: match.name ?? `portal-${match.id}`
+		};
+	}
+	const { definitionId } = await prompts({
+		type: "select",
+		name: "definitionId",
+		message: "Select a Fluid OS definition to clone",
+		choices: definitions.filter((d) => d.id != null).map((d) => ({
+			title: d.name ?? "(unnamed)",
+			value: d.id
+		}))
+	});
+	if (definitionId == null) throw new Error("No definition selected.");
+	const selected = definitions.find((d) => d.id === definitionId);
+	if (!selected || selected.id == null) throw new Error("Selected definition not found.");
+	return {
+		id: selected.id,
+		name: selected.name ?? `portal-${selected.id}`
+	};
+}
+const cloneCommand = new Command("clone").description("Clone a portal definition's provisioned GitHub repo (mints a fresh token per call)").argument("[app]", "Definition name (prompts to select when omitted)").option("--app <name>", "Definition name (same as the positional argument)").option("--dir <dir>", "Target directory (defaults to ./<slug>/)").action(async (appArg, options) => {
+	try {
+		await ensureGitAvailable();
+		const token = getAuthToken();
+		if (!token) {
+			const profile = getActiveProfile();
+			throw new Error(profile ? `No auth token for profile ${chalk.cyan(profile.name)}. Run ${chalk.cyan("fluid login")}.` : `Not logged in. Run ${chalk.cyan("fluid login")} first.`);
+		}
+		const client = createClient$1(token);
+		const spinner = ora("Resolving definition…").start();
+		const definition = await selectDefinition(client, options.app ?? appArg);
+		spinner.text = "Minting git credential…";
+		const outcome = await createPortalGitCredential({
+			baseUrl: getBaseUrl(),
+			token,
+			definitionId: definition.id
+		});
+		if (outcome.status !== "ok") {
+			spinner.warn(`Can't clone — ${outcome.reason}`);
+			process.exit(1);
+		}
+		const slug = deriveSlug(definition.name);
+		const targetDir = resolve(options.dir ?? slug);
+		if (existsSync(targetDir)) {
+			spinner.fail(`Directory ${targetDir} already exists. Pass --dir or remove it first.`);
+			process.exit(1);
+		}
+		spinner.text = `Cloning into ${slug}/…`;
+		try {
+			await gitClone(outcome.credential.remote_url, targetDir);
+		} catch (err) {
+			spinner.fail("git clone failed");
+			throw err;
+		}
+		spinner.succeed(`Cloned into ${chalk.cyan(targetDir)}`);
+		console.log(chalk.dim(`  cd ${slug}`));
+		console.log(chalk.dim(`  ${chalk.cyan("fluid portal pull")} to sync content`));
+	} catch (error) {
+		console.log();
+		console.log(chalk.red("Error:") + " " + (error instanceof Error ? error.message : String(error)));
+		process.exit(1);
+	}
+});
+//#endregion
 //#region src/utils/widget-helpers.ts
 /**
 * Pure helper functions for widget scaffolding.
@@ -5620,6 +6216,7 @@ const plugin = {
 		portal.addCommand(buildCommand);
 		portal.addCommand(pullCommand);
 		portal.addCommand(pushCommand);
+		portal.addCommand(cloneCommand);
 		portal.addCommand(deployCommand);
 		portal.addCommand(widgetCommand);
 		portal.addCommand(doctorCommand);
@@ -5628,6 +6225,6 @@ const plugin = {
 	}
 };
 //#endregion
-export { CANONICAL_PROJECT_NAME, FILE_SYSTEM_ERRORS, GitError, TEMPLATES, TEMPLATE_REPO_URL, WIDGET_PACKAGE_BUILDER_VERSION, WidgetPackageUploadError, buildIdToSlugMap, buildNavigationIdToSlugMap, buildSharedWidgetPackage, buildSnapshot, buildThemeIdToSlugMap, buildWidgetPackageCompleteUploadPayload, buildWidgetPackageDescriptor, buildWidgetPackageUploadSessionPayload, categorizeChanges, collectWidgetPackageArtifacts, completeWidgetPackageUpload, computeArtifactMetadata, computeFileHash, copyTemplate, copyTemplateSafe, createAuthenticatedWidgetPackageClient, createCommand, createDirectory, createDirectorySafe, createPublishManifestMetadata, createWidgetPackageEntrySource, createWidgetPackagePublishRequest, plugin as default, deployCommand, deriveScreenSlug, deriveSlug, diffAgainstSnapshot, directoryExists, doctorCommand, ensureGitAvailable, fileExists, getArtifactContentType, getInstallCommand, getRunCommand, getSdkVersion, getSdkVersionSafe, getTemplatePaths, getWidgetPackageCompleteUploadRoute, getWidgetPackageUploadSessionRoute, gitClone, gitInit, gitMissingError, installDependencies, isGitAvailable, loadSourceWidgetPackages, normalizeWidgetPackageCompleteResponse, normalizeWidgetPackageUploadSession, pathExists, printDryRunSessionPayload, printRuntimeOnlyNotice, printWidgetPublishSummary, promptProjectConfig, publishWidgetPackageVersion, publishWidgetRuntimeArtifacts, pullCommand, pushCommand, readFileSafe, readMappings, readSnapshot, removeMapping, requestWidgetPackageUploadSession, resolveIdToSlug, resolvePortalWidgetSourceConfig, resolveSlugToId, rewriteProjectName, runPackageManager, scaffoldFromGitHub, sha256, slugFromPath, topLevelWidgetCommand, transformNavigation, transformNavigationItems, transformProfile, transformScreen, transformTheme, updateMapping, uploadWidgetPackageArtifacts, validateCrossReferences, validateSingleSourceWidgetPackage, validateWidgetPublishOutDir, versionCommand, widgetCommand, writeFileSafe, writeFluidrcProfile, writeMappings, writeSnapshot };
+export { CANONICAL_PROJECT_NAME, FILE_SYSTEM_ERRORS, GitError, TEMPLATES, TEMPLATE_REPO_URL, WIDGET_PACKAGE_BUILDER_VERSION, WidgetPackageUploadError, buildIdToSlugMap, buildNavigationIdToSlugMap, buildSharedWidgetPackage, buildSnapshot, buildThemeIdToSlugMap, buildWidgetPackageCompleteUploadPayload, buildWidgetPackageDescriptor, buildWidgetPackageUploadSessionPayload, categorizeChanges, cloneCommand, collectWidgetPackageArtifacts, completeWidgetPackageUpload, computeArtifactMetadata, computeFileHash, copyTemplate, copyTemplateSafe, createAuthenticatedWidgetPackageClient, createCommand, createDirectory, createDirectorySafe, createPortalGitCredential, createPublishManifestMetadata, createWidgetPackageEntrySource, createWidgetPackagePublishRequest, plugin as default, deployCommand, deriveScreenSlug, deriveSlug, diffAgainstSnapshot, directoryExists, doctorCommand, ensureGitAvailable, fileExists, getArtifactContentType, getInstallCommand, getOriginUrl, getRunCommand, getSdkVersion, getSdkVersionSafe, getTemplatePaths, getWidgetPackageCompleteUploadRoute, getWidgetPackageUploadSessionRoute, gitAheadBehindVsFetchHead, gitAutoCommit, gitClone, gitFetch, gitInit, gitMergeFastForward, gitMissingError, gitPush, hasUncommittedChanges, installDependencies, isGitAvailable, isGitRepo, loadSourceWidgetPackages, normalizeWidgetPackageCompleteResponse, normalizeWidgetPackageUploadSession, pathExists, portalGitCredentialPath, printDryRunSessionPayload, printRuntimeOnlyNotice, printWidgetPublishSummary, promptProjectConfig, publishWidgetPackageVersion, publishWidgetRuntimeArtifacts, pullCommand, pushCommand, readFileSafe, readMappings, readSnapshot, removeMapping, requestWidgetPackageUploadSession, resolveIdToSlug, resolvePortalWidgetSourceConfig, resolveSlugToId, rewriteProjectName, runPackageManager, runPortalGitSync, scaffoldFromGitHub, sha256, slugFromPath, topLevelWidgetCommand, transformNavigation, transformNavigationItems, transformProfile, transformScreen, transformTheme, updateMapping, uploadWidgetPackageArtifacts, validateCrossReferences, validateSingleSourceWidgetPackage, validateWidgetPublishOutDir, versionCommand, widgetCommand, writeFileSafe, writeFluidrcProfile, writeMappings, writeSnapshot };
 
 //# sourceMappingURL=index.mjs.map