@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/client/plugos/syscalls/config.ts

@@ -5,45 +5,161 @@ import { stripFunctions } from "../util.ts";
 
 export function configSyscalls(config: Config): SysCallMapping {
   return {
-    "config.get": (_ctx, path: string, defaultValue: any) => {
-      return config.get(path, defaultValue);
+    "config.get": {
+      callback: (_ctx, path: string, defaultValue: any) => {
+        return config.get(path, defaultValue);
+      },
+      description:
+        "Gets a configuration value by path, with dot notation support.",
+      parameters: [
+        { name: "path", type: "string", description: "Configuration path." },
+        {
+          name: "defaultValue",
+          description: "Value returned when the path is absent.",
+        },
+      ],
+      returns: [{ description: "Configured value or the supplied default." }],
+      examples: [{ code: 'local theme = config.get("theme", "light")' }],
     },
-    "config.set": (
-      _ctx,
-      keyOrValues: string | string[] | Record<string, any>,
-      value?: any,
-    ) => {
-      config.set(keyOrValues as any, value);
+    "config.set": {
+      callback: (
+        _ctx,
+        keyOrValues: string | string[] | Record<string, any>,
+        value?: any,
+      ) => {
+        config.set(keyOrValues as any, value);
+      },
+      description: "Sets one configuration value or multiple values at once.",
+      signatures: ["config.set(path, value)", "config.set(values)"],
+      parameters: [
+        {
+          name: "pathOrValues",
+          description: "Configuration path or table of values.",
+        },
+        {
+          name: "value",
+          description: "Value to set when a path is supplied.",
+          optional: true,
+        },
+      ],
+      examples: [
+        { code: 'config.set("theme", "dark")' },
+        { code: 'config.set({theme = "dark", fontSize = 14})' },
+      ],
     },
-    "lua:config.setLuaValue": async (
-      _ctx,
-      keyOrValues: string | string[] | Record<string, any>,
-      value?: any,
-    ) => {
-      // This is for special cases where we explicitly want to NOT convert a value to a JS value, but maintain its Lua version (mostly for LuaTables) — main use case: metatable
-      keyOrValues = await luaValueToJS(keyOrValues, LuaStackFrame.lostFrame);
-      config.set(keyOrValues as any, value);
+    "lua:config.setLuaValue": {
+      callback: async (
+        _ctx,
+        keyOrValues: string | string[] | Record<string, any>,
+        value?: any,
+      ) => {
+        // This is for special cases where we explicitly want to NOT convert a value to a JS value, but maintain its Lua version (mostly for LuaTables) — main use case: metatable
+        keyOrValues = await luaValueToJS(keyOrValues, LuaStackFrame.lostFrame);
+        config.set(keyOrValues as any, value);
+      },
+      description:
+        "Sets configuration while preserving the supplied Lua value representation.",
+      signatures: [
+        "config.setLuaValue(path, value)",
+        "config.setLuaValue(values)",
+      ],
+      parameters: [
+        {
+          name: "pathOrValues",
+          description: "Configuration path or table of values.",
+        },
+        {
+          name: "value",
+          description: "Lua value to preserve.",
+          optional: true,
+        },
+      ],
     },
-    "config.insert": (_ctx, key: string | string[], value: any) => {
-      config.insert(key, value);
+    "config.insert": {
+      callback: (_ctx, key: string | string[], value: any) => {
+        config.insert(key, value);
+      },
+      description: "Appends a value to the configuration array at a path.",
+      parameters: [
+        { name: "path", description: "Configuration path." },
+        { name: "value", description: "Value to append." },
+      ],
     },
-    "config.has": (_ctx, path: string) => {
-      return config.has(path);
+    "config.has": {
+      callback: (_ctx, path: string) => {
+        return config.has(path);
+      },
+      description: "Checks whether a configuration path exists.",
+      parameters: [
+        { name: "path", type: "string", description: "Configuration path." },
+      ],
+      returns: [{ type: "boolean", description: "Whether the path exists." }],
     },
-    "config.define": (_ctx, key: string, schema: any) => {
-      config.define(key, schema);
+    "config.define": {
+      callback: (_ctx, key: string, schema: any) => {
+        config.define(key, schema);
+      },
+      description: "Defines a JSON schema for a configuration key.",
+      parameters: [
+        { name: "key", type: "string", description: "Configuration key." },
+        {
+          name: "schema",
+          type: "table",
+          description:
+            "JSON Schema definition; default applies a missing value and ui annotations expose it in the Configuration Manager.",
+        },
+      ],
+      examples: [
+        {
+          code: 'config.define("shortWikiLinks", {\n  description = "Render short wiki link labels",\n  type = "boolean",\n  default = true,\n  ui = {category = "Editor", label = "Short wiki links", priority = 1},\n})',
+        },
+      ],
     },
-    "config.defineCategory": (_ctx, definition: any) => {
-      config.defineCategory(definition);
+    "config.defineCategory": {
+      callback: (_ctx, definition: any) => {
+        config.defineCategory(definition);
+      },
+      description: "Defines or updates a Configuration Manager UI category.",
+      parameters: [
+        {
+          name: "definition",
+          type: "table",
+          description: "Category name, description, and priority.",
+        },
+      ],
+      examples: [
+        {
+          code: 'config.defineCategory {\n  name = "Editor",\n  description = "Page editor behavior.",\n  priority = 50,\n}',
+        },
+      ],
     },
-    "config.getValues": () => {
-      return stripFunctions(config.values);
+    "config.getValues": {
+      callback: () => {
+        return stripFunctions(config.values);
+      },
+      description: "Gets all configuration values as a single table.",
+      returns: [{ type: "table", description: "All configuration values." }],
     },
-    "config.getSchemas": () => {
-      return stripFunctions(config.schemas);
+    "config.getSchemas": {
+      callback: () => {
+        return stripFunctions(config.schemas);
+      },
+      description: "Gets all defined configuration schemas.",
+      returns: [
+        {
+          type: "table",
+          description: "Schemas keyed by configuration path.",
+        },
+      ],
     },
-    "config.getCategories": () => {
-      return { ...config.categories };
+    "config.getCategories": {
+      callback: () => {
+        return { ...config.categories };
+      },
+      description: "Gets all Configuration Manager UI categories.",
+      returns: [
+        { type: "table", description: "Category definitions keyed by name." },
+      ],
     },
   };
 }

package/client/plugos/syscalls/datastore.ts

@@ -25,65 +25,171 @@ export function dataStoreReadSyscalls(
   clientSystem: ClientSystem,
 ): SysCallMapping {
   return {
-    "datastore.batchGet": (
-      _ctx,
-      keys: KvKey[],
-    ): Promise<(any | undefined)[]> => {
-      return ds.batchGet(keys);
+    "datastore.batchGet": {
+      callback: (_ctx, keys: KvKey[]): Promise<(any | undefined)[]> => {
+        return ds.batchGet(keys);
+      },
+      description: "Gets multiple values from the key-value store.",
+      parameters: [
+        { name: "keys", type: "table", description: "List of keys to read." },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "Values in key order, with nil for missing keys.",
+        },
+      ],
+      examples: [
+        {
+          code: 'local values = datastore.batchGet({{"user", "1"}, {"user", "2"}})',
+        },
+      ],
     },
 
-    "datastore.get": (_ctx, key: KvKey): Promise<any | null> => {
-      return ds.get(key);
+    "datastore.get": {
+      callback: (_ctx, key: KvKey): Promise<any | null> => {
+        return ds.get(key);
+      },
+      description: "Gets a value from the key-value store.",
+      parameters: [
+        { name: "key", type: "table", description: "Key segments." },
+      ],
+      returns: [{ description: "Stored value, or nil when absent." }],
+      examples: [{ code: 'local user = datastore.get({"user", "123"})' }],
     },
 
-    "datastore.query": async (_ctx, options: KvQueryOptions): Promise<KV[]> => {
-      const results: KV[] = [];
-      for await (const item of ds.query(options)) {
-        results.push(item);
-      }
-      return results;
+    "datastore.query": {
+      callback: async (_ctx, options: KvQueryOptions): Promise<KV[]> => {
+        const results: KV[] = [];
+        for await (const item of ds.query(options)) {
+          results.push(item);
+        }
+        return results;
+      },
+      description:
+        "Queries key-value entries, optionally restricted to a key prefix.",
+      parameters: [
+        {
+          name: "options",
+          type: "table",
+          description: "Query options, including an optional prefix.",
+        },
+      ],
+      returns: [{ type: "table", description: "Matching key-value entries." }],
     },
 
-    "datastore.queryLua": async (
-      _ctx,
-      prefix: string[],
-      query: LuaCollectionQuery,
-      scopeVariables?: Record<string, any>,
-    ): Promise<any[]> => {
-      const sf = LuaStackFrame.createWithGlobalEnv(
-        clientSystem.spaceLuaEnv.env,
-      );
-      let env = clientSystem.spaceLuaEnv.env;
-      if (scopeVariables) {
-        env = new LuaEnv(clientSystem.spaceLuaEnv.env);
-        for (const [key, value] of Object.entries(scopeVariables)) {
-          env.setLocal(key, jsToLuaValue(value));
+    "datastore.queryLua": {
+      callback: async (
+        _ctx,
+        prefix: string[],
+        query: LuaCollectionQuery,
+        scopeVariables?: Record<string, any>,
+      ): Promise<any[]> => {
+        const sf = LuaStackFrame.createWithGlobalEnv(
+          clientSystem.spaceLuaEnv.env,
+        );
+        let env = clientSystem.spaceLuaEnv.env;
+        if (scopeVariables) {
+          env = new LuaEnv(clientSystem.spaceLuaEnv.env);
+          for (const [key, value] of Object.entries(scopeVariables)) {
+            env.setLocal(key, jsToLuaValue(value));
+          }
         }
-      }
-      return (await queryLua<any>(ds.kv, prefix, query, env, sf)).map((item) =>
-        luaValueToJS(item, sf),
-      );
+        return (await queryLua<any>(ds.kv, prefix, query, env, sf)).map(
+          (item) => luaValueToJS(item, sf),
+        );
+      },
+      description: "Runs a Space Lua collection query over a key prefix.",
+      parameters: [
+        {
+          name: "prefix",
+          type: "table",
+          description: "Key prefix to query.",
+        },
+        {
+          name: "query",
+          type: "table",
+          description: "Parsed collection query.",
+        },
+        {
+          name: "scopeVariables",
+          type: "table",
+          description: "Additional variables available to the query.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "table",
+          description: "Query results converted to Lua values.",
+        },
+      ],
     },
   };
 }
 
 export function dataStoreWriteSyscalls(ds: DataStore): SysCallMapping {
   return {
-    "datastore.delete": (_ctx, key: KvKey) => {
-      console.log("Deleting key", key);
-      return ds.delete(key);
+    "datastore.delete": {
+      callback: (_ctx, key: KvKey) => {
+        console.log("Deleting key", key);
+        return ds.delete(key);
+      },
+      description: "Deletes a value from the key-value store.",
+      parameters: [
+        { name: "key", type: "table", description: "Key segments." },
+      ],
+      examples: [{ code: 'datastore.delete({"user", "123"})' }],
     },
 
-    "datastore.set": (_ctx, key: KvKey, value: any) => {
-      return ds.set(key, value);
+    "datastore.set": {
+      callback: (_ctx, key: KvKey, value: any) => {
+        return ds.set(key, value);
+      },
+      description: "Sets a value in the key-value store.",
+      parameters: [
+        { name: "key", type: "table", description: "Key segments." },
+        { name: "value", description: "Value to store." },
+      ],
+      examples: [{ code: 'datastore.set({"user", "123"}, {name = "John"})' }],
     },
 
-    "datastore.batchSet": (_ctx, kvs: KV[]) => {
-      return ds.batchSet(kvs);
+    "datastore.batchSet": {
+      callback: (_ctx, kvs: KV[]) => {
+        return ds.batchSet(kvs);
+      },
+      description: "Sets multiple key-value entries in one operation.",
+      parameters: [
+        {
+          name: "entries",
+          type: "table",
+          description: "Entries with key and value fields.",
+        },
+      ],
+      examples: [
+        {
+          code: 'datastore.batchSet({\n  {key = {"user", "1"}, value = {name = "Alice"}},\n  {key = {"user", "2"}, value = {name = "Bob"}},\n})',
+        },
+      ],
     },
 
-    "datastore.batchDelete": (_ctx, keys: KvKey[]) => {
-      return ds.batchDelete(keys);
+    "datastore.batchDelete": {
+      callback: (_ctx, keys: KvKey[]) => {
+        return ds.batchDelete(keys);
+      },
+      description: "Deletes multiple values from the key-value store.",
+      parameters: [
+        {
+          name: "keys",
+          type: "table",
+          description: "List of keys to delete.",
+        },
+      ],
+      examples: [
+        {
+          code: 'datastore.batchDelete({{"user", "1"}, {"user", "2"}})',
+        },
+      ],
     },
   };
 }