@xopcai/xopc 0.0.23 → 0.0.24

package/dist/src/extensions/sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../../src/extensions/sdk/index.ts"],"sourcesContent":["/**\n * xopc Extension SDK\n * \n * Official SDK for developing xopc extensions.\n * Import types and utilities from this module:\n * \n * @example\n * import type { ExtensionApi, ExtensionDefinition } from 'xopc/extension-sdk';\n */\n\n// ============================================================================\n// Core extension types\n// ============================================================================\n\nexport type {\n  ExtensionDefinition,\n  ExtensionModule,\n  ExtensionKind,\n  ExtensionApi,\n  ExtensionLogger,\n  ExtensionManifest,\n  ExtensionRecord,\n  ExtensionRegistry,\n  ResolvedExtensionConfig,\n  ExtensionRuntime,\n  ExtensionCliRegistration,\n} from '../types/index.js';\n\n// ============================================================================\n// Tools (re-exported from @mariozechner/pi-agent-core)\n// ============================================================================\n\nexport type {\n  AgentTool,\n  AgentToolResult,\n  AgentToolUpdateCallback,\n  ToolExecutionStartEvent,\n  ToolExecutionUpdateEvent,\n  ToolExecutionEndEvent,\n} from '../types/index.js';\n\n// ============================================================================\n// Hooks ( Strongly Typed)\n// ============================================================================\n\nexport type {\n  ExtensionHookEvent,\n  ExtensionHookHandler,\n  HookOptions,\n  HookAgentContext,\n  AgentMessage,\n  ContextEvent,\n  ContextResult,\n  InputEvent,\n  InputResult,\n  TurnEvent,\n  TurnResult,\n  //  New hook types\n  HookHandlerMap,\n  HookExecutionMode,\n  // Note: HOOK_EXECUTION_MODES is exported as value below\n  //  LLM observation hooks\n  HookBeforeModelResolveEvent,\n  HookBeforeModelResolveResult,\n  HookBeforePromptBuildEvent,\n  HookBeforePromptBuildResult,\n  HookLlmInputEvent,\n  HookLlmOutputEvent,\n  //  Inbound claim\n  HookInboundClaimEvent,\n  HookInboundClaimResult,\n  //  Reset hook\n  HookBeforeResetEvent,\n  HookBeforeResetResult,\n  //  Message write hook\n  HookBeforeMessageWriteEvent,\n  HookBeforeMessageWriteResult,\n  //  Turn hooks\n  HookTurnStartEvent,\n  HookTurnEndEvent,\n  //  Tool execution hooks\n  HookToolExecutionStartEvent,\n  HookToolExecutionUpdateEvent,\n  HookToolExecutionEndEvent,\n  // Existing context types\n  HookContext,\n  BeforeAgentStartContext,\n  BeforeAgentStartResult,\n  AgentEndContext,\n  BeforeCompactionContext,\n  AfterCompactionContext,\n  MessageReceivedContext,\n  MessageSendingContext,\n  MessageSendingResult,\n  MessageSentContext,\n  BeforeToolCallContext,\n  BeforeToolCallResult,\n  AfterToolCallContext,\n  SessionStartContext,\n  SessionEndContext,\n  GatewayStartContext,\n  GatewayStopContext,\n} from '../types/index.js';\n\n// ============================================================================\n//  Typed Event Bus\n// ============================================================================\n\nexport type {\n  EventMap,\n  RequestMap,\n  EventHandler,\n  EventHandlerMeta,\n  RequestHandler,\n  RequestHandlerMeta,\n  WildcardEventHandler,\n  WildcardHandlerMeta,\n  TypedEventBusOptions,\n  RequestOptions,\n} from '../types/index.js';\n\n// ============================================================================\n//  Provider Types\n// ============================================================================\n\nexport type {\n  ProviderPlugin,\n  ProviderModelDefinition,\n  ProviderCapabilities,\n  ProviderStreamParams,\n  ProviderStreamChunk,\n  ProviderCompleteParams,\n  ProviderResponse,\n  ProviderRegistry,\n  BUILTIN_PROVIDERS,\n  BuiltinProviderId,\n} from '../types/index.js';\n\n// ============================================================================\n//  Advanced Features\n// ============================================================================\n\nexport type {\n  ProviderConfig,\n  ModelConfig,\n  OAuthConfig,\n  OAuthCallbacks,\n  OAuthCredentials,\n  FlagConfig,\n  FlagValue,\n  ShortcutConfig,\n  ShortcutHandler,\n} from '../types/index.js';\n\n// ============================================================================\n//  Security Types\n// ============================================================================\n\nexport type {\n  SafetyCheckResult,\n  SecurityConfig,\n  ExtensionSourceOrigin,\n  ProvenanceInfo,\n} from '../security.js';\n\n// ============================================================================\n//  Slot Types\n// ============================================================================\n\nexport type {\n  SlotKey,\n  SlotClaim,\n  SlotConfig,\n} from '../slots.js';\n\n// ============================================================================\n//  Diagnostics Types\n// ============================================================================\n\nexport type {\n  DiagnosticLevel,\n  ExtensionDiagnostic,\n  ExtensionLoaderCache,\n} from '../diagnostics.js';\n\n// ============================================================================\n// Channels (ChannelPlugin registry)\n// ============================================================================\n\nexport type {\n  ChannelPlugin,\n  ChannelPluginInitOptions,\n  ChannelPluginStartOptions,\n} from '../../channels/plugin-types.js';\n\n// ============================================================================\n// HTTP\n// ============================================================================\n\nexport type {\n  HttpRequestHandler,\n  HttpRequest,\n  HttpResponse,\n} from '../types/index.js';\n\n// ============================================================================\n// Commands\n// ============================================================================\n\nexport type {\n  ExtensionCommand,\n  ExtensionCommandHandler,\n  ExtensionCommandContext,\n  ExtensionCommandResult,\n  ExtensionReloadHandler,\n  ExtensionReloadResult,\n  ExtensionReloadRegistration,\n} from '../types/index.js';\n\n// ============================================================================\n// Services\n// ============================================================================\n\nexport type {\n  ExtensionService,\n} from '../types/index.js';\n\n// ============================================================================\n// Gateway\n// ============================================================================\n\nexport type {\n  GatewayMethodHandler,\n} from '../types/index.js';\n\n// ============================================================================\n// Export Classes\n// ============================================================================\n\nexport { TypedEventBus } from '../typed-event-bus.js';\nexport { ExtensionRegistryImpl } from '../loader.js';\nexport { ProviderPluginRegistry, getProviderRegistry } from '../../providers/plugin-registry.js';\nexport { SlotRegistry, getSlotRegistry, registerSlotType } from '../slots.js';\nexport { HOOK_EXECUTION_MODES } from '../types/hooks.js';\n\nexport { defineChannelPluginEntry } from './channel-entry.js';\nexport { registerExtensionCliProgram } from './channel-helpers.js';\n\n// ============================================================================\n// Export Hook Runner and Utilities\n// ============================================================================\n\nexport { \n  ExtensionHookRunner, \n  createHookContext, \n  isHookEvent \n} from '../hooks.js';\n\n// ============================================================================\n//  Security Utilities\n// ============================================================================\n\nexport {\n  checkExtensionPathSafety,\n  checkExtensionDirSafety,\n  isExtensionAllowed,\n  provenanceTracker,\n  logSecurityIssue,\n  DEFAULT_SECURITY_CONFIG,\n} from '../security.js';\n\n// ============================================================================\n//  Diagnostics Utilities\n// ============================================================================\n\nexport {\n  getExtensionCache,\n  getExtensionDiagnostics,\n  ExtensionLoaderCacheImpl,\n  ExtensionDiagnostics,\n} from '../diagnostics.js';\n\n// ============================================================================\n// Config\n// ============================================================================\n\nexport type { Config } from '../../config/config-surface.js';\n\n// Subpath barrels (also available as `xopc/extension-sdk/<name>`)\nexport { lazyModule, lazyFunction } from './lazy.js';\n"],"mappings":";;;;;;;;;;;;sBAiPiG"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/extensions/sdk/index.ts"],"sourcesContent":["/**\n * xopc Extension SDK\n * \n * Official SDK for developing xopc extensions.\n * Import types and utilities from this module:\n * \n * @example\n * import type { ExtensionApi, ExtensionDefinition } from 'xopc/extension-sdk';\n */\n\n// ============================================================================\n// Core extension types\n// ============================================================================\n\nexport type {\n  ExtensionDefinition,\n  ExtensionModule,\n  ExtensionKind,\n  ExtensionApi,\n  ExtensionLogger,\n  ExtensionManifest,\n  ExtensionRecord,\n  ExtensionRegistry,\n  ResolvedExtensionConfig,\n  ExtensionRuntime,\n  ExtensionCliRegistration,\n} from '../types/index.js';\n\n// ============================================================================\n// Tools (re-exported from @mariozechner/pi-agent-core)\n// ============================================================================\n\nexport type {\n  AgentTool,\n  AgentToolResult,\n  AgentToolUpdateCallback,\n  ToolExecutionStartEvent,\n  ToolExecutionUpdateEvent,\n  ToolExecutionEndEvent,\n} from '../types/index.js';\n\n// ============================================================================\n// Hooks ( Strongly Typed)\n// ============================================================================\n\nexport type {\n  ExtensionHookEvent,\n  ExtensionHookHandler,\n  HookOptions,\n  HookAgentContext,\n  AgentMessage,\n  ContextEvent,\n  ContextResult,\n  InputEvent,\n  InputResult,\n  TurnEvent,\n  TurnResult,\n  //  New hook types\n  HookHandlerMap,\n  HookExecutionMode,\n  // Note: HOOK_EXECUTION_MODES is exported as value below\n  //  LLM observation hooks\n  HookBeforeModelResolveEvent,\n  HookBeforeModelResolveResult,\n  HookBeforePromptBuildEvent,\n  HookBeforePromptBuildResult,\n  HookLlmInputEvent,\n  HookLlmOutputEvent,\n  //  Inbound claim\n  HookInboundClaimEvent,\n  HookInboundClaimResult,\n  //  Reset hook\n  HookBeforeResetEvent,\n  HookBeforeResetResult,\n  //  Message write hook\n  HookBeforeMessageWriteEvent,\n  HookBeforeMessageWriteResult,\n  //  Turn hooks\n  HookTurnStartEvent,\n  HookTurnEndEvent,\n  //  Tool execution hooks\n  HookToolExecutionStartEvent,\n  HookToolExecutionUpdateEvent,\n  HookToolExecutionEndEvent,\n  // Existing context types\n  HookContext,\n  BeforeAgentStartContext,\n  BeforeAgentStartResult,\n  AgentEndContext,\n  BeforeCompactionContext,\n  AfterCompactionContext,\n  MessageReceivedContext,\n  MessageSendingContext,\n  MessageSendingResult,\n  MessageSentContext,\n  BeforeToolCallContext,\n  BeforeToolCallResult,\n  AfterToolCallContext,\n  SessionStartContext,\n  SessionEndContext,\n  GatewayStartContext,\n  GatewayStopContext,\n} from '../types/index.js';\n\n// ============================================================================\n//  Typed Event Bus\n// ============================================================================\n\nexport type {\n  EventMap,\n  RequestMap,\n  EventHandler,\n  EventHandlerMeta,\n  RequestHandler,\n  RequestHandlerMeta,\n  WildcardEventHandler,\n  WildcardHandlerMeta,\n  TypedEventBusOptions,\n  RequestOptions,\n} from '../types/index.js';\n\n// ============================================================================\n//  Provider Types\n// ============================================================================\n\nexport type {\n  ProviderPlugin,\n  ProviderModelDefinition,\n  ProviderCapabilities,\n  ProviderStreamParams,\n  ProviderStreamChunk,\n  ProviderCompleteParams,\n  ProviderResponse,\n  ProviderRegistry,\n  BUILTIN_PROVIDERS,\n  BuiltinProviderId,\n} from '../types/index.js';\n\n// ============================================================================\n//  Advanced Features\n// ============================================================================\n\nexport type {\n  ProviderConfig,\n  ModelConfig,\n  OAuthConfig,\n  OAuthCallbacks,\n  OAuthCredentials,\n  FlagConfig,\n  FlagValue,\n  ShortcutConfig,\n  ShortcutHandler,\n} from '../types/index.js';\n\n// ============================================================================\n//  Security Types\n// ============================================================================\n\nexport type {\n  SafetyCheckResult,\n  SecurityConfig,\n  ExtensionSourceOrigin,\n  ProvenanceInfo,\n} from '../security.js';\n\n// ============================================================================\n//  Slot Types\n// ============================================================================\n\nexport type {\n  SlotKey,\n  SlotClaim,\n  SlotConfig,\n} from '../slots.js';\n\n// ============================================================================\n//  Diagnostics Types\n// ============================================================================\n\nexport type {\n  DiagnosticLevel,\n  ExtensionDiagnostic,\n  ExtensionLoaderCache,\n} from '../diagnostics.js';\n\n// ============================================================================\n// Channels (ChannelPlugin registry)\n// ============================================================================\n\nexport type {\n  ChannelPlugin,\n  ChannelPluginInitOptions,\n  ChannelPluginStartOptions,\n} from '../../channels/plugin-types.js';\n\n// ============================================================================\n// HTTP\n// ============================================================================\n\nexport type {\n  HttpRequestHandler,\n  HttpRequest,\n  HttpResponse,\n} from '../types/index.js';\n\n// ============================================================================\n// Commands\n// ============================================================================\n\nexport type {\n  ExtensionCommand,\n  ExtensionCommandHandler,\n  ExtensionCommandContext,\n  ExtensionCommandResult,\n  ExtensionReloadHandler,\n  ExtensionReloadResult,\n  ExtensionReloadRegistration,\n} from '../types/index.js';\n\n// ============================================================================\n// Services\n// ============================================================================\n\nexport type {\n  ExtensionService,\n} from '../types/index.js';\n\n// ============================================================================\n// Gateway\n// ============================================================================\n\nexport type {\n  GatewayMethodHandler,\n} from '../types/index.js';\n\n// ============================================================================\n// Export Classes\n// ============================================================================\n\nexport { TypedEventBus } from '../typed-event-bus.js';\nexport { ExtensionRegistryImpl } from '../loader.js';\nexport { ProviderPluginRegistry, getProviderRegistry } from '../../providers/plugin-registry.js';\nexport { SlotRegistry, getSlotRegistry, registerSlotType } from '../slots.js';\nexport { HOOK_EXECUTION_MODES } from '../types/hooks.js';\n\nexport { defineChannelPluginEntry } from './channel-entry.js';\nexport { registerExtensionCliProgram } from './channel-helpers.js';\n\n// ============================================================================\n// Export Hook Runner and Utilities\n// ============================================================================\n\nexport { \n  ExtensionHookRunner, \n  createHookContext, \n  isHookEvent \n} from '../hooks.js';\n\n// ============================================================================\n//  Security Utilities\n// ============================================================================\n\nexport {\n  checkExtensionPathSafety,\n  checkExtensionDirSafety,\n  isExtensionAllowed,\n  provenanceTracker,\n  logSecurityIssue,\n  DEFAULT_SECURITY_CONFIG,\n} from '../security.js';\n\n// ============================================================================\n//  Diagnostics Utilities\n// ============================================================================\n\nexport {\n  getExtensionCache,\n  getExtensionDiagnostics,\n  ExtensionLoaderCacheImpl,\n  ExtensionDiagnostics,\n} from '../diagnostics.js';\n\n// ============================================================================\n// Config\n// ============================================================================\n\nexport type { Config } from '../../config/config-surface.js';\n\n// Subpath barrels (also available as `xopc/extension-sdk/<name>`)\nexport { lazyModule, lazyFunction } from './lazy.js';\n\nexport { createMockExtensionApi, createTestGateway } from './testing.js';\nexport type {\n  MockExtensionApi,\n  MockExtensionApiOptions,\n  TestGateway,\n} from './testing.js';\n"],"mappings":";;;;;;;;;;;;;sBAiPiG"}

