@punica/editor 1.0.6 → 1.0.8

package/types/punica.module.extensions.api.d.ts

@@ -0,0 +1,766 @@
+declare module 'punica' {
+  export namespace Extensions {
+    interface BaseView {
+      id: string;
+      name: string;
+      title?: string;
+      label?: string;
+      icon?: string;
+      alignment?: 'primary' | 'secondary';
+      content?: HTMLElement;
+      /**
+       * Capability id to execute when the view is activated.
+       * For activity bar items this will be invoked when the icon is clicked.
+       */
+      capability?: string;
+    }
+
+    /**
+     * A single icon-button action shown in the panel tab bar's toolbar
+     * area while the owning view is the active panel view. Clicking the
+     * button dispatches `command` through the kernel command manager
+     * (the single command choke point — lazy-activates the owning
+     * extension when needed).
+     */
+    interface PanelToolbarAction {
+      /** Unique within the owning view. */
+      id: string;
+      /** Tooltip / aria-label. */
+      title: string;
+      /** Raw HTML icon markup, e.g. '<i class="fa-solid fa-plus"></i>'. */
+      icon?: string;
+      /** Command id dispatched on click. */
+      command: string;
+    }
+
+    interface Views {
+      primarySidebar?: BaseView;
+      secondarySidebar?: BaseView;
+      /**
+       * Contextual detail drawer (overlay). TRANSIENT: its content is
+       * parameterized per open, so the shell re-renders the view's
+       * provider on every reveal, and hiding unmounts the drawer.
+       */
+      contentSidebar?: BaseView;
+      content?: BaseView;
+      /**
+       * Declarative bottom-panel tab. The tab appears in the panel tab
+       * strip at load time (like activity bar items); content renders
+       * only on reveal — via the extension's ViewProvider, or, for
+       * pre-migration extensions, via the bound `capability` command.
+       */
+      panel?: BaseView & {
+        order?: number;
+        /**
+         * Toolbar actions rendered in the panel tab bar's right-side
+         * toolbar area, visible only while this view is the active
+         * panel view. Ignored by older cores.
+         */
+        toolbar?: PanelToolbarAction[];
+      };
+      activityBar?: Pick<BaseView, 'id' | 'name'> &
+        Required<Pick<BaseView, 'title' | 'icon' | 'alignment'>>;
+      statusBar?: Pick<BaseView, 'id' | 'name'> &
+        Required<Pick<BaseView, 'title' | 'label' | 'icon' | 'alignment'>>;
+    }
+
+    interface Command {
+      command: string;
+      title: string;
+    }
+
+    interface Keybinding {
+      /**
+       * Capability id to execute when the keybinding is triggered.
+       */
+      capability?: string;
+      key: string;
+      when: string;
+    }
+
+    interface MenuItem {
+      /**
+       * Capability id to execute when the menu item is selected.
+       */
+      capability?: string;
+      when: string;
+      group: string;
+    }
+
+    interface Menu {
+      commandPalette: MenuItem;
+      context: MenuItem;
+    }
+
+    interface BooleanProperty {
+      type: 'boolean';
+      default: boolean;
+      description: string;
+    }
+
+    interface StringProperty {
+      type: 'string';
+      default: string;
+      description: string;
+      enum?: string[];
+    }
+
+    interface NumberProperty {
+      type: 'number';
+      default: number;
+      description: string;
+    }
+
+    interface ArrayProperty {
+      type: 'array';
+      default: any[];
+      description: string;
+      items: any;
+    }
+
+    interface ObjectProperty {
+      type: 'object';
+      default: { [key: string]: any };
+      description: string;
+      properties: { [key: string]: Property };
+    }
+
+    type Property =
+      | BooleanProperty
+      | StringProperty
+      | NumberProperty
+      | ArrayProperty
+      | ObjectProperty;
+
+    interface Configuration {
+      title: string;
+      properties: {
+        [key: string]: Property;
+      };
+    }
+
+    interface MarketplaceScreenshot {
+      path: string;
+      label?: string;
+    }
+
+    interface MarketplacePermissions {
+      fs?: 'none' | 'read-only' | 'read-write';
+      network?: 'none' | 'limited' | 'full';
+      kernels?: string[];
+    }
+
+    interface MarketplaceMeta {
+      /**
+       * Relative path to the primary icon for this extension (used in
+       * marketplace listings and, when appropriate, activity bar).
+       */
+      icon?: string;
+      /**
+       * Optional banner / hero image shown on the extension detail page.
+       */
+      banner?: string;
+      /**
+       * Relative path to the README file that describes this extension in
+       * more detail. Typically "README.md" at the extension root.
+       */
+      readmePath?: string;
+      /**
+       * Optional path to a changelog file.
+       */
+      changelogPath?: string;
+      /**
+       * Publisher / owner identifier for this extension (e.g. "ivyx").
+       */
+      publisher?: string;
+      /**
+       * Homepage or marketing site for this extension.
+       */
+      homepage?: string;
+      /**
+       * Repository URL for the extension source code.
+       */
+      repository?: string;
+      /**
+       * Optional screenshots shown on the detail page.
+       */
+      screenshots?: MarketplaceScreenshot[];
+      /**
+       * High-level capabilities / tags used for discovery and filtering
+       * in the marketplace (e.g. "flow", "ai-assistant", "notebook").
+       */
+      capabilities?: string[];
+      /**
+       * Declared permissions for this extension. This is advisory metadata
+       * that helps users understand what the extension might access.
+       */
+      permissions?: MarketplacePermissions;
+      /**
+       * Target platforms / hosts supported by this extension, such as
+       * "browser", "electron", or "server".
+       */
+      platforms?: string[];
+      /**
+       * Optional base URL for this extension module on a marketplace or
+       * extension gallery. When provided, hosts or managers can call
+       * Extensions.manager.load(moduleURL) to install/activate it.
+       */
+      moduleURL?: string;
+    }
+
+    interface FileOpenerIntegration {
+      /**
+       * Capability id to execute when a matching file is opened.
+       */
+      capability?: string;
+      priority?: number;
+      matches?: Runtime.FileMatch[];
+      id?: string;
+    }
+
+    /**
+     * Extension capability definition — same unified shape as module-level
+     * {@link CapabilityDefinition}. Alias (not `extends CapabilityDefinition`
+     * inside this namespace) avoids a self-referential empty interface.
+     *
+     * Extensions declare these in `.punica/capabilities.yaml` using JSON Schema
+     * for inputs/outputs.
+     */
+    type CapabilityDefinition = import('punica').CapabilityDefinition;
+
+    /**
+     * Extension activation lifecycle events.
+     *
+     * - `onStartup` / `onStartup:begin`:
+     *    For extensions that should run early during editor startup,
+     *    after the core systems and layout/render have been initialized.
+     * - `onStartup:finish`:
+     *    For heavy or background work that should start only after
+     *    the UI + workspace are fully ready / idle (deferred startup).
+     * - `onCommand:<commandId>`:
+     *    Activates the extension the first time the given command is executed.
+     * - `onExtension:<extensionName>`:
+     *    Triggers when another extension is activated.
+     * - `onView:<viewId>`:
+     *    Activates the extension when a specific view (e.g. sidebar/content)
+     *    is shown for the first time.
+     *
+     * Other custom activation events are supported as generic strings,
+     * but the ones above define the official, documented lifecycle flow.
+     */
+    type ActivationEvent =
+      | 'onStartup'
+      | 'onStartup:begin'
+      | 'onStartup:finish'
+      | `onCommand:${string}`
+      | `onExtension:${string}`
+      | `onView:${string}`
+      | (string & {});
+
+    interface Integrations {
+      keybindings?: Keybinding[];
+      menus?: Menu;
+      views?: Views;
+      configuration?: Configuration;
+      fileOpeners?: FileOpenerIntegration[];
+    }
+
+    interface Extension {
+      module: Extensions.IExtension;
+      moduleURL: string;
+      name: string;
+      displayName: string;
+      description: string;
+      version: string;
+      main: string;
+      categories?: string[];
+      tags?: string[];
+      activationEvents?: ActivationEvent[];
+      dependOns?: string[];
+      integrations: Integrations;
+      /**
+       * When true, the Reader loads `.punica/capabilities.yaml` and populates
+       * `capabilities`. Absent/false ⇒ the file is never fetched, so extensions
+       * that expose no gateway capabilities don't trigger a speculative 404.
+       */
+      hasCapabilities?: boolean;
+      /**
+       * Optional capabilities registry loaded from `.punica/capabilities.yaml`.
+       * Keys are capability ids. Populated by the Reader only when
+       * `hasCapabilities` is declared in config.yaml.
+       */
+      capabilities?: Record<string, CapabilityDefinition>;
+      /**
+       * Instruction classes loaded from `.punica/instruction-classes/*.ic.yaml`.
+       * Populated by the Reader during analysis phase; auto-registered into
+       * the kernel instructionClassRegistry by the extension manager.
+       */
+      instructionClasses?: kernel.llm.InstructionClass[];
+      engines: {
+        punica: string;
+      };
+      marketplace?: MarketplaceMeta;
+    }
+
+    interface ExtensionDecorator {
+      execute(): Promise<Extension>;
+    }
+
+    /**
+     * Extension runtime state — dimension A of the lifecycle model.
+     * Contains NO UI/visibility state: whether an extension runs as a
+     * service and whether its views are shown are orthogonal. View
+     * presentation state lives in `punica.shell.Views.manager`, per view.
+     */
+    type ExtensionRuntimeState =
+      | 'loaded'
+      | 'activating'
+      | 'active'
+      | 'deactivating'
+      | 'failed';
+
+    /** Why an activation was requested. */
+    type ActivationReason =
+      | 'startup:begin'
+      | 'startup:finish'
+      | 'command'
+      | 'view'
+      | 'capability'
+      | 'extension'
+      | 'host';
+
+    interface ActivationOptions {
+      reason?: ActivationReason;
+      /** What triggered it: command id, capability id, viewId, extension name. */
+      trigger?: string;
+      /**
+       * 'headless': activation must not change focus-stealing UI state
+       * (derived for capability invocations). 'interactive': a
+       * user-visible flow. Derived from `reason` when omitted.
+       */
+      presentation?: 'interactive' | 'headless';
+    }
+
+    interface IExtensionContext {
+      /**
+       * Why this extension is being activated. `presentation:
+       * 'headless'` means a service caller (agent, MCP client, flow)
+       * triggered the activation — do not attempt to show UI; defer
+       * UI-adjacent warmup until a view is revealed.
+       */
+      activation: Readonly<{
+        reason: ActivationReason;
+        trigger?: string;
+        presentation: 'interactive' | 'headless';
+      }>;
+
+      /**
+       * Disposal bag: everything pushed here is disposed by
+       * `punica.extensions.manager.deactivate(name)`.
+       */
+      subscriptions: Array<{ dispose(): void }>;
+
+      /**
+       * Capability API available during extension activation.
+       *
+       * Call `registerHandler` for each capability declared in
+       * `.punica/capabilities.yaml` that you want to make
+       * gateway-invocable. The gateway will invoke the handler after
+       * the full 13-stage middleware pipeline runs (policy, audit, etc.).
+       *
+       * Example:
+       * ```ts
+       * async activate(context) {
+       *   context.capabilities.registerHandler('myext.doThing', async (input, ctx) => {
+       *     return { result: 'ok' };
+       *   });
+       * }
+       * ```
+       */
+      capabilities: {
+        /** Register an execution handler for a capability declared by this extension. */
+        registerHandler(
+          capabilityId: string,
+          handler: (input: unknown, ctx: unknown) => Promise<unknown>
+        ): void;
+      };
+
+      /**
+       * Declarative UI contribution API. Activation NEVER shows UI —
+       * register a provider and the shell materializes/renders it
+       * lazily on first reveal (user gesture or `shell.revealView`).
+       */
+      ui: {
+        /**
+         * Register the render provider for a view declared in this
+         * extension's `integrations.views`. Registration alone never
+         * shows anything.
+         */
+        registerViewProvider(
+          viewId: string,
+          provider: shell.Views.ViewProvider
+        ): { dispose(): void };
+
+        /**
+         * Deliberate, audited reveal — a thin shortcut over the
+         * `shell.revealView` core capability (the substrate's single
+         * visibility mutator). Use sparingly: showing UI should almost
+         * always be the user's or the host's decision.
+         */
+        reveal(viewId: string, options?: { focus?: boolean }): Promise<void>;
+
+        /**
+         * Deliberate, audited hide — a thin shortcut over the
+         * `shell.hideView` core capability. The close affordance of
+         * transient views (the contentSidebar drawer's close button /
+         * Escape) goes through here, never through direct DOM removal.
+         */
+        hide(viewId: string): Promise<void>;
+      };
+    }
+
+    interface StyleHandle {
+      id: string;
+      dispose(): void;
+    }
+
+    interface StyleOptions {
+      /**
+       * Target element to append the <style> tag into. Defaults to document.head.
+       */
+      target?: HTMLElement;
+      /**
+       * When true, an existing style with the same id will be updated with the
+       * new CSS instead of being left untouched.
+       */
+      overwrite?: boolean;
+      /**
+       * Optional attributes applied to the created <style> element. Useful for
+       * debugging (e.g. data-extension="ivy-nodes").
+       */
+      attrs?: Record<string, string>;
+    }
+
+    /**
+     * Helper API for managing extension-scoped <style> tags.
+     *
+     * This is a lightweight utility; extensions remain free to manage styles
+     * however they like. Using this helper simply standardizes the common
+     * pattern of injecting CSS on activate() and cleaning it up on deactivate().
+     */
+    const Styles: {
+      /**
+       * Inject a CSS string as a <style> tag. Returns a handle that can be
+       * disposed to remove the style.
+       */
+      register(id: string, css: string, options?: StyleOptions): StyleHandle;
+
+      /**
+       * Remove a previously registered style by id. Safe to call multiple times.
+       */
+      unregister(id: string): void;
+
+      /**
+       * Check whether a style with the given id is currently registered.
+       */
+      has(id: string): boolean;
+    };
+
+    interface IExtension {
+      activate: (context: IExtensionContext) => Promise<void>;
+      deactivate: () => void;
+    }
+
+    interface IExtensionManager {
+      /**
+       * Load one or more extensions from URL or file path.
+       */
+      load(extensionPath: string, ...args: string[]): Promise<void>;
+
+      /**
+       * Activate a specific extension by name — start it as a running
+       * service. Activation never shows UI; visibility flows through
+       * the `shell.revealView` capability.
+       *
+       * Concurrent calls coalesce (single-flight). A failed activation
+       * records `failed` state and rethrows; a later call retries.
+       */
+      activate(
+        extensionName: string,
+        options?: ActivationOptions
+      ): Promise<void>;
+
+      /**
+       * Deactivate an extension: `active → deactivating → loaded`.
+       * Shell unmounts its rendered views (manifest placements stay),
+       * `module.deactivate()` runs, `context.subscriptions` are
+       * disposed and its capability handlers are removed. A later
+       * capability call re-activates headlessly.
+       */
+      deactivate(extensionName: string): Promise<void>;
+
+      /**
+       * Current runtime state of an extension, or undefined when not
+       * loaded.
+       */
+      getRuntimeState(extensionName: string): ExtensionRuntimeState | undefined;
+
+      /**
+       * Trigger activation of all extensions that declare `onStartup:begin`
+       * in their activationEvents.
+       */
+      startupBegin(): Promise<void>;
+
+      /**
+       * Trigger activation of all extensions that declare `onStartup:finish`
+       * in their activationEvents.
+       */
+      startupFinish(): Promise<void>;
+
+      /**
+       * Get loaded extension metadata by name.
+       */
+      getExtension(extensionName: string): Extension | undefined;
+
+      /**
+       * Return all loaded extensions metadata as an array. This is primarily
+       * used by the Extension Manager UI to list installed extensions.
+       */
+      getAllExtensions(): Extension[];
+
+      /**
+       * Return the list of extensions that declared `onCommand:<commandId>`
+       * activation events.
+       */
+      getExtensionsForCommand(commandId: string): string[];
+
+      /**
+       * Resolve a capability definition by id across all loaded extensions.
+       */
+      getCapability(capabilityId: string): CapabilityDefinition | undefined;
+
+      /**
+       * List all capabilities known to the extension manager.
+       */
+      listCapabilities(): Array<{
+        id: string;
+        extensionName: string;
+        definition: CapabilityDefinition;
+      }>;
+
+      /**
+       * Validate a capability input against its declared inputs schema.
+       * Early iterations may implement only minimal checks.
+       */
+      validateCapabilityInput(
+        capabilityId: string,
+        input: unknown
+      ): { ok: boolean; errors?: string[] };
+
+      /**
+       * Register a JS handler for an extension capability.
+       *
+       * Typically called internally via `context.capabilities.registerHandler`
+       * during extension activation. Exposed here for host/test access.
+       */
+      registerCapabilityHandler(
+        id: string,
+        handler: (input: unknown, ctx: unknown) => Promise<unknown>
+      ): void;
+
+      /**
+       * Execute an extension capability by id, routing through the
+       * registered handler. Called by the gateway's extension provider
+       * after the middleware pipeline.
+       *
+       * Lazily activates the owning extension if not yet active.
+       * Throws `CAPABILITY_HANDLER_MISSING` when the extension did not
+       * register a handler during activation.
+       */
+      executeCapability(
+        id: string,
+        input: unknown,
+        ctx: unknown
+      ): Promise<unknown>;
+
+      /**
+       * Register built-in capabilities that ship with the editor (virtual extension).
+       *
+       * This is intended for core capabilities like workspace/vcs/tasks that are
+       * always present without loading an external extension.
+       */
+      registerBuiltinCapabilities(
+        entries: Array<{
+          id: string;
+          extensionName: string;
+          definition: CapabilityDefinition;
+        }>
+      ): void;
+    }
+
+    const manager: IExtensionManager;
+
+    /**
+     * Readonly Extension Metadata API
+     */
+    namespace metadata {
+      export interface ReadonlyExtension {
+        readonly name: string;
+        readonly displayName?: string;
+        readonly description?: string;
+        readonly version: string;
+        readonly configuration?: Readonly<{
+          title: string;
+          properties: Readonly<
+            Record<string, ReadonlyExtensionSettingProperty>
+          >;
+        }>;
+        readonly capabilities?: Readonly<
+          Record<string, ReadonlyCapabilityDefinition>
+        >;
+      }
+
+      export interface ReadonlyExtensionSettingProperty {
+        readonly type: 'boolean' | 'string' | 'number';
+        readonly default?: unknown;
+        readonly description?: string;
+        readonly enum?: readonly string[];
+      }
+
+      export interface ReadonlyCapabilityDefinition {
+        readonly title?: string;
+        readonly description?: string;
+        readonly inputs?: Readonly<unknown>;
+        readonly outputs?: Readonly<unknown>;
+        readonly policy?: Readonly<unknown>;
+      }
+
+      export interface ExtensionMetadataApi {
+        /**
+         * Get readonly extension metadata by name
+         */
+        getExtension(extensionName: string): ReadonlyExtension | undefined;
+
+        /**
+         * Get all extensions as readonly array
+         */
+        getAllExtensions(): readonly ReadonlyExtension[];
+
+        /**
+         * Get readonly capabilities for an extension
+         */
+        getExtensionCapabilities(
+          extensionName: string
+        ): Readonly<Record<string, ReadonlyCapabilityDefinition>> | undefined;
+      }
+
+      /**
+       * Extension metadata manager façade surfaced via `punica.extensions.metadata.manager`.
+       */
+      export const manager: ExtensionMetadataApi;
+    }
+
+    /**
+     * Settings API for managing extension and system settings
+     */
+    namespace settings {
+      /**
+       * Settings manager façade surfaced via `punica.extensions.settings.manager`.
+       */
+      export const manager: extensions.settings.SettingsApi;
+    }
+  }
+
+  /**
+   * extensions: top-level extension system façade exposed as `punica.extensions`.
+   * This is a convenience alias around the existing Extensions namespace.
+   */
+  export namespace extensions {
+    export import Extension = Extensions.Extension;
+    export import ExtensionDecorator = Extensions.ExtensionDecorator;
+    export import IExtension = Extensions.IExtension;
+    export import IExtensionManager = Extensions.IExtensionManager;
+    export import IExtensionContext = Extensions.IExtensionContext;
+    export import Styles = Extensions.Styles;
+    /**
+     * Extension manager façade surfaced via `punica.extensions.manager`.
+     */
+    export const manager: Extensions.IExtensionManager;
+    export import MarketplaceMeta = Extensions.MarketplaceMeta;
+    export import ActivationEvent = Extensions.ActivationEvent;
+    export import ActivationOptions = Extensions.ActivationOptions;
+    export import ActivationReason = Extensions.ActivationReason;
+    export import ExtensionRuntimeState = Extensions.ExtensionRuntimeState;
+
+    /**
+     * Readonly Extension Metadata API
+     */
+    export namespace metadata {
+      export interface ReadonlyExtension {
+        readonly name: string;
+        readonly displayName?: string;
+        readonly description?: string;
+        readonly version: string;
+        readonly configuration?: Readonly<{
+          title: string;
+          properties: Readonly<
+            Record<string, ReadonlyExtensionSettingProperty>
+          >;
+        }>;
+        readonly capabilities?: Readonly<
+          Record<string, ReadonlyCapabilityDefinition>
+        >;
+      }
+
+      export interface ReadonlyExtensionSettingProperty {
+        readonly type: 'boolean' | 'string' | 'number';
+        readonly default?: unknown;
+        readonly description?: string;
+        readonly enum?: readonly string[];
+      }
+
+      export interface ReadonlyCapabilityDefinition {
+        readonly title?: string;
+        readonly description?: string;
+        readonly inputs?: Readonly<unknown>;
+        readonly outputs?: Readonly<unknown>;
+        readonly policy?: Readonly<unknown>;
+      }
+
+      export interface ExtensionMetadataApi {
+        /**
+         * Get readonly extension metadata by name
+         */
+        getExtension(extensionName: string): ReadonlyExtension | undefined;
+
+        /**
+         * Get all extensions as readonly array
+         */
+        getAllExtensions(): readonly ReadonlyExtension[];
+
+        /**
+         * Get readonly capabilities for an extension
+         */
+        getExtensionCapabilities(
+          extensionName: string
+        ): Readonly<Record<string, ReadonlyCapabilityDefinition>> | undefined;
+      }
+
+      /**
+       * Extension metadata manager façade surfaced via `punica.extensions.metadata.manager`.
+       */
+      export const manager: ExtensionMetadataApi;
+    }
+
+    /**
+     * Settings API for managing extension and system settings
+     */
+    export namespace settings {
+      export import SettingsApi = extensions.settings.SettingsApi;
+      /**
+       * Settings manager façade surfaced via `punica.extensions.settings.manager`.
+       */
+      export const manager: SettingsApi;
+    }
+  }
+}