@f5-sales-demo/xcsh 21.32.0 → 21.33.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "21.32.0",
+	"version": "21.33.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -63,13 +63,13 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.4.0",
-		"@f5-sales-demo/pi-agent-core": "21.32.0",
-		"@f5-sales-demo/pi-ai": "21.32.0",
-		"@f5-sales-demo/pi-natives": "21.32.0",
-		"@f5-sales-demo/pi-resource-management": "21.32.0",
-		"@f5-sales-demo/pi-tui": "21.32.0",
-		"@f5-sales-demo/pi-utils": "21.32.0",
-		"@f5-sales-demo/xcsh-stats": "21.32.0",
+		"@f5-sales-demo/pi-agent-core": "21.33.0",
+		"@f5-sales-demo/pi-ai": "21.33.0",
+		"@f5-sales-demo/pi-natives": "21.33.0",
+		"@f5-sales-demo/pi-resource-management": "21.33.0",
+		"@f5-sales-demo/pi-tui": "21.33.0",
+		"@f5-sales-demo/pi-utils": "21.33.0",
+		"@f5-sales-demo/xcsh-stats": "21.33.0",
 		"@mozilla/readability": "^0.6",
 		"@sinclair/typebox": "0.34.52",
 		"@xterm/headless": "^6.0",

package/src/cli/plugin-cli.ts

@@ -4,9 +4,11 @@
  * Handles `xcsh plugin <command>` subcommands for plugin lifecycle management.
  */
 
+import { createInterface } from "node:readline/promises";
 import { APP_NAME, getProjectDir } from "@f5-sales-demo/pi-utils";
 import chalk from "chalk";
 import { resolveOrDefaultProjectRegistryPath } from "../discovery/helpers";