package/dist/src/extensions/sdk/testing.d.ts

@@ -1,5 +1,51 @@
 /**
- * Lightweight test doubles — no Vitest dependency.
+ * Extension testing helpers (Phase 2): mock API + minimal HTTP gateway fixture.
  */
-import type { ExtensionApi } from '../types/core.js';
-export declare function createMockExtensionApi(overrides?: Partial<ExtensionApi>): ExtensionApi;
+import type { AgentTool } from '@mariozechner/pi-agent-core';
+import type { ChannelPlugin } from '../../channels/plugin-types.js';
+import type { Config } from '../../config/config-surface.js';
+import type { ExtensionApi, ExtensionCommand, ExtensionCommandContext, ExtensionLogger, ExtensionReloadHandler, ExtensionService, GatewayMethodHandler, HttpRequestHandler } from '../types/core.js';
+import type { ExtensionHookEvent } from '../types/hooks.js';
+import type { CommandContribution } from '../types/manifest.js';
+export interface MockExtensionApiOptions {
+    id?: string;
+    name?: string;
+    version?: string;
+    source?: string;
+    extensionConfig?: Record<string, unknown>;
+    config?: Partial<Config>;
+    logger?: ExtensionLogger;
+    /** Pretend manifest `ui.contributions.commands` for `onCommand` tests. */
+    manifestCommands?: CommandContribution[];
+}
+export interface MockExtensionApi extends ExtensionApi {
+    getRegisteredTools(): AgentTool[];
+    getRegisteredHooks(): Array<{
+        event: ExtensionHookEvent;
+        handler: unknown;
+    }>;
+    getRegisteredCommands(): ExtensionCommand[];
+    getRegisteredHttpRoutes(): Array<{
+        path: string;
+        handler: HttpRequestHandler;
+    }>;
+    getRegisteredServices(): ExtensionService[];
+    getRegisteredGatewayMethods(): Array<{
+        method: string;
+        handler: GatewayMethodHandler;
+    }>;
+    getRegisteredChannelPlugins(): ChannelPlugin[];
+    getRegisteredReloadHandlers(): ExtensionReloadHandler[];
+    getEmittedEvents(): Array<{
+        event: string;
+        data: unknown;
+    }>;
+}
+export declare function createMockExtensionApi(options?: MockExtensionApiOptions): MockExtensionApi;
+export interface TestGateway {
+    baseUrl: string;
+    fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    close: () => Promise<void>;
+}
+export declare function createTestGateway(): Promise<TestGateway>;
+export type { ExtensionCommandContext };

