@lapis-notes/api 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @lapis-notes/api
+
+## 0.1.0
+
+### Minor Changes
+
+- First public npm release of the Lapis Notes runtime kernel, including the app
+  container, vault contracts, workspace model, plugin lifecycle, commands,
+  settings, metadata, editor, telemetry, and agent-tool public subpaths.

package/LICENSE.md

@@ -0,0 +1,4 @@
+Apache-2.0
+
+This package is licensed under the Apache License 2.0.
+See <https://www.apache.org/licenses/LICENSE-2.0>.

package/README.md

@@ -0,0 +1,43 @@
+# @lapis-notes/api
+
+Shared runtime kernel for Lapis Notes.
+
+This package defines the transport-neutral contracts used by Lapis hosts and
+plugins: the app container, vault/storage interfaces, workspace model, commands,
+settings, metadata, events, editor abstractions, plugin lifecycle, telemetry,
+and portable agent-tool helpers. It intentionally does not own desktop or web
+boot policy, vault selection, persistence transport, bundled plugin enablement,
+or product routing.
+
+## Public surface
+
+- Root runtime exports for app, workspace, commands, plugins, settings, and
+  shared models.
+- Narrow subpaths for `app-database`, `vault`, `desktop-native`, `agent-tools`,
+  `agent-skills`, `telemetry`, path helpers, workspace host integration, and the
+  editor core/language-service surfaces.
+- Peer dependencies for UI, Svelte, CodeMirror, Mira, and Design Core so hosts
+  retain singleton control over their runtime stack.
+
+## Usage
+
+```ts
+import "@lapis-notes/api";
+import { App } from "@lapis-notes/api";
+import { MemoryVaultAdapter } from "@lapis-notes/api/vault";
+import type { AppDatabase } from "@lapis-notes/api/app-database";
+```
+
+## Common Scripts
+
+```sh
+pnpm --filter @lapis-notes/api build
+pnpm --filter @lapis-notes/api check
+pnpm --filter @lapis-notes/api test
+```
+
+## References
+
+- [Package spec](spec.md)
+- [Canonical spec](../../spec/src/20-packages/api/index.md)
+- [App state model](../../spec/src/20-packages/api/app-state-and-workspace-model.md)

package/dist/__tests__/data-adapter-conformance.js

