@f5xc-salesdemos/xcsh 19.5.1 → 19.6.0

package/package.json

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

package/src/discovery/claude-plugins.ts

@@ -19,6 +19,7 @@ import {
 	listXcshPluginRoots,
 	loadFilesFromDir,
 	scanSkillsFromDir,
+	scopeToLevel,
 	type XcshPluginRoot,
 } from "./helpers";
 
@@ -45,7 +46,7 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 			const result = await scanSkillsFromDir(ctx, {
 				dir: skillsDir,
 				providerId: PROVIDER_ID,
-				level: root.scope,
+				level: scopeToLevel(root.scope),
 			});
 			return { root, result };
 		}),
@@ -76,7 +77,7 @@ async function loadSlashCommands(ctx: LoadContext): Promise<LoadResult<SlashComm
 	const results = await Promise.all(
 		roots.map(async root => {
 			const commandsDir = path.join(root.path, "commands");
-			return loadFilesFromDir<SlashCommand>(ctx, commandsDir, PROVIDER_ID, root.scope, {
+			return loadFilesFromDir<SlashCommand>(ctx, commandsDir, PROVIDER_ID, scopeToLevel(root.scope), {
 				extensions: ["md"],
 				transform: (name, content, filePath, source) => {
 					const cmdName = name.replace(/\.md$/, "");
@@ -84,7 +85,7 @@ async function loadSlashCommands(ctx: LoadContext): Promise<LoadResult<SlashComm
 						name: root.plugin ? `${root.plugin}:${cmdName}` : cmdName,
 						path: filePath,
 						content,
-						level: root.scope,
+						level: scopeToLevel(root.scope),
 						_source: source,
 					};
 				},
@@ -123,7 +124,7 @@ async function loadHooks(ctx: LoadContext): Promise<LoadResult<Hook>> {
 	const results = await Promise.all(
 		loadTasks.map(async ({ root, hookType }) => {
 			const hooksDir = path.join(root.path, "hooks", hookType);
-			return loadFilesFromDir<Hook>(ctx, hooksDir, PROVIDER_ID, root.scope, {
+			return loadFilesFromDir<Hook>(ctx, hooksDir, PROVIDER_ID, scopeToLevel(root.scope), {
 				transform: (name, _content, filePath, source) => {
 					const toolName = name.replace(/\.(sh|bash|zsh|fish)$/, "");
 					return {
@@ -131,7 +132,7 @@ async function loadHooks(ctx: LoadContext): Promise<LoadResult<Hook>> {
 						path: filePath,
 						type: hookType,
 						tool: toolName,
-						level: root.scope,
+						level: scopeToLevel(root.scope),
 						_source: source,
 					};
 				},
@@ -161,14 +162,14 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 	const results = await Promise.all(
 		roots.map(async root => {
 			const toolsDir = path.join(root.path, "tools");
-			return loadFilesFromDir<CustomTool>(ctx, toolsDir, PROVIDER_ID, root.scope, {
+			return loadFilesFromDir<CustomTool>(ctx, toolsDir, PROVIDER_ID, scopeToLevel(root.scope), {
 				transform: (name, _content, filePath, source) => {
 					const toolName = name.replace(/\.(ts|js|sh|bash|py)$/, "");
 					return {
 						name: toolName,
 						path: filePath,
 						description: `${toolName} custom tool`,
-						level: root.scope,
+						level: scopeToLevel(root.scope),
 						_source: source,
 					};
 				},
@@ -242,7 +243,7 @@ async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>>
 				...(raw.auth !== undefined && { auth: raw.auth }),
 				...(raw.oauth !== undefined && { oauth: raw.oauth }),
 				...(raw.type !== undefined && { transport: raw.type as MCPServer["transport"] }),
-				_source: createSourceMeta(PROVIDER_ID, mcpPath, root.scope),
+				_source: createSourceMeta(PROVIDER_ID, mcpPath, scopeToLevel(root.scope)),
 			};
 			items.push(server);
 		}

package/src/discovery/helpers.ts

@@ -365,6 +365,22 @@ function expandEnvVars(value: string, extraEnv?: Record<string, string>): string
 	});
 }
 
+/**
+ * Build plugin-specific environment variables for variable substitution.
+ * These are injected as extraEnv when loading plugin configs (hooks, MCP, LSP).
+ */
+export function buildPluginEnvVars(pluginRoot: string, pluginId: string, projectDir?: string): Record<string, string> {
+	const dataDir = path.join(os.homedir(), getConfigDirName(), "plugins", "data", pluginId.replace("@", "__"));
+	const vars: Record<string, string> = {
+		XCSH_PLUGIN_ROOT: pluginRoot,
+		XCSH_PLUGIN_DATA: dataDir,
+	};
+	if (projectDir) {
+		vars.XCSH_PROJECT_DIR = projectDir;
+	}
+	return vars;
+}
+
 /**
  * Recursively expand environment variables in an object.
  */
@@ -621,8 +637,13 @@ export interface XcshPluginRoot {
 	version: string;
 	/** Absolute path to plugin root */
 	path: string;
-	/** Whether this is a user or project scope plugin */
-	scope: "user" | "project";
+	/** Whether this is a user, project, or local scope plugin */
+	scope: "user" | "project" | "local";
+}
+
+/** Map plugin scope to the loading level — "local" behaves as "project" for capability loading. */
+export function scopeToLevel(scope: "user" | "project" | "local"): "user" | "project" {
+	return scope === "local" ? "project" : scope;
 }
 
 /**

package/src/extensibility/plugins/marketplace/fetcher.ts

@@ -277,8 +277,9 @@ async function cloneAndReadCatalog(url: string, cacheDir: string): Promise<Fetch
 	const tmpDir = path.join(cacheDir, `.tmp-clone-${Date.now()}`);
 	await fs.mkdir(cacheDir, { recursive: true });
 
-	logger.debug(`[marketplace] cloning ${url} → ${tmpDir}`);
-	await git.clone(url, tmpDir);
+	const timeoutMs = Number(Bun.env.XCSH_PLUGIN_GIT_TIMEOUT_MS) || 120_000;
+	logger.debug(`[marketplace] cloning ${url} → ${tmpDir} (timeout: ${timeoutMs}ms)`);
+	await git.clone(url, tmpDir, { signal: AbortSignal.timeout(timeoutMs) });
 
 	const catalogPath = path.join(tmpDir, CATALOG_RELATIVE_PATH);
 	let content: string;

package/src/extensibility/plugins/marketplace/manager.ts

@@ -49,6 +49,11 @@ export interface MarketplaceManagerOptions {
 	 * Resolved by resolveActiveProjectRegistryPath(cwd) in callers.
 	 */
 	projectInstalledRegistryPath?: string;
+	/**
+	 * Path to the local-scoped installed_plugins.json (gitignored, project-specific).
+	 * Same as project path but under a `.local` variant so it stays out of VCS.
+	 */
+	localInstalledRegistryPath?: string;
 	marketplacesCacheDir: string;
 	pluginsCacheDir: string;
 	/** Injected for testing; production callers pass clearXcshPluginRootsCache.
@@ -143,7 +148,17 @@ export class MarketplaceManager {
 			throw new Error(`Marketplace "${name}" not found`);
 		}
 
-		const { catalog, clonePath } = await fetchMarketplace(existing.sourceUri, this.#opts.marketplacesCacheDir);
+		let fetchResult: { catalog: MarketplaceCatalog; clonePath?: string };
+		try {
+			fetchResult = await fetchMarketplace(existing.sourceUri, this.#opts.marketplacesCacheDir);
+		} catch (err) {
+			if (Bun.env.XCSH_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE === "1") {
+				logger.debug("Marketplace fetch failed, preserving cached catalog", { name, error: String(err) });
+				return existing;
+			}
+			throw err;
+		}
+		const { catalog, clonePath } = fetchResult;
 
 		// Guard against upstream catalog silently renaming itself — the registry
 		// entry is keyed by name, so a drift would corrupt the entry on next read.
@@ -227,7 +242,7 @@ export class MarketplaceManager {
 	async installPlugin(
 		name: string,
 		marketplace: string,
-		options?: { force?: boolean; scope?: "user" | "project" },
+		options?: { force?: boolean; scope?: "user" | "project" | "local" },
 	): Promise<InstalledPluginEntry> {
 		const force = options?.force ?? false;
 		const scope = options?.scope ?? "user";
@@ -378,7 +393,7 @@ export class MarketplaceManager {
 		return "0.0.0";
 	}
 
-	async uninstallPlugin(pluginId: string, scope?: "user" | "project"): Promise<void> {
+	async uninstallPlugin(pluginId: string, scope?: "user" | "project" | "local"): Promise<void> {
 		const parsed = parsePluginId(pluginId);
 		if (!parsed) {
 			throw new Error(`Invalid plugin ID format: "${pluginId}". Expected "name@marketplace".`);
@@ -394,7 +409,7 @@ export class MarketplaceManager {
 		}
 
 		// Disambiguation: if installed in both scopes and no explicit scope, require one.
-		let targetScope: "user" | "project";
+		let targetScope: "user" | "project" | "local";
 		if (inUser && inProject) {
 			if (!scope) {
 				throw new Error(
@@ -478,7 +493,7 @@ export class MarketplaceManager {
 		return results;
 	}
 
-	async setPluginEnabled(pluginId: string, enabled: boolean, scope?: "user" | "project"): Promise<void> {
+	async setPluginEnabled(pluginId: string, enabled: boolean, scope?: "user" | "project" | "local"): Promise<void> {
 		const { userEntries, projectEntries, userReg, projectReg } = await this.#findInBothRegistries(pluginId);
 
 		const inUser = userEntries && userEntries.length > 0;
@@ -489,7 +504,7 @@ export class MarketplaceManager {
 		}
 
 		// Disambiguation: if installed in both scopes and no explicit scope, require one.
-		let targetScope: "user" | "project";
+		let targetScope: "user" | "project" | "local";
 		if (inUser && inProject) {
 			if (!scope) {
 				throw new Error(
@@ -548,16 +563,23 @@ export class MarketplaceManager {
 	// Compare installed plugin versions against their catalog entries.
 	// Returns one entry per (pluginId, scope) pair where the catalog declares a newer version.
 	// Catalog entries without a version field are skipped.
-	async checkForUpdates(): Promise<Array<{ pluginId: string; scope: "user" | "project"; from: string; to: string }>> {
+	async checkForUpdates(): Promise<
+		Array<{ pluginId: string; scope: "user" | "project" | "local"; from: string; to: string }>
+	> {
 		const mktReg = await readMarketplacesRegistry(this.#opts.marketplacesRegistryPath);
-		const updates: Array<{ pluginId: string; scope: "user" | "project"; from: string; to: string }> = [];
+		const updates: Array<{ pluginId: string; scope: "user" | "project" | "local"; from: string; to: string }> = [];
 
 		// Keyed by (path, scope) so each scope is checked independently.
 		// A plugin current in user scope but stale in project scope must still appear.
-		const registryEntries: Array<[string, "user" | "project"]> = [[this.#opts.installedRegistryPath, "user"]];
+		const registryEntries: Array<[string, "user" | "project" | "local"]> = [
+			[this.#opts.installedRegistryPath, "user"],
+		];
 		if (this.#opts.projectInstalledRegistryPath) {
 			registryEntries.push([this.#opts.projectInstalledRegistryPath, "project"]);
 		}
+		if (this.#opts.localInstalledRegistryPath) {
+			registryEntries.push([this.#opts.localInstalledRegistryPath, "local"]);
+		}
 
 		for (const [regPath, scope] of registryEntries) {
 			const instReg = await readInstalledPluginsRegistry(regPath);
@@ -598,7 +620,7 @@ export class MarketplaceManager {
 	}
 
 	// Re-install a specific plugin at the latest catalog version (force-overwrites).
-	async upgradePlugin(pluginId: string, scope?: "user" | "project"): Promise<InstalledPluginEntry> {
+	async upgradePlugin(pluginId: string, scope?: "user" | "project" | "local"): Promise<InstalledPluginEntry> {
 		const parsed = parsePluginId(pluginId);
 		if (!parsed) {
 			throw new Error(`Invalid plugin ID: "${pluginId}". Expected "name@marketplace".`);
@@ -613,7 +635,7 @@ export class MarketplaceManager {
 			throw new Error(`Plugin "${pluginId}" is not installed`);
 		}
 
-		let resolvedScope: "user" | "project";
+		let resolvedScope: "user" | "project" | "local";
 		if (inUser && inProject) {
 			if (!scope) {
 				throw new Error(
@@ -667,10 +689,10 @@ export class MarketplaceManager {
 	// Only stale scopes are touched; a current user install is not re-installed when only
 	// the project scope is stale. Per-entry failures are skipped — partial success is returned.
 	async upgradeAllPlugins(): Promise<
-		Array<{ pluginId: string; scope: "user" | "project"; from: string; to: string }>
+		Array<{ pluginId: string; scope: "user" | "project" | "local"; from: string; to: string }>
 	> {
 		const updates = await this.checkForUpdates();
-		const results: Array<{ pluginId: string; scope: "user" | "project"; from: string; to: string }> = [];
+		const results: Array<{ pluginId: string; scope: "user" | "project" | "local"; from: string; to: string }> = [];
 		for (const update of updates) {
 			try {
 				const entry = await this.upgradePlugin(update.pluginId, update.scope);
@@ -684,13 +706,19 @@ export class MarketplaceManager {
 
 	// ── Private helpers ───────────────────────────────────────────────────────
 
-	#registryPath(scope: "user" | "project"): string {
+	#registryPath(scope: "user" | "project" | "local"): string {
 		if (scope === "project") {
 			if (!this.#opts.projectInstalledRegistryPath) {
 				throw new Error("project-scoped install requires running inside a project directory");
 			}
 			return this.#opts.projectInstalledRegistryPath;
 		}
+		if (scope === "local") {
+			if (!this.#opts.localInstalledRegistryPath) {
+				throw new Error("local-scoped install requires running inside a project directory");
+			}
+			return this.#opts.localInstalledRegistryPath;
+		}
 		return this.#opts.installedRegistryPath;
 	}
 

package/src/extensibility/plugins/marketplace/types.ts

@@ -163,7 +163,7 @@ export interface InstalledPluginsRegistry {
 }
 
 export interface InstalledPluginEntry {
-	scope: "user" | "project";
+	scope: "user" | "project" | "local";
 	/** Absolute path to cached plugin directory. */
 	installPath: string;
 	version: string;
@@ -186,7 +186,7 @@ export interface InstalledPluginEntry {
  */
 export interface InstalledPluginSummary {
 	id: string;
-	scope: "user" | "project";
+	scope: "user" | "project" | "local";
 	entries: InstalledPluginEntry[];
 	/** Set when a user-scoped plugin is overridden by a project-scoped install. */
 	shadowedBy?: "project";

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.5.1",
-	"commit": "9c15a98f105051030aa1e0f5376d315d0214e8fd",
-	"shortCommit": "9c15a98",
+	"version": "19.6.0",
+	"commit": "8505c9827499b1e269615db372fec4132b61c506",
+	"shortCommit": "8505c98",
 	"branch": "main",
-	"tag": "v19.5.1",
-	"commitDate": "2026-06-04T17:32:07Z",
-	"buildDate": "2026-06-04T17:56:43.676Z",
+	"tag": "v19.6.0",
+	"commitDate": "2026-06-04T18:26:24Z",
+	"buildDate": "2026-06-04T18:51:12.169Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/9c15a98f105051030aa1e0f5376d315d0214e8fd",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v19.5.1"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/8505c9827499b1e269615db372fec4132b61c506",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v19.6.0"
 };

package/src/modes/components/plugin-selector.ts

@@ -17,7 +17,7 @@ export interface PluginItem {
 	plugin: { name: string; version?: string; description?: string };
 	marketplace: string;
 	/** Scope of this entry. When set, appended to the label and forwarded to onSelect. */
-	scope?: "user" | "project";
+	scope?: "user" | "project" | "local";
 }
 
 export class PluginSelectorComponent extends Container {

package/src/modes/components/plugins/types.ts

@@ -4,7 +4,7 @@ export interface DashboardPlugin {
 	displayName?: string;
 	marketplace?: string;
 	source: "npm" | "marketplace";
-	scope?: "user" | "project";
+	scope?: "user" | "project" | "local";
 	version?: string;
 	catalogVersion?: string;
 	description?: string;