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

package/src/defaults-metadata.ts

@@ -0,0 +1,76 @@
+import { DEFAULTS_METADATA } from "./defaults-metadata.generated";
+import type { MinimalExportFilter } from "./manifest-export";
+
+/**
+ * Raw, per-kind defaults knowledge extracted from the enriched API specs
+ * (the api-specs-enriched single source of truth). Field paths are
+ * `spec.`-prefixed, matching the enriched OpenAPI schema paths.
+ *
+ * This is the input to {@link buildFilterFromMetadata}, which transforms it
+ * into the spec-relative {@link MinimalExportFilter} consumed by
+ * {@link applyMinimalExportFilter}.
+ */
+export interface KindDefaultsMetadata {
+	/** Field paths the server applies a default for (from `x-f5xc-server-default`). */
+	readonly serverDefaultFields: readonly string[];
+	/** Known default values, keyed by field path (from OpenAPI `default`). */
+	readonly fieldDefaults: Readonly<Record<string, unknown>>;
+	/** Field paths required for a minimum viable config (never stripped). */
+	readonly minimumConfigFields: readonly string[];
+	/** oneOf conflicts, keyed by field path (from `x-f5xc-conflicts-with`). */
+	readonly fieldConflicts: Readonly<Record<string, readonly string[]>>;
+}
+
+function stripSpecPrefix(path: string): string {
+	return path.startsWith("spec.") ? path.slice(5) : path;
+}
+
+/**
+ * Transform raw per-kind defaults knowledge into a {@link MinimalExportFilter}.
+ *
+ * Returns `undefined` when the kind has no server-default fields — callers
+ * treat that as "export everything" (no stripping), which is the safe default
+ * for kinds not yet covered by the enriched specs.
+ */
+export function buildFilterFromMetadata(meta: KindDefaultsMetadata): MinimalExportFilter | undefined {
+	if (meta.serverDefaultFields.length === 0) {
+		return undefined;
+	}
+
+	const serverDefaults: Record<string, unknown> = {};
+	const serverDefaultFields: string[] = [];
+
+	for (const path of meta.serverDefaultFields) {
+		const specPath = stripSpecPrefix(path);
+		if (path in meta.fieldDefaults) {
+			serverDefaults[specPath] = meta.fieldDefaults[path];
+		} else {
+			serverDefaultFields.push(specPath);
+		}
+	}
+
+	const oneofDefaultVariants: Record<string, string> = {};
+	for (const [path, conflictList] of Object.entries(meta.fieldConflicts)) {
+		if (!meta.serverDefaultFields.includes(path)) continue;
+		if (conflictList.length === 0) continue;
+		const fieldName = stripSpecPrefix(path).split(".").pop();
+		if (fieldName) {
+			oneofDefaultVariants[fieldName] = fieldName;
+		}
+	}
+
+	const minimumConfigFields = meta.minimumConfigFields.map(stripSpecPrefix);
+
+	return { serverDefaults, serverDefaultFields, minimumConfigFields, oneofDefaultVariants };
+}
+
+/**
+ * Build the minimum-settings export filter for a resource kind from the
+ * generated defaults table. Returns `undefined` for kinds with no known
+ * server defaults (caller exports everything).
+ */
+export function buildMinimalExportFilter(kind: string): MinimalExportFilter | undefined {
+	const meta = DEFAULTS_METADATA[kind];
+	if (!meta) return undefined;
+	return buildFilterFromMetadata(meta);
+}

package/src/diff-engine.ts

