@lapis-notes/api 0.1.0

package/dist/plugin-runtime-entry.d.ts

@@ -0,0 +1,19 @@
+import type { LapisPluginModuleFormat } from "./lapis-extension";
+import type { PluginManifest } from "./plugin";
+export type PluginExecutionHostId = "workspace" | "electron-renderer" | "electron-sidecar";
+export interface SelectedPluginRuntimeEntry {
+    host: PluginExecutionHostId;
+    path: string;
+    format: LapisPluginModuleFormat;
+    fallbackPath?: string;
+    sharedDependencies: string[];
+    requiresReloadOnUpdate?: boolean;
+    source: "lapis-runtime-entry" | "lapis-legacy-runtime" | "obsidian-main";
+}
+export declare function selectPluginRuntimeEntry(options: {
+    manifest: PluginManifest;
+    requestedHost: PluginExecutionHostId;
+    supportsEsm: boolean;
+    supportsNodeEsm: boolean;
+    hasMainJs: boolean;
+}): SelectedPluginRuntimeEntry | null;

package/dist/plugin-runtime-entry.js

@@ -0,0 +1,135 @@
+export function selectPluginRuntimeEntry(options) {
+    const lapis = isLapisRuntimeContainer(options.manifest.lapis)
+        ? options.manifest.lapis
+        : null;
+    const structuredEntry = lapis
+        ? selectStructuredEntry(lapis, options.requestedHost)
+        : null;
+    if (!lapis) {
+        if (!options.hasMainJs) {
+            return null;
+        }
+        return {
+            host: options.requestedHost,
+            path: "main.js",
+            format: "commonjs",
+            sharedDependencies: [],
+            source: "obsidian-main",
+        };
+    }
+    if (structuredEntry) {
+        return selectDescriptorEntry(structuredEntry, {
+            host: options.requestedHost,
+            supportsEsm: options.supportsEsm,
+            supportsNodeEsm: options.supportsNodeEsm,
+            sharedDependencies: structuredEntry.sharedDependencies ??
+                getSharedDependencyDefaults(lapis, options.requestedHost),
+        });
+    }
+    const legacyEntry = selectLegacyEntry(lapis, options.requestedHost);
+    if (legacyEntry) {
+        return {
+            host: options.requestedHost,
+            path: legacyEntry,
+            format: "commonjs",
+            sharedDependencies: getSharedDependencyDefaults(lapis, options.requestedHost),
+            source: "lapis-legacy-runtime",
+        };
+    }
+    if (options.hasMainJs) {
+        return {
+            host: options.requestedHost,
+            path: "main.js",
+            format: "commonjs",
+            sharedDependencies: getSharedDependencyDefaults(lapis, options.requestedHost),
+            source: "obsidian-main",
+        };
+    }
+    return null;
+}
+function selectDescriptorEntry(descriptor, options) {
+    if ((descriptor.format === "esm" && !options.supportsEsm) ||
+        (descriptor.format === "node-esm" && !options.supportsNodeEsm)) {
+        if (!descriptor.fallbackPath) {
+            return null;
+        }
+        return {
+            host: options.host,
+            path: descriptor.fallbackPath,
+            format: "commonjs",
+            fallbackPath: descriptor.fallbackPath,
+            sharedDependencies: options.sharedDependencies,
+            requiresReloadOnUpdate: descriptor.requiresReloadOnUpdate,
+            source: "lapis-runtime-entry",
+        };
+    }
+    return {
+        host: options.host,
+        path: descriptor.path,
+        format: descriptor.format,
+        fallbackPath: descriptor.fallbackPath,
+        sharedDependencies: options.sharedDependencies,
+        requiresReloadOnUpdate: descriptor.requiresReloadOnUpdate,
+        source: "lapis-runtime-entry",
+    };
+}
+function selectStructuredEntry(lapis, host) {
+    const entries = lapis.runtime?.entries;
+    if (!entries) {
+        return null;
+    }
+    switch (host) {
+        case "electron-renderer":
+            return entries.electronRenderer ?? entries.workspace ?? null;
+        case "electron-sidecar":
+            return (entries.trustedDesktop ??
+                entries.electronSidecar ??
+                entries.desktop ??
+                null);
+        case "workspace":
+        default:
+            return entries.workspace ?? null;
+    }
+}
+function selectLegacyEntry(lapis, host) {
+    const runtime = lapis.runtime;
+    if (!runtime) {
+        return null;
+    }
+    if (host === "electron-sidecar") {
+        return normalizeRuntimePath(runtime.trustedDesktop ?? runtime.desktop);
+    }
+    return normalizeRuntimePath(runtime.workspace);
+}
+function getSharedDependencyDefaults(lapis, host) {
+    const sharedDependencies = lapis?.runtime?.sharedDependencies;
+    if (!sharedDependencies) {
+        return [];
+    }
+    switch (host) {
+        case "electron-renderer":
+            return normalizeStringArray(sharedDependencies.electronRenderer ?? sharedDependencies.workspace);
+        case "electron-sidecar":
+            return normalizeStringArray(sharedDependencies.electronSidecar ?? sharedDependencies.desktop);
+        case "workspace":
+        default:
+            return normalizeStringArray(sharedDependencies.workspace);
+    }
+}
+function normalizeRuntimePath(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return [
+        ...new Set(value.filter((item) => typeof item === "string")),
+    ];
+}
+function isLapisRuntimeContainer(value) {
+    return isRecord(value) && value.manifestVersion === 1;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/plugin.d.ts

@@ -0,0 +1,350 @@
+import type { MetadataProcessor } from "./cache.svelte";
+import type { IndexProjectionRegistration, RegisteredIndexProjectionHandle } from "./storage/index-projection";
+import type { SearchDocumentProvider, SearchDocumentProviderRegistration } from "./search-document-provider";
+import type { Command, KeymapEventHandler } from "./command.svelte";
+import type { ContextKeyValue, ScopedContextKey } from "./context-keys.svelte";
+import type { App, ExtType } from "./context.svelte";
+import type { LapisExtensionContributions, LapisExtensionKind, LapisExtensionManifest, LapisExtensionPermission, LapisExtensionRuntimeHost, LapisPluginClassification, LapisServiceProviderRegistration, LapisSystemExtensionRegistration } from "./lapis-extension";
+import type { EditorViewContribution } from "./editor-view-registry";
+import type { ConfigurationOptionSourceProvider, ConfigurationOptionSourceRegistration } from "./configuration-option-source-registry";
+import type { HostedPluginCapability } from "./plugin-capability-facade";
+import type { MarkdownDirectiveRenderer, MarkdownPostProcessor, MarkdownPostProcessorContext, MarkdownViewMenuItemProvider } from "./markdown";
+import type { MarkdownExtensionContribution } from "./markdown-extension-registry";
+import type { MarkdownFileSurfaceProvider } from "./markdown-file-surface-registry";
+import type { TypeWidget } from "./metadata.svelte";
+import type { PluginSettingTab } from "./settings.svelte";
+import type { EditorSuggest } from "./suggest";
+import type { TelemetryAttributes, TelemetryMeasurementOptions, TelemetrySpan, TelemetrySpanOptions } from "./telemetry";
+import type { PluginProvenance } from "./plugin-distribution/types";
+import { Component } from "./view.svelte";
+import type { ViewCreator } from "./workspace.svelte";
+import type { DiagnosticCollection, DiagnosticCollectionOptions } from "./diagnostics";
+import type { AppTool, AppToolRegistration } from "./agent-tools";
+import type { AgentResultViewDefinition, AgentResultViewRegistration } from "./agent-result-views";
+import type { AppSkillSourceRegistration, AppSlashCommandDefinition, AppSlashCommandRegistration, ProgrammaticAppSkill } from "./agent-skills";
+/**
+ * A concise, plugin-owned palette command that opens a registered view.
+ *
+ * @public
+ */
+export type ViewOpenCommand = Omit<Command, "id" | "name" | "sourcePlugin" | "title" | "callback"> & {
+    /** @public */
+    id: `open-${string}`;
+    /** @public */
+    name: `Open ${string}`;
+    /** @public */
+    callback: NonNullable<Command["callback"]>;
+};
+/**
+ * Declares how a registered view is reached.
+ *
+ * First-party source must classify every registration. The optional parameter
+ * preserves the established third-party plugin API.
+ *
+ * @public
+ */
+export type ViewAccess = {
+    kind: "command";
+    command: ViewOpenCommand;
+} | {
+    kind: "file";
+} | {
+    kind: "internal";
+} | {
+    kind: "alias";
+    canonicalViewType: string;
+};
+export interface PluginManifest {
+    /**
+     * Vault path to the plugin folder in the config directory.
+     *
+     * @public
+     */
+    dir?: string;
+    /**
+     * The plugin ID.
+     *
+     * @public
+     */
+    id: string;
+    /**
+     * The display name.
+     *
+     * @public
+     */
+    name: string;
+    /**
+     * The author's name.
+     *
+     * @public
+     */
+    author: string;
+    /**
+     * The current version, using {@link https://semver.org/ Semantic Versioning}.
+     *
+     * @public
+     */
+    version: string;
+    /**
+     * The minimum required Obsidian version to run this plugin.
+     *
+     * @public
+     */
+    minAppVersion: string;
+    /**
+     * A description of the plugin.
+     *
+     * @public
+     */
+    description: string;
+    /**
+     * A URL to the author's website.
+     *
+     * @public
+     */
+    authorUrl?: string;
+    /**
+     * Whether the plugin can be used only on desktop.
+     *
+     * @public
+     */
+    isDesktopOnly?: boolean;
+    /**
+     * Runtime host IDs this plugin explicitly supports.
+     *
+     * Missing or empty values preserve baseline Obsidian manifest behavior.
+     *
+     * @public
+     */
+    supportedRuntimes?: string[];
+    /**
+     * Structured host capabilities required before the plugin can be evaluated.
+     *
+     * @public
+     */
+    requiredCapabilities?: HostedPluginCapability[];
+    /**
+     * Optional host-specific execution hints for future sidecar scheduling.
+     *
+     * @public
+     */
+    executionHints?: Record<string, unknown>;
+    /**
+     * Optional Lapis extension metadata. Existing Obsidian-compatible manifests
+     * can omit this namespace and continue to load unchanged.
+     *
+     * @public
+     */
+    lapis?: LapisExtensionManifest;
+}
+export type { LapisExtensionContributions, LapisExtensionKind, LapisExtensionManifest, LapisExtensionPermission, LapisExtensionRuntimeHost, LapisPluginClassification, LapisSystemExtensionRegistration, };
+/**
+ * Identifies where a plugin was loaded from.
+ *
+ * @public
+ */
+export type PluginSource = "core" | "community" | "official" | "system";
+/**
+ * Resolve the compatibility data path used by `loadData()` and `saveData()`.
+ *
+ * Community plugins store data beside their manifest folder, while bundled and
+ * system plugins use the shared `/.obsidian/<id>.json` location.
+ *
+ * @public
+ */
+export declare function resolvePluginDataPath(pluginId: string, source: PluginSource, basePath?: string): string | null;
+export type PluginRuntimeState = "disabled" | "enabling" | "enabled" | "disabling" | "failed";
+export type PluginConstructor<T extends Plugin = Plugin> = new (app: App) => T;
+/**
+ * Runtime metadata applied to a plugin instance before activation.
+ *
+ * @public
+ */
+export interface PluginRuntimeOptions {
+    basePath?: string;
+    source?: PluginSource;
+    provenance?: PluginProvenance;
+    required?: boolean;
+    hostMode?: string;
+    requestedCapabilities?: HostedPluginCapability[];
+    grantedCapabilities?: HostedPluginCapability[];
+}
+/**
+ * Base class for Lapis plugins.
+ *
+ * Plugins extend {@link Component}, so teardown callbacks, events, commands, and
+ * DOM listeners registered through helper methods are cleaned up when the
+ * plugin unloads.
+ *
+ * @public
+ */
+export declare abstract class Plugin extends Component {
+    #private;
+    readonly app: App;
+    readonly manifest: PluginManifest;
+    basePath: string;
+    constructor(app: App, manifest: PluginManifest);
+    /**
+     * Load plugin state and register plugin-owned resources.
+     *
+     * @public
+     */
+    abstract onload(): Promise<void> | void;
+    /**
+     * Release plugin-owned resources before the plugin unloads.
+     *
+     * @public
+     */
+    onunload(): Promise<void> | void;
+    /**
+     * Apply runtime metadata resolved by the plugin manager before activation.
+     *
+     * @param options - Runtime source, host, and capability information.
+     * @public
+     */
+    configureRuntime(options?: PluginRuntimeOptions): void;
+    /**
+     * Enable the plugin and run its `onload()` lifecycle.
+     *
+     * @returns A promise that resolves when activation completes.
+     * @public
+     */
+    enable(): Promise<void>;
+    get enabled(): boolean;
+    get source(): PluginSource;
+    get provenance(): PluginProvenance;
+    get required(): boolean;
+    /** View types owned by this plugin across enable and disable cycles. */
+    get registeredViewTypes(): ReadonlySet<string>;
+    get state(): PluginRuntimeState;
+    get errorMessage(): string | null;
+    get lastFailureMessage(): string | null;
+    get failureCount(): number;
+    get hostMode(): string;
+    get requestedCapabilities(): HostedPluginCapability[];
+    get grantedCapabilities(): HostedPluginCapability[];
+    get id(): string;
+    private getDataPath;
+    private readLegacyData;
+    private writeLegacyData;
+    protected telemetryAttributes(attributes?: TelemetryAttributes): TelemetryAttributes;
+    startTelemetrySpan(name: string, options?: TelemetrySpanOptions): TelemetrySpan;
+    measureTelemetry<T>(name: string, callback: (span: TelemetrySpan) => T, options?: TelemetryMeasurementOptions): T;
+    measureTelemetryAsync<T>(name: string, callback: (span: TelemetrySpan) => Promise<T>, options?: TelemetryMeasurementOptions): Promise<T>;
+    disable(): Promise<void>;
+    addStatusBarItem(): HTMLElement;
+    /**
+     * Load settings data from disk. Data is stored in `data.json` in the plugin
+     * folder.
+     *
+     * @public
+     * @see {@link https://docs.obsidian.md/Plugins/User+interface/Settings}
+     */
+    loadData(): Promise<any>;
+    /**
+     * Write settings data to disk. Data is stored in `data.json` in the plugin
+     * folder.
+     *
+     * @public
+     * @see {@link https://docs.obsidian.md/Plugins/User+interface/Settings}
+     */
+    saveData(data: any): Promise<void>;
+    loadGeneratedState<T>(key: string): Promise<T | null>;
+    saveGeneratedState(key: string, value: unknown): Promise<void>;
+    deleteGeneratedState(key: string): Promise<void>;
+    migrateDataToGeneratedState<T = unknown>(legacyKey: string, options?: {
+        generatedKey?: string;
+        pruneLegacyKey?: boolean;
+    }): Promise<T | null>;
+    private requireGeneratedStateKey;
+    private generatedStateMetaKey;
+    private generatedStateMigrationMetaKey;
+    addRibbonIcon(icon: string, title: string, callback: (evt: MouseEvent) => any): void;
+    addCommand(command: Command): Command;
+    removeCommand(commandId: string): void;
+    registerContextKey(key: string, defaultValue?: ContextKeyValue): ScopedContextKey;
+    registerShortcut(handler: KeymapEventHandler): void;
+    registerView(type: string, viewCreator: ViewCreator, access?: ViewAccess): void;
+    registerSidebarView(type: string, viewCreator: ViewCreator, options?: {
+        side?: "left" | "right";
+        group?: string;
+        groupTitle?: string;
+        groupIcon?: string;
+        title?: string;
+        icon?: string;
+        hidden?: boolean;
+    }, access?: ViewAccess): void;
+    registerEditorView(contribution: EditorViewContribution): void;
+    registerConfigurationOptionSource(id: string, provider: Omit<ConfigurationOptionSourceProvider, "pluginId">): ConfigurationOptionSourceRegistration;
+    registerHoverLinkSource(id: string, info: any): void;
+    registerObsidianProtocolHandler(action: string, handler: (params: Record<string, string>) => any): void;
+    registerCliHandler(name: string, prefix: string, callback: (...args: any[]) => any): void;
+    registerBasesView(viewId: string, registration: any): boolean;
+    registerLapisServiceProvider(registration: Omit<LapisServiceProviderRegistration, "pluginId">): void;
+    /** Create an owner-scoped diagnostic collection disposed with this plugin. */
+    createDiagnosticCollection(id: string, options?: DiagnosticCollectionOptions): DiagnosticCollection;
+    onUserEnable(): Promise<void> | void;
+    onExternalSettingsChange(): Promise<void> | void;
+    registerExtensions(extensions: string[], viewType?: string): void;
+    registerTypeWidget(widget: TypeWidget): void;
+    /**
+     * Register an EditorSuggest which can provide live suggestions while the user
+     * is typing.
+     *
+     * @public
+     */
+    registerEditorSuggest(editorSuggest: EditorSuggest<any>, viewType?: string): void;
+    /**
+     * Registers a CodeMirror 6 extension. To reconfigure cm6 extensions for a
+     * plugin on the fly, an array should be passed in, and modified dynamically.
+     * Once this array is modified, calling {@link Workspace.updateOptions} will
+     * apply the changes.
+     *
+     * @param extension - Must be a CodeMirror 6 `Extension`, or an array of
+     *   Extensions.
+     * @public
+     */
+    registerEditorExtension(extension: ExtType, viewType?: string): void;
+    /** Register a plugin-owned Markdown contribution for every Markdown surface. */
+    registerMarkdownExtension(contribution: MarkdownExtensionContribution): void;
+    /** Register a provider for complete Markdown file surfaces. */
+    registerMarkdownFileSurfaceProvider(provider: MarkdownFileSurfaceProvider): void;
+    /**
+     * Registers a post processor, to change how the document looks in reading
+     * mode.
+     *
+     * @public
+     * @see {@link https://docs.obsidian.md/Plugins/Editor/Markdown+post+processing}
+     */
+    registerMarkdownPostProcessor(postProcessor: MarkdownPostProcessor, sortOrder?: number): MarkdownPostProcessor;
+    registerMarkdownCodeBlockProcessor(language: string, handler: (source: string, el: HTMLElement, ctx: MarkdownPostProcessorContext) => Promise<any> | void, sortOrder?: number): MarkdownPostProcessor;
+    registerMarkdownDirectiveRenderer(directive: string, renderer: MarkdownDirectiveRenderer): void;
+    registerMarkdownViewMenuItem(provider: MarkdownViewMenuItemProvider): void;
+    registerMetadataProcessor(processor: MetadataProcessor, ext?: string): void;
+    registerIndexProjection<T = Record<string, unknown>>(registration: IndexProjectionRegistration): RegisteredIndexProjectionHandle<T>;
+    private backfillIndexProjection;
+    /**
+     * Contribute normalized searchable content without writing generated state.
+     * The local id is namespaced by this plugin's runtime id.
+     */
+    registerSearchDocumentProvider(localId: string, provider: Omit<SearchDocumentProvider, "id">): SearchDocumentProviderRegistration;
+    /** Register an application tool under this plugin's lifecycle and identity. */
+    registerAgentTool<TInput>(tool: AppTool<TInput>): AppToolRegistration;
+    /** Register a directory that contains one skill. */
+    registerAgentSkillDirectory(path: string): AppSkillSourceRegistration;
+    /** Register a root that may contain many skill directories. */
+    registerAgentSkillRoot(path: string): AppSkillSourceRegistration;
+    /** Register a programmatic skill under this plugin's lifecycle. */
+    registerAgentSkill(skill: ProgrammaticAppSkill): AppSkillSourceRegistration;
+    /** Register a composer slash command. This is not a workspace palette command. */
+    registerAgentSlashCommand(command: AppSlashCommandDefinition): AppSlashCommandRegistration;
+    /** Register a transcript result view. This is not a workspace palette command. */
+    registerAgentResultView(view: AgentResultViewDefinition<App>): AgentResultViewRegistration;
+    /**
+     * Register a settings tab, which allows users to change settings.
+     *
+     * @public
+     * @see {@link https://docs.obsidian.md/Plugins/User+interface/Settings#Register+a+settings+tab}
+     */
+    addSettingTab(settingTab: PluginSettingTab): void;
+}