@f5xc-salesdemos/pi-resource-management 19.30.1

package/package.json

@@ -0,0 +1,57 @@
+{
+	"type": "module",
+	"name": "@f5xc-salesdemos/pi-resource-management",
+	"version": "19.30.1",
+	"description": "Shared resource management for F5 XC manifest parsing, validation, diff, and CRUD operations",
+	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
+	"author": "Robin Mordasiewicz",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/f5xc-salesdemos/xcsh.git",
+		"directory": "packages/resource-management"
+	},
+	"bugs": {
+		"url": "https://github.com/f5xc-salesdemos/xcsh/issues"
+	},
+	"keywords": [
+		"f5xc",
+		"resource-management",
+		"kubectl",
+		"apply",
+		"manifest"
+	],
+	"main": "./src/index.ts",
+	"types": "./src/index.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"yaml": "2.9.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3"
+	},
+	"engines": {
+		"bun": ">=1.3.7"
+	},
+	"files": [
+		"src"
+	],
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./src/*.ts",
+			"import": "./src/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}

package/src/arg-parser.ts

@@ -0,0 +1,73 @@
+import type { ParsedResourceArgs } from "./types";
+
+const VALID_OUTPUT_FORMATS = new Set(["json", "yaml", "table", "wide"]);
+const VALID_DRY_RUN_MODES = new Set(["client", "server"]);
+
+export function parseResourceArgs(argsString: string): ParsedResourceArgs | { error: string } {
+	const tokens = argsString.split(/\s+/).filter(Boolean);
+	const filenames: string[] = [];
+	let namespace: string | undefined;
+	let outputFormat: ParsedResourceArgs["outputFormat"] = "table";
+	let dryRun: ParsedResourceArgs["dryRun"];
+	let recursive = false;
+	let force = false;
+	const positionals: string[] = [];
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+
+		if (token === "-f" || token === "--filename") {
+			if (i + 1 >= tokens.length) return { error: `${token} requires a file path.` };
+			filenames.push(tokens[++i]);
+		} else if (token.startsWith("-f") && token.length > 2 && token[2] !== "-") {
+			filenames.push(token.slice(2));
+		} else if (token === "-n" || token === "--namespace") {
+			if (i + 1 >= tokens.length) return { error: `${token} requires a namespace value.` };
+			namespace = tokens[++i];
+		} else if (token.startsWith("-n") && token.length > 2 && token[2] !== "-") {
+			namespace = token.slice(2);
+		} else if (token === "-o" || token === "--output") {
+			if (i + 1 >= tokens.length) return { error: `${token} requires a format value (json, yaml, table, wide).` };
+			const fmt = tokens[++i];
+			if (!VALID_OUTPUT_FORMATS.has(fmt)) {
+				return { error: `Invalid output format: "${fmt}". Must be one of: json, yaml, table, wide.` };
+			}
+			outputFormat = fmt as ParsedResourceArgs["outputFormat"];
+		} else if (token.startsWith("-o") && token.length > 2 && token[2] !== "-") {
+			const fmt = token.slice(2);
+			if (!VALID_OUTPUT_FORMATS.has(fmt)) {
+				return { error: `Invalid output format: "${fmt}". Must be one of: json, yaml, table, wide.` };
+			}
+			outputFormat = fmt as ParsedResourceArgs["outputFormat"];
+		} else if (token.startsWith("--dry-run")) {
+			if (token.includes("=")) {
+				const mode = token.split("=")[1];
+				if (!VALID_DRY_RUN_MODES.has(mode)) {
+					return { error: `Invalid --dry-run mode: "${mode}". Must be "client" or "server".` };
+				}
+				dryRun = mode as ParsedResourceArgs["dryRun"];
+			} else {
+				dryRun = "client";
+			}
+		} else if (token === "-R" || token === "--recursive") {
+			recursive = true;
+		} else if (token === "--force") {
+			force = true;
+		} else if (token.startsWith("-")) {
+			return { error: `Unknown flag: "${token}".` };
+		} else {
+			positionals.push(token);
+		}
+	}
+
+	return {
+		filenames,
+		namespace,
+		outputFormat,
+		dryRun,
+		recursive,
+		force,
+		kind: positionals[0],
+		name: positionals[1],
+	};
+}

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,34 @@
+export { parseResourceArgs } from "./arg-parser";
+export { computeResourceDiff, formatDiff } from "./diff-engine";
+export { ManifestFileError, readManifestFiles } from "./file-reader";
+export { createKindResolver, KindResolutionError } from "./kind-resolver";
+export { ManifestParseError, parseManifests } from "./manifest-parser";
+export { formatValidationErrors, validateManifest, validateManifests } from "./manifest-validator";
+export {
+	formatMultiOperationSummary,
+	formatOperationResult,
+	formatResourceDetail,
+	formatResourceList,
+} from "./output-formatter";
+export { ResourceClient } from "./resource-client";
+export type {
+	ApiSpecDomainEntry,
+	ApiSpecDomainResource,
+	ApiSpecIndex,
+	ApiSpecValidationResourceEntry,
+	DiffEntry,
+	KindResolver,
+	ManifestValidationResult,
+	OperationResult,
+	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;
+}