@@ -0,0 +1,160 @@
+import type { DiffEntry, ResourceDiff } from "./types";
+
+export function computeResourceDiff(current: Record<string, unknown>, desired: Record<string, unknown>): ResourceDiff {
+	const added: DiffEntry[] = [];
+	const removed: DiffEntry[] = [];
+	const changed: DiffEntry[] = [];
+	let unchangedCount = 0;
+
+	diffObjects(current, desired, "", added, removed, changed, { count: 0 });
+	unchangedCount =
+		countLeafKeys(current) + countLeafKeys(desired) - added.length - removed.length - changed.length * 2;
+	if (unchangedCount < 0) unchangedCount = 0;
+
+	return {
+		hasDifferences: added.length > 0 || removed.length > 0 || changed.length > 0,
+		added,
+		removed,
+		changed,
+		unchangedCount,
+	};
+}
+
+function diffObjects(
+	current: unknown,
+	desired: unknown,
+	prefix: string,
+	added: DiffEntry[],
+	removed: DiffEntry[],
+	changed: DiffEntry[],
+	_ctx: { count: number },
+): void {
+	if (current === desired) return;
+	if (current === undefined || current === null) {
+		if (desired !== undefined && desired !== null) {
+			added.push({ path: prefix || "(root)", newValue: desired });
+		}
+		return;
+	}
+	if (desired === undefined || desired === null) {
+		removed.push({ path: prefix || "(root)", oldValue: current });
+		return;
+	}
+
+	if (Array.isArray(current) && Array.isArray(desired)) {
+		diffArrays(current, desired, prefix, added, removed, changed, _ctx);
+		return;
+	}
+
+	if (
+		typeof current === "object" &&
+		typeof desired === "object" &&
+		!Array.isArray(current) &&
+		!Array.isArray(desired)
+	) {
+		const curObj = current as Record<string, unknown>;
+		const desObj = desired as Record<string, unknown>;
+		const allKeys = new Set([...Object.keys(curObj), ...Object.keys(desObj)]);
+
+		for (const key of allKeys) {
+			const childPath = prefix ? `${prefix}.${key}` : key;
+			const curVal = curObj[key];
+			const desVal = desObj[key];
+
+			if (!(key in curObj)) {
+				added.push({ path: childPath, newValue: desVal });
+			} else if (!(key in desObj)) {
+				removed.push({ path: childPath, oldValue: curVal });
+			} else {
+				diffObjects(curVal, desVal, childPath, added, removed, changed, _ctx);
+			}
+		}
+		return;
+	}
+
+	if (!deepEqual(current, desired)) {
+		changed.push({ path: prefix || "(root)", oldValue: current, newValue: desired });
+	}
+}
+
+function diffArrays(
+	current: unknown[],
+	desired: unknown[],
+	prefix: string,
+	added: DiffEntry[],
+	removed: DiffEntry[],
+	changed: DiffEntry[],
+	_ctx: { count: number },
+): void {
+	const maxLen = Math.max(current.length, desired.length);
+	for (let i = 0; i < maxLen; i++) {
+		const childPath = `${prefix}[${i}]`;
+		if (i >= current.length) {
+			added.push({ path: childPath, newValue: desired[i] });
+		} else if (i >= desired.length) {
+			removed.push({ path: childPath, oldValue: current[i] });
+		} else {
+			diffObjects(current[i], desired[i], childPath, added, removed, changed, _ctx);
+		}
+	}
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (a == null || b == null) return a === b;
+	if (typeof a !== typeof b) return false;
+	if (typeof a !== "object") return false;
+
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		return a.every((val, i) => deepEqual(val, b[i]));
+	}
+
+	if (Array.isArray(a) || Array.isArray(b)) return false;
+
+	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 countLeafKeys(obj: unknown): number {
+	if (obj == null || typeof obj !== "object") return 1;
+	if (Array.isArray(obj)) return obj.reduce((sum, item) => sum + countLeafKeys(item), 0);
+	return Object.values(obj as Record<string, unknown>).reduce((sum: number, val) => sum + countLeafKeys(val), 0);
+}
+
+export function formatDiff(diff: ResourceDiff, kind: string, name: string): string {
+	if (!diff.hasDifferences) {
+		return `${kind}/${name}: no changes detected.`;
+	}
+
+	const lines: string[] = [];
+	lines.push(`diff ${kind}/${name}`);
+
+	for (const entry of diff.removed) {
+		lines.push(`- ${entry.path}: ${formatValue(entry.oldValue)}`);
+	}
+	for (const added of diff.added) {
+		lines.push(`+ ${added.path}: ${formatValue(added.newValue)}`);
+	}
+	for (const entry of diff.changed) {
+		lines.push(`~ ${entry.path}: ${formatValue(entry.oldValue)} → ${formatValue(entry.newValue)}`);
+	}
+
+	lines.push(`  ${diff.unchangedCount} field(s) unchanged`);
+	return lines.join("\n");
+}
+
+function formatValue(value: unknown): string {
+	if (value === undefined) return "<undefined>";
+	if (value === null) return "null";
+	if (typeof value === "string") return `"${value}"`;
+	if (typeof value === "object") {
+		const json = JSON.stringify(value);
+		return json.length > 80 ? `${json.slice(0, 77)}...` : json;
+	}
+	return String(value);
+}

