@f5xc-salesdemos/pi-utils 19.44.2 → 19.45.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/pi-utils",
-	"version": "19.44.2",
+	"version": "19.45.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.44.2"
+		"@f5xc-salesdemos/pi-natives": "19.45.0"
 	},
 	"engines": {
 		"bun": ">=1.3.7"

package/src/dirs.ts

@@ -441,40 +441,40 @@ export function getSSHConfigPath(scope: "user" | "project", cwd: string = getPro
 // F5 Distributed Cloud (F5 XC) context paths
 // =============================================================================
 
-const F5XC_DIR_NAME = "f5xc";
+const XCSH_DIR_NAME = "xcsh";
 
-/** Get the F5 XC config directory ($XDG_CONFIG_HOME/f5xc or ~/.config/f5xc). */
-export function getF5XCConfigDir(): string {
+/** Get the F5 XC config directory ($XDG_CONFIG_HOME/xcsh or ~/.config/xcsh). */
+export function getXCSHConfigDir(): string {
 	const xdgConfig = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
-	return path.join(xdgConfig, F5XC_DIR_NAME);
+	return path.join(xdgConfig, XCSH_DIR_NAME);
 }
 
-/** Get the F5 XC contexts directory (~/.config/f5xc/contexts). */
-export function getF5XCContextsDir(): string {
-	return path.join(getF5XCConfigDir(), "contexts");
+/** Get the F5 XC contexts directory (~/.config/xcsh/contexts). */
+export function getXCSHContextsDir(): string {
+	return path.join(getXCSHConfigDir(), "contexts");
 }
 
-/** Get the path to the active context indicator file (~/.config/f5xc/active_context). */
-export function getF5XCActiveContextPath(): string {
-	return path.join(getF5XCConfigDir(), "active_context");
+/** Get the path to the active context indicator file (~/.config/xcsh/active_context). */
+export function getXCSHActiveContextPath(): string {
+	return path.join(getXCSHConfigDir(), "active_context");
 }
 
-/** Get the path to a specific context JSON file (~/.config/f5xc/contexts/<name>.json). */
-export function getF5XCContextPath(name: string): string {
-	return path.join(getF5XCContextsDir(), `${name}.json`);
+/** Get the path to a specific context JSON file (~/.config/xcsh/contexts/<name>.json). */
+export function getXCSHContextPath(name: string): string {
+	return path.join(getXCSHContextsDir(), `${name}.json`);
 }
 
 /** Get the project-local F5 XC contexts directory (.xcsh/contexts under cwd). */
-export function getLocalF5XCContextsDir(cwd: string = getProjectDir()): string {
+export function getLocalXCSHContextsDir(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");
+export function getLocalXCSHActiveContextPath(cwd: string = getProjectDir()): string {
+	return path.join(getLocalXCSHContextsDir(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`);
+export function getLocalXCSHContextPath(name: string, cwd: string = getProjectDir()): string {
+	return path.join(getLocalXCSHContextsDir(cwd), `${name}.json`);
 }

package/src/index.ts

@@ -3,7 +3,6 @@ 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";
@@ -38,6 +37,8 @@ export * from "./tab-spacing";
 export * from "./temp";
 export * from "./type-guards";
 export * from "./which";
+export * from "./xcsh-context-paths";
+export * from "./xcsh-context-resolver";
 
 function isPlainObject(val: object): val is Record<string, unknown> {
 	return Object.getPrototypeOf(val) === Object.prototype || Array.isArray(val);

package/src/xcsh-context-paths.ts

@@ -0,0 +1,23 @@
+import {
+	getLocalXCSHActiveContextPath,
+	getLocalXCSHContextPath,
+	getLocalXCSHContextsDir,
+	getXCSHActiveContextPath,
+	getXCSHContextPath,
+	getXCSHContextsDir,
+} from "./dirs";
+import type { ContextPathProvider } from "./xcsh-context-resolver";
+
+/**
+ * The xcsh host's path provider for {@link ContextResolver}, wired to the
+ * `dirs.ts` family (`~/.config/xcsh/...`). The VS Code extension supplies its
+ * own provider from `contextPaths.ts`; both must resolve identical directories.
+ */
+export const xcshContextPaths: ContextPathProvider = {
+	getContextsDir: getXCSHContextsDir,
+	getActiveContextPath: getXCSHActiveContextPath,
+	getContextPath: getXCSHContextPath,
+	getLocalContextsDir: (cwd: string) => getLocalXCSHContextsDir(cwd),
+	getLocalActiveContextPath: (cwd: string) => getLocalXCSHActiveContextPath(cwd),
+	getLocalContextPath: (name: string, cwd: string) => getLocalXCSHContextPath(name, cwd),
+};

package/src/{f5xc-context-resolver.ts → xcsh-context-resolver.ts}

@@ -1,15 +1,8 @@
+import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import {
-	getF5XCActiveContextPath,
-	getF5XCContextPath,
-	getF5XCContextsDir,
-	getLocalF5XCActiveContextPath,
-	getLocalF5XCContextPath,
-	getLocalF5XCContextsDir,
-} from "./dirs";
-
-export interface F5XCContextData {
+
+export interface XCSHContextData {
 	name: string;
 	apiUrl: string;
 	apiToken: string;
@@ -51,11 +44,34 @@ export interface PointerContext {
 export type ContextSource = "env" | "local" | "global";
 
 export interface ResolvedContext {
-	context: F5XCContextData;
+	context: XCSHContextData;
 	source: ContextSource;
 	sourcePath: string;
 }
 
+/**
+ * Host-supplied path helpers. xcsh injects the `dirs.ts` family; the VS Code
+ * extension injects its `contextPaths.ts` family. Keeping the resolver free of a
+ * direct `dirs.ts` import keeps this module runtime-agnostic (no Bun globals, no
+ * JSON imports) so it bundles cleanly into the VS Code extension via webpack.
+ */
+export interface ContextPathProvider {
+	getContextsDir(): string;
+	getActiveContextPath(): string;
+	getContextPath(name: string): string;
+	getLocalContextsDir(cwd: string): string;
+	getLocalActiveContextPath(cwd: string): string;
+	getLocalContextPath(name: string, cwd: string): string;
+}
+
+export type GitTracker = (filePath: string) => Promise<boolean>;
+
+export interface ResolverDeps {
+	paths: ContextPathProvider;
+	/** Optional override; defaults to a `node:child_process` implementation that runs under both Bun and Node. */
+	gitTracker?: GitTracker;
+}
+
 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>;
@@ -85,7 +101,7 @@ export function validateLocalContextFile(data: unknown): { valid: boolean; error
 	return { valid: true };
 }
 
-export function mergePointerOverrides(base: F5XCContextData, overrides: ContextOverrides): F5XCContextData {
+export function mergePointerOverrides(base: XCSHContextData, overrides: ContextOverrides): XCSHContextData {
 	const merged = { ...base };
 
 	if (overrides.defaultNamespace !== undefined) {
@@ -110,70 +126,126 @@ export function mergePointerOverrides(base: F5XCContextData, overrides: ContextO
 	return merged;
 }
 
+/**
+ * Subcommand names that must not be usable as context names — otherwise
+ * `/context <name>` could not disambiguate a switch from a subcommand. Single
+ * source of truth shared by both the resolver and the coding agent.
+ */
+export const RESERVED_CONTEXT_NAMES = new Set([
+	"list",
+	"show",
+	"status",
+	"create",
+	"delete",
+	"rename",
+	"namespace",
+	"env",
+	"set",
+	"unset",
+	"add",
+	"remove",
+	"clear",
+	"activate",
+	"validate",
+	"export",
+	"import",
+	"wizard",
+	"help",
+	"link",
+	"unlink",
+]);
+
 const CONTEXT_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 
 export function isSafeContextName(name: string): boolean {
-	return CONTEXT_NAME_RE.test(name);
+	if (!CONTEXT_NAME_RE.test(name)) return false;
+	return !RESERVED_CONTEXT_NAMES.has(name.toLowerCase());
+}
+
+/**
+ * Normalize an API URL for safe path joining by stripping trailing slash(es).
+ *
+ * The shared resource library joins URLs by raw concatenation
+ * (`${apiUrl}${path}`) where path templates begin with `/api/...`. A trailing
+ * slash produces `https://host/api//api/...`; after the transport strips the
+ * base URL the remainder begins with `//`, which `new URL()` parses as a
+ * protocol-relative authority — collapsing the host to a bare label and breaking
+ * TLS altname verification. Stripping trailing slashes prevents this.
+ */
+export function normalizeApiUrl(apiUrl: string): string {
+	return typeof apiUrl === "string" ? apiUrl.replace(/\/+$/, "") : apiUrl;
+}
+
+function defaultGitTracker(filePath: string): Promise<boolean> {
+	try {
+		const dir = path.dirname(filePath);
+		const res = spawnSync("git", ["ls-files", "--error-unmatch", filePath], {
+			cwd: dir,
+			stdio: "ignore",
+		});
+		return Promise.resolve(res.status === 0);
+	} catch {
+		return Promise.resolve(false);
+	}
 }
 
 export class ContextResolver {
+	readonly #paths: ContextPathProvider;
+	readonly #gitTracker: GitTracker;
+
+	constructor(deps: ResolverDeps) {
+		this.#paths = deps.paths;
+		this.#gitTracker = deps.gitTracker ?? defaultGitTracker;
+	}
+
 	resolve(cwd: string): Promise<ResolvedContext | null> {
 		// Priority 1: environment variables
-		const envUrl = process.env.F5XC_API_URL;
-		const envToken = process.env.F5XC_API_TOKEN;
+		const envUrl = process.env.XCSH_API_URL;
+		const envToken = process.env.XCSH_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",
-			});
+			return Promise.resolve(
+				this.#finalize(
+					{
+						name: "(env)",
+						apiUrl: envUrl,
+						apiToken: envToken,
+						defaultNamespace: process.env.XCSH_NAMESPACE ?? "system",
+					},
+					"env",
+					"environment variables",
+				),
+			);
 		}
 
 		// Priority 2: local .xcsh/contexts/
 		const localDir = this.findLocalContextsDir(cwd);
 		if (localDir) {
-			const localResult = this.#resolveFromDir(localDir, "local", cwd);
+			const localResult = this.#resolveFromDir("local", cwd);
 			if (localResult) return Promise.resolve(localResult);
 		}
 
-		// Priority 3: global ~/.config/f5xc/contexts/
-		const globalResult = this.#resolveGlobal();
-		return Promise.resolve(globalResult);
+		// Priority 3: global ~/.config/xcsh/contexts/
+		return Promise.resolve(this.#resolveGlobal());
 	}
 
 	findLocalContextsDir(cwd: string): string | null {
-		const dir = getLocalF5XCContextsDir(cwd);
+		const dir = this.#paths.getLocalContextsDir(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;
-		}
+	checkGitTracking(filePath: string): Promise<boolean> {
+		return this.#gitTracker(filePath);
 	}
 
-	#resolveFromDir(_contextsDir: string, source: ContextSource, cwd: string): ResolvedContext | null {
-		const activeContextPath = source === "local" ? getLocalF5XCActiveContextPath(cwd) : getF5XCActiveContextPath();
+	#resolveFromDir(source: ContextSource, cwd: string): ResolvedContext | null {
+		const activeContextPath =
+			source === "local" ? this.#paths.getLocalActiveContextPath(cwd) : this.#paths.getActiveContextPath();
 
 		const activeName = this.#readActivePointer(activeContextPath);
 		if (!activeName || !isSafeContextName(activeName)) return null;
 
 		const contextPath =
-			source === "local" ? getLocalF5XCContextPath(activeName, cwd) : getF5XCContextPath(activeName);
+			source === "local" ? this.#paths.getLocalContextPath(activeName, cwd) : this.#paths.getContextPath(activeName);
 
 		const data = this.#readJsonFile(contextPath);
 		if (!data) return null;
@@ -182,7 +254,7 @@ export class ContextResolver {
 		if (!validation.valid) return null;
 
 		if (isPointerContext(data)) {
-			return this.#resolvePointer(data, contextPath, cwd);
+			return this.#resolvePointer(data, contextPath);
 		}
 
 		if (isInlineContext(data)) {
@@ -194,38 +266,38 @@ export class ContextResolver {
 			) {
 				return null;
 			}
-			return {
-				context: data as unknown as F5XCContextData,
-				source,
-				sourcePath: contextPath,
-			};
+			return this.#finalize(data as unknown as XCSHContextData, source, contextPath);
 		}
 
 		return null;
 	}
 
 	#resolveGlobal(): ResolvedContext | null {
-		const globalContextsDir = getF5XCContextsDir();
+		const globalContextsDir = this.#paths.getContextsDir();
 		if (!fs.existsSync(globalContextsDir)) return null;
-		return this.#resolveFromDir(globalContextsDir, "global", "");
+		return this.#resolveFromDir("global", "");
 	}
 
-	#resolvePointer(pointer: PointerContext, pointerPath: string, _cwd: string): ResolvedContext | null {
+	#resolvePointer(pointer: PointerContext, pointerPath: string): ResolvedContext | null {
 		if (!isSafeContextName(pointer.context)) return null;
-		const globalPath = getF5XCContextPath(pointer.context);
+		const globalPath = this.#paths.getContextPath(pointer.context);
 		const globalData = this.#readJsonFile(globalPath);
 		if (!globalData) return null;
 
-		let resolved = globalData as unknown as F5XCContextData;
+		let resolved = globalData as unknown as XCSHContextData;
 		if (pointer.overrides) {
 			resolved = mergePointerOverrides(resolved, pointer.overrides);
 		}
 
-		return {
-			context: resolved,
-			source: "local",
-			sourcePath: pointerPath,
-		};
+		// A pointer always resolves through the local tier, so report "local".
+		return this.#finalize(resolved, "local", pointerPath);
+	}
+
+	/** Stamp source/path and normalize the resolved apiUrl uniformly across all sources. */
+	#finalize(context: XCSHContextData, source: ContextSource, sourcePath: string): ResolvedContext {
+		const normalized =
+			typeof context.apiUrl === "string" ? { ...context, apiUrl: normalizeApiUrl(context.apiUrl) } : context;
+		return { context: normalized, source, sourcePath };
 	}
 
 	#readActivePointer(filePath: string): string | null {