@f5xc-salesdemos/pi-utils 19.42.1 → 19.43.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/pi-utils",
-	"version": "19.42.1",
+	"version": "19.43.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -39,7 +39,7 @@
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3",
-		"@f5xc-salesdemos/pi-natives": "19.42.1"
+		"@f5xc-salesdemos/pi-natives": "19.43.0"
 	},
 	"engines": {
 		"bun": ">=1.3.7"

package/src/dirs.ts

@@ -463,3 +463,18 @@ export function getF5XCActiveContextPath(): string {
 export function getF5XCContextPath(name: string): string {
 	return path.join(getF5XCContextsDir(), `${name}.json`);
 }
+
+/** Get the project-local F5 XC contexts directory (.xcsh/contexts under cwd). */
+export function getLocalF5XCContextsDir(cwd: string = getProjectDir()): string {
+	return path.join(cwd, CONFIG_DIR_NAME, "contexts");
+}
+
+/** Get the project-local active context pointer (.xcsh/contexts/active_context). */
+export function getLocalF5XCActiveContextPath(cwd: string = getProjectDir()): string {
+	return path.join(getLocalF5XCContextsDir(cwd), "active_context");
+}
+
+/** Get the path to a project-local context JSON (.xcsh/contexts/<name>.json). */
+export function getLocalF5XCContextPath(name: string, cwd: string = getProjectDir()): string {
+	return path.join(getLocalF5XCContextsDir(cwd), `${name}.json`);
+}

package/src/f5xc-context-resolver.ts

@@ -0,0 +1,250 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+	getF5XCActiveContextPath,
+	getF5XCContextPath,
+	getF5XCContextsDir,
+	getLocalF5XCActiveContextPath,
+	getLocalF5XCContextPath,
+	getLocalF5XCContextsDir,
+} from "./dirs";
+
+export interface F5XCContextData {
+	name: string;
+	apiUrl: string;
+	apiToken: string;
+	defaultNamespace: string;
+	env?: Record<string, string>;
+	sensitiveKeys?: string[];
+	knowledgeSources?: KnowledgeSource[];
+	includeSkills?: string[];
+	excludeSkills?: string[];
+	version?: number;
+	metadata?: {
+		createdAt?: string;
+		expiresAt?: string;
+		lastRotatedAt?: string;
+		rotateAfterDays?: number;
+	};
+}
+
+export interface KnowledgeSource {
+	url: string;
+	label?: string;
+	type?: "llms-txt" | "skill-dir" | "docs-site";
+}
+
+export interface ContextOverrides {
+	defaultNamespace?: string;
+	env?: Record<string, string>;
+	sensitiveKeys?: string[];
+	knowledgeSources?: KnowledgeSource[];
+	includeSkills?: string[];
+	excludeSkills?: string[];
+}
+
+export interface PointerContext {
+	context: string;
+	overrides?: ContextOverrides;
+}
+
+export type ContextSource = "env" | "local" | "global";
+
+export interface ResolvedContext {
+	context: F5XCContextData;
+	source: ContextSource;
+	sourcePath: string;
+}
+
+export function isPointerContext(data: unknown): data is PointerContext {
+	if (data === null || data === undefined || typeof data !== "object") return false;
+	const obj = data as Record<string, unknown>;
+	return typeof obj.context === "string" && !("apiUrl" in obj);
+}
+
+export function isInlineContext(data: unknown): boolean {
+	if (data === null || data === undefined || typeof data !== "object") return false;
+	const obj = data as Record<string, unknown>;
+	return typeof obj.apiUrl === "string";
+}
+
+export function validateLocalContextFile(data: unknown): { valid: boolean; error?: string } {
+	if (data === null || data === undefined || typeof data !== "object") {
+		return { valid: false, error: "Context file must be a JSON object" };
+	}
+	const obj = data as Record<string, unknown>;
+	const hasContext = typeof obj.context === "string";
+	const hasApiUrl = typeof obj.apiUrl === "string";
+
+	if (hasContext && hasApiUrl) {
+		return { valid: false, error: "Context file cannot have both 'context' (pointer) and 'apiUrl' (inline) fields" };
+	}
+	if (!hasContext && !hasApiUrl) {
+		return { valid: false, error: "Context file must have either 'context' (pointer) or 'apiUrl' (inline) field" };
+	}
+	return { valid: true };
+}
+
+export function mergePointerOverrides(base: F5XCContextData, overrides: ContextOverrides): F5XCContextData {
+	const merged = { ...base };
+
+	if (overrides.defaultNamespace !== undefined) {
+		merged.defaultNamespace = overrides.defaultNamespace;
+	}
+	if (overrides.sensitiveKeys !== undefined) {
+		merged.sensitiveKeys = overrides.sensitiveKeys;
+	}
+	if (overrides.knowledgeSources !== undefined) {
+		merged.knowledgeSources = overrides.knowledgeSources;
+	}
+	if (overrides.includeSkills !== undefined) {
+		merged.includeSkills = overrides.includeSkills;
+	}
+	if (overrides.excludeSkills !== undefined) {
+		merged.excludeSkills = overrides.excludeSkills;
+	}
+	if (overrides.env !== undefined) {
+		merged.env = { ...base.env, ...overrides.env };
+	}
+
+	return merged;
+}
+
+const CONTEXT_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+
+export function isSafeContextName(name: string): boolean {
+	return CONTEXT_NAME_RE.test(name);
+}
+
+export class ContextResolver {
+	resolve(cwd: string): Promise<ResolvedContext | null> {
+		// Priority 1: environment variables
+		const envUrl = process.env.F5XC_API_URL;
+		const envToken = process.env.F5XC_API_TOKEN;
+		if (envUrl && envToken) {
+			return Promise.resolve({
+				context: {
+					name: "(env)",
+					apiUrl: envUrl,
+					apiToken: envToken,
+					defaultNamespace: process.env.F5XC_NAMESPACE ?? "system",
+				},
+				source: "env",
+				sourcePath: "environment variables",
+			});
+		}
+
+		// Priority 2: local .xcsh/contexts/
+		const localDir = this.findLocalContextsDir(cwd);
+		if (localDir) {
+			const localResult = this.#resolveFromDir(localDir, "local", cwd);
+			if (localResult) return Promise.resolve(localResult);
+		}
+
+		// Priority 3: global ~/.config/f5xc/contexts/
+		const globalResult = this.#resolveGlobal();
+		return Promise.resolve(globalResult);
+	}
+
+	findLocalContextsDir(cwd: string): string | null {
+		const dir = getLocalF5XCContextsDir(cwd);
+		return fs.existsSync(dir) ? dir : null;
+	}
+
+	async checkGitTracking(filePath: string): Promise<boolean> {
+		try {
+			const dir = path.dirname(filePath);
+			const proc = Bun.spawn(["git", "ls-files", "--error-unmatch", filePath], {
+				cwd: dir,
+				stdout: "ignore",
+				stderr: "ignore",
+			});
+			const code = await proc.exited;
+			return code === 0;
+		} catch {
+			return false;
+		}
+	}
+
+	#resolveFromDir(_contextsDir: string, source: ContextSource, cwd: string): ResolvedContext | null {
+		const activeContextPath = source === "local" ? getLocalF5XCActiveContextPath(cwd) : getF5XCActiveContextPath();
+
+		const activeName = this.#readActivePointer(activeContextPath);
+		if (!activeName || !isSafeContextName(activeName)) return null;
+
+		const contextPath =
+			source === "local" ? getLocalF5XCContextPath(activeName, cwd) : getF5XCContextPath(activeName);
+
+		const data = this.#readJsonFile(contextPath);
+		if (!data) return null;
+
+		const validation = validateLocalContextFile(data);
+		if (!validation.valid) return null;
+
+		if (isPointerContext(data)) {
+			return this.#resolvePointer(data, contextPath, cwd);
+		}
+
+		if (isInlineContext(data)) {
+			const obj = data as Record<string, unknown>;
+			if (
+				typeof obj.name !== "string" ||
+				typeof obj.apiToken !== "string" ||
+				typeof obj.defaultNamespace !== "string"
+			) {
+				return null;
+			}
+			return {
+				context: data as unknown as F5XCContextData,
+				source,
+				sourcePath: contextPath,
+			};
+		}
+
+		return null;
+	}
+
+	#resolveGlobal(): ResolvedContext | null {
+		const globalContextsDir = getF5XCContextsDir();
+		if (!fs.existsSync(globalContextsDir)) return null;
+		return this.#resolveFromDir(globalContextsDir, "global", "");
+	}
+
+	#resolvePointer(pointer: PointerContext, pointerPath: string, _cwd: string): ResolvedContext | null {
+		if (!isSafeContextName(pointer.context)) return null;
+		const globalPath = getF5XCContextPath(pointer.context);
+		const globalData = this.#readJsonFile(globalPath);
+		if (!globalData) return null;
+
+		let resolved = globalData as unknown as F5XCContextData;
+		if (pointer.overrides) {
+			resolved = mergePointerOverrides(resolved, pointer.overrides);
+		}
+
+		return {
+			context: resolved,
+			source: "local",
+			sourcePath: pointerPath,
+		};
+	}
+
+	#readActivePointer(filePath: string): string | null {
+		if (!fs.existsSync(filePath)) return null;
+		try {
+			const name = fs.readFileSync(filePath, "utf-8").trim();
+			return name || null;
+		} catch {
+			return null;
+		}
+	}
+
+	#readJsonFile(filePath: string): Record<string, unknown> | null {
+		if (!fs.existsSync(filePath)) return null;
+		try {
+			const raw = fs.readFileSync(filePath, "utf-8");
+			return JSON.parse(raw) as Record<string, unknown>;
+		} catch {
+			return null;
+		}
+	}
+}

package/src/index.ts

@@ -3,6 +3,7 @@ export * from "./async";
 export * from "./color";
 export * from "./dirs";
 export * from "./env";
+export * from "./f5xc-context-resolver";
 export * from "./format";
 export * from "./frontmatter";
 export * from "./fs-error";