@f5-sales-demo/pi-resource-management 19.51.2

package/src/manifest-export.ts

@@ -0,0 +1,194 @@
+import { stringify as yamlStringify } from "yaml";
+
+const METADATA_KEEP_KEYS = new Set(["name", "namespace", "labels", "annotations", "description", "disable"]);
+
+const SPEC_STRIP_KEYS = new Set([
+	"host_name",
+	"dns_info",
+	"state",
+	"auto_cert_info",
+	"internet_vip_info",
+	"cert_state",
+	"create_form",
+	"replace_form",
+	"status",
+]);
+
+export interface MinimalExportFilter {
+	serverDefaults?: Record<string, unknown>;
+	serverDefaultFields?: string[];
+	minimumConfigFields?: string[];
+	oneofDefaultVariants?: Record<string, string>;
+}
+
+export interface ExportedManifest {
+	kind: string;
+	metadata: Record<string, unknown>;
+	spec: Record<string, unknown>;
+}
+
+export function toManifest(
+	apiResponse: Record<string, unknown>,
+	kind: string,
+	filter?: MinimalExportFilter,
+): ExportedManifest {
+	const objectData = apiResponse.object as Record<string, unknown> | undefined;
+	const getSpec = apiResponse.get_spec as Record<string, unknown> | undefined;
+
+	const rawMeta = (apiResponse.metadata ?? objectData?.metadata ?? getSpec?.metadata ?? {}) as Record<string, unknown>;
+	const metadata: Record<string, unknown> = {};
+
+	for (const key of Object.keys(rawMeta)) {
+		if (METADATA_KEEP_KEYS.has(key)) {
+			const val = rawMeta[key];
+			if (val !== undefined && val !== null) {
+				if (typeof val === "object" && !Array.isArray(val) && Object.keys(val as object).length === 0) continue;
+				metadata[key] = val;
+			}
+		}
+	}
+
+	const rawSpec = (apiResponse.spec ?? objectData?.spec ?? getSpec ?? {}) as Record<string, unknown>;
+	let spec = cleanSpec(rawSpec);
+	if (filter) {
+		spec = applyMinimalExportFilter(spec, filter);
+	}
+
+	return { kind, metadata, spec };
+}
+
+function cleanSpec(raw: Record<string, unknown>): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	for (const [key, val] of Object.entries(raw)) {
+		if (SPEC_STRIP_KEYS.has(key)) continue;
+		const cleaned = cleanValue(val);
+		if (cleaned !== undefined) {
+			result[key] = cleaned;
+		}
+	}
+	return result;
+}
+
+function cleanValue(val: unknown): unknown {
+	if (val === null || val === undefined) return undefined;
+	if (Array.isArray(val)) {
+		if (val.length === 0) return undefined;
+		const cleaned = val.map(cleanValue).filter(v => v !== undefined);
+		return cleaned.length > 0 ? cleaned : undefined;
+	}
+	if (typeof val === "object") {
+		const obj = val as Record<string, unknown>;
+		const keys = Object.keys(obj);
+		if (keys.length === 0) return val;
+		const result: Record<string, unknown> = {};
+		let hasContent = false;
+		for (const [k, v] of Object.entries(obj)) {
+			const cleaned = cleanValue(v);
+			if (cleaned !== undefined) {
+				result[k] = cleaned;
+				hasContent = true;
+			}
+		}
+		return hasContent ? result : val;
+	}
+	return val;
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (a === null || b === null || a === undefined || b === undefined) return a === b;
+	if (typeof a !== typeof b) return false;
+	if (typeof a !== "object") return false;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		return a.every((item, i) => deepEqual(item, b[i]));
+	}
+	const aObj = a as Record<string, unknown>;
+	const bObj = b as Record<string, unknown>;
+	const aKeys = Object.keys(aObj);
+	const bKeys = Object.keys(bObj);
+	if (aKeys.length !== bKeys.length) return false;
+	return aKeys.every(key => key in bObj && deepEqual(aObj[key], bObj[key]));
+}
+
+function isTriviallyEmpty(val: unknown): boolean {
+	if (val === false || val === 0 || val === "") return true;
+	if (Array.isArray(val) && val.length === 0) return true;
+	if (typeof val === "object" && val !== null && !Array.isArray(val) && Object.keys(val as object).length === 0)
+		return true;
+	return false;
+}
+
+export function applyMinimalExportFilter(
+	spec: Record<string, unknown>,
+	filter: MinimalExportFilter | undefined,
+): Record<string, unknown> {
+	if (!filter) return spec;
+
+	const minimumSet = new Set(filter.minimumConfigFields ?? []);
+	const serverDefaults = filter.serverDefaults ?? {};
+	const serverDefaultFieldsSet = new Set(filter.serverDefaultFields ?? []);
+	const oneofDefaults = filter.oneofDefaultVariants ?? {};
+	const oneofDefaultKeys = new Set(Object.keys(oneofDefaults));
+
+	function filterObject(obj: Record<string, unknown>, prefix: string): Record<string, unknown> {
+		const result: Record<string, unknown> = {};
+
+		for (const [key, val] of Object.entries(obj)) {
+			const path = prefix ? `${prefix}.${key}` : key;
+
+			if (minimumSet.has(path)) {
+				result[key] = val;
+				continue;
+			}
+
+			if (path in serverDefaults && deepEqual(val, serverDefaults[path])) {
+				continue;
+			}
+
+			if (serverDefaultFieldsSet.has(path) && isTriviallyEmpty(val)) {
+				continue;
+			}
+
+			if (oneofDefaultKeys.has(key) && deepEqual(val, {})) {
+				continue;
+			}
+
+			if (typeof val === "object" && val !== null && !Array.isArray(val) && Object.keys(val as object).length > 0) {
+				const filtered = filterObject(val as Record<string, unknown>, path);
+				if (Object.keys(filtered).length > 0) {
+					result[key] = filtered;
+				}
+				continue;
+			}
+
+			result[key] = val;
+		}
+
+		return result;
+	}
+
+	return filterObject(spec, "");
+}
+
+export function toManifestList(apiListResponse: Record<string, unknown>, kind: string): ExportedManifest[] {
+	const items = Array.isArray(apiListResponse.items) ? (apiListResponse.items as Record<string, unknown>[]) : [];
+	return items.map(item => toManifest(item, kind));
+}
+
+export type ManifestOutputFormat = "json" | "yaml";
+
+export function formatManifestOutput(manifests: ExportedManifest[], format: ManifestOutputFormat): string {
+	if (format === "yaml") {
+		if (manifests.length === 1) {
+			return yamlStringify(manifests[0]);
+		}
+		return manifests.map(m => yamlStringify(m)).join("---\n");
+	}
+
+	if (manifests.length === 1) {
+		return JSON.stringify(manifests[0], null, 2);
+	}
+	return JSON.stringify(manifests, null, 2);
+}

