@fluid-app/fluid-cli-mist 0.1.47 → 0.1.48

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -1,12 +1,12 @@
 import { Command, InvalidArgumentError, Option } from "commander";
 import chalk from "chalk";
 import { getAuthToken, getConfigDir, gitSyncActorFromMe, gitSyncCommitSubject, parseNameStatusZ, resolveGitSyncActor, summarizeChanges } from "@fluid-app/fluid-cli";
+import { randomUUID } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import path, { join, resolve } from "node:path";
 import os from "node:os";
 import { execa } from "execa";
 import ora from "ora";
-import { randomUUID } from "node:crypto";
 import prompts from "prompts";
 import open from "open";
 //#region src/api/client.ts
@@ -166,6 +166,181 @@ async function restoreMist(client, slug) {
 	return client.post(`${BASE$4}/${id}/restore`);
 }
 //#endregion
+//#region src/api/branch_environments.ts
+/**
+* Branch environments and branch operations for a Mist project.
+*
+* Server contracts (Rails, internal API v2026-04):
+*   apps/rails/docs/openapi/internal/mist-branch-environments-v2026-04.yaml
+*   apps/rails/docs/openapi/internal/mist-branch-operations-v2026-04.yaml
+*
+* Every response is checked at runtime before a caller sees it. A server
+* whose listing has no `capability` block predates branch environments and
+* reads as unsupported. A response that does not match the contract throws
+* `BranchContractError`; neither case is ever a reason to fall back to a
+* production publish.
+*/
+const ENVIRONMENT_STATES = [
+	"provisioning",
+	"ready",
+	"error",
+	"expired",
+	"deleting"
+];
+const OPERATION_KINDS = [
+	"ensure_staging",
+	"create",
+	"delete",
+	"promote",
+	"publish"
+];
+const OPERATION_STATES = [
+	"queued",
+	"running",
+	"awaiting_content",
+	"awaiting_resolution",
+	"retryable_failure",
+	"succeeded",
+	"failed",
+	"cancelled",
+	"stale"
+];
+/** States after which the server will not advance the operation again. */
+const TERMINAL_OPERATION_STATES = [
+	"succeeded",
+	"failed",
+	"cancelled",
+	"stale"
+];
+/** A server response that does not match the branch environments contract. */
+var BranchContractError = class extends Error {
+	constructor(message) {
+		super(`Unexpected branch environments response: ${message}`);
+		this.name = "BranchContractError";
+	}
+};
+const SOURCE_REVISION = /^[0-9a-f]{40}$/;
+const OPERATION_KEY = /^[A-Za-z0-9._:-]{1,128}$/;
+function base(mistId) {
+	return `/api/v202604/mists/${mistId}`;
+}
+/** List the project's branch environments and what the server offers. */
+async function listBranchEnvironments(client, slug) {
+	const id = await resolveMistId(client, slug);
+	return parseListing(await client.get(`${base(id)}/branch-environments`));
+}
+/**
+* Request the staging branch at `sourceRevision`. Reusing `operationKey`
+* with the same revision returns the same operation, so a caller persists
+* the key before calling and retries with it.
+*/
+async function requestStaging(client, slug, request) {
+	if (!SOURCE_REVISION.test(request.sourceRevision)) throw new Error("Source revision must be a full 40-character commit SHA");
+	if (!OPERATION_KEY.test(request.operationKey)) throw new Error("Operation key must be 1-128 of A-Z a-z 0-9 . _ : -");
+	const id = await resolveMistId(client, slug);
+	return parseOperationEnvelope(await client.post(`${base(id)}/branch-environments/staging`, { source_revision: request.sourceRevision }, { "X-Operation-Key": request.operationKey }));
+}
+/** Read one branch operation of the project. Never advances it. */
+async function fetchBranchOperation(client, slug, operationId) {
+	const id = await resolveMistId(client, slug);
+	return parseOperationEnvelope(await client.get(`${base(id)}/branch-operations/${encodeURIComponent(operationId)}`));
+}
+/** A fresh key for a new staging request. */
+function newOperationKey() {
+	return `staging-${randomUUID()}`;
+}
+function isTerminal(operation) {
+	return TERMINAL_OPERATION_STATES.includes(operation.state);
+}
+function parseListing(body) {
+	const envelope = record(body, "response");
+	return {
+		environments: array(envelope["environments"], "environments").map((item, index) => parseEnvironment(item, `environments[${index}]`)),
+		capability: parseCapability(envelope["capability"])
+	};
+}
+function parseCapability(raw) {
+	if (raw === void 0) return { supported: false };
+	const capability = record(raw, "capability");
+	const version = capability["version"];
+	if (typeof version !== "number" || !Number.isInteger(version) || version < 1) throw new BranchContractError("capability.version is not a positive integer");
+	const staging = record(capability["staging"], "capability.staging");
+	return {
+		supported: true,
+		version,
+		staging: {
+			available: boolean(staging["available"], "capability.staging.available"),
+			reason: nullableString(staging["reason"], "capability.staging.reason"),
+			active_operation_id: nullableString(staging["active_operation_id"], "capability.staging.active_operation_id")
+		}
+	};
+}
+function parseEnvironment(raw, path) {
+	const environment = record(raw, path);
+	const url = nullableString(environment["url"], `${path}.url`);
+	if (url !== null && !url.startsWith("https://")) throw new BranchContractError(`${path}.url is not an https address`);
+	return {
+		id: string(environment["id"], `${path}.id`),
+		slug: string(environment["slug"], `${path}.slug`),
+		state: member(environment["state"], ENVIRONMENT_STATES, `${path}.state`),
+		seeded: boolean(environment["seeded"], `${path}.seeded`),
+		url,
+		created_at: string(environment["created_at"], `${path}.created_at`),
+		updated_at: string(environment["updated_at"], `${path}.updated_at`)
+	};
+}
+function parseOperationEnvelope(body) {
+	return parseOperation(record(body, "response")["operation"]);
+}
+function parseOperation(raw) {
+	const operation = record(raw, "operation");
+	const progress = record(operation["progress"], "operation.progress");
+	const sourceRevision = string(operation["source_revision"], "operation.source_revision");
+	if (!SOURCE_REVISION.test(sourceRevision)) throw new BranchContractError("operation.source_revision is not a commit SHA");
+	return {
+		id: string(operation["id"], "operation.id"),
+		kind: member(operation["kind"], OPERATION_KINDS, "operation.kind"),
+		state: member(operation["state"], OPERATION_STATES, "operation.state"),
+		source_revision: sourceRevision,
+		branch_id: nullableString(operation["branch_id"], "operation.branch_id"),
+		progress: {
+			database_isolated: boolean(progress["database_isolated"], "operation.progress.database_isolated"),
+			branch_published: boolean(progress["branch_published"], "operation.progress.branch_published"),
+			build_ready: boolean(progress["build_ready"], "operation.progress.build_ready")
+		},
+		failure: parseFailure(operation["failure"]),
+		created_at: string(operation["created_at"], "operation.created_at"),
+		updated_at: string(operation["updated_at"], "operation.updated_at")
+	};
+}
+function parseFailure(raw) {
+	if (raw === null) return null;
+	return { type: string(record(raw, "operation.failure")["type"], "operation.failure.type") };
+}
+function record(raw, path) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new BranchContractError(`${path} is not an object`);
+	return raw;
+}
+function array(raw, path) {
+	if (!Array.isArray(raw)) throw new BranchContractError(`${path} is not a list`);
+	return raw;
+}
+function string(raw, path) {
+	if (typeof raw !== "string") throw new BranchContractError(`${path} is not a string`);
+	return raw;
+}
+function nullableString(raw, path) {
+	return raw === null ? null : string(raw, path);
+}
+function boolean(raw, path) {
+	if (typeof raw !== "boolean") throw new BranchContractError(`${path} is not a boolean`);
+	return raw;
+}
+function member(raw, allowed, path) {
+	if (typeof raw !== "string" || !allowed.includes(raw)) throw new BranchContractError(`${path} has an unknown value`);
+	return raw;
+}
+//#endregion
 //#region src/lib/hostable.ts
 const SHORTHAND = {
 	droplet: "Droplet::Application",
@@ -830,6 +1005,133 @@ function readMistFileFrom(dir = process.cwd()) {
 	return readMistFile(dir);
 }
 //#endregion
+//#region src/lib/staging.ts
+/** A staging step the user can act on, as opposed to a server fault. */
+var StagingUnavailableError = class extends Error {
+	reason;
+	activeOperationId;
+	constructor(reason, message, activeOperationId = null) {
+		super(message);
+		this.name = "StagingUnavailableError";
+		this.reason = reason;
+		this.activeOperationId = activeOperationId;
+	}
+};
+/** The operation stopped without succeeding. */
+var StagingOperationFailedError = class extends Error {
+	operation;
+	constructor(operation) {
+		const cause = operation.failure ? ` (${operation.failure.type})` : "";
+		super(`Staging ${operation.state}${cause}. Operation ${operation.id}.`);
+		this.name = "StagingOperationFailedError";
+		this.operation = operation;
+	}
+};
+/** The local wait ran out; the server keeps working on the operation. */
+var StagingWaitTimeoutError = class extends Error {
+	operation;
+	constructor(operation) {
+		super(`Still ${operation.state} after the wait limit. The server keeps working on it; follow it with \`fluid mist staging wait --operation ${operation.id}\`.`);
+		this.name = "StagingWaitTimeoutError";
+		this.operation = operation;
+	}
+};
+const UNSUPPORTED = "This Fluid server doesn't support branch environments yet, so there is no staging to use. Nothing was published.";
+/** Why staging can't be requested now, in words a user can act on. */
+function describeUnavailable(staging) {
+	switch (staging.reason) {
+		case "feature_disabled": return "Branch environments aren't enabled for this company.";
+		case "execution_unavailable": return "Staging isn't running on the server right now. Try again later.";
+		case "hosting_unavailable": return "This mist isn't live, so it can't have a staging environment.";
+		case "credentials_not_retired": return "This mist's production credentials still reach preview builds. A Fluid operator has to retire them before staging can be used.";
+		case "operation_in_progress": return `Staging is already being prepared (operation ${staging.active_operation_id ?? "unknown"}). Follow it with \`fluid mist staging wait\`.`;
+		case "environment_deleting": return "Staging is being torn down. Request it again once it's removed.";
+		case "staging_exists": return "Staging already exists. It can't be requested again until it's torn down.";
+		case "quota_exceeded": return "This company has reached its branch environment limit.";
+		default: return `Staging isn't available right now (${staging.reason ?? "no reason given"}).`;
+	}
+}
+/** Where staging stands: capability, the staging environment and any run. */
+async function readStagingStatus(client, slug) {
+	const listing = await listBranchEnvironments(client, slug);
+	if (!listing.capability.supported) throw new StagingUnavailableError("unsupported", UNSUPPORTED);
+	const { staging } = listing.capability;
+	const activeOperation = staging.active_operation_id ? await fetchBranchOperation(client, slug, staging.active_operation_id) : null;
+	return {
+		capability: {
+			version: listing.capability.version,
+			staging
+		},
+		environment: listing.environments.find((env) => env.seeded) ?? null,
+		activeOperation
+	};
+}
+/**
+* Request staging at a revision. A key the caller passes is retried even
+* while the capability reports a run in progress, because that run may be
+* the one this key started. Throws `StagingOperationFailedError` when the
+* key returns an operation that already failed, was cancelled or went stale.
+*/
+async function admitStaging(client, slug, request) {
+	if (!request.operationKey) {
+		const listing = await listBranchEnvironments(client, slug);
+		if (!listing.capability.supported) throw new StagingUnavailableError("unsupported", UNSUPPORTED);
+		const { staging } = listing.capability;
+		if (!staging.available) throw new StagingUnavailableError(staging.reason ?? "unavailable", describeUnavailable(staging), staging.active_operation_id);
+	}
+	const operationKey = request.operationKey ?? newOperationKey();
+	request.onOperationKey?.(operationKey);
+	const operation = await requestStaging(client, slug, {
+		sourceRevision: request.sourceRevision,
+		operationKey
+	});
+	if (isTerminal(operation) && operation.state !== "succeeded") throw new StagingOperationFailedError(operation);
+	return operation;
+}
+/**
+* Poll the staging operation until it finishes. Resolves on success;
+* throws `StagingUnavailableError` for an operation that isn't a staging
+* request, `StagingOperationFailedError` on any other terminal state and
+* `StagingWaitTimeoutError` when the local wait runs out, which never
+* cancels the server operation.
+*/
+async function waitForOperation(client, slug, operationId, options) {
+	const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const now = options.now ?? Date.now;
+	const deadline = now() + options.timeoutMs;
+	let lastSeen = "";
+	for (;;) {
+		const operation = await fetchBranchOperation(client, slug, operationId);
+		if (operation.kind !== "ensure_staging") throw new StagingUnavailableError("not_a_staging_operation", `Operation ${operation.id} is a ${operation.kind} operation, not a staging request. Follow staging with \`fluid mist staging wait\`.`);
+		const seen = JSON.stringify([
+			operation.state,
+			operation.progress,
+			operation.failure
+		]);
+		if (seen !== lastSeen) {
+			lastSeen = seen;
+			options.onChange?.(operation);
+		}
+		if (isTerminal(operation)) {
+			if (operation.state === "succeeded") return operation;
+			throw new StagingOperationFailedError(operation);
+		}
+		if (now() >= deadline) throw new StagingWaitTimeoutError(operation);
+		await sleep(options.intervalMs);
+	}
+}
+/** One line describing an operation's progress, for stderr. */
+function describeProgress(operation) {
+	const { progress } = operation;
+	const steps = [
+		`database ${progress.database_isolated ? "isolated" : "pending"}`,
+		`branch ${progress.branch_published ? "published" : "pending"}`,
+		`build ${progress.build_ready ? "ready" : "pending"}`
+	].join(", ");
+	const failure = operation.failure ? `, last error ${operation.failure.type}` : "";
+	return `${operation.state}: ${steps}${failure}`;
+}
+//#endregion
 //#region src/lib/error-handler.ts
 /**
 * Centralized error handling — maps thrown errors to spec'd exit codes
@@ -856,6 +1158,14 @@ function handle(err) {
 		console.error(chalk.red(err.message));
 		process.exit(1);
 	}
+	if (err instanceof StagingUnavailableError || err instanceof StagingWaitTimeoutError) {
+		console.error(chalk.yellow(err.message));
+		process.exit(1);
+	}
+	if (err instanceof StagingOperationFailedError || err instanceof BranchContractError) {
+		console.error(chalk.red(err.message));
+		process.exit(3);
+	}
 	if (err instanceof MistApiError) {
 		if (err.status === 403) {
 			const action = err.details?.["permission"];
@@ -3838,6 +4148,70 @@ function printSummary(summary, options = {}) {
 /** `fluid mist droplet` — sub-command aggregator for the attached Droplet. */
 const dropletCommand = new Command("droplet").description("Repair, reinstall, or set egress for the Mist's attached Droplet").addCommand(dropletRepairCommand).addCommand(dropletReinstallCommand).addCommand(dropletEgressProxyCommand);
 //#endregion
+//#region src/commands/staging/status.ts
+/** `fluid mist staging status` — where staging stands. */
+const stagingStatusCommand = new Command("status").description("Show the staging environment and whether it can be requested").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--json", "Emit the status as JSON").action((slug, opts) => runAction(async () => {
+	const status = await readStagingStatus(createMistClient(), resolveSlug(slug));
+	if (opts.json) return printJson({
+		capability: status.capability,
+		environment: status.environment,
+		active_operation: status.activeOperation
+	});
+	const { environment, activeOperation, capability } = status;
+	if (environment) {
+		console.log(`Staging: ${chalk.bold(environment.state)}`);
+		if (environment.url) console.log(`URL: ${chalk.cyan(environment.url)}`);
+	} else console.log(chalk.dim("No staging environment yet."));
+	if (activeOperation) console.log(`Operation ${activeOperation.id}: ${describeProgress(activeOperation)}`);
+	console.log(capability.staging.available ? "Staging can be requested with `fluid mist staging request --revision <sha>`." : chalk.yellow(describeUnavailable(capability.staging)));
+}));
+//#endregion
+//#region src/commands/staging/wait.ts
+/** `fluid mist staging wait` — follow a staging operation to the end. */
+const POLL_INTERVAL_MS = 5e3;
+const DEFAULT_TIMEOUT_MINUTES = 30;
+/** Polling options for a `--timeout <minutes>` flag, progress on stderr. */
+function waitOptions(timeout) {
+	const minutes = timeout ? Number(timeout) : DEFAULT_TIMEOUT_MINUTES;
+	if (!Number.isFinite(minutes) || minutes <= 0) throw new Error("--timeout must be a positive number of minutes");
+	return {
+		intervalMs: POLL_INTERVAL_MS,
+		timeoutMs: minutes * 6e4,
+		onChange: (operation) => process.stderr.write(`${describeProgress(operation)}\n`)
+	};
+}
+const stagingWaitCommand = new Command("wait").description("Follow a staging operation until it finishes").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").option("--operation <id>", "Operation to follow (defaults to the one preparing staging)").option("--timeout <minutes>", "How long to follow it (default 30)").option("--json", "Emit the finished operation as JSON").action((slug, opts) => runAction(async () => {
+	const resolved = resolveSlug(slug);
+	const client = createMistClient();
+	const options = waitOptions(opts.timeout);
+	const operationId = opts.operation ?? (await readStagingStatus(client, resolved)).activeOperation?.id;
+	if (!operationId) throw new Error("No staging operation is running. Check `fluid mist staging status`.");
+	const operation = await waitForOperation(client, resolved, operationId, options);
+	if (opts.json) return printJson({ operation });
+	console.log("✔ Staging is ready. Run `fluid mist staging status` for its URL.");
+}));
+//#endregion
+//#region src/commands/staging/request.ts
+/** `fluid mist staging request` — request staging at a revision. */
+const stagingRequestCommand = new Command("request").description("Request the staging environment at a pushed commit").argument("[slug]", "The mist slug (defaults to .mist file in CWD)").requiredOption("--revision <sha>", "Full 40-character SHA of a commit already on the mist's repository").option("--operation-key <key>", "Resume an interrupted request with the key it printed").option("--wait", "Follow the operation until staging is ready").option("--timeout <minutes>", "How long --wait follows it (default 30)").option("--json", "Emit the operation as JSON").action((slug, opts) => runAction(async () => {
+	const resolved = resolveSlug(slug);
+	const client = createMistClient();
+	let operation = await admitStaging(client, resolved, {
+		sourceRevision: opts.revision,
+		operationKey: opts.operationKey,
+		onOperationKey: (key) => process.stderr.write(chalk.dim(`Operation key ${key}. If this is interrupted, rerun with --operation-key ${key}.\n`))
+	});
+	process.stderr.write(`Staging operation ${operation.id}: ${describeProgress(operation)}\n`);
+	if (opts.wait) operation = await waitForOperation(client, resolved, operation.id, waitOptions(opts.timeout));
+	if (opts.json) return printJson({ operation });
+	if (operation.state === "succeeded") console.log(`✔ Staging is ready. Run \`fluid mist staging status\` for its URL.`);
+	else console.log(`Requested. Follow it with \`fluid mist staging wait --operation ${operation.id}\`.`);
+}));
+//#endregion
+//#region src/commands/staging/index.ts
+/** `fluid mist staging` — sub-command aggregator. */
+const stagingCommand = new Command("staging").description("Use a mist's isolated staging environment").addCommand(stagingStatusCommand).addCommand(stagingRequestCommand).addCommand(stagingWaitCommand);
+//#endregion
 //#region src/index.ts
 /**
 * @fluid-app/fluid-cli-mist
@@ -3869,6 +4243,7 @@ const plugin = {
 		mist.addCommand(logsCommand);
 		mist.addCommand(envCommand);
 		mist.addCommand(dropletCommand);
+		mist.addCommand(stagingCommand);
 		ctx.program.addCommand(mist);
 	}
 };