package/src/file-reader.ts

@@ -0,0 +1,163 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseAllDocuments } from "yaml";
+
+const JSON_EXTENSIONS = new Set([".json"]);
+const YAML_EXTENSIONS = new Set([".yaml", ".yml"]);
+const SUPPORTED_EXTENSIONS = new Set([...JSON_EXTENSIONS, ...YAML_EXTENSIONS]);
+
+export interface FileReadResult {
+	objects: Record<string, unknown>[];
+	sourcePath: string;
+}
+
+export async function readManifestFiles(filenames: string[], recursive: boolean): Promise<FileReadResult[]> {
+	const results: FileReadResult[] = [];
+	for (const filename of filenames) {
+		if (filename === "-") {
+			results.push(await readFromStdin());
+			continue;
+		}
+
+		const resolved = path.resolve(filename);
+		const stat = await fs.promises.stat(resolved).catch(() => null);
+		if (!stat) {
+			throw new ManifestFileError(`File not found: ${filename}`);
+		}
+
+		if (stat.isDirectory()) {
+			const files = await collectDirectoryFiles(resolved, recursive);
+			for (const file of files) {
+				results.push(await readSingleFile(file));
+			}
+		} else {
+			results.push(await readSingleFile(resolved));
+		}
+	}
+	return results;
+}
+
+async function readSingleFile(filePath: string): Promise<FileReadResult> {
+	const ext = path.extname(filePath).toLowerCase();
+	const content = await fs.promises.readFile(filePath, "utf-8");
+
+	if (JSON_EXTENSIONS.has(ext)) {
+		return { objects: parseJsonContent(content, filePath), sourcePath: filePath };
+	}
+	if (YAML_EXTENSIONS.has(ext)) {
+		return { objects: parseYamlContent(content, filePath), sourcePath: filePath };
+	}
+
+	return { objects: parseAutoDetect(content, filePath), sourcePath: filePath };
+}
+
+function parseJsonContent(content: string, sourcePath: string): Record<string, unknown>[] {
+	const trimmed = content.trim();
+	if (!trimmed) return [];
+	try {
+		const parsed = JSON.parse(trimmed);
+		if (Array.isArray(parsed)) {
+			return parsed.filter((item): item is Record<string, unknown> => item != null && typeof item === "object");
+		}
+		if (typeof parsed === "object" && parsed !== null) {
+			return [parsed as Record<string, unknown>];
+		}
+		throw new ManifestFileError(`Expected object or array in ${sourcePath}, got ${typeof parsed}`);
+	} catch (err) {
+		if (err instanceof ManifestFileError) throw err;
+		throw new ManifestFileError(`Invalid JSON in ${sourcePath}: ${(err as Error).message}`);
+	}
+}
+
+function parseYamlContent(content: string, sourcePath: string): Record<string, unknown>[] {
+	const trimmed = content.trim();
+	if (!trimmed) return [];
+	try {
+		const docs = parseAllDocuments(trimmed);
+		const objects: Record<string, unknown>[] = [];
+		for (const doc of docs) {
+			if (doc.errors.length > 0) {
+				const firstError = doc.errors[0];
+				throw new ManifestFileError(`Invalid YAML in ${sourcePath}: ${firstError.message}`);
+			}
+			const value = doc.toJSON();
+			if (value != null && typeof value === "object" && !Array.isArray(value)) {
+				objects.push(value as Record<string, unknown>);
+			}
+		}
+		return objects;
+	} catch (err) {
+		if (err instanceof ManifestFileError) throw err;
+		throw new ManifestFileError(`Invalid YAML in ${sourcePath}: ${(err as Error).message}`);
+	}
+}
+
+function parseAutoDetect(content: string, sourcePath: string): Record<string, unknown>[] {
+	const trimmed = content.trim();
+	if (!trimmed) return [];
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+		return parseJsonContent(content, sourcePath);
+	}
+	return parseYamlContent(content, sourcePath);
+}
+
+async function collectDirectoryFiles(dirPath: string, recursive: boolean): Promise<string[]> {
+	const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+	const files: string[] = [];
+
+	for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+		const fullPath = path.join(dirPath, entry.name);
+		if (entry.isFile()) {
+			const ext = path.extname(entry.name).toLowerCase();
+			if (SUPPORTED_EXTENSIONS.has(ext)) {
+				files.push(fullPath);
+			}
+		} else if (entry.isDirectory() && recursive) {
+			files.push(...(await collectDirectoryFiles(fullPath, recursive)));
+		}
+	}
+	return files;
+}
+
+async function readFromStdin(): Promise<FileReadResult> {
+	return new Promise((resolve, reject) => {
+		const chunks: Buffer[] = [];
+		let timedOut = false;
+
+		const timer = setTimeout(() => {
+			timedOut = true;
+			if (chunks.length === 0) {
+				reject(new ManifestFileError("No data received from stdin (timed out after 5s)."));
+			}
+		}, 5000);
+
+		process.stdin.on("data", (chunk: Buffer) => {
+			chunks.push(chunk);
+		});
+
+		process.stdin.on("end", () => {
+			clearTimeout(timer);
+			if (timedOut && chunks.length === 0) return;
+			const content = Buffer.concat(chunks).toString("utf-8");
+			try {
+				resolve({ objects: parseAutoDetect(content, "stdin"), sourcePath: "stdin" });
+			} catch (err) {
+				reject(err);
+			}
+		});
+
+		process.stdin.on("error", err => {
+			clearTimeout(timer);
+			reject(new ManifestFileError(`Failed to read from stdin: ${err.message}`));
+		});
+
+		process.stdin.resume();
+	});
+}
+
+export class ManifestFileError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ManifestFileError";
+	}
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+export { parseExportArgs, parseResourceArgs } from "./arg-parser";
+export type { KindDefaultsMetadata } from "./defaults-metadata";
+export { buildFilterFromMetadata, buildMinimalExportFilter } from "./defaults-metadata";
+export { DEFAULTS_METADATA } from "./defaults-metadata.generated";
+export { computeResourceDiff, formatDiff } from "./diff-engine";
+export { ManifestFileError, readManifestFiles } from "./file-reader";
+export { createKindResolver, KindResolutionError } from "./kind-resolver";
+export type { ExportedManifest, ManifestOutputFormat, MinimalExportFilter } from "./manifest-export";
+export { applyMinimalExportFilter, formatManifestOutput, toManifest, toManifestList } from "./manifest-export";
+export { ManifestParseError, parseManifests } from "./manifest-parser";
+export { formatValidationErrors, validateManifest, validateManifests } from "./manifest-validator";
+export {
+	formatMultiOperationSummary,
+	formatOperationResult,
+	formatResourceDetail,
+	formatResourceList,
+} from "./output-formatter";
+export { FetchTransport, ResourceClient } from "./resource-client";
+export type {
+	ApiSpecDomainEntry,
+	ApiSpecDomainResource,
+	ApiSpecIndex,
+	ApiSpecValidationResourceEntry,
+	DiffEntry,
+	HttpTransport,
+	HttpTransportRequest,
+	HttpTransportResponse,
+	KindResolver,
+	ManifestValidationResult,
+	OperationResult,
+	ParsedExportArgs,
+	ParsedResourceArgs,
+	ResolvedKind,
+	ResourceClientOptions,
+	ResourceDiff,
+	ResourceError,
+	ResourceErrorKind,
+	ResourceManifest,
+	ValidationError,
+	ValidationErrorCode,
+	ValidationWarning,
+	ValidationWarningCode,
+} from "./types";