package/src/manifest-parser.ts

@@ -0,0 +1,72 @@
+import type { ResourceManifest } from "./types";
+
+export class ManifestParseError extends Error {
+	readonly manifestIndex: number;
+	constructor(message: string, index: number) {
+		super(message);
+		this.name = "ManifestParseError";
+		this.manifestIndex = index;
+	}
+}
+
+export function parseManifests(objects: Record<string, unknown>[], sourcePath: string): ResourceManifest[] {
+	const manifests: ResourceManifest[] = [];
+	for (let i = 0; i < objects.length; i++) {
+		manifests.push(parseSingleManifest(objects[i], i, sourcePath));
+	}
+	return manifests;
+}
+
+function parseSingleManifest(obj: Record<string, unknown>, index: number, sourcePath: string): ResourceManifest {
+	const kind = obj.kind;
+	if (typeof kind !== "string" || !kind) {
+		throw new ManifestParseError(
+			`Manifest at index ${index} in ${sourcePath} is missing required field "kind".`,
+			index,
+		);
+	}
+
+	const metadata = obj.metadata;
+	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+		throw new ManifestParseError(
+			`Manifest "${kind}" at index ${index} in ${sourcePath} is missing required field "metadata".`,
+			index,
+		);
+	}
+
+	const meta = metadata as Record<string, unknown>;
+	const name = meta.name;
+	if (typeof name !== "string" || !name) {
+		throw new ManifestParseError(
+			`Manifest "${kind}" at index ${index} in ${sourcePath} is missing required field "metadata.name".`,
+			index,
+		);
+	}
+
+	const spec = obj.spec;
+	if (spec !== undefined && (typeof spec !== "object" || spec === null || Array.isArray(spec))) {
+		throw new ManifestParseError(
+			`Manifest "${kind}/${name}" at index ${index} in ${sourcePath}: "spec" must be an object.`,
+			index,
+		);
+	}
+
+	return {
+		kind,
+		metadata: {
+			name,
+			namespace: typeof meta.namespace === "string" ? meta.namespace : undefined,
+			labels: isStringRecord(meta.labels) ? meta.labels : undefined,
+			annotations: isStringRecord(meta.annotations) ? meta.annotations : undefined,
+			description: typeof meta.description === "string" ? meta.description : undefined,
+			disable: typeof meta.disable === "boolean" ? meta.disable : undefined,
+		},
+		spec: (spec as Record<string, unknown>) ?? {},
+		rawObject: obj,
+	};
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	return Object.values(value as Record<string, unknown>).every(v => typeof v === "string");
+}

