@openforge-app/plugin-sdk 0.2.3 → 0.2.4

package/README.md

@@ -1,6 +1,6 @@
 # @openforge-app/plugin-sdk
 
-Public SDK for building OpenForge plugins. See [`docs/plugin-authoring.md`](../../docs/plugin-authoring.md) for the complete package, runtime, Svelte-sharing, and CSS-loading contract.
+Public SDK for building OpenForge plugins. [`docs/plugin-authoring.md`](../../docs/plugin-authoring.md) is the canonical guide for the package, runtime, Svelte-sharing, and CSS-loading contract.
 
 Styled frontend plugins must declare Vite/Svelte's emitted CSS artifacts in `package.json#openforge.frontendStyles`:
 
@@ -24,9 +24,3 @@ Automated releases use npm trusted publishing rather than a long-lived npm token
 `@openforge-app/plugin-sdk` is licensed under the MIT License. Plugin authors may use it for personal, internal, open source, or commercial plugin development, including redistribution and modification under the MIT terms.
 
 This MIT license applies to the SDK package only. The OpenForge desktop application is licensed separately under the repository root `LICENSE` and is source-available/proprietary; the app may not be commercially resold or redistributed without permission.
-
-## Current contract
-
-Version `0.2.1` publishes the API-v1 contract used by the OpenForge host, including agent-facing Plugin Command metadata, `PluginCommandInvocationContext`, and the `@openforge-app/plugin-sdk/testing` helpers. Legacy handoff-summary declarations (`Task.summary` and `tasks.updateSummary`) are no longer part of the contract.
-
-Desktop releases publish the SDK in the same workflow using the desktop git tag's semver; the manual publish workflow uses the checked-in package version. Both paths run `pnpm check:contract`, which packs the package, verifies all exported files, and compiles the current authoring contract against the tarball before publication.

package/dist/backend.d.ts

@@ -1,3 +1,3 @@
-import type { BackendMethodRegistration, BackendMethodRegistry, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, BackgroundServiceRegistry, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot } from './types';
+import type { BackendFileSystemAPI, BackendMethodRegistration, BackendMethodRegistry, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, BackgroundServiceRegistry, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadFileSystemAPI, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot } from './types';
 export declare function defineBackendPlugin<const TPlugin extends BackendPlugin>(plugin: TPlugin): TPlugin;
-export type { BackendMethodRegistration, BackendMethodRegistry, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, BackgroundServiceRegistry, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, };
+export type { BackendFileSystemAPI, BackendMethodRegistration, BackendMethodRegistry, BackendOpenForgeAPI, BackendPlugin, BackendPluginContext, BackgroundServiceRegistration, BackgroundServiceRegistry, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadFileSystemAPI, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, };

package/dist/frontend.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSurfaceVisualFeedback, BrowserSurfaceRegion, BrowserSurfaceErrorCode, BrowserSurfaceNavigationError, BrowserSurfacesAPI, GetOrCreateBrowserSurfaceRequest, TaskBrowserSurfaceController, TaskBrowserSurfaceState } from './browserSurfaces';
-import type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol } from './types';
+import type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, PtyBufferState, TerminalImageProtocol } from './types';
 export declare const OPENFORGE_FRONTEND_PLUGIN_MARKER = "__openforgeFrontendPlugin";
 export type MarkedFrontendPlugin<TPlugin extends FrontendPlugin = FrontendPlugin> = TPlugin & {
     readonly [OPENFORGE_FRONTEND_PLUGIN_MARKER]: true;
@@ -7,4 +7,4 @@ export type MarkedFrontendPlugin<TPlugin extends FrontendPlugin = FrontendPlugin
 export declare function defineFrontendPlugin<const TPlugin extends FrontendPlugin>(plugin: TPlugin): MarkedFrontendPlugin<TPlugin>;
 export { BrowserSurfaceError, isAllowedBrowserSurfaceUrl } from './browserSurfaces';
 export type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSurfaceVisualFeedback, BrowserSurfaceRegion, BrowserSurfaceErrorCode, BrowserSurfaceNavigationError, BrowserSurfacesAPI, GetOrCreateBrowserSurfaceRequest, TaskBrowserSurfaceController, TaskBrowserSurfaceState, };
