@silverbulletmd/silverbullet 2.9.0 → 2.10.0

package/client/plugos/syscalls/markdown.ts

@@ -10,6 +10,7 @@ import {
   type MarkdownExpandOptions,
 } from "../../markdown_renderer/inline.ts";
 import type { Client } from "../../client.ts";
+import { bakeSectionsInText } from "../../baked_sections/bake.ts";
 import {
   type MarkdownRenderOptions,
   renderMarkdownToHtml,
@@ -22,62 +23,177 @@ import * as TagConstants from "../../../plugs/index/constants.ts";
 
 export function markdownSyscalls(client: Client): SysCallMapping {
   return {
-    "markdown.parseMarkdown": (_ctx, text: string): ParseTree => {
-      return parse(markdownLanguageWithUserExtensions(client), text);
+    "markdown.parseMarkdown": {
+      callback: (_ctx, text: string): ParseTree => {
+        return parse(markdownLanguageWithUserExtensions(client), text);
+      },
+      description: "Parses Markdown text into a syntax tree.",
+      parameters: [
+        { name: "text", type: "string", description: "Markdown source." },
+      ],
+      returns: [{ type: "table", description: "Parsed Markdown tree." }],
+      examples: [{ code: 'local tree = markdown.parseMarkdown("# Title")' }],
     },
-    "markdown.renderParseTree": (_ctx, tree: ParseTree): string => {
-      return renderToText(tree);
+    "markdown.renderParseTree": {
+      callback: (_ctx, tree: ParseTree): string => {
+        return renderToText(tree);
+      },
+      description: "Renders a Markdown syntax tree back to source text.",
+      parameters: [
+        { name: "tree", type: "table", description: "Markdown syntax tree." },
+      ],
+      returns: [{ type: "string", description: "Rendered Markdown." }],
+      examples: [
+        {
+          code: 'local tree = markdown.parseMarkdown("# Title")\nprint(markdown.renderParseTree(tree))',
+        },
+      ],
     },
-    "markdown.expandMarkdown": async (
-      _ctx,
-      treeOrText: ParseTree | string,
-      options?: MarkdownExpandOptions,
-    ): Promise<ParseTree | string> => {
-      const outputString = typeof treeOrText === "string";
-      if (typeof treeOrText === "string") {
-        treeOrText = parse(
-          markdownLanguageWithUserExtensions(client),
+    "markdown.expandMarkdown": {
+      callback: async (
+        _ctx,
+        treeOrText: ParseTree | string,
+        options?: MarkdownExpandOptions,
+      ): Promise<ParseTree | string> => {
+        const outputString = typeof treeOrText === "string";
+        if (typeof treeOrText === "string") {
+          treeOrText = parse(
+            markdownLanguageWithUserExtensions(client),
+            treeOrText,
+          );
+        }
+        const result = await expandMarkdownWithClient(
+          client,
           treeOrText,
+          options,
         );
-      }
-      const result = await expandMarkdownWithClient(
-        client,
-        treeOrText,
-        options,
-      );
-      if (outputString) {
-        return renderToText(result);
-      } else {
-        return result;
-      }
+        if (outputString) {
+          return renderToText(result);
+        } else {
+          return result;
+        }
+      },
+      description:
+        "Expands Markdown transclusions, Lua directives, and task references.",
+      signatures: [
+        "markdown.expandMarkdown(text, options?)",
+        "markdown.expandMarkdown(tree, options?)",
+      ],
+      parameters: [
+        { name: "textOrTree", description: "Markdown text or parsed tree." },
+        {
+          name: "options",
+          type: "table",
+          description:
+            "Expansion switches: expandTransclusions, expandLuaDirectives, and rewriteTasks; all default to true.",
+          optional: true,
+        },
+      ],
+      returns: [
+        { description: "Expanded text or tree, matching the input form." },
+      ],
+      examples: [
+        {
+          code: 'local expanded = markdown.expandMarkdown("This is some Lua: ${1 + 2}")',
+        },
+      ],
     },
-    "markdown.markdownToHtml": async (
-      _ctx,
-      text: string,
-      options: MarkdownRenderOptions = {},
-    ) => {
-      let mdTree = parse(markdownLanguageWithUserExtensions(client), text);
-      if (options.expand) {
-        mdTree = await expandMarkdownWithClient(client, mdTree);
-      }
-      if (!options.resolveTagHref) {
-        options.resolveTagHref = (tagName: string) => {
-          return client.config.get<string | null>(
-            ["tags", tagName, "tagPage"],
-            null,
-          ) ?? TagConstants.tagPrefix + tagName;
-        };
-      }
-      return renderMarkdownToHtml(mdTree, options);
+    "markdown.markdownToHtml": {
+      callback: async (
+        _ctx,
+        text: string,
+        options: MarkdownRenderOptions = {},
+      ) => {
+        let mdTree = parse(markdownLanguageWithUserExtensions(client), text);
+        if (options.expand) {
+          mdTree = await expandMarkdownWithClient(client, mdTree);
+        }
+        if (!options.resolveTagHref) {
+          options.resolveTagHref = (tagName: string) => {
+            return (
+              client.config.get<string | null>(
+                ["tags", tagName, "tagPage"],
+                null,
+              ) ?? TagConstants.tagPrefix + tagName
+            );
+          };
+        }
+        return renderMarkdownToHtml(mdTree, options);
+      },
+      description: "Renders Markdown text to HTML.",
+      parameters: [
+        { name: "text", type: "string", description: "Markdown source." },
+        {
+          name: "options",
+          type: "table",
+          description: "HTML rendering options.",
+          optional: true,
+        },
+      ],
+      returns: [{ type: "string", description: "Rendered HTML." }],
+      examples: [{ code: 'local html = markdown.markdownToHtml("# Title")' }],
     },
-    "markdown.objectsToTable": (
-      _ctx,
-      data: any[],
-      options: {
-        renderCell?: (val: any, key: string) => Promise<any> | any;
-      } = {},
-    ) => {
-      return jsonToMDTable(data, options.renderCell || refCellTransformer);
+    // Re-bake every baked section (`<!--#lua EXPR -->` … `<!--/lua-->`) in
+    // `text` and return the updated markdown. Pure transform (no editor) — the
+    // text-level counterpart of the "Baked Sections: Update" command. `pageName`
+    // sets the `currentPage` context for the evaluated expressions.
+    "markdown.bakeSections": {
+      callback: (_ctx, text: string, pageName?: string): Promise<string> => {
+        return bakeSectionsInText(client, text, pageName);
+      },
+      description:
+        "Re-evaluates all baked Lua sections in Markdown text; sections that error or only render as HTML are left unchanged.",
+      parameters: [
+        {
+          name: "text",
+          type: "string",
+          description: "Markdown containing baked sections.",
+        },
+        {
+          name: "pageName",
+          type: "string",
+          description: "Page used as currentPage during evaluation.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "string",
+          description: "Markdown with updated baked section bodies.",
+        },
+      ],
+      examples: [
+        {
+          code: 'local text = "Total: <!--#lua 1 + 2 -->\\nold\\n<!--/lua-->"\nprint(markdown.bakeSections(text))',
+        },
+      ],
+    },
+    "markdown.objectsToTable": {
+      callback: (
+        _ctx,
+        data: any[],
+        options: {
+          renderCell?: (val: any, key: string) => Promise<any> | any;
+        } = {},
+      ) => {
+        return jsonToMDTable(data, options.renderCell || refCellTransformer);
+      },
+      description: "Formats a list of objects as a Markdown table.",
+      parameters: [
+        { name: "data", type: "table", description: "Rows to render." },
+        {
+          name: "options",
+          type: "table",
+          description: "Optional renderCell callback.",
+          optional: true,
+        },
+      ],
+      returns: [{ type: "string", description: "Markdown table." }],
+      examples: [
+        {
+          code: 'local tableText = markdown.objectsToTable({{name = "Pete", age = 20}})',
+        },
+      ],
     },
   };
 }

package/client/plugos/syscalls/mq.ts

@@ -11,34 +11,107 @@ export function mqSyscalls(mq: DataStoreMQ): SysCallMapping {
     /**
      * Define a Lua event listener
      */
-    "mq.subscribe": (_ctx, def: MQListenerSpec) => {
-      def.autoAck = def.autoAck !== false;
-      // console.log("Registering Lua event listener: ", def.name);
-      client.config.insert(["mqSubscriptions", def.queue], def);
+    "mq.subscribe": {
+      callback: (_ctx, def: MQListenerSpec) => {
+        def.autoAck = def.autoAck !== false;
+        // console.log("Registering Lua event listener: ", def.name);
+        client.config.insert(["mqSubscriptions", def.queue], def);
+      },
+      description: "Subscribes a Space Lua callback to a message queue.",
+      parameters: [
+        {
+          name: "spec",
+          type: "table",
+          description:
+            "Subscription with queue, optional batchSize and pollInterval, autoAck (default true), and a run(messages) callback; each message has queue, id, and body fields.",
+        },
+      ],
+      examples: [
+        {
+          code: 'mq.subscribe { queue = "tasks", batchSize = 1, run = function(messages) print(messages[1].body) end }',
+        },
+      ],
     },
-    "mq.send": (_ctx, queue: string, body: any) => {
-      return mq.send(queue, body);
+    "mq.send": {
+      callback: (_ctx, queue: string, body: any) => {
+        return mq.send(queue, body);
+      },
+      description: "Sends a message to a queue.",
+      parameters: [
+        { name: "queue", type: "string", description: "Queue name." },
+        { name: "body", description: "Message body." },
+      ],
+      examples: [{ code: 'mq.send("tasks", "my task")' }],
     },
-    "mq.batchSend": (_ctx, queue: string, bodies: any[]) => {
-      return mq.batchSend(queue, bodies);
+    "mq.batchSend": {
+      callback: (_ctx, queue: string, bodies: any[]) => {
+        return mq.batchSend(queue, bodies);
+      },
+      description: "Sends multiple messages to a queue in one operation.",
+      parameters: [
+        { name: "queue", type: "string", description: "Queue name." },
+        { name: "bodies", type: "table", description: "Message bodies." },
+      ],
     },
-    "mq.ack": (_ctx, queue: string, id: string) => {
-      return mq.ack(queue, id);
+    "mq.ack": {
+      callback: (_ctx, queue: string, id: string) => {
+        return mq.ack(queue, id);
+      },
+      description: "Acknowledges one queue message as processed.",
+      parameters: [
+        { name: "queue", type: "string", description: "Queue name." },
+        { name: "id", type: "string", description: "Message ID." },
+      ],
     },
-    "mq.batchAck": (_ctx, queue: string, ids: string[]) => {
-      return mq.batchAck(queue, ids);
+    "mq.batchAck": {
+      callback: (_ctx, queue: string, ids: string[]) => {
+        return mq.batchAck(queue, ids);
+      },
+      description: "Acknowledges multiple queue messages as processed.",
+      parameters: [
+        { name: "queue", type: "string", description: "Queue name." },
+        { name: "ids", type: "table", description: "Message IDs." },
+      ],
     },
-    "mq.flushQueue": (_ctx, queue: string) => {
-      return mq.flushQueue(queue);
+    "mq.flushQueue": {
+      callback: (_ctx, queue: string) => {
+        return mq.flushQueue(queue);
+      },
+      description: "Removes all messages from a queue.",
+      parameters: [
+        { name: "queue", type: "string", description: "Queue name." },
+      ],
     },
-    "mq.flushAllQueues": () => {
-      return mq.flushAllQueues();
+    "mq.flushAllQueues": {
+      callback: () => {
+        return mq.flushAllQueues();
+      },
+      description: "Removes all messages from every queue.",
     },
-    "mq.getQueueStats": (_ctx, queue: string) => {
-      return mq.getQueueStats(queue);
+    "mq.getQueueStats": {
+      callback: (_ctx, queue: string) => {
+        return mq.getQueueStats(queue);
+      },
+      description:
+        "Gets queued, processing, and dead-letter counts for a queue.",
+      parameters: [
+        {
+          name: "queue",
+          type: "string",
+          description: "Queue name.",
+          optional: true,
+        },
+      ],
+      returns: [{ type: "table", description: "Queue statistics." }],
     },
-    "mq.awaitEmptyQueue": (_ctx, queue: string) => {
-      return mq.awaitEmptyQueue(queue);
+    "mq.awaitEmptyQueue": {
+      callback: (_ctx, queue: string) => {
+        return mq.awaitEmptyQueue(queue);
+      },
+      description: "Waits until a queue has no pending or processing messages.",
+      parameters: [
+        { name: "queue", type: "string", description: "Queue name." },
+      ],
     },
   };
 }

package/client/plugos/syscalls/schema_introspection.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure schema-introspection helpers over the `["tags"]` config table.
+ *
+ * Returns raw JSON Schema objects; presentation-layer flattening (into typed
+ * property rows) happens in the `sb describe` CLI (describe.rs).
+ */
+
+/**
+ * Returns a map of tag name → raw JSON Schema for every tag that defines a schema.
+ * Tags without a schema are omitted.
+ */
+export function describeSchemas(
+  tags: Record<string, any>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [name, def] of Object.entries(tags)) {
+    if (def?.schema != null) {
+      result[name] = def.schema;
+    }
+  }
+  return result;
+}
+
+/**
+ * Returns the raw JSON Schema for a single tag, or null if the tag is
+ * undefined or has no schema.
+ */
+export function tagSchema(
+  tags: Record<string, any>,
+  tagName: string,
+): unknown | null {
+  return tags[tagName]?.schema ?? null;
+}

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,28 +4,59 @@ 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)',
+        },
+      ],
     },
   };
 }