@@ -0,0 +1,205 @@
+import { describe, expect, it } from "vitest";
+import { dirname, joinPath, } from "../storage";
+export class InMemoryDataAdapter {
+    files = new Map();
+    folders = new Map([
+        ["/", { type: "folder", ctime: 1, mtime: 1, size: 0 }],
+    ]);
+    clock = 10;
+    getName() {
+        return "memory";
+    }
+    nextTime() {
+        this.clock += 1;
+        return this.clock;
+    }
+    path(path) {
+        path = path.replace(/\/+$/, "") || "/";
+        return path === "/" ? "/" : path.replace(/^\/+/, "");
+    }
+    byteLength(data) {
+        return typeof data === "string"
+            ? new TextEncoder().encode(data).byteLength
+            : data.byteLength;
+    }
+    async exists(path) {
+        path = this.path(path);
+        return this.files.has(path) || this.folders.has(path);
+    }
+    async stat(path) {
+        path = this.path(path);
+        return this.files.get(path)?.stat ?? this.folders.get(path) ?? null;
+    }
+    async list(path) {
+        path = this.path(path);
+        const prefix = path === "/" ? "" : `${path}/`;
+        const data = { files: [], folders: [] };
+        for (const file of this.files.keys()) {
+            if (!file.startsWith(prefix))
+                continue;
+            const rest = file.slice(prefix.length);
+            if (rest && !rest.includes("/"))
+                data.files.push(rest);
+        }
+        for (const folder of this.folders.keys()) {
+            if (folder === path || !folder.startsWith(prefix))
+                continue;
+            const rest = folder.slice(prefix.length);
+            if (rest && !rest.includes("/"))
+                data.folders.push(rest);
+        }
+        data.files.sort();
+        data.folders.sort();
+        return data;
+    }
+    async read(path) {
+        const value = this.files.get(this.path(path))?.data;
+        if (value === undefined)
+            throw Object.assign(new Error(path), { code: "ENOENT" });
+        return typeof value === "string" ? value : new TextDecoder().decode(value);
+    }
+    async readBinary(path) {
+        const value = this.files.get(this.path(path))?.data;
+        if (value === undefined)
+            throw Object.assign(new Error(path), { code: "ENOENT" });
+        return typeof value === "string"
+            ? new TextEncoder().encode(value).buffer
+            : value;
+    }
+    async write(path, data, options) {
+        await this.writeValue(path, data, options);
+    }
+    async writeBinary(path, data, options) {
+        await this.writeValue(path, data, options);
+    }
+    async writeValue(path, data, options) {
+        path = this.path(path);
+        const existing = this.files.get(path)?.stat;
+        const now = this.nextTime();
+        this.files.set(path, {
+            data,
+            stat: {
+                type: "file",
+                ctime: options?.ctime ?? existing?.ctime ?? now,
+                mtime: options?.mtime ?? now,
+                size: this.byteLength(data),
+            },
+        });
+    }
+    async append(path, data) {
+        await this.write(path, (await this.read(path).catch(() => "")) + data);
+    }
+    async appendBinary(path, data) {
+        const current = new Uint8Array(await this.readBinary(path).catch(() => new ArrayBuffer(0)));
+        const next = new Uint8Array(current.byteLength + data.byteLength);
+        next.set(current);
+        next.set(new Uint8Array(data), current.byteLength);
+        await this.writeBinary(path, next.buffer);
+    }
+    async process(path, fn) {
+        const next = fn(await this.read(path));
+        await this.write(path, next);
+        return next;
+    }
+    async mkdir(path) {
+        path = this.path(path);
+        const now = this.nextTime();
+        this.folders.set(path, { type: "folder", ctime: now, mtime: now, size: 0 });
+    }
+    async rmdir(path, recursive = true) {
+        path = this.path(path);
+        this.folders.delete(path);
+        for (const child of [...this.files.keys()]) {
+            if (child.startsWith(`${path}/`))
+                this.files.delete(child);
+        }
+        for (const child of [...this.folders.keys()]) {
+            if (child.startsWith(`${path}/`))
+                this.folders.delete(child);
+        }
+    }
+    async remove(path) {
+        this.files.delete(this.path(path));
+    }
+    async rename(path, newPath) {
+        await this.copy(path, newPath);
+        const stat = await this.stat(path);
+        if (stat?.type === "folder") {
+            await this.rmdir(path, true);
+        }
+        else {
+            await this.remove(path);
+        }
+    }
+    async copy(path, newPath) {
+        path = this.path(path);
+        newPath = this.path(newPath);
+        const file = this.files.get(path);
+        if (file) {
+            await this.writeValue(newPath, file.data);
+            return;
+        }
+        if (this.folders.has(path)) {
+            await this.mkdir(newPath);
+            const { files, folders } = await this.list(path);
+            for (const folder of folders) {
+                await this.copy(joinPath(path, folder), joinPath(newPath, folder));
+            }
+            for (const child of files) {
+                await this.copy(joinPath(path, child), joinPath(newPath, child));
+            }
+        }
+    }
+    getResourcePath(path) {
+        return `memory://${this.path(path)}`;
+    }
+    async trashSystem() {
+        return false;
+    }
+    async trashLocal(path) {
+        await this.mkdir(dirname(joinPath(".trash", path)));
+        await this.rename(path, joinPath(".trash", path));
+    }
+}
+export function runDataAdapterConformance(name, createAdapter) {
+    describe(name, () => {
+        it("handles text files, folders, stats, and lists", async () => {
+            const adapter = await createAdapter();
+            await adapter.mkdir("notes");
+            await adapter.write("notes/a.md", "hello");
+            expect(await adapter.read("notes/a.md")).toBe("hello");
+            expect(await adapter.exists("notes/a.md")).toBe(true);
+            expect(await adapter.stat("notes/a.md")).toMatchObject({
+                type: "file",
+                size: 5,
+            });
+            expect((await adapter.list("/")).folders).toContain("notes");
+            expect((await adapter.list("notes")).files).toContain("a.md");
+        });
+        it("handles binary writes, appends, and process updates", async () => {
+            const adapter = await createAdapter();
+            await adapter.write("note.md", "a");
+            await adapter.append("note.md", "b");
+            expect(await adapter.process("note.md", (data) => data + "c")).toBe("abc");
+            expect(await adapter.read("note.md")).toBe("abc");
+            await adapter.writeBinary("file.bin", new Uint8Array([1]).buffer);
+            await adapter.appendBinary("file.bin", new Uint8Array([2, 3]).buffer);
+            expect([...new Uint8Array(await adapter.readBinary("file.bin"))]).toEqual([1, 2, 3]);
+        });
+        it("handles copy, rename, delete, and local trash", async () => {
+            const adapter = await createAdapter();
+            await adapter.mkdir("folder");
+            await adapter.write("folder/source.md", "data");
+            await adapter.copy("folder/source.md", "folder/copy.md");
+            expect(await adapter.read("folder/copy.md")).toBe("data");
+            await adapter.rename("folder/copy.md", "renamed.md");
+            expect(await adapter.exists("folder/copy.md")).toBe(false);
+            expect(await adapter.read("renamed.md")).toBe("data");
+            await adapter.trashLocal("renamed.md");
+            expect(await adapter.exists("renamed.md")).toBe(false);
+            expect(await adapter.read(".trash/renamed.md")).toBe("data");
+            await adapter.remove("folder/source.md");
+            expect(await adapter.exists("folder/source.md")).toBe(false);
+        });
+    });
+}