-export type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, };
+export type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, PtyBufferState, TerminalImageProtocol, };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSur
 export { OPENFORGE_PACKAGE_METADATA_SCHEMA, OPENFORGE_PLUGIN_CAPABILITIES, isOpenForgePackageMetadata, isPluginPackageMetadata, isSupportedOpenForgeApiVersion, validateOpenForgePackageMetadata, validatePluginPackageMetadata, } from './manifest';
 export { createMemoryPluginStorage, createMockBackendOpenForgeApi, createMockFrontendOpenForgeApi, createMockOpenForgeApi, createMockPluginContext, createOpenForgeRegistryFake, createTestingCalls, TestingOpenForgeRegistryFake, TestingSubscriptionSink, } from './testing';
 export { TaskFollowUpError, MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, makePluginViewKey, parsePluginViewKey, } from './types';
-export type { AgentCommandDescriptor, AgentCommandMetadata, AgentCommandRuntime, AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, FileSystemAPI, ImplementationRun, InjectionPointLocation, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginCommandInvocationContext, PluginCommandInvocationSource, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginIcon, PluginInjectionPointProps, PluginSettingsSectionProps, PluginState, PluginSvgIcon, PluginTaskPaneProps, PluginTaskUISectionProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, ShellAPI, ShellResizeRequest, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskFollowUpDisposition, TaskFollowUpErrorCode, TaskFollowUpReceipt, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, TasksAPI, ValidationError, } from './types';
+export type { AgentCommandDescriptor, AgentCommandMetadata, AgentCommandRuntime, AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, BackendFileSystemAPI, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadFileSystemAPI, FileSystemAPI, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, ImplementationRun, InjectionPointLocation, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginCommandInvocationContext, PluginCommandInvocationSource, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginSettingsSectionProps, PluginState, PluginSvgIcon, PluginTaskPaneProps, PluginTaskUISectionProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, PtyBufferState, ShellAPI, ShellResizeRequest, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskFollowUpDisposition, TaskFollowUpErrorCode, TaskFollowUpReceipt, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, TasksAPI, ValidationError, } from './types';
 export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingEventListenerContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingTaskUISectionContribution, TestingViewContribution, } from './testing';
 export { parseStrictFiniteNumber } from './numberParsing';
 export { buildProjectFileTree, flattenVisibleProjectFileTree, formatProjectFileTreeSize, getProjectFileTreeDepth, getProjectFileTreeItemAccessibility, getProjectFileTreeKeyboardAction, getProjectFileTreeParentPath, hasProjectFileTreeShortcutModifier, projectFileTreePathToId, } from './projectFileTree';

package/dist/manifest.d.ts

@@ -11,7 +11,7 @@ export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
     dependentRequired: {
         frontendStyles: string[];
     };
-    allOf: {
+    allOf: ({
         if: {
             properties: {
                 requires: {
@@ -19,13 +19,35 @@ export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
                         const: string;
                     };
                 };
+                enablement?: undefined;
             };
             required: string[];
         };
         then: {
             required: string[];
+            properties?: undefined;
         };
-    }[];
+    } | {
+        if: {
+            properties: {
+                enablement: {
+                    const: string;
+                };
+                requires?: undefined;
+            };
+            required: string[];
+        };
+        then: {
+            properties: {
+                requires: {
+                    contains: {
+                        const: string;
+                    };
+                };
+            };
+            required: string[];
+        };
+    })[];
     properties: {
         id: {
             type: string;
@@ -44,9 +66,36 @@ export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
             type: string;
             minLength: number;
         };
+        enablement: {
+            enum: string[];
+            default: string;
+            description: string;
+        };
         icon: {
-            type: string;
-            minLength: number;
+            oneOf: ({
+                type: string;
+                minLength: number;
+                pattern: string;
+                additionalProperties?: undefined;
+                required?: undefined;
+                properties?: undefined;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    type: {
+                        const: string;
+                    };
+                    svg: {
+                        type: string;
+                        minLength: number;
+                        pattern: string;
+                    };
+                };
+                minLength?: undefined;
+                pattern?: undefined;
+            })[];
             description: string;
         };
         frontend: {

package/dist/manifest.js

@@ -1,4 +1,5 @@
 import packageMetadataSchemaData from './openforgePackageMetadataSchema.json';
+import { isPluginIconName, isPluginSvgIcon } from './pluginIconContract';
 import { SUPPORTED_OPENFORGE_API_VERSIONS } from './types';
 export const OPENFORGE_PACKAGE_METADATA_SCHEMA = packageMetadataSchemaData;
 export const OPENFORGE_PLUGIN_CAPABILITIES = packageMetadataSchemaData.properties.requires.items.enum;
@@ -27,6 +28,18 @@ function validateOptionalString(value, path) {
     }
     return [];
 }
