@lapis-notes/api 0.1.0

package/dist/agent-skills.js

@@ -0,0 +1,182 @@
+import { EventDispatcher } from "./events";
+export const SKILL_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+export const SLASH_COMMAND_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+let skillSequence = 0;
+let slashSequence = 0;
+export function assertSkillRelativePath(path, label) {
+    const trimmed = path.trim().replaceAll("\\", "/");
+    if (!trimmed) {
+        throw new Error(`${label} must not be empty.`);
+    }
+    if (trimmed.startsWith("/") || /^[a-z]:/iu.test(trimmed)) {
+        throw new Error(`${label} must stay inside the extension root.`);
+    }
+    const segments = trimmed.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new Error(`${label} must not contain traversal segments.`);
+    }
+    return trimmed;
+}
+function normalizeSkill(skill) {
+    const name = skill.name.trim();
+    if (!SKILL_NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid skill name: ${skill.name}. Expected pattern ${SKILL_NAME_PATTERN.source}.`);
+    }
+    const description = skill.description.trim();
+    if (!description) {
+        throw new Error(`Skill ${name} description must not be empty.`);
+    }
+    const instructions = skill.instructions.trim();
+    if (!instructions) {
+        throw new Error(`Skill ${name} instructions must not be empty.`);
+    }
+    return { ...skill, name, description, instructions };
+}
+function normalizeSlashName(name) {
+    const normalized = name.trim().replace(/^\/+/u, "").toLowerCase();
+    if (!SLASH_COMMAND_NAME_PATTERN.test(normalized)) {
+        throw new Error(`Invalid slash command name: ${name}. Expected pattern ${SLASH_COMMAND_NAME_PATTERN.source}.`);
+    }
+    return normalized;
+}
+/** Transport-neutral registry for plugin-owned skill sources. */
+export class AppSkillRegistry extends EventDispatcher {
+    sources = new Map();
+    registerRoot(owner, path) {
+        return this.#registerPath(owner, "root", path);
+    }
+    registerDirectory(owner, path) {
+        return this.#registerPath(owner, "directory", path);
+    }
+    registerSkill(owner, skill) {
+        const pluginId = owner.pluginId.trim();
+        if (!pluginId) {
+            throw new Error("Skill owner plugin id must not be empty.");
+        }
+        const registeredSkill = normalizeSkill(skill);
+        const registrationId = `app-skill-${++skillSequence}`;
+        const registered = {
+            registrationId,
+            ownerPluginId: pluginId,
+            kind: "programmatic",
+            skill: registeredSkill,
+        };
+        this.sources.set(registrationId, registered);
+        this.emit("changed", {
+            registrationId,
+            ownerPluginId: pluginId,
+            reason: "registered",
+        });
+        return this.#disposable(registered);
+    }
+    list() {
+        return [...this.sources.values()];
+    }
+    #registerPath(owner, kind, path) {
+        const pluginId = owner.pluginId.trim();
+        if (!pluginId) {
+            throw new Error("Skill owner plugin id must not be empty.");
+        }
+        const relative = assertSkillRelativePath(path, "Skill source path");
+        const registrationId = `app-skill-${++skillSequence}`;
+        const registered = {
+            registrationId,
+            ownerPluginId: pluginId,
+            kind,
+            path: relative,
+        };
+        this.sources.set(registrationId, registered);
+        this.emit("changed", {
+            registrationId,
+            ownerPluginId: pluginId,
+            reason: "registered",
+        });
+        return this.#disposable(registered);
+    }
+    #disposable(registered) {
+        let disposed = false;
+        return {
+            id: registered.registrationId,
+            kind: registered.kind,
+            dispose: () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                if (this.sources.get(registered.registrationId) !== registered)
+                    return;
+                this.sources.delete(registered.registrationId);
+                this.emit("changed", {
+                    registrationId: registered.registrationId,
+                    ownerPluginId: registered.ownerPluginId,
+                    reason: "unregistered",
+                });
+            },
+        };
+    }
+}
+/** Transport-neutral registry for plugin-owned composer slash commands. */
+export class AppSlashCommandRegistry extends EventDispatcher {
+    commands = new Map();
+    register(owner, command) {
+        const pluginId = owner.pluginId.trim();
+        if (!pluginId) {
+            throw new Error("Slash command owner plugin id must not be empty.");
+        }
+        const name = normalizeSlashName(command.name);
+        if (this.commands.has(name)) {
+            throw new Error(`Slash command already registered: ${name}`);
+        }
+        const description = command.description.trim();
+        if (!description) {
+            throw new Error(`Slash command ${name} description must not be empty.`);
+        }
+        if (!command.dispatch || typeof command.dispatch !== "object") {
+            throw new Error(`Slash command ${name} must provide a dispatch.`);
+        }
+        const aliases = (command.aliases ?? []).map((alias) => normalizeSlashName(alias));
+        const registrationId = `app-slash-${++slashSequence}`;
+        const registered = {
+            registrationId,
+            ownerPluginId: pluginId,
+            command: {
+                ...command,
+                name,
+                description,
+                aliases,
+            },
+        };
+        this.commands.set(name, registered);
+        this.emit("changed", {
+            registrationId,
+            name,
+            ownerPluginId: pluginId,
+            reason: "registered",
+        });
+        let disposed = false;
+        return {
+            id: registrationId,
+            name,
+            dispose: () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                if (this.commands.get(name) !== registered)
+                    return;
+                this.commands.delete(name);
+                this.emit("changed", {
+                    registrationId,
+                    name,
+                    ownerPluginId: pluginId,
+                    reason: "unregistered",
+                });
+            },
+        };
+    }
+    get(name) {
+        const normalized = name.trim().replace(/^\/+/u, "").toLowerCase();
+        return this.commands.get(normalized);
+    }
+    list() {
+        return [...this.commands.values()].sort((left, right) => left.command.name.localeCompare(right.command.name));
+    }
+}

package/dist/agent-tools.d.ts

@@ -0,0 +1,92 @@
+import { EventDispatcher } from "./events";
+export type AppToolEffect = "read" | "write" | "external";
+export type AppToolJsonValue = null | boolean | number | string | AppToolJsonValue[] | {
+    [key: string]: AppToolJsonValue;
+};
+export type AppToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export interface AppToolResult {
+    content: AppToolContent[];
+    isError?: boolean;
+    structuredContent?: AppToolJsonValue;
+}
+export interface AppToolApprovalDetails {
+    title: string;
+    description?: string;
+    path?: string;
+    paths?: string[];
+    diff?: {
+        before: string;
+        after: string;
+    };
+    diffs?: Array<{
+        path?: string;
+        before: string;
+        after: string;
+    }>;
+}
+export interface AppToolExecutionScope {
+    /** Vault-relative directory fixed by the owning conversation. */
+    readonly directory: string;
+    contains(path: string): boolean;
+    resolve(path: string): string;
+}
+/** Construct an immutable execution scope from trusted conversation state. */
+export declare function createAppToolExecutionScope(directory: string): AppToolExecutionScope;
+export interface AppToolExecutionContext {
+    conversationId: string;
+    agentBindingId: string;
+    runId: string;
+    toolCallId: string;
+    scope: AppToolExecutionScope;
+    launchNotePath?: string;
+    signal: AbortSignal;
+}
+export interface AppTool<TInput = unknown> {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    effect: AppToolEffect;
+    describeApproval?(input: TInput, context: AppToolExecutionContext): Promise<AppToolApprovalDetails>;
+    execute(input: TInput, context: AppToolExecutionContext): Promise<AppToolResult>;
+}
+export interface AppToolOwner {
+    pluginId: string;
+    source: "core" | "community" | "official" | "system";
+    provenance: "bundled" | "official" | "community" | "manual" | "development";
+}
+export interface RegisteredAppTool {
+    registrationId: string;
+    owner: AppToolOwner;
+    tool: AppTool;
+}
+export interface AppToolRegistration {
+    readonly id: string;
+    readonly name: string;
+    dispose(): void;
+}
+export type AppToolRegistryChange = {
+    registrationId: string;
+    name: string;
+    ownerPluginId: string;
+    reason: "registered" | "unregistered";
+};
+export { createVaultFileAppTools, createVaultFileOperations, } from "./file-tools";
+export declare const APP_TOOL_NAME_PATTERN: RegExp;
+/** Transport-neutral registry for plugin-owned application tools. */
+export declare class AppToolRegistry extends EventDispatcher<{
+    changed: [change: AppToolRegistryChange];
+}> {
+    private readonly tools;
+    register<TInput>(owner: AppToolOwner, tool: AppTool<TInput>): AppToolRegistration;
+    get(name: string): RegisteredAppTool | undefined;
+    resolve(name: string, registrationId: string): RegisteredAppTool | undefined;
+    list(): RegisteredAppTool[];
+}

package/dist/agent-tools.js

@@ -0,0 +1,139 @@
+import { EventDispatcher } from "./events";
+function assertPortableVaultPath(path, label) {
+    if (path.includes("\\") || path.startsWith("/") || /^[a-z]:/iu.test(path)) {
+        throw new Error(`${label} must be a vault-relative portable path.`);
+    }
+    const segments = path.split("/");
+    if (segments.some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`${label} must not contain traversal segments.`);
+    }
+    if (segments.some((segment) => segment.length === 0) && path.length > 0) {
+        throw new Error(`${label} must not contain empty path segments.`);
+    }
+    return path;
+}
+/** Construct an immutable execution scope from trusted conversation state. */
+export function createAppToolExecutionScope(directory) {
+    const trustedDirectory = assertPortableVaultPath(directory, "App tool scope directory");
+    return Object.freeze({
+        directory: trustedDirectory,
+        contains(path) {
+            try {
+                const candidate = assertPortableVaultPath(path, "App tool path");
+                return (trustedDirectory === "" ||
+                    candidate === trustedDirectory ||
+                    candidate.startsWith(`${trustedDirectory}/`));
+            }
+            catch {
+                return false;
+            }
+        },
+        resolve(path) {
+            const candidate = assertPortableVaultPath(path, "App tool path");
+            if (trustedDirectory !== "" &&
+                candidate !== trustedDirectory &&
+                !candidate.startsWith(`${trustedDirectory}/`)) {
+                throw new Error(`App tool path escapes scope: ${path}`);
+            }
+            return candidate;
+        },
+    });
+}
+export { createVaultFileAppTools, createVaultFileOperations, } from "./file-tools";
+export const APP_TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+let registrationSequence = 0;
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function validateSchema(schema, label, toolName) {
+    if (!isRecord(schema)) {
+        throw new Error(`App tool ${toolName} ${label} schema must be an object.`);
+    }
+    if (schema.type !== "object") {
+        throw new Error(`App tool ${toolName} ${label} schema must have type object.`);
+    }
+    try {
+        JSON.stringify(schema);
+    }
+    catch {
+        throw new Error(`App tool ${toolName} ${label} schema must be serializable.`);
+    }
+}
+function normalizeTool(tool) {
+    const name = tool.name.trim();
+    if (!APP_TOOL_NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid app tool name: ${tool.name}. Expected pattern ${APP_TOOL_NAME_PATTERN.source}.`);
+    }
+    const description = tool.description.trim();
+    if (!description) {
+        throw new Error(`App tool ${name} description must not be empty.`);
+    }
+    if (!["read", "write", "external"].includes(tool.effect)) {
+        throw new Error(`App tool ${name} has an invalid effect: ${tool.effect}.`);
+    }
+    if (typeof tool.execute !== "function") {
+        throw new Error(`App tool ${name} must provide an execute function.`);
+    }
+    validateSchema(tool.inputSchema, "input", name);
+    if (tool.outputSchema !== undefined) {
+        validateSchema(tool.outputSchema, "output", name);
+    }
+    return { ...tool, name, description };
+}
+/** Transport-neutral registry for plugin-owned application tools. */
+export class AppToolRegistry extends EventDispatcher {
+    tools = new Map();
+    register(owner, tool) {
+        const registeredTool = normalizeTool(tool);
+        if (!owner.pluginId.trim()) {
+            throw new Error("App tool owner plugin id must not be empty.");
+        }
+        if (this.tools.has(registeredTool.name)) {
+            throw new Error(`App tool already registered: ${registeredTool.name}`);
+        }
+        const registrationId = `app-tool-${++registrationSequence}`;
+        const registered = {
+            registrationId,
+            owner: { ...owner, pluginId: owner.pluginId.trim() },
+            tool: registeredTool,
+        };
+        this.tools.set(registeredTool.name, registered);
+        this.emit("changed", {
+            registrationId,
+            name: registeredTool.name,
+            ownerPluginId: registered.owner.pluginId,
+            reason: "registered",
+        });
+        let disposed = false;
+        return {
+            id: registrationId,
+            name: registeredTool.name,
+            dispose: () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                if (this.tools.get(registeredTool.name) !== registered)
+                    return;
+                this.tools.delete(registeredTool.name);
+                this.emit("changed", {
+                    registrationId,
+                    name: registeredTool.name,
+                    ownerPluginId: registered.owner.pluginId,
+                    reason: "unregistered",
+                });
+            },
+        };
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    resolve(name, registrationId) {
+        const registered = this.tools.get(name);
+        return registered?.registrationId === registrationId
+            ? registered
+            : undefined;
+    }
+    list() {
+        return [...this.tools.values()].sort((left, right) => left.tool.name.localeCompare(right.tool.name));
+    }
+}