package/dist/__tests__/lapis-runtime-manifest.js

@@ -0,0 +1,32 @@
+/**
+ * Synthetic Lapis ESM workspace runtime manifest for api-local tests.
+ * Not tied to any first-party plugin package.
+ */
+export function createEsmWorkspaceRuntimeManifest(overrides = {}) {
+    const id = overrides.id ?? "fixture-esm-workspace";
+    const { lapis: lapisOverrides, ...rest } = overrides;
+    return {
+        id,
+        name: rest.name ?? id,
+        author: rest.author ?? "test",
+        version: rest.version ?? "1.0.0",
+        minAppVersion: rest.minAppVersion ?? "0.0.0",
+        description: rest.description ?? "",
+        ...rest,
+        lapis: {
+            manifestVersion: 1,
+            ...lapisOverrides,
+            runtime: {
+                entries: {
+                    workspace: {
+                        path: "main.mjs",
+                        format: "esm",
+                        sharedDependencies: ["@lapis-notes/api", "svelte", "clsx"],
+                        requiresReloadOnUpdate: false,
+                    },
+                },
+                ...lapisOverrides?.runtime,
+            },
+        },
+    };
+}

package/dist/__tests__/svelte-internal-client.d.ts

@@ -0,0 +1,3 @@
+declare module "svelte/internal/client" {
+  export function effect_root(fn: () => void): () => void;
+}

package/dist/agent-result-views.d.ts