package/dist/src/extensions/sdk/testing.js

@@ -1,12 +1,181 @@
+import { TypedEventBus } from "../typed-event-bus.js";
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { EventEmitter, once } from "node:events";
 //#region src/extensions/sdk/testing.ts
-function createMockExtensionApi(overrides) {
+const noopLogger = {
+	debug: () => {},
+	info: () => {},
+	warn: () => {},
+	error: () => {}
+};
+function createMockExtensionApi(options = {}) {
+	return new MockExtensionApiImpl(options);
+}
+var MockExtensionApiImpl = class {
+	id;
+	name;
+	version;
+	source;
+	config;
+	extensionConfig;
+	logger;
+	runtime;
+	events;
+	_tools = [];
+	_hooks = [];
+	_commands = [];
+	_http = [];
+	_services = [];
+	_gw = [];
+	_channels = [];
+	_reload = [];
+	_emitted = [];
+	_bus = new EventEmitter();
+	_manifestCommands = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.id = opts.id ?? "test-extension";
+		this.name = opts.name ?? "Test Extension";
+		this.version = opts.version;
+		this.source = opts.source ?? "/test";
+		this.extensionConfig = opts.extensionConfig ?? {};
+		this.config = opts.config ?? {};
+		this.logger = opts.logger ?? noopLogger;
+		this.runtime = {
+			config: this.config,
+			log: this.logger
+		};
+		this.events = new TypedEventBus({ logger: this.logger });
+		if (opts.manifestCommands?.length) for (const c of opts.manifestCommands) this._manifestCommands.set(c.id, c);
+	}
+	_setManifestCommands(commands) {
+		this._manifestCommands.clear();
+		for (const c of commands) this._manifestCommands.set(c.id, c);
+	}
+	getRegisteredTools() {
+		return [...this._tools];
+	}
+	getRegisteredHooks() {
+		return [...this._hooks];
+	}
+	getRegisteredCommands() {
+		return [...this._commands];
+	}
+	getRegisteredHttpRoutes() {
+		return [...this._http];
+	}
+	getRegisteredServices() {
+		return [...this._services];
+	}
+	getRegisteredGatewayMethods() {
+		return [...this._gw];
+	}
+	getRegisteredChannelPlugins() {
+		return [...this._channels];
+	}
+	getRegisteredReloadHandlers() {
+		return [...this._reload];
+	}
+	getEmittedEvents() {
+		return [...this._emitted];
+	}
+	registerTool(tool) {
+		this._tools.push(tool);
+	}
+	registerHook(event, handler, _opts) {
+		this._hooks.push({
+			event,
+			handler
+		});
+	}
+	onHook(_hookName, _handler) {}
+	registerChannel(registration) {
+		this._channels.push(registration.plugin);
+	}
+	registerHttpRoute(path, handler) {
+		this._http.push({
+			path,
+			handler
+		});
+	}
+	registerCommand(command) {
+		this._commands.push(command);
+	}
+	onCommand(commandId, handler) {
+		const meta = this._manifestCommands.get(commandId);
+		if (!meta) {
+			const name = commandId.includes(".") ? (commandId.split(".").pop() ?? commandId).trim() : commandId;
+			this.registerCommand({
+				name: name || commandId,
+				description: commandId,
+				handler
+			});
+			return;
+		}
+		let name;
+		if (meta.chatAlias?.trim()) name = meta.chatAlias.trim().replace(/^\//, "");
+		else name = meta.id.includes(".") ? meta.id.split(".").pop() ?? meta.id : meta.id;
+		if (!name) name = meta.id;
+		this.registerCommand({
+			name,
+			description: meta.title,
+			handler
+		});
+	}
+	registerReload(handler) {
+		this._reload.push(handler);
+	}
+	registerService(service) {
+		this._services.push(service);
+	}
+	registerGatewayMethod(method, handler) {
+		this._gw.push({
+			method,
+			handler
+		});
+	}
+	registerCli(_factory, _opts) {}
+	resolvePath(input) {
+		return `${this.source.replace(/\/$/, "")}/${input.replace(/^\//, "")}`;
+	}
+	emit(event, data) {
+		this._emitted.push({
+			event,
+			data
+		});
+		this._bus.emit(event, data);
+	}
+	on(event, handler) {
+		this._bus.on(event, handler);
+	}
+	off(event, handler) {
+		this._bus.off(event, handler);
+	}
+	registerProvider(_plugin) {}
+	registerProviderPlugin(_plugin) {}
+	registerFlag(_name, _config) {}
+	getFlag(_name) {}
+	registerShortcut(_key, _config) {}
+};
+async function createTestGateway() {
+	const app = new Hono();
+	app.get("/health", (c) => c.json({ ok: true }));
+	const server = serve({
+		fetch: app.fetch,
+		port: 0,
+		hostname: "127.0.0.1"
+	});
+	if (!server.listening) await once(server, "listening");
+	const baseUrl = `http://127.0.0.1:${server.address().port}`;
 	return {
-		id: "mock",
-		name: "mock",
-		...overrides
+		baseUrl,
+		fetch: (path, init) => fetch(`${baseUrl}${path.startsWith("/") ? path : `/${path}`}`, init),
+		close: () => new Promise((resolve, reject) => {
+			server.close((err) => err ? reject(err) : resolve());
+		})
 	};
 }
 //#endregion
-export { createMockExtensionApi };
+export { createMockExtensionApi, createTestGateway };
 
 //# sourceMappingURL=testing.js.map

package/dist/src/extensions/sdk/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","names":[],"sources":["../../../../src/extensions/sdk/testing.ts"],"sourcesContent":["/**\n * Lightweight test doubles — no Vitest dependency.\n */\n\nimport type { ExtensionApi } from '../types/core.js';\n\nexport function createMockExtensionApi(overrides?: Partial<ExtensionApi>): ExtensionApi {\n  return {\n    id: 'mock',\n    name: 'mock',\n    ...overrides,\n  } as unknown as ExtensionApi;\n}\n"],"mappings":";AAMA,SAAgB,uBAAuB,WAAiD;AACtF,QAAO;EACL,IAAI;EACJ,MAAM;EACN,GAAG;EACJ"}
+{"version":3,"file":"testing.js","names":[],"sources":["../../../../src/extensions/sdk/testing.ts"],"sourcesContent":["/**\n * Extension testing helpers (Phase 2): mock API + minimal HTTP gateway fixture.\n */\n\nimport type { Command } from 'commander';\nimport { EventEmitter } from 'node:events';\nimport { once } from 'node:events';\nimport type { AddressInfo } from 'node:net';\n\nimport type { AgentTool } from '@mariozechner/pi-agent-core';\n\nimport { Hono } from 'hono';\nimport { serve } from '@hono/node-server';\nimport type { ServerType } from '@hono/node-server';\n\nimport type { ChannelPlugin } from '../../channels/plugin-types.js';\nimport type { Config } from '../../config/config-surface.js';\nimport type {\n  ExtensionApi,\n  ExtensionCommand,\n  ExtensionCommandContext,\n  ExtensionCommandHandler,\n  ExtensionLogger,\n  ExtensionReloadHandler,\n  ExtensionRuntime,\n  ExtensionService,\n  GatewayMethodHandler,\n  HttpRequestHandler,\n} from '../types/core.js';\nimport type { FlagConfig, FlagValue, ShortcutConfig } from '../types/phase4.js';\nimport type {\n  ExtensionHookEvent,\n  ExtensionHookHandler,\n  HookHandlerMap,\n  HookOptions,\n} from '../types/hooks.js';\nimport type { CommandContribution } from '../types/manifest.js';\nimport { TypedEventBus } from '../typed-event-bus.js';\n\nexport interface MockExtensionApiOptions {\n  id?: string;\n  name?: string;\n  version?: string;\n  source?: string;\n  extensionConfig?: Record<string, unknown>;\n  config?: Partial<Config>;\n  logger?: ExtensionLogger;\n  /** Pretend manifest `ui.contributions.commands` for `onCommand` tests. */\n  manifestCommands?: CommandContribution[];\n}\n\nconst noopLogger: ExtensionLogger = {\n  debug: () => {},\n  info: () => {},\n  warn: () => {},\n  error: () => {},\n};\n\nexport interface MockExtensionApi extends ExtensionApi {\n  getRegisteredTools(): AgentTool[];\n  getRegisteredHooks(): Array<{ event: ExtensionHookEvent; handler: unknown }>;\n  getRegisteredCommands(): ExtensionCommand[];\n  getRegisteredHttpRoutes(): Array<{ path: string; handler: HttpRequestHandler }>;\n  getRegisteredServices(): ExtensionService[];\n  getRegisteredGatewayMethods(): Array<{ method: string; handler: GatewayMethodHandler }>;\n  getRegisteredChannelPlugins(): ChannelPlugin[];\n  getRegisteredReloadHandlers(): ExtensionReloadHandler[];\n  getEmittedEvents(): Array<{ event: string; data: unknown }>;\n}\n\nexport function createMockExtensionApi(options: MockExtensionApiOptions = {}): MockExtensionApi {\n  return new MockExtensionApiImpl(options);\n}\n\nclass MockExtensionApiImpl implements MockExtensionApi {\n  readonly id: string;\n  readonly name: string;\n  readonly version: string | undefined;\n  readonly source: string;\n  readonly config: Config;\n  readonly extensionConfig: Record<string, unknown>;\n  readonly logger: ExtensionLogger;\n  readonly runtime: ExtensionRuntime;\n  readonly events: TypedEventBus;\n\n  private readonly _tools: AgentTool[] = [];\n  private readonly _hooks: Array<{ event: ExtensionHookEvent; handler: unknown }> = [];\n  private readonly _commands: ExtensionCommand[] = [];\n  private readonly _http: Array<{ path: string; handler: HttpRequestHandler }> = [];\n  private readonly _services: ExtensionService[] = [];\n  private readonly _gw: Array<{ method: string; handler: GatewayMethodHandler }> = [];\n  private readonly _channels: ChannelPlugin[] = [];\n  private readonly _reload: ExtensionReloadHandler[] = [];\n  private readonly _emitted: Array<{ event: string; data: unknown }> = [];\n  private readonly _bus = new EventEmitter();\n  private readonly _manifestCommands = new Map<string, CommandContribution>();\n\n  constructor(opts: MockExtensionApiOptions) {\n    this.id = opts.id ?? 'test-extension';\n    this.name = opts.name ?? 'Test Extension';\n    this.version = opts.version;\n    this.source = opts.source ?? '/test';\n    this.extensionConfig = opts.extensionConfig ?? {};\n    this.config = (opts.config ?? {}) as Config;\n    this.logger = opts.logger ?? noopLogger;\n    this.runtime = { config: this.config, log: this.logger };\n    this.events = new TypedEventBus({ logger: this.logger });\n    if (opts.manifestCommands?.length) {\n      for (const c of opts.manifestCommands) {\n        this._manifestCommands.set(c.id, c);\n      }\n    }\n  }\n\n  _setManifestCommands(commands: CommandContribution[]): void {\n    this._manifestCommands.clear();\n    for (const c of commands) {\n      this._manifestCommands.set(c.id, c);\n    }\n  }\n\n  getRegisteredTools(): AgentTool[] {\n    return [...this._tools];\n  }\n  getRegisteredHooks(): Array<{ event: ExtensionHookEvent; handler: unknown }> {\n    return [...this._hooks];\n  }\n  getRegisteredCommands(): ExtensionCommand[] {\n    return [...this._commands];\n  }\n  getRegisteredHttpRoutes(): Array<{ path: string; handler: HttpRequestHandler }> {\n    return [...this._http];\n  }\n  getRegisteredServices(): ExtensionService[] {\n    return [...this._services];\n  }\n  getRegisteredGatewayMethods(): Array<{ method: string; handler: GatewayMethodHandler }> {\n    return [...this._gw];\n  }\n  getRegisteredChannelPlugins(): ChannelPlugin[] {\n    return [...this._channels];\n  }\n  getRegisteredReloadHandlers(): ExtensionReloadHandler[] {\n    return [...this._reload];\n  }\n  getEmittedEvents(): Array<{ event: string; data: unknown }> {\n    return [...this._emitted];\n  }\n\n  registerTool(tool: AgentTool): void {\n    this._tools.push(tool);\n  }\n\n  registerHook(\n    event: ExtensionHookEvent,\n    handler: ExtensionHookHandler,\n    _opts?: HookOptions,\n  ): void {\n    this._hooks.push({ event, handler });\n  }\n\n  onHook<K extends ExtensionHookEvent>(_hookName: K, _handler: HookHandlerMap[K]): void {\n    /* optional for tests */\n  }\n\n  registerChannel(registration: { plugin: ChannelPlugin }): void {\n    this._channels.push(registration.plugin);\n  }\n\n  registerHttpRoute(path: string, handler: HttpRequestHandler): void {\n    this._http.push({ path, handler });\n  }\n\n  registerCommand(command: ExtensionCommand): void {\n    this._commands.push(command);\n  }\n\n  onCommand(commandId: string, handler: ExtensionCommandHandler): void {\n    const meta = this._manifestCommands.get(commandId);\n    if (!meta) {\n      const name = commandId.includes('.')\n        ? (commandId.split('.').pop() ?? commandId).trim()\n        : commandId;\n      this.registerCommand({\n        name: name || commandId,\n        description: commandId,\n        handler,\n      });\n      return;\n    }\n    let name: string;\n    if (meta.chatAlias?.trim()) {\n      name = meta.chatAlias.trim().replace(/^\\//, '');\n    } else {\n      name = meta.id.includes('.') ? (meta.id.split('.').pop() ?? meta.id) : meta.id;\n    }\n    if (!name) name = meta.id;\n    this.registerCommand({ name, description: meta.title, handler });\n  }\n\n  registerReload(handler: ExtensionReloadHandler): void {\n    this._reload.push(handler);\n  }\n\n  registerService(service: ExtensionService): void {\n    this._services.push(service);\n  }\n\n  registerGatewayMethod(method: string, handler: GatewayMethodHandler): void {\n    this._gw.push({ method, handler });\n  }\n\n  registerCli(_factory: (ctx: { program: Command }) => void, _opts?: { commands: string[] }): void {\n    /* noop */\n  }\n\n  resolvePath(input: string): string {\n    const base = this.source.replace(/\\/$/, '');\n    const p = input.replace(/^\\//, '');\n    return `${base}/${p}`;\n  }\n\n  emit(event: string, data: unknown): void {\n    this._emitted.push({ event, data });\n    this._bus.emit(event, data);\n  }\n\n  on(event: string, handler: (data: unknown) => void): void {\n    this._bus.on(event, handler);\n  }\n\n  off(event: string, handler: (data: unknown) => void): void {\n    this._bus.off(event, handler);\n  }\n\n  registerProvider(_plugin: unknown): void {\n    /* noop */\n  }\n\n  registerProviderPlugin(_plugin: unknown): void {\n    /* noop */\n  }\n\n  registerFlag(_name: string, _config: FlagConfig): void {\n    /* noop */\n  }\n\n  getFlag(_name: string): FlagValue {\n    return undefined;\n  }\n\n  registerShortcut(_key: string, _config: ShortcutConfig): void {\n    /* noop */\n  }\n}\n\nexport interface TestGateway {\n  baseUrl: string;\n  fetch: (path: string, init?: RequestInit) => Promise<Response>;\n  close: () => Promise<void>;\n}\n\nexport async function createTestGateway(): Promise<TestGateway> {\n  const app = new Hono();\n  app.get('/health', (c) => c.json({ ok: true }));\n\n  const server: ServerType = serve({\n    fetch: app.fetch,\n    port: 0,\n    hostname: '127.0.0.1',\n  });\n\n  if (!server.listening) {\n    await once(server, 'listening');\n  }\n  const addr = server.address() as AddressInfo;\n  const port = addr.port;\n  const baseUrl = `http://127.0.0.1:${port}`;\n\n  return {\n    baseUrl,\n    fetch: (path, init) =>\n      fetch(`${baseUrl}${path.startsWith('/') ? path : `/${path}`}`, init),\n    close: () =>\n      new Promise((resolve, reject) => {\n        server.close((err) => (err ? reject(err) : resolve()));\n      }),\n  };\n}\n\nexport type { ExtensionCommandContext };\n"],"mappings":"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"}

package/dist/src/extensions/types/core.d.ts

@@ -79,6 +79,11 @@ export interface ExtensionApi {
     }): void;
     registerHttpRoute(path: string, handler: HttpRequestHandler): void;
     registerCommand(command: ExtensionCommand): void;