+import { discoverAndLoadExtensions } from "../extensibility/extensions";
 import { PluginManager, parseSettingValue, validateSetting } from "../extensibility/plugins";
 import {
 	formatMarketplaceRefreshWarning,
@@ -16,7 +18,10 @@ import {
 	getPluginsCacheDir,
 	MarketplaceManager,
 } from "../extensibility/plugins/marketplace/index.js";
+import { describeSetupPlan, executeReviewedSetup } from "../integrations/setup";
+import type { IntegrationHandle } from "../integrations/types";
 import { theme } from "../modes/theme/theme";
+import { personProfileService } from "../person-profile/service";
 
 // =============================================================================
 // Types
@@ -34,7 +39,9 @@ export type PluginAction =
 	| "disable"
 	| "marketplace"
 	| "discover"
-	| "upgrade";
+	| "upgrade"
+	| "status"
+	| "setup";
 
 export interface PluginCommandArgs {
 	action: PluginAction;
@@ -69,6 +76,8 @@ const VALID_ACTIONS: PluginAction[] = [
 	"marketplace",
 	"discover",
 	"upgrade",
+	"status",
+	"setup",
 ];
 
 /**
@@ -187,6 +196,149 @@ export async function runPluginCommand(cmd: PluginCommandArgs): Promise<void> {
 		case "upgrade":
 			await handleUpgrade(cmd.args, cmd.flags);
 			break;
+		case "status":
+			await handleIntegrationStatus(cmd.args, cmd.flags);
+			break;
+		case "setup":
+			await handleIntegrationSetup(cmd.args, cmd.flags);
+			break;
+	}
+}
+
+async function loadIntegrationHandles(): Promise<IntegrationHandle<unknown>[]> {
+	const loaded = await discoverAndLoadExtensions([], process.cwd());
+	if (loaded.errors.length) throw new Error(`Unable to load ${loaded.errors.length} plugin extension(s)`);
+	return loaded.extensions.flatMap(extension => [...extension.integrations.values()]);
+}
+
+function matchesIntegration(handle: IntegrationHandle<unknown>, target: string): boolean {
+	return handle.id === target || handle.plugin === target || handle.plugin?.split("@")[0] === target;
+}
+
+export function selectSetupIntegration(
+	handles: readonly IntegrationHandle<unknown>[],
+	target: string,
+): IntegrationHandle<unknown> {
+	const matches = handles.filter(handle => matchesIntegration(handle, target));
+	if (!matches.length) throw new Error(`No enabled integration is registered for ${target}`);
+	const setupMatches = matches.filter(handle => handle.setupPlan !== undefined);
+	if (!setupMatches.length) throw new Error(`No setup plan is registered for ${target}`);
+	if (setupMatches.length > 1)
+		throw new Error(`Plugin ${target} registers multiple setup plans; use an integration id`);
+	return setupMatches[0];
+}
+
+async function handleIntegrationStatus(args: string[], flags: { json?: boolean }): Promise<void> {
+	if (args.length > 1) throw new Error(`Usage: ${APP_NAME} plugin status [plugin] [--json]`);
+	const handles = await loadIntegrationHandles();
+	const selected = args[0] ? handles.filter(handle => matchesIntegration(handle, args[0])) : handles;
+	if (args[0] && !selected.length) throw new Error(`No enabled integration is registered for ${args[0]}`);
+	const statuses = await Promise.all(
+		selected.map(async handle => {
+			const { value: _, ...status } = await handle.get();
+			return {
+				...status,
+				nextAction:
+					status.state === "setup_required" ? `${APP_NAME} plugin setup ${handle.plugin ?? handle.id}` : undefined,
+			};
+		}),
+	);
+	if (flags.json) {
+		process.stdout.write(`${JSON.stringify({ integrations: statuses })}\n`);
+		return;
+	}
+	if (!statuses.length) {
+		process.stdout.write("No enabled plugin integrations are registered.\n");
+		return;
+	}
+	for (const status of statuses) {
+		process.stdout.write(
+			`${status.plugin ?? status.id}: ${status.state}${status.reason ? ` (${status.reason})` : ""}\n`,
+		);
+		if (status.nextAction) process.stdout.write(`  next: ${status.nextAction}\n`);
+	}
+}
+
+export async function reviewAndExecuteIntegrationSetup(handle: IntegrationHandle<unknown>) {
+	const plan = handle.setupPlan;
+	if (!plan) throw new Error(`Integration ${handle.id} does not declare setup`);
+	const current = await handle.get();
+	if (current.state === "ready") return current;
+	process.stdout.write(`${describeSetupPlan(handle)}\n`);
+	const prompt = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		const answer = await prompt.question('Type "setup" to run this exact plan: ');
+		if (answer !== "setup") throw new Error("Plugin setup cancelled; the installed plugin remains setup_required");
+	} finally {
+		prompt.close();
+	}
+	const result = await executeReviewedSetup(handle, plan);
+	await personProfileService.reconcileFromCollectors(undefined, 0);
+	return result;
+}
+
+async function handleIntegrationSetup(args: string[], flags: { json?: boolean }): Promise<void> {
+	if (flags.json) throw new Error("plugin setup is human-only and does not accept --json");
+	if (args.length !== 1) throw new Error(`Usage: ${APP_NAME} plugin setup <plugin>`);
+	if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("Plugin setup requires an interactive terminal");
+	const handle = selectSetupIntegration(await loadIntegrationHandles(), args[0]);
+	const current = await handle.get();
+	if (current.state === "ready") {
+		process.stdout.write(`${handle.plugin ?? handle.id}: ready (setup is not required)\n`);
+		return;
+	}
+	const result = await reviewAndExecuteIntegrationSetup(handle);
+	process.stdout.write(
+		`${handle.plugin ?? handle.id}: ${result.state}${result.reason ? ` (${result.reason})` : ""}\n`,
+	);
+}
+
+async function reportMarketplaceInstallation(
+	plugin: string,
+	marketplace: string,
+	entry: { version: string; scope: string; setupRequired: boolean },
+	flags: { json?: boolean },
+): Promise<void> {
+	let handles: IntegrationHandle<unknown>[] = [];
+	try {
+		handles = (await loadIntegrationHandles()).filter(handle => matchesIntegration(handle, plugin));
+	} catch {
+		// Installation remains successful even when extension loading cannot establish readiness.
+	}
+	const statuses = await Promise.all(
+		handles.map(async handle => {
+			const { value: _, ...status } = await handle.get();
+			return status;
+		}),
+	);
+	const setupHandles = handles.filter(handle => handle.setupPlan !== undefined);
+	const setupHandle = setupHandles.length === 1 ? setupHandles[0] : undefined;
+	const setupStatus = setupHandle ? statuses.find(status => status.id === setupHandle.id) : undefined;
+	const nextAction =
+		entry.setupRequired && setupStatus?.state !== "ready" ? `${APP_NAME} plugin setup ${plugin}` : undefined;
+	if (flags.json || !process.stdin.isTTY || !process.stdout.isTTY) {
+		const result = {
+			installation: { state: "installed", plugin, marketplace, version: entry.version, scope: entry.scope },
+			readiness: { integrations: statuses },
+			...(nextAction ? { nextAction } : {}),
+		};
+		if (flags.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+		else {
+			process.stdout.write(`${theme.status.success} Installed ${plugin} from ${marketplace} (${entry.version})\n`);
+			for (const status of statuses)
+				process.stdout.write(`  ${status.id}: ${status.state}${status.reason ? ` (${status.reason})` : ""}\n`);
+			if (nextAction) process.stdout.write(`  next: ${nextAction}\n`);
+		}
+		return;
+	}
+	process.stdout.write(`${theme.status.success} Installed ${plugin} from ${marketplace} (${entry.version})\n`);
+	if (!setupHandle || setupStatus?.state === "ready") return;
+	try {
+		const result = await reviewAndExecuteIntegrationSetup(setupHandle);
+		process.stdout.write(`${plugin}: ${result.state}${result.reason ? ` (${result.reason})` : ""}\n`);
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		process.stderr.write(`Next: ${APP_NAME} plugin setup ${plugin}\n`);
 	}
 }
 
@@ -461,6 +613,9 @@ async function handleInstall(
 		}
 
 		if (target.type === "marketplace") {
+			const catalogEntry = listings.find(
+				item => item.marketplace === target.marketplace && item.plugin.name === target.name,
+			)?.plugin;
 			if (flags.dryRun) {
 				const preview = {
 					action: "install",
@@ -477,10 +632,11 @@ async function handleInstall(
 					force: flags.force,
 					scope: flags.scope,
 				});
-				console.log(
-					chalk.green(
-						`${theme.status.success} Installed ${target.name} from ${target.marketplace} (${entry.version})`,
-					),
+				await reportMarketplaceInstallation(
+					target.name,
+					target.marketplace,
+					{ ...entry, setupRequired: catalogEntry?.lifecycle.setupRequired ?? false },
+					flags,
 				);
 			} catch (err) {
 				console.error(chalk.red(`${theme.status.error} Failed to install ${spec}: ${err}`));

package/src/commands/plugin.ts

@@ -18,6 +18,8 @@ const ACTIONS: PluginAction[] = [
 	"marketplace",
 	"discover",
 	"upgrade",
+	"status",
+	"setup",
 ];
 
 export default class Plugin extends Command {

package/src/extensibility/extensions/loader.ts

@@ -15,6 +15,8 @@ import { loadCapability } from "../../discovery";
 import { getExtensionNameFromPath, getPreloadedPluginRoots } from "../../discovery/helpers";
 import type { ExecOptions } from "../../exec/exec";
 import { execCommand } from "../../exec/exec";
+import { integrationRegistry } from "../../integrations/registry";
+import type { IntegrationDefinition, IntegrationHandle } from "../../integrations/types";
 import { personProfileService } from "../../person-profile/service";
 import type { CustomMessage } from "../../session/messages";
 import { EventBus } from "../../utils/event-bus";
@@ -33,7 +35,6 @@ import type {
 	LoadExtensionsResult,
 	MessageRenderer,
 	RegisteredCommand,
-	ServiceStatusContribution,
 	ToolDefinition,
 } from "./types";
 
@@ -122,6 +123,7 @@ class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 		sourceId: string;
 	}> = [];
 	readonly personProfile: ExtensionAPI["personProfile"];
+	readonly integrations: ExtensionAPI["integrations"];
 
 	constructor(
 		public readonly pi: typeof import("@f5-sales-demo/xcsh"),
@@ -131,6 +133,8 @@ class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 		public readonly events: EventBus,
 	) {
 		const registrant = extension.resolvedPath;
+		integrationRegistry.unregisterOwner(registrant);
+		personProfileService.unregisterProfileCollectorsByRegistrant(registrant);
 		this.personProfile = Object.freeze({
 			get: () => personProfileService.get(),
 			registerCollector: collector => {
@@ -140,6 +144,46 @@ class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 			},
 			unregisterCollector: (id: string) => personProfileService.unregisterProfileCollector(id, registrant),
 		});
+		this.integrations = Object.freeze({
+			register: <T>(definition: IntegrationDefinition<T>): IntegrationHandle<T> => {
+				const handle = integrationRegistry.register(registrant, definition);
+				extension.integrations.set(definition.id, handle as IntegrationHandle<unknown>);
+				if (definition.profile) {
+					const profile = definition.profile;
+					personProfileService.registerProfileCollector(
+						{
+							id: definition.id,
+							name: definition.name,
+							dependsOn: definition.dependencies,
+							available: async () => true,
+							collect: async signal => {
+								const snapshot = await handle.get(signal);
+								if (snapshot.state !== "ready" || snapshot.value === undefined)
+									return {
+										facts: {},
+										observations: [],
+										sourceState: {
+											state: snapshot.state,
+											...(snapshot.reason ? { reason: snapshot.reason } : {}),
+											...(snapshot.retryAt ? { retryAt: new Date(snapshot.retryAt).toISOString() } : {}),
+										},
+									};
+								return { ...profile(snapshot.value), sourceState: { state: snapshot.state } };
+							},
+						},
+						registrant,
+					);
+				}
+				return handle;
+			},
+			unregister: (id: string): boolean => {
+				const removed = integrationRegistry.unregister(registrant, id);
+				if (!removed) return false;
+				extension.integrations.delete(id);
+				personProfileService.unregisterProfileCollector(id, registrant);
+				return true;
+			},
+		});
 	}
 
 	on<F extends HandlerFn>(event: string, handler: F): void {
@@ -194,10 +238,6 @@ class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 		this.extension.messageRenderers.set(customType, renderer as MessageRenderer);
 	}
 
-	registerServiceStatus(contribution: ServiceStatusContribution): void {
-		this.extension.serviceStatuses.set(contribution.name, contribution);
-	}
-
 	getFlag(name: string): boolean | string | undefined {
 		if (!this.extension.flags.has(name)) return undefined;
 		return this.runtime.flagValues.get(name);
@@ -279,7 +319,7 @@ function createExtension(extensionPath: string, resolvedPath: string): Extension
 		commands: new Map(),
 		flags: new Map(),
 		shortcuts: new Map(),
-		serviceStatuses: new Map(),
+		integrations: new Map(),
 	};
 }
 

package/src/extensibility/extensions/runner.ts

@@ -6,6 +6,7 @@ import type { ImageContent, Model } from "@f5-sales-demo/pi-ai";
 import type { KeyId } from "@f5-sales-demo/pi-tui";
 import { logger } from "@f5-sales-demo/pi-utils";
 import type { ModelRegistry } from "../../config/model-registry";
+import type { IntegrationHandle } from "../../integrations/types";
 import { type Theme, theme } from "../../modes/theme/theme";
 import type { SessionManager } from "../../session/session-manager";
 import type {
@@ -36,7 +37,6 @@ import type {
 	RegisteredTool,
 	ResourcesDiscoverEvent,
 	ResourcesDiscoverResult,
-	ServiceStatusContribution,
 	SessionBeforeBranchResult,
 	SessionBeforeCompactResult,
 	SessionBeforeSwitchResult,
@@ -263,15 +263,15 @@ export class ExtensionRunner {
 		return tools;
 	}
 
-	/** Get all registered service status contributions from all extensions. */
-	getAllRegisteredServiceStatuses(): ServiceStatusContribution[] {
-		const statuses: ServiceStatusContribution[] = [];
+	/** Get all integration handles registered by the loaded extensions. */
+	getAllRegisteredIntegrations(): IntegrationHandle<unknown>[] {
+		const integrations: IntegrationHandle<unknown>[] = [];
 		for (const ext of this.extensions) {
-			for (const contribution of ext.serviceStatuses.values()) {
-				statuses.push(contribution);
+			for (const handle of ext.integrations.values()) {
+				integrations.push(handle);
 			}
 		}
-		return statuses;
+		return integrations;
 	}
 
 	getFlags(): Map<string, ExtensionFlag> {

package/src/extensibility/extensions/types.ts

@@ -974,20 +974,6 @@ export interface RegisteredCommand {
 	handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
 }
 
-// ============================================================================
-// Service Status Contributions
-// ============================================================================
-
-export interface ServiceStatusContribution {
-	name: string;
-	group?: string;
-	check: () => Promise<{ state: "connected" | "unauthenticated" | "unavailable"; hint?: string }>;
-	fix?: {
-		prompt: string;
-		command: string[];
-	};
-}
-
 // ============================================================================
 // Extension API
 // ============================================================================
@@ -1020,6 +1006,14 @@ export interface ExtensionAPI {
 		unregisterCollector(id: string): boolean;
 	};
 
+	/** Process-wide provider readiness, setup and profile-discovery lifecycle. */
+	readonly integrations: {
+		register<T>(
+			definition: import("../../integrations/types").IntegrationDefinition<T>,
+		): import("../../integrations/types").IntegrationHandle<T>;
+		unregister(id: string): boolean;
+	};
+
 	// =========================================================================
 	// Event Subscription
 	// =========================================================================
@@ -1129,9 +1123,6 @@ export interface ExtensionAPI {
 	/** Register a custom renderer for CustomMessageEntry. */
 	registerMessageRenderer<T = unknown>(customType: string, renderer: MessageRenderer<T>): void;
 
-	/** Register a service status check for the welcome screen. */
-	registerServiceStatus(contribution: ServiceStatusContribution): void;
-
 	// =========================================================================
 	// Actions
 	// =========================================================================
@@ -1422,7 +1413,7 @@ export interface Extension {
 	commands: Map<string, RegisteredCommand>;
 	flags: Map<string, ExtensionFlag>;
 	shortcuts: Map<KeyId, ExtensionShortcut>;
-	serviceStatuses: Map<string, ServiceStatusContribution>;
+	integrations: Map<string, import("../../integrations/types").IntegrationHandle<unknown>>;
 }
 
 /** Result of loading extensions. */