package/src/kind-resolver.ts

@@ -0,0 +1,157 @@
+import type {
+	ApiSpecDomainResource,
+	ApiSpecIndex,
+	ApiSpecValidationResourceEntry,
+	KindResolver,
+	ResolvedKind,
+} from "./types";
+
+export class KindResolutionError extends Error {
+	readonly suggestions: string[];
+	constructor(message: string, suggestions: string[] = []) {
+		super(message);
+		this.name = "KindResolutionError";
+		this.suggestions = suggestions;
+	}
+}
+
+export function createKindResolver(
+	specIndex: ApiSpecIndex,
+	validationData?: Readonly<Record<string, ApiSpecValidationResourceEntry>>,
+): KindResolver {
+	function resolveKind(kind: string): ResolvedKind {
+		let foundWithoutPaths = false;
+		for (const domain of specIndex.domains) {
+			for (const resource of domain.resources) {
+				if (resource.name === kind) {
+					const paths = extractPaths(resource);
+					if (!paths) {
+						foundWithoutPaths = true;
+						continue;
+					}
+					return {
+						kind,
+						domain: domain.domain,
+						resource,
+						paths,
+						validation: validationData?.[kind],
+					};
+				}
+			}
+		}
+
+		if (foundWithoutPaths) {
+			throw new KindResolutionError(`Resource kind "${kind}" exists but has no CRUD API paths defined.`);
+		}
+
+		const allKinds = getAllKnownKinds();
+		const suggestions = findSimilarKinds(kind, allKinds).slice(0, 5);
+		const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : "";
+		throw new KindResolutionError(`Unknown resource kind: "${kind}".${suggestionText}`, suggestions);
+	}
+
+	function getAllKnownKinds(): string[] {
+		const kinds: string[] = [];
+		for (const domain of specIndex.domains) {
+			for (const resource of domain.resources) {
+				kinds.push(resource.name);
+			}
+		}
+		return kinds.sort();
+	}
+
+	function getKindsWithApiPaths(): string[] {
+		const kinds: string[] = [];
+		for (const domain of specIndex.domains) {
+			for (const resource of domain.resources) {
+				if (resource.apiPaths && resource.apiPaths.length > 0) {
+					kinds.push(resource.name);
+				}
+			}
+		}
+		return kinds.sort();
+	}
+
+	return { resolveKind, getAllKnownKinds, getKindsWithApiPaths };
+}
+
+function extractPaths(resource: ApiSpecDomainResource): ResolvedKind["paths"] | null {
+	if (!resource.apiPaths || resource.apiPaths.length === 0) return null;
+
+	let listPath: string | undefined;
+	let itemPath: string | undefined;
+
+	for (const apiPath of resource.apiPaths) {
+		const normalized = normalizePathPlaceholders(apiPath);
+		const hasNamespace = normalized.includes("{namespace}");
+		const hasName = normalized.includes("{name}");
+
+		if (hasNamespace && !hasName && !listPath) {
+			listPath = normalized;
+		} else if (hasNamespace && hasName && !itemPath) {
+			itemPath = normalized;
+		}
+	}
+
+	if (!listPath && !itemPath) {
+		for (const apiPath of resource.apiPaths) {
+			const normalized = normalizePathPlaceholders(apiPath);
+			if (!normalized.includes("{name}") && !listPath) {
+				listPath = normalized;
+			} else if (normalized.includes("{name}") && !itemPath) {
+				itemPath = normalized;
+			}
+		}
+	}
+
+	if (!listPath) return null;
+	if (!itemPath && listPath) {
+		itemPath = `${listPath}/{name}`;
+	}
+
+	return {
+		list: listPath,
+		get: itemPath!,
+		create: listPath,
+		update: itemPath!,
+		delete: itemPath!,
+	};
+}
+
+function normalizePathPlaceholders(apiPath: string): string {
+	return apiPath.replace(/\{metadata\.namespace\}/g, "{namespace}").replace(/\{metadata\.name\}/g, "{name}");
+}
+
+function findSimilarKinds(input: string, candidates: string[]): string[] {
+	const scored = candidates.map(candidate => ({
+		kind: candidate,
+		score: similarityScore(input, candidate),
+	}));
+	return scored
+		.filter(s => s.score > 0.3)
+		.sort((a, b) => b.score - a.score)
+		.map(s => s.kind);
+}
+
+function similarityScore(a: string, b: string): number {
+	const la = a.toLowerCase();
+	const lb = b.toLowerCase();
+
+	if (la === lb) return 1;
+	if (lb.startsWith(la) || la.startsWith(lb)) return 0.8;
+	if (lb.includes(la) || la.includes(lb)) return 0.6;
+
+	const aParts = la.split("_");
+	const bParts = lb.split("_");
+	let matchCount = 0;
+	for (const ap of aParts) {
+		if (bParts.some(bp => bp === ap || bp.startsWith(ap) || ap.startsWith(bp))) {
+			matchCount++;
+		}
+	}
+	if (aParts.length > 0 && matchCount > 0) {
+		return (matchCount / Math.max(aParts.length, bParts.length)) * 0.5;
+	}
+
+	return 0;
+}