+function validateEnablement(value) {
+    if (value === undefined || value === 'app' || value === 'project') {
+        return [];
+    }
+    return [{ path: 'enablement', message: 'Must be "app" or "project"' }];
+}
+function validatePluginIcon(value) {
+    if (value === undefined || isPluginIconName(value) || isPluginSvgIcon(value)) {
+        return [];
+    }
+    return [{ path: 'icon', message: 'Must be a non-empty Lucide icon name or { type: "svg", svg }' }];
+}
 function validateFrontendStyles(value) {
     if (value === undefined)
         return [];
@@ -97,7 +110,8 @@ export function validateOpenForgePackageMetadata(data) {
     errors.push(...validateApiVersion(data.apiVersion));
     errors.push(...validateRequiredString(data.displayName, 'displayName'));
     errors.push(...validateRequiredString(data.description, 'description'));
-    errors.push(...validateOptionalString(data.icon, 'icon'));
+    errors.push(...validateEnablement(data.enablement));
+    errors.push(...validatePluginIcon(data.icon));
     errors.push(...validateOptionalString(data.frontend, 'frontend'));
     errors.push(...validateFrontendStyles(data.frontendStyles));
     if (data.frontendStyles !== undefined && !isNonEmptyString(data.frontend)) {
@@ -105,6 +119,9 @@ export function validateOpenForgePackageMetadata(data) {
     }
     errors.push(...validateOptionalString(data.backend, 'backend'));
     errors.push(...validateRequires(data.requires));
+    if (data.enablement === 'app' && (!Array.isArray(data.requires) || !data.requires.includes('appEnablement'))) {
+        errors.push({ path: 'requires', message: 'App enablement requires the appEnablement capability' });
+    }
     if (Array.isArray(data.requires) && data.requires.includes('browserSurfaces') && !isNonEmptyString(data.frontend)) {
         errors.push({ path: 'requires', message: 'browserSurfaces capability requires a frontend entry' });
     }

package/dist/openforgePackageMetadataSchema.json

@@ -27,6 +27,18 @@
                 "required": ["requires"]
             },
             "then": { "required": ["frontend"] }
+        },
+        {
+            "if": {
+                "properties": { "enablement": { "const": "app" } },
+                "required": ["enablement"]
+            },
+            "then": {
+                "properties": {
+                    "requires": { "contains": { "const": "appEnablement" } }
+                },
+                "required": ["requires"]
+            }
         }
     ],
     "properties": {
@@ -47,10 +59,33 @@
             "type": "string",
             "minLength": 1
         },
+        "enablement": {
+            "enum": ["app", "project"],
+            "default": "project",
+            "description": "Lifecycle ownership for this plugin package. Omission means project-owned enablement."
+        },
         "icon": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Semantic OpenForge icon key or package asset reference."
+            "oneOf": [
+                {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S"
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "svg"],
+                    "properties": {
+                        "type": { "const": "svg" },
+                        "svg": {
+                            "type": "string",
+                            "minLength": 1,
+                            "pattern": "\\S"
+                        }
+                    }
+                }
+            ],
+            "description": "Lucide icon name in kebab-case or inline SVG geometry using the PluginIcon contract."
         },
         "frontend": {
             "type": "string",
@@ -101,7 +136,9 @@
                     "config",
                     "projectConfig",
                     "browserSurfaces",
-                    "taskLinks"
+                    "taskLinks",
+                    "appEnablement",
+                    "customSidebarNavigation"
                 ]
             }
         }

package/dist/pluginIconContract.d.ts

@@ -0,0 +1,3 @@
+import type { PluginSvgIcon } from './types';
+export declare function isPluginIconName(value: unknown): value is string;
+export declare function isPluginSvgIcon(value: unknown): value is PluginSvgIcon;

package/dist/pluginIconContract.js

