@silverbulletmd/silverbullet 2.9.0 → 2.10.0

package/client/space_lua/pretty_print.ts

@@ -29,9 +29,28 @@ function resolveOptions(opts?: PrintOptions): ResolvedOptions {
 }
 
 const RESERVED = new Set([
-  "and", "break", "do", "else", "elseif", "end", "false", "for", "function",
-  "goto", "if", "in", "local", "nil", "not", "or", "repeat", "return", "then",
-  "true", "until", "while",
+  "and",
+  "break",
+  "do",
+  "else",
+  "elseif",
+  "end",
+  "false",
+  "for",
+  "function",
+  "goto",
+  "if",
+  "in",
+  "local",
+  "nil",
+  "not",
+  "or",
+  "repeat",
+  "return",
+  "then",
+  "true",
+  "until",
+  "while",
 ]);
 
 function isLuaIdentifier(s: string): boolean {
@@ -39,16 +58,26 @@ function isLuaIdentifier(s: string): boolean {
 }
 
 const BINARY_PREC: Record<string, number> = {
-  "or": 1,
-  "and": 2,
-  "<": 3, ">": 3, "<=": 3, ">=": 3, "~=": 3, "==": 3,
+  or: 1,
+  and: 2,
+  "<": 3,
+  ">": 3,
+  "<=": 3,
+  ">=": 3,
+  "~=": 3,
+  "==": 3,
   "|": 4,
   "~": 5, // binary bitwise xor
   "&": 6,
-  "<<": 7, ">>": 7,
+  "<<": 7,
+  ">>": 7,
   "..": 8,
-  "+": 9, "-": 9,
-  "*": 10, "/": 10, "//": 10, "%": 10,
+  "+": 9,
+  "-": 9,
+  "*": 10,
+  "/": 10,
+  "//": 10,
+  "%": 10,
   "^": 12,
 };
 const UNARY_PREC = 11;
@@ -62,7 +91,7 @@ function exprPrec(e: LuaExpression): number {
 }
 
 class Printer {
-  constructor(private opts: ResolvedOptions) { }
+  constructor(private opts: ResolvedOptions) {}
 
   private indent(depth: number): string {
     return " ".repeat(depth * this.opts.indentWidth);
@@ -129,22 +158,29 @@ class Printer {
       case "TableConstructor":
         return this.tableConstructor(e.fields, depth);
       case "FunctionDefinition":
-        return "function" +
-          this.functionRest(e.body.parameters, e.body.block, depth);
+        return `function${this.functionRest(
+          e.body.parameters,
+          e.body.block,
+          depth,
+        )}`;
       case "FunctionCall":
         return this.functionCall(e, depth);
       case "Query": {
-        const lines = e.clauses.map((c) =>
-          this.indent(depth + 1) + this.queryClause(c, depth + 1)
+        const lines = e.clauses.map(
+          (c) => this.indent(depth + 1) + this.queryClause(c, depth + 1),
         );
         return `query[[\n${lines.join("\n")}\n${this.indent(depth)}]]`;
       }
       case "FilteredCall":
-        return `${this.expression(e.call, depth)} filter ${this.expression(e.filter, depth)
-          }`;
+        return `${this.expression(e.call, depth)} filter ${this.expression(
+          e.filter,
+          depth,
+        )}`;
       case "AggregateCall":
-        return `${this.expression(e.call, depth)} order by ${this.orderByList(e.orderBy, depth)
-          }`;
+        return `${this.expression(e.call, depth)} order by ${this.orderByList(
+          e.orderBy,
+          depth,
+        )}`;
       default:
         throw new Error(
           `pretty_print: unsupported expression type: ${(e as any).type}`,
@@ -193,8 +229,8 @@ class Printer {
   private tableConstructor(fields: LuaTableField[], depth: number): string {
     if (fields.length === 0) return "{}";
     if (fields.length === 1) return `{${this.field(fields[0], depth)}}`;
-    const lines = fields.map((f) =>
-      this.indent(depth + 1) + this.field(f, depth + 1)
+    const lines = fields.map(
+      (f) => this.indent(depth + 1) + this.field(f, depth + 1),
     );
     const tail = this.opts.trailingComma ? "," : "";
     return `{\n${lines.join(",\n")}${tail}\n${this.indent(depth)}}`;
@@ -224,7 +260,8 @@ class Printer {
       ? ` order by ${this.orderByList(e.orderBy, depth)}`
       : "";
     if (
-      !e.orderBy && args.length === 1 &&
+      !e.orderBy &&
+      args.length === 1 &&
       (args[0].type === "TableConstructor" || args[0].type === "String")
     ) {
       return `${base} ${this.expression(args[0], depth)}`;
@@ -254,8 +291,10 @@ class Printer {
       case "Where":
         return `where ${this.expression(c.expression, depth)}`;
       case "Limit":
-        return `limit ${this.expression(c.limit, depth)}` +
-          (c.offset ? ` offset ${this.expression(c.offset, depth)}` : "");
+        return (
+          `limit ${this.expression(c.limit, depth)}` +
+          (c.offset ? ` offset ${this.expression(c.offset, depth)}` : "")
+        );
       case "Offset":
         return `offset ${this.expression(c.offset, depth)}`;
       case "OrderBy":
@@ -271,16 +310,32 @@ class Printer {
 
   block(b: LuaBlock, depth: number): string {
     const stmts = b.statements.filter((s) => s.type !== "Semicolon");
-    const isDef = (s: LuaStatement) =>
+    const items: (LuaStatement | NonNullable<LuaBlock["comments"]>[number])[] =
+      [...stmts, ...(b.comments ?? [])].sort(
+        (a, z) => (a.ctx.from ?? 0) - (z.ctx.from ?? 0),
+      );
+    const isDef = (s: (typeof items)[number]) =>
       s.type === "Function" || s.type === "LocalFunction";
     let out = "";
-    for (let i = 0; i < stmts.length; i++) {
+    for (let i = 0; i < items.length; i++) {
       if (i > 0) {
         out += "\n";
         // blank line separating function definitions from neighbours
-        if (isDef(stmts[i - 1]) || isDef(stmts[i])) out += "\n";
+        const previous = items[i - 1];
+        const isDocumentationPair =
+          previous.type === "Comment" &&
+          previous.text.startsWith("---") &&
+          isDef(items[i]);
+        if (!isDocumentationPair && (isDef(previous) || isDef(items[i]))) {
+          out += "\n";
+        }
       }
-      out += this.statement(stmts[i], depth);
+      const item = items[i];
+      out +=
+        item.type === "Comment"
+          ? this.indent(depth) +
+            item.text.replaceAll("\n", `\n${this.indent(depth)}`)
+          : this.statement(item, depth);
     }
     return out;
   }
@@ -290,11 +345,14 @@ class Printer {
     switch (s.type) {
       case "Local": {
         const names = s.names
-          .map((n) =>
-            n.name +
-            (n.attribute
-              ? ` <${n.attribute}>`
-              : (n.attributes?.length ? ` <${n.attributes[0]}>` : ""))
+          .map(
+            (n) =>
+              n.name +
+              (n.attribute
+                ? ` <${n.attribute}>`
+                : n.attributes?.length
+                  ? ` <${n.attributes[0]}>`
+                  : ""),
           )
           .join(", ");
         const exprs = s.expressions?.length
@@ -303,12 +361,16 @@ class Printer {
         return `${ind}local ${names}${exprs}`;
       }
       case "Assignment":
-        return `${ind}${s.variables.map((v) => this.expression(v, depth)).join(", ")
-          } = ${s.expressions.map((e) => this.expression(e, depth)).join(", ")}`;
+        return `${ind}${s.variables
+          .map((v) => this.expression(v, depth))
+          .join(
+            ", ",
+          )} = ${s.expressions.map((e) => this.expression(e, depth)).join(", ")}`;
       case "Return":
         return s.expressions.length
-          ? `${ind}return ${s.expressions.map((e) => this.expression(e, depth)).join(", ")
-          }`
+          ? `${ind}return ${s.expressions
+              .map((e) => this.expression(e, depth))
+              .join(", ")}`
           : `${ind}return`;
       case "FunctionCallStatement":
         return ind + this.expression(s.call, depth);
@@ -328,7 +390,8 @@ class Printer {
           const kw = i === 0 ? "if" : "elseif";
           const head = i === 0 ? `${ind}${kw} ` : `\n${ind}${kw} `;
           const body = this.block(c.block, depth + 1);
-          out += `${head}${this.expression(c.condition, depth)} then` +
+          out +=
+            `${head}${this.expression(c.condition, depth)} then` +
             (body ? `\n${body}` : "");
         });
         if (s.elseBlock) {
@@ -340,34 +403,48 @@ class Printer {
       }
       case "While": {
         const body = this.block(s.block, depth + 1);
-        return `${ind}while ${this.expression(s.condition, depth)} do` +
-          (body ? `\n${body}` : "") + `\n${ind}end`;
+        return (
+          `${ind}while ${this.expression(s.condition, depth)} do` +
+          (body ? `\n${body}` : "") +
+          `\n${ind}end`
+        );
       }
       case "Repeat": {
         const body = this.block(s.block, depth + 1);
-        return `${ind}repeat` + (body ? `\n${body}` : "") +
-          `\n${ind}until ${this.expression(s.condition, depth)}`;
+        return (
+          `${ind}repeat` +
+          (body ? `\n${body}` : "") +
+          `\n${ind}until ${this.expression(s.condition, depth)}`
+        );
       }
       case "For": {
         const step = s.step ? `, ${this.expression(s.step, depth)}` : "";
         const body = this.block(s.block, depth + 1);
-        return `${ind}for ${s.name} = ${this.expression(s.start, depth)}, ${this.expression(s.end, depth)
-          }${step} do${body ? `\n${body}` : ""}\n${ind}end`;
+        return `${ind}for ${s.name} = ${this.expression(s.start, depth)}, ${this.expression(
+          s.end,
+          depth,
+        )}${step} do${body ? `\n${body}` : ""}\n${ind}end`;
       }
       case "ForIn": {
         const body = this.block(s.block, depth + 1);
-        return `${ind}for ${s.names.join(", ")} in ${s.expressions.map((e) => this.expression(e, depth)).join(", ")
-          } do${body ? `\n${body}` : ""}\n${ind}end`;
+        return `${ind}for ${s.names.join(", ")} in ${s.expressions
+          .map((e) => this.expression(e, depth))
+          .join(", ")} do${body ? `\n${body}` : ""}\n${ind}end`;
       }
       case "Function": {
-        const name = s.name.propNames.join(".") +
+        const name =
+          s.name.propNames.join(".") +
           (s.name.colonName ? `:${s.name.colonName}` : "");
-        return `${ind}function ${name}` +
-          this.functionRest(s.body.parameters, s.body.block, depth);
+        return (
+          `${ind}function ${name}` +
+          this.functionRest(s.body.parameters, s.body.block, depth)
+        );
       }
       case "LocalFunction":
-        return `${ind}local function ${s.name}` +
-          this.functionRest(s.body.parameters, s.body.block, depth);
+        return (
+          `${ind}local function ${s.name}` +
+          this.functionRest(s.body.parameters, s.body.block, depth)
+        );
       default:
         throw new Error(
           `pretty_print: unsupported statement type: ${(s as any).type}`,
@@ -383,9 +460,6 @@ export function prettyPrintExpression(
   return new Printer(resolveOptions(opts)).expression(expr, 0);
 }
 
-export function prettyPrintBlock(
-  block: LuaBlock,
-  opts?: PrintOptions,
-): string {
+export function prettyPrintBlock(block: LuaBlock, opts?: PrintOptions): string {
   return new Printer(resolveOptions(opts)).block(block, 0);
 }

package/client/space_lua/query_collection.ts

@@ -193,7 +193,7 @@ export interface LuaQueryCollection {
  * Implements a query collection for a regular JavaScript array
  */
 export class ArrayQueryCollection<T> implements LuaQueryCollection {
-  constructor(private readonly array: T[]) { }
+  constructor(private readonly array: T[]) {}
   query(
     query: LuaCollectionQuery,
     env: LuaEnv,
@@ -842,7 +842,7 @@ export async function applyQuery(
 
   const mkEnv = grouped
     ? (ov: string | undefined, item: any, e: LuaEnv, s: LuaStackFrame) =>
-      buildGroupItemEnv(ov, groupByNames, item, e, s)
+        buildGroupItemEnv(ov, groupByNames, item, e, s)
     : buildItemEnvLocal;
 
   let selectResults: any[] | undefined;
@@ -1002,7 +1002,7 @@ export async function queryLua<T = any>(
   for await (let { key, value } of kv.query({ prefix })) {
     if (enricher) {
       value = enricher(key, value);
-      // Enrichers may return undefined to filter a row out 
+      // Enrichers may return undefined to filter a row out
       if (value === undefined) continue;
     }
     results.push(value);
@@ -1056,7 +1056,7 @@ export class DataStoreQueryCollection implements LuaQueryCollection {
   constructor(
     private readonly dataStore: DataStore,
     readonly prefix: string[],
-  ) { }
+  ) {}
   query(
     query: LuaCollectionQuery,
     env: LuaEnv,

package/client/space_lua/render_widget.ts

@@ -0,0 +1,156 @@
+import type { ASTCtx } from "./ast.ts";
+import { evalExpression } from "./eval.ts";
+import { parseExpressionString } from "./parse.ts";
+import {
+  type ILuaFunction,
+  LuaEnv,
+  LuaRuntimeError,
+  LuaStackFrame,
+  LuaTable,
+  type LuaValue,
+  luaValueToJS,
+  singleResult,
+} from "./runtime.ts";
+import { isTaggedFloat } from "./numeric.ts";
+import {
+  encodeRef,
+  getNameFromPath,
+} from "@silverbulletmd/silverbullet/lib/ref";
+import { resolveASTReference } from "../space_lua.ts";
+import type { Client } from "../client.ts";
+import {
+  classifyResult,
+  renderResultToCleanMarkdown,
+} from "./render_lua_markdown.ts";
+
+/**
+ * Run a Space Lua computation and convert its result into something the
+ * LuaWidget renderer understands (a widget table, markdown string, or number).
+ * Shared by the `${...}` directive and Lua code widgets so the conversion +
+ * error formatting live in one place.
+ */
+export async function renderLuaWidgetResult(
+  client: Client,
+  compute: (env: LuaEnv, sf: LuaStackFrame) => Promise<LuaValue> | LuaValue,
+  ctx: ASTCtx,
+  currentPageMeta?: { name: string } | undefined,
+): Promise<any> {
+  try {
+    const tl = new LuaEnv();
+    tl.setLocal(
+      "currentPage",
+      currentPageMeta ||
+        (client.ui.viewState.current
+          ? { name: getNameFromPath(client.ui.viewState.current.path) }
+          : undefined),
+    );
+    const sf = LuaStackFrame.createWithGlobalEnv(
+      client.clientSystem.spaceLuaEnv.env,
+      ctx,
+    );
+    const env = new LuaEnv(client.clientSystem.spaceLuaEnv.env);
+    env.setLocal("_CTX", tl);
+    const rawResult = singleResult(await compute(env, sf));
+    if (isTaggedFloat(rawResult) || typeof rawResult === "number") {
+      return rawResult;
+    }
+    if (rawResult instanceof LuaTable) {
+      if (rawResult.rawGet("_isWidget")) {
+        return luaValueToJS(rawResult, sf);
+      }
+      return rawResult;
+    }
+    return luaValueToJS(rawResult, sf);
+  } catch (e: any) {
+    if (e instanceof LuaRuntimeError && e.sf?.astCtx) {
+      const source = resolveASTReference(e.sf.astCtx);
+      if (source) {
+        return `**Lua error:** ${e.message} (Origin: [[${encodeRef(source)}]])`;
+      }
+    }
+    return `**Lua error:** ${e.message}`;
+  }
+}
+
+/** Evaluate a `${...}`-style expression string and render it as a widget. */
+export async function renderLuaExpression(
+  client: Client,
+  expressionText: string,
+  currentPageMeta?: { name: string } | undefined,
+): Promise<any> {
+  if (expressionText.trim().length === 0) {
+    return "**Error:** Empty Lua expression";
+  }
+  const expr = parseExpressionString(expressionText);
+  return renderLuaWidgetResult(
+    client,
+    (env, sf) => evalExpression(expr, env, sf),
+    expr.ctx,
+    currentPageMeta,
+  );
+}
+
+/** Call a stored Lua render function (e.g. a code widget) and render it. */
+export async function renderLuaCallback(
+  client: Client,
+  fn: ILuaFunction,
+  args: LuaValue[],
+  currentPageMeta?: { name: string } | undefined,
+): Promise<any> {
+  return renderLuaWidgetResult(
+    client,
+    (_env, sf) => fn.call(sf, ...args),
+    {} as ASTCtx,
+    currentPageMeta,
+  );
+}
+
+export type PortableMarkdownResult =
+  | { ok: true; markdown: string }
+  | { ok: false; reason: string };
+
+/**
+ * Evaluate a `${...}`-style expression and produce portable GFM markdown — the
+ * same clean rendering the Copy button uses — or report why it can't be baked.
+ * - nil/empty → ok with empty markdown
+ * - Lua error → not ok (the eval error string)
+ * - widget object: portable only if it exposes a `markdown` rendering;
+ *   html-only widgets are not bakeable
+ * - scalars / tables / arrays / strings → clean GFM
+ */
+export async function expressionToPortableMarkdown(
+  client: Client,
+  expressionText: string,
+  currentPageMeta?: { name: string } | undefined,
+): Promise<PortableMarkdownResult> {
+  const rawResult = await renderLuaExpression(
+    client,
+    expressionText,
+    currentPageMeta,
+  );
+  if (rawResult === null || rawResult === undefined) {
+    return { ok: true, markdown: "" };
+  }
+  // renderLuaExpression returns eval failures as markdown error strings.
+  if (
+    typeof rawResult === "string" &&
+    (rawResult.startsWith("**Lua error:**") ||
+      rawResult.startsWith("**Error:**"))
+  ) {
+    return { ok: false, reason: rawResult };
+  }
+  // Widget objects: portable only when they expose a `markdown` rendering.
+  if (typeof rawResult === "object" && (rawResult as any)._isWidget) {
+    const md = (rawResult as any).markdown;
+    if (typeof md === "string") {
+      return { ok: true, markdown: md.trim() };
+    }
+    return { ok: false, reason: "html-only widget (no markdown rendering)" };
+  }
+  // Scalars, tables, arrays, plain strings → clean GFM markdown.
+  const markdown = await renderResultToCleanMarkdown(
+    rawResult,
+    classifyResult(rawResult),
+  );
+  return { ok: true, markdown };
+}

package/client/space_lua/runtime.ts

@@ -5,6 +5,10 @@ import { isPromise, rpAll } from "./rp.ts";
 import { isNegativeZero, isTaggedFloat } from "./numeric.ts";
 import { isSqlNull } from "./sliq_null.ts";
 import { luaFormat } from "./stdlib/format.ts";
+import type {
+  LuaFunctionDocumentation,
+  LuaFunctionInfo,
+} from "../../plug-api/types/index.ts";
 
 export type LuaType =
   | "nil"
@@ -20,10 +24,19 @@ export type LuaType =
 export type LuaValue = any;
 export type JSValue = any;
 
+type LuaFunctionDefinitionMetadata = LuaFunctionDocumentation &
+  Partial<Pick<LuaFunctionInfo, "kind" | "name" | "source">>;
+
+export type LuaFunctionDefinition<Callback> = {
+  callback: Callback;
+} & LuaFunctionDefinitionMetadata;
+
 export interface ILuaFunction {
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue;
 
   asString(): string;
+
+  info?: LuaFunctionInfo;
 }
 
 export interface ILuaSettable {
@@ -453,12 +466,25 @@ export function singleResult(value: any): any {
 export class LuaFunction implements ILuaFunction {
   private capturedEnv: LuaEnv;
   funcHasGotos?: boolean;
+  info: LuaFunctionInfo;
 
   constructor(
     readonly body: LuaFunctionBody,
     closure: LuaEnv,
+    info: Partial<LuaFunctionInfo> = {},
   ) {
     this.capturedEnv = closure;
+    const documentation = body.documentation ?? {};
+    this.info = {
+      kind: "lua",
+      source: { ...body.ctx },
+      ...documentation,
+      ...info,
+      parameters:
+        info.parameters ??
+        documentation.parameters ??
+        body.parameters.map((name) => ({ name })),
+    };
   }
 
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue {
@@ -482,10 +508,7 @@ export class LuaFunction implements ILuaFunction {
         for (let i = 0; i < varargStart; i++) {
           env.setLocal(params[i], resolvedArgs[i] ?? null);
         }
-        env.setLocal(
-          "...",
-          new LuaMultiRes(resolvedArgs.slice(varargStart)),
-        );
+        env.setLocal("...", new LuaMultiRes(resolvedArgs.slice(varargStart)));
       } else {
         // Non-variadic: bind all named params directly
         for (let i = 0; i < params.length; i++) {
@@ -565,7 +588,26 @@ function mapFunctionReturnValue(values: any[]): any {
 }
 
 export class LuaNativeJSFunction implements ILuaFunction {
-  constructor(readonly fn: (...args: JSValue[]) => JSValue) {}
+  readonly fn: (...args: JSValue[]) => JSValue;
+  public info: LuaFunctionInfo;
+
+  constructor(
+    definition:
+      | ((...args: JSValue[]) => JSValue)
+      | LuaFunctionDefinition<(...args: JSValue[]) => JSValue>,
+  ) {
+    if (typeof definition === "function") {
+      this.fn = definition;
+      this.info = { kind: "builtin" };
+    } else {
+      const { callback, ...info } = definition;
+      this.fn = callback;
+      this.info = {
+        kind: "builtin",
+        ...info,
+      };
+    }
+  }
 
   // Performs automatic conversion between Lua and JS values for arguments, but not for return values
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue {
@@ -595,9 +637,28 @@ export class LuaNativeJSFunction implements ILuaFunction {
 }
 
 export class LuaBuiltinFunction implements ILuaFunction {
+  readonly fn: (sf: LuaStackFrame, ...args: LuaValue[]) => LuaValue;
+  public info: LuaFunctionInfo;
+
   constructor(
-    readonly fn: (sf: LuaStackFrame, ...args: LuaValue[]) => LuaValue,
-  ) {}
+    definition:
+      | ((sf: LuaStackFrame, ...args: LuaValue[]) => LuaValue)
+      | LuaFunctionDefinition<
+          (sf: LuaStackFrame, ...args: LuaValue[]) => LuaValue
+        >,
+  ) {
+    if (typeof definition === "function") {
+      this.fn = definition;
+      this.info = { kind: "builtin" };
+    } else {
+      const { callback, ...info } = definition;
+      this.fn = callback;
+      this.info = {
+        kind: "builtin",
+        ...info,
+      };
+    }
+  }
 
   call(sf: LuaStackFrame, ...args: LuaValue[]): Promise<LuaValue> | LuaValue {
     // _CTX is already available via the stack frame
@@ -1313,11 +1374,9 @@ export function luaSet(
     const k = toNumKey(normKey);
     const jsVal = luaValueToJS(value, sf);
     if (isPromise(jsVal)) {
-      return (jsVal as Promise<any>).then(
-        (v) => {
-          (obj as Record<string | number, any>)[k] = v;
-        },
-      );
+      return (jsVal as Promise<any>).then((v) => {
+        (obj as Record<string | number, any>)[k] = v;
+      });
     }
     (obj as Record<string | number, any>)[k] = jsVal;
   }
@@ -1492,16 +1551,18 @@ export function luaCall(
 
 export function luaEquals(a: any, b: any): boolean {
   // Normalize nil variants (null, undefined, SQL NULL) to null
-  const an = (a === null || a === undefined || isSqlNull(a))
-    ? null
-    : isTaggedFloat(a)
-    ? a.value
-    : a;
-  const bn = (b === null || b === undefined || isSqlNull(b))
-    ? null
-    : isTaggedFloat(b)
-    ? b.value
-    : b;
+  const an =
+    a === null || a === undefined || isSqlNull(a)
+      ? null
+      : isTaggedFloat(a)
+        ? a.value
+        : a;
+  const bn =
+    b === null || b === undefined || isSqlNull(b)
+      ? null
+      : isTaggedFloat(b)
+        ? b.value
+        : b;
   return an === bn;
 }
 

package/client/space_lua/stdlib/crypto.ts

@@ -2,9 +2,14 @@ import { LuaBuiltinFunction, LuaTable } from "../runtime.ts";
 import { hashSHA256 } from "../../../plug-api/lib/crypto.ts";
 
 export const cryptoApi = new LuaTable({
-  sha256: new LuaBuiltinFunction(
-    (_sf, s: string | Uint8Array): Promise<string> => {
+  sha256: new LuaBuiltinFunction({
+    callback: (_sf, s: string | Uint8Array): Promise<string> => {
       return hashSHA256(s);
     },
-  ),
+    description: "Computes the SHA-256 digest of a string or byte buffer.",
+    parameters: [
+      { name: "data", type: "string|bytes", description: "Data to hash." },
+    ],
+    returns: [{ type: "string", description: "Hexadecimal SHA-256 digest." }],
+  }),
 });