@openforge-app/plugin-sdk 0.1.0 → 0.2.4

package/dist/testing/support.js

@@ -0,0 +1,247 @@
+export function createDisposable(dispose) {
+    let disposed = false;
+    return {
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            await dispose();
+        },
+    };
+}
+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 function createTestingCalls() {
+    return {
+        commandInvocations: [],
+        globalCommandInvocations: [],
+        backendInvocations: [],
+        emittedEvents: [],
+        emittedGlobalEvents: [],
+        openUrl: [],
+        clipboardWrites: [],
+        taskLinkOpenRequests: [],
+        navigationRequests: [],
+        notify: [],
+        taskCreations: [],
+        taskComposes: [],
+        startPromptContributionConfigurations: [],
+        taskImplementationStarts: [],
+        taskFollowUps: [],
+        taskListRequests: [],
+        taskStatusUpdates: [],
+        configWrites: [],
+        fsWrites: [],
+        fsUserDataReadDirs: [],
+        fsUserDataReads: [],
+        fsUserDataWrites: [],
+        fsExternalReadDirs: [],
+        fsExternalReads: [],
+        shellSpawns: [],
+        shellWrites: [],
+        shellResizes: [],
+        shellKills: [],
+        shellBuffers: [],
+        browserSurfaceGetOrCreate: [],
+        browserSurfaceAttachments: [],
+        browserSurfaceDetaches: [],
+        browserSurfaceDestroys: [],
+        browserSurfaceNavigations: [],
+        browserSurfaceControls: [],
+        browserSurfaceSelections: [],
+        browserSurfaceFeedbackClears: [],
+        browserSurfaceFeedbackReplacements: [],
+        browserSurfaceCaptureChecks: [],
+        browserSurfaceCaptures: [],
+        browserSurfaceCaptureDiscards: [],
+        browserSurfaceSessionResets: [],
+        storageGets: [],
+        storageSets: [],
+        storageDeletes: [],
+    };
+}
+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 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,
+    };
+}
+export function normalizeAgentCommandMetadata(metadata) {
+    if (metadata === undefined)
+        return undefined;
+    if (metadata === null || typeof metadata !== 'object' || Array.isArray(metadata)) {
+        throw new Error('commands registration agent metadata must be an object');
+    }
+    const candidate = metadata;
+    if (typeof candidate.description !== 'string' || candidate.description.trim().length === 0) {
+        throw new Error('commands registration agent metadata requires a non-empty description');
+    }
+    if (candidate.examples !== undefined && (!Array.isArray(candidate.examples) || !candidate.examples.every(example => isJsonValue(example)))) {
+        throw new Error('commands registration agent metadata examples must contain only JSON values');
+    }
+    if (candidate.discoverable !== undefined && typeof candidate.discoverable !== 'boolean') {
+        throw new Error('commands registration agent metadata discoverable must be a boolean');
+    }
+    return {
+        description: candidate.description.trim(),
+        examples: candidate.examples ? [...candidate.examples] : [],
+        discoverable: candidate.discoverable ?? true,
+    };
+}
+export function isJsonValue(value, seen = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object')
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    const valid = Array.isArray(value)
+        ? value.every(entry => isJsonValue(entry, seen))
+        : Object.values(value).every(entry => isJsonValue(entry, seen));
+    seen.delete(value);
+    return valid;
+}
+export 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}"`);
+    }
+}
+export function assertTitle(kind, title) {
+    if (typeof title !== 'string' || title.trim().length === 0) {
+        throw new Error(`${kind} registration requires a non-empty title`);
+    }
+}
+export function assertFunction(kind, field, value) {
+    if (typeof value !== 'function') {
+        throw new Error(`${kind} registration requires a ${field} function`);
+    }
+}
+export class TestingContributionClaims {
+    ids = new Set();
+    claim(kind, qualifiedId) {
+        const key = this.key(kind, qualifiedId);
+        if (this.ids.has(key)) {
+            throw new Error(`Duplicate runtime contribution id: ${qualifiedId}`);
+        }
+        this.ids.add(key);
+    }
+    release(kind, qualifiedId) {
+        this.ids.delete(this.key(kind, qualifiedId));
+    }
+    key(kind, qualifiedId) {
+        return kind === 'commands' ? `commands:${qualifiedId}` : `${kind}:${qualifiedId}`;
+    }
+}
+export class TestingRegistryServices {
+    pluginId;
+    projectId;
+    taskId;
+    viewId;
+    packageMetadata;
+    calls;
+    storage;
+    config = new Map();
+    seededTasks;
+    claims = new TestingContributionClaims();
+    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);
+        this.seededTasks = options.tasks ?? [];
+    }
+    localQualifiedId(kind, id) {
+        assertLocalId(kind, id);
+        return `${this.pluginId}.${id.trim()}`;
+    }
+    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,
+        };
+    }
+    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')
+            : [];
+    }
+}

