@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/client/plugos/syscalls/service_registry.ts

@@ -12,29 +12,83 @@ export function serviceRegistrySyscalls(
     /**
      * Define a Lua event listener
      */
-    "service.define": (_ctx, def: ServiceSpec) => {
-      return serviceRegistry.define(def);
+    "service.define": {
+      callback: (_ctx, def: ServiceSpec) => {
+        return serviceRegistry.define(def);
+      },
+      description: "Defines a service that can be discovered by selector.",
+      parameters: [
+        {
+          name: "spec",
+          type: "table",
+          description: "Selector, match rule, and run callback.",
+        },
+      ],
+      examples: [
+        {
+          code: 'service.define { selector = "greeter", match = {}, run = function(name) return "Hello " .. name end }',
+        },
+      ],
     },
-    "service.discover": (
-      _ctx,
-      selector: string,
-      data: any,
-    ): Promise<ServiceMatch[]> => {
-      return serviceRegistry.discover(selector, data);
+    "service.discover": {
+      callback: (
+        _ctx,
+        selector: string,
+        data: any,
+      ): Promise<ServiceMatch[]> => {
+        return serviceRegistry.discover(selector, data);
+      },
+      description: "Discovers matching services sorted by descending priority.",
+      parameters: [
+        {
+          name: "selector",
+          type: "string",
+          description: "Service selector.",
+        },
+        { name: "data", description: "Value passed to match callbacks." },
+      ],
+      returns: [
+        { type: "table", description: "Matching service descriptors." },
+      ],
     },
-    "service.invoke": (
-      _ctx,
-      service: ServiceMatch,
-      data: any,
-    ): Promise<any> => {
-      return serviceRegistry.invoke(service, data);
+    "service.invoke": {
+      callback: (_ctx, service: ServiceMatch, data: any): Promise<any> => {
+        return serviceRegistry.invoke(service, data);
+      },
+      description: "Invokes a previously discovered service match.",
+      parameters: [
+        {
+          name: "match",
+          type: "table",
+          description: "Service match returned by service.discover.",
+        },
+        { name: "data", description: "Value passed to the service." },
+      ],
+      returns: [{ description: "Service result." }],
     },
-    "service.invokeBestMatch": (
-      _ctx,
-      selector: string,
-      data: any,
-    ): Promise<any> => {
-      return serviceRegistry.invokeBestMatch(selector, data);
+    "service.invokeBestMatch": {
+      callback: (_ctx, selector: string, data: any): Promise<any> => {
+        return serviceRegistry.invokeBestMatch(selector, data);
+      },
+      description:
+        "Discovers and invokes the highest-priority matching service.",
+      parameters: [
+        {
+          name: "selector",
+          type: "string",
+          description: "Service selector.",
+        },
+        {
+          name: "data",
+          description: "Value used for matching and invocation.",
+        },
+      ],
+      returns: [{ description: "Best matching service result." }],
+      examples: [
+        {
+          code: 'local greeting = service.invokeBestMatch("greeter", "Pete")',
+        },
+      ],
     },
   };
 }

package/client/plugos/syscalls/shell.ts

@@ -4,33 +4,63 @@ import { fsEndpoint } from "../../spaces/constants.ts";
 
 export function shellSyscalls(client: Client): SysCallMapping {
   return {
-    "shell.run": async (
-      _ctx,
-      cmd: string,
-      args: string[],
-      stdin?: string,
-    ): Promise<{ stdout: string; stderr: string; code: number }> => {
-      if (!client.httpSpacePrimitives) {
-        throw new Error("Not supported in fully local mode");
-      }
-      const resp = client.httpSpacePrimitives.authenticatedFetch(
-        buildShellUrl(client),
+    "shell.run": {
+      callback: async (
+        _ctx,
+        cmd: string,
+        args: string[],
+        stdin?: string,
+      ): Promise<{ stdout: string; stderr: string; code: number }> => {
+        if (!client.httpSpacePrimitives) {
+          throw new Error("Not supported in fully local mode");
+        }
+        const resp = client.httpSpacePrimitives.authenticatedFetch(
+          buildShellUrl(client),
+          {
+            method: "POST",
+            body: JSON.stringify({
+              cmd,
+              args,
+              stdin,
+            }),
+          },
+        );
+        const { code, stderr, stdout } = await (await resp).json();
+        return { code, stderr, stdout };
+      },
+      description: "Runs a shell command on the server and returns its output.",
+      parameters: [
+        { name: "command", type: "string", description: "Executable name." },
         {
-          method: "POST",
-          body: JSON.stringify({
-            cmd,
-            args,
-            stdin,
-          }),
+          name: "arguments",
+          type: "table",
+          description: "Command arguments.",
         },
-      );
-      const { code, stderr, stdout } = await (await resp).json();
-      return { code, stderr, stdout };
+        {
+          name: "stdin",
+          type: "string",
+          description: "Text supplied on standard input.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "stdout, stderr, and numeric exit code.",
+        },
+      ],
+      examples: [
+        {
+          code: 'local result = shell.run("ls", {"-l"})\nprint(result.stdout)',
+        },
+        {
+          code: 'local result = shell.run("cat", {}, "hello")\nprint(result.stdout)',
+        },
+      ],
     },
   };
 }
 
 function buildShellUrl(client: Client) {
-  // Strip off the /.fs and replace with /.shell
   return `${client.httpSpacePrimitives.url.slice(0, -fsEndpoint.length)}/.shell`;
 }