@silverbulletmd/silverbullet 2.9.0 → 2.10.0

package/client/plugos/syscalls/system.ts

@@ -1,6 +1,6 @@
 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";
 
@@ -9,153 +9,250 @@ export function systemSyscalls(
   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.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": () => {
-      return document.baseURI;
+    "system.getBaseURI": {
+      callback: () => document.baseURI,
+      description:
+        "Returns the browser base URI for this SilverBullet instance.",
     },
-    "system.getVersion": () => {
-      return publicVersion;
+    "system.getVersion": {
+      callback: () => publicVersion,
+      description: "Returns the running SilverBullet version.",
     },
-    "system.getConfig": (_ctx, key: string, defaultValue: any = undefined) => {
-      return client.config.get(key, defaultValue);
+    "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;

package/client/plugos/system.ts

@@ -7,9 +7,10 @@ import {
   builtinPlugNames,
   builtinPlugPaths,
 } from "../../plugs/builtin_plugs.ts";
+import type { LuaFunctionDocumentation } from "../../plug-api/types/index.ts";
 
 export interface SysCallMapping {
-  [key: string]: (ctx: SyscallContext, ...args: any) => Promise<any> | any;
+  [key: string]: SyscallSignature | SyscallDefinition;
 }
 
 export type SystemEvents<HookT> = {
@@ -26,10 +27,14 @@ export type SyscallContext = {
 
 type SyscallSignature = (...args: any[]) => Promise<any> | any;
 
-type Syscall = {
+export type SyscallDefinition = {
+  callback: SyscallSignature;
+} & LuaFunctionDocumentation;
+
+type RegisteredSyscall = {
   requiredPermissions: string[];
   callback: SyscallSignature;
-};
+} & LuaFunctionDocumentation;
 
 export type SystemOptions = {
   manifestCache?: ManifestCache<any>;
@@ -37,7 +42,7 @@ export type SystemOptions = {
 };
 
 export class System<HookT> extends EventEmitter<SystemEvents<HookT>> {
-  registeredSyscalls = new Map<string, Syscall>();
+  registeredSyscalls = new Map<string, RegisteredSyscall>();
   protected plugs = new Map<string, Plug<HookT>>();
   protected enabledHooks = new Set<Hook<HookT>>();
 
@@ -68,10 +73,21 @@ export class System<HookT> extends EventEmitter<SystemEvents<HookT>> {
     ...registrationObjects: SysCallMapping[]
   ) {
     for (const registrationObject of registrationObjects) {
-      for (const [name, callback] of Object.entries(registrationObject)) {
+      for (const [name, registration] of Object.entries(registrationObject)) {
+        const definition =
+          typeof registration === "function"
+            ? { callback: registration }
+            : registration;
+        const cleanName = name.startsWith("lua:")
+          ? name.slice("lua:".length)
+          : name;
+        const namespace = cleanName.split(".")[0];
+        const { callback, ...metadata } = definition;
         this.registeredSyscalls.set(name, {
           requiredPermissions: requiredCapabilities,
           callback,
+          see: `API/${namespace}`,
+          ...metadata,
         });
       }
     }

package/client/space_lua/api_documentation.ts

@@ -0,0 +1,107 @@
+import type {
+  LuaFunctionExampleDocumentation,
+  LuaFunctionInfo,
+  LuaFunctionParameterDocumentation,
+  LuaFunctionReturnDocumentation,
+} from "../../plug-api/types/index.ts";
+
+function compareNames(a: LuaFunctionInfo, b: LuaFunctionInfo): number {
+  const aName = a.name ?? "";
+  const bName = b.name ?? "";
+  return aName < bName ? -1 : aName > bName ? 1 : 0;
+}
+
+function signature(info: LuaFunctionInfo): string {
+  const parameters = (info.parameters ?? [])
+    .map((parameter) => `${parameter.name}${parameter.optional ? "?" : ""}`)
+    .join(", ");
+  return `${info.name ?? "<anonymous>"}(${parameters})`;
+}
+
+function renderParameter(parameter: LuaFunctionParameterDocumentation): string {
+  const type = parameter.type ? ` (\`${parameter.type}\`)` : "";
+  const description = parameter.description
+    ? ` — ${parameter.description}`
+    : "";
+  return `- \`${parameter.name}${parameter.optional ? "?" : ""}\`${type}${description}`;
+}
+
+function renderReturn(value: LuaFunctionReturnDocumentation): string {
+  const type = value.type ? `\`${value.type}\`` : "Value";
+  return `- ${type}${value.description ? ` — ${value.description}` : ""}`;
+}
+
+function codeFence(example: LuaFunctionExampleDocumentation): string[] {
+  const longestFence = Math.max(
+    2,
+    ...[...example.code.matchAll(/`+/g)].map((match) => match[0].length),
+  );
+  const fence = "`".repeat(longestFence + 1);
+  return [`${fence}${example.language ?? "lua"}`, example.code, fence];
+}
+
+function renderFunction(
+  info: LuaFunctionInfo,
+  apiNamespace?: string,
+): string[] {
+  const lines = [`## ${info.name ?? "<anonymous>"}`, ""];
+  const signatures = info.signatures?.length
+    ? info.signatures
+    : [signature(info)];
+  for (const value of signatures) lines.push(`\`${value}\``);
+
+  if (info.deprecated) {
+    lines.push(
+      "",
+      `> **Deprecated:** ${
+        typeof info.deprecated === "string"
+          ? info.deprecated
+          : "This function is deprecated."
+      }`,
+    );
+  }
+  if (info.description) lines.push("", info.description);
+  if (info.parameters?.length) {
+    lines.push("", "**Parameters:**", "");
+    lines.push(...info.parameters.map(renderParameter));
+  }
+  if (info.returns?.length) {
+    lines.push("", "**Returns:**", "");
+    lines.push(...info.returns.map(renderReturn));
+  }
+  if (info.examples?.length) {
+    lines.push(
+      "",
+      info.examples.length === 1 ? "**Example:**" : "**Examples:**",
+    );
+    for (const example of info.examples) {
+      if (example.description) lines.push("", example.description);
+      lines.push("", ...codeFence(example));
+    }
+  }
+  const namespacePage = apiNamespace ? `API/${apiNamespace}` : undefined;
+  if (info.see && info.see !== namespacePage) {
+    lines.push("", `**See:** [[${info.see}]]`);
+  }
+  return lines;
+}
+
+/** Render function metadata as deterministic Markdown for live `${...}` directives. */
+export function renderApiDocumentationMarkdown(
+  functions: LuaFunctionInfo[],
+  context?: string,
+): string {
+  const documented = functions.filter((info) => info.name).sort(compareNames);
+  if (documented.length === 0) {
+    return context
+      ? `_No documented API functions found for \`${context}\`._`
+      : "_No functions found._";
+  }
+  return documented
+    .flatMap((info, index) => [
+      ...(index > 0 ? [""] : []),
+      ...renderFunction(info, context),
+    ])
+    .join("\n")
+    .trim();
+}

package/client/space_lua/ast.ts

@@ -1,3 +1,5 @@
+import type { LuaFunctionDocumentation } from "../../plug-api/types/index.ts";
+
 type ASTContext = {
   ctx: ASTCtx;
 };
@@ -12,6 +14,8 @@ export type ASTCtx = {
 export type LuaBlock = {
   type: "Block";
   statements: LuaStatement[];
+  // Comments lexically owned by this block, in source order.
+  comments?: LuaComment[];
   hasLabel?: boolean;
   hasGoto?: boolean;
   // the first duplicated label is recorded here for later eval
@@ -26,6 +30,14 @@ export type LuaBlock = {
   hasFunctionDef?: boolean;
 } & ASTContext;
 
+export type LuaComment = {
+  type: "Comment";
+  /** Exact source text, including delimiters. */
+  text: string;
+  kind: "line" | "long";
+  ctx: ASTCtx;
+};
+
 // STATEMENTS
 export type LuaReturnStatement = {
   type: "Return";
@@ -128,6 +140,7 @@ export type LuaFunctionBody = {
   type: "FunctionBody";
   parameters: string[];
   block: LuaBlock;
+  documentation?: LuaFunctionDocumentation;
 } & ASTContext;
 
 export type LuaAssignmentStatement = {

package/client/space_lua/eval.ts

@@ -1015,7 +1015,8 @@ export function evalExpression(
       case "Variable":
       case "FunctionCall":
       case "TableAccess":
-      case "PropertyAccess": {
+      case "PropertyAccess":
+      case "Parenthesized": {
         return evalPrefixExpression(e, env, sf);
       }
       case "TableConstructor": {
@@ -1318,7 +1319,7 @@ function evalPrefixExpression(
 
     case "Parenthesized": {
       const p = asParenthesized(e);
-      return evalExpression(p.expression, env, sf);
+      return rpThen(evalExpression(p.expression, env, sf), singleResult);
     }
 
     // <<expr>>[<<expr>>]
@@ -2063,6 +2064,12 @@ export function evalStatement(
         let errSf: LuaStackFrame | undefined;
         const ps: Promise<any>[] = [];
         for (let i = 0; i < lvalues.length; i++) {
+          if (
+            values[i] instanceof LuaFunction &&
+            typeof lvalues[i].key === "string"
+          ) {
+            values[i].info.name ??= lvalues[i].key;
+          }
           const r = luaSet(
             lvalues[i].env,
             lvalues[i].key,
@@ -2115,6 +2122,7 @@ export function evalStatement(
       }
 
       const bindOne = (name: any, v: LuaValue) => {
+        if (v instanceof LuaFunction) v.info.name ??= name.name;
         const isConst = name.attributes?.includes(LuaAttribute.Const) === true;
         const isClose = name.attributes?.includes(LuaAttribute.Close) === true;
 
@@ -2386,13 +2394,13 @@ export function evalStatement(
       }
       (settable as any).set(
         propNames[propNames.length - 1],
-        new LuaFunction(body, env),
+        new LuaFunction(body, env, { name: propNames.join(".") }),
       );
       return;
     }
     case "LocalFunction": {
       const lf = asLocalFunction(s);
-      env.setLocal(lf.name, new LuaFunction(lf.body, env));
+      env.setLocal(lf.name, new LuaFunction(lf.body, env, { name: lf.name }));
       return;
     }
     case "Return": {