@silverbulletmd/silverbullet 2.9.0 → 2.10.0

package/client/space_lua/syscalls.ts

@@ -0,0 +1,270 @@
+import type { ASTCtx, LuaBlock, LuaExpression } from "./ast.ts";
+import { evalExpression } from "./eval.ts";
+import { parseBlock, parseExpressionString } from "./parse.ts";
+import {
+  type PrintOptions,
+  prettyPrintBlock,
+  prettyPrintExpression,
+} from "./pretty_print.ts";
+import {
+  isILuaFunction,
+  LuaEnv,
+  LuaStackFrame,
+  LuaTable,
+  luaGet,
+  luaKeys,
+  luaToString,
+  luaTypeOf,
+  luaValueToJS,
+} from "./runtime.ts";
+import { buildThreadLocalEnv } from "../space_lua_api.ts";
+import type { SysCallMapping, System } from "../plugos/system.ts";
+import { isSendable } from "../plugos/util.ts";
+import type {
+  LuaFunctionInfo,
+  LuaPropertyInspection,
+  LuaValueInspection,
+} from "../../plug-api/types/index.ts";
+import { encodeRef } from "../../plug-api/lib/ref.ts";
+import { resolveASTReference } from "../space_lua.ts";
+
+async function inspectValue(
+  value: unknown,
+  path: string[],
+): Promise<Omit<LuaValueInspection, "properties">> {
+  const type = value instanceof LuaEnv ? "table" : await luaTypeOf(value);
+  if (!isILuaFunction(value)) {
+    return { type };
+  }
+  const functionInfo: LuaFunctionInfo = {
+    ...(value.info ?? { kind: "builtin" }),
+    name: value.info?.name ?? path.join("."),
+  };
+  const definitionRef =
+    functionInfo.kind === "lua" && functionInfo.source
+      ? resolveASTReference(functionInfo.source as ASTCtx)
+      : null;
+  return {
+    type,
+    functionInfo,
+    definition: definitionRef ? encodeRef(definitionRef) : undefined,
+  };
+}
+
+async function inspectLuaPath(
+  env: LuaEnv,
+  path: string[],
+): Promise<LuaValueInspection | null> {
+  const sf = LuaStackFrame.createWithGlobalEnv(env);
+  let value: unknown = env;
+  for (const key of path) {
+    value = await luaGet(value, key, null, sf);
+    if (value === null || value === undefined) {
+      return null;
+    }
+  }
+
+  const properties: LuaPropertyInspection[] = [];
+  const keys =
+    value instanceof LuaEnv
+      ? value.keys()
+      : value instanceof LuaTable ||
+          Array.isArray(value) ||
+          (typeof value === "object" && value !== null)
+        ? luaKeys(value)
+        : [];
+  for (const key of [...new Set(keys)]
+    .filter((candidate): candidate is string => typeof candidate === "string")
+    .sort()) {
+    const child = await luaGet(value, key, null, sf);
+    if (child === null || child === undefined) continue;
+    properties.push({
+      key,
+      ...(await inspectValue(child, [...path, key])),
+    });
+  }
+
+  return {
+    ...(await inspectValue(value, path)),
+    properties,
+  };
+}
+
+export function luaSyscalls(
+  system: System<any>,
+  getEnvironment: () => LuaEnv,
+): SysCallMapping {
+  return {
+    "lua.parseBlock": {
+      callback: (_ctx, code: string): LuaBlock => parseBlock(code),
+      description:
+        "Parses a Space Lua chunk and returns its AST. Blocks retain comments in source order with their exact text, kind, and source range.",
+      parameters: [
+        { name: "code", type: "string", description: "Lua code to parse." },
+      ],
+      returns: [{ type: "table", description: "Parsed Lua block AST." }],
+      examples: [
+        {
+          code: 'local ast = lua.parseBlock("print(\\"Hello\\")")',
+        },
+      ],
+      see: "API/lua",
+    },
+    // Deprecated alias for `lua.parseBlock`, kept for backwards compatibility.
+    "lua.parse": {
+      callback: (_ctx, code: string): LuaBlock => parseBlock(code),
+      description: "Deprecated alias for lua.parseBlock.",
+      parameters: [
+        { name: "code", type: "string", description: "Lua code to parse." },
+      ],
+      returns: [{ type: "table", description: "Parsed Lua block AST." }],
+      deprecated: "Use lua.parseBlock instead.",
+      see: "API/lua",
+    },
+    "lua.parseExpression": {
+      callback: (_ctx, expression: string): LuaExpression =>
+        parseExpressionString(expression),
+      description: "Parses a Space Lua expression and returns its AST.",
+      parameters: [
+        {
+          name: "expression",
+          type: "string",
+          description: "Lua expression to parse.",
+        },
+      ],
+      returns: [{ type: "table", description: "Parsed expression AST." }],
+      examples: [
+        {
+          code: 'local expression = lua.parseExpression("1 + 2 * 3")',
+        },
+      ],
+      see: "API/lua",
+    },
+    "lua.prettyPrintBlock": {
+      callback: (_ctx, block: LuaBlock, opts?: PrintOptions): string =>
+        prettyPrintBlock(block, opts),
+      description:
+        "Pretty-prints a parsed Space Lua block. Comments are preserved while their placement and indentation are normalized.",
+      parameters: [
+        { name: "block", type: "table", description: "Parsed block AST." },
+        {
+          name: "options",
+          type: "table",
+          description:
+            "Formatting options: `indentWidth`, `quote`, and `trailingComma`.",
+          optional: true,
+        },
+      ],
+      returns: [{ type: "string", description: "Formatted Lua source." }],
+      examples: [
+        {
+          code: 'local formatted = lua.prettyPrintBlock(lua.parseBlock("if a then return 1 end"))',
+        },
+      ],
+      see: "API/lua",
+    },
+    "lua.prettyPrintExpression": {
+      callback: (
+        _ctx,
+        expression: LuaExpression,
+        opts?: PrintOptions,
+      ): string => prettyPrintExpression(expression, opts),
+      description: "Pretty-prints a parsed Space Lua expression.",
+      parameters: [
+        {
+          name: "expression",
+          type: "table",
+          description: "Parsed expression AST.",
+        },
+        {
+          name: "options",
+          type: "table",
+          description:
+            "Formatting options: `indentWidth`, `quote`, and `trailingComma`.",
+          optional: true,
+        },
+      ],
+      returns: [{ type: "string", description: "Formatted Lua source." }],
+      examples: [
+        {
+          code: 'local formatted = lua.prettyPrintExpression(lua.parseExpression("{a=1,b=2}"))',
+        },
+      ],
+      see: "API/lua",
+    },
+    /**
+     * Evaluates a Lua expression and returns the result as a JavaScript value
+     * @param _ctx
+     * @param expression
+     * @returns
+     */
+    "lua.evalExpression": {
+      callback: async (_ctx, expression: string) => {
+        try {
+          const ast = parseExpressionString(expression);
+          const globalEnv = getEnvironment();
+          const env = await buildThreadLocalEnv(system, globalEnv);
+          const sf = new LuaStackFrame(env, null);
+          const luaResult = await evalExpression(ast, globalEnv, sf);
+          const jsResult = luaValueToJS(luaResult, sf);
+          if (isSendable(jsResult)) {
+            return jsResult;
+          } else {
+            // This may evaluate to e.g. a function, which is not sendable, in this case we'll console.warn and return a stringified version of the result
+            console.warn(
+              "Lua eval result is not sendable, returning stringified version",
+              jsResult,
+            );
+            return luaToString(luaResult);
+          }
+        } catch (e: any) {
+          console.error("Lua eval error: ", e.message, e.sf?.astCtx);
+          throw e;
+        }
+      },
+      description: "Evaluates a Space Lua expression.",
+      parameters: [
+        {
+          name: "expression",
+          type: "string",
+          description: "Lua expression to evaluate.",
+        },
+      ],
+      returns: [{ description: "Evaluated result." }],
+      examples: [
+        {
+          code: 'local result = lua.evalExpression("1 + 2 * 3")\nprint(result)',
+        },
+      ],
+      see: "API/lua",
+    },
+    "lua.inspect": {
+      callback: (_ctx, path: string[] = []) =>
+        inspectLuaPath(getEnvironment(), path),
+      description:
+        "Inspects a value in the live Space Lua environment and returns serializable type, function, definition, and property metadata.",
+      parameters: [
+        {
+          name: "path",
+          type: "table",
+          description:
+            "Sequence of property names from the global environment; omit to inspect globals.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "table|nil",
+          description:
+            "Inspection metadata, or nil when the requested path does not exist.",
+        },
+      ],
+      examples: [
+        {
+          code: 'local info = lua.inspect({"editor", "getText"})',
+        },
+      ],
+      see: "API/lua",
+    },
+  };
+}

