@openforge-app/plugin-sdk 0.1.0

package/dist/testing.js

@@ -0,0 +1,625 @@
+export class TestingSubscriptionSink {
+    subscriptions = [];
+    add(subscription) {
+        if (typeof subscription === 'function') {
+            this.subscriptions.push(createDisposable(subscription));
+            return;
+        }
+        if (!subscription || typeof subscription.dispose !== 'function') {
+            throw new Error('context.subscriptions.add requires a disposable or cleanup function');
+        }
+        this.subscriptions.push(subscription);
+    }
+    async disposeAll() {
+        const subscriptions = this.subscriptions.splice(0).reverse();
+        for (const subscription of subscriptions) {
+            await subscription.dispose();
+        }
+    }
+}
+export class TestingOpenForgeRegistryFake {
+    pluginId;
+    projectId;
+    taskId;
+    viewId;
+    packageMetadata;
+    calls;
+    storage;
+    frontendSubscriptions = new TestingSubscriptionSink();
+    backendSubscriptions = new TestingSubscriptionSink();
+    commands = new Map();
+    views = new Map();
+    taskPaneTabs = new Map();
+    settingsSections = new Map();
+    eventListeners = new Map();
+    eventHandlers = new Map();
+    backendMethods = new Map();
+    backgroundServices = new Map();
+    claimedIds = new Set();
+    config = new Map();
+    eventListenerSequence = 0;
+    cachedFrontendApi = null;
+    cachedBackendApi = null;
+    constructor(options = {}) {
+        this.pluginId = options.pluginId ?? 'test-plugin';
+        this.projectId = options.projectId ?? null;
+        this.taskId = options.taskId ?? null;
+        this.viewId = options.viewId ?? 'board';
+        this.packageMetadata = options.packageMetadata ?? {
+            id: this.pluginId,
+            apiVersion: 1,
+            displayName: this.pluginId,
+            description: '',
+        };
+        this.calls = createTestingCalls();
+        this.storage = options.storage ?? createMemoryPluginStorage(this.calls);
+    }
+    get frontendApi() {
+        return this.createFrontendApi();
+    }
+    get backendApi() {
+        return this.createBackendApi();
+    }
+    get snapshot() {
+        return this.getSnapshot();
+    }
+    createFrontendApi() {
+        if (this.cachedFrontendApi)
+            return this.cachedFrontendApi;
+        const api = {
+            ...this.createCommonApi(),
+            views: {
+                register: (registration) => this.registerView(registration),
+            },
+            taskPane: {
+                registerTab: (registration) => this.registerTaskPaneTab(registration),
+            },
+            settings: {
+                registerSection: (registration) => this.registerSettingsSection(registration),
+            },
+            backend: {
+                state: 'ready',
+                whenReady: async () => undefined,
+                onReady: (handler) => {
+                    handler();
+                    return createDisposable(() => undefined);
+                },
+                invoke: async (method, payload) => this.invokeBackend(method, payload),
+            },
+            __testing: {
+                calls: this.calls,
+                registry: this,
+            },
+        };
+        this.cachedFrontendApi = api;
+        return api;
+    }
+    createBackendApi() {
+        if (this.cachedBackendApi)
+            return this.cachedBackendApi;
+        const api = {
+            ...this.createCommonApi(),
+            backend: {
+                registerMethod: (method, registration) => this.registerBackendMethod(method, registration),
+            },
+            background: {
+                register: (registration) => this.registerBackgroundService(registration),
+            },
+            __testing: {
+                calls: this.calls,
+                registry: this,
+            },
+        };
+        this.cachedBackendApi = api;
+        return api;
+    }
+    createFrontendContext() {
+        return this.createContext(this.frontendSubscriptions);
+    }
+    createBackendContext() {
+        return this.createContext(this.backendSubscriptions);
+    }
+    async activateFrontend(plugin) {
+        await plugin.activate(this.frontendApi, this.createFrontendContext());
+    }
+    async activateBackend(plugin) {
+        const existingServices = new Set(this.backgroundServices.keys());
+        await plugin.activate(this.backendApi, this.createBackendContext());
+        await this.startBackgroundServices(existingServices);
+    }
+    async disposeAll() {
+        await this.backendSubscriptions.disposeAll();
+        await this.frontendSubscriptions.disposeAll();
+    }
+    getSnapshot() {
+        return {
+            pluginId: this.pluginId,
+            projectId: this.projectId,
+            views: Array.from(this.views.values()),
+            taskPaneTabs: Array.from(this.taskPaneTabs.values()),
+            settingsSections: Array.from(this.settingsSections.values()),
+            commands: Array.from(this.commands.values()),
+            eventListeners: Array.from(this.eventListeners.values()),
+            backendMethods: Array.from(this.backendMethods.values()),
+            backgroundServices: Array.from(this.backgroundServices.values()),
+        };
+    }
+    createContext(subscriptions) {
+        return {
+            pluginId: this.pluginId,
+            apiVersion: 1,
+            packageMetadata: this.packageMetadata,
+            subscriptions,
+        };
+    }
+    startPromptContributions(projectId) {
+        const raw = this.config.get(`project:${projectId}:start_prompt_contributions`);
+        return Array.isArray(raw) ? raw.filter((entry) => Boolean(entry) && typeof entry === 'object' && typeof entry.id === 'string' && typeof entry.content === 'string') : [];
+    }
+    createCommonApi() {
+        return {
+            commands: {
+                register: (registration) => this.registerCommand(registration),
+                invoke: async (id, payload) => this.invokeCommand(id, payload),
+                invokeGlobal: async (qualifiedId, payload) => this.invokeGlobalCommand(qualifiedId, payload),
+                list: async () => Array.from(this.commands.values()).map(commandDescriptor),
+            },
+            events: {
+                on: (event, handler) => this.registerEventListener(event, handler, false),
+                onGlobal: (qualifiedEvent, handler) => this.registerEventListener(qualifiedEvent, handler, true),
+                emit: async (event, payload) => this.emitEvent(event, payload, false),
+                emitGlobal: async (qualifiedEvent, payload) => this.emitEvent(qualifiedEvent, payload, true),
+            },
+            storage: this.storage,
+            context: {
+                getSnapshot: () => this.getContextSnapshot(),
+            },
+            tasks: {
+                list: async () => [],
+                get: async (taskId) => { throw new Error(`Mock task not found: ${taskId}`); },
+                create: async (request) => {
+                    this.calls.taskCreations.push(request);
+                    return {
+                        id: `mock-task-${this.calls.taskCreations.length}`,
+                        initial_prompt: request.initialPrompt,
+                        status: 'backlog',
+                        prompt: null,
+                        title: null,
+                        title_source: null,
+                        title_generated_at: null,
+                        summary: null,
+                        agent: null,
+                        permission_mode: null,
+                        worktree_source: null,
+                        worktree_branch: null,
+                        handoff_notes_enabled: true,
+                        depends_on: request.dependsOn ?? [],
+                        project_id: request.projectId,
+                        created_at: 0,
+                        updated_at: 0,
+                    };
+                },
+                updateSummary: async (taskId, summary) => {
+                    this.calls.taskSummaryUpdates.push({ taskId, summary });
+                },
+                updateStatus: async (taskId, status) => {
+                    this.calls.taskStatusUpdates.push({ taskId, status });
+                },
+                listStartPromptContributions: async (projectId) => this.startPromptContributions(projectId),
+                configureStartPromptContribution: async (request) => {
+                    this.calls.startPromptContributionConfigurations.push(request);
+                    const existing = this.startPromptContributions(request.projectId).filter((entry) => entry.id !== request.id);
+                    const next = [...existing, request].sort((a, b) => (a.order ?? 0) - (b.order ?? 0) || a.id.localeCompare(b.id));
+                    this.config.set(`project:${request.projectId}:start_prompt_contributions`, next);
+                    return next;
+                },
+                startImplementation: async (request) => {
+                    this.calls.taskImplementationStarts.push(request);
+                    return {
+                        taskId: request.taskId,
+                        workspacePath: '/mock-workspace',
+                        sessionId: 'mock-session',
+                    };
+                },
+                getWorkspace: async () => null,
+                getLatestSession: async () => null,
+            },
+            projects: {
+                list: async () => [],
+                get: async () => null,
+            },
+            fs: {
+                readDir: async () => [],
+                readFile: async () => ({ type: 'text', content: '', mimeType: null, size: 0 }),
+                writeFile: async (request) => {
+                    this.calls.fsWrites.push(request);
+                },
+                searchFiles: async () => [],
+            },
+            shell: {
+                spawn: async (request) => {
+                    this.calls.shellSpawns.push(request);
+                    return 0;
+                },
+                write: async (request) => {
+                    this.calls.shellWrites.push(request);
+                },
+                resize: async (request) => {
+                    this.calls.shellResizes.push(request);
+                },
+                kill: async (request) => {
+                    this.calls.shellKills.push(request);
+                },
+                getBuffer: async (request) => {
+                    this.calls.shellBuffers.push(request);
+                    return null;
+                },
+            },
+            notifications: {
+                notify: async (request) => {
+                    this.calls.notify.push(request);
+                },
+            },
+            attention: {
+                listProjects: async () => [],
+            },
+            system: {
+                openUrl: async (url) => {
+                    this.calls.openUrl.push(url);
+                },
+            },
+            navigation: {
+                get: () => this.getNavigationSnapshot(),
+                navigate: async (request) => {
+                    this.calls.navigationRequests.push(request);
+                    return this.getNavigationSnapshot(request);
+                },
+            },
+            config: {
+                get: async (key) => this.config.has(`global:${key}`) ? this.config.get(`global:${key}`) : null,
+                set: async (key, value) => {
+                    this.config.set(`global:${key}`, value);
+                    this.calls.configWrites.push({ key, value, projectId: null });
+                },
+            },
+            projectConfig: {
+                get: async (key, projectId = this.projectId ?? '') => this.config.has(`project:${projectId}:${key}`) ? this.config.get(`project:${projectId}:${key}`) : null,
+                set: async (key, value, projectId = this.projectId ?? '') => {
+                    this.config.set(`project:${projectId}:${key}`, value);
+                    this.calls.configWrites.push({ key, value, projectId });
+                },
+            },
+        };
+    }
+    getContextSnapshot() {
+        return {
+            pluginId: this.pluginId,
+            projectId: this.projectId,
+            ...(this.taskId === null ? {} : { taskId: this.taskId }),
+        };
+    }
+    getNavigationSnapshot(overrides = {}) {
+        return {
+            activeProjectId: overrides.projectId ?? this.projectId,
+            currentView: overrides.viewId ?? this.viewId,
+            selectedTaskId: overrides.taskId ?? this.taskId,
+        };
+    }
+    localQualifiedId(kind, id) {
+        assertLocalId(kind, id);
+        return `${this.pluginId}.${id.trim()}`;
+    }
+    claim(kind, qualifiedId) {
+        const key = kind === 'commands' ? `commands:${qualifiedId}` : `${kind}:${qualifiedId}`;
+        if (this.claimedIds.has(key)) {
+            throw new Error(`Duplicate runtime contribution id: ${qualifiedId}`);
+        }
+        this.claimedIds.add(key);
+    }
+    release(kind, qualifiedId) {
+        const key = kind === 'commands' ? `commands:${qualifiedId}` : `${kind}:${qualifiedId}`;
+        this.claimedIds.delete(key);
+    }
+    registerCommand(registration) {
+        const qualifiedId = this.localQualifiedId('commands', registration.id);
+        assertTitle('commands', registration.title);
+        assertFunction('commands', 'handler', registration.handler);
+        this.claim('commands', qualifiedId);
+        const contribution = {
+            ...registration,
+            id: registration.id.trim(),
+            title: registration.title.trim(),
+            qualifiedId,
+            pluginId: this.pluginId,
+            projectId: this.projectId,
+            handler: registration.handler,
+        };
+        this.commands.set(qualifiedId, contribution);
+        return createDisposable(() => {
+            this.commands.delete(qualifiedId);
+            this.release('commands', qualifiedId);
+        });
+    }
+    registerView(registration) {
+        const qualifiedId = this.localQualifiedId('views', registration.id);
+        assertTitle('views', registration.title);
+        assertFunction('views', 'component', registration.component);
+        this.claim('views', qualifiedId);
+        const contribution = {
+            ...registration,
+            id: registration.id.trim(),
+            title: registration.title.trim(),
+            qualifiedId,
+            pluginId: this.pluginId,
+            projectId: this.projectId,
+        };
+        this.views.set(qualifiedId, contribution);
+        return createDisposable(() => {
+            this.views.delete(qualifiedId);
+            this.release('views', qualifiedId);
+        });
+    }
+    registerTaskPaneTab(registration) {
+        const qualifiedId = this.localQualifiedId('taskPane', registration.id);
+        assertTitle('taskPane', registration.title);
+        assertFunction('taskPane', 'component', registration.component);
+        this.claim('taskPane', qualifiedId);
+        const contribution = {
+            ...registration,
+            id: registration.id.trim(),
+            title: registration.title.trim(),
+            qualifiedId,
+            pluginId: this.pluginId,
+            projectId: this.projectId,
+        };
+        this.taskPaneTabs.set(qualifiedId, contribution);
+        return createDisposable(() => {
+            this.taskPaneTabs.delete(qualifiedId);
+            this.release('taskPane', qualifiedId);
+        });
+    }
+    registerSettingsSection(registration) {
+        const qualifiedId = this.localQualifiedId('settings', registration.id);
+        assertTitle('settings', registration.title);
+        assertFunction('settings', 'component', registration.component);
+        this.claim('settings', qualifiedId);
+        const contribution = {
+            ...registration,
+            id: registration.id.trim(),
+            title: registration.title.trim(),
+            qualifiedId,
+            pluginId: this.pluginId,
+            projectId: this.projectId,
+        };
+        this.settingsSections.set(qualifiedId, contribution);
+        return createDisposable(() => {
+            this.settingsSections.delete(qualifiedId);
+            this.release('settings', qualifiedId);
+        });
+    }
+    registerBackendMethod(method, registration) {
+        const qualifiedId = this.localQualifiedId('backend', method);
+        assertFunction('backend', 'handler', registration.handler);
+        this.claim('backend', qualifiedId);
+        const contribution = {
+            id: method.trim(),
+            qualifiedId,
+            pluginId: this.pluginId,
+            projectId: this.projectId,
+            registration,
+        };
+        this.backendMethods.set(qualifiedId, contribution);
+        return createDisposable(() => {
+            this.backendMethods.delete(qualifiedId);
+            this.release('backend', qualifiedId);
+        });
+    }
+    registerBackgroundService(registration) {
+        const qualifiedId = this.localQualifiedId('background', registration.id);
+        if (registration.scope !== 'global' && registration.scope !== 'project' && registration.scope !== 'task') {
+            throw new Error('background registration requires scope to be global, project, or task');
+        }
+        assertFunction('background', 'start', registration.start);
+        this.claim('background', qualifiedId);
+        const contribution = {
+            ...registration,
+            id: registration.id.trim(),
+            qualifiedId,
+            pluginId: this.pluginId,
+            projectId: this.projectId,
+            started: false,
+        };
+        this.backgroundServices.set(qualifiedId, contribution);
+        return createDisposable(async () => {
+            this.backgroundServices.delete(qualifiedId);
+            this.release('background', qualifiedId);
+            if (contribution.started) {
+                await contribution.stop?.();
+                contribution.started = false;
+            }
+        });
+    }
+    registerEventListener(event, handler, global) {
+        const qualifiedId = global ? event : this.localQualifiedId('events', event);
+        if (qualifiedId.trim().length === 0) {
+            throw new Error('events registration requires a non-empty id');
+        }
+        assertFunction('events', 'handler', handler);
+        const handlers = this.eventHandlers.get(qualifiedId) ?? new Set();
+        handlers.add(handler);
+        this.eventHandlers.set(qualifiedId, handlers);
+        const listenerKey = `${qualifiedId}#${++this.eventListenerSequence}`;
+        const contribution = {
+            id: event,
+            qualifiedId,
+            pluginId: this.pluginId,
+            projectId: this.projectId,
+            handler,
+            global,
+        };
+        this.eventListeners.set(listenerKey, contribution);
+        return createDisposable(() => {
+            handlers.delete(handler);
+            if (handlers.size === 0) {
+                this.eventHandlers.delete(qualifiedId);
+            }
+            this.eventListeners.delete(listenerKey);
+        });
+    }
+    async startBackgroundServices(existingServices) {
+        for (const [key, service] of this.backgroundServices.entries()) {
+            if (existingServices.has(key) || service.started)
+                continue;
+            await service.start();
+            service.started = true;
+        }
+    }
+    async invokeCommand(id, payload) {
+        const qualifiedId = this.localQualifiedId('commands', id);
+        this.calls.commandInvocations.push({ id, qualifiedId, payload });
+        return this.invokeGlobalCommand(qualifiedId, payload);
+    }
+    async invokeGlobalCommand(qualifiedId, payload) {
+        this.calls.globalCommandInvocations.push({ qualifiedId, payload });
+        const command = this.commands.get(qualifiedId);
+        if (!command) {
+            throw new Error(`Unknown command: ${qualifiedId}`);
+        }
+        return await command.handler(payload);
+    }
+    async invokeBackend(method, payload) {
+        const qualifiedId = this.localQualifiedId('backend', method);
+        this.calls.backendInvocations.push({ method, qualifiedId, payload });
+        const contribution = this.backendMethods.get(qualifiedId);
+        if (!contribution) {
+            throw new Error(`Backend method is not registered: ${qualifiedId}`);
+        }
+        return await contribution.registration.handler(payload);
+    }
+    async emitEvent(event, payload, global) {
+        const qualifiedEvent = global ? event : this.localQualifiedId('events', event);
+        if (global) {
+            this.calls.emittedGlobalEvents.push({ qualifiedEvent, payload });
+        }
+        else {
+            this.calls.emittedEvents.push({ event, qualifiedEvent, payload });
+        }
+        for (const handler of Array.from(this.eventHandlers.get(qualifiedEvent) ?? [])) {
+            handler(payload);
+        }
+    }
+}
+export function createOpenForgeRegistryFake(options = {}) {
+    return new TestingOpenForgeRegistryFake(options);
+}
+export function createMockOpenForgeApi(options = {}) {
+    return createMockFrontendOpenForgeApi(options);
+}
+export function createMockFrontendOpenForgeApi(options = {}) {
+    return createOpenForgeRegistryFake(options).frontendApi;
+}
+export function createMockBackendOpenForgeApi(options = {}) {
+    return createOpenForgeRegistryFake(options).backendApi;
+}
+export function createMockPluginContext(options = {}) {
+    return createOpenForgeRegistryFake(options).createFrontendContext();
+}
+export function createMemoryPluginStorage(calls = createTestingCalls()) {
+    const values = new Map();
+    function scope(scopeKind, scopeId) {
+        const prefix = `${scopeKind}:${scopeId ?? ''}:`;
+        return {
+            async get(key) {
+                calls.storageGets.push({ scope: scopeKind, scopeId, key });
+                return values.has(`${prefix}${key}`) ? values.get(`${prefix}${key}`) : null;
+            },
+            async set(key, value) {
+                values.set(`${prefix}${key}`, value);
+                calls.storageSets.push({ scope: scopeKind, scopeId, key, value });
+            },
+            async delete(key) {
+                values.delete(`${prefix}${key}`);
+                calls.storageDeletes.push({ scope: scopeKind, scopeId, key });
+            },
+        };
+    }
+    return {
+        global: scope('global', null),
+        project: (projectId) => scope('project', projectId),
+        task: (taskId) => scope('task', taskId),
+    };
+}
+export function createTestingCalls() {
+    return {
+        commandInvocations: [],
+        globalCommandInvocations: [],
+        backendInvocations: [],
+        emittedEvents: [],
+        emittedGlobalEvents: [],
+        openUrl: [],
+        navigationRequests: [],
+        notify: [],
+        taskCreations: [],
+        startPromptContributionConfigurations: [],
+        taskImplementationStarts: [],
+        taskSummaryUpdates: [],
+        taskStatusUpdates: [],
+        configWrites: [],
+        fsWrites: [],
+        shellSpawns: [],
+        shellWrites: [],
+        shellResizes: [],
+        shellKills: [],
+        shellBuffers: [],
+        storageGets: [],
+        storageSets: [],
+        storageDeletes: [],
+    };
+}
+function commandDescriptor(command) {
+    return {
+        id: command.id,
+        qualifiedId: command.qualifiedId,
+        pluginId: command.pluginId,
+        projectId: command.projectId,
+        title: command.title,
+        icon: command.icon,
+        shortcut: command.shortcut,
+        discoverable: command.discoverable ?? true,
+        input: command.input,
+        output: command.output,
+    };
+}
+function createDisposable(dispose) {
+    let disposed = false;
+    return {
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            await dispose();
+        },
+    };
+}
+function assertLocalId(kind, id) {
+    if (typeof id !== 'string' || id.trim().length === 0) {
+        throw new Error(`${kind} registration requires a non-empty id`);
+    }
+    const trimmed = id.trim();
+    if (trimmed.startsWith('openforge.')) {
+        throw new Error(`${kind} registration cannot use openforge.* reserved namespace`);
+    }
+    if (trimmed.includes(':') || trimmed.startsWith('.') || trimmed.endsWith('.') || trimmed.includes('..')) {
+        throw new Error(`${kind} registration has invalid id "${trimmed}"`);
+    }
+}
+function assertTitle(kind, title) {
+    if (typeof title !== 'string' || title.trim().length === 0) {
+        throw new Error(`${kind} registration requires a non-empty title`);
+    }
+}
+function assertFunction(kind, field, value) {
+    if (typeof value !== 'function') {
+        throw new Error(`${kind} registration requires a ${field} function`);
+    }
+}