@f5-sales-demo/xcsh 22.4.3 → 22.4.6

package/src/index.ts

@@ -30,6 +30,9 @@ export * from "./extensibility/extensions";
 export * from "./extensibility/skills";
 // Slash commands
 export { type FileSlashCommand, loadSlashCommands as discoverSlashCommands } from "./extensibility/slash-commands";
+export { type HostInfo, host } from "./host/host";
+export { type SoftwareRecipe, type SoftwareResolution, software } from "./host/software";
+export type { IntegrationDefinition, IntegrationHandle, IntegrationSetupPlan } from "./integrations/types";
 export type * from "./lsp";
 // Main entry point
 export * from "./main";

package/src/integrations/registry.ts

@@ -33,6 +33,8 @@ function freezeStrings(values: readonly string[]): readonly string[] {
 function freezePlan(plan: IntegrationSetupPlan | undefined): IntegrationSetupPlan | undefined {
 	if (!plan) return undefined;
 	const frozen: IntegrationSetupPlan = {
+		...(plan.notes ? { notes: freezeStrings(plan.notes) } : {}),
+		...(plan.validate ? { validate: plan.validate } : {}),
 		pluginDependencies: freezeStrings(plan.pluginDependencies),
 		requiredEnvironment: freezeStrings(plan.requiredEnvironment),
 		profileFields: freezeStrings(plan.profileFields),
@@ -41,6 +43,14 @@ function freezePlan(plan: IntegrationSetupPlan | undefined): IntegrationSetupPla
 				Object.freeze({
 					...step,
 					argv: freezeStrings(step.argv),
+					...(step.archive
+						? {
+								archive: Object.freeze({
+									...step.archive,
+									versionArgs: freezeStrings(step.archive.versionArgs),
+								}),
+							}
+						: {}),
 					...(step.environment ? { environment: freezeStrings(step.environment) } : {}),
 				}),
 			),
@@ -82,8 +92,13 @@ function validatePlan(plan: IntegrationSetupPlan | undefined): void {
 		plan.steps.some(
 			step =>
 				!step ||
-				!(["install", "login"] as const).includes(step.kind) ||
-				!validateArgv(step.argv) ||
+				!(["install", "login", "archive-install"] as const).includes(step.kind) ||
+				(step.kind === "archive-install"
+					? !step.archive ||
+						!/^\d+\.\d+\.\d+$/.test(step.archive.version) ||
+						!/^[a-f0-9]{64}$/.test(step.archive.sha256) ||
+						!validateArgv(step.archive.versionArgs)
+					: !validateArgv(step.argv)) ||
 				!Number.isInteger(step.timeoutMs) ||
 				step.timeoutMs < 1_000 ||
 				step.timeoutMs > MAX_SETUP_STEP_TIMEOUT_MS ||
@@ -134,7 +149,8 @@ export class IntegrationRegistry {
 		const existing = this.#entries.get(definition.id);
 		if (existing && existing.owner !== owner) throw new Error(`Integration ${definition.id} is already registered`);
 
-		const setupPlan = freezePlan(definition.setup);
+		let setupPlan = freezePlan(definition.setup);
+		let preparationRevision = 0;
 		const frozenDefinition = Object.freeze({
 			...definition,
 			dependencies: definition.dependencies ? freezeStrings(definition.dependencies) : undefined,
@@ -145,12 +161,28 @@ export class IntegrationRegistry {
 			id: definition.id,
 			name: definition.name,
 			plugin: definition.plugin,
-			setupPlan,
+			get setupPlan() {
+				return setupPlan;
+			},
+			prepareSetup: async (signal?: AbortSignal) => {
+				const revision = ++preparationRevision;
+				if (!definition.prepareSetup) {
+					if (!setupPlan) throw new Error("No setup is declared");
+					return setupPlan;
+				}
+				const prepared = await definition.prepareSetup(signal);
+				signal?.throwIfAborted();
+				validatePlan(prepared);
+				if (revision !== preparationRevision || this.#entries.get(definition.id)?.handle !== handle)
+					throw new Error("Setup preparation changed; review again");
+				setupPlan = freezePlan(prepared)!;
+				return setupPlan;
+			},
 			get: (signal?: AbortSignal) => this.#get(definition.id, false, signal) as Promise<IntegrationSnapshot<T>>,
 			invalidate: () => this.invalidate(definition.id),
 			verifyAfterSetup: (reviewedPlan: IntegrationSetupPlan, signal?: AbortSignal) => {
 				const current = this.#entries.get(definition.id);
-				if (!current?.definition.setup || reviewedPlan !== current.definition.setup)
+				if (current?.handle !== handle || reviewedPlan !== setupPlan)
 					throw new Error("Setup requires the current reviewed setup plan");
 				return this.#get(definition.id, true, signal) as Promise<IntegrationSnapshot<T>>;
 			},

package/src/integrations/setup.ts

@@ -1,3 +1,5 @@
+import { installArchive } from "../host/archive";
+import { host } from "../host/host";
 import type { IntegrationHandle, IntegrationSetupPlan, IntegrationSetupStep, IntegrationSnapshot } from "./types";
 
 export type PluginSetupTrigger = "direct-install" | "bulk-install" | "upgrade" | "cache-refresh" | "dependency-install";
@@ -9,6 +11,7 @@ export interface InstallAuthorizedSetupOptions {
 	readonly handles: readonly IntegrationHandle<unknown>[];
 	readonly run?: SetupStepRunner;
 	readonly signal?: AbortSignal;
+	readonly review?: (handle: IntegrationHandle<unknown>, plan: IntegrationSetupPlan) => Promise<void>;
 }
 
 export type SetupStepRunner = (step: IntegrationSetupStep, signal?: AbortSignal) => Promise<number>;
@@ -64,12 +67,15 @@ export function describeSetupPlan(handle: IntegrationHandle<unknown>): string {
 		`Required environment names: ${plan.requiredEnvironment.join(", ") || "none"}`,
 		`Person-profile categories: ${plan.profileFields.join(", ") || "none"}`,
 	];
+	lines.push(...(plan.notes ?? []));
 	if (plan.guidedAction?.kind === "context_wizard") {
 		lines.push("Guided action: native xcsh context wizard");
 	} else {
 		lines.push(
 			"Commands:",
-			...plan.steps.map(step => `  ${step.kind}: ${JSON.stringify(step.argv)} (timeout ${step.timeoutMs}ms)`),
+			...plan.steps.map(
+				step => `  ${step.kind}: ${JSON.stringify(step.archive ?? step.argv)} (timeout ${step.timeoutMs}ms)`,
+			),
 			"Verification:",
 			...plan.verification.map(step => `  ${JSON.stringify(step.argv)} (timeout ${step.timeoutMs}ms)`),
 		);
@@ -82,6 +88,11 @@ export function createSetupStepRunner(
 	options: SetupStepRunnerOptions = {},
 ): SetupStepRunner {
 	return async (step, signal) => {
+		if (step.kind === "archive-install") {
+			if (!step.archive) throw new Error("Missing archive installation specification");
+			await installArchive(step.archive, signal, step.timeoutMs);
+			return 0;
+		}
 		const environment = { ...process.env };
 		for (const name of step.environment ?? []) {
 			const value = resolveEnvironment(name);
@@ -93,7 +104,7 @@ export function createSetupStepRunner(
 		const interactiveInput = step.stdin === "inherit" || step.kind === "login";
 		const output = step.kind === "login" ? "inherit" : (options.nonInteractiveOutput ?? "inherit");
 		try {
-			const child = Bun.spawn([...step.argv], {
+			const child = Bun.spawn([host.findExecutable(step.argv[0]) ?? step.argv[0], ...step.argv.slice(1)], {
 				env: environment,
 				stdin: interactiveInput ? "inherit" : "ignore",
 				stdout: output,
@@ -117,6 +128,9 @@ export async function executeReviewedSetup<T>(
 ): Promise<IntegrationSnapshot<T>> {
 	if (reviewedPlan !== handle.setupPlan) throw new Error("Setup requires the current reviewed setup plan");
 	if (reviewedPlan.guidedAction) throw new Error("Guided setup must run through its native interactive action");
+	if (signal?.aborted) throw new Error("Integration setup cancelled");
+	await reviewedPlan.validate?.(signal);
+	if (reviewedPlan !== handle.setupPlan) throw new Error("Setup requires the current reviewed setup plan");
 	for (const step of reviewedPlan.steps) {
 		if (signal?.aborted) throw new Error("Integration setup cancelled");
 		if ((await run(step, signal)) !== 0) throw new Error(`Integration ${step.kind} step failed`);
@@ -154,5 +168,7 @@ export async function executeInstallAuthorizedSetup(
 	const handle = matches[0];
 	const current = await handle.get(options.signal);
 	if (current.state !== "setup_required" && current.state !== "degraded") return current;
-	return executeReviewedSetup(handle, handle.setupPlan!, options.run, options.signal);
+	const plan = handle.prepareSetup ? await handle.prepareSetup(options.signal) : handle.setupPlan!;
+	await options.review?.(handle, plan);
+	return executeReviewedSetup(handle, plan, options.run, options.signal);
 }

package/src/integrations/types.ts

@@ -20,8 +20,20 @@ export interface IntegrationProbeResult<T> {
 	readonly retryAfterMs?: number;
 }
 
+export interface ArchiveInstall {
+	readonly version: string;
+	readonly url: string;
+	readonly sha256: string;
+	readonly destination: string;
+	readonly link: string;
+	readonly baseDir: string;
+	readonly executable: string;
+	readonly versionArgs: readonly string[];
+}
+
 export interface IntegrationSetupStep {
-	readonly kind: "install" | "login";
+	readonly archive?: ArchiveInstall;
+	readonly kind: "install" | "login" | "archive-install";
 	readonly argv: readonly string[];
 	readonly timeoutMs: number;
 	/** Environment variable names inherited by this step. Values are never part of the plan. */
@@ -45,6 +57,8 @@ export interface IntegrationSetupPlan {
 	readonly steps: readonly IntegrationSetupStep[];
 	readonly verification: readonly IntegrationVerificationStep[];
 	readonly guidedAction?: IntegrationGuidedSetupAction;
+	readonly notes?: readonly string[];
+	readonly validate?: (signal?: AbortSignal) => Promise<void>;
 }
 
 export interface IntegrationDefinition<T> {
@@ -55,6 +69,7 @@ export interface IntegrationDefinition<T> {
 	readonly dependencies?: readonly string[];
 	readonly successTtlMs?: number;
 	readonly setup?: IntegrationSetupPlan;
+	readonly prepareSetup?: (signal?: AbortSignal) => Promise<IntegrationSetupPlan>;
 	readonly probe: (signal?: AbortSignal) => Promise<IntegrationProbeResult<T>>;
 	/** Optional private profile projection. The registry never persists `value` itself. */
 	readonly profile?: (value: T) => ProfileCollection;
@@ -77,6 +92,7 @@ export interface IntegrationHandle<T> {
 	readonly name: string;
 	readonly plugin?: string;
 	readonly setupPlan?: IntegrationSetupPlan;
+	prepareSetup?(signal?: AbortSignal): Promise<IntegrationSetupPlan>;
 	get(signal?: AbortSignal): Promise<IntegrationSnapshot<T>>;
 	invalidate(): void;
 	verifyAfterSetup(reviewedPlan: IntegrationSetupPlan, signal?: AbortSignal): Promise<IntegrationSnapshot<T>>;