package/dist/plug-compile.js

@@ -4,7 +4,7 @@
 import { Command } from "commander";
 
 // version.ts
-var version = "2.9.0";
+var version = "2.10.0";
 
 // client/plugos/plug_compile.ts
 import * as path from "node:path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silverbulletmd/silverbullet",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "type": "module",
   "description": "A self-hosted, web-based note taking app",
   "publishConfig": {
@@ -63,8 +63,8 @@
     "fmt:check": "biome format .",
     "bench": "vitest bench",
     "index-stats": "tsx plugs/index/index_stats.ts",
-    "test:e2e": "npx playwright test",
-    "test:e2e:headed": "npx playwright test --headed"
+    "test:e2e": "npx playwright test --project=chromium",
+    "test:e2e:headed": "npx playwright test --project=chromium --headed"
   },
   "peerDependencies": {
     "preact": "^10.25.0"

package/plug-api/lib/ref.ts

@@ -140,6 +140,102 @@ export function parseToRef(stringRef: string): Ref | null {
   return ref;
 }
 
+/**
+ * Coerces a ref-or-string (including the legacy `{ page, pos, header }` shape)
+ * into a {@link Ref} and validates its structure, throwing on malformed input.
+ * Used wherever an external caller (e.g. a syscall) hands in a ref that may be a
+ * string or a legacy object.
+ */
+export function coerceAndValidateRef(ref: Ref | string): Ref {
+  if (typeof ref === "string") {
+    const parsedRef = parseToRef(ref);
+    if (!parsedRef) {
+      throw new Error("Unable to parse string as ref");
+    }
+    ref = parsedRef;
+  }
+
+  if (
+    // @ts-expect-error: Legacy support
+    ref.page !== undefined
+  ) {
+    console.warn(
+      "You are using legacy navigation syntax (`{ page, pos, header }`), this will be phased out in the future",
+    );
+
+    const legacyRef = ref as unknown as {
+      kind: "page" | "document";
+      page: string;
+      pos?: number | { line: number; column: number };
+      header?: string;
+      meta?: boolean;
+    };
+
+    legacyRef.kind ??= "page";
+
+    let details: Ref["details"];
+
+    if (typeof legacyRef.pos === "number") {
+      details = { type: "position", pos: legacyRef.pos };
+    } else if (legacyRef.pos) {
+      details = {
+        type: "linecolumn",
+        line: legacyRef.pos.line,
+        column: legacyRef.pos.column,
+      };
+    } else if (legacyRef.header) {
+      details = { type: "header", header: legacyRef.header };
+    }
+
+    ref = {
+      path: (legacyRef.kind === "page"
+        ? `${legacyRef.page}.md`
+        : legacyRef.page) as Path,
+      details,
+      meta: legacyRef.meta,
+    };
+  }
+
+  if (!isValidPath(ref.path) && ref.path !== "") {
+    throw new Error("Path passed in ref is invalid");
+  } else if (typeof ref.meta !== "boolean" && ref.meta !== undefined) {
+    throw new Error("ref.meta has to be of type `boolean`");
+  } else if (ref.details !== undefined && typeof ref.details !== "object") {
+    throw new Error("ref.details has to be of type `object` or `undefined`");
+  } else if (
+    ref.details &&
+    !["position", "linecolumn", "header", "anchor"].includes(ref.details.type)
+  ) {
+    throw new Error(
+      "ref.details.type has to be 'position', 'linecolumn', 'header' or 'anchor'",
+    );
+  }
+
+  if (ref.details?.type === "position" && typeof ref.details.pos !== "number") {
+    throw new Error("ref.details.pos has to be of type `number`");
+  } else if (
+    ref.details?.type === "header" &&
+    typeof ref.details.header !== "string"
+  ) {
+    throw new Error("ref.details.header has to be of type `string`");
+  } else if (
+    ref.details?.type === "linecolumn" &&
+    typeof ref.details.line !== "number" &&
+    typeof ref.details.column !== "number"
+  ) {
+    throw new Error(
+      "ref.details.line and ref.details.column has to be of type `number`",
+    );
+  } else if (
+    ref.details?.type === "anchor" &&
+    typeof ref.details.name !== "string"
+  ) {
+    throw new Error("ref.details.name has to be of type `string`");
+  }
+
+  return ref;
+}
+
 /**
  * The inverse of {@link parseToRef}, encodes a ref object into a reference string.
  * It tries to produce the shortest valid representation

package/plug-api/lib/shortcut.ts

@@ -1,4 +1,5 @@
-export const isMacLike = typeof navigator !== "undefined" &&
+export const isMacLike =
+  typeof navigator !== "undefined" &&
   /(Mac|iPhone|iPod|iPad)/i.test(navigator.platform);
 
 export function prettifyShortcut(shortcut: string): string {

package/plug-api/syscalls/config.ts

@@ -60,9 +60,11 @@ export function define(key: string, schema: any): Promise<void> {
  * ascending `order` (default 0); unknown categories fall to the bottom in
  * alphabetical order.
  */
-export function defineCategory(
-  definition: { name: string; description?: string; order?: number },
-): Promise<void> {
+export function defineCategory(definition: {
+  name: string;
+  description?: string;
+  order?: number;
+}): Promise<void> {
   return syscall("config.defineCategory", definition);
 }
 

package/plug-api/syscalls/editor.ts

@@ -129,6 +129,22 @@ export function navigate(
   return syscall("editor.navigate", ref, replaceState, newWindow);
 }
 
+/**
+ * Opens the specified page reference, restoring the previous cursor and scroll
+ * position for that page when one is remembered from the current session. Like
+ * navigate(), an explicit pointer in the ref (e.g. `#header`, `@123`) still wins.
+ * @param ref the page reference to open
+ * @param replaceState whether to replace the current history state in the browser history
+ * @param newWindow whether to open the page in a new window
+ */
+export function open(
+  ref: Ref | string,
+  replaceState = false,
+  newWindow = false,
+): Promise<void> {
+  return syscall("editor.open", ref, replaceState, newWindow);
+}
+
 /**
  * Opens the page navigator
  * @param mode the mode to open the navigator in

package/plug-api/syscalls/index.ts

@@ -4,7 +4,6 @@ import type {
 } from "../../client/space_lua/query_collection.ts";
 import { syscall } from "@silverbulletmd/silverbullet/syscall";
 import type { ObjectValue } from "../../plug-api/types/index.ts";
-
 /**
  * Exposes the SilverBullet object indexing system
  * @module
@@ -200,3 +199,20 @@ export function resolveAnchor(
 ): Promise<ResolveAnchorResult> {
   return syscall("index.resolveAnchor", name, page);
 }
+
+/**
+ * Returns a map of tag name → raw JSON Schema for every defined object-type /
+ * [[Tag]] that declares a schema. Tags without a schema are omitted.
+ * Use it to discover what attributes a tag's objects carry before querying them.
+ */
+export function describeSchema(): Promise<Record<string, unknown>> {
+  return syscall("index.describeSchema");
+}
+
+/**
+ * Returns the raw JSON Schema for a single tag, or null if the tag is not
+ * defined or has no schema.
+ */
+export function tagSchema(tagName: string): Promise<unknown | null> {
+  return syscall("index.tagSchema", tagName);
+}

package/plug-api/syscalls/jsonschema.ts

@@ -21,3 +21,12 @@ export function validateObject(
 export function validateSchema(schema: any): Promise<string | undefined> {
   return syscall("jsonschema.validateSchema", schema);
 }
+
+/**
+ * Infers a best-effort JSON schema from a sample value's shape.
+ * @param object the sample value to infer a schema from
+ * @returns an inferred JSON schema (draft 2020-12), marked `x-inferred`
+ */
+export function inferFromObject(object: any): Promise<any> {
+  return syscall("jsonschema.inferFromObject", object);
+}

package/plug-api/syscalls/lua.ts

@@ -1,6 +1,7 @@
 import { syscall } from "../syscall.ts";
 import type { LuaBlock, LuaExpression } from "../../client/space_lua/ast.ts";
 import type { PrintOptions } from "../../client/space_lua/pretty_print.ts";
+import type { LuaValueInspection } from "../types/index.ts";
 
 export function parseBlock(code: string): Promise<LuaBlock> {
   return syscall("lua.parseBlock", code);
@@ -32,3 +33,9 @@ export function prettyPrintExpression(
 ): Promise<string> {
   return syscall("lua.prettyPrintExpression", expression, opts);
 }
+
+export function inspect(
+  path: string[] = [],
+): Promise<LuaValueInspection | null> {
+  return syscall("lua.inspect", path);
+}

package/plug-api/syscalls/shell.ts

@@ -14,4 +14,3 @@ export function run(
 ): Promise<{ stdout: string; stderr: string; code: number }> {
   return syscall("shell.run", cmd, args, stdin);
 }
-

package/plug-api/syscalls/system.ts

@@ -51,6 +51,13 @@ export function reloadPlugs(): Promise<void> {
   return syscall("system.reloadPlugs");
 }
 
+/**
+ * Make edited-on-disk state live and wait until the client is ready again.
+ */
+export function reboot(): Promise<void> {
+  return syscall("system.reboot");
+}
+
 /**
  * Load (or reload) a single plug from a space file path.
  */

package/plug-api/system_mock.ts

@@ -12,7 +12,7 @@ import { eventSyscalls } from "../client/plugos/syscalls/event.ts";
 import { indexSyscalls } from "../client/plugos/syscalls/index.ts";
 import { jsonschemaSyscalls } from "../client/plugos/syscalls/jsonschema.ts";
 import { languageSyscalls } from "../client/plugos/syscalls/language.ts";
-import { luaSyscalls } from "../client/plugos/syscalls/lua.ts";
+import { luaSyscalls } from "../client/space_lua/syscalls.ts";
 import { markdownSyscalls } from "../client/plugos/syscalls/markdown.ts";
 import { mqSyscalls } from "../client/plugos/syscalls/mq.ts";
 import {
@@ -64,7 +64,7 @@ export function createMockSystem() {
     languageSyscalls(),
     jsonschemaSyscalls(),
     indexSyscalls(objectIndex, clientMock),
-    luaSyscalls(clientSystemMock),
+    luaSyscalls(system, () => clientSystemMock.spaceLuaEnv.env),
     mqSyscalls(mq),
     dataStoreReadSyscalls(ds, clientSystemMock),
     dataStoreWriteSyscalls(ds),

package/plug-api/types/index.ts

@@ -36,11 +36,62 @@ export type DocumentMeta = ObjectValue<
     extension: string;
   } & Record<string, any>
 >;
-export type SyscallMeta = {
+export type SyscallMeta = LuaFunctionDocumentation & {
   name: string;
   requiredPermissions: string[];
   argCount: number;
 };
+
+export type LuaFunctionParameterDocumentation = {
+  name: string;
+  type?: string;
+  description?: string;
+  optional?: boolean;
+};
+
+export type LuaFunctionReturnDocumentation = {
+  type?: string;
+  description?: string;
+};
+
+export type LuaFunctionExampleDocumentation = {
+  code: string;
+  description?: string;
+  language?: string;
+};
+
+/** Structured documentation shared by Lua functions, built-ins and syscalls. */
+export type LuaFunctionDocumentation = {
+  description?: string;
+  parameters?: LuaFunctionParameterDocumentation[];
+  returns?: LuaFunctionReturnDocumentation[];
+  /** Full signatures, used for overloaded or otherwise non-standard functions. */
+  signatures?: string[];
+  examples?: LuaFunctionExampleDocumentation[];
+  deprecated?: string | boolean;
+  /** Page or page anchor containing the full documentation. */
+  see?: string;
+};
+
+export type LuaFunctionInfo = LuaFunctionDocumentation & {
+  name?: string;
+  kind: "lua" | "builtin" | "syscall";
+  source?: Record<string, unknown>;
+};
+
+export type LuaPropertyInspection = {
+  key: string;
+  type: string;
+  functionInfo?: LuaFunctionInfo;
+  definition?: string;
+};
+
+export type LuaValueInspection = {
+  type: string;
+  functionInfo?: LuaFunctionInfo;
+  definition?: string;
+  properties: LuaPropertyInspection[];
+};
 /**
  * An ObjectValue that can be indexed by the `index` plug, needs to have a minimum of
  * of two fields:

package/plug-api/types/manifest.ts

@@ -1,5 +1,6 @@
 import type { Manifest as PlugosManifest } from "../../client/plugos/types.ts";
 import type { NamespaceOperation } from "./namespace.ts";
+import type { LuaFunctionDocumentation } from "./index.ts";
 
 export type CodeWidgetT = {
   codeWidget?: string;
@@ -12,10 +13,23 @@ export type CodeWidgetT = {
  * Quit, About, etc.) instead of a command-dispatching item.
  */
 export type PredefinedMenuKind =
-  | "quit" | "about" | "services" | "hide" | "hideOthers" | "showAll"
-  | "closeWindow" | "minimize" | "maximize" | "fullscreen"
+  | "quit"
+  | "about"
+  | "services"
+  | "hide"
+  | "hideOthers"
+  | "showAll"
+  | "closeWindow"
+  | "minimize"
+  | "maximize"
+  | "fullscreen"
   | "separator"
-  | "undo" | "redo" | "cut" | "copy" | "paste" | "selectAll";
+  | "undo"
+  | "redo"
+  | "cut"
+  | "copy"
+  | "paste"
+  | "selectAll";
 
 /**
  * A single native-menu placement for a command or submenu.
@@ -130,7 +144,11 @@ export type SlashCommandHookT = {
 };
 
 export type SyscallHookT = {
-  syscall?: string;
+  syscall?:
+    | string
+    | ({
+        name: string;
+      } & LuaFunctionDocumentation);
 };
 
 export type DocumentEditorT = {

package/plug-api/ui/cx.ts

@@ -1,6 +1,4 @@
 /** Join class-name parts, dropping falsy values. */
-export function cx(
-  ...parts: Array<string | false | null | undefined>
-): string {
+export function cx(...parts: Array<string | false | null | undefined>): string {
   return parts.filter(Boolean).join(" ");
 }

package/plug-api/ui/index.ts

@@ -14,6 +14,9 @@ export { Badge } from "./badge.tsx";
 export type { BadgeProps } from "./badge.tsx";
 export { Progress } from "./progress.tsx";
 export type { ProgressProps } from "./progress.tsx";
+export { UrlPrefixInput } from "./url_prefix_input.tsx";
+export type { UrlPrefixInputProps } from "./url_prefix_input.tsx";
+export { normalizePrefix, prefixFromName, slugify } from "./slugify.ts";
 export { cx } from "./cx.ts";
 export { panelStyles } from "./panel_styles.ts";
 export type { PanelStylesOptions } from "./panel_styles.ts";