@@ -0,0 +1,12 @@
+export function isPluginIconName(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function isPluginSvgIcon(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const icon = value;
+    return Object.keys(icon).length === 2
+        && icon.type === 'svg'
+        && typeof icon.svg === 'string'
+        && icon.svg.trim().length > 0;
+}

package/dist/pluginIcons.js

@@ -1,4 +1,5 @@
 import DOMPurify from 'dompurify';
+import { isPluginSvgIcon } from './pluginIconContract';
 export const MAX_PLUGIN_SVG_ICON_CHARACTERS = 10_000;
 const ALLOWED_SVG_TAGS = ['svg', 'g', 'path', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon'];
 const ALLOWED_SVG_ATTRIBUTES = [
@@ -33,12 +34,6 @@ const ALLOWED_SVG_ATTRIBUTES = [
     'points',
 ];
 const SAFE_PAINT_VALUE = /^(?:none|currentColor|transparent|#[0-9a-f]{3,8}|[a-z]+|(?:rgb|rgba|hsl|hsla)\([\d\s.,%+\-/]+\))$/iu;
-function isPluginSvgIcon(value) {
-    return value !== null
-        && typeof value === 'object'
-        && value.type === 'svg'
-        && typeof value.svg === 'string';
-}
 function parseSvgRoot(markup) {
     const template = document.createElement('template');
     template.innerHTML = markup.trim();

package/dist/publicUiExports.mjs

@@ -8,6 +8,7 @@ const PUBLIC_UI_COMPONENT_NAMES = Object.freeze([
   'Modal',
   'PluginPageHeader',
   'PluginViewState',
+  'PluginSidebarLink',
   'FileTypeIcon',
 ])
 

package/dist/testing/commonApiFake.d.ts

@@ -1,4 +1,4 @@
-import type { FrontendOpenForgeAPI, OpenForgeCommonAPI } from '../types';
+import type { BackendOpenForgeAPI, FrontendOpenForgeAPI, OpenForgeCommonAPI } from '../types';
 import { type TestingRegistryServices } from './support';
 import type { TestingCommandContribution, TestingEventListenerContribution } from './contracts';
 export type TestingCommonApi = OpenForgeCommonAPI & Pick<FrontendOpenForgeAPI, 'navigation'>;
@@ -10,6 +10,7 @@ export declare class TestingCommonApiFake {
     private eventListenerSequence;
     constructor(services: TestingRegistryServices);
     createApi(): TestingCommonApi;
+    createBackendApi(): TestingCommonApi & Pick<BackendOpenForgeAPI, 'fs'>;
     getSnapshot(): {
         commands: TestingCommandContribution[];
         eventListeners: TestingEventListenerContribution[];

package/dist/testing/commonApiFake.js

@@ -136,7 +136,7 @@ export class TestingCommonApiFake {
                 },
                 getBuffer: async (request) => {
                     this.services.calls.shellBuffers.push(request);
-                    return null;
+                    return { buffer: null, isLive: false };
                 },
             },
             notifications: {
@@ -183,6 +183,38 @@ export class TestingCommonApiFake {
         };
         return api;
     }
+    createBackendApi() {
+        const api = this.createApi();
+        return {
+            ...api,
+            fs: {
+                ...api.fs,
+                userData: {
+                    readDir: async (request = {}) => {
+                        this.services.calls.fsUserDataReadDirs.push(request);
+                        return [];
+                    },
+                    readTextFile: async (request) => {
+                        this.services.calls.fsUserDataReads.push(request);
+                        return '';
+                    },
+                    writeTextFile: async (request) => {
+                        this.services.calls.fsUserDataWrites.push(request);
+                    },
+                },
+                external: {
+                    readDir: async (request) => {
+                        this.services.calls.fsExternalReadDirs.push(request);
+                        return [];
+                    },
+                    readTextFile: async (request) => {
+                        this.services.calls.fsExternalReads.push(request);
+                        return '';
+                    },
+                },
+            },
+        };
+    }
     getSnapshot() {
         return {
             commands: Array.from(this.commands.values()),

package/dist/testing/contracts.d.ts

@@ -1,6 +1,6 @@
 import type { BrowserSurfaceVisualFeedback } from '../browserSurfaces';
 import type { TestingOpenForgeRegistryFake } from './registryFake';
-import type { BackendMethodRegistration, BackendOpenForgeAPI, BackgroundServiceRegistration, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ConfigureStartPromptContributionRequest, CreateTaskRequest, FrontendOpenForgeAPI, InjectionPointLocation, JsonValue, NotificationRequest, OpenForgeNavigationRequest, OpenForgePackageMetadata, PluginSettingsSectionRegistration, PluginStorage, PluginTaskPaneTabRegistration, PluginTaskUISectionRegistration, PluginViewRegistration, ShellSpawnRequest, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskLinkOpenRequest, TaskStartPrefixContext } from '../types';
+import type { BackendMethodRegistration, BackendOpenForgeAPI, BackgroundServiceRegistration, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ConfigureStartPromptContributionRequest, CreateTaskRequest, FrontendOpenForgeAPI, InjectionPointLocation, JsonValue, NotificationRequest, OpenForgeNavigationRequest, OpenForgePackageMetadata, PluginSettingsSectionRegistration, PluginStorage, PluginTaskPaneTabRegistration, PluginTaskUISectionRegistration, PluginViewRegistration, ShellSpawnRequest, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskLinkOpenRequest, TaskStartPrefixContext, ExternalReadDirectoryRequest, ExternalReadFileRequest, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileWriteRequest } from '../types';
 import type { Task } from '../domain';
 export type TestingRuntimeScope = 'global' | 'project' | 'task';
 export type TestingRuntimeKind = 'commands' | 'events' | 'views' | 'taskPane' | 'taskUI' | 'settings' | 'backend' | 'background';
@@ -74,6 +74,11 @@ export interface TestingOpenForgeApiCalls {
         path: string;
         content: string;
     }>;
+    fsUserDataReadDirs: UserDataDirectoryRequest[];
+    fsUserDataReads: UserDataFileRequest[];
+    fsUserDataWrites: UserDataFileWriteRequest[];
+    fsExternalReadDirs: ExternalReadDirectoryRequest[];
+    fsExternalReads: ExternalReadFileRequest[];
     shellSpawns: ShellSpawnRequest[];
     shellWrites: Array<{
         taskId: string;

package/dist/testing/frontendContributionFake.js

@@ -102,6 +102,15 @@ export class TestingFrontendContributionFake {
         const qualifiedId = this.services.localQualifiedId('views', registration.id);
         assertTitle('views', registration.title);
         assertFunction('views', 'component', registration.component);
+        if (registration.navigationComponent !== undefined) {
+            assertFunction('views', 'navigationComponent', registration.navigationComponent);
+            if (registration.placement !== 'sidebar') {
+                throw new Error('views registration custom navigation requires sidebar placement');
+            }
+            if (!this.services.packageMetadata.requires?.includes('customSidebarNavigation')) {
+                throw new Error('views registration custom navigation requires the customSidebarNavigation capability');
+            }
+        }
         this.services.claims.claim('views', qualifiedId);
         const contribution = {
             ...registration,

package/dist/testing/registryFake.js

@@ -58,7 +58,7 @@ export class TestingOpenForgeRegistryFake {
         if (this.cachedBackendApi)
             return this.cachedBackendApi;
         const api = {
-            ...this.commonApi.createApi(),
+            ...this.commonApi.createBackendApi(),
             ...this.backendServices.createApi(),
             __testing: {
                 calls: this.calls,

package/dist/testing/support.js

@@ -48,6 +48,11 @@ export function createTestingCalls() {
         taskStatusUpdates: [],
         configWrites: [],
         fsWrites: [],
+        fsUserDataReadDirs: [],
+        fsUserDataReads: [],
+        fsUserDataWrites: [],
+        fsExternalReadDirs: [],
+        fsExternalReads: [],
         shellSpawns: [],
         shellWrites: [],
         shellResizes: [],

package/dist/types.d.ts

@@ -17,13 +17,16 @@ export interface ValidationError {
     path: string;
     message: string;
 }
-export type OpenForgePluginCapability = 'commands' | 'events' | 'views' | 'taskPane' | 'taskStart' | 'settings' | 'background' | 'backend' | 'storage' | 'context' | 'navigation' | 'tasks' | 'projects' | 'fs' | 'shell' | 'notifications' | 'attention' | 'system.openUrl' | 'system.writeClipboardText' | 'config' | 'projectConfig' | 'browserSurfaces' | 'taskLinks';
+declare const OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS: readonly ["commands", "events", "views", "injectionPoints", "taskPane", "taskStart", "settings", "background", "backend", "storage", "context", "navigation", "tasks", "projects", "fs", "shell", "notifications", "attention", "system.openUrl", "system.writeClipboardText", "config", "projectConfig", "browserSurfaces", "taskLinks", "appEnablement", "customSidebarNavigation"];
+export type OpenForgePluginCapability = (typeof OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS)[number];
 export interface OpenForgePackageMetadata {
     id: string;
     apiVersion: SupportedOpenForgeApiVersion;
     displayName: string;
     description: string;
-    icon?: string;
+    /** Defaults to project-owned lifecycle when omitted. */
+    enablement?: 'app' | 'project';
+    icon?: PluginIcon;
     frontend?: string;
     frontendStyles?: string[];
     backend?: string;
@@ -188,6 +191,21 @@ export interface PluginViewProps extends Record<string, unknown> {
     api: FrontendOpenForgeAPI;
     context: OpenForgeContextSnapshot;
 }
+export interface PluginSidebarViewIdentity {
+    pluginId: string;
+    id: string;
+    qualifiedId: string;
+    title: string;
+    icon: PluginIcon;
+}
+export interface PluginSidebarNavigationProps extends Record<string, unknown> {
+    api: FrontendOpenForgeAPI;
+    context: OpenForgeContextSnapshot;
+    active: boolean;
+    collapsed: boolean;
+    view: PluginSidebarViewIdentity;
+    onActivate: () => void;
+}
 export interface PluginTaskPaneProps extends Record<string, unknown> {
     api: FrontendOpenForgeAPI;
     context: OpenForgeContextSnapshot;
@@ -230,6 +248,8 @@ export interface PluginViewRegistration {
     order?: number;
     shortcut?: string;
     component: PluginComponentLoader<PluginViewProps> | PluginComponent<PluginViewProps>;
+    /** Custom content for a sidebar-placed View's host-owned navigation slot. */
+    navigationComponent?: PluginComponentLoader<PluginSidebarNavigationProps> | PluginComponent<PluginSidebarNavigationProps>;
 }
 export interface PluginTaskPaneTabRegistration {
     id: string;
@@ -353,6 +373,36 @@ export interface FileSystemAPI {
         limit?: number;
     }): Promise<string[]>;
 }
+export interface UserDataDirectoryRequest {
+    path?: string | null;
+}
+export interface UserDataFileRequest {
+    path: string;
+}
+export interface UserDataFileWriteRequest extends UserDataFileRequest {
+    content: string;
+}
+export interface ExternalReadDirectoryRequest {
+    root: string;
+    path?: string | null;
+}
+export interface ExternalReadFileRequest {
+    root: string;
+    path: string;
+}
+export interface UserDataFileSystemAPI {
+    readDir(request?: UserDataDirectoryRequest): Promise<FileEntry[]>;
+    readTextFile(request: UserDataFileRequest): Promise<string>;
+    writeTextFile(request: UserDataFileWriteRequest): Promise<void>;
+}
+export interface ExternalReadFileSystemAPI {
+    readDir(request: ExternalReadDirectoryRequest): Promise<FileEntry[]>;
+    readTextFile(request: ExternalReadFileRequest): Promise<string>;
+}
+export interface BackendFileSystemAPI extends FileSystemAPI {
+    userData: UserDataFileSystemAPI;
+    external: ExternalReadFileSystemAPI;
+}
 export type TerminalImageProtocol = 'iterm2';
 export interface ShellSessionRequest {
     taskId: string;
@@ -371,12 +421,16 @@ export interface ShellResizeRequest extends ShellSessionRequest {
     cols: number;
     rows: number;
 }
+export interface PtyBufferState {
+    buffer: string | null;
+    isLive: boolean;
+}
 export interface ShellAPI {
     spawn(request: ShellSpawnRequest): Promise<number>;
     write(request: ShellWriteRequest): Promise<void>;
     resize(request: ShellResizeRequest): Promise<void>;
     kill(request: ShellSessionRequest): Promise<void>;
-    getBuffer(request: ShellSessionRequest): Promise<string | null>;
+    getBuffer(request: ShellSessionRequest): Promise<PtyBufferState>;
 }
 export interface CreateTaskRequest {
     initialPrompt: string;
@@ -518,6 +572,7 @@ export interface FrontendOpenForgeAPI extends OpenForgeCommonAPI {
     taskStart: FrontendTaskStartRegistry;
 }
 export interface BackendOpenForgeAPI extends OpenForgeCommonAPI {
+    fs: BackendFileSystemAPI;
     backend: BackendMethodRegistry;
     background: BackgroundServiceRegistry;
 }
@@ -534,3 +589,4 @@ export declare function parsePluginViewKey(key: PluginViewKey): {
     pluginId: string;
     viewId: string;
 };
+export {};

package/dist/types.js

@@ -10,6 +10,45 @@ export const SUPPORTED_OPENFORGE_API_VERSIONS = Object.freeze(readSupportedOpenF
 export const OPENFORGE_PLUGIN_API_VERSION = SUPPORTED_OPENFORGE_API_VERSIONS[0];
 export const MIN_SUPPORTED_API_VERSION = Math.min(...SUPPORTED_OPENFORGE_API_VERSIONS);
 export const MAX_SUPPORTED_API_VERSION = Math.max(...SUPPORTED_OPENFORGE_API_VERSIONS);
+const OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS = [
+    'commands',
+    'events',
+    'views',
+    'injectionPoints',
+    'taskPane',
+    'taskStart',
+    'settings',
+    'background',
+    'backend',
+    'storage',
+    'context',
+    'navigation',
+    'tasks',
+    'projects',
+    'fs',
+    'shell',
+    'notifications',
+    'attention',
+    'system.openUrl',
+    'system.writeClipboardText',
+    'config',
+    'projectConfig',
+    'browserSurfaces',
+    'taskLinks',
+    'appEnablement',
+    'customSidebarNavigation',
+];
+function assertOpenForgePluginCapabilitiesMatchSchema() {
+    const schemaCapabilities = packageMetadataSchemaData.properties.requires.items.enum;
+    if (!Array.isArray(schemaCapabilities) || !schemaCapabilities.every((capability) => typeof capability === 'string')) {
+        throw new Error('openforgePackageMetadataSchema.json properties.requires.items.enum must contain only strings');
+    }
+    if (schemaCapabilities.length !== OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS.length
+        || schemaCapabilities.some((capability, index) => capability !== OPENFORGE_PLUGIN_CAPABILITY_TYPE_MEMBERS[index])) {
+        throw new Error('OpenForgePluginCapability must match openforgePackageMetadataSchema.json properties.requires.items.enum');
+    }
+}
+assertOpenForgePluginCapabilitiesMatchSchema();
 export class TaskFollowUpError extends Error {
     code;
     constructor(code, message) {

package/dist/ui/PluginSidebarLink.svelte

@@ -0,0 +1,54 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte'
+
+  interface Props {
+    accessibleName: string
+    active: boolean
+    collapsed: boolean
+    onActivate: () => void
+    leading?: Snippet
+    label?: Snippet
+    trailing?: Snippet
+    class?: string
+  }
+
+  let {
+    accessibleName,
+    active,
+    collapsed,
+    onActivate,
+    leading,
+    label,
+    trailing,
+    class: className,
+  }: Props = $props()
+
+  function handleKeydown(event: KeyboardEvent): void {
+    if (event.key !== 'Enter' && event.key !== ' ') return
+    event.preventDefault()
+    onActivate()
+  }
+</script>
+
+<button
+  type="button"
+  class={[
+    'relative mx-2 flex min-h-11 w-auto items-center rounded-lg gap-3 py-2.5 cursor-pointer transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary',
+    collapsed ? 'justify-center px-0' : 'px-3',
+    active ? 'bg-primary/10 text-primary' : 'text-base-content/55 hover:bg-base-200 hover:text-base-content',
+    className,
+  ]}
+  title={collapsed ? accessibleName : undefined}
+  aria-label={accessibleName}
+  aria-current={active ? 'page' : undefined}
+  onclick={onActivate}
+  onkeydown={handleKeydown}
+>
+  {#if leading}
+    <span class="relative shrink-0">{@render leading()}</span>
+  {/if}
+  {#if !collapsed}
+    {#if label}<span class="min-w-0 text-sm font-medium">{@render label()}</span>{/if}
+    {#if trailing}<span class="ml-auto shrink-0">{@render trailing()}</span>{/if}
+  {/if}
+</button>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openforge-app/plugin-sdk",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -71,6 +71,7 @@
     "./ui/Modal.svelte": "./dist/ui/Modal.svelte",
     "./ui/PluginPageHeader.svelte": "./dist/ui/PluginPageHeader.svelte",
     "./ui/PluginViewState.svelte": "./dist/ui/PluginViewState.svelte",
+    "./ui/PluginSidebarLink.svelte": "./dist/ui/PluginSidebarLink.svelte",
     "./ui/FileTypeIcon.svelte": "./dist/ui/FileTypeIcon.svelte"
   },
   "files": [