@@ -0,0 +1,52 @@
+import type { Component } from "svelte";
+import { EventDispatcher } from "./events";
+export type AgentResultViewState = "running" | "completed" | "error";
+export interface AgentResultViewConversation {
+    conversationId?: string;
+    scopeDirectory?: string;
+    launchNotePath?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentResultViewProps<TApp = object> {
+    app: TApp;
+    conversation?: AgentResultViewConversation;
+    name: string;
+    input?: unknown;
+    output?: unknown;
+    state?: AgentResultViewState;
+}
+export interface AgentResultViewDefinition<TApp = object> {
+    tool?: string;
+    command?: string;
+    component: Component<AgentResultViewProps<TApp>>;
+}
+export interface RegisteredAgentResultView<TApp = object> {
+    registrationId: string;
+    ownerPluginId: string;
+    key: string;
+    kind: "tool" | "command";
+    name: string;
+    component: Component<AgentResultViewProps<TApp>>;
+}
+export interface AgentResultViewRegistration {
+    readonly id: string;
+    readonly key: string;
+    dispose(): void;
+}
+export type AgentResultViewRegistryChange = {
+    registrationId: string;
+    key: string;
+    ownerPluginId: string;
+    reason: "registered" | "unregistered";
+};
+export declare function agentResultViewKey(kind: "tool" | "command", name: string): string;
+/** Registry for plugin-owned transcript result views. */
+export declare class AppResultViewRegistry extends EventDispatcher<{
+    changed: [change: AgentResultViewRegistryChange];
+}> {
+    private readonly views;
+    register<TApp>(ownerPluginId: string, view: AgentResultViewDefinition<TApp>): AgentResultViewRegistration;
+    getByTool(name: string): RegisteredAgentResultView | undefined;
+    getByCommand(name: string): RegisteredAgentResultView | undefined;
+    list(): RegisteredAgentResultView[];
+}

package/dist/agent-result-views.js

@@ -0,0 +1,89 @@
+import { EventDispatcher } from "./events";
+const NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+let registrationSequence = 0;
+export function agentResultViewKey(kind, name) {
+    return `${kind}:${name}`;
+}
+function normalizeName(value, label) {
+    const name = value?.trim() ?? "";
+    if (!NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid result view ${label}: ${value ?? ""}. Expected pattern ${NAME_PATTERN.source}.`);
+    }
+    return name;
+}
+function normalizeDefinition(view) {
+    const hasTool = Boolean(view.tool?.trim());
+    const hasCommand = Boolean(view.command?.trim());
+    if (hasTool === hasCommand) {
+        throw new Error("A result view must name exactly one of tool or command.");
+    }
+    if (view.component == null) {
+        throw new Error("A result view must provide a component.");
+    }
+    const kind = hasTool ? "tool" : "command";
+    const name = normalizeName(hasTool ? view.tool : view.command, kind);
+    return {
+        kind,
+        name,
+        key: agentResultViewKey(kind, name),
+        component: view.component,
+    };
+}
+/** Registry for plugin-owned transcript result views. */
+export class AppResultViewRegistry extends EventDispatcher {
+    views = new Map();
+    register(ownerPluginId, view) {
+        const pluginId = ownerPluginId.trim();
+        if (!pluginId) {
+            throw new Error("Result view owner plugin id must not be empty.");
+        }
+        const normalized = normalizeDefinition(view);
+        if (this.views.has(normalized.key)) {
+            throw new Error(`Result view already registered: ${normalized.key}`);
+        }
+        const registrationId = `app-result-view-${++registrationSequence}`;
+        const registered = {
+            registrationId,
+            ownerPluginId: pluginId,
+            key: normalized.key,
+            kind: normalized.kind,
+            name: normalized.name,
+            component: normalized.component,
+        };
+        this.views.set(normalized.key, registered);
+        this.emit("changed", {
+            registrationId,
+            key: normalized.key,
+            ownerPluginId: pluginId,
+            reason: "registered",
+        });
+        let disposed = false;
+        return {
+            id: registrationId,
+            key: normalized.key,
+            dispose: () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                if (this.views.get(normalized.key) !== registered)
+                    return;
+                this.views.delete(normalized.key);
+                this.emit("changed", {
+                    registrationId,
+                    key: normalized.key,
+                    ownerPluginId: pluginId,
+                    reason: "unregistered",
+                });
+            },
+        };
+    }
+    getByTool(name) {
+        return this.views.get(agentResultViewKey("tool", name.trim()));
+    }
+    getByCommand(name) {
+        return this.views.get(agentResultViewKey("command", name.trim()));
+    }
+    list() {
+        return [...this.views.values()].sort((left, right) => left.key.localeCompare(right.key));
+    }
+}

package/dist/agent-skills.d.ts

@@ -0,0 +1,99 @@
+import { EventDispatcher } from "./events";
+export declare const SKILL_NAME_PATTERN: RegExp;
+export declare const SLASH_COMMAND_NAME_PATTERN: RegExp;
+export type SkillSourceKind = "folder" | "vault" | "user" | "extension" | "bundled" | "programmatic";
+export interface ProgrammaticAppSkill {
+    name: string;
+    description: string;
+    instructions: string;
+    userInvocable?: boolean;
+    disableModelInvocation?: boolean;
+    argumentHint?: string;
+    command?: {
+        kind: "tool";
+        tool: string;
+        argMode?: "raw";
+    };
+}
+export interface AppSkillOwner {
+    pluginId: string;
+}
+export interface RegisteredAppSkillSource {
+    registrationId: string;
+    ownerPluginId: string;
+    kind: "root" | "directory" | "programmatic";
+    path?: string;
+    skill?: ProgrammaticAppSkill;
+}
+export interface AppSkillSourceRegistration {
+    readonly id: string;
+    readonly kind: RegisteredAppSkillSource["kind"];
+    dispose(): void;
+}
+export type AppSkillRegistryChange = {
+    registrationId: string;
+    ownerPluginId: string;
+    reason: "registered" | "unregistered";
+};
+export interface AppSlashCommandContext {
+    arguments: string;
+    conversationId?: string;
+}
+export type AppSlashCommandDispatch = {
+    kind: "host";
+    execute: (context: AppSlashCommandContext) => Promise<void> | void;
+} | {
+    kind: "tool";
+    tool: string;
+    argMode?: "raw" | "parsed";
+} | {
+    kind: "skill";
+    skill: string;
+} | {
+    kind: "prompt";
+    template: string;
+};
+export interface AppSlashCommandDefinition {
+    name: string;
+    description: string;
+    aliases?: string[];
+    argumentHint?: string;
+    dispatch: AppSlashCommandDispatch;
+}
+export interface RegisteredAppSlashCommand {
+    registrationId: string;
+    ownerPluginId: string;
+    command: AppSlashCommandDefinition;
+}
+export interface AppSlashCommandRegistration {
+    readonly id: string;
+    readonly name: string;
+    dispose(): void;
+}
+export type AppSlashCommandRegistryChange = {
+    registrationId: string;
+    name: string;
+    ownerPluginId: string;
+    reason: "registered" | "unregistered";
+};
+export declare function assertSkillRelativePath(path: string, label: string): string;
+/** Transport-neutral registry for plugin-owned skill sources. */
+export declare class AppSkillRegistry extends EventDispatcher<{
+    changed: [change: AppSkillRegistryChange];
+}> {
+    #private;
+    private readonly sources;
+    registerRoot(owner: AppSkillOwner, path: string): AppSkillSourceRegistration;
+    registerDirectory(owner: AppSkillOwner, path: string): AppSkillSourceRegistration;
+    registerSkill(owner: AppSkillOwner, skill: ProgrammaticAppSkill): AppSkillSourceRegistration;
+    list(): RegisteredAppSkillSource[];
+}
+/** Transport-neutral registry for plugin-owned composer slash commands. */
+export declare class AppSlashCommandRegistry extends EventDispatcher<{
+    changed: [change: AppSlashCommandRegistryChange];
+}> {
+    private readonly commands;
+    register(owner: AppSkillOwner, command: AppSlashCommandDefinition): AppSlashCommandRegistration;
+    get(name: string): RegisteredAppSlashCommand | undefined;
+    list(): RegisteredAppSlashCommand[];
+}