package/dist/app-database-host.d.ts

@@ -0,0 +1,4 @@
+export * from "./storage/app-database";
+export * from "./storage/index-projection";
+export * from "./storage/task-projection";
+export * from "./storage/turso-app-database";

package/dist/app-database-host.js

@@ -0,0 +1,4 @@
+export * from "./storage/app-database";
+export * from "./storage/index-projection";
+export * from "./storage/task-projection";
+export * from "./storage/turso-app-database";

package/dist/app-shell-plugin-persistence.d.ts

@@ -0,0 +1,15 @@
+export declare const APP_SHELL_PLUGINS_PATH = ".obsidian/app-shell-plugins.json";
+export interface AppShellPluginPersistenceVault {
+    mkpath?(path: string): Promise<unknown>;
+    adapter?: {
+        exists?(path: string): Promise<boolean>;
+        read(path: string): Promise<string>;
+        write(path: string, data: string): Promise<unknown>;
+    };
+}
+export type AppShellPluginPersistenceVaultSource = AppShellPluginPersistenceVault | (() => AppShellPluginPersistenceVault | undefined | null) | undefined | null;
+export interface AppShellPluginEnablementPersistence {
+    load(): Promise<unknown | null>;
+    save(enabledById: Record<string, boolean>): Promise<void>;
+}
+export declare function createAppShellPluginPersistence(vault: AppShellPluginPersistenceVaultSource): AppShellPluginEnablementPersistence;

