@tailor-platform/sdk 1.2.2 → 1.2.3

package/dist/{list-CinLZzZW.mjs → list-nW4EfF7C.mjs}

@@ -1,5 +1,5 @@
 import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM, r as __exportAll, t as __commonJSMin } from "./chunk-CIV_ash9.mjs";
-import { i as WORKFLOW_JOB_BRAND, r as getDistDir } from "./config-CnvbSTIP.mjs";
+import { i as WORKFLOW_JOB_BRAND, r as getDistDir } from "./config-CJPKA-ui.mjs";
 import Module, { createRequire } from "node:module";
 import { defineCommand } from "citty";
 import * as path$20 from "node:path";
@@ -1093,6 +1093,10 @@ const OperatorService = /* @__PURE__ */ serviceDesc(file_tailor_v1_service, 0);
 //#endregion
 //#region src/cli/utils/package-json.ts
 let packageJson = null;
+/**
+* Read and cache the package.json of the SDK package.
+* @returns {Promise<PackageJson>} Parsed package.json contents
+*/
 async function readPackageJson() {
 	if (packageJson) return packageJson;
 	packageJson = await readPackageJSON(import.meta.url);
@@ -1104,6 +1108,10 @@ async function readPackageJson() {
 const platformBaseUrl = process.env.PLATFORM_URL ?? "https://api.tailor.tech";
 const oauth2ClientId = "cpoc_0Iudir72fqSpqC6GQ58ri1cLAqcq5vJl";
 const oauth2DiscoveryEndpoint = "/.well-known/oauth-authorization-server/oauth2/platform";
+/**
+* Initialize an OAuth2 client for Tailor Platform.
+* @returns {OAuth2Client} Configured OAuth2 client
+*/
 function initOAuth2Client() {
 	return new OAuth2Client({
 		clientId: oauth2ClientId,
@@ -1111,6 +1119,11 @@ function initOAuth2Client() {
 		discoveryEndpoint: oauth2DiscoveryEndpoint
 	});
 }
+/**
+* Initialize an Operator client with the given access token.
+* @param {string} accessToken - Access token for authentication
+* @returns {Promise<OperatorClient>} Configured Operator client
+*/
 async function initOperatorClient(accessToken) {
 	return createClient(OperatorService, createConnectTransport({
 		httpVersion: "2",
@@ -1123,6 +1136,10 @@ async function initOperatorClient(accessToken) {
 		]
 	}));
 }
+/**
+* Create an interceptor that sets a User-Agent header.
+* @returns {Promise<Interceptor>} User-Agent interceptor
+*/
 async function userAgentInterceptor() {
 	const ua = await userAgent();
 	return (next) => async (req) => {
@@ -1130,15 +1147,28 @@ async function userAgentInterceptor() {
 		return await next(req);
 	};
 }
+/**
+* Build the User-Agent string for CLI requests.
+* @returns {Promise<string>} User-Agent header value
+*/
 async function userAgent() {
 	return `tailor-sdk/${(await readPackageJson()).version ?? "unknown"}`;
 }
+/**
+* Create an interceptor that sets the Authorization bearer token.
+* @param {string} accessToken - Access token to use
+* @returns {Promise<Interceptor>} Bearer token interceptor
+*/
 async function bearerTokenInterceptor(accessToken) {
 	return (next) => async (req) => {
 		req.header.set("Authorization", `Bearer ${accessToken}`);
 		return await next(req);
 	};
 }
+/**
+* Create an interceptor that retries idempotent requests with backoff.
+* @returns {Interceptor} Retry interceptor
+*/
 function retryInterceptor() {
 	return (next) => async (req) => {
 		if (req.stream) return await next(req);
@@ -1158,10 +1188,21 @@ function retryInterceptor() {
 		throw lastError;
 	};
 }
+/**
+* Wait for an exponential backoff delay with jitter.
+* @param {number} attempt - Current retry attempt number (1-based)
+* @returns {Promise<void>} Promise that resolves after the delay
+*/
 function waitRetryBackoff(attempt) {
 	const backoff = 50 * 2 ** (attempt - 1) * (1 + .1 * (Math.random() * 2 - 1));
 	return new Promise((resolve$3) => setTimeout(resolve$3, backoff));
 }
+/**
+* Determine whether the given error is retriable for the method idempotency.
+* @param {unknown} error - Error thrown by the request
+* @param {MethodOptions_IdempotencyLevel} idempotency - Method idempotency level
+* @returns {boolean} True if the error should be retried
+*/
 function isRetirable(error, idempotency) {
 	if (!(error instanceof ConnectError)) return false;
 	switch (error.code) {
@@ -1170,6 +1211,10 @@ function isRetirable(error, idempotency) {
 		default: return false;
 	}
 }
+/**
+* Create an interceptor that enhances error messages from the Operator API.
+* @returns {Interceptor} Error handling interceptor
+*/
 function errorHandlingInterceptor() {
 	return (next) => async (req) => {
 		try {
@@ -1210,6 +1255,12 @@ function formatRequestParams(message) {
 		return "(unable to serialize request)";
 	}
 }
+/**
+* Fetch all paginated resources by repeatedly calling the given function.
+* @template T
+* @param {(pageToken: string) => Promise<[T[], string]>} fn - Page fetcher returning items and next page token
+* @returns {Promise<T[]>} All fetched items
+*/
 async function fetchAll(fn) {
 	const items = [];
 	let pageToken = "";
@@ -1221,6 +1272,11 @@ async function fetchAll(fn) {
 	}
 	return items;
 }
+/**
+* Fetch user info from the Tailor Platform userinfo endpoint.
+* @param {string} accessToken - Access token for the current user
+* @returns {Promise<{ email: string }>} Parsed user info
+*/
 async function fetchUserInfo(accessToken) {
 	const userInfoUrl = new URL("/auth/platform/userinfo", platformBaseUrl).href;
 	const resp = await fetch(userInfoUrl, { headers: {
@@ -1231,6 +1287,14 @@ async function fetchUserInfo(accessToken) {
 	const rawJson = await resp.json();
 	return z.object({ email: z.string() }).parse(rawJson);
 }
+/**
+* Resolve "name:url" patterns to actual Static Website URLs.
+* @param {OperatorClient} client - Operator client instance
+* @param {string} workspaceId - Workspace ID
+* @param {string[] | undefined} urls - URLs or name:url patterns
+* @param {string} context - Logging context (e.g., "CORS", "OAuth2 redirect URIs")
+* @returns {Promise<string[]>} Resolved URLs
+*/
 async function resolveStaticWebsiteUrls(client, workspaceId, urls, context) {
 	if (!urls) return [];
 	return (await Promise.all(urls.map(async (url) => {
@@ -1256,6 +1320,13 @@ async function resolveStaticWebsiteUrls(client, workspaceId, urls, context) {
 		return [url];
 	}))).flat();
 }
+/**
+* Fetch an OAuth2 access token for a machine user.
+* @param {string} url - OAuth2 server base URL
+* @param {string} clientId - Client ID for the machine user
+* @param {string} clientSecret - Client secret for the machine user
+* @returns {Promise<string>} Access token
+*/
 async function fetchMachineUserToken(url, clientId, clientSecret) {
 	const tokenEndpoint = new URL("/oauth2/token", url).href;
 	const formData = new URLSearchParams();
@@ -1298,6 +1369,10 @@ function platformConfigPath() {
 	if (!xdgConfig) throw new Error("User home directory not found");
 	return path$20.join(xdgConfig, "tailor-platform", "config.yaml");
 }
+/**
+* Read Tailor Platform CLI configuration, migrating from tailorctl if necessary.
+* @returns {PfConfig} Parsed platform configuration
+*/
 function readPlatformConfig() {
 	const configPath = platformConfigPath();
 	if (!fs$15.existsSync(configPath)) {
@@ -1315,6 +1390,11 @@ function readPlatformConfig() {
 	const rawConfig = parseYAML(fs$15.readFileSync(configPath, "utf-8"));
 	return pfConfigSchema.parse(rawConfig);
 }
+/**
+* Write Tailor Platform CLI configuration to disk.
+* @param {PfConfig} config - Platform configuration to write
+* @returns {void}
+*/
 function writePlatformConfig(config) {
 	const configPath = platformConfigPath();
 	fs$15.mkdirSync(path$20.dirname(configPath), { recursive: true });
@@ -1367,6 +1447,12 @@ function validateUUID(value, source) {
 	if (!result.success) throw new Error(`Invalid value from ${source}: must be a valid UUID`);
 	return result.data;
 }
+/**
+* Load workspace ID from command options, environment variables, or platform config.
+* Priority: opts/workspaceId > env/workspaceId > opts/profile > env/profile > error
+* @param {{ workspaceId?: string; profile?: string }} [opts] - Workspace and profile options
+* @returns {string} Resolved workspace ID
+*/
 function loadWorkspaceId(opts) {
 	if (opts?.workspaceId) return validateUUID(opts.workspaceId, "--workspace-id option");
 	if (process.env.TAILOR_PLATFORM_WORKSPACE_ID) return validateUUID(process.env.TAILOR_PLATFORM_WORKSPACE_ID, "TAILOR_PLATFORM_WORKSPACE_ID environment variable");
@@ -1381,6 +1467,12 @@ function loadWorkspaceId(opts) {
     Please specify workspace ID via --workspace-id option or TAILOR_PLATFORM_WORKSPACE_ID environment variable.
   `);
 }
+/**
+* Load access token from command options, environment variables, or platform config.
+* Priority: env/TAILOR_PLATFORM_TOKEN > env/TAILOR_TOKEN (deprecated) > opts/profile > env/profile > config/currentUser > error
+* @param {{ useProfile?: boolean; profile?: string }} [opts] - Profile options
+* @returns {Promise<string>} Resolved access token
+*/
 async function loadAccessToken(opts) {
 	if (process.env.TAILOR_PLATFORM_TOKEN) return process.env.TAILOR_PLATFORM_TOKEN;
 	if (process.env.TAILOR_TOKEN) {
@@ -1404,6 +1496,12 @@ async function loadAccessToken(opts) {
 	}
 	return await fetchLatestToken(pfConfig, user);
 }
+/**
+* Fetch the latest access token, refreshing if necessary.
+* @param {PfConfig} config - Platform config
+* @param {string} user - User name
+* @returns {Promise<string>} Latest access token
+*/
 async function fetchLatestToken(config, user) {
 	const tokens = config.users[user];
 	if (!tokens) throw new Error(ml`
@@ -1425,15 +1523,33 @@ async function fetchLatestToken(config, user) {
 	return resp.accessToken;
 }
 const DEFAULT_CONFIG_FILENAME = "tailor.config.ts";
+/**
+* Load config path from command options or environment variables.
+* Priority: opts/config > env/config > search parent directories
+* @param {string} [configPath] - Optional explicit config path
+* @returns {string | undefined} Resolved config path or undefined
+*/
 function loadConfigPath(configPath) {
 	if (configPath) return configPath;
 	if (process.env.TAILOR_PLATFORM_SDK_CONFIG_PATH) return process.env.TAILOR_PLATFORM_SDK_CONFIG_PATH;
 	return findUpSync(DEFAULT_CONFIG_FILENAME);
 }
+/**
+* Load organization ID from command options or environment variables.
+* Priority: opts/organizationId > env/organizationId > undefined (optional)
+* @param {string} [organizationId] - Organization ID override
+* @returns {string | undefined} Resolved organization ID or undefined
+*/
 function loadOrganizationId(organizationId) {
 	if (organizationId) return validateUUID(organizationId, "--organization-id option");
 	if (process.env.TAILOR_PLATFORM_ORGANIZATION_ID) return validateUUID(process.env.TAILOR_PLATFORM_ORGANIZATION_ID, "TAILOR_PLATFORM_ORGANIZATION_ID environment variable");
 }
+/**
+* Load folder ID from command options or environment variables.
+* Priority: opts/folderId > env/folderId > undefined (optional)
+* @param {string} [folderId] - Folder ID override
+* @returns {string | undefined} Resolved folder ID or undefined
+*/
 function loadFolderId(folderId) {
 	if (folderId) return validateUUID(folderId, "--folder-id option");
 	if (process.env.TAILOR_PLATFORM_FOLDER_ID) return validateUUID(process.env.TAILOR_PLATFORM_FOLDER_ID, "TAILOR_PLATFORM_FOLDER_ID environment variable");
@@ -1988,14 +2104,18 @@ const convertHookToExpr = (fn) => {
 /**
 * Parse TailorDBField into OperatorFieldConfig.
 * This transforms user-defined functions into script expressions.
+* @param {TailorAnyDBField} field - TailorDB field definition
+* @returns {OperatorFieldConfig} Parsed operator field configuration
 */
 function parseFieldConfig(field) {
 	const metadata = field.metadata;
 	const fieldType = field.type;
+	const rawRelation = field.rawRelation;
 	const nestedFields = field.fields;
 	return {
 		type: fieldType,
 		...metadata,
+		rawRelation,
 		...fieldType === "nested" && nestedFields && Object.keys(nestedFields).length > 0 ? { fields: Object.entries(nestedFields).reduce((acc, [key, nestedField]) => {
 			acc[key] = parseFieldConfig(nestedField);
 			return acc;
@@ -98745,6 +98865,12 @@ const eslintConfig = {
 	},
 	rules: { "no-undef": "error" }
 };
+/**
+* Ensure that a TailorDB script expression does not reference external variables.
+* @param {string} expr - JavaScript expression to validate
+* @param {ScriptContext} ctx - Script context (type, field, kind)
+* @returns {void}
+*/
 function ensureNoExternalVariablesInScript(expr, ctx) {
 	if (!expr.trim()) return;
 	let messages;
@@ -98763,6 +98889,13 @@ function ensureNoExternalVariablesInScript(expr, ctx) {
 	const namesList = [...externalNames].sort().join(", ");
 	throw new Error(`TailorDB ${ctx.kind} for ${ctx.typeName}.${ctx.fieldName} captures external variables (${namesList}). Hooks and validators must not reference variables outside their own parameters and local declarations.`);
 }
+/**
+* Ensure that TailorDB field scripts do not capture external variables.
+* @param {string} typeName - TailorDB type name
+* @param {string} fieldName - Field name
+* @param {TailorDBFieldConfig} fieldConfig - Parsed field configuration
+* @returns {void}
+*/
 function ensureNoExternalVariablesInFieldScripts(typeName, fieldName, fieldConfig) {
 	for (const validateConfig of fieldConfig.validate ?? []) {
 		const expr = validateConfig.script?.expr;
@@ -98812,12 +98945,24 @@ function isObjectFormat(p$1) {
 function isSingleArrayConditionFormat(cond) {
 	return cond.length >= 2 && typeof cond[1] === "string";
 }
+/**
+* Normalize record-level permissions into a standard structure.
+* @template User
+* @template Type
+* @param {TailorTypePermission<User, Type>} permission - Tailor type permission
+* @returns {StandardTailorTypePermission} Normalized record permissions
+*/
 function normalizePermission(permission) {
 	return Object.keys(permission).reduce((acc, action) => {
 		acc[action] = permission[action].map((p$1) => normalizeActionPermission(p$1));
 		return acc;
 	}, {});
 }
+/**
+* Normalize GraphQL permissions into a standard structure.
+* @param {TailorTypeGqlPermission<unknown, unknown>} permission - Tailor GQL permission
+* @returns {StandardTailorTypeGqlPermission} Normalized GQL permissions
+*/
 function normalizeGqlPermission(permission) {
 	return permission.map((policy) => normalizeGqlPolicy(policy));
 }
@@ -98832,6 +98977,8 @@ function normalizeGqlPolicy(policy) {
 /**
 * Parse raw permissions into normalized permissions.
 * This is the main entry point for permission parsing in the parser layer.
+* @param {RawPermissions} rawPermissions - Raw permissions definition
+* @returns {Permissions} Normalized permissions
 */
 function parsePermissions(rawPermissions) {
 	return {
@@ -98839,6 +98986,11 @@ function parsePermissions(rawPermissions) {
 		...rawPermissions.gql && { gql: normalizeGqlPermission(rawPermissions.gql) }
 	};
 }
+/**
+* Normalize a single action permission into the standard format.
+* @param {unknown} permission - Raw permission definition
+* @returns {StandardActionPermission} Normalized action permission
+*/
 function normalizeActionPermission(permission) {
 	if (isObjectFormat(permission)) {
 		const conditions$1 = permission.conditions;
@@ -98876,6 +99028,79 @@ function normalizeActionPermission(permission) {
 	};
 }
 
+//#endregion
+//#region src/parser/service/tailordb/relation.ts
+const relationTypes = {
+	"1-1": "1-1",
+	oneToOne: "1-1",
+	"n-1": "n-1",
+	manyToOne: "n-1",
+	"N-1": "n-1",
+	keyOnly: "keyOnly"
+};
+function fieldRef(context) {
+	return `Field "${context.fieldName}" on type "${context.typeName}"`;
+}
+/**
+* Validate relation configuration
+*/
+function validateRelationConfig(rawRelation, context) {
+	if (!rawRelation.type) throw new Error(`${fieldRef(context)} has a relation but is missing the required 'type' property. Valid values: ${Object.keys(relationTypes).join(", ")}.`);
+	if (!(rawRelation.type in relationTypes)) throw new Error(`${fieldRef(context)} has invalid relation type '${rawRelation.type}'. Valid values: ${Object.keys(relationTypes).join(", ")}.`);
+	if (rawRelation.toward.type !== "self" && !context.allTypeNames.has(rawRelation.toward.type)) throw new Error(`${fieldRef(context)} references unknown type "${rawRelation.toward.type}".`);
+}
+/**
+* Process raw relation config and compute derived metadata values
+*/
+function processRelationMetadata(rawRelation, context, isArrayField = false) {
+	const isUnique = relationTypes[rawRelation.type] === "1-1";
+	const key = rawRelation.toward.key ?? "id";
+	const targetTypeName = rawRelation.toward.type === "self" ? context.typeName : rawRelation.toward.type;
+	const shouldSetIndex = !isArrayField;
+	const shouldSetUnique = !isArrayField && isUnique;
+	return {
+		index: shouldSetIndex,
+		foreignKey: true,
+		relationType: rawRelation.type,
+		unique: shouldSetUnique,
+		foreignKeyType: targetTypeName,
+		foreignKeyField: key
+	};
+}
+/**
+* Build relation info for creating forward/backward relationships
+* Returns undefined for keyOnly relations
+*/
+function buildRelationInfo(rawRelation, context) {
+	if (rawRelation.type === "keyOnly") return;
+	const isUnique = relationTypes[rawRelation.type] === "1-1";
+	const key = rawRelation.toward.key ?? "id";
+	const targetTypeName = rawRelation.toward.type === "self" ? context.typeName : rawRelation.toward.type;
+	let forwardName = rawRelation.toward.as;
+	if (!forwardName) if (rawRelation.toward.type === "self") forwardName = context.fieldName.replace(/(ID|Id|id)$/u, "");
+	else forwardName = inflection.camelize(targetTypeName, true);
+	return {
+		targetType: targetTypeName,
+		forwardName,
+		backwardName: rawRelation.backward ?? "",
+		key,
+		unique: isUnique
+	};
+}
+/**
+* Apply processed relation metadata to field config
+*/
+function applyRelationMetadataToFieldConfig(fieldConfig, metadata) {
+	return {
+		...fieldConfig,
+		index: metadata.index,
+		foreignKey: metadata.foreignKey,
+		unique: metadata.unique,
+		foreignKeyType: metadata.foreignKeyType,
+		foreignKeyField: metadata.foreignKeyField
+	};
+}
+
 //#endregion
 //#region src/parser/service/tailordb/type-parser.ts
 /**
@@ -98884,7 +99109,8 @@ function normalizeActionPermission(permission) {
 */
 function parseTypes(rawTypes, namespace, typeSourceInfo) {
 	const types$2 = {};
-	for (const [typeName, type] of Object.entries(rawTypes)) types$2[typeName] = parseTailorDBType(type);
+	const allTypeNames = new Set(Object.keys(rawTypes));
+	for (const [typeName, type] of Object.entries(rawTypes)) types$2[typeName] = parseTailorDBType(type, allTypeNames, rawTypes);
 	buildBackwardRelationships(types$2, namespace, typeSourceInfo);
 	validatePluralFormUniqueness(types$2, namespace, typeSourceInfo);
 	return types$2;
@@ -98892,13 +99118,24 @@ function parseTypes(rawTypes, namespace, typeSourceInfo) {
 /**
 * Parse a TailorDBType into a ParsedTailorDBType.
 */
-function parseTailorDBType(type) {
+function parseTailorDBType(type, allTypeNames, rawTypes) {
 	const metadata = type.metadata;
 	const pluralForm = metadata.settings?.pluralForm || inflection.pluralize(type.name);
 	const fields = {};
 	const forwardRelationships = {};
 	for (const [fieldName, fieldDef] of Object.entries(type.fields)) {
-		const fieldConfig = parseFieldConfig(fieldDef);
+		let fieldConfig = parseFieldConfig(fieldDef);
+		const rawRelation = fieldConfig.rawRelation;
+		const context = {
+			typeName: type.name,
+			fieldName,
+			allTypeNames
+		};
+		if (rawRelation) {
+			validateRelationConfig(rawRelation, context);
+			const relationMetadata = processRelationMetadata(rawRelation, context, fieldConfig.array);
+			fieldConfig = applyRelationMetadataToFieldConfig(fieldConfig, relationMetadata);
+		}
 		if (fieldConfig.array && fieldConfig.index) throw new Error(`Field "${fieldName}" on type "${type.name}": index cannot be set on array fields`);
 		if (fieldConfig.array && fieldConfig.unique) throw new Error(`Field "${fieldName}" on type "${type.name}": unique cannot be set on array fields`);
 		ensureNoExternalVariablesInFieldScripts(type.name, fieldName, fieldConfig);
@@ -98906,29 +99143,18 @@ function parseTailorDBType(type) {
 			name: fieldName,
 			config: fieldConfig
 		};
-		const ref$1 = fieldDef.reference;
-		if (ref$1) {
-			const targetType = ref$1.type?.name;
-			if (targetType) {
-				const forwardName = ref$1.nameMap?.[0] || inflection.camelize(targetType, true);
-				const backwardName = ref$1.nameMap?.[1] || "";
-				const key = ref$1.key || "id";
-				parsedField.relation = {
-					targetType,
-					forwardName,
-					backwardName,
-					key,
-					unique: fieldDef.metadata?.unique ?? false
-				};
-				forwardRelationships[forwardName] = {
-					name: forwardName,
-					targetType,
-					targetField: fieldName,
-					sourceField: key,
-					isArray: false,
-					description: ref$1.type?.metadata?.description || ""
-				};
-			}
+		const relationInfo = rawRelation ? buildRelationInfo(rawRelation, context) : void 0;
+		if (relationInfo) {
+			parsedField.relation = { ...relationInfo };
+			const targetType = rawTypes[relationInfo.targetType];
+			forwardRelationships[relationInfo.forwardName] = {
+				name: relationInfo.forwardName,
+				targetType: relationInfo.targetType,
+				targetField: fieldName,
+				sourceField: relationInfo.key,
+				isArray: false,
+				description: targetType?.metadata?.description || ""
+			};
 		}
 		fields[fieldName] = parsedField;
 	}
@@ -99262,6 +99488,11 @@ var Application = class {
 		});
 	}
 };
+/**
+* Define a Tailor application from the given configuration.
+* @param {AppConfig} config - Application configuration object
+* @returns {Application} Configured application instance
+*/
 function defineApplication(config) {
 	const app = new Application(config.name, config);
 	app.defineTailorDB(config.db);
@@ -99968,6 +100199,11 @@ function createTriggerTransformPlugin(triggerContext) {
 
 //#endregion
 //#region src/cli/bundler/executor/loader.ts
+/**
+* Load and validate an executor definition from a file.
+* @param {string} executorFilePath - Path to the executor file
+* @returns {Promise<Executor | null>} Parsed executor or null if invalid
+*/
 async function loadExecutor(executorFilePath) {
 	const executor = (await import(pathToFileURL(executorFilePath).href)).default;
 	const parseResult = ExecutorSchema.safeParse(executor);
@@ -100058,6 +100294,11 @@ async function bundleSingleExecutor(executor, outputDir, tsconfig, triggerContex
 
 //#endregion
 //#region src/cli/bundler/resolver/loader.ts
+/**
+* Load and validate a resolver definition from a file.
+* @param {string} resolverFilePath - Path to the resolver file
+* @returns {Promise<Resolver | null>} Parsed resolver or null if invalid
+*/
 async function loadResolver(resolverFilePath) {
 	const resolver = (await import(pathToFileURL(resolverFilePath).href)).default;
 	const parseResult = ResolverSchema.safeParse(resolver);
@@ -101343,6 +101584,11 @@ const builtinGenerators = new Map([
 	[FileUtilsGeneratorID, (options) => new FileUtilsGenerator(options)]
 ]);
 const GeneratorConfigSchema = createGeneratorConfigSchema(builtinGenerators);
+/**
+* Load Tailor configuration file and associated generators.
+* @param {string} [configPath] - Optional explicit config path
+* @returns {Promise<{ config: AppConfig; generators: Generator[]; configPath: string }>} Loaded config and generators
+*/
 async function loadConfig(configPath) {
 	const foundPath = loadConfigPath(configPath);
 	if (!foundPath) throw new Error("Configuration file not found: tailor.config.ts not found in current or parent directories");
@@ -101376,6 +101622,13 @@ async function loadConfig(configPath) {
 function extractAttributesFromConfig(config) {
 	return collectAttributesFromConfig(config);
 }
+/**
+* Generate the contents of the user-defined type definition file.
+* @param {AttributeMapConfig | undefined} attributeMap - Attribute map configuration
+* @param {AttributeListConfig | undefined} attributeList - Attribute list configuration
+* @param {Record<string, string | number | boolean>} [env] - Environment configuration
+* @returns {string} Generated type definition source
+*/
 function generateTypeDefinition(attributeMap, attributeList, env) {
 	const mapFields = attributeMap ? Object.entries(attributeMap).map(([key, value]) => `    ${key}: ${value};`).join("\n") : "";
 	const mapBody = !attributeMap || Object.keys(attributeMap).length === 0 ? "{}" : `{
@@ -101433,6 +101686,11 @@ function collectAttributesFromConfig(config) {
 	}
 	return {};
 }
+/**
+* Resolve the output path for the generated type definition file.
+* @param {string} configPath - Path to Tailor config file
+* @returns {string} Absolute path to the type definition file
+*/
 function resolveTypeDefinitionPath(configPath) {
 	const typePath = process.env.TAILOR_PLATFORM_SDK_TYPE_PATH;
 	if (typePath) return path$20.resolve(process.cwd(), typePath);
@@ -101441,6 +101699,12 @@ function resolveTypeDefinitionPath(configPath) {
 	if (!packageDir) return path$20.join(configDir, "node_modules", "@tailor-platform", "sdk", "dist", "user-defined.d.ts");
 	return path$20.join(packageDir, "dist", "user-defined.d.ts");
 }
+/**
+* Generate user type definitions from the app config and write them to disk.
+* @param {AppConfig} config - Application config
+* @param {string} configPath - Path to Tailor config file
+* @returns {Promise<void>} Promise that resolves when types are generated
+*/
 async function generateUserTypes(config, configPath) {
 	try {
 		const { attributeMap, attributeList } = extractAttributesFromConfig(config);
@@ -101481,10 +101745,21 @@ function resolvePackageDirectory(startDir) {
 
 //#endregion
 //#region src/cli/apply/services/label.ts
+/**
+* Build TRN prefix for a workspace.
+* @param {string} workspaceId - Workspace ID
+* @returns {string} TRN prefix string
+*/
 function trnPrefix(workspaceId) {
 	return `trn:v1:workspace:${workspaceId}`;
 }
 const sdkNameLabelKey = "sdk-name";
+/**
+* Build metadata request with SDK labels.
+* @param {string} trn - Target TRN
+* @param {string} appName - Application name label
+* @returns {Promise<MessageInitShape<typeof SetMetadataRequestSchema>>} Metadata request
+*/
 async function buildMetaRequest(trn$7, appName) {
 	const packageJson$1 = await readPackageJson();
 	const sdkVersion = packageJson$1.version ? `v${packageJson$1.version.replace(/\./g, "-")}` : "unknown";
@@ -101526,6 +101801,13 @@ var ChangeSet = class {
 
 //#endregion
 //#region src/cli/apply/services/application.ts
+/**
+* Apply application changes for the given phase.
+* @param {OperatorClient} client - Operator client instance
+* @param {ReturnType<typeof planApplication>} changeSet - Planned application changes
+* @param {"create-update" | "delete"} [phase="create-update"] - Apply phase
+* @returns {Promise<void>} Promise that resolves when applications are applied
+*/
 async function applyApplication(client, changeSet, phase = "create-update") {
 	if (phase === "create-update") await Promise.all([...changeSet.creates.map(async (create$1) => {
 		create$1.request.cors = await resolveStaticWebsiteUrls(client, create$1.request.workspaceId, create$1.request.cors, "CORS");
@@ -101543,6 +101825,11 @@ async function applyApplication(client, changeSet, phase = "create-update") {
 function trn$6(workspaceId, name$1) {
 	return `trn:v1:workspace:${workspaceId}:application:${name$1}`;
 }
+/**
+* Plan application changes based on current and desired state.
+* @param {PlanContext} context - Planning context
+* @returns {Promise<ChangeSet<CreateApplication, UpdateApplication, DeleteApplication>>} Planned changes
+*/
 async function planApplication({ client, workspaceId, application, forRemoval }) {
 	const changeSet = new ChangeSet("Applications");
 	const existingApplications = await fetchAll(async (pageToken) => {
@@ -101648,12 +101935,31 @@ function protoSubgraph(subgraph) {
 
 //#endregion
 //#region src/cli/apply/services/idp.ts
+/**
+* Build the vault name for an IdP client.
+* @param {string} namespaceName - IdP namespace name
+* @param {string} clientName - IdP client name
+* @returns {string} Vault name
+*/
 function idpClientVaultName(namespaceName, clientName) {
 	return `idp-${namespaceName}-${clientName}`;
 }
+/**
+* Build the secret name for an IdP client.
+* @param {string} namespaceName - IdP namespace name
+* @param {string} clientName - IdP client name
+* @returns {string} Secret name
+*/
 function idpClientSecretName(namespaceName, clientName) {
 	return `client-secret-${namespaceName}-${clientName}`;
 }
+/**
+* Apply IdP-related changes for the given phase.
+* @param {OperatorClient} client - Operator client instance
+* @param {Awaited<ReturnType<typeof planIdP>>} result - Planned IdP changes
+* @param {Exclude<ApplyPhase, "delete">} [phase="create-update"] - Apply phase
+* @returns {Promise<void>} Promise that resolves when IdP changes are applied
+*/
 async function applyIdP(client, result, phase = "create-update") {
 	const { changeSet } = result;
 	if (phase === "create-update") {
@@ -101711,6 +102017,11 @@ async function applyIdP(client, result, phase = "create-update") {
 	}));
 	else if (phase === "delete-services") await Promise.all(changeSet.service.deletes.map((del) => client.deleteIdPService(del.request)));
 }
+/**
+* Plan IdP-related changes based on current and desired state.
+* @param {PlanContext} context - Planning context
+* @returns {Promise<unknown>} Planned changes and metadata
+*/
 async function planIdP({ client, workspaceId, application, forRemoval }) {
 	const idps = forRemoval ? [] : application.idpServices;
 	const { changeSet: serviceChangeSet, conflicts, unmanaged, resourceOwners } = await planServices$3(client, workspaceId, application.name, idps);
@@ -101899,6 +102210,13 @@ function convertLang(lang) {
 
 //#endregion
 //#region src/cli/apply/services/auth.ts
+/**
+* Apply auth-related changes for the given phase.
+* @param {OperatorClient} client - Operator client instance
+* @param {Awaited<ReturnType<typeof planAuth>>} result - Planned auth changes
+* @param {Exclude<ApplyPhase, "delete">} [phase="create-update"] - Apply phase
+* @returns {Promise<void>} Promise that resolves when auth changes are applied
+*/
 async function applyAuth(client, result, phase = "create-update") {
 	const { changeSet } = result;
 	if (phase === "create-update") {
@@ -101935,6 +102253,11 @@ async function applyAuth(client, result, phase = "create-update") {
 		await Promise.all(changeSet.idpConfig.deletes.map((del) => client.deleteAuthIDPConfig(del.request)));
 	} else if (phase === "delete-services") await Promise.all(changeSet.service.deletes.map((del) => client.deleteAuthService(del.request)));
 }
+/**
+* Plan auth-related changes based on current and desired state.
+* @param {PlanContext} context - Planning context
+* @returns {Promise<unknown>} Planned auth changes and metadata
+*/
 async function planAuth({ client, workspaceId, application, forRemoval }) {
 	const auths = [];
 	if (!forRemoval && application.authService) {
@@ -102740,6 +103063,13 @@ function protoSCIMAttribute(attr) {
 
 //#endregion
 //#region src/cli/apply/services/confirm.ts
+/**
+* Confirm reassignment of resources when owner conflicts are detected.
+* @param {OwnerConflict[]} conflicts - Detected owner conflicts
+* @param {string} appName - Target application name
+* @param {boolean} yes - Whether to auto-confirm without prompting
+* @returns {Promise<void>} Promise that resolves when confirmation completes
+*/
 async function confirmOwnerConflict(conflicts, appName, yes) {
 	if (conflicts.length === 0) return;
 	const currentOwners = [...new Set(conflicts.map((c$1) => c$1.currentOwner))];
@@ -102762,6 +103092,13 @@ async function confirmOwnerConflict(conflicts, appName, yes) {
       To override, run again and confirm, or use --yes flag.
     `);
 }
+/**
+* Confirm allowing tailor-sdk to manage previously unmanaged resources.
+* @param {UnmanagedResource[]} resources - Unmanaged resources
+* @param {string} appName - Target application name
+* @param {boolean} yes - Whether to auto-confirm without prompting
+* @returns {Promise<void>} Promise that resolves when confirmation completes
+*/
 async function confirmUnmanagedResources(resources, appName, yes) {
 	if (resources.length === 0) return;
 	logger.warn("Existing resources not tracked by tailor-sdk were found:");
@@ -102783,6 +103120,12 @@ async function confirmUnmanagedResources(resources, appName, yes) {
       To override, run again and confirm, or use --yes flag.
     `);
 }
+/**
+* Confirm deletion of important resources.
+* @param {ImportantResourceDeletion[]} resources - Resources scheduled for deletion
+* @param {boolean} yes - Whether to auto-confirm without prompting
+* @returns {Promise<void>} Promise that resolves when confirmation completes
+*/
 async function confirmImportantResourceDeletion(resources, yes) {
 	if (resources.length === 0) return;
 	logger.warn("The following resources will be deleted:");
@@ -102805,6 +103148,13 @@ async function confirmImportantResourceDeletion(resources, yes) {
 
 //#endregion
 //#region src/cli/apply/services/executor.ts
+/**
+* Apply executor-related changes for the given phase.
+* @param {OperatorClient} client - Operator client instance
+* @param {Awaited<ReturnType<typeof planExecutor>>} result - Planned executor changes
+* @param {Extract<ApplyPhase, "create-update" | "delete">} [phase="create-update"] - Apply phase
+* @returns {Promise<void>} Promise that resolves when executors are applied
+*/
 async function applyExecutor(client, result, phase = "create-update") {
 	const { changeSet } = result;
 	if (phase === "create-update") await Promise.all([...changeSet.creates.map(async (create$1) => {
@@ -102819,6 +103169,11 @@ async function applyExecutor(client, result, phase = "create-update") {
 function trn$3(workspaceId, name$1) {
 	return `trn:v1:workspace:${workspaceId}:executor:${name$1}`;
 }
+/**
+* Plan executor-related changes based on current and desired state.
+* @param {PlanContext} context - Planning context
+* @returns {Promise<ChangeSet<CreateExecutor, UpdateExecutor, DeleteExecutor>>} Planned changes
+*/
 async function planExecutor({ client, workspaceId, application, forRemoval }) {
 	const changeSet = new ChangeSet("Executors");
 	const conflicts = [];
@@ -103079,6 +103434,13 @@ const SCALAR_TYPE_MAP = {
 		name: "Time"
 	}
 };
+/**
+* Apply resolver pipeline changes for the given phase.
+* @param {OperatorClient} client - Operator client instance
+* @param {Awaited<ReturnType<typeof planPipeline>>} result - Planned pipeline changes
+* @param {Exclude<ApplyPhase, "delete">} [phase="create-update"] - Apply phase
+* @returns {Promise<void>} Promise that resolves when pipeline changes are applied
+*/
 async function applyPipeline(client, result, phase = "create-update") {
 	const { changeSet } = result;
 	if (phase === "create-update") {
@@ -103093,6 +103455,11 @@ async function applyPipeline(client, result, phase = "create-update") {
 	} else if (phase === "delete-resources") await Promise.all(changeSet.resolver.deletes.map((del) => client.deletePipelineResolver(del.request)));
 	else if (phase === "delete-services") await Promise.all(changeSet.service.deletes.map((del) => client.deletePipelineService(del.request)));
 }
+/**
+* Plan resolver pipeline changes based on current and desired state.
+* @param {PlanContext} context - Planning context
+* @returns {Promise<unknown>} Planned changes
+*/
 async function planPipeline({ client, workspaceId, application, forRemoval }) {
 	const pipelines = [];
 	if (!forRemoval) for (const pipeline of application.resolverServices) {
@@ -103327,6 +103694,13 @@ function protoFields(fields, baseName, isInput) {
 
 //#endregion
 //#region src/cli/apply/services/staticwebsite.ts
+/**
+* Apply static website changes for the given phase.
+* @param {OperatorClient} client - Operator client instance
+* @param {Awaited<ReturnType<typeof planStaticWebsite>>} result - Planned static website changes
+* @param {Extract<ApplyPhase, "create-update" | "delete">} [phase="create-update"] - Apply phase
+* @returns {Promise<void>} Promise that resolves when static websites are applied
+*/
 async function applyStaticWebsite(client, result, phase = "create-update") {
 	const { changeSet } = result;
 	if (phase === "create-update") await Promise.all([...changeSet.creates.map(async (create$1) => {
@@ -103341,6 +103715,11 @@ async function applyStaticWebsite(client, result, phase = "create-update") {
 function trn$1(workspaceId, name$1) {
 	return `trn:v1:workspace:${workspaceId}:staticwebsite:${name$1}`;
 }
+/**
+* Plan static website changes based on current and desired state.
+* @param {PlanContext} context - Planning context
+* @returns {Promise<unknown>} Planned changes
+*/
 async function planStaticWebsite({ client, workspaceId, application, forRemoval }) {
 	const changeSet = new ChangeSet("StaticWebsites");
 	const conflicts = [];
@@ -103430,6 +103809,13 @@ async function planStaticWebsite({ client, workspaceId, application, forRemoval
 
 //#endregion
 //#region src/cli/apply/services/tailordb.ts
+/**
+* Apply TailorDB-related changes for the given phase.
+* @param {OperatorClient} client - Operator client instance
+* @param {Awaited<ReturnType<typeof planTailorDB>>} result - Planned TailorDB changes
+* @param {Exclude<ApplyPhase, "delete">} [phase="create-update"] - Apply phase
+* @returns {Promise<void>} Promise that resolves when TailorDB changes are applied
+*/
 async function applyTailorDB(client, result, phase = "create-update") {
 	const { changeSet } = result;
 	if (phase === "create-update") {
@@ -103444,6 +103830,11 @@ async function applyTailorDB(client, result, phase = "create-update") {
 		await Promise.all(changeSet.type.deletes.map((del) => client.deleteTailorDBType(del.request)));
 	} else if (phase === "delete-services") await Promise.all(changeSet.service.deletes.map((del) => client.deleteTailorDBService(del.request)));
 }
+/**
+* Plan TailorDB-related changes based on current and desired state.
+* @param {PlanContext} context - Planning context
+* @returns {Promise<unknown>} Planned changes
+*/
 async function planTailorDB({ client, workspaceId, application, forRemoval }) {
 	const tailordbs = [];
 	if (!forRemoval) for (const tailordb of application.tailorDBServices) {
@@ -103972,6 +104363,13 @@ function protoGqlOperand(operand) {
 
 //#endregion
 //#region src/cli/apply/services/workflow.ts
+/**
+* Apply workflow changes for the given phase.
+* @param {OperatorClient} client - Operator client instance
+* @param {Awaited<ReturnType<typeof planWorkflow>>} result - Planned workflow changes
+* @param {Extract<ApplyPhase, "create-update" | "delete">} [phase="create-update"] - Apply phase
+* @returns {Promise<void>} Promise that resolves when workflows are applied
+*/
 async function applyWorkflow(client, result, phase = "create-update") {
 	const { changeSet, appName } = result;
 	if (phase === "create-update") {
@@ -104064,6 +104462,15 @@ function workflowTrn(workspaceId, name$1) {
 function jobFunctionTrn(workspaceId, name$1) {
 	return `trn:v1:workspace:${workspaceId}:workflow_job_function:${name$1}`;
 }
+/**
+* Plan workflow changes and job functions based on current and desired state.
+* @param {OperatorClient} client - Operator client instance
+* @param {string} workspaceId - Workspace ID
+* @param {string} appName - Application name
+* @param {Record<string, Workflow>} workflows - Parsed workflows
+* @param {Record<string, string[]>} mainJobDeps - Main job dependencies by workflow
+* @returns {Promise<unknown>} Planned workflow changes
+*/
 async function planWorkflow(client, workspaceId, appName, workflows, mainJobDeps) {
 	const changeSet = new ChangeSet("Workflows");
 	const conflicts = [];
@@ -104155,6 +104562,11 @@ async function loadWorkflowScripts() {
 
 //#endregion
 //#region src/cli/apply/index.ts
+/**
+* Apply the configured application to the Tailor platform.
+* @param {ApplyOptions} [options] - Options for apply execution
+* @returns {Promise<void>} Promise that resolves when apply completes
+*/
 async function apply(options) {
 	const { config, configPath } = await loadConfig(options?.configPath);
 	const dryRun = options?.dryRun ?? false;
@@ -105044,6 +105456,11 @@ var GenerationManager = class {
 		});
 	}
 };
+/**
+* Run code generation using the Tailor configuration and generators.
+* @param {GenerateOptions} [options] - Generation options
+* @returns {Promise<void>} Promise that resolves when generation (and watch, if enabled) completes
+*/
 async function generate(options) {
 	const { config, generators, configPath } = await loadConfig(options?.configPath);
 	const watch = options?.watch ?? false;
@@ -105082,6 +105499,11 @@ const generateCommand = defineCommand({
 
 //#endregion
 //#region src/cli/machineuser/list.ts
+/**
+* Map a MachineUser protobuf message to CLI-friendly info.
+* @param {MachineUser} user - Machine user resource
+* @returns {MachineUserInfo} Flattened machine user info
+*/
 function machineUserInfo(user) {
 	return {
 		name: user.name,
@@ -105091,6 +105513,11 @@ function machineUserInfo(user) {
 		updatedAt: user.updatedAt ? timestampDate(user.updatedAt).toISOString() : "N/A"
 	};
 }
+/**
+* List machine users for the current application.
+* @param {ListMachineUsersOptions} [options] - Machine user listing options
+* @returns {Promise<MachineUserInfo[]>} List of machine users
+*/
 async function listMachineUsers(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -105137,6 +105564,11 @@ const listCommand$3 = defineCommand({
 
 //#endregion
 //#region src/cli/machineuser/token.ts
+/**
+* Get a machine user access token for the current application.
+* @param {GetMachineUserTokenOptions} options - Token retrieval options
+* @returns {Promise<MachineUserTokenInfo>} Machine user token info
+*/
 async function getMachineUserToken(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -105207,6 +105639,11 @@ const grantTypeToString = (grantType) => {
 		default: return "unknown";
 	}
 };
+/**
+* Transform an AuthOAuth2Client into CLI-friendly OAuth2 client info.
+* @param {AuthOAuth2Client} client - OAuth2 client resource
+* @returns {OAuth2ClientInfo} Flattened OAuth2 client info
+*/
 function toOAuth2ClientInfo(client) {
 	return {
 		name: client.name,
@@ -105217,6 +105654,11 @@ function toOAuth2ClientInfo(client) {
 		createdAt: client.createdAt ? timestampDate(client.createdAt).toISOString() : "N/A"
 	};
 }
+/**
+* Transform an AuthOAuth2Client into OAuth2 client credentials info.
+* @param {AuthOAuth2Client} client - OAuth2 client resource
+* @returns {OAuth2ClientCredentials} OAuth2 client credentials
+*/
 function toOAuth2ClientCredentials(client) {
 	return {
 		name: client.name,
@@ -105231,6 +105673,11 @@ function toOAuth2ClientCredentials(client) {
 
 //#endregion
 //#region src/cli/oauth2client/get.ts
+/**
+* Get OAuth2 client credentials for the current application.
+* @param {GetOAuth2ClientOptions} options - OAuth2 client lookup options
+* @returns {Promise<OAuth2ClientCredentials>} OAuth2 client credentials
+*/
 async function getOAuth2Client(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -105286,6 +105733,11 @@ const getCommand$1 = defineCommand({
 
 //#endregion
 //#region src/cli/oauth2client/list.ts
+/**
+* List OAuth2 clients for the current application.
+* @param {ListOAuth2ClientsOptions} [options] - OAuth2 client listing options
+* @returns {Promise<OAuth2ClientInfo[]>} List of OAuth2 clients
+*/
 async function listOAuth2Clients(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -105378,6 +105830,11 @@ async function execRemove(client, workspaceId, application, confirm) {
 	await applyTailorDB(client, tailorDB, "delete-resources");
 	await applyTailorDB(client, tailorDB, "delete-services");
 }
+/**
+* Remove all resources managed by the current application.
+* @param {RemoveOptions} [options] - Remove options
+* @returns {Promise<void>} Promise that resolves when removal completes
+*/
 async function remove(options) {
 	const { client, workspaceId, application } = await loadOptions$1(options);
 	await execRemove(client, workspaceId, application);
@@ -105450,6 +105907,11 @@ function applicationInfo(app) {
 		updatedAt: app.updateTime ? timestampDate(app.updateTime).toISOString() : "N/A"
 	};
 }
+/**
+* Show applied application information for the current workspace.
+* @param {ShowOptions} [options] - Show options
+* @returns {Promise<ApplicationInfo>} Application information
+*/
 async function show(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -105527,6 +105989,11 @@ function formatTableWithHeaders(headers, rows) {
 		return lineIndex === 0 || lineIndex === 1 || lineIndex === rowCount;
 	} });
 }
+/**
+* Format an ISO timestamp string as a human-readable relative time.
+* @param {string} isoString - ISO date string
+* @returns {string} Relative time (e.g., "5 minutes ago")
+*/
 function humanizeRelativeTime(isoString) {
 	const date = new Date(isoString);
 	if (Number.isNaN(date.getTime())) return isoString;
@@ -105563,6 +106030,11 @@ const waitArgs = {
 
 //#endregion
 //#region src/cli/workflow/transform.ts
+/**
+* Convert a workflow execution status enum to a string.
+* @param {WorkflowExecution_Status} status - Workflow execution status
+* @returns {string} String representation of the status
+*/
 function workflowExecutionStatusToString(status) {
 	switch (status) {
 		case WorkflowExecution_Status.PENDING: return "PENDING";
@@ -105573,6 +106045,11 @@ function workflowExecutionStatusToString(status) {
 		default: return "UNSPECIFIED";
 	}
 }
+/**
+* Convert a workflow job execution status enum to a string.
+* @param {WorkflowJobExecution_Status} status - Workflow job execution status
+* @returns {string} String representation of the status
+*/
 function workflowJobExecutionStatusToString(status) {
 	switch (status) {
 		case WorkflowJobExecution_Status.RUNNING: return "RUNNING";
@@ -105582,6 +106059,11 @@ function workflowJobExecutionStatusToString(status) {
 		default: return "UNSPECIFIED";
 	}
 }
+/**
+* Convert a Workflow proto to CLI-friendly list info.
+* @param {Workflow} workflow - Workflow resource
+* @returns {WorkflowListInfo} Flattened workflow list info
+*/
 function toWorkflowListInfo(workflow) {
 	return {
 		name: workflow.name,
@@ -105590,6 +106072,11 @@ function toWorkflowListInfo(workflow) {
 		updatedAt: workflow.updatedAt ? timestampDate(workflow.updatedAt).toISOString() : "N/A"
 	};
 }
+/**
+* Convert a Workflow proto to detailed workflow info for CLI output.
+* @param {Workflow} workflow - Workflow resource
+* @returns {WorkflowInfo} Detailed workflow info
+*/
 function toWorkflowInfo(workflow) {
 	const jobFunctions = {};
 	for (const [name$1, version$4] of Object.entries(workflow.jobFunctions)) jobFunctions[name$1] = version$4.toString();
@@ -105602,6 +106089,11 @@ function toWorkflowInfo(workflow) {
 		updatedAt: workflow.updatedAt ? timestampDate(workflow.updatedAt).toISOString() : "N/A"
 	};
 }
+/**
+* Convert a WorkflowJobExecution proto to CLI-friendly job execution info.
+* @param {WorkflowJobExecution} jobExecution - Workflow job execution resource
+* @returns {WorkflowJobExecutionInfo} Flattened job execution info
+*/
 function toWorkflowJobExecutionInfo(jobExecution) {
 	return {
 		id: jobExecution.id,
@@ -105612,6 +106104,11 @@ function toWorkflowJobExecutionInfo(jobExecution) {
 		finishedAt: jobExecution.finishedAt ? timestampDate(jobExecution.finishedAt).toISOString() : "N/A"
 	};
 }
+/**
+* Convert a WorkflowExecution proto to CLI-friendly execution info.
+* @param {WorkflowExecution} execution - Workflow execution resource
+* @returns {WorkflowExecutionInfo} Flattened execution info
+*/
 function toWorkflowExecutionInfo(execution) {
 	return {
 		id: execution.id,
@@ -105652,6 +106149,11 @@ function parseStatus(status) {
 		default: throw new Error(`Invalid status: ${status}. Valid values: PENDING, PENDING_RESUME, RUNNING, SUCCESS, FAILED`);
 	}
 }
+/**
+* List workflow executions with optional filters.
+* @param {ListWorkflowExecutionsOptions} [options] - Workflow execution listing options
+* @returns {Promise<WorkflowExecutionInfo[]>} List of workflow executions
+*/
 async function listWorkflowExecutions(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -105692,6 +106194,11 @@ async function listWorkflowExecutions(options) {
 		return [executions, nextPageToken];
 	})).map(toWorkflowExecutionInfo);
 }
+/**
+* Get a single workflow execution with optional logs.
+* @param {GetWorkflowExecutionOptions} options - Workflow execution lookup options
+* @returns {Promise<GetWorkflowExecutionResult>} Workflow execution with optional logs
+*/
 async function getWorkflowExecution(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -105774,6 +106281,11 @@ async function waitWithSpinner(waitFn, interval, json) {
 		spinner?.stop();
 	}
 }
+/**
+* Print a workflow execution and its logs in a human-readable format.
+* @param {WorkflowExecutionDetailInfo} execution - Workflow execution detail info
+* @returns {void}
+*/
 function printExecutionWithLogs(execution) {
 	const summaryData = [
 		["id", execution.id],
@@ -105867,6 +106379,13 @@ const executionsCommand = defineCommand({
 
 //#endregion
 //#region src/cli/workflow/get.ts
+/**
+* Resolve a workflow definition by name.
+* @param {Awaited<ReturnType<typeof initOperatorClient>>} client - Operator client
+* @param {string} workspaceId - Workspace ID
+* @param {string} name - Workflow name
+* @returns {Promise<unknown>} Resolved workflow
+*/
 async function resolveWorkflow(client, workspaceId, name$1) {
 	const { workflow } = await client.getWorkflowByName({
 		workspaceId,
@@ -105875,6 +106394,11 @@ async function resolveWorkflow(client, workspaceId, name$1) {
 	if (!workflow) throw new Error(`Workflow '${name$1}' not found.`);
 	return workflow;
 }
+/**
+* Get a workflow by name and return CLI-friendly info.
+* @param {GetWorkflowOptions} options - Workflow lookup options
+* @returns {Promise<WorkflowInfo>} Workflow information
+*/
 async function getWorkflow(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -105914,6 +106438,11 @@ const getCommand = defineCommand({
 
 //#endregion
 //#region src/cli/workflow/list.ts
+/**
+* List workflows in the workspace and return CLI-friendly info.
+* @param {ListWorkflowsOptions} [options] - Workflow listing options
+* @returns {Promise<WorkflowListInfo[]>} List of workflows
+*/
 async function listWorkflows(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -105988,6 +106517,11 @@ function colorizeStatus(status) {
 		default: return statusText;
 	}
 }
+/**
+* Wait for a workflow execution to reach a terminal state, optionally showing progress.
+* @param {WaitForExecutionOptions} options - Wait options
+* @returns {Promise<WorkflowExecutionInfo>} Final workflow execution info
+*/
 async function waitForExecution(options) {
 	const { client, workspaceId, executionId, interval, showProgress, trackJobs } = options;
 	let lastStatus;
@@ -106044,6 +106578,11 @@ function getRunningJobs(execution) {
 function isTerminalStatus(status) {
 	return status === WorkflowExecution_Status.SUCCESS || status === WorkflowExecution_Status.FAILED || status === WorkflowExecution_Status.PENDING_RESUME;
 }
+/**
+* Start a workflow and return a handle to wait for completion.
+* @param {StartWorkflowOptions} options - Start options
+* @returns {Promise<StartWorkflowResultWithWait>} Start result with wait helper
+*/
 async function startWorkflow(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -106140,6 +106679,11 @@ const startCommand = defineCommand({
 
 //#endregion
 //#region src/cli/workflow/resume.ts
+/**
+* Resume a suspended workflow execution and return a handle to wait for completion.
+* @param {ResumeWorkflowOptions} options - Resume options
+* @returns {Promise<ResumeWorkflowResultWithWait>} Resume result with wait helper
+*/
 async function resumeWorkflow(options) {
 	const client = await initOperatorClient(await loadAccessToken({
 		useProfile: true,
@@ -106242,6 +106786,11 @@ const validateRegion = async (region, client) => {
 	const availableRegions = await client.listAvailableWorkspaceRegions({});
 	if (!availableRegions.regions.includes(region)) throw new Error(`Region must be one of: ${availableRegions.regions.join(", ")}.`);
 };
+/**
+* Create a new workspace with the given options.
+* @param {CreateWorkspaceOptions} options - Workspace creation options
+* @returns {Promise<WorkspaceInfo>} Created workspace info
+*/
 async function createWorkspace(options) {
 	const result = createWorkspaceOptionsSchema.safeParse(options);
 	if (!result.success) throw new Error(result.error.issues[0].message);
@@ -106319,6 +106868,11 @@ async function loadOptions(options) {
 		workspaceId: result.data.workspaceId
 	};
 }
+/**
+* Delete a workspace by ID.
+* @param {DeleteWorkspaceOptions} options - Workspace deletion options
+* @returns {Promise<void>} Promise that resolves when deletion completes
+*/
 async function deleteWorkspace(options) {
 	const { client, workspaceId } = await loadOptions(options);
 	await client.deleteWorkspace({ workspaceId });
@@ -106365,6 +106919,11 @@ const deleteCommand = defineCommand({
 //#endregion
 //#region src/cli/workspace/list.ts
 const limitSchema = z.coerce.number().int().positive().optional();
+/**
+* List workspaces with an optional limit.
+* @param {ListWorkspacesOptions} [options] - Workspace listing options
+* @returns {Promise<WorkspaceInfo[]>} List of workspaces
+*/
 async function listWorkspaces(options) {
 	const limit = options?.limit;
 	const hasLimit = limit !== void 0;
@@ -106419,4 +106978,4 @@ const listCommand = defineCommand({
 
 //#endregion
 export { withCommonArgs as $, generate as A, loadWorkspaceId as B, listOAuth2Clients as C, tokenCommand as D, getMachineUserToken as E, loadConfig as F, initOAuth2Client as G, writePlatformConfig as H, apiCall as I, PATScope as J, initOperatorClient as K, apiCommand as L, apply as M, applyCommand as N, listCommand$3 as O, generateUserTypes as P, jsonArgs as Q, fetchLatestToken as R, listCommand$2 as S, getOAuth2Client as T, fetchAll as U, readPlatformConfig as V, fetchUserInfo as W, confirmationArgs as X, commonArgs as Y, deploymentArgs as Z, listWorkflowExecutions as _, createCommand as a, remove as b, resumeWorkflow as c, listCommand$1 as d, workspaceArgs as et, listWorkflows as f, getWorkflowExecution as g, executionsCommand as h, deleteWorkspace as i, generateCommand as j, listMachineUsers as k, startCommand as l, getWorkflow as m, listWorkspaces as n, createWorkspace as o, getCommand as p, readPackageJson as q, deleteCommand as r, resumeCommand as s, listCommand as t, logger as tt, startWorkflow as u, show as v, getCommand$1 as w, removeCommand as x, showCommand as y, loadAccessToken as z };
-//# sourceMappingURL=list-CinLZzZW.mjs.map
+//# sourceMappingURL=list-nW4EfF7C.mjs.map