@f5xc-salesdemos/xcsh 18.13.0 → 18.14.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.13.0",
+	"version": "18.14.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -47,12 +47,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.13.0",
-		"@f5xc-salesdemos/pi-agent-core": "18.13.0",
-		"@f5xc-salesdemos/pi-ai": "18.13.0",
-		"@f5xc-salesdemos/pi-natives": "18.13.0",
-		"@f5xc-salesdemos/pi-tui": "18.13.0",
-		"@f5xc-salesdemos/pi-utils": "18.13.0",
+		"@f5xc-salesdemos/xcsh-stats": "18.14.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.14.0",
+		"@f5xc-salesdemos/pi-ai": "18.14.0",
+		"@f5xc-salesdemos/pi-natives": "18.14.0",
+		"@f5xc-salesdemos/pi-tui": "18.14.0",
+		"@f5xc-salesdemos/pi-utils": "18.14.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.13.0",
-	"commit": "90af1747f04e90d8ebc6ccfe4d0bd8c7f6347760",
-	"shortCommit": "90af174",
+	"version": "18.14.0",
+	"commit": "f1b1d44fd6a0481b3745e233a70756df5d45f335",
+	"shortCommit": "f1b1d44",
 	"branch": "main",
-	"tag": "v18.13.0",
-	"commitDate": "2026-04-23T15:10:43Z",
-	"buildDate": "2026-04-23T15:30:07.473Z",
+	"tag": "v18.14.0",
+	"commitDate": "2026-04-23T21:05:32Z",
+	"buildDate": "2026-04-23T21:32:33.280Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/90af1747f04e90d8ebc6ccfe4d0bd8c7f6347760",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.13.0"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/f1b1d44fd6a0481b3745e233a70756df5d45f335",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.14.0"
 };

package/src/modes/components/welcome-checks.ts

@@ -11,7 +11,9 @@ const STARTUP_FIRST_TIMEOUT_MS = 4000;
 const STARTUP_RETRY_TIMEOUT_MS = 5000;
 const STARTUP_RETRY_DELAY_MS = 500;
 
