@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/client/plugos/syscalls/sync.ts

@@ -1,8 +1,13 @@
-import type { SysCallMapping } from "../system.ts";
 import type { Client } from "../../client.ts";
+import type { SysCallMapping } from "../system.ts";
 
 export function syncSyscalls(client: Client): SysCallMapping {
   const syncTimeoutMs = 30000;
+  // Deferring indexing only pays off while the sync engine is actually
+  // delivering files. Once it has gone this long without reporting progress
+  // there is nothing left to yield to, and continuing to defer would stall
+  // the initial index forever.
+  const syncStallMs = 5000;
 
   function waitForServiceWorkerActivation(path?: string): Promise<any> {
     return new Promise<any>((resolve, reject) => {
@@ -60,27 +65,105 @@ export function syncSyscalls(client: Client): SysCallMapping {
   }
 
   return {
-    "sync.hasInitialSyncCompleted": (): boolean => {
-      return client.fullSyncCompleted;
+    "sync.hasInitialSyncCompleted": {
+      callback: (): boolean => {
+        return client.fullSyncCompleted;
+      },
+      description:
+        "Checks whether the initial client synchronization has completed.",
+      returns: [
+        { type: "boolean", description: "Whether initial sync is complete." },
+      ],
     },
-    "sync.performFileSync": async (_ctx, path: string): Promise<void> => {
-      await client.postServiceWorkerMessage({
-        type: "perform-file-sync",
-        path,
-      });
-      // postServiceWorkerMessage returns silently if no SW, so only wait if SW is active
-      const registration = await navigator.serviceWorker.getRegistration();
-      if (registration?.active) {
-        return waitForServiceWorkerActivation(path);
-      }
+    "sync.areFilesReadyToIndex": {
+      callback: (_ctx, paths: string[]): boolean[] => {
+        const allReady =
+          !!client.bootConfig.disableServiceWorker ||
+          client.fullSyncCompleted ||
+          client.fullIndexCompleted ||
+          (client.serverPingMs !== undefined && client.serverPingMs < 25) ||
+          Date.now() - client.lastSyncProgressAt > syncStallMs;
+        return paths.map((path) => allReady || client.syncedPaths.has(path));
+      },
+      description:
+        "For each file, whether indexing it now would read it locally or cheaply (true), or race the initial sync and expensively re-download it (false).",
+      parameters: [
+        {
+          name: "paths",
+          type: "string[]",
+          description: "Space-relative file paths.",
+        },
+      ],
+      returns: [
+        {
+          type: "boolean[]",
+          description: "Per-path readiness, in input order.",
+        },
+      ],
     },
-    "sync.performSpaceSync": async (): Promise<number> => {
-      await client.postServiceWorkerMessage({ type: "perform-space-sync" });
-      const registration = await navigator.serviceWorker.getRegistration();
-      if (registration?.active) {
-        return waitForServiceWorkerActivation();
-      }
-      return 0;
+    "sync.performFileSync": {
+      callback: async (
+        _ctx,
+        path: string,
+        remoteLastModified?: number,
+        remoteRevisionHash?: string,
+      ): Promise<void> => {
+        await client.postServiceWorkerMessage({
+          type: "perform-file-sync",
+          path,
+          remoteLastModified,
+          remoteRevisionHash,
+        });
+        // postServiceWorkerMessage returns silently if no SW, so only wait if SW is active
+        const registration = await navigator.serviceWorker?.getRegistration();
+        if (registration?.active) {
+          return waitForServiceWorkerActivation(path);
+        }
+      },
+      description:
+        "Prioritizes a file for immediate synchronization and waits for completion.",
+      parameters: [
+        {
+          name: "path",
+          type: "string",
+          description: "Space-relative file path.",
+        },
+        {
+          name: "remoteLastModified",
+          type: "number",
+          optional: true,
+          description:
+            "lastModified of the remote change event, used for echo suppression.",
+        },
+        {
+          name: "remoteRevisionHash",
+          type: "string",
+          optional: true,
+          description:
+            "Content revision the remote change event reported, which tells a same-millisecond change from an echo.",
+        },
+      ],
+      examples: [{ code: 'sync.performFileSync("notes/important.md")' }],
+    },
+    "sync.performSpaceSync": {
+      callback: async (): Promise<number> => {
+        await client.postServiceWorkerMessage({ type: "perform-space-sync" });
+        const registration = await navigator.serviceWorker?.getRegistration();
+        if (registration?.active) {
+          return waitForServiceWorkerActivation();
+        }
+        return 0;
+      },
+      description:
+        "Starts an immediate full-space synchronization and waits for completion.",
+      returns: [
+        {
+          type: "number",
+          description:
+            "Number of sync operations, or zero without an active worker.",
+        },
+      ],
+      examples: [{ code: "local changes = sync.performSpaceSync()" }],
     },
   };
 }

package/client/plugos/syscalls/system.ts

@@ -1,161 +1,296 @@
 import type { SysCallMapping } from "../system.ts";
 import type { Client } from "../../client.ts";
-import { publicVersion } from "../../../public_version.ts";
+import { version as publicVersion } from "../../../version.json";
 import type { CommandDef } from "@silverbulletmd/silverbullet/type/manifest";
 import type { SyscallMeta } from "@silverbulletmd/silverbullet/type/index";
+import { loadAccounts, loadProfile } from "../../accounts.ts";
+import type {
+  Account,
+  ClientProfile,
+} from "../../../plug-api/types/profile.ts";
 
 export function systemSyscalls(
   client: Client,
   readOnlyMode: boolean,
 ): SysCallMapping {
   const api: SysCallMapping = {
-    "system.invokeFunction": (
-      _ctx,
-      fullName: string, // plug.function
-      ...args: any[]
-    ) => {
-      const [plugName, functionName] = fullName.split(".");
-      if (!plugName || !functionName) {
-        throw Error(`Invalid function name ${fullName}`);
-      }
-      const plug = client.clientSystem.system.loadedPlugs.get(plugName);
-      if (!plug) {
-        throw Error(`Plug ${plugName} not found`);
-      }
-      const functionDef = plug.manifest!.functions[functionName];
-      if (!functionDef) {
-        throw Error(`Function ${functionName} not found`);
-      }
-      return plug.invoke(functionName, args);
-    },
-    "system.invokeFunctionOnServer": (
-      ctx,
-      fullName: string, // plug.function
-      ...args: any[]
-    ) => {
-      console.warn(
-        "Calling deprecated system.invokeFunctionOnServer, use system.invokeFunction instead",
-      );
-      return api["system.invokeFunction"](ctx, fullName, ...args);
-    },
-    "system.serverSyscall": (_ctx, name: string, ...args: any[]) => {
-      console.warn(
-        "Calling deprecated system.serverSyscall, use syscall instead",
-      );
-      return client.clientSystem.localSyscall(name, args);
-    },
-    "system.invokeCommand": (_ctx, name: string, args?: string[]) => {
-      console.warn("Deprecated, use editor.invokeCommand instead");
-      return client.runCommandByName(name, args);
-    },
-    "system.listCommands": (): { [key: string]: CommandDef } => {
-      const commandHook = client.clientSystem.commandHook;
-      const allCommands: { [key: string]: CommandDef } = {};
-      for (const [cmd, def] of commandHook.buildAllCommands()) {
-        allCommands[cmd] = {
-          name: def.name,
-          contexts: def.contexts,
-          priority: def.priority,
-          key: def.key,
-          mac: def.mac,
-          hide: def.hide,
-          requireMode: def.requireMode,
-          requireEditor: def.requireEditor,
-          menu: def.menu,
-          menuMac: def.menuMac,
-          menuWindows: def.menuWindows,
-          menuLinux: def.menuLinux,
-        };
-      }
-      return allCommands;
-    },
-    "system.listSyscalls": (): SyscallMeta[] => {
-      const syscalls: SyscallMeta[] = [];
-      for (const [name, info] of client.clientSystem.system
-        .registeredSyscalls) {
-        syscalls.push({
-          name,
-          requiredPermissions: info.requiredPermissions,
-          argCount: Math.max(0, info.callback.length - 1),
-        });
-      }
-      return syscalls;
-    },
-    "system.reloadPlugs": () => {
-      if (!client) {
-        throw new Error("Not supported");
-      }
-      return client.loadPlugs();
-    },
-    "system.loadPlug": async (_ctx, path: string) => {
-      const meta = await client.space.spacePrimitives.getFileMeta(path);
-      await client.clientSystem.loadPlugFromPath(path, meta.lastModified);
-      await client.dispatchAppEvent("plugs:loaded");
-    },
-    "system.unloadPlug": (_ctx, path: string) => {
-      return client.clientSystem.system.unloadByPath(path);
-    },
-    "system.reloadConfig": (): Record<string, any> => {
-      console.warn("system.reloadConfig is deprecated, it's now a no-op");
-      return client.config.values;
-    },
-    "system.loadSpaceScripts": async () => {
-      console.warn("DEPRECATED: used system.loadScripts instead");
-      await client.clientSystem.loadLuaScripts();
-    },
-    "system.loadScripts": async () => {
-      await client.clientSystem.loadLuaScripts();
-    },
-    "system.loadSpaceStyles": async () => {
-      if (!client) {
-        throw new Error("Not supported on server");
-      }
-      await client.loadCustomStyles();
-    },
-    "system.wipeClient": async (_ctx, logout = false) => {
-      await client.wipeClient();
-      if (logout) {
-        location.href = ".logout";
-      } else {
-        alert("Client wiped, feel free to navigate elsewhere");
-      }
+    "system.invokeFunction": {
+      callback: (
+        _ctx,
+        fullName: string, // plug.function
+        ...args: any[]
+      ) => {
+        const [plugName, functionName] = fullName.split(".");
+        if (!plugName || !functionName) {
+          throw Error(`Invalid function name ${fullName}`);
+        }
+        const plug = client.clientSystem.system.loadedPlugs.get(plugName);
+        if (!plug) {
+          throw Error(`Plug ${plugName} not found`);
+        }
+        const functionDef = plug.manifest!.functions[functionName];
+        if (!functionDef) {
+          throw Error(`Function ${functionName} not found`);
+        }
+        return plug.invoke(functionName, args);
+      },
+      description: "Invokes a loaded plug function by its plug-qualified name.",
+      signatures: ["system.invokeFunction(name, ...)"],
+    },
+    "system.invokeFunctionOnServer": {
+      callback: (
+        ctx,
+        fullName: string, // plug.function
+        ...args: any[]
+      ) => {
+        console.warn(
+          "Calling deprecated system.invokeFunctionOnServer, use system.invokeFunction instead",
+        );
+        const registration = api["system.invokeFunction"];
+        const invokeFunction =
+          typeof registration === "function"
+            ? registration
+            : registration.callback;
+        return invokeFunction(ctx, fullName, ...args);
+      },
+      description: "Deprecated alias for system.invokeFunction.",
+      deprecated: "Use system.invokeFunction instead.",
+      signatures: ["system.invokeFunctionOnServer(name, ...)"],
+    },
+    "system.serverSyscall": {
+      callback: (_ctx, name: string, ...args: any[]) => {
+        console.warn(
+          "Calling deprecated system.serverSyscall, use syscall instead",
+        );
+        return client.clientSystem.localSyscall(name, args);
+      },
+      description: "Deprecated helper for invoking a named syscall.",
+      deprecated: "Invoke the target syscall directly instead.",
+      signatures: ["system.serverSyscall(name, ...)"],
+    },
+    "system.invokeCommand": {
+      callback: (_ctx, name: string, args?: string[]) => {
+        console.warn("Deprecated, use editor.invokeCommand instead");
+        return client.runCommandByName(name, args);
+      },
+      description: "Deprecated alias for editor.invokeCommand.",
+      deprecated: "Use editor.invokeCommand instead.",
+      signatures: ["system.invokeCommand(name, args?)"],
+    },
+    "system.listCommands": {
+      callback: (): { [key: string]: CommandDef } => {
+        const commandHook = client.clientSystem.commandHook;
+        const allCommands: { [key: string]: CommandDef } = {};
+        for (const [cmd, def] of commandHook.buildAllCommands()) {
+          allCommands[cmd] = {
+            name: def.name,
+            contexts: def.contexts,
+            priority: def.priority,
+            key: def.key,
+            mac: def.mac,
+            hide: def.hide,
+            requireMode: def.requireMode,
+            requireEditor: def.requireEditor,
+            menu: def.menu,
+            menuMac: def.menuMac,
+            menuWindows: def.menuWindows,
+            menuLinux: def.menuLinux,
+          };
+        }
+        return allCommands;
+      },
+      description:
+        "Returns a map of every currently available command definition.",
+    },
+    "system.listPaletteCommands": {
+      callback: () => client.listPaletteCommands(),
+      description: `Returns the commands the command palette would show right now: context- and mode-filtered, hidden ones dropped, each with its prettified key hint and the time it was last run on this client.`,
+      signatures: ["system.listPaletteCommands()"],
+    },
+    "system.runPaletteCommand": {
+      callback: async (_ctx, name: string) => {
+        await client.registerCommandRun(name);
+        try {
+          return await client.runCommandByName(name);
+        } catch (e: any) {
+          client.reportError(e, "Command invocation");
+          return false;
+        }
+      },
+      description: `Runs a command as if it had been picked from the command palette: records it as the most recently run, then invokes it and returns its result. A command that throws is reported to the user and answered as false, which in this protocol means "do not move focus on my behalf".`,
+      parameters: [
+        { name: "name", type: "string", description: "Command name." },
+      ],
+      returns: [{ description: "Whatever the command returned." }],
+    },
+    "system.listSyscalls": {
+      callback: (): SyscallMeta[] => {
+        const syscalls: SyscallMeta[] = [];
+        for (const [name, info] of client.clientSystem.system
+          .registeredSyscalls) {
+          const { callback, requiredPermissions, ...metadata } = info;
+          syscalls.push({
+            name,
+            requiredPermissions,
+            argCount: Math.max(0, callback.length - 1),
+            ...metadata,
+          });
+        }
+        return syscalls;
+      },
+      description:
+        "Lists registered syscalls with permissions, argument counts, and documentation metadata.",
+    },
+    "system.reloadPlugs": {
+      callback: () => {
+        if (!client) {
+          throw new Error("Not supported");
+        }
+        return client.loadPlugs();
+      },
+      description: "Reloads every plug available to the client.",
+    },
+    "system.reboot": {
+      callback: async () => {
+        await client.save(true);
+        await client.eventedSpacePrimitives.fetchFileListWhenIdle();
+        await client.mq.awaitEmptyQueue("indexQueue");
+        await client.clientSystem.reloadState();
+      },
+      description:
+        "Saves the current editor buffer, detects on-disk changes, waits for indexing, and reloads configuration, scripts, styles, and client state. Because the buffer is saved first, an external edit to the currently open page can be overwritten; edit that page through the editor or navigate away first.",
+    },
+    "system.loadPlug": {
+      callback: async (_ctx, path: string) => {
+        const meta = await client.space.spacePrimitives.getFileMeta(path);
+        await client.clientSystem.loadPlugFromPath(path, meta.lastModified);
+        await client.dispatchAppEvent("plugs:loaded");
+      },
+      description: "Loads or reloads one plug from a space file path.",
+      signatures: ["system.loadPlug(path)"],
+    },
+    "system.unloadPlug": {
+      callback: (_ctx, path: string) =>
+        client.clientSystem.system.unloadByPath(path),
+      description: "Unloads the plug loaded from a space file path.",
+      signatures: ["system.unloadPlug(path)"],
+    },
+    "system.reloadConfig": {
+      callback: (): Record<string, any> => {
+        console.warn("system.reloadConfig is deprecated, it's now a no-op");
+        return client.config.values;
+      },
+      description: "Deprecated no-op that returns the current configuration.",
+      deprecated:
+        "Configuration reloads automatically; use system.reboot when needed.",
+    },
+    "system.loadSpaceScripts": {
+      callback: async () => {
+        console.warn("DEPRECATED: used system.loadScripts instead");
+        await client.clientSystem.loadLuaScripts();
+      },
+      description: "Deprecated alias for system.loadScripts.",
+      deprecated: "Use system.loadScripts instead.",
+    },
+    "system.loadScripts": {
+      callback: async () => {
+        await client.clientSystem.loadLuaScripts();
+      },
+      description: "Reloads Space Lua scripts and configuration.",
+    },
+    "system.loadSpaceStyles": {
+      callback: async () => {
+        if (!client) {
+          throw new Error("Not supported on server");
+        }
+        await client.loadCustomStyles();
+      },
+      description: "Reloads custom Space Style definitions.",
+    },
+    "system.wipeClient": {
+      callback: async (_ctx, logout = false) => {
+        await client.wipeClient();
+        if (logout) {
+          location.href = ".logout";
+        } else {
+          alert("Client wiped, feel free to navigate elsewhere");
+        }
+      },
+      description:
+        "Wipes local client state, cached files, databases, and optionally the login session.",
+      signatures: ["system.wipeClient(logout?)"],
     },
     // DEPRECATED
-    "system.cleanDatabases": (): boolean => {
-      console.warn(
-        "system.cleanDatabses is deprecated, use Client: Wipe instead",
-      );
-      return false;
+    "system.cleanDatabases": {
+      callback: (): boolean => {
+        console.warn(
+          "system.cleanDatabses is deprecated, use Client: Wipe instead",
+        );
+        return false;
+      },
+      description: "Deprecated no-op retained for compatibility.",
+      deprecated: "Use system.wipeClient or the Client: Wipe command instead.",
     },
-    "system.getMode": () => {
-      return readOnlyMode ? "ro" : "rw";
+    "system.getMode": {
+      callback: () => (readOnlyMode ? "ro" : "rw"),
+      description: "Returns rw for read-write mode or ro for read-only mode.",
     },
-    "system.getURLPrefix": () => {
-      const url = new URL(document.baseURI);
-
-      return url.pathname;
+    "system.getURLPrefix": {
+      callback: () => {
+        const url = new URL(document.baseURI);
+        return url.pathname;
+      },
+      description:
+        "Returns the configured URL path prefix for this SilverBullet instance.",
+    },
+    "system.getBaseURI": {
+      callback: () => document.baseURI,
+      description:
+        "Returns the browser base URI for this SilverBullet instance.",
     },
-    "system.getBaseURI": () => {
-      return document.baseURI;
+    "system.getVersion": {
+      callback: () => publicVersion,
+      description: "Returns the running SilverBullet version.",
     },
-    "system.getVersion": () => {
-      return publicVersion;
+    "system.getProfile": {
+      callback: (): Promise<ClientProfile> => loadProfile(client),
+      description:
+        'The current user\'s identity. `username` is "me" when the server has no account for this session.',
+      signatures: ["system.getProfile()"],
     },
-    "system.getConfig": (_ctx, key: string, defaultValue: any = undefined) => {
-      return client.config.get(key, defaultValue);
+    "system.listAccounts": {
+      callback: (): Promise<Account[]> => loadAccounts(client),
+      description:
+        "Every account with access to this space, with the current user marked.",
+      signatures: ["system.listAccounts()"],
+    },
+    "system.getConfig": {
+      callback: (_ctx, key: string, defaultValue: any = undefined) =>
+        client.config.get(key, defaultValue),
+      description: "Returns a configuration value, with an optional default.",
+      signatures: ["system.getConfig(key, defaultValue?)"],
     },
     // DEPRECATED
-    "system.getEnv": () => {
-      console.warn(
-        "system.getEnv is deprecated, you can assume the env to always be the client",
-      );
-      return null;
-    },
-    "system.getSpaceConfig": (_ctx, key, defaultValue?) => {
-      console.warn(
-        "system.getSpaceConfig is deprecated, use system.getConfig instead",
-      );
-      return client.config.get(key, defaultValue);
+    "system.getEnv": {
+      callback: () => {
+        console.warn(
+          "system.getEnv is deprecated, you can assume the env to always be the client",
+        );
+        return null;
+      },
+      description: "Deprecated environment probe that always returns nil.",
+      deprecated: "The environment is always the client.",
+    },
+    "system.getSpaceConfig": {
+      callback: (_ctx, key, defaultValue?) => {
+        console.warn(
+          "system.getSpaceConfig is deprecated, use system.getConfig instead",
+        );
+        return client.config.get(key, defaultValue);
+      },
+      description: "Deprecated alias for system.getConfig.",
+      deprecated: "Use system.getConfig instead.",
+      signatures: ["system.getSpaceConfig(key, defaultValue?)"],
     },
   };
   return api;