@f5-sales-demo/pi-utils 19.51.2

package/src/xcsh-context-resolver.ts

@@ -0,0 +1,333 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface XCSHContextData {
+	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: 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>;
+	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: XCSHContextData, overrides: ContextOverrides): XCSHContextData {
+	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;
+}
+
+/**
+ * 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 {
+	if (!CONTEXT_NAME_RE.test(name)) return false;
+	return !RESERVED_CONTEXT_NAMES.has(name.toLowerCase());
+}
+
+/**
+ * Normalize an API URL to its origin (`https://host[:port]`) — the canonical
+ * stored form for a context endpoint, shared verbatim by the xcsh shell and the
+ * VS Code extension.
+ *
+ * The stored value must be the bare origin only: no path, query, fragment, or
+ * trailing slash. Callers append `/api/...` themselves, so the endpoint stays a
+ * single consistent value. This also defuses the protocol-relative host
+ * collapse: the shared resource library joins URLs by raw concatenation
+ * (`${apiUrl}${path}`), and a leftover path or trailing slash would produce a
+ * `//` that `new URL()` parses as an authority — collapsing the host to a bare
+ * label and breaking TLS altname verification.
+ */
+export function normalizeApiUrl(apiUrl: string): string {
+	if (typeof apiUrl !== "string") return apiUrl;
+	const trimmed = apiUrl.trim();
+	try {
+		return new URL(trimmed).origin;
+	} catch {
+		// Not a parseable absolute URL (input validation should prevent this);
+		// fall back to stripping trailing slashes so we never worsen a bad value.
+		return trimmed.replace(/\/+$/, "");
+	}
+}
+
+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.XCSH_API_URL;
+		const envToken = process.env.XCSH_API_TOKEN;
+		if (envUrl && envToken) {
+			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("local", cwd);
+			if (localResult) return Promise.resolve(localResult);
+		}
+
+		// Priority 3: global ~/.config/xcsh/contexts/
+		return Promise.resolve(this.#resolveGlobal());
+	}
+
+	findLocalContextsDir(cwd: string): string | null {
+		const dir = this.#paths.getLocalContextsDir(cwd);
+		return fs.existsSync(dir) ? dir : null;
+	}
+
+	checkGitTracking(filePath: string): Promise<boolean> {
+		return this.#gitTracker(filePath);
+	}
+
+	#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" ? this.#paths.getLocalContextPath(activeName, cwd) : this.#paths.getContextPath(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);
+		}
+
+		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 this.#finalize(data as unknown as XCSHContextData, source, contextPath);
+		}
+
+		return null;
+	}
+
+	#resolveGlobal(): ResolvedContext | null {
+		const globalContextsDir = this.#paths.getContextsDir();
+		if (!fs.existsSync(globalContextsDir)) return null;
+		return this.#resolveFromDir("global", "");
+	}
+
+	#resolvePointer(pointer: PointerContext, pointerPath: string): ResolvedContext | null {
+		if (!isSafeContextName(pointer.context)) return null;
+		const globalPath = this.#paths.getContextPath(pointer.context);
+		const globalData = this.#readJsonFile(globalPath);
+		if (!globalData) return null;
+
+		let resolved = globalData as unknown as XCSHContextData;
+		if (pointer.overrides) {
+			resolved = mergePointerOverrides(resolved, pointer.overrides);
+		}
+
+		// 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 {
+		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/xcsh-env-names.ts

@@ -0,0 +1,69 @@
+/**
+ * Canonical F5 XC context environment-variable names and the secret-detection
+ * rule, shared by every host (the xcsh shell and the VS Code extension) so both
+ * agree on which keys are reserved, which are recognized auth credentials, and
+ * which values must be masked.
+ *
+ * This module is intentionally dependency-free (no Bun/Node APIs) so a CommonJS
+ * `require()` from the extension can load it without dragging in the Bun-only
+ * barrel. Names are typed `as const` so bracket access like
+ * `process.env[XCSH_API_URL]` type-checks correctly.
+ */
+
+export const XCSH_API_URL = "XCSH_API_URL" as const;
+export const XCSH_API_TOKEN = "XCSH_API_TOKEN" as const;
+export const XCSH_NAMESPACE = "XCSH_NAMESPACE" as const;
+export const XCSH_TENANT = "XCSH_TENANT" as const;
+export const XCSH_USERNAME = "XCSH_USERNAME" as const;
+export const XCSH_CONSOLE_PASSWORD = "XCSH_CONSOLE_PASSWORD" as const;
+/** Active context profile name. Read-only metadata injected by ContextService. */
+export const XCSH_CONTEXT_NAME = "XCSH_CONTEXT_NAME" as const;
+
+/**
+ * Control env vars owned by the context itself (apiUrl/apiToken/defaultNamespace
+ * → XCSH_API_URL/XCSH_API_TOKEN/XCSH_NAMESPACE), derived (XCSH_TENANT), or
+ * injected at activation (XCSH_CONTEXT_NAME). A context's custom `env` map must
+ * never set these — they would be ignored or clobbered by the resolver.
+ */
+export const RESERVED_ENV_KEYS: ReadonlySet<string> = new Set([
+	XCSH_NAMESPACE,
+	XCSH_API_URL,
+	XCSH_API_TOKEN,
+	XCSH_TENANT,
+	XCSH_CONTEXT_NAME,
+]);
+
+/**
+ * Recognized web-console login credentials. Unlike RESERVED_ENV_KEYS these live
+ * in the context's generic `env` map (a user sets them like any other variable),
+ * but hosts surface them in a dedicated "Auth" section, in display order.
+ */
+export const AUTH_ENV_KEYS: readonly string[] = [XCSH_USERNAME, XCSH_CONSOLE_PASSWORD];
+
+/** Env var name patterns that indicate a secret value (mask in output, redact on export). */
+export const SECRET_ENV_PATTERNS = /(?:KEY|SECRET|TOKEN|PASSWORD|PASS|AUTH|CREDENTIAL|PRIVATE|OAUTH)(?:_|$)/i;
+
+/** True iff an env var NAME looks like it holds a secret (e.g. XCSH_CONSOLE_PASSWORD). */
+export function isSensitiveEnvKey(key: string): boolean {
+	return SECRET_ENV_PATTERNS.test(key);
+}
+
+/** Prefix that namespaces every context-owned environment variable. */
+export const XCSH_ENV_PREFIX = "XCSH_";
+
+/**
+ * True iff a context's `env` entry may be injected into a spawned subprocess.
+ *
+ * This is an allowlist (default-deny): only `XCSH_`-namespaced, non-reserved keys
+ * are injectable. A project-local `.xcsh/contexts/*.json` is untrusted input, so a
+ * denylist of "dangerous" names is unsafe — it is impossible to enumerate every
+ * process/interpreter-hijacking variable (LD_PRELOAD, DYLD_INSERT_LIBRARIES,
+ * NODE_OPTIONS, NODE_PATH, PATH, PYTHONHOME, JAVA_TOOL_OPTIONS, CLASSPATH, …).
+ * Restricting injection to the `XCSH_` namespace blocks all of them by
+ * construction, since none are `XCSH_`-prefixed. Reserved keys (XCSH_API_URL,
+ * XCSH_API_TOKEN, XCSH_NAMESPACE, XCSH_TENANT, XCSH_CONTEXT_NAME) are excluded too —
+ * the host sets those itself from the context's typed fields.
+ */
+export function isInjectableContextEnvKey(key: string): boolean {
+	return key.startsWith(XCSH_ENV_PREFIX) && !RESERVED_ENV_KEYS.has(key);
+}