-type ProfileValidator = (opts: { timeoutMs: number }) => Promise<{ status: AuthStatus; latencyMs?: number }>;
+type ProfileValidator = (opts: {
+	timeoutMs: number;
+}) => Promise<{ status: AuthStatus; latencyMs?: number; errorClass?: "network" | "credential" }>;
 
 /**
  * Runs the profile validator once with a startup-sized timeout; if the result is `offline`

package/src/services/f5xc-profile-command.ts

@@ -8,8 +8,14 @@ import {
 	F5XC_TENANT,
 	F5XC_USERNAME,
 } from "./f5xc-env";
-import { ProfileError, ProfileService } from "./f5xc-profile";
-import { formatAuthIndicator, renderF5XCTable, type TableRow } from "./f5xc-table";
+import { CURRENT_SCHEMA_VERSION, ProfileError, ProfileService } from "./f5xc-profile";
+import {
+	formatAuthIndicator,
+	formatExpiration,
+	formatRelativeTime,
+	renderF5XCTable,
+	type TableRow,
+} from "./f5xc-table";
 
 interface CommandContext {
 	showStatus(msg: string): void;
@@ -81,14 +87,16 @@ async function handleList(ctx: CommandContext, service: ProfileService): Promise
 	const status = service.getStatus();
 	const lines = profiles.map(p => {
 		const marker = p.name === status.activeProfileName ? "*" : " ";
-		return `  ${marker} ${sanitize(p.name).padEnd(20)} ${sanitize(p.apiUrl)}`;
+		const versionSuffix =
+			p.version !== undefined && p.version > CURRENT_SCHEMA_VERSION ? ` (v${p.version} — upgrade required)` : "";
+		return `  ${marker} ${sanitize(p.name).padEnd(20)} ${sanitize(p.apiUrl)}${versionSuffix}`;
 	});
 	ctx.showStatus(lines.join("\n"));
 }
 
 async function handleActivate(ctx: CommandContext, service: ProfileService, name: string): Promise<void> {
 	if (!name) {
-		ctx.showError("Usage: /profile activate <name>");
+		ctx.showError("Usage: /profile activate <name>. Run `/profile list` to see available profiles.");
 		return;
 	}
 	try {
@@ -110,13 +118,15 @@ function isSensitiveKey(key: string): boolean {
 async function handleShow(ctx: CommandContext, service: ProfileService, name?: string): Promise<void> {
 	const targetName = name || service.getStatus().activeProfileName;
 	if (!targetName) {
-		ctx.showError("No active profile. Use /profile activate <name> first.");
+		ctx.showError(
+			"No active profile. Run `/profile create <name>` to create one, or `/profile activate <name>` if profiles exist.",
+		);
 		return;
 	}
 	const profiles = await service.listProfiles();
 	const profile = profiles.find(p => p.name === targetName);
 	if (!profile) {
-		ctx.showError(`Profile '${targetName}' not found.`);
+		ctx.showError(`Profile '${targetName}' not found. Run \`/profile list\` to see available profiles.`);
 		return;
 	}
 
@@ -143,7 +153,7 @@ async function handleShow(ctx: CommandContext, service: ProfileService, name?: s
 	}
 
 	// Auth status indicator
-	rows.push({ key: "Status", value: formatAuthIndicator(auth.status, auth.latencyMs) });
+	rows.push({ key: "Status", value: formatAuthIndicator(auth.status, auth.latencyMs, auth.errorClass) });
 
 	// Track where environment section starts
 	const envDividerIndex = rows.length;
@@ -157,7 +167,28 @@ async function handleShow(ctx: CommandContext, service: ProfileService, name?: s
 		}
 	}
 
-	ctx.showStatus(renderF5XCTable(profile.name, rows, { dividerBefore: envDividerIndex }));
+	// Metadata section (only rendered when at least one field is present)
+	const metaRows: TableRow[] = [];
+	if (profile.metadata?.createdAt) {
+		metaRows.push({ key: "Created", value: formatRelativeTime(profile.metadata.createdAt) });
+	}
+	if (profile.metadata?.expiresAt) {
+		metaRows.push({ key: "Expires", value: formatExpiration(profile.metadata.expiresAt) });
+	}
+	if (profile.metadata?.lastRotatedAt) {
+		metaRows.push({ key: "Last Rotated", value: formatRelativeTime(profile.metadata.lastRotatedAt) });
+	}
+	if (profile.metadata?.rotateAfterDays) {
+		metaRows.push({ key: "Rotation", value: `every ${profile.metadata.rotateAfterDays} days` });
+	}
+
+	const dividers: Array<{ before: number; label: string }> = [{ before: envDividerIndex, label: "Environment" }];
+	if (metaRows.length > 0) {
+		dividers.push({ before: rows.length, label: "Metadata" });
+		rows.push(...metaRows);
+	}
+
+	ctx.showStatus(renderF5XCTable(profile.name, rows, { dividers }));
 }
 
 async function handleStatus(ctx: CommandContext, service: ProfileService): Promise<void> {
@@ -172,7 +203,7 @@ async function handleStatus(ctx: CommandContext, service: ProfileService): Promi
 		{ key: "Source", value: status.credentialSource },
 		{ key: "API URL", value: status.activeProfileUrl ?? "(not set)" },
 		{ key: "Namespace", value: status.activeProfileNamespace ?? "(not set)" },
-		{ key: "Status", value: formatAuthIndicator(auth.status, auth.latencyMs) },
+		{ key: "Status", value: formatAuthIndicator(auth.status, auth.latencyMs, auth.errorClass) },
 	];
 	ctx.showStatus(renderF5XCTable(status.activeProfileName ?? "status", rows));
 }
@@ -219,7 +250,7 @@ async function handleDelete(ctx: CommandContext, service: ProfileService, args:
 	}
 	const status = service.getStatus();
 	if (name === status.activeProfileName) {
-		ctx.showError("Cannot delete the active profile. Activate a different profile first.");
+		ctx.showError("Cannot delete the active profile. Run `/profile activate <other>` to switch first.");
 		return;
 	}
 	if (!confirmed) {

package/src/services/f5xc-profile.ts

@@ -12,6 +12,8 @@ import {
 	hasEnvOverride,
 } from "./f5xc-env";
 
+export const CURRENT_SCHEMA_VERSION = 1;
+
 export interface F5XCProfile {
 	name: string;
 	apiUrl: string;
@@ -20,6 +22,7 @@ export interface F5XCProfile {
 	env?: Record<string, string>;
 	/** Env var names from `env` whose values should be masked in output (e.g. ["F5XC_USERNAME"]). */
 	sensitiveKeys?: string[];