package/dist/app-shell-plugin-persistence.js

@@ -0,0 +1,34 @@
+export const APP_SHELL_PLUGINS_PATH = ".obsidian/app-shell-plugins.json";
+function resolvePluginPersistenceVault(source) {
+    if (typeof source === "function") {
+        return source() ?? undefined;
+    }
+    return source ?? undefined;
+}
+export function createAppShellPluginPersistence(vault) {
+    return {
+        async load() {
+            const adapter = resolvePluginPersistenceVault(vault)?.adapter;
+            if (!adapter?.read)
+                return null;
+            try {
+                if (adapter.exists && !(await adapter.exists(APP_SHELL_PLUGINS_PATH))) {
+                    return null;
+                }
+                const raw = await adapter.read(APP_SHELL_PLUGINS_PATH);
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        },
+        async save(enabledById) {
+            const resolved = resolvePluginPersistenceVault(vault);
+            const adapter = resolved?.adapter;
+            if (!adapter?.write)
+                return;
+            await resolved?.mkpath?.(".obsidian").catch(() => undefined);
+            await adapter.write(APP_SHELL_PLUGINS_PATH, `${JSON.stringify(enabledById, null, 2)}\n`);
+        },
+    };
+}

package/dist/app-url.d.ts

@@ -0,0 +1,54 @@
+import type { App } from "./context.svelte";
+import type { PaneType } from "./workspace.svelte";
+export type AppUrlHandlerParams = Record<string, string>;
+export type AppUrlHandler = (params: AppUrlHandlerParams) => unknown;
+export interface ParsedAppUrl {
+    scheme: string;
+    action: string;
+    params: AppUrlHandlerParams;
+}
+export interface CreateLapisOpenUrlOptions {
+    vault: string;
+    file?: string;
+    path?: string;
+    paneType?: PaneType;
+}
+export declare function createLapisOpenUrl(options: CreateLapisOpenUrlOptions): string;
+export declare function createLapisFileUrl(vault: string, file: string): string;
+/**
+ * Parses `lapis://` app URLs and dispatches registered protocol handlers.
+ *
+ * @public
+ */
+export declare class AppUrlService {
+    #private;
+    private readonly app;
+    constructor(app: App);
+    /**
+     * Register a handler for a custom app URL action.
+     *
+     * @param action - Action name to match after the app URL scheme.
+     * @param handler - Callback invoked when a matching URL is dispatched.
+     * @returns A cleanup function that unregisters the handler.
+     * @public
+     */
+    registerProtocolHandler(action: string, handler: AppUrlHandler): () => void;
+    /**
+     * Parse an app URL into its normalized action and parameter map.
+     *
+     * @param rawUrl - Raw `lapis://`, `lapis-notes://`, or compatible app URL.
+     * @returns The normalized URL request.
+     * @public
+     */
+    parse(rawUrl: string): ParsedAppUrl;
+    /**
+     * Dispatch an app URL through the built-in open handler or a registered
+     * custom action.
+     *
+     * @param rawUrl - Raw app URL to parse and execute.
+     * @returns `true` when the URL was handled successfully.
+     * @public
+     */
+    dispatch(rawUrl: string): Promise<boolean>;
+    private open;
+}