@silverbulletmd/silverbullet 2.9.0 → 2.11.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,106 @@ 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;
+        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/navigator.ts

@@ -0,0 +1,143 @@
+import {
+  defineView,
+  focusPanel,
+  moveByRename,
+  openView,
+  pickView,
+} from "../../navigator/navigator.ts";
+import { newView } from "../../navigator/view_value.ts";
+import type { SysCallMapping } from "../system.ts";
+
+export function navigatorSyscalls(): SysCallMapping {
+  const viewSyscalls: SysCallMapping = {
+    "view.open": {
+      callback: (_ctx, name: string, opts?: any) => {
+        return openView(name, opts);
+      },
+      description: "Opens a navigator view by name.",
+      parameters: [
+        { name: "name", type: "string", description: "View name." },
+        {
+          name: "opts",
+          type: "table",
+          description:
+            "Optional segment, phrase, dropdown, focus and quiet flags.",
+          optional: true,
+        },
+      ],
+      returns: [
+        { type: "boolean", description: "Whether the view actually opened." },
+      ],
+      examples: [{ code: 'view.open("std.spaceTree")' }],
+    },
+    "view.focus": {
+      callback: (_ctx, slot?: string) => focusPanel(slot),
+      description:
+        "Returns focus to an open navigator panel's input, keeping its current selection.",
+      parameters: [
+        {
+          name: "slot",
+          type: "string",
+          description:
+            "Which panel: modal, lhs, rhs or bhs. Defaults to any open one.",
+          optional: true,
+        },
+      ],
+      returns: [
+        { type: "boolean", description: "Whether a panel was there to focus." },
+      ],
+      examples: [{ code: 'view.focus("rhs")' }],
+    },
+    "view.moveByRename": {
+      callback: (_ctx, obj: any, newName: string) => {
+        return moveByRename(obj, newName);
+      },
+      description:
+        "Renames the page, document or folder an object stands for -- the default `onMove` for space-backed views.",
+      parameters: [
+        { name: "obj", type: "table", description: "The row's object." },
+        { name: "newName", type: "string", description: "New name." },
+      ],
+      examples: [{ code: "onMove = view.moveByRename" }],
+    },
+    "lua:view.new": {
+      callback: (_ctx, spec: any) => newView(spec),
+      description:
+        "Creates a reusable navigator view value without registering or evaluating it.",
+      parameters: [
+        {
+          name: "spec",
+          type: "table",
+          description: "View content and behavior; see the Navigator API docs.",
+        },
+      ],
+      returns: [{ type: "table", description: "The reusable view value." }],
+      examples: [
+        {
+          code: "local projects = view.new { source = function() return {} end }",
+        },
+      ],
+    },
+    "lua:view.define": {
+      callback: (_ctx, spec: any) => {
+        return defineView(spec);
+      },
+      description:
+        "Registers a navigator view, and optionally a command that opens it. Rejects a bad spec at definition time.",
+      parameters: [
+        {
+          name: "spec",
+          type: "table",
+          description: "View definition; see the Navigator API docs.",
+        },
+      ],
+      examples: [
+        {
+          code: 'view.define {\n  name = "myView",\n  source = function() return {} end,\n  onSelect = function(obj) editor.navigate(obj.ref) end,\n}',
+        },
+      ],
+    },
+    "lua:view.pick": {
+      callback: (_ctx, spec: any) => {
+        return pickView(spec);
+      },
+      description:
+        "Opens a one-shot picker over the supplied source and returns the object picked (or nil).",
+      parameters: [
+        {
+          name: "spec",
+          type: "table",
+          description:
+            "Picker definition; a view.define spec minus its name and chrome.",
+        },
+      ],
+      returns: [{ description: "The picked object, or nil." }],
+      examples: [
+        {
+          code: 'local picked = view.pick { source = function() return { { name = "One" } } end }',
+        },
+      ],
+    },
+  };
+
+  return {
+    ...viewSyscalls,
+    ...aliasNamespace(viewSyscalls, "view", "navigator"),
+  };
+}
+
+function aliasNamespace(
+  mapping: SysCallMapping,
+  from: string,
+  to: string,
+): SysCallMapping {
+  const aliased: SysCallMapping = {};
+  for (const [name, definition] of Object.entries(mapping)) {
+    const isLuaNative = name.startsWith("lua:");
+    const cleanName = isLuaNative ? name.slice("lua:".length) : name;
+    if (!cleanName.startsWith(`${from}.`)) continue;
+    const aliasedName = `${to}.${cleanName.slice(from.length + 1)}`;
+    aliased[isLuaNative ? `lua:${aliasedName}` : aliasedName] = definition;
+  }
+  return aliased;
+}

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/search.ts

@@ -0,0 +1,44 @@
+import type { SysCallMapping } from "../system.ts";
+import { rank, type RankOptions } from "../../../plug-api/lib/fuzzy.ts";
+
+export function searchSyscalls(): SysCallMapping {
+  return {
+    "search.rank": {
+      callback: (
+        _ctx,
+        objects: Record<string, any>[],
+        phrase: string,
+        options?: {
+          fields?: Record<
+            string,
+            number | { weight: number; segments?: boolean }
+          >;
+        },
+      ) => rank(objects, phrase, options as RankOptions<any>),
+      description:
+        "Fuzzy-ranks objects against a phrase, best match first. The same ranker the navigator's own filtering uses.",
+      parameters: [
+        { name: "objects", type: "table", description: "Objects to rank." },
+        {
+          name: "phrase",
+          type: "string",
+          description:
+            "Phrase to match against. An empty phrase returns every object, in the order given.",
+        },
+        {
+          name: "options",
+          type: "table",
+          description:
+            "Ranking options. `fields` maps a field name to its weight, or to `{ weight, segments = true }` to also score the parts of a `/`-separated value.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "The matching objects, best match first.",
+        },
+      ],
+    },
+  };
+}