+	version?: number;
 	metadata?: {
 		createdAt?: string;
 		expiresAt?: string;
@@ -38,7 +41,6 @@ export interface ProfileStatus {
 	credentialSource: "profile" | "environment" | "mixed" | "none";
 	authStatus: AuthStatus;
 	isConfigured: boolean;
-	watcherActive: boolean;
 }
 
 export class ProfileError extends Error {
@@ -173,6 +175,17 @@ export class ProfileService {
 			return null;
 		}
 
+		// Gate: incompatible schema version — log warning and return null (don't crash startup)
+		try {
+			this.#assertCompatibleVersion(profile);
+		} catch (err) {
+			logger.warn("F5XC: profile uses incompatible schema version, skipping", {
+				name: profileName,
+				error: String(err),
+			});
+			return null;
+		}
+
 		// Only persist active_profile after the profile validates
 		if (autoActivated) {
 			this.#atomicWrite(this.activeProfilePath, profileName);
@@ -190,17 +203,18 @@ export class ProfileService {
 		// Reject activation when env overrides are present — would create mismatched credentials
 		if (process.env[F5XC_API_URL]) {
 			throw new ProfileError(
-				"Cannot activate a profile while F5XC_API_URL is set in the environment. " +
-					"Unset F5XC_API_URL first, or restart xcsh without it.",
+				"Cannot activate: F5XC_API_URL environment variable overrides profile. Run `unset F5XC_API_URL` first, or restart without it.",
 			);
 		}
 
 		this.#validateProfileName(name);
 		const profile = this.#readProfile(name);
 		if (!profile) {
-			throw new ProfileError(`Profile '${name}' not found.`, name);
+			throw new ProfileError(`Profile '${name}' not found. Run \`/profile list\` to see available profiles.`, name);
 		}
 
+		this.#assertCompatibleVersion(profile);
+
 		// NFR-402: write active_profile first — if it fails, don't update settings
 		this.#atomicWrite(this.activeProfilePath, name);
 
@@ -223,7 +237,7 @@ export class ProfileService {
 		return profiles;
 	}
 
-	async createProfile(profile: Omit<F5XCProfile, "metadata">): Promise<void> {
+	async createProfile(profile: Omit<F5XCProfile, "metadata" | "version">): Promise<void> {
 		this.#validateProfileName(profile.name);
 		const profilePath = path.join(this.profilesDir, `${profile.name}.json`);
 		if (fs.existsSync(profilePath)) {
@@ -233,6 +247,7 @@ export class ProfileService {
 		fs.mkdirSync(this.#configDir, { recursive: true, mode: 0o700 });
 		const data: F5XCProfile = {
 			...profile,
+			version: CURRENT_SCHEMA_VERSION,
 			metadata: { createdAt: new Date().toISOString() },
 		};
 		const tmpPath = `${profilePath}.tmp`;
@@ -256,6 +271,8 @@ export class ProfileService {
 		const profile = this.#readProfile(name);
 		if (!profile) throw new ProfileError(`Profile '${name}' not found.`, name);
 
+		this.#assertCompatibleVersion(profile);
+
 		const env = { ...(profile.env ?? {}), ...vars };
 		const sensitiveSet = new Set(profile.sensitiveKeys ?? []);
 		const newSensitive: string[] = [];
@@ -289,6 +306,8 @@ export class ProfileService {
 		const profile = this.#readProfile(name);
 		if (!profile) throw new ProfileError(`Profile '${name}' not found.`, name);
 
+		this.#assertCompatibleVersion(profile);
+
 		const env = { ...(profile.env ?? {}) };
 		const removed: string[] = [];
 		for (const key of keys) {
@@ -322,7 +341,7 @@ export class ProfileService {
 		timeoutMs?: number;
 		apiUrl?: string;
 		apiToken?: string;
-	}): Promise<{ status: AuthStatus; latencyMs?: number }> {
+	}): Promise<{ status: AuthStatus; latencyMs?: number; errorClass?: "network" | "credential" }> {
 		// Use explicit credentials if provided (for non-active profiles or env-backed sessions),
 		// otherwise fall back to effective credentials (env override > active profile)
 		const effectiveUrl = options?.apiUrl ?? process.env[F5XC_API_URL] ?? this.#activeProfile?.apiUrl;
@@ -344,19 +363,20 @@ export class ProfileService {
 			}
 			if (response.status === 401 || response.status === 403) {
 				this.#authStatus = "auth_error";
-				return { status: "auth_error", latencyMs };
+				return { status: "auth_error", latencyMs, errorClass: "credential" };
 			}
-			this.#authStatus = "connected";
-			return { status: "connected", latencyMs };
+			// 5xx, 429, etc. — server reachable but unhealthy; treat as offline so startup retry fires
+			this.#authStatus = "offline";
+			return { status: "offline", latencyMs, errorClass: "network" };
 		} catch {
 			this.#authStatus = "offline";
-			return { status: "offline" };
+			return { status: "offline", errorClass: "network" };
 		}
 	}
 
 	setNamespace(namespace: string): void {
 		if (!this.#activeProfile) {
-			throw new ProfileError("No active profile. Activate a profile first.");
+			throw new ProfileError("No active profile. Run `/profile activate <name>` to select one.");
 		}
 		this.#activeProfile = { ...this.#activeProfile, defaultNamespace: namespace };
 		// Re-apply settings with the new namespace
@@ -375,7 +395,6 @@ export class ProfileService {
 			credentialSource: this.#credentialSource,
 			authStatus: this.#authStatus,
 			isConfigured: this.#credentialSource !== "none",
-			watcherActive: false,
 		};
 	}
 
@@ -401,6 +420,15 @@ export class ProfileService {
 		}
 	}
 
+	#assertCompatibleVersion(profile: F5XCProfile): void {
+		if (profile.version !== undefined && profile.version > CURRENT_SCHEMA_VERSION) {
+			throw new ProfileError(
+				`Profile '${profile.name}' uses schema version ${profile.version}, but this version of xcsh only supports version ${CURRENT_SCHEMA_VERSION}. Upgrade xcsh to use this profile, or run \`/profile create\` to create a new one.`,
+				profile.name,
+			);
+		}
+	}
+
 	#readActiveProfileName(): string | null {
 		try {
 			if (!fs.existsSync(this.activeProfilePath)) return null;
@@ -468,6 +496,7 @@ export class ProfileService {
 				defaultNamespace: parsed.defaultNamespace ?? "default",
 				env,
 				sensitiveKeys,
+				version: typeof parsed.version === "number" ? parsed.version : undefined,
 				metadata: parsed.metadata,
 			};
 		} catch (err) {

package/src/services/f5xc-table.ts

@@ -20,27 +20,64 @@ const BOX = {
 
 const r = (s: string) => `${F5_RED}${s}${RESET}`;
 
-export function formatAuthIndicator(status: AuthStatus, latencyMs?: number): string {
+export function formatAuthIndicator(
+	status: AuthStatus,
+	latencyMs?: number,
+	errorClass?: "network" | "credential",
+): string {
 	const ms = latencyMs !== undefined ? ` (${latencyMs}ms)` : "";
 	switch (status) {
 		case "connected":
 			return `${formatStatusIcon("connected")} Connected${ms}`;
 		case "auth_error":
-			return `${formatStatusIcon("error")} Auth Error${ms}`;
+			return `${formatStatusIcon("error")} Auth Error — check token${ms}`;
 		case "offline":
-			return `${formatStatusIcon("warning")} Offline`;
+			return `${formatStatusIcon("warning")} Offline — ${errorClass === "credential" ? "auth issue" : "network issue"}${ms}`;
 		default:
 			return `${formatStatusIcon("unknown")} Unknown`;
 	}
 }
 
+export function formatRelativeTime(isoDate: string, now?: Date): string {
+	const nowMs = (now ?? new Date()).getTime();
+	const thenMs = new Date(isoDate).getTime();
+	const diffMs = nowMs - thenMs;
+	const absDiffMs = Math.abs(diffMs);
+	const minutes = Math.floor(absDiffMs / 60_000);
+	const hours = Math.floor(minutes / 60);
+	const days = Math.floor(hours / 24);
+	const months = Math.floor(days / 30);
+
+	if (months > 0) return `${months} month${months > 1 ? "s" : ""} ago`;
+	if (days > 0) return `${days} day${days > 1 ? "s" : ""} ago`;
+	if (hours > 0) return `${hours} hour${hours > 1 ? "s" : ""} ago`;
+	if (minutes > 0) return `${minutes} minute${minutes > 1 ? "s" : ""} ago`;
+	return "just now";
+}
+
+export function formatExpiration(isoDate: string, now?: Date): string {
+	const nowMs = (now ?? new Date()).getTime();
+	const expiresMs = new Date(isoDate).getTime();
+	const dateStr = isoDate.split("T")[0];
+	const diffDays = Math.ceil((expiresMs - nowMs) / 86_400_000);
+
+	if (diffDays < 0) {
+		const ago = Math.abs(diffDays);
+		return `${dateStr}  ${formatStatusIcon("warning")} expired ${ago} day${ago > 1 ? "s" : ""} ago`;
+	}
+	if (diffDays <= 7) {
+		return `${dateStr}  ${formatStatusIcon("warning")} expires in ${diffDays} day${diffDays !== 1 ? "s" : ""}`;
+	}
+	return dateStr;
+}
+
 export interface TableRow {
 	key: string;
 	value: string;
 }
 
 export interface TableOptions {
-	dividerBefore?: number; // insert ├──┤ divider before this row index
+	dividers?: Array<{ before: number; label: string }>;
 }
 
 // Measures the visible terminal column width of a string.
@@ -64,9 +101,10 @@ export function renderF5XCTable(title: string, rows: TableRow[], options?: Table
 
 	// Rows
 	for (let i = 0; i < rows.length; i++) {
-		// Optional divider
-		if (options?.dividerBefore === i) {
-			const divLabel = " Environment ";
+		// Optional labeled dividers
+		const divider = options?.dividers?.find(d => d.before === i);
+		if (divider) {
+			const divLabel = ` ${divider.label} `;
 			const divPad = innerWidth - visibleWidth(divLabel) - 1;
 			lines.push(`${r(BOX.lt + BOX.h)}${BOLD}${divLabel}${RESET}${r(BOX.h.repeat(Math.max(0, divPad)) + BOX.rt)}`);
 		}