package/src/manifest-validator.ts

@@ -0,0 +1,109 @@
+import { KindResolutionError } from "./kind-resolver";
+import type {
+	KindResolver,
+	ManifestValidationResult,
+	ResolvedKind,
+	ResourceManifest,
+	ValidationError,
+	ValidationWarning,
+} from "./types";
+
+export function validateManifest(
+	manifest: ResourceManifest,
+	resolver: KindResolver,
+	namespaceOverride?: string,
+): { result: ManifestValidationResult; resolved?: ResolvedKind } {
+	const errors: ValidationError[] = [];
+	const warnings: ValidationWarning[] = [];
+
+	if (!manifest.kind) {
+		errors.push({ path: "kind", message: 'Required field "kind" is missing.', code: "MISSING_FIELD" });
+	}
+
+	if (!manifest.metadata.name) {
+		errors.push({
+			path: "metadata.name",
+			message: 'Required field "metadata.name" is missing.',
+			code: "MISSING_FIELD",
+		});
+	}
+
+	if (!manifest.metadata.namespace && !namespaceOverride) {
+		errors.push({
+			path: "metadata.namespace",
+			message: "No namespace specified. Use -n flag or set metadata.namespace in the manifest.",
+			code: "MISSING_FIELD",
+		});
+	}
+
+	let resolved: ResolvedKind | undefined;
+	if (manifest.kind) {
+		try {
+			resolved = resolver.resolveKind(manifest.kind);
+		} catch (err) {
+			if (err instanceof KindResolutionError) {
+				errors.push({ path: "kind", message: err.message, code: "UNKNOWN_KIND" });
+			} else {
+				errors.push({
+					path: "kind",
+					message: `Failed to resolve kind "${manifest.kind}": ${(err as Error).message}`,
+					code: "UNKNOWN_KIND",
+				});
+			}
+		}
+	}
+
+	if (resolved?.validation) {
+		const requiredFields = resolved.validation.create ?? resolved.validation.minimum_config ?? [];
+		for (const fieldPath of requiredFields) {
+			if (fieldPath.startsWith("metadata.")) continue;
+			const value = getNestedValue(manifest.rawObject, fieldPath);
+			if (value === undefined || value === null) {
+				errors.push({
+					path: fieldPath,
+					message: `Required field "${fieldPath}" is missing for ${manifest.kind} creation.`,
+					code: "MISSING_FIELD",
+				});
+			}
+		}
+	}
+
+	return { result: { valid: errors.length === 0, errors, warnings }, resolved };
+}
+
+export function validateManifests(
+	manifests: ResourceManifest[],
+	resolver: KindResolver,
+	namespaceOverride?: string,
+): { results: ManifestValidationResult[]; resolved: (ResolvedKind | undefined)[] } {
+	const results: ManifestValidationResult[] = [];
+	const resolved: (ResolvedKind | undefined)[] = [];
+	for (const manifest of manifests) {
+		const v = validateManifest(manifest, resolver, namespaceOverride);
+		results.push(v.result);
+		resolved.push(v.resolved);
+	}
+	return { results, resolved };
+}
+
+export function formatValidationErrors(manifest: ResourceManifest, result: ManifestValidationResult): string {
+	const lines: string[] = [];
+	lines.push(`Error: validation failed for ${manifest.kind || "unknown"} "${manifest.metadata.name || "unnamed"}"`);
+	for (const error of result.errors) {
+		lines.push(`  - ${error.path}: ${error.message}`);
+	}
+	for (const warning of result.warnings) {
+		lines.push(`  ! ${warning.path}: ${warning.message}`);
+	}
+	return lines.join("\n");
+}
+
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+	const parts = path.split(".");
+	let current: unknown = obj;
+	for (const part of parts) {
+		if (current == null || typeof current !== "object") return undefined;
+		current = (current as Record<string, unknown>)[part];
+	}
+	return current;
+}