package/dist/testing.d.ts

@@ -1,223 +1,3 @@
-import type { BackendMethodRegistration, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, CommandRegistration, CommandShortcutMetadata, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, JsonValue, NotificationRequest, OpenForgeNavigationRequest, OpenForgePackageMetadata, PluginSettingsSectionRegistration, PluginStorage, PluginTaskPaneTabRegistration, StartTaskImplementationRequest, PluginViewRegistration, SubscriptionSink } from './types';
-export type TestingRuntimeScope = 'global' | 'project' | 'task';
-export type TestingRuntimeKind = 'commands' | 'events' | 'views' | 'taskPane' | 'settings' | 'backend' | 'background';
-type MaybePromise<T> = T | Promise<T>;
-type CommandHandler = (payload?: unknown) => MaybePromise<unknown>;
-type EventHandler = (payload: unknown) => void;
-export interface TestingOpenForgeApiOptions {
-    pluginId?: string;
-    projectId?: string | null;
-    taskId?: string | null;
-    /** The active view key reported by `navigation.get().currentView`. Defaults to `'board'`. */
-    viewId?: string;
-    packageMetadata?: OpenForgePackageMetadata;
-    storage?: PluginStorage;
-}
-export interface TestingOpenForgeApiCalls {
-    commandInvocations: Array<{
-        id: string;
-        qualifiedId: string;
-        payload: unknown;
-    }>;
-    globalCommandInvocations: Array<{
-        qualifiedId: string;
-        payload: unknown;
-    }>;
-    backendInvocations: Array<{
-        method: string;
-        qualifiedId: string;
-        payload: unknown;
-    }>;
-    emittedEvents: Array<{
-        event: string;
-        qualifiedEvent: string;
-        payload: unknown;
-    }>;
-    emittedGlobalEvents: Array<{
-        qualifiedEvent: string;
-        payload: unknown;
-    }>;
-    openUrl: string[];
-    navigationRequests: OpenForgeNavigationRequest[];
-    notify: NotificationRequest[];
-    taskCreations: CreateTaskRequest[];
-    startPromptContributionConfigurations: ConfigureStartPromptContributionRequest[];
-    taskImplementationStarts: StartTaskImplementationRequest[];
-    taskSummaryUpdates: Array<{
-        taskId: string;
-        summary: string;
-    }>;
-    taskStatusUpdates: Array<{
-        taskId: string;
-        status: string;
-    }>;
-    configWrites: Array<{
-        key: string;
-        value: JsonValue;
-        projectId: string | null;
-    }>;
-    fsWrites: Array<{
-        projectId: string;
-        path: string;
-        content: string;
-    }>;
-    shellSpawns: Array<{
-        taskId: string;
-        cwd: string;
-        cols: number;
-        rows: number;
-        terminalIndex: number;
-    }>;
-    shellWrites: Array<{
-        taskId: string;
-        terminalIndex: number;
-        data: string;
-    }>;
-    shellResizes: Array<{
-        taskId: string;
-        terminalIndex: number;
-        cols: number;
-        rows: number;
-    }>;
-    shellKills: Array<{
-        taskId: string;
-        terminalIndex: number;
-    }>;
-    shellBuffers: Array<{
-        taskId: string;
-        terminalIndex: number;
-    }>;
-    storageGets: Array<{
-        scope: TestingRuntimeScope;
-        scopeId: string | null;
-        key: string;
-    }>;
-    storageSets: Array<{
-        scope: TestingRuntimeScope;
-        scopeId: string | null;
-        key: string;
-        value: JsonValue;
-    }>;
-    storageDeletes: Array<{
-        scope: TestingRuntimeScope;
-        scopeId: string | null;
-        key: string;
-    }>;
-}
-export interface TestingContributionBase {
-    id: string;
-    qualifiedId: string;
-    pluginId: string;
-    projectId: string | null;
-}
-export type TestingCommandContribution = TestingContributionBase & CommandRegistration & {
-    title: string;
-    icon?: string;
-    shortcut?: CommandShortcutMetadata;
-    handler: CommandHandler;
-};
-export type TestingEventListenerContribution = TestingContributionBase & {
-    handler: EventHandler;
-    global: boolean;
-};
-export type TestingViewContribution = TestingContributionBase & PluginViewRegistration;
-export type TestingTaskPaneTabContribution = TestingContributionBase & PluginTaskPaneTabRegistration;
-export type TestingSettingsSectionContribution = TestingContributionBase & PluginSettingsSectionRegistration;
-export type TestingBackendMethodContribution = TestingContributionBase & {
-    registration: BackendMethodRegistration;
-};
-export type TestingBackgroundServiceContribution = TestingContributionBase & BackgroundServiceRegistration & {
-    started: boolean;
-};
-export interface TestingOpenForgeRegistrySnapshot {
-    pluginId: string;
-    projectId: string | null;
-    views: TestingViewContribution[];
-    taskPaneTabs: TestingTaskPaneTabContribution[];
-    settingsSections: TestingSettingsSectionContribution[];
-    commands: TestingCommandContribution[];
-    eventListeners: TestingEventListenerContribution[];
-    backendMethods: TestingBackendMethodContribution[];
-    backgroundServices: TestingBackgroundServiceContribution[];
-}
-export type MockFrontendOpenForgeAPI = FrontendOpenForgeAPI & {
-    readonly __testing: {
-        readonly calls: TestingOpenForgeApiCalls;
-        readonly registry: TestingOpenForgeRegistryFake;
-    };
-};
-export type MockBackendOpenForgeAPI = BackendOpenForgeAPI & {
-    readonly __testing: {
-        readonly calls: TestingOpenForgeApiCalls;
-        readonly registry: TestingOpenForgeRegistryFake;
-    };
-};
-export declare class TestingSubscriptionSink implements SubscriptionSink {
-    readonly subscriptions: Disposable[];
-    add(subscription: Disposable | (() => void)): void;
-    disposeAll(): Promise<void>;
-}
-export declare class TestingOpenForgeRegistryFake {
-    readonly pluginId: string;
-    readonly projectId: string | null;
-    readonly taskId: string | null;
-    readonly viewId: string;
-    readonly packageMetadata: OpenForgePackageMetadata;
-    readonly calls: TestingOpenForgeApiCalls;
-    readonly storage: PluginStorage;
-    readonly frontendSubscriptions: TestingSubscriptionSink;
-    readonly backendSubscriptions: TestingSubscriptionSink;
-    private readonly commands;
-    private readonly views;
-    private readonly taskPaneTabs;
-    private readonly settingsSections;
-    private readonly eventListeners;
-    private readonly eventHandlers;
-    private readonly backendMethods;
-    private readonly backgroundServices;
-    private readonly claimedIds;
-    private readonly config;
-    private eventListenerSequence;
-    private cachedFrontendApi;
-    private cachedBackendApi;
-    constructor(options?: TestingOpenForgeApiOptions);
-    get frontendApi(): MockFrontendOpenForgeAPI;
-    get backendApi(): MockBackendOpenForgeAPI;
-    get snapshot(): TestingOpenForgeRegistrySnapshot;
-    createFrontendApi(): MockFrontendOpenForgeAPI;
-    createBackendApi(): MockBackendOpenForgeAPI;
-    createFrontendContext(): FrontendPluginContext;
-    createBackendContext(): BackendPluginContext;
-    activateFrontend(plugin: FrontendPlugin): Promise<void>;
-    activateBackend(plugin: BackendPlugin): Promise<void>;
-    disposeAll(): Promise<void>;
-    getSnapshot(): TestingOpenForgeRegistrySnapshot;
-    private createContext;
-    private startPromptContributions;
-    private createCommonApi;
-    private getContextSnapshot;
-    private getNavigationSnapshot;
-    private localQualifiedId;
-    private claim;
-    private release;
-    private registerCommand;
-    private registerView;
-    private registerTaskPaneTab;
-    private registerSettingsSection;
-    private registerBackendMethod;
-    private registerBackgroundService;
-    private registerEventListener;
-    private startBackgroundServices;
-    private invokeCommand;
-    private invokeGlobalCommand;
-    private invokeBackend;
-    private emitEvent;
-}
-export declare function createOpenForgeRegistryFake(options?: TestingOpenForgeApiOptions): TestingOpenForgeRegistryFake;
-export declare function createMockOpenForgeApi(options?: TestingOpenForgeApiOptions): MockFrontendOpenForgeAPI;
-export declare function createMockFrontendOpenForgeApi(options?: TestingOpenForgeApiOptions): MockFrontendOpenForgeAPI;
-export declare function createMockBackendOpenForgeApi(options?: TestingOpenForgeApiOptions): MockBackendOpenForgeAPI;
-export declare function createMockPluginContext(options?: TestingOpenForgeApiOptions): FrontendPluginContext;
-export declare function createMemoryPluginStorage(calls?: TestingOpenForgeApiCalls): PluginStorage;
-export declare function createTestingCalls(): TestingOpenForgeApiCalls;
-export {};
+export { createMockBackendOpenForgeApi, createMockFrontendOpenForgeApi, createMockOpenForgeApi, createMockPluginContext, createOpenForgeRegistryFake, TestingOpenForgeRegistryFake, } from './testing/registryFake';
+export { createMemoryPluginStorage, createTestingCalls, TestingSubscriptionSink, } from './testing/support';
+export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingEventListenerContribution, TestingInjectionPointContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingTaskUISectionContribution, TestingViewContribution, } from './testing/contracts';