+    /**
+     * Bind a handler to a manifest-declared command id (`ui.contributions.commands`).
+     * Metadata comes from the manifest; optional `chatAlias` becomes the slash command name.
+     */
+    onCommand(commandId: string, handler: ExtensionCommandHandler): void;
     /**
      * Register a reload handler when config paths matching this extension change during hot reload.
      */

package/dist/src/extensions/types/manifest.d.ts

@@ -3,6 +3,11 @@
  * New fields are optional for backward compatibility.
  */
 import type { ExtensionKind } from './core.js';
+/** Declared in `engines` in the extension manifest (e.g. VSCode-style). */
+export interface EnginesDeclaration {
+    /** Semver range string for the running xopc CLI / gateway, e.g. `">=0.0.20"`. */
+    xopc?: string;
+}
 export interface ExtensionManifest {
     id: string;
     name: string;
@@ -29,6 +34,11 @@ export interface ExtensionManifest {
         configPrefixes?: string[];
         supportsHotReload?: boolean;
     };
+    /**
+     * Host / runtime requirements (e.g. compatible xopc semver range).
+     * Normalized from `xopc.extension.json` `engines`.
+     */
+    engines?: EnginesDeclaration;
     /** Chat commands metadata (runtime registration still required in `register()`). */
     commands?: ExtensionManifestCommand[];
     /** Frontend UI declaration — enables extensions to render custom UI in the Gateway Console. */
@@ -70,6 +80,8 @@ export interface SidebarPanelContribution {
     icon?: string;
     entrypoint: string;
     defaultVisible?: boolean;
+    /** When-expression for visibility (see Phase 2). */
+    when?: string;
 }
 /** A panel rendered inside the settings page. */
 export interface SettingsPanelContribution {
@@ -102,6 +114,7 @@ export interface PageContribution {
     showInNav?: boolean;
     /** Lucide icon name */
     navIcon?: string;
+    when?: string;
 }
 /** A command registered in the command palette. */
 export interface CommandContribution {
@@ -109,6 +122,9 @@ export interface CommandContribution {
     title: string;
     shortcut?: string;
     opensPanel?: string;
+    /** Optional chat slash name (e.g. `/hello`); bound via `api.onCommand`. */
+    chatAlias?: string;
+    when?: string;
 }
 /** A small widget rendered in the status bar. */
 export interface StatusBarItemContribution {
@@ -116,6 +132,7 @@ export interface StatusBarItemContribution {
     entrypoint: string;
     position?: 'left' | 'right';
     width?: number;
+    when?: string;
 }
 export interface ProviderAuthChoice {
     provider: string;

package/dist/src/extensions/when-context.d.ts

@@ -0,0 +1,6 @@
+import type { Config as SurfaceConfig } from '../config/config-surface.js';
+import type { ExtensionLoader } from './loader.js';
+/**
+ * Flat payload for `GET /api/context` and client-side `when` evaluation.
+ */
+export declare function buildWhenContextSnapshot(config: SurfaceConfig, loader: ExtensionLoader | null): Record<string, unknown>;

package/dist/src/extensions/when-context.js

@@ -0,0 +1,28 @@
+import { getAllProviders, init_providers, isProviderConfiguredSync } from "../providers/index.js";
+//#region src/extensions/when-context.ts
+init_providers();
+/**
+* Flat payload for `GET /api/context` and client-side `when` evaluation.
+*/
+function buildWhenContextSnapshot(config, loader) {
+	const out = {
+		platform: process.platform,
+		isElectron: Boolean(process.versions.electron),
+		gatewayAuthenticated: true,
+		sessionActive: false,
+		agentRunning: false
+	};
+	for (const p of getAllProviders()) out[`hasProvider.${p}`] = isProviderConfiguredSync(p);
+	const channels = config.channels;
+	if (channels && typeof channels === "object") for (const [id, raw] of Object.entries(channels)) if (raw && typeof raw === "object" && raw !== null && "enabled" in raw) out[`hasChannel.${id}`] = raw.enabled === true;
+	else out[`hasChannel.${id}`] = Boolean(raw);
+	if (loader) try {
+		loader.setConfig(config);
+		for (const ext of loader.discoverExtensions()) out[`extensionEnabled.${ext.id}`] = true;
+	} catch {}
+	return out;
+}
+//#endregion
+export { buildWhenContextSnapshot };
+
+//# sourceMappingURL=when-context.js.map

package/dist/src/extensions/when-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"when-context.js","names":[],"sources":["../../../src/extensions/when-context.ts"],"sourcesContent":["import type { Config as SurfaceConfig } from '../config/config-surface.js';\nimport { getAllProviders, isProviderConfiguredSync } from '../providers/index.js';\nimport type { ExtensionLoader } from './loader.js';\n\n/**\n * Flat payload for `GET /api/context` and client-side `when` evaluation.\n */\nexport function buildWhenContextSnapshot(\n  config: SurfaceConfig,\n  loader: ExtensionLoader | null,\n): Record<string, unknown> {\n  const out: Record<string, unknown> = {\n    platform: process.platform,\n    isElectron: Boolean(process.versions.electron),\n    gatewayAuthenticated: true,\n    sessionActive: false,\n    agentRunning: false,\n  };\n  for (const p of getAllProviders()) {\n    out[`hasProvider.${p}`] = isProviderConfiguredSync(p);\n  }\n  const channels = config.channels;\n  if (channels && typeof channels === 'object') {\n    for (const [id, raw] of Object.entries(channels)) {\n      if (raw && typeof raw === 'object' && raw !== null && 'enabled' in raw) {\n        out[`hasChannel.${id}`] = (raw as { enabled?: boolean }).enabled === true;\n      } else {\n        out[`hasChannel.${id}`] = Boolean(raw);\n      }\n    }\n  }\n  if (loader) {\n    try {\n      loader.setConfig(config);\n      for (const ext of loader.discoverExtensions()) {\n        out[`extensionEnabled.${ext.id}`] = true;\n      }\n    } catch {\n      /* non-fatal for context snapshot */\n    }\n  }\n  return out;\n}\n"],"mappings":";;gBACkF;;;;AAMlF,SAAgB,yBACd,QACA,QACyB;CACzB,MAAM,MAA+B;EACnC,UAAU,QAAQ;EAClB,YAAY,QAAQ,QAAQ,SAAS,SAAS;EAC9C,sBAAsB;EACtB,eAAe;EACf,cAAc;EACf;AACD,MAAK,MAAM,KAAK,iBAAiB,CAC/B,KAAI,eAAe,OAAO,yBAAyB,EAAE;CAEvD,MAAM,WAAW,OAAO;AACxB,KAAI,YAAY,OAAO,aAAa,SAClC,MAAK,MAAM,CAAC,IAAI,QAAQ,OAAO,QAAQ,SAAS,CAC9C,KAAI,OAAO,OAAO,QAAQ,YAAY,QAAQ,QAAQ,aAAa,IACjE,KAAI,cAAc,QAAS,IAA8B,YAAY;KAErE,KAAI,cAAc,QAAQ,QAAQ,IAAI;AAI5C,KAAI,OACF,KAAI;AACF,SAAO,UAAU,OAAO;AACxB,OAAK,MAAM,OAAO,OAAO,oBAAoB,CAC3C,KAAI,oBAAoB,IAAI,QAAQ;SAEhC;AAIV,QAAO"}

package/dist/src/extensions/when-expression.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Boolean when-expressions for extension UI contributions (Phase 2).
+ * Grammar: expression := term (('&&' | '||') term)*; term := '!' term | atom;
+ * atom := variable (('==' | '!=') literal)? | '(' expression ')'
+ */
+export type WhenContext = Record<string, unknown>;
+/**
+ * Evaluate a when-expression string against a flat context object.
+ * Unknown variables are treated as falsey for boolean tests; missing keys are undefined.
+ */
+export declare function evaluateWhenExpression(expr: string, ctx: WhenContext): boolean;

package/dist/src/extensions/when-expression.js

@@ -0,0 +1,215 @@
+//#region src/extensions/when-expression.ts
+function tokenize(input) {
+	const out = [];
+	let i = 0;
+	const s = input.trim();
+	while (i < s.length) {
+		const c = s[i];
+		if (/\s/.test(c)) {
+			i++;
+			continue;
+		}
+		if (s.slice(i, i + 2) === "&&") {
+			out.push({ k: "AND" });
+			i += 2;
+			continue;
+		}
+		if (s.slice(i, i + 2) === "||") {
+			out.push({ k: "OR" });
+			i += 2;
+			continue;
+		}
+		if (s.slice(i, i + 2) === "==") {
+			out.push({ k: "EQ" });
+			i += 2;
+			continue;
+		}
+		if (s.slice(i, i + 2) === "!=") {
+			out.push({ k: "NE" });
+			i += 2;
+			continue;
+		}
+		if (c === "(") {
+			out.push({ k: "LP" });
+			i++;
+			continue;
+		}
+		if (c === ")") {
+			out.push({ k: "RP" });
+			i++;
+			continue;
+		}
+		if (c === "!") {
+			out.push({ k: "NOT" });
+			i++;
+			continue;
+		}
+		if (c === "'" || c === "\"") {
+			const q = c;
+			i++;
+			let buf = "";
+			while (i < s.length) {
+				const ch = s[i];
+				if (ch === "\\" && i + 1 < s.length) {
+					buf += s[i + 1];
+					i += 2;
+					continue;
+				}
+				if (ch === q) {
+					i++;
+					break;
+				}
+				buf += ch;
+				i++;
+			}
+			out.push({
+				k: "STR",
+				v: buf
+			});
+			continue;
+		}
+		if (/[0-9]/.test(c) || c === "-" && i + 1 < s.length && /[0-9]/.test(s[i + 1])) {
+			let j = i + 1;
+			while (j < s.length && /[0-9.]/.test(s[j])) j++;
+			const n = Number(s.slice(i, j));
+			out.push({
+				k: "NUM",
+				v: Number.isFinite(n) ? n : 0
+			});
+			i = j;
+			continue;
+		}
+		if (/[a-zA-Z_]/.test(c)) {
+			let j = i + 1;
+			while (j < s.length && /[a-zA-Z0-9_.]/.test(s[j])) j++;
+			const word = s.slice(i, j);
+			i = j;
+			if (word === "true") out.push({
+				k: "BOOL",
+				v: true
+			});
+			else if (word === "false") out.push({
+				k: "BOOL",
+				v: false
+			});
+			else out.push({
+				k: "IDENT",
+				v: word
+			});
+			continue;
+		}
+		throw new Error(`Unexpected character in when-expression at ${i}: ${c}`);
+	}
+	out.push({ k: "EOF" });
+	return out;
+}
+function ctxLookup(ctx, key) {
+	if (key in ctx) return ctx[key];
+}
+var Parser = class {
+	i = 0;
+	constructor(toks, ctx) {
+		this.toks = toks;
+		this.ctx = ctx;
+	}
+	parse() {
+		const v = this.parseOr();
+		const tail = this.cur();
+		if (tail.k !== "EOF") throw new Error(`Unexpected tokens after expression (at ${this.i}: ${tail.k}${"v" in tail ? ` ${tail.v}` : ""})`);
+		return v;
+	}
+	cur() {
+		return this.toks[this.i] ?? { k: "EOF" };
+	}
+	parseOr() {
+		let v = this.parseAnd();
+		while (this.cur().k === "OR") {
+			this.i++;
+			const rhs = this.parseAnd();
+			v = v || rhs;
+		}
+		return v;
+	}
+	parseAnd() {
+		let v = this.parseUnary();
+		while (this.cur().k === "AND") {
+			this.i++;
+			const rhs = this.parseUnary();
+			v = v && rhs;
+		}
+		return v;
+	}
+	parseUnary() {
+		if (this.cur().k === "NOT") {
+			this.i++;
+			return !this.parseUnary();
+		}
+		return this.parsePrimary();
+	}
+	parsePrimary() {
+		if (this.cur().k === "LP") {
+			this.i++;
+			const inner = this.parseOr();
+			if (this.cur().k !== "RP") throw new Error("Expected )");
+			this.i++;
+			return inner;
+		}
+		return this.parseAtom();
+	}
+	parseAtom() {
+		const left = this.readAtomValue();
+		const op = this.cur();
+		if (op.k === "EQ" || op.k === "NE") {
+			this.i++;
+			const eq = valuesLooselyEqual(left, this.readAtomValue());
+			return op.k === "EQ" ? eq : !eq;
+		}
+		return isTruthyWhen(left);
+	}
+	readAtomValue() {
+		const t = this.cur();
+		if (t.k === "IDENT") {
+			this.i++;
+			return ctxLookup(this.ctx, t.v);
+		}
+		if (t.k === "STR") {
+			this.i++;
+			return t.v;
+		}
+		if (t.k === "NUM") {
+			this.i++;
+			return t.v;
+		}
+		if (t.k === "BOOL") {
+			this.i++;
+			return t.v;
+		}
+		throw new Error("Expected value in when-expression");
+	}
+};
+function valuesLooselyEqual(a, b) {
+	if (a === b) return true;
+	if (a == null || b == null) return a === b;
+	if (typeof a === "boolean" || typeof b === "boolean") return Boolean(a) === Boolean(b);
+	if (typeof a === "number" && typeof b === "number") return a === b;
+	return String(a) === String(b);
+}
+function isTruthyWhen(v) {
+	if (typeof v === "boolean") return v;
+	if (typeof v === "number") return v !== 0;
+	if (typeof v === "string") return v.length > 0;
+	return v != null;
+}
+/**
+* Evaluate a when-expression string against a flat context object.
+* Unknown variables are treated as falsey for boolean tests; missing keys are undefined.
+*/
+function evaluateWhenExpression(expr, ctx) {
+	const s = expr.trim();
+	if (!s) return true;
+	return new Parser(tokenize(s), ctx).parse();
+}
+//#endregion
+export { evaluateWhenExpression };
+
+//# sourceMappingURL=when-expression.js.map