package/src/output-formatter.ts

@@ -0,0 +1,209 @@
+import { stringify as yamlStringify } from "yaml";
+import { formatDiff } from "./diff-engine";
+import type { OperationResult, ResourceDiff, ResourceManifest } from "./types";
+
+export type OutputFormat = "json" | "yaml" | "table" | "wide";
+
+export function formatOperationResult(
+	result: OperationResult,
+	manifest: ResourceManifest,
+	format: OutputFormat = "table",
+): string {
+	switch (result.status) {
+		case "created":
+			return formatMutationResult("created", manifest, result.resource, result.durationMs, format);
+		case "updated":
+			return formatMutationResult("configured", manifest, result.resource, result.durationMs, format, result.diff);
+		case "unchanged":
+			return `${manifest.kind}/${manifest.metadata.name} unchanged`;
+		case "deleted":
+			return `${result.kind}/${result.name} deleted (${result.durationMs}ms)`;
+		case "error":
+			return `Error: ${result.error.message}`;
+		case "dry-run":
+			if (result.action === "create") {
+				return `${manifest.kind}/${manifest.metadata.name} would be created (dry-run)`;
+			}
+			if (result.diff) {
+				return `${manifest.kind}/${manifest.metadata.name} would be updated (dry-run)\n${formatDiff(result.diff, manifest.kind, manifest.metadata.name)}`;
+			}
+			return `${manifest.kind}/${manifest.metadata.name} would be updated (dry-run)`;
+	}
+}
+
+function formatMutationResult(
+	verb: string,
+	manifest: ResourceManifest,
+	resource: Record<string, unknown>,
+	durationMs: number,
+	format: OutputFormat,
+	diff?: ResourceDiff,
+): string {
+	if (format === "json") {
+		return JSON.stringify(resource, null, 2);
+	}
+	if (format === "yaml") {
+		return yamlStringify(resource);
+	}
+
+	const parts: string[] = [];
+	parts.push(`${manifest.kind}/${manifest.metadata.name} ${verb} (${durationMs}ms)`);
+	if (diff?.hasDifferences) {
+		parts.push(formatDiff(diff, manifest.kind, manifest.metadata.name));
+	}
+	return parts.join("\n");
+}
+
+export function formatResourceList(items: Record<string, unknown>[], kind: string, format: OutputFormat): string {
+	if (format === "json") {
+		return JSON.stringify({ items }, null, 2);
+	}
+	if (format === "yaml") {
+		return yamlStringify({ items });
+	}
+
+	if (items.length === 0) {
+		return `No ${kind} resources found.`;
+	}
+
+	const rows: string[][] = [];
+	const headers = format === "wide" ? ["NAME", "NAMESPACE", "DISABLED", "AGE", "UID"] : ["NAME", "NAMESPACE", "AGE"];
+
+	for (const item of items) {
+		const name = String(item.name ?? "");
+		const namespace = String(item.namespace ?? "");
+		const disabled = item.disabled === true ? "true" : "false";
+		const sysMeta = item.system_metadata as Record<string, unknown> | undefined;
+		const createdAt = sysMeta?.creation_timestamp ?? item.creation_timestamp;
+		const age = typeof createdAt === "string" ? formatAge(createdAt) : "";
+		const uid = typeof sysMeta?.uid === "string" ? sysMeta.uid.slice(0, 8) : "";
+
+		if (format === "wide") {
+			rows.push([name, namespace, disabled, age, uid]);
+		} else {
+			rows.push([name, namespace, age]);
+		}
+	}
+
+	return formatTable(headers, rows);
+}
+
+export function formatResourceDetail(resource: Record<string, unknown>, kind: string, format: OutputFormat): string {
+	if (format === "json") {
+		return JSON.stringify(resource, null, 2);
+	}
+	if (format === "yaml") {
+		return yamlStringify(resource);
+	}
+
+	const lines: string[] = [];
+	const metadata = resource.metadata as Record<string, unknown> | undefined;
+	const sysMeta = resource.system_metadata as Record<string, unknown> | undefined;
+	const spec = resource.spec as Record<string, unknown> | undefined;
+
+	lines.push(`Name:       ${metadata?.name ?? ""}`);
+	lines.push(`Kind:       ${kind}`);
+	lines.push(`Namespace:  ${metadata?.namespace ?? ""}`);
+
+	if (sysMeta) {
+		lines.push(`UID:        ${sysMeta.uid ?? ""}`);
+		if (sysMeta.creation_timestamp) lines.push(`Created:    ${sysMeta.creation_timestamp}`);
+		if (sysMeta.creator_id) lines.push(`Creator:    ${sysMeta.creator_id}`);
+	}
+
+	if (metadata?.labels && Object.keys(metadata.labels as object).length > 0) {
+		lines.push(`Labels:     ${formatLabels(metadata.labels as Record<string, string>)}`);
+	}
+
+	if (metadata?.description) lines.push(`Description: ${metadata.description}`);
+	if (metadata?.disable === true) lines.push(`Disabled:   true`);
+
+	if (spec) {
+		lines.push("");
+		lines.push("Spec:");
+		const specJson = JSON.stringify(spec, null, 2);
+		for (const line of specJson.split("\n")) {
+			lines.push(`  ${line}`);
+		}
+	}
+
+	const status = resource.status;
+	if (status) {
+		lines.push("");
+		lines.push("Status:");
+		const statusJson = JSON.stringify(status, null, 2);
+		for (const line of statusJson.split("\n")) {
+			lines.push(`  ${line}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+export function formatMultiOperationSummary(results: OperationResult[], _manifests: ResourceManifest[]): string {
+	let created = 0;
+	let updated = 0;
+	let unchanged = 0;
+	let errors = 0;
+	let dryRun = 0;
+
+	for (const result of results) {
+		switch (result.status) {
+			case "created":
+				created++;
+				break;
+			case "updated":
+				updated++;
+				break;
+			case "unchanged":
+				unchanged++;
+				break;
+			case "error":
+				errors++;
+				break;
+			case "dry-run":
+				dryRun++;
+				break;
+		}
+	}
+
+	const parts: string[] = [];
+	if (created > 0) parts.push(`${created} created`);
+	if (updated > 0) parts.push(`${updated} configured`);
+	if (unchanged > 0) parts.push(`${unchanged} unchanged`);
+	if (dryRun > 0) parts.push(`${dryRun} dry-run`);
+	if (errors > 0) parts.push(`${errors} error(s)`);
+
+	return parts.join(", ");
+}
+
+function formatTable(headers: string[], rows: string[][]): string {
+	const colWidths = headers.map((h, i) => Math.max(h.length, ...rows.map(r => (r[i] ?? "").length)));
+
+	const headerLine = headers.map((h, i) => h.padEnd(colWidths[i])).join("  ");
+	const dataLines = rows.map(row => row.map((cell, i) => cell.padEnd(colWidths[i])).join("  "));
+
+	return [headerLine, ...dataLines].join("\n");
+}
+
+function formatAge(timestamp: string): string {
+	const created = new Date(timestamp);
+	const now = new Date();
+	const diffMs = now.getTime() - created.getTime();
+
+	if (diffMs < 0) return "0s";
+	const seconds = Math.floor(diffMs / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h`;
+	const days = Math.floor(hours / 24);
+	return `${days}d`;
+}
+
+function formatLabels(labels: Record<string, string>): string {
+	return Object.entries(labels)
+		.map(([k, v]) => `${k}=${v}